★ FEATURED ARTICLE 后端前端协同办公即时通讯企业应用CRMAI Agent人工智能【免费下载链接】macroMacro is a unified workspace for teams: email, chat, docs, tasks, agents, calls, and CRM — -linked together with shared AI memory.项目地址https://gitcode.com/GitHub_Trending/macro3/macro点击查看免费下载crates/、services/和tooling/是 Macro 仓库 Rust 代码的主要所在地。本文以仓库内提示词文件.pi/prompts/rust_clean.md描述的四步清理流程为主线逐条拆解just prepare_db、just clippy、just check、just format背后的真实实现、执行顺序约束与失败处理策略并结合源码给出可复现的排错路径。一、原始流程一条严格串行的清理指令.pi/prompts/rust_clean.md的内容非常克制它只定义了三件事作用范围、命令顺序、失败处理。You will clean up the Rust code in crates/, services/, and tooling/. From the repository root, run the following commands in order: 1. just prepare_db 2. just clippy 3. just check 4. just format Note: If any of the above tests fail make sure to always run just format after any code is updated If any command fails surface that failure to the user and do not continue running commands.这四行命令并非随便排列而是由三个隐含约束决定的SQLx 离线缓存必须先刷新。仓库的 Rust 检查全部以SQLX_OFFLINEtrue运行若缓存与查询文本不一致后续命令会在编译期宏展开处报错而不是在 lint 阶段报错。静态检查先于格式化。lint 失败会驱动你改代码改完代码又要重新跑一遍前缀命令因此格式化放在最后可以避免反复格式化。失败即停不许静默降级。提示词明确要求向用户暴露失败而不是换一条“更宽松”的命令绕过。下面逐项展开。二、第 1 步just prepare_db—— 刷新 SQLx 离线查询缓存prepare_db定义在 tooling/just/rust.just并委托给 SQLx 的具体实现# This can be used in any crate that uses macrodb under the hood [no-cd] prepare_db: just sqlx::prepare_db {{ DATABASE_URL }}这代表真正的执行体在 tooling/just/sqlx.just[no-cd] prepare_db $DATABASE_URL *FLAGS: cargo sqlx prepare --workspace -- {{ FLAGS }} --workspace --exclude sync_service --all-features从这里可以读出三个关键设计--workspace --all-features缓存覆盖整个 workspace 的功能组合。Macro 大量使用 Cargo feature 来切换 inbound/outbound 适配器例如crates/soup/Cargo.toml中的ports、outbound、axum等 feature只在默认 feature 下生成缓存会产生大量“缺缓存条目”的假性错误。--exclude sync_serviceservices/sync-service是编译到 wasm 的 Cloudflare Worker见 services/sync-service/AGENTS.md其依赖闭包与传统服务不同因此从 workspace 级离线缓存中排除。与之对应clippy与rust-check都对sync_service单独跑一遍。***** **DATABASE_URL来源**默认值定义在 [tooling/just/database.just](https://link.gitcode.com/i/958f49c3abbaff3e20601f2e2c9e3c58)即postgres://user:passwordlocalhost:5432/macrodb。为什么这一步必须最先执行cargo sqlx prepare会连接真实数据库、解析 SQL 并写出.sqlx/query-*.json缓存。当前仓库的.sqlx/目录下有 3000 多个缓存文件全部纳入版本控制。只要改动涉及sqlx::query!/query_as!/query_scalar!等编译期宏缓存就与代码脱节SQLX_OFFLINEtrue的后续编译会直接失败。这一步与 .pi/agents/db-checker.md 的职责边界一致DB reviewer 子代理被明确限制“唯一允许改文件的命令就是just prepare_db”且仅在 SQLx 查询发生变化时触发。同一规则也写在 .pi/skills/sqlx-query-validator/SKILL.md 中——如果本次清理没有触碰任何查询这一步可以被跳过一旦触碰就必须执行并把生成的.sqlx变更加入提交。前置条件本地 Postgres 必须已启动并完成迁移。可按 docs/development/database.md 执行just run_dbs -d、just setup_test_envs、just setup_macrodb。三、第 2 步just clippy—— 以警告为错误的 workspace lintclippy是整条流水线里最重的一步定义为四条串行命令tooling/just/rust.justclippy: RUSTFLAGS-Dwarnings -Dclippy::disallowed_methods RUSTDOCFLAGS-Dwarnings CARGO_TERM_COLORalways SQLX_OFFLINEtrue cargo clippy --workspace --all-features --exclude sync_service RUSTFLAGS-Dwarnings -Dclippy::disallowed_methods RUSTDOCFLAGS-Dwarnings CARGO_TERM_COLORalways SQLX_OFFLINEtrue cargo clippy -p sync_service -- -A clippy::unnecessary_map_or -A clippy::collapsible_if RUSTFLAGS-Dwarnings -Dclippy::disallowed_methods RUSTDOCFLAGS-Dwarnings CARGO_TERM_COLORalways SQLX_OFFLINEtrue cargo clippy -p soup --no-default-features RUSTFLAGS-Dwarnings -Dclippy::disallowed_methods RUSTDOCFLAGS-Dwarnings CARGO_TERM_COLORalways SQLX_OFFLINEtrue cargo clippy -p soup --no-default-features --features ports理解这条 recipe 需要注意四个细节。1.-Dwarnings警告即失败所有四条命令都设置RUSTFLAGS-Dwarnings并额外设置RUSTDOCFLAGS-Dwarnings。这意味着文档注释中的失效链接、无效 HTML 也会让 lint 失败清理时不能只关注cargo输出的warning:行还要看rustdoc报错。2.-Dclippy::disallowed_methods项目级禁用 API真正让这条命令具备“仓库专属语义”的是 clippy.tomldisallowed-methods [ { path std::env::var, reason use macro_env_var so APP_SECRETS_JSON is honored }, { path sqlx::query, replacement sqlx::query! }, { path sqlx::query_as, replacement sqlx::query_as! }, { path sqlx::query_scalar, replacement sqlx::query_scalar! }, ]由此可以确认两条硬性约定读取环境变量不能用std::env::var必须走macro_env_var否则APP_SECRETS_JSON机制会被绕过查询不能直接调用sqlx::query/query_as/query_scalar函数必须使用对应宏。第二条与 .pi/skills/sqlx-query-validator/SKILL.md 的检查清单完全对应只有“SQL 必须动态拼装、无法用宏表达”时才允许直接调用函数且动态片段必须来自受信任白名单取值必须用.bind(...)绑定。清理代码时若为了消除类型推断错误而把宏改成函数调用会在这一步被直接拦下。3.--exclude sync_service与单独补偿sync_service因 wasm 目标被排除在 workspace 级命令之外但并没有被放过第二条命令单独对它执行 clippy并显式放行clippy::unnecessary_map_or与clippy::collapsible_if。这是“排除范围但不排除责任”的写法清理时不要误以为 sync-service 不受约束。4.soup --no-default-features的最小特性矩阵后两条命令针对crates/soup分别验证“无默认特性”和“仅启用ports”两种组合。结合 crates/soup/Cargo.toml 可见soup的outbound、inbound、axum、ai_tools各自拉入不同的域 crate 与可选依赖默认特性全开时很多被条件编译屏蔽的代码根本不会被检查。这两条命令等于强制检查“最精简的下游使用者”视角。四、第 3 步just check—— 只审视你改动的文件just check定义在 tooling/just/check.just与clippy有本质区别它不是全量检查而是变更范围检查。范围计算逻辑如下base${CHECK_BASE:-$(git merge-base HEAD origin/main 2/dev/null || true)} changed$({ [ -n $base ] git diff --name-only $base; \ git diff --name-only HEAD; \ git ls-files --others --exclude-standard; } | sort -u \ | while IFS read -r f; do [ -f $f ] printf %s\n $f; done)即“与origin/main的 merge-base 差异 未提交改动 未跟踪文件”三者并集。文件集为空时直接输出no changed files — nothing to check并以 0 退出。Rust 文件触发的动作若改动集合中包含crates/、services/、tooling/下的.rs文件会执行cargo fmt --check || { echo fix: cargo fmt; fail1; }注意这里只做格式校验不做格式化。这正是原提示词要求“最后统一just format”的原因在未格式化的中间状态下运行just check预期会看到fix: cargo fmt。其他变更会同时被检查just check是一个多语言门禁Rust 只是其中一支。从源码可见它还会变更类型检查动作apps/web、packages等目录的.ts/.tsxBiomeci分别使用 web 与 SDK 各自的配置随后 oxlintapps/web的.ts/.tsxoxlint--type-aware唯一 error 规则为typescript/no-floating-promisesstatic_assets/schema.graphqlcargo x graphql-schema-compat --base base宽范围.rs/.ts/.tsxast-grep 规则扫描规则 id 映射到 docs/development/style-guide.md这意味着即便你的清理只改 Rust只要工作区里还残留未提交的前端改动它们也会一起被检查。若只想聚焦 Rust提交或清理无关改动是更省时的做法。just check full与CHECK_BASEcheck.just的注释给出了两种用法just check秒级覆盖 rustfmt biome oxlint ast-grepjust check full额外加跑tsc与clippy分钟级。此外浅克隆场景下git merge-base可能取不到值此时范围会静默收窄为“仅未提交改动”。源码对此有明确提示并提供了覆盖方式CHECK_BASEorigin/main just check五、第 4 步just format—— 收尾且必须放在最后format: SQLX_OFFLINEtrue cargo fmt只有一行但它是整条流水线唯一“写文件”的步骤。原提示词特别强调任何命令失败并被修复后都要重新运行just format。原因是cargo fmt依据rustfmt规则整文件重排而前面的 lint 修复往往是在局部插入?、调整if let结构格式会因此再次漂移。SQLX_OFFLINEtrue在此处并非必需cargo fmt不编译但与仓库其他 recipe 保持一致避免在format之后误跑了依赖在线数据库的命令而混淆环境。六、把四步串起来顺序为何不能互换顺序命令作用若提前/推后会发生什么1just prepare_db用真实 DB 重建.sqlx缓存放到clippy之后宏展开失败报“query not found in cache”一类错误2just clippy全量 lint警告即错误放到check之后check只查改动文件会漏掉被改动代码影响的兄弟 crate3just check变更范围内的格式/lint/规则放到format之后失去“格式问题会被暴露”的意义4just format统一写入格式放到最前lint 修复会再次破坏格式需要重复执行原提示词的失败语义同样重要任一命令失败就向用户报告并停止。这与 .pi/skills/rust-validation/SKILL.md 的规则一致——“如果rust-check或clippy失败不要继续执行后续命令修复后从序列开头重跑”。七、与仓库其他质量门禁的关系.pi/prompts/rust_clean.md是清理场景的收敛版仓库里还存在两条更完整的序列理解它们的差异可以避免误判“检查已全部通过”。1.rust-validation技能类型检查 hakari.pi/skills/rust-validation/SKILL.md 给出的顺序是just rust-check just clippy just format just hakari其中just rust-check是 workspace 类型检查tooling/just/rust.justjust hakari会运行cargo run -p xtask -- deps重新生成依赖统一元数据tooling/just/rust.just配置见 .config/hakari.toml。后者仅在改动Cargo.toml时才有意义——hakari.toml中维护了大量traversal-excludes用于把 wasm 目标 crate 与 dev-only 的 xtask 排除在workspace-hack之外。清理任务若只改函数体clippy已隐含完成编译但若动过依赖声明或 feature 组合应补跑rust-check与hakari。2.rust.md中的推荐组合docs/development/rust.md 明确了各命令定位命令用途just rust-check使用 SQLx 缓存对 workspace 做类型检查just check快速、变更范围的格式/lint/规则门禁不是类型检查或测试运行器just check full增加 TypeScript 检查与 Rust clippyjust clippy使用 SQLx 缓存跑 workspace lintjust format格式化并特别提醒SQLX_OFFLINEtrue只适用于cargo check、cargo build、cargo clippy不要在会运行测试的会话中导出测试必须连活库且POST前应unset SQLX_OFFLINE。八、常见失败与定位现象根因处理prepare_db连接失败本地 Postgres 未启动或未迁移按 docs/development/database.md 启动并迁移后重跑宏展开报“缓存中找不到查询”改了查询但未刷新缓存重跑just prepare_db并提交.sqlx变更clippy 报use of a disallowed method使用了std::env::var或直接调用sqlx::query*改用macro_env_var/ 宏版本clippy 在sync_service报 wasm 相关错误该 crate 目标是 wasm32确认未在非 wasm 目标下误改其依赖just check输出fix: cargo fmt改动的 Rust 文件尚未格式化继续执行第 4 步just format再重跑just checkjust check报“no merge-base”浅克隆或缺origin/main设置CHECK_BASEref扩大范围ast-grep 命中规则 id违反 docs/development/style-guide.md 中的机械规则按规则说明改代码不要改规则关于最后一条需要额外说明just check只把severity: error的 ast-grep 规则视为失败warning/hint 仅打印。清理时可以优先处理 error 级规则但不应为了“输出干净”去修改rules/ast-grep/下的 YAML——那属于规则变更不属于代码清理。九、边界说明本文只依据.pi/prompts/rust_clean.md与其在仓库中的实现展开。以下几点属于可确认的事实边界需在实操中自行验证文中所有 recipe 内容来自当前仓库快照若tooling/just/被改动命令语义可能变化仓库未提供根级just test清理流程本身不包含测试执行docs/development/rust.md 明确要求按包执行cargo test -p package环境依赖Nix dev shell、just、sqlx-cli、cargo需按 docs/development/rust.md 的说明准备当前文档未给出可省略的替代方案。将这四步理解为一条有向流水线而不是四个独立命令是.pi/prompts/rust_clean.md真正传达的信息缓存先行、lint 全量、范围校验、格式收尾失败即停。赞分享后端前端协同办公即时通讯企业应用CRMAI Agent人工智能【免费下载链接】macroMacro is a unified workspace for teams: email, chat, docs, tasks, agents, calls, and CRM — -linked together with shared AI memory.项目地址https://gitcode.com/GitHub_Trending/macro3/macro点击查看免费下载相关推荐GitLab CI集成rust-clippy打造自动化代码质量门禁GitLab CI集成rust clippy打造自动化代码质量门禁 你还在手动运行代码检查团队协作中是否常因代码风格不统一、潜在bug流入主分支而头疼本文静态分析代码质量开发工具Stable Video Infinity错误排查指南解决常见的渲染失败问题Stable Video Infinity错误排查指南解决常见的渲染失败问题 Stable Video InfinitySVI是一个革命性的无限长度视频生人工智能深度学习媒体生成视频微调LoRA多模态React Native Calendar Events API深度解析从基础查询到高级操作React Native Calendar Events API深度解析从基础查询到高级操作 React Native Calendar Events是一个功上一篇GDAL 栅格数据集只读线程安全RFC 101 从 API 到源码实现的完整指南下一篇Harbor 网络策略矩阵实战用 [verifier.environment] 构建「Agent 断网 Verifier 独立公网」的隔离评测任务创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
阅读完成 · 觉得有帮助？
