ECC 实战指南：用 /rust-build 命令与 rust-build-resolver Agent 增量修复 Rust 构建错误

2026-09-07 23:56:12作者：谭伦延

The agent harness performance optimization system. Skills, instincts, memory, security, and research-first development for Claude Code, Codex, Opencode, Cursor and beyond.

项目地址：https://gitcode.com/GitHub_Trending/ev/ECC

导读

在 ECC（Agent Harness Performance Optimization System）这一面向 Claude Code、Codex、Opencode、Cursor 等工具链的 Agent 编排体系中，/rust-build 是专为 Rust 工程设计的“构建错误救援”命令：当你遇到 cargo build/cargo check 报错、借用检查器（borrow checker）或生命周期错误阻塞编译、依赖解析失败，或在拉取他人改动后构建被破坏时，它都会接管诊断—修复—验证的完整闭环。读完本文，你将掌握 /rust-build 的命令语义、它背后 rust-build-resolver Agent 的诊断命令序列与最小化修复策略、常见错误的对照速查表，以及如何将这套“一次只修一个错误、修完立即重验”的增量方法论落地到真实的 Rust 工程（例如仓库自带的 ecc2 TUI crate）中。

/rust-build 命令是什么：文档定义与适用场景

依据 commands/rust-build.md 的定义，该命令会调用 rust-build-resolver Agent，以最小、外科手术式（surgical）的改动增量修复 Rust 构建错误。其 front matter 描述为：

Fix Rust build errors, borrow checker issues, and dependency problems incrementally. Invokes the rust-build-resolver agent for minimal, surgical fixes.

它的工作分五个阶段：

运行诊断：依次执行 cargo check、cargo clippy、cargo fmt --check；
解析错误：识别错误码（如 E0502、E0308、E0425）与受影响文件；
增量修复：一次只处理一个错误；
逐次验证：每次改动后重新运行 cargo check；
汇总报告：说明修了什么、还剩什么。

文档明确给出了建议触发 /rust-build 的五类场景：

cargo build 或 cargo check 报错失败；
cargo clippy 报告告警；
借用检查器或生命周期错误阻塞编译；
Cargo 依赖解析失败；
拉取代码变更后构建被破坏。

命令背后：rust-build-resolver Agent 的定位

/rust-build 是用户侧的“遥控器”，真正执行修复逻辑的是 agents/rust-build-resolver.md 中定义的 Agent。该 Agent 在 front matter 中声明了如下元数据：

name: rust-build-resolver
description：Rust 构建/编译/依赖错误解析专家，负责修复 cargo build 错误、借用检查器问题与 Cargo.toml 问题，改动保持最小化；
tools: Read, Write, Edit, Bash, Grep, Glob——即它具备读写文件、执行命令、搜索定位的能力；
model: sonnet

其核心职责被划分为六项：诊断 cargo build/cargo check 错误、修复借用检查器与生命周期错误、解决 trait 实现不匹配、处理 Cargo 依赖与 feature 问题、修复 cargo clippy 告警。这与命令文档中“Diagnostic Commands Run”与“Fix Strategy”两节一一对应。

值得注意的是，Agent 定义中还包含一套 Prompt Defense Baseline（提示词防御基线）：要求 Agent 不得泄露机密数据与密钥、不得输出未经验证的可执行代码、对 unicode 同形字/零宽字符/编码混淆/越权内容等视为可疑输入等。这说明在 ECC 的体系里，即便是一个纯代码修复类 Agent，也默认带上了安全护栏，避免被第三方仓库内容或恶意 prompt 劫持。

诊断命令序列：先全量快照，再逐个击破

命令文档与 Agent 定义给出了同一套按序执行的诊断命令。这套命令是 /rust-build 一切决策的信息来源：

# 主要构建检查（解析 error code 与受影响文件）
cargo check 2>&1

# Lints 与建议（把告警升级为错误，便于门禁式管理）
cargo clippy -- -D warnings 2>&1

# 格式化检查
cargo fmt --check 2>&1

# 依赖问题（查找重复依赖）
cargo tree --duplicates

# 安全审计（可用时执行）
if command -v cargo-audit >/dev/null; then cargo audit; else echo "cargo-audit not installed"; fi

要点解读：

