Fuel Corefuel-core仓库开发质量门禁实战nightly rustfmt 格式化、CI 同步与本地复现【免费下载链接】fuel-coreRust full node implementation of the Fuel v2 protocol.项目地址: https://gitcode.com/GitHub_Trending/fu/fuel-core这篇指南围绕 Fuel v2 全节点 Rust 实现fuel-core仓库根目录下的 AGENTS.md完整讲解任何涉及 Rust 源码的改动无论由人类开发者还是 AI 编码代理完成在合入前必须通过的质量门禁为什么格式化必须使用 CI 同款nightly rustfmt而不能用rust-toolchain.toml固定的 stable 工具链、如何逐条执行 .github/workflows/ci.yml 中rustfmt作业对应的命令以及如何借助 ci_checks.sh 在本地一次性复现绝大多数 CI 检查。读完你将掌握一套可直接复制的命令与判断标准避免提交因格式检查失败或意外重写数百个文件而被 CI 打回。一、仓库背景一份配置两套工具链的格局fuel-core是一个大型 Rust workspaceworkspace 成员定义在根 Cargo.tomlresolver 2同时面向wasm32-unknown-unknown目标构建可执行层与 WASM 执行器并引入了 2024 edition 与rust-version 1.93.0的 MSRV 约束。要理解 AGENTS.md 的质量门禁首先需要认清该仓库对编译工具链与格式化工具链的刻意区分用途工具链来源具体版本编译、测试、clippyrust-toolchain.tomlchannel 1.93.0stable pin含wasm32-unknown-unknowntarget格式化rustfmtCI 中单独指定的 nightlynightly-2025-09-28见 ci.yml 的env.RUST_VERSION_FMT也就是说仓库根目录的rust-toolchain.toml只控制日常cargo build/cargo test/cargo clippy使用的默认工具链而格式化这一环被显式排除在 stable 之外这是 AGENTS.md 反复强调的第一要义。二、为什么不能对 stable 工具链跑cargo fmtAGENTS.md 的 Hard rules 段落给出了一个极其重要的技术事实仓库根目录的 .rustfmt.toml 依赖若干nightly-only的 rustfmt 配置项。实际文件内容如下max_width 90 # changed normalize_comments true # changed imports_layout Vertical # changed imports_granularity Crate # changed trailing_semicolon false # changed edition 2024 # changed use_try_shorthand true # changed use_field_init_shorthand true # changed其中imports_layout Vertical、imports_granularity Crate、normalize_comments true、trailing_semicolon false都是 rustfmt 在 nightly 工具链上才稳定的能力。若误在 stable / 1.93.0 工具链上运行cargo fmtstable rustfmt 会静默忽略这些 nightly-only 选项不会报错也不会提示你格式不一致结果就是 import 区块会被 stable 默认的 compact / mixed 布局重排最终可能以紧凑的 import 布局重写仓库中数百个文件产生与 CI 预期完全相反的巨型 diff由于 CI 的rustfmt作业总是用 nightly-2025-09-28 跑--check本地 stable 格式化后的代码在该作业上必然失败PR 无法合入。因此 AGENTS.md 给出的硬性规则第一条是绝不要在来自rust-toolchain.toml的 stable / 1.93.0 工具链上执行cargo fmt/cargo fmt --all。三、质量门禁实操安装并应用 nightly rustfmtAGENTS.md 明确凡是触及 Rust 源码的改动在声称完成、提交或推送 PR 之前必须完成两步——用 CI 同款 nightly rustfmt 格式化并确认--check干净通过。完整命令如下与.github/workflows/ci.yml的rustfmt作业保持一致# 若本机尚未安装该 nightly 及其 rustfmt 组件先安装一次 rustup toolchain install nightly-2025-09-28 --component rustfmt # 应用格式化等价于 CI rustfmt 作业的写模式 cargo nightly-2025-09-28 fmt --all # 校验格式化结果等价于 CI 中 cargo nightly-2025-09-28 fmt --all -- --check cargo nightly-2025-09-28 fmt --all -- --check用法细节使用cargo toolchain语法显式指定工具链避免被rust-toolchain.toml的默认1.93.0覆盖尽量以--all格式化整个 workspace而不是只格式化局部文件。这样本地结果与 CI 作业逐字节可比PR diff 最小若确实只想格式化某个子集也必须使用nightly-2025-09-28并配合本仓库的 .rustfmt.toml而不是换用任何 stable 工具链cargo fmt --all -- --check中--之后的部分会直接透传给 rustfmt等价于 CI 执行的检查模式任何未格式化的文件都会使该命令以非零退出码失败。对应到 CI 侧.github/workflows/ci.yml 中第 5970 行的rustfmt作业完整复刻了这套逻辑先通过dtolnay/rust-toolchainmaster安装${{ env.RUST_VERSION_FMT }}即nightly-2025-09-28及rustfmt组件随后只执行一条命令- name: Rustfmt check run: cargo ${{ env.RUST_VERSION_FMT }} fmt --all -- --check这一作业位于 ci.yml并被后续cargo-verifications等矩阵作业通过needs: rustfmt前置依赖因此格式检查不过后续所有编译/测试作业都不会启动。四、保持版本同步RUST_VERSION_FMT与 CI 的一致性约定AGENTS.md 提出了一条容易被忽略的维护约定让RUST_VERSION_FMT与.github/workflows/ci.ymlenv.RUST_VERSION_FMT当前为nightly-2025-09-28保持同步。在 ci.yml 中nightly 版本与 MSRV 被集中声明为 envenv: RUST_VERSION: 1.93.0 RUST_VERSION_FMT: nightly-2025-09-28 RUST_VERSION_COV: nightly-2025-09-28 RUSTFLAGS: -D warnings这意味着仓库内所有工作流CI、覆盖率等共用一套 env 命名。若有人升级 nightly 格式化版本例如统一某个 rustfmt bug 修复或新导入布局能力必须同步更新 CI 的 env 与 AGENTS.md 中记录的安装命令否则会出现本地按 AGENTS.md 装了 A 版本、CI 用的是 B 版本的漂移导致格式化结果不一致。从仓库现状看RUST_VERSION_FMT声明为nightly-2025-09-28的主 CI 流程是 .github/workflows/ci.yml它把 warnings 视为错误RUSTFLAGS: -D warnings这与 AGENTS.md 中 clippy 要求相呼应。五、质量门禁的其余环节clippy 与本地 CI 复现5.1 clippywarnings 视为错误AGENTS.md 建议在改动涉及的 crate 上尽可能运行 stable pin 的 clippy 并加上-D warnings因为 CI 将 warnings 视为 errors见 ci.yml 中矩阵作业的RUSTFLAGS: -D warnings。推荐命令cargo clippy -- -D warnings若只想覆盖本次改动影响的 crate可以再加-p crate做范围裁剪例如cargo clippy -p fuel-core-types -- -D warnings值得一提的是仓库还通过根目录 clippy.toml 用disallowed-macros机制把log::*系列宏全部列入禁用清单理由是仓库统一使用tracing而非log所以 clippy 通过与否不仅是风格问题也承担着引导使用正确日志库的作用。此配置属于从源码可确认的事实可作为 clippy 门禁的一部分理解。5.2 一键本地复现source ci_checks.shAGENTS.md 的命令矩阵将source ci_checks.sh列为 Local CI-ish 选项。根目录的 ci_checks.sh 是一个近乎逐条搬运 CI 矩阵的 bash 脚本其执行顺序与内容如下cargo nightly fmt --all cargo sort -w --check source .github/workflows/scripts/verify_openssl.sh cargo clippy -p fuel-core-wasm-executor --target wasm32-unknown-unknown --no-default-features cargo clippy --all-targets --all-features cargo clippy --manifest-path version-compatibility/Cargo.toml --workspace cargo doc --all-features --workspace --no-deps cargo check -p fuel-core-types --target wasm32-unknown-unknown --no-default-features --features alloc # ... 其余 crate 的 wasm 目标 check、nextest 全 workspace 测试等脚本头部注释明确列出了本地运行的全部前置依赖Rust1.93.0stable pinNightly rust formatter即nightly-2025-09-28及其 rustfmt 组件通过cargo install安装的cargo-sort、cargo-make、cargo-insta、cargo-nextest通过npm install prettier prettier-plugin-toml安装的前端格式化工具用于 TOML 等文件的 prettier 检查。注意事项脚本第一行便是cargo nightly fmt --all但因为 AGENTS.md 规定 CI 固定的 nightly 是 2025-09-28且脚本中并未显式写出 nightly 日期因此严格复现 CI 时应先保证本机默认 nightly 恰好等于 CI 版本或手动将脚本内的命令替换为cargo nightly-2025-09-28。这是 AGENTS.md 与 ci_checks.sh 配合使用时最容易踩的坑值得在本地运行时留意。六、命令矩阵速查AGENTS.md 将日常操作整理为一张速查表逐条整理并补充说明如下步骤命令补充说明Setup拉取依赖cargo fetch基于根 Cargo.lock 预取全部锁定依赖网络较差时建议先执行Build构建cargo build使用rust-toolchain.toml的1.93.0stableversion-compatibility目录不在 workspace 内Test测试cargo test全 workspace 测试CI 中实际使用cargo nextest run见 ci_checks.shFormat必做cargo nightly-2025-09-28 fmt --all随后cargo nightly-2025-09-28 fmt --all -- --check必须先装rustup toolchain install nightly-2025-09-28 --component rustfmtLint静态检查cargo clippy -- -D warnings可加-p crate限定本次改动的 crate配合 clippy.toml 的禁用宏规则Local CI-ish本地近似 CIsource ci_checks.sh需预先装齐注释中列出的 cargo-sort / cargo-make / cargo-insta / cargo-nextest 与 prettier 插件其中Format必做一行的两段命令之间是先应用、后校验的关系先让 nightly rustfmt 重排代码再用--check确认没有再需要改动的内容从而保证与 CIrustfmt作业的输出完全一致。七、Hard Rules 总结三条红线AGENTS.md 的 Hard rules 本质上是三条不可逾越的红线任何 AI agent 或开发者在提交前都应逐条自检禁止用 stable 格式化永远不要对rust-toolchain.toml指向的 stable /1.93.0执行cargo fmt/cargo fmt --all。因为 .rustfmt.toml 中的imports_layout、imports_granularity、normalize_comments、trailing_semicolon是 nightly-only 选项stable 会忽略它们并按 compact import 布局重排可能把数百个文件改得面目全非优先全量格式化用 CI nightlycargo nightly-2025-09-28 fmt --all格式化整个 workspace使 PR 与 CI 结果严格一致即便要格式化子集也必须沿用该 nightly 与本仓库的.rustfmt.toml顺手跑 clippy在改动涉及到的 crate 上用 stable pin 跑cargo clippy并带-D warnings与 CI 将 warnings 视为 errors 的策略对齐。这三条红线共同服务于一个目标让本地改动在 CI 门禁上的第一次运行就通过同时避免工具链版本漂移带来的海量非必要 diff。八、领域/就绪度术语说明AGENTS.md 末尾提到ReadyvsHealth、Height Gap、Max Sync Height Diff等区块链同步领域术语的正式定义参见CONTEXT.md。需要如实指出的是当前仓库快照中未包含CONTEXT.md文件在仓库根目录与maxdepth 2范围内均未检索到这些术语属于 fuel-core 节点同步状态判断模型就绪状态、健康状态、与最新高度差、最大允许同步高度差的一部分。若你在真实开发环境中工作应向仓库维护者或 CI 环境确认CONTEXT.md的提供方式若本地缺失可仅将 AGENTS.md 中的该引用视为术语提示结合crates/services/sync与 crates/fuel-core 中同步与状态上报相关实现去理解对应语义。九、给 AI 编码 Agent 的落地清单将全文浓缩为一份可直接照做的 checklist供以 AI agent 身份在本仓库工作时逐项确认改动是否触及.rs文件若是质量门禁不可跳过是否已执行rustup toolchain install nightly-2025-09-28 --component rustfmt仅首次需要是否已用cargo nightly-2025-09-28 fmt --all格式化且cargo nightly-2025-09-28 fmt --all -- --check退出码为 0是否确认全程没有对1.93.0stable 工具链执行过cargo fmt改动涉及 crate 是否已通过cargo clippy -p crate -- -D warnings是否已对照 CI env 确认RUST_VERSION_FMT仍为nightly-2025-09-28若需提交版本管理相关改动是否同步更新根 CHANGELOG.md 与.changes变更文件CI 的check-changelog作业会校验 PR 必须在.changes目录下存在对应变更记录见 ci.yml。以上清单全部通过即可认为改动在格式化与 lint这一维度的质量门禁上达标可以放心进入构建、测试与代码评审阶段。关键参考文件作为本指南主线的 AGENTS.md、格式化配置 .rustfmt.toml、工具链声明 rust-toolchain.toml、CI 主流程 .github/workflows/ci.yml、本地 CI 复现脚本 ci_checks.sh以及 workspace 元数据 Cargo.toml。【免费下载链接】fuel-coreRust full node implementation of the Fuel v2 protocol.项目地址: https://gitcode.com/GitHub_Trending/fu/fuel-core创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考