ECC 命令实战：使用 /cpp-build 增量修复 C++ 构建、CMake 与链接错误

本篇指南围绕开源 Agent 编排项目 ECC（Everything Claude Code）中的 /cpp-build 命令展开，讲解如何让 Agent 在 cmake --build 失败、链接器报错、模板实例化失败或拉取变更后构建被破坏时，按"最小改动、逐条修复、逐次验证"的纪律性流程恢复构建。读完本文，你将掌握该命令的完整工作流、底层 cpp-build-resolver Agent 的诊断策略与收手条件，以及如何与 /cpp-test、/cpp-review 衔接成一套闭环的 C++ 质量保障流程。

命令定位：一条"构建急救"命令

/cpp-build（全称 C++ Build and Fix）是 ECC 仓库中专门用于修复 C++ 构建错误的命令。它在命令入口处以 commands/cpp-build.md 定义，作用是唤起 cpp-build-resolver 这个专项 Agent，对编译错误、CMake 配置问题和链接问题进行增量式、外科手术式的最小修复。

与 /cpp-review（全面代码评审）和 /cpp-test（TDD 测试驱动开发）不同，/cpp-build 的目标非常收敛：让代码重新编译、链接、通过测试，而不是重构或评审。它默认不承担架构改进职责，一切改动都服务于"恢复绿色构建"这一单一目标。

从底层看，真正的执行实体定义在 agents/cpp-build-resolver.md，其声明的职责包括：

1. 诊断 C++ 编译错误；
2. 修复 CMake 配置问题；
3. 解决链接器错误（undefined references、multiple definitions）；
4. 处理模板实例化错误；
5. 修复 include 与依赖问题。

命令文档则把上述职责封装成一条用户可直接输入的斜杠命令（slash command），二者构成"用户入口 + Agent 大脑"的标准 ECC 命令架构。

命令执行的五个步骤

按 commands/cpp-build.md 的定义，/cpp-build 一旦被调用，会依次执行如下动作：

1. 运行诊断：依次执行 cmake --build、clang-tidy、cppcheck，采集第一手构建失败信息；
2. 解析错误：按文件分组、按严重程度排序，形成可执行的修复清单；
3. 增量修复：一次只处理一个错误；
4. 验证每次修复：每改动一处，立即重新构建，确认该错误消失且未引入新错误；
5. 输出总结报告：汇报已修复项与剩余问题。

这套流程在 agents/cpp-build-resolver.md 的 Resolution Workflow 中有更紧凑的循环表述：

1. cmake --build build    -> Parse error message
2. Read affected file     -> Understand context
3. Apply minimal fix      -> Only what's needed
4. cmake --build build    -> Verify fix
5. ctest --test-dir build -> Ensure nothing broke

即：构建 → 解析错误 → 阅读受影响文件 → 最小修复 → 重建验证 → 跑测试确认无回归，随后进入下一个错误。

适用场景

命令文档明确列出，以下情况正是使用 /cpp-build 的时机：

• cmake --build build 构建失败并报错；
• 出现链接器错误（undefined references 未定义引用、multiple definitions 多重定义）；
• 模板实例化失败（template instantiation failures）；
• 头文件包含或依赖问题（include/dependency issues）；
• 拉取他人变更后构建被破坏（After pulling changes that break the build）。

从使用习惯看，/cpp-build 与 cpp-test、cpp-review 构成闭环：/cpp-test 保证测试先行且通过，/cpp-build 负责在编译/链接环节"排障"，/cpp-review 在提交前做质量把关。典型的调用链是"先 /cpp-test 验证 → 构建出错则 /cpp-build 修复 → 提交前 /cpp-review"，这与 commands/cpp-test.md 中"Run tests after build succeeds"以及 commands/cpp-review.md 中"Use /cpp-build if build errors occur"的互相引用完全吻合。

命令执行的诊断工具集

/cpp-build 在诊断阶段会依次运行以下命令（可原样在命令行复现）：

# CMake configure
cmake -B build -S .

# Build
cmake --build build 2>&1 | head -100