cargo check 优先于 cargo build：check 只做类型检查与借用检查、不做代码生成，速度远快于完整 build，因此作为“每次修复后的验证闸门”最合适；
cargo clippy -- -D warnings：把 clippy 的所有告警当成硬错误处理，用于保证合入前没有“灰色地带”的告警残留；
cargo fmt --check：只检查不写入，避免 Agent 静默改动全文件格式；
cargo tree --duplicates：定位同一依赖多版本并存的问题，这是“依赖解析失败”类报错最常见的源头；
cargo audit 是条件执行：只有当环境中存在 cargo-audit 时才运行，避免因工具缺失而中断流程。

在 rust-build-resolver 的 Resolution Workflow 中，这套命令进一步被编排为一个显式循环：

1. cargo check          -> Parse error message and error code
2. Read affected file   -> Understand ownership and lifetime context
3. Apply minimal fix    -> Only what's needed
4. cargo check          -> Verify fix
5. cargo clippy         -> Check for warnings
6. cargo test           -> Ensure nothing broke

其中第 2 步“读受影响文件并理解所有权与生命周期上下文”尤为关键——Rust 的借用检查错误光看报错行往往无法定位，必须结合函数签名、数据结构与调用上下文才能判断“该结束借用、该转移所有权、还是该加生命周期标注”。

完整示例会话：3 个错误的增量修复演示

commands/rust-build.md 用一段完整的模拟会话展示了从诊断到收尾的 Agent 行为模式，我们在此完整保留并逐段拆解。

初始诊断

$ cargo check
error[E0502]: cannot borrow `map` as mutable because it is also borrowed as immutable
  --> src/service/cache.rs:25:5
error[E0308]: mismatched types
  --> src/handler/api.rs:42:12
error[E0425]: cannot find value `db` in this scope
  --> src/handler/api.rs:58:9

Errors found: 3

拆解：Agent 输出以 error[E编号] 为锚点，同时给出文件与行号，这正是后续“逐错误修复”的最小工作单元。E0502（可变/不可变借用冲突）、E0308（类型不匹配）、E0425（作用域内找不到该值）恰好对应三种不同类型的典型编译错误。

Fix 1：借用检查器错误

File: src/service/cache.rs:25
Error: E0502 — cannot borrow `map` as mutable because also borrowed as immutable
Cause: Immutable borrow still active during mutable insert

// Changed: restructured to end immutable borrow before mutable access
if !map.contains_key("key") {
    map.insert("key".into(), default);
}

$ cargo check
# 2 errors remaining

拆解：contains_key("key") 返回的是 bool（按值返回），它在 if 条件求值后立即结束借用，因此条件体内可以安全地进行 map.insert 可变借用。若原代码曾写成 if map.get("key").is_none()，由于 is_none() 只在临时引用上求值也通常没问题；真正的坑是“把不可变借用结果保存到变量中跨越了 insert”。注意这里刻意没有使用 clone()，与后文“clone 仅在确有理由时才用”的原则一致——用重构结束借用，而不是用复制掩盖问题。

Fix 2：类型不匹配

File: src/handler/api.rs:42
Error: E0308 — mismatched types: expected `usize`, found `&str`

// Changed
let count = params.get("count");
// To
let count: usize = params.get("count")
    .and_then(|s| s.parse().ok())
    .unwrap_or(0);

$ cargo check
# 1 error remaining

拆解：params.get(...) 返回 Option<&str>，无法直接赋给 usize。修复采用安全解析链：and_then(|s| s.parse().ok()) 把解析失败折叠成 None，最后由 unwrap_or(0) 提供默认值，全程无 panic 路径。这符合 Agent 原则中“不要用 .unwrap() 去掩盖类型错误，应传播或提供默认值”的要求。

Fix 3：未解析的名称

File: src/handler/api.rs:58
Error: E0425 — cannot find value `db` in this scope
Cause: Missing import

// Added
use crate::db;

$ cargo check
# Build successful!

拆解：E0425 的常见成因有两种——缺少 use 导入，或路径写错。此处修复只补了一行 import。

最终验证与汇总

$ cargo clippy -- -D warnings
# No warnings

$ cargo test
running 6 tests
test service::cache::tests::test_insert ... ok
test service::cache::tests::test_get ... ok
test handler::api::tests::test_parse_count ... ok
test handler::api::tests::test_missing_count ... ok
test handler::api::tests::test_db_import ... ok
test handler::api::tests::test_response ... ok

test result: ok. 6 passed; 0 failed; 0 ignored

Metric	Count
Build errors fixed	3
Clippy warnings fixed	0
Files modified	2
Remaining issues	0

Build Status: SUCCESS

