ECC 构建修复指南：用 /build-fix 分步解决 TypeScript 与构建错误
【免费下载链接】ECCThe 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
/build-fix是 ECC（Agent Harness 性能优化系统）内置的构建错误修复命令，面向 Claude Code、Codex、Opencode、Cursor 等 Agent 工作流，指导 Agent 以"一次只修一个错误"的渐进方式修复 TypeScript 与构建错误。本文以 docs/ja-JP/commands/build-fix.md 为核心骨架，结合 commands/build-fix.md 英文原版与仓库源码，完整讲解该命令的执行流程、停止条件、恢复策略及其背后的工程质量保障机制，读完即可在任意支持 ECC 命令的 Agent 会话中安全、可复现地使用它修复构建失败。
命令定位：ECC 命令体系中的构建修复入口
在 ECC 的命令体系中，/build-fix属于"构建与错误修正"（ビルド & エラー修正）类别。根据 docs/ja-JP/commands/README.md，该类别与代码质量、测试验证、计划实现等命令并列，是开发工作流中的关键一环：
/build-fix：修复构建错误/go-build：解决 Go 构建错误/go-test：执行 Go 测试
在 docs/ja-JP/COMMANDS-QUICK-REF.md 的快速决策指南中，/build-fix的定位十分明确——"ビルドが壊れた？ → /build-fix"（构建坏了？→ 用 /build-fix）。同时该文档还揭示了它的一个重要特性："ビルドエラーを検出して修正 — 適切なビルドリゾルバーエージェントに自動的に委任"（检测并修复构建错误——自动委派给合适的构建解析器 Agent）以及"言語を自動検出してビルドエラーを修正"（自动检测语言后修复构建错误）。
从命令文件本身来看，英文原版 commands/build-fix.md 的 frontmatter 给出了精确定义：
description: Detect the project build system and incrementally fix build/type errors with minimal safe changes.即：检测项目的构建系统，并以最小、安全的最小变更（minimal safe changes）增量修复构建与类型错误。
执行总览：五步渐进式修复流程
命令的核心执行流程分为五个阶段，其逻辑是"检测 → 解析 → 单点修复 → 护栏拦截 → 汇总报告"，每一步都要求可验证、可回退：
- 运行构建：执行
npm run build或pnpm build - 解析错误输出：
- 按文件（ファイル別）分组
- 按严重度（重大度）排序
- 逐错误处理（对每个错误依次执行）：
- 显示错误上下文（前后 5 行）
- 解释问题
- 提出修正方案
- 应用修正
- 重新运行构建
- 确认错误是否已解决
- 满足以下任一条件时停止：
- 修正引入了新的错误
- 同一错误在 3 次尝试后仍然存在
- 用户请求暂停
- 输出汇总：
- 已修复的错误
- 剩余的错误
- 新引入的错误
命令文档在最后强调了一条最重要的安全铁律：安全起见，一次只修复一个错误（安全のため、一度に 1 つのエラーのみを修正してください！）。
第一步：检测构建系统并运行构建
在执行修复前，首先需要识别项目使用的构建工具，并运行对应的构建命令。英文原版文档提供了一张构建系统检测映射表，覆盖了主流语言与构建工具：
| 检测依据（Indicator） | 构建命令（Build Command） |
|---|---|
含build脚本的package.json | npm run build或pnpm build |
tsconfig.json（纯 TypeScript 项目） | npx tsc --noEmit |
Cargo.toml | cargo build 2>&1 |
pom.xml | mvn compile |
build.gradle | ./gradlew compileJava |
go.mod | go build ./... |
pyproject.toml | python -m compileall -q .或mypy . |
注意事项：
- 构建命令的选取以仓库实际内容为准。以 ECC 自身为例，其 package.json 中定义了
build:opencode（执行node scripts/build-opencode.js）等脚本，说明"运行项目自身的 build 脚本"是最高优先级的做法。 - 当语言与构建工具不明确时，英文原版描述的"自动检测语言"能力会先识别项目类型（依据
package.json、tsconfig.json、Cargo.toml、go.mod等标志文件），再选择对应的构建命令。 - 构建失败时的输出要完整捕获（尤其要保留 stderr），这是下一步错误解析的输入。
第二步：解析并分组错误输出
拿到构建输出后，不要立刻动手改代码，而是先做结构化分析：
- 运行构建命令并捕获 stderr；
- 按文件路径分组错误——同一文件内的多个错误往往具有相同的根因（例如缺失 import、错误的类型定义），集中处理效率更高；
- 按依赖顺序排序——先修 import 错误与类型错误，再处理逻辑错误。理由很直接：类型/导入错误会引发连锁报错，先把"上游"错误修掉，许多"下游"报错会自动消失；
- 统计错误总数——用于进度追踪，也便于在汇总阶段对比修复前后差异。
这一步对应日语文档中的"按文件分组、按严重度排序"，是确保后续修复不盲目、可量化的关键。
第三步：逐个错误修复循环
对于每一个错误，命令要求按以下固定节奏处理，且每步之间都必须有明确产出：
- 读取文件：用 Read 工具查看错误上下文（日语版规定前后 5 行；英文原版为 10 行左右）。上下文用于判断错误是孤立问题还是更大范围问题的一部分；
- 诊断：定位根本原因——是缺失 import、类型不匹配，还是语法错误？
- 最小化修复：用 Edit 工具实施能解决该错误的最小改动；
- 重新运行构建：验证该错误已消失，且没有引入新错误；
- 处理下一个错误：继续剩余错误，直到构建通过或触发停止条件。
英文原版特别强调"Prefer minimal diffs over refactoring"（优先最小差异，而非重构）。这一原则与日语文档"一次只修一个错误"的安全约束互为表里：改动越小，越容易定位回归来源；一次只修一个，才能准确判断每次改动与错误消失之间的因果关系。
第四步：护栏与停止条件
命令明确规定了停止条件，避免 Agent 陷入无意义的反复试错或越权改动。出现以下任一情况即应停止并向用户报告：
- 修正引入了比解决掉的更多的错误（fix introduces more errors than it resolves）；
- 同一错误在 3 次尝试后仍然存在——英文原版解释这"很可能是一个更深层的问题"（likely a deeper issue）；
- 修复需要架构级变更（architectural changes），而不仅是构建修复；
- 构建错误源于缺失依赖（missing dependencies），需要执行
npm install、cargo add等依赖安装操作。
日语版给出的三条停止条件（引入新错误、3 次尝试后仍存在、用户请求暂停）是英文原版护栏的子集，两者共同构成"不硬闯、不扩大破坏面"的执行边界。
第五步：输出修复汇总
修复循环结束后（无论是构建通过还是触发停止条件），必须输出结构化汇总，至少包含四类信息：
- 已修复的错误（附文件路径，便于复核）；
- 剩余的错误（如有）；
- 新引入的错误（英文原版要求应为零——should be zero）；
- 对未解决问题建议的下一步动作。
这保证了整个修复过程可审计：读者（或用户）可以基于文件路径快速核对每处改动，并对未解决的错误继续人工介入。
常见问题的恢复策略
英文原版还提供了一张"恢复策略"表，针对构建失败中最常见的几类问题给出标准动作，可用于在第三步诊断时快速匹配方案：
| 场景（Situation） | 动作（Action） |
|---|---|
| 模块/导入缺失（Missing module/import） | 检查包是否已安装；给出安装命令建议 |
| 类型不匹配（Type mismatch） | 阅读两端的类型定义；修正较窄的那一侧类型 |
| 循环依赖（Circular dependency） | 用依赖图定位环；建议提取公共部分 |
| 版本冲突（Version conflict） | 检查package.json/Cargo.toml中的版本约束 |
| 构建工具配置错误（Build tool misconfiguration） | 读取配置文件；与可工作的默认配置对比 |
源码佐证：命令文档为何可被 Agent 可靠执行
/build-fix之所以能被 Agent 稳定解析和执行，离不开 ECC 对命令文件的工程化约束。仓库中的 scripts/ci/validate-commands.js 是专门校验命令 Markdown 文件的 CI 脚本，其职责包括：
- 非空校验：命令文件必须是可读的非空 Markdown，空文件直接报错；
- frontmatter 校验：要求以
---开头并闭合，frontmatter 行必须符合key: value格式，且 YAML 序列/映射值必须完整闭合（未闭合的[或{会被标记为错误）——这正是 commands/build-fix.md 顶部description字段能够被 /help 等机制读取的前提； - 交叉引用校验：代码块之外的
/command-name引用、agents/xxx.md引用、skills/xxx/引用都会被逐一验证是否存在，避免命令文档中出现悬空链接。
这意味着build-fix.md这样的命令文件不仅在语义上是给 Agent 的"操作 SOP"，在结构上也是经过 CI 强校验的合格资产，两者共同保证了命令行为的可预测性。
与其他命令的协同：完整的开发闭环
/build-fix并非孤立工具，它处于 ECC 开发工作流的中段。根据 docs/ja-JP/commands/README.md 的工作流编排：
- 开发工作流：
/plan（制定实现计划）→/tdd（测试驱动开发）→/code-review（质量审查）→/build-fix（修复构建错误）→/e2e（端到端测试）→/update-docs（更新文档）； - 调试工作流：
/verify（验证实现）→/code-review（质量检查）→/build-fix（修复错误）→/test-coverage（确认覆盖率）。
其中/verify命令（见 docs/ja-JP/commands/verify.md）执行"构建 → 类型 → Lint → 测试 → console.log 审计 → Git 状态"的完整验证链，构建失败时它会报告错误并停止——此时正是/build-fix的介入时机。此外，commands/react-build.md 中明确划定了职责边界：涉及 React 构建/打包器/运行时水合失败的场景使用/react-build，而不涉及 React 的纯 TypeScript 类型错误则使用/build-fix（通用版），并标注其为"generic build fixer (non-React)"。
小结：把构建修复变成可复现的工程流程
/build-fix的价值不在于"自动修好一切"，而在于把构建修复从随机的试错变成一条可重复、可验证、有护栏的工程流程：先检测构建系统并运行构建，再按文件与依赖顺序解析错误，然后以最小改动一次修复一个错误并立即复验，最后用明确的三条停止条件防止失控，并输出包含文件路径的修复汇总。配合 ECC 对命令文档的 CI 校验机制，以及/verify、/react-build等相邻命令的协同，它可以在 Claude Code、Codex、Opencode、Cursor 等任意支持 ECC 命令的 Agent 会话中，安全地帮助你从构建失败快速回到可继续开发的状态。
【免费下载链接】ECCThe 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
创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
