用 /build-fix 让 ECC 构建重新变绿：Agent Harness 下 TypeScript 与构建错误的最小化修复协议

用 /build-fix 让 ECC 构建重新变绿Agent Harness 下 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 操作系统在 OpenCode 工作流中提供的一个子任务命令它把「修构建、修类型错误」这件事从随意的聊天式操作收敛为一条可重复、可验证的协议先跑tsc --noEmit全量收集错误再以最小 diff 逐个修复并验证。读完本文你将掌握该命令的完整执行逻辑、它背后的build-error-resolver智能体规范、按语言拆分的 resolver 家族以及仓库中配套的钩子与 CI 校验机制从而在任何 Agent Harness 项目中复现同样的「改一处、验一次、最终全绿」节奏。/build-fix 是什么一条绑定专属智能体的 subagent 命令在 ECC 仓库中/build-fix的完整定义位于 .opencode/commands/build-fix.md。它不是一个普通的静态提示词而是一个带元数据、被 OpenCode 注册为可执行 slash command 的命令文件--- description: Fix build and TypeScript errors with minimal changes agent: build-error-resolver subtask: true ---三个 frontmatter 字段各有明确作用description命令的能力声明同时用于工具选择与命令列表展示明确指出其职责是「以最小改动修复构建与 TypeScript 错误」agent声明本命令由build-error-resolver智能体执行。这意味着触发命令后主 agent 会委派delegate给这个专职 resolver 子代理subtask: true标记为子任务模式resolver 只对本命令上下文负责不接管整个会话的主线程逻辑。这条注册关系在 .opencode/opencode.json 的command段中显式落地第 339–344 行与文件名一一对应build-fix: { description: Fix build and TypeScript errors with minimal changes, template: {file:commands/build-fix.md}\n\n$ARGUMENTS, agent: build-error-resolver, subtask: true }其中template会把命令文件全文作为提示词注入并把用户在/build-fix 内容中输入的自由参数拼接到$ARGUMENTS位置——这正是「Fix build and TypeScript errors with minimal changes: $ARGUMENTS」一句的来历既能按模板执行又能针对用户给出的具体报错或文件定向处理。命令体本身被设计成通用模板因此可以复用于仓库里的任何 TypeScript/Node 工程本仓库的npm生态与scripts/、tests/均为 JS/TS 实现非常贴合该命令的适用场景。核心任务协议先收集、再逐修、后验证/build-fix的正文字数不多但提炼出了一条五步修复协议每一步都是可执行命令或明确的动作运行类型检查执行npx tsc --noEmit收集全部错误不放过任何一条报错作为后续逐修的清单逐一修复对每个错误做最小改动验证每个修复确认本次改动没有引入新错误最终复核确认所有错误已解决。这条「先全量、后增量」的顺序非常关键如果只盯着第一条报错修往往会在连环错误里反复打转。先拿到完整错误清单才能判断哪些是根因、哪些只是根因引发的连带报错避免重复劳动。行为边界DO 与 DONT协议最核心的约束是「只修错不优化」。原命令文件将其写成两条清单DO允许用正确的类型修复类型错误补充缺失的 import修复语法错误做最小改动保持既有行为不变每次改动后运行tsc --noEmit。DONT禁止重构代码新增功能变更架构使用any类型除非绝对必要添加ts-ignore注释修改业务逻辑。这套边界的本质是把「修构建」与「改代码」两种动作解耦构建修复追求的是以尽可能小的 diff 让管线恢复绿色任何重构、功能与架构改动都会放大 diff、拉长评审并显著提高引入新缺陷的概率。any与ts-ignore被明令禁止是因为它们会永久性地削弱类型检查能力——它们是「消灭报错」而不是「修复错误」。常见错误快速修复对照表命令文件内置了 TypeScript 最常见的五类报错与对应修复手段报错修复Type X is not assignable to type Y补充正确的类型标注Property X does not exist把属性加入 interface或修正属性名Cannot find module X安装依赖包或修正 import 路径Argument of type X is not assignable做类型转换cast或修正函数签名Object is possibly undefined增加空值检查或可选链optional chaining这些并不是孤立条目。对照 resolver 智能体全文见下文其Common Fixes表补充了更细的「症状 → 处方」对可一并作为排查手册使用例如implicitly has any type→ 加类型标注Hook called conditionally→ 把 Hooks 移到顶层await outside async→ 补async关键字泛型约束失败 → 补extends { ... }。两张表叠加后基本覆盖了从类型推断、空值收窄到模块解析、React Hooks 规则的大部分日常报错。修复完成的验证闭环命令文件规定修复结束后必须跑完三步才算真正完成npx tsc --noEmit—— 应显示 0 个错误npm run build—— 应成功npm test—— 测试仍应通过。第三步尤其容易被忽略类型全绿只代表编译期正确不代表行为正确。由于协议禁止修改业务逻辑测试应当「原样通过」若测试失败通常意味着某个修复越过了行为边界需要回退重做而不是继续叠加改动。命令背后的智能体build-error-resolver/build-fix只是入口真正的执行主体是 agents/build-error-resolver.md 中定义的build-error-resolver智能体。它在 OpenCode 侧同样注册于 .opencode/opencode.json第 95–105 行mode: subagent、拥有read/write/edit/bash四类工具、默认加载prompts/agents/build-error-resolver.txt作为角色提示词。职责边界与六项核心能力其角色定位是「以最小改动让构建通过的专业 resolver」六项核心职责包括TypeScript 错误解析类型推断、泛型约束问题、构建错误修复编译失败、模块解析、依赖问题import 错误、缺包、版本冲突、配置错误tsconfig、webpack、Next.js 配置、最小 diff 原则、以及「绝不重构、绝不重新设计」的约束。诊断命令集智能体规范给出了比命令正文更完整的诊断工具箱npx tsc --noEmit --pretty npx tsc --noEmit --pretty --incremental false # 展示全部错误 npm run build npx eslint . --ext .ts,.tsx,.js,.jsx--incremental false用于绕过增量缓存确保拿到的是完整错误面而非陈旧结果eslint 用于把编译期检查不到的规则性问题也纳入视野但它们属于第三优先级见下。优先级分级级别症状动作CRITICAL构建完全损坏、dev server 起不来立即修复HIGH单个文件失败、新代码存在类型错误尽快修复MEDIUMLinter 警告、已弃用 API有余力时处理这一分级告诉 resolver 不要被告警噪声带偏节奏先救活构建再清理高价值类型错误最后才轮到警告。快速恢复手段规范同时保留了「兜底三连」用于缓存或依赖本身损坏的场景# 清空全部缓存后重建 rm -rf .next node_modules/.cache npm run build # 重装依赖 rm -rf node_modules package-lock.json npm install # 修复 ESLint 可自动修复项 npx eslint . --fix注意这些手段应作为最后手段审慎使用删package-lock.json会改变依赖解析结果使用前应确认 lockfile 本身不是被特意锁定的版本基线。成功度量指标一次合格的修复会话应同时满足npx tsc --noEmit退出码为 0、npm run build成功、未引入新错误、改动行数小于受影响文件的 5%、测试仍然通过。「改动少于受影响文件 5%」把「最小 diff」从口号变成可量化的验收标准。何时不要用 build-error-resolver协议还明确划定了职责边界把不同类型的任务交给不同专职智能体代码需要重构 → 交给refactor-cleaner需要架构调整 → 交给architect需要新功能 → 交给planner测试失败 → 交给tdd-guide安全问题 → 交给security-reviewer。这正是 ECC 多智能体编排的思路每个 agent 都是单点专家靠「When NOT to Use」把任务精准路由到正确的专家手中而不是让一个 agent 包打天下。不止于 TS按语言拆分的 build resolver 家族/build-fix是面向 TypeScript/JavaScript 生态的通用构建修复命令对于其他语言栈ECC 在.opencode/commands/与opencode.json中维护了一族结构完全同构的 resolver 命令/go-build.opencode/commands/go-build.md→ 绑定go-build-resolver流程为go build ./...→go vet ./...→ 逐错修复覆盖 import 未使用、类型不匹配、undefined: identifier、vet 的 printf 格式告警等/rust-build.opencode/commands/rust-build.md→ 绑定rust-build-resolver流程为cargo check→cargo clippy -- -D warnings→ 逐错修复重点处理借用检查、类型不匹配、缺失 import、生命周期与 trait 未实现错误。这些命令与/build-fix共享同一套 frontmatter 骨架description/agent/subtask并复用完全相同的边界原则「只修错误不做改进以最小改动让构建变绿」。在编排层ECC 的plan-orchestrateskill见 skills/plan-orchestrate/SKILL.md进一步定义了路由规则构建类链路优先匹配lang-build-resolver当语言无法判定时则回退到通用的build-error-resolver——也就是说/build-fix本身就是这条 fallback 链的收底角色。根目录 agents/build-error-resolver.md 还设定了默认模型model: sonnet并内置了 Prompt Defense Baseline防提示注入、防泄露、防越权说明该角色既被当作普通子代理使用也被当作可能接触不可信输入的角色加以加固。仓库配套机制钩子、CI 与命令索引编辑后自动触发类型检查的插件钩子/build-fix是被动触发用户主动调用的修复手段而 ECC 的 OpenCode 插件还提供主动预警机制。在 .opencode/plugins/ecc-hooks.ts 的第 213–257 行tool.execute.after钩子会在edit工具修改了.ts/.tsx文件后自动执行npx tsc --noEmit若类型检查通过记录TypeScript check passed若失败记录前 5 条错误用于会话内提醒。该钩子受hookEnabled(post:edit:typecheck, [strict])控制属于 strict 档位行为——这意味着在严格模式下Agent 每次改完 TS 文件都会立刻收到类型反馈把「改完才发现错」的滞后窗口压缩到几乎为零而tsc报错后下一步的自然选择就是把问题交给/build-fix走正式修复协议。CI 对命令文件本身的校验命令文件不是写完就完事仓库的 CI 会对它们做静态校验。scripts/ci/validate-commands.js 会检查每个命令 Markdown 文件非空、frontmatter 格式合法解析正文中所有/xxx形式的跨命令引用该校验器在注释中特别点名/build-fix作为示例确认被引用命令真实存在校验agents/name.md、skills/dir/引用是否存在。该校验器被挂在 package.json 的test脚本链开头node scripts/ci/validate-commands.js与validate-agents.js、validate-skills.js、validate-hooks.js等共同构成仓库的「文档即代码」质量门禁。命令在文档与工作流中的索引位置根目录 CLAUDE.md 第 49 行把/build-fix列入命令清单「Fix build errors」AGENTS.md 第 151 行给出构建故障排除建议使用build-error-resolver智能体 → 分析错误 → 增量修复 → 每次修复后验证docs/COMMAND-AGENT-MAP.md 明确映射/build-fix → build-error-resolverFix build/type errorsCOMMANDS-QUICK-REF.md 提供速查入口构建坏了→/build-fixdocs/COMMAND-REGISTRY.json 的命令注册表中同样登记了build-fix及其路径commands/build-fix.md在/plan、/tdd、/python-review等命令的工作流正文里如 commands/plan.md也都预留了「构建出错时转用/build-fix」的接力指引。此外manifests/install-components.json 将该命令背后的agent:build-error-resolver作为可安装组件收录说明通过ecc-install安装规则与智能体时该修复角色会随配置一起分发到目标项目。一次典型的 /build-fix 会话是怎样的把上述所有机制串起来一次标准会话大致长这样开发者在buildECC 默认主 agent见 .opencode/opencode.json 的default_agent与agent.build中迭代代码编辑.ts文件后触发 strict 档 TypeScript 钩子会话内出现类型告警主 agent 判断需要系统性修复调用/build-fix 报错文件或现象OpenCode 将命令模板与$ARGUMENTS拼装后委派给build-error-resolver子代理resolver 先执行npx tsc --noEmit --pretty必要时加--incremental false收集全量错误按 CRITICAL/HIGH/MEDIUM 分级对每个错误做最小修复补类型标注、加空值检查、修 import、修签名……每修一条就重跑一次tsc --noEmit确认没有引入新错误全部类型错误清零后依次执行npm run build与npm test确认构建成功且测试不受影响若问题不在类型而在依赖或缓存则按需使用快速恢复手段清理.next/缓存、重装依赖若构建错误背后其实是需要重构或改架构的深层问题resolver 会停手并把任务转交给refactor-cleaner、architect等专职 agent而不是越界硬修。使用 /build-fix 前需要知道的边界最后再次强调该命令的前提条件与适用限制适用对象TypeScript/JavaScript 项目的编译、类型、模块解析与基础构建配置错误使用前提是项目根目录可运行npx tsc、npm run build与npm test非适用对象需要重构、架构演进、新功能开发的诉求——应分别改用 ECC 的refactor-cleaner、architect、planner对应流程可量化的完成标准tsc --noEmit退出码 0、npm run build成功、测试通过、改动行数控制在受影响文件的 5% 以内。把/build-fix看作一条「纪律化」的修复通道而不是一个万能改错工具它用显式协议约束了 agent 的行为边界用验证闭环保证每次改动都可回滚、可审计。对任何希望把「让 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），仅供参考