拆解：注意收尾阶段的完整闭环——不仅 cargo check 通过，还补跑了 cargo clippy 与 cargo test。cargo test 输出中出现了 test_insert、test_parse_count、test_db_import 等与三个修复点一一对应的用例名，说明这些修复是被测试覆盖到的行为，而非“编译器放行但语义存疑”的补丁。

常见编译错误速查表：错误码 → 修复模式

命令文档给出了七类常见错误的典型修复方向，Agent 定义则将其扩展为更细粒度的对照表。我们把两者合并成一张可直接查用的速查表：

Error（报错信息片段）	Typical Fix（典型修复）
`cannot borrow as mutable`	重构代码以先结束不可变借用（必要时 `Cell`/`RefCell`），只有在确有理由时才 clone
`does not live long enough`	改用拥有所有权的类型，或添加生命周期标注
`cannot move out of`	重构以转移所有权；clone 只是最后手段
`mismatched types` / `expected X, found Y`	添加 `.into()`、`as` 或显式类型转换
`trait X not implemented`	添加 `#[derive(Trait)]` 或手动实现 trait
`unresolved import`	在 Cargo.toml 中补充依赖，或修正 `use` 路径
`cannot find value`	添加 import 或修正路径
`unused variable` / `unused import`	删除死代码，或以前缀 `_` 标注
`cannot find macro`	补充 `#[macro_use]`，或启用对应依赖 feature / 导入宏
`multiple applicable items`	使用全限定语法 `<Type as Trait>::method()` 消除歧义
`lifetime may not live long enough`	添加生命周期约束，或按需使用 `'static`
`async fn is not Send`	重构，使非 Send 值在 `.await` 之前被释放
`the trait bound is not satisfied`	为泛型参数添加 trait bound
`no method named X`	补充 `use Trait;` 导入该 trait

这条表的实用价值在于：多数 Rust 编译错误是“模式可复用”的。当 Agent 面对陌生错误时，先查表匹配错误码与修复模板，再读代码上下文做最终判断，成功率远高于从头推理。

深度剖析：借用检查器三大经典陷阱与修复样板

Agent 定义中针对借用检查器给出了三组带完整代码的“问题—修复”样板，这是理解 E0502 家族错误最直观的材料：

陷阱一：可变借用时不可变借用仍存活

// Problem: Cannot borrow as mutable because also borrowed as immutable
// Fix: Restructure to end immutable borrow before mutable borrow
let value = map.get("key").cloned(); // Clone ends the immutable borrow
if value.is_none() {
    map.insert("key".into(), default_value);
}

这里的 .cloned() 是有充分理由的：它把 Option<&V> 变成 Option<V>，借用随 clone 立即结束，从而允许后续 insert。这与“无脑 clone 规避借用检查”的坏味道不同——关键区别在于 clone 的是小体积的查询结果而非整个容器。

陷阱二：悬垂引用（值先被释放，引用后返回）

// Problem: Value does not live long enough
// Fix: Move ownership instead of borrowing
fn get_name() -> String {     // Return owned String
    let name = compute_name();
    name                       // Not &name (dangling reference)
}

返回类型从“借用局部变量”改为拥有所有权的 String，从根源上消除悬垂引用。

陷阱三：从索引处移出

// Problem: Cannot move out of index
// Fix: Use swap_remove, clone, or take
let item = vec.swap_remove(index); // Takes ownership
// Or: let item = vec[index].clone();

swap_remove 用末尾元素填补空位后转移所有权，O(1) 且不破坏顺序语义；当顺序敏感时退而用 .clone()。选型依据是：是否关心被移除元素之后剩余元素的相对顺序。

Cargo.toml 与依赖问题排查工具箱

当问题不是出在代码而是出在依赖解析上时，rust-build-resolver 提供了一套 Cargo 原生命令作为工具箱：

# 检查依赖树中的重复依赖
cargo tree -d                          # Show duplicate dependencies
cargo tree -i some_crate               # Invert — who depends on this?

# Feature 解析
cargo tree -f "{p} {f}"               # Show features enabled per crate
cargo check --features "feat1,feat2"  # Test specific feature combination

# Workspace 问题
cargo check --workspace               # Check all workspace members
cargo check -p specific_crate         # Check single crate in workspace

# Lock 文件问题
cargo update -p specific_crate        # Update one dependency (preferred)
cargo update                          # Full refresh (last resort — broad changes)

实操建议按此优先级：

