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是 ECCAgent 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.jsonnpm run build或pnpm buildtsconfig.json纯 TypeScript 项目npx tsc --noEmitCargo.tomlcargo build 21pom.xmlmvn compilebuild.gradle./gradlew compileJavago.modgo build ./...pyproject.tomlpython -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），仅供参考