ARTICLE DETAIL

资讯详情

深耕郑州网站建设与运营推广的一线实战洞察。

Optimism 单仓 Rust 工程实战:修复 rust-fmt CI 门禁的 mise + just fmt-fix 标准流程

Optimism 单仓 Rust 工程实战:修复 rust-fmt CI 门禁的 mise + just fmt-fix 标准流程 Optimism 单仓 Rust 工程实战修复 rust-fmt CI 门禁的 mise just fmt-fix 标准流程【免费下载链接】optimismOptimism is Ethereum, scaled.项目地址: https://gitcode.com/GitHub_Trending/op/optimism本文基于 Optimism 仓库中面向 AI Agent 的技能文档 fix-rust-fmt 展开说明当 PR 的rust-fmtCI 作业失败时如何完成修复从mise trust/mise install准备钉死版本的工具链到在rust/目录执行mise exec -- just fmt-fix一次性完成格式化并结合rust/justfile、rust/rustfmt.toml与 CircleCI 配置讲清为什么该流程必须依赖 nightly 工具链、CI 门禁与本地 pre-push 钩子为何不会漂移。读完后你能够独立完成 rust-fmt 失败的定位、修复与提交并理解其背后的双 Cargo 工作区格式化机制。适用场景与触发条件根据技能文档的定义该技能的使用时机非常明确当某个触碰了 Rust 代码的 PR 上rust-fmtCI 作业失败时。文档同时列出了三个触发短语Trigger Phrases便于人类和 Agent 快速识别意图Fix rust formattingrust-fmt is failingFix the rust-fmt CI job在仓库的 Agent 工作流文档中该技能被登记为可通过斜杠命令调用的能力。rust-dev.md 的 Skills 一节写明Fix Rust Formatting.claude/skills/fix-rust-fmt/SKILL.md用于通过安装钉死的 nightly 工具链并运行just fmt-fix来修复rust-fmtCI 失败调用方式为/fix-rust-fmtrust/kona/CLAUDE.md 中也提示若rust-fmtCI 失败使用/fix-rust-fmt。技能文档的 Notes 部分给出了一条关键结论也是整套流程成立的前提无需检查rust-fmtCI 的报错输出——作业失败本身就是全部所需的信息运行just fmt-fix并提交产生的改动即为完整修复。这是因为 rustfmt 是确定性格式化器CI 检查--check与本地修复使用同一工具链、同一配置文件本地修复后重新检查必然通过逐个阅读 CI 的 diff 报错没有信息增量。前置条件mise 必须已安装并信任本仓库技能文档的 Prerequisites 一节要求mise必须已安装并信任trust本仓库即执行mise trust mise installOptimism 单仓所有工具的版本都钉死在仓库根目录的 mise.toml 中开发工作流文档 dev-workflow.md 对此有进一步约定始终通过 mise 访问工具不要安装或直接调用系统全局版本AI Agent 的 shell 通常没有激活 mise 环境因此命令需要以mise exec --前缀执行后文 Step 2 的命令正是这一模式的实例如果 mise 报告仓库未受信任应交由用户执行mise trust不应自动信任每个 clone 可再执行一次mise exec -- just install-git-hooks把 git 的core.hooksPath指向.githooks/安装 pre-push 钩子见下文本地与 CI 的门禁如何保持一致一节。Step 1从仓库根目录执行 mise install技能文档 Workflow 的第一步在仓库根目录或 worktree 根目录执行cd REPO_ROOT mise install文档说明该命令会安装rust、just以及mise.toml中钉死的其余所有工具。对照 mise.toml 的实际情况mise.toml#L9-L12rust被钉为两个版本rust [ { version 1.95.0, components clippy,rustfmt,llvm-tools, targets riscv32imac-unknown-none-elf,wasm32-unknown-unknown,wasm32-wasip1 }, { version nightly-2026-08-22, components rustfmt,clippy }, ]1.95.0是 stable 工具链附带clippy、rustfmt、llvm-tools组件以及若干交叉编译 targetnightly-2026-08-22是格式化与部分 lint 所需的 nightly 工具链组件为rustfmt,clippy。此外 mise.toml#L24 还钉死了just 1.46.0即just fmt-fix所用构建编排工具的版本。也就是说mise install之后格式化的两个关键依赖——just与 nightly 的rustfmt——都以可复现的钉死版本就位本地与 CI 使用同一版本。值得一提的是rust/justfile 第 3 行通过 grep 从mise.toml反向解析 nightly 版本NIGHTLY : grep -oE nightly-[0-9]{4}-[0-9]{2}-[0-9]{2} ../mise.toml | head -1从源码结构看这意味着justfile不重复维护一份 nightly 版本号而是以mise.toml为单一事实来源两者天然保持同步升级工具链时只需改mise.toml一处。配套的 rust/justfile#L24-L25 还提供了手动安装 nightly 的备选路径install-nightly: rustup toolchain install {{NIGHTLY}} --component rustfmt --component rust-srcStep 2在 rust/ 目录运行 mise exec -- just fmt-fix技能文档 Workflow 的第二步cd REPO_ROOT/rust mise exec -- just fmt-fix文档同时说明任何被改动的文件就是 CI 作业失败的原因直接 stage 并提交它们即可。mise exec --的作用在技能文档 Notes 中有明确解释它激活 mise 环境使cargo、just、rustup解析到mise.toml中钉死的版本而不是调用机器上可能存在的其他版本。fmt-fix 在 justfile 中的真实实现rust/justfile#L133-L135 中fmt-fix的定义是# Fix formatting (requires nightly); also formats the SP1 guest workspace fmt-fix: fmt-fix-sp1-guest cargo {{NIGHTLY}} fmt --all它做了两件事依赖fmt-fix-sp1-guest先格式化嵌套的 SP1 guest 工作区再以 nightly 工具链对外层整个工作区执行cargo {{NIGHTLY}} fmt --all。这里涉及 Optimism Rust 工程的双工作区结构。rust/justfile#L5-L8 的注释说明了原因SP1 guest 程序位于一个嵌套的 Cargo 工作区中为 SP1 加密补丁隔离而独立因此 fmt/clippy/测试都必须显式指定其 manifest该 manifest 被定义为kona/sp1/programs/Cargo.toml变量SP1_GUEST_MANIFEST且 guest 工作区从rust/目录运行以共享rust/rustfmt.toml与rust/clippy.toml。对应的修复与检查配方为fmt-check-sp1-guest: check-sp1-guest-lints cargo {{NIGHTLY}} fmt --manifest-path {{SP1_GUEST_MANIFEST}} --all -- --check fmt-fix-sp1-guest: _sync-sp1-guest-lints cargo {{NIGHTLY}} fmt --manifest-path {{SP1_GUEST_MANIFEST}} --all从源码结构看fmt-fix-sp1-guest在格式化前还会先运行_sync-sp1-guest-lints把根工作区Cargo.toml中# BEGIN/END SHARED WORKSPACE LINTS标记之间的共享 lint 配置同步到 guest manifest防止两个工作区的 lint 配置漂移——这与格式化检查属于同一套防漂移设计。另外rust/justfile#L11-L14 为常用配方定义了别名因此just f、just fmt与just fmt-fix等价[rust/kona/CLAUDE.md](https://link.gitcode.com/i/33bf94be873813437a76d30716b8eaba)中提到的just f即来源于此alias f : fmt-fix alias fmt : fmt-fix为什么格式化必须使用 nightly 工具链技能文档 Notes 指出nightly 工具链是必需的因为工作区使用了不稳定的rustfmt选项见rust/rustfmt.toml。查看 rust/rustfmt.toml 的完整内容style_edition 2024 imports_granularity Crate use_small_heuristics Max comment_width 100 wrap_comments true binop_separator Back format_code_in_doc_comments true doc_comment_code_block_width 100 format_macro_matchers true其中style_edition 2024、wrap_comments、format_code_in_doc_comments、format_macro_matchers等属于 rustfmt 尚未稳定的选项stable 渠道的rustfmt无法完全支持——这正是不依赖 nightly 会检查不过或格式不一致的根本原因。rust/justfile#L125-L127 的注释同样标注了这一点# Check formatting (requires nightly) fmt-check: cargo {{NIGHTLY}} fmt --all -- --checkrust-dev.md 的 Formatting Requires Nightly 一节给出了与技能文档一致的结论格式化使用钉死的 nightly 工具链定义在rust/justfile的NIGHTLY通过 mise 安装用just fmt-fix自动格式化用just fmt-check校验。这也解释了mise exec --的重要性如果 shell 里直接裸跑just fmt-fix而cargo/just来自系统全局环境{{NIGHTLY}}可能解析不到对应工具链或解析到错误版本的 rustfmt导致本地通过而 CI 失败。本地与 CI 的门禁如何保持一致理解修复流程为何一步到位还需要看rust-fmtCI 作业与本地钩子各自执行什么。CI 侧rust-fmt 作业执行 just fmt-checkCI 配置位于 rust-ci.yml。共享的格式化检查作业rust-ci-fmtrust-ci.yml#L40-L62定义如下关键参数工作目录parameters.directory该作业传入rust检查命令parameters.command默认值为just fmt-check。而rust-ci工作流中该作业以rust-fmt之名挂载rust-ci.yml#L792-L795- rust-ci-fmt: name: rust-fmt directory: rust即 CI 的rust-fmt作业等价于在rust/目录运行just fmt-check展开后是cargo {{NIGHTLY}} fmt --all -- --check外层工作区。本地侧pre-push 钩子执行 just fmt-check-allrust/justfile#L129-L131 定义了一个聚合目标其注释直接点明了设计意图# Check formatting across both the main and SP1 guest workspaces. Shared by the # pre-push git hook and the rust-fmt CI job so the two cant drift. fmt-check-all: fmt-check fmt-check-sp1-guestpre-push git hook 与 rust-fmt CI 作业共享此目标使二者不可能漂移。仓库的 .githooks/pre-push 钩子正是通过它复刻 CI 行为仅当本次推送的 diff 中实际包含.rs文件时才执行pre-push#L11-L25 按 ref 范围判断纯 Go/文档改动零开销找不到mise时直接报错退出提示安装 mise 后重新推送pre-push#L27-L30否则在rust/目录执行just fmt-check-all失败时打印修复指引run just fmt-fix in rust/ and re-commitpre-push#L40-L43。钩子由just install-git-hooks安装将core.hooksPath指向.githooks/说明见 .githooks/README.mdpre-push会在推送包含.rs变更时拦截未格式化的 Rust 代码执行的正是聚合目标just fmt-check-all。汇总来看门禁链条是本地just fmt-fix修复→just fmt-check-allpre-push 校验双工作区→ CIrust-fmtjust fmt-check外层工作区——全部经由rust/justfile中同一组配方、同一个从mise.toml派生的NIGHTLY工具链因此修复流程只需一次格式化加一次提交无需人工比对 CI 报错。格式时机的最佳实践只在最后一次编辑后运行rust-dev.md 的 Before Every Commit 一节对格式化时机有一条值得牢记的告诫格式化只在最后一次编辑之后运行绝不在编辑之间运行。原文解释了原因nightly 格式化器有自己的审美例如把多行let绑定合并到一行编辑器工具无法复现这些变换——若在会话中途运行fmt-fix、随后又继续编辑新编辑的代码会再次变得未格式化最终仍会失败rust-fmtCI 检查。格式化之后建议运行git diff --stat确认工作区状态与你即将提交的内容一致。这与技能文档修复 运行 fmt-fix 提交改动的极简流程互为补充CI 失败后按 Step 1/Step 2 走一遍把格式化作为提交前的最后一步即可闭环。命令与文件速查内容路径 / 命令说明技能文档SKILL.md本文主体触发条件、前置条件、两步修复流程工具版本钉死mise.tomlrust 1.95.0 nightly-2026-08-22、just 1.46.0 等安装工具cd REPO_ROOT mise install安装mise.toml钉死的全部工具修复格式化cd REPO_ROOT/rust mise exec -- just fmt-fix外层 SP1 guest 双工作区一次格式化格式化配方rust/justfilefmt-fix、fmt-check、fmt-check-all、NIGHTLY派生逻辑rustfmt 配置rust/rustfmt.toml含 nightly-only 选项故需 nightly 工具链CI 作业rust-ci.ymlrust-ci-fmt作业工作流内名称rust-fmt执行just fmt-check本地钩子.githooks/pre-push含.rs变更时执行just fmt-check-all失败则拦截推送开发工作流dev-workflow.md、rust-dev.mdmise 使用约定、格式化时机建议小结fix-rust-fmt技能把修复 rust-fmt CI 失败压缩成两个确定动作mise install让just与 nightlyrustfmt以钉死版本就位mise exec -- just fmt-fix以 CI 同一套配方完成双工作区格式化改动直接提交。其可靠性来自仓库内的防漂移设计NIGHTLY版本由justfile从mise.toml解析、fmt-check-all同时被 pre-push 钩子与 CI 复用、SP1 guest 工作区与根工作区共享同一份rustfmt.toml。理解了这条链路rust-fmt 的失败就不再需要逐行排查 CI 日志——运行修复、查看git diff、提交即是完整闭环。【免费下载链接】optimismOptimism is Ethereum, scaled.项目地址: https://gitcode.com/GitHub_Trending/op/optimism创作声明:本文部分内容由AI辅助生成(AIGC),仅供参考
返回列表