先看重复依赖：cargo tree -d（等价于 --duplicates）能立刻暴露同一 crate 的多个版本，多半是传递依赖版本约束冲突所致；
再用反向查询定位来源：cargo tree -i some_crate 回答“是谁把这份依赖拉进来的”，便于决定升级谁或约束谁；
feature 组合单独验证：很多“本地能编、CI 编不过”的问题源于 feature 组合差异，cargo check --features 用于定点复现；
workspace 场景区分粒度：--workspace 全量检查，-p 精确到单个 crate，缩短反馈回路；
锁文件只做定点升级：cargo update -p 只动一个依赖，cargo update 全量刷新是“最后手段”——它会带来大范围变更，违背“minimal changes”总原则。

Edition 与 MSRV（最低支持 Rust 版本）问题

# 在 Cargo.toml 中查看 edition
grep "edition" Cargo.toml

# 查看当前 rustc 版本与声明的 MSRV
rustc --version
grep "rust-version" Cargo.toml

# 常见修复：为新语法升级 edition（务必先确认 rust-version！）
# 在 Cargo.toml 中：edition = "2024"   # Requires rustc 1.85+

命令文档特别标注了一个次序纪律：升级 edition 前必须先核对 MSRV。因为 edition = "2024" 需要 rustc 1.85+，如果团队 CI 或用户环境仍停留在旧工具链，盲目升级会引入“比修好的错误更多的错误”。

这一点在当前仓库中有真实的旁证：ecc2 crate 的 rust-toolchain.toml 中写道：

[toolchain]
# Minimum 1.85 required: several dependencies use edition2024.
channel = "1.96"
components = ["rustfmt", "clippy"]

它既声明了 channel = "1.96" 固定工具链版本，也显式安装了 rustfmt 与 clippy 两个组件——正好是 /rust-build 诊断序列所依赖的 cargo fmt --check 与 cargo clippy 的前置条件。同时 Cargo.toml 内的注释“several dependencies use edition2024”印证了“MSRV 由依赖链驱动”的现实，任何依赖升级都可能在 cargo update 后悄然抬升最低工具链要求——这正是需要 cargo tree 与工具链版本双核对的原因。

最小化修复的五大原则与纪律红线

命令文档的 Fix Strategy 与 Agent 定义的 Key Principles 相互呼应，构成该命令的方法论内核：

修复次序（Fix Strategy）

构建错误优先 —— 代码必须先能编译；
clippy 告警次之 —— 修复可疑构造；
格式化第三 —— 满足 cargo fmt；
一次只修一个 —— 每次改动都验证；
改动最小化 —— 只修不重构。

纪律红线（Key Principles）

外科手术式修复：不做重构，只修当前错误；
未经明确批准，绝不添加 #[allow(unused)]；
绝不用 unsafe 绕过借用检查错误；
绝不用 .unwrap() 压制类型错误 —— 应使用 ? 传播；
每次修复尝试后必须运行 cargo check；
修根因而非压制症状；
优先选择能保留原始意图的最简修复。

停止条件：什么时候 Agent 必须停下来上报

一套负责任的自动修复流程必须知道自己的边界。命令文档与 Agent 定义共同约定：出现以下任一情况，Agent 停止修复并上报，而不是继续硬撑：

同一错误在 3 次修复尝试后仍然存在；
修复引入的错误比解决的还多；
该错误需要超出范围的架构级改动；
借用检查错误需要重新设计数据所有权模型。

停止条件的意义在于成本控制：当问题从“局部 bug”升级为“所有权模型设计错误”时，继续自动尝试不仅命中率低，还可能把代码越改越糟，此时正确动作是交还给开发者做架构决策。

修复的收尾格式与可审计性

Agent 定义还为每次修复规定了统一的输出格式，保证过程可审计、可回溯：

[FIXED] src/handler/user.rs:42
Error: E0502 — cannot borrow `map` as mutable because it is also borrowed as immutable
Fix: Cloned value from immutable borrow before mutable insert
Remaining errors: 3

最终收尾必须给出一行状态摘要：

Build Status: SUCCESS/FAILED | Errors Fixed: N | Files Modified: list

这种“文件:行号 + 错误码 + 修复手法 + 剩余错误数”的结构化输出，让每一次修复都能被 review、被回滚、被统计——也正是命令文档示例中那两张 Summary 表格（错误修复数/文件改动数）的底层来源。

与 /rust-test、/rust-review 的配合链路

/rust-build 不是孤立的命令。命令文档与 commands/rust-review.md 的 “Integration with Other Commands” 一节共同勾勒出一条完整的 Rust 工程流水线：