# Static analysis (if available)
clang-tidy src/*.cpp -- -std=c++17
cppcheck --enable=all src/

补充说明各命令在本流程中的角色：

• cmake -B build -S .：在 build 目录执行源码目录（当前目录）的 CMake 配置，负责生成构建系统；
• cmake --build build 2>&1 | head -100：触发实际编译与链接，管道截取前 100 行输出，既控制日志量，也避免超长错误淹没上下文；
• clang-tidy 与 cppcheck：静态分析工具，用于在编译错误之外发现隐患（若环境未安装，工具链应能优雅降级）。

agents/cpp-build-resolver.md 中给出了带降级处理的版本，更贴合真实 Agent 执行环境：

cmake --build build 2>&1 | head -100
cmake -B build -S . 2>&1 | tail -30
clang-tidy src/*.cpp -- -std=c++17 2>/dev/null || echo "clang-tidy not available"
cppcheck --enable=all src/ 2>/dev/null || echo "cppcheck not available"

注意 Agent 版本特意把 clang-tidy/cppcheck 标注为"not available"时静默跳过，说明这两项属于增强诊断，而非构建恢复的硬性前置。

完整实战会话示例

命令文档给出了一个贯穿始终的实战示例：Agent 在一个 C++ 项目上执行 /cpp-build，从发现 3 个错误到逐一修复、最终测试全绿。以下完整继承该会话并补充必要注释。

初始诊断：构建失败，共发现 3 个错误。

$ cmake --build build
src/service/user.cpp:25:15: error: use of undeclared identifier 'UserRepository'
src/handler/api.cpp:42:9: error: no matching function for call to 'process'
src/handler/api.cpp:58:1: error: non-void function does not return a value

Errors found: 3

Fix 1：未声明的标识符（Undeclared Identifier）

• 位置：src/service/user.cpp:25
• 根因：缺少头文件包含（Missing include）
• 修复：补上对应 include

// Added include
#include "repository/user_repository.hpp"

$ cmake --build build
# 2 errors remaining

修复后重新构建，剩余错误降为 2 个。

Fix 2：没有匹配的函数调用（No Matching Function）

• 位置：src/handler/api.cpp:42
• 根因：实参类型与函数签名不匹配
• 修复：对参数做显式类型转换

// Changed
process(params.get("count"));
// To
process(std::stoi(params.get("count")));

$ cmake --build build
# 1 error remaining

Fix 3：非 void 函数缺少返回值（Missing Return）

• 位置：src/handler/api.cpp:58
• 修复：为 getUser 补齐 std::optional<User> 的所有返回路径

std::optional<User> getUser(const std::string& id) {
    if (id.empty()) {
        return std::nullopt;
    }
    auto user = findUser(id);
    // Added missing return
    return user;
}

$ cmake --build build
# Build successful!

三个错误依次清零，构建恢复成功。

最终验证：构建通过后执行测试套件，确认修复没有引入回归。

$ ctest --test-dir build --output-on-failure
Test project build
    1/5 Test #1: unit_tests ........   Passed    0.02 sec
    2/5 Test #2: integration_tests    Passed    0.15 sec
All tests passed.

总结报告：以指标表形式输出会话成果。

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

Build Status: PASS: SUCCESS

这个会话完整演示了"一次只修一个错误、每步重建验证、最后跑测试确认"的纪律。底层 Agent 文档要求的输出格式也与之一致——每处修复以 [FIXED] 标注位置、错误、修复动作与剩余错误数：

[FIXED] src/handler/user.cpp:42
Error: undefined reference to `UserService::create`
Fix: Added missing method implementation in user_service.cpp
Remaining errors: 3

最终以一行状态行收尾：Build Status: SUCCESS/FAILED | Errors Fixed: N | Files Modified: list。

常见错误速查表

命令文档归纳了 C++ 构建中最高频的 8 类错误及其典型修复路径，实际使用时可作为速查字典：

Error	Typical Fix
undeclared identifier	Add #include or fix typo
no matching function	Fix argument types or add overload
undefined reference	Link library or add implementation
multiple definition	Use inline or move to .cpp
incomplete type	Replace forward decl with #include
no member named X	Fix member name or include
cannot convert X to Y	Add appropriate cast
CMake Error	Fix CMakeLists.txt configuration

agents/cpp-build-resolver.md 在此基础上补充了 "Cause / Fix" 双列结构，把错误成因与对策拆得更细，可供对照加深理解：

Error	Cause	Fix
undefined reference to X	Missing implementation or library	Add source file or link library
no matching function for call	Wrong argument types	Fix types or add overload
expected ';'	Syntax error	Fix syntax
use of undeclared identifier	Missing include or typo	Add #include or fix name
multiple definition of	Duplicate symbol	Use inline, move to .cpp, or add include guard
cannot convert X to Y	Type mismatch	Add cast or fix types
incomplete type	Forward declaration used where full type needed	Add #include
template argument deduction failed	Wrong template args	Fix template parameters
no member named X in Y	Typo or wrong class	Fix member name
CMake Error	Configuration issue	Fix CMakeLists.txt

观察上表可以发现一个共同规律：绝大多数编译期错误都能追溯到 include 缺失、命名错误或类型不匹配，而链接期错误则基本指向"缺少实现文件或链接库"。这也是 Agent 在动手前先运行静态分析、按类别归因的原因。

CMake 专项排障手段

当问题出在 CMake 配置层而非源码层时，Agent 文档给出了三条递增的排障命令：

cmake -B build -S . -DCMAKE_VERBOSE_MAKEFILE=ON
cmake --build build --verbose
cmake --build build --clean-first

逐一解释其用途：

• -DCMAKE_VERBOSE_MAKEFILE=ON 与 --verbose：让 Make/Ninja 打印每条实际执行的编译/链接命令（含头文件路径、宏、链接库），用于排查"明明链接了却报 undefined reference"这类隐蔽问题；
• --clean-first：先清理目标再全量重建，用于排除"陈旧产物导致的假错误"——例如目标文件与最新头文件不同步、符号表过期等场景。

修复策略与原则

命令文档将修复顺序明确固定为优先级队列：

1. 编译错误优先——代码必须能编译（Compilation errors first）；
2. 链接错误其次——解决未定义引用（Linker errors second）；
3. 警告最后——用 -Wall -Wextra 清理警告（Warnings third）；
4. 一次只修一处——每处改动都单独验证（One fix at a time）；
5. 最小改动——只修错误，不做重构（Minimal changes, don't refactor, just fix）。

agents/cpp-build-resolver.md 的 Key Principles 对第 5 条做了更严格的限定，可视为 Agent 的行为红线：

• 只做外科手术式修复——不要借机重构；
• 未经批准，绝不使用 #pragma 压制警告；
• 除非确有必要，绝不修改函数签名；
• 修根因，而非掩盖症状（Fix root cause over suppressing symptoms）；
• 一次一个修复，每次修复后验证。

这套原则与 ECC 提供的 C++ 编码规范一脉相承：技能文档 skills/cpp-coding-standards/SKILL.md 以 C++ Core Guidelines 为蓝本，强调类型安全（P.4）、资源安全（R.1 RAII）、不可变性优先（Con.1）与最小复杂度（Per.4/5）。因此 cpp-build-resolver 在修复时会倾向于给出符合这些规范的最小补丁，例如优先使用 RAII/智能指针、nullptr 而非 0、enum class 等；若一个 bug 的根因属于规范系统性违规，Agent 通常会止步并报告，而不是越界重写。

停止条件：什么情况下 Agent 会停手上报

增量修复并非无限循环。命令文档规定，出现以下情况时 Agent 会停止修复并主动上报：

• 同一错误连续尝试 3 次仍然存在；
• 修复引入了更多新错误；
• 问题需要架构级改动才能解决；
• 缺少外部依赖（例如第三方库未安装、工具链缺失）。

agents/cpp-build-resolver.md 的表述略有收敛但本质一致：

• 同一错误 3 次修复尝试后依然存在；
• 修复引入的错误多于解决掉的错误；
• 错误超出范围、需要架构级变更。

这四条停止条件非常关键——它们界定了 Agent 的能力边界：/cpp-build 是"手术刀"而不是"重建队"，一旦触及架构决策或外部环境短板，正确的动作是把现场交给开发者或切换到更宏观的命令，而不是无限试错消耗预算。

与相邻命令的技能编排

命令文档在文末给出三条关联入口，构成了完整的 C++ 工作流闭环：

• /cpp-build 修复构建错误；
• /cpp-test 在构建成功后运行测试（其 TDD 循环 RED → GREEN → REFACTOR 与 GoogleTest/CTest/gcov 配合，见 commands/cpp-test.md）；
• /cpp-review 在实现完成后做代码评审（按 CRITICAL/HIGH/MEDIUM 分级，见 commands/cpp-review.md）；
• verification-loop 技能则提供覆盖上述环节的全量验证循环。

推荐的使用节奏是：新功能走 /cpp-test 的 TDD 流程 → 构建环节交给 /cpp-build 兜底排障 → 合并前用 /cpp-review 把关内存安全与现代 C++ 用法。三者互相引用、职责互补，对应仓库中 COMMANDS-QUICK-REF.md 对 /cpp-build 的定位描述——"Fix C++ CMake and linker problems"。

小结

/cpp-build 是 ECC 在 C++ 工程质量链上的"最后一公里"保障：它把易失控的"改到能编译为止"行为，收敛为先诊断、后排序、一次一修、逐次验证、明确停手的可预期流程。其命令定义见 commands/cpp-build.md，执行实体为 agents/cpp-build-resolver.md，配套的修复质量底线可参考 skills/cpp-coding-standards/SKILL.md。无论你是在 CI 管道里让 Agent 自动排障，还是在本地使用斜杠命令手动恢复被破坏的构建，这套"编译错误 → 链接错误 → 警告"的优先级与"3 次即停"的止损机制，都值得直接复用到你自己的 C++ 工作流中。