先 /rust-test：以 TDD 方式编写测试、确保测试通过（见 commands/rust-test.md）；
构建失败用 /rust-build：修复编译与借用检查错误；
提交前用 /rust-review：对所有权、生命周期、错误处理、unsafe 用法做全面代码评审（调用 rust-reviewer Agent）；
非 Rust 专项问题走 /code-review。

同时三者共享同一个“质量闸门”约定：cargo check、cargo clippy -- -D warnings、cargo fmt --check、cargo test 四项全部通过才允许继续，cargo audit 可用时执行。rust-review 会把未检查的 unwrap()/expect()、缺少 // SAFETY: 注释的 unsafe 等列为 CRITICAL 并阻止合并——这反过来要求 /rust-build 的修复质量必须达到“可被评审放行”的标准。

生态纵深：rust-patterns 与 rust-testing Skill 的支撑

命令文档与 Agent 定义在末尾都指向了两个 skill 作为深度补充：

skills/rust-patterns/SKILL.md：讲解惯用 Rust 模式——所有权与借用（含 Cow 的按需拥有）、Result/? 错误传播（库用 thiserror、应用用 anyhow）、用枚举与穷尽匹配表达非法状态、trait 与泛型的零成本抽象、Arc<Mutex<T>>/channel/async 的并发模型、最小化 pub 面等。它把 /rust-build 的“错误修复”从“让编译器闭嘴”提升到“让代码符合惯用范式”的层面；
skills/rust-testing/SKILL.md：与 /rust-test 配套的 TDD 技能，覆盖 #[test]、rstest 参数化测试、#[tokio::test] 异步测试、proptest 属性测试与 cargo llvm-cov 覆盖率门槛。

对修复者而言，这两个 skill 的深层价值在于：当修复方案与惯用模式冲突时（例如是否引入 Cow、是否用 thiserror 替代裸字符串错误），skill 提供了决策依据，避免“编译器通过了、但代码风格跑偏”的次生问题。

在当前仓库中实际演练：ecc2 crate 与 Cargo 工程要素

要验证 /rust-build 命令对真实工程的适用性，仓库内的 ecc2 子项目是最佳演练对象。ecc2/Cargo.toml 是一个真实的 Rust 二进制 crate（ecc-tui），它呈现了 Agent 需要处理的全部工程要素：

feature 与平台相关依赖：默认启用 vendored-openssl = ["git2/vendored-openssl"]，这类 feature 传递是依赖解析问题的常见温床；
版本约束形态多样：既有 ratatui = { version = "0.30", features = [...] }、git2 = { version = "0.21", features = ["ssh"] } 的 feature 化声明，也有 serde = { version = "1", features = ["derive"] } 与 chrono = { version = "0.4", features = ["serde"] } 等需要对齐 feature 的依赖；
release 调优 profile：lto = true、codegen-units = 1、strip = true，若在这些 profile 下出现链接类问题，cargo check 未必能复现，需回到完整 cargo build --release 验证；
模块组织清晰（src/main.rs 中 mod comms; mod config; mod harness_eval; mod notifications; mod observability; mod session; mod tui; mod worktree; 共 12800+ 行源码），src/main.rs 中的测试辅助模块 CurrentDirGuard 还展示了 anyhow::Context、OnceLock<Mutex> 等在真实代码中的应用，正好对应 rust-patterns 中“应用用 anyhow + ? 上下文传播”的建议。

若你拉取本仓库后构建 ecc2 失败，即可按本文工作流演练：先 cargo check 收集错误码 → 按速查表定位模式 → 一次修一个并逐次 cargo check → 全部通过后补跑 cargo clippy 与 cargo test。工具链层面则由 rust-toolchain.toml 自动保证 rustfmt/clippy 组件可用。

小结：增量、最小、可验证的修复方法论

/rust-build 命令的真正价值不在某条命令或某个错误码，而在于它固化了一套可复用的工程方法论：用 cargo check 快速取证 → 用错误码速查表缩小范围 → 读上下文定位根因 → 以最小改动逐错误修复 → 每次验证 → 收尾补跑 clippy/test → 结构化汇报，并在触及架构边界或连续失败时果断止损上报。配合 rust-build-resolver Agent 的安全基线、rust-patterns 的惯用范式与 rust-testing 的测试保障，它构成了 Agent 化 Rust 工程维护中“构建修复”这一环的完整参考实现——既适合在 ECC 体系中直接使用，也值得在任何需要自动化修复 Rust 构建的流水线中借鉴。