用 /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是 ECC（Agent 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的正文字数不多，但提炼出了一条五步修复协议，每一步都是可执行命令或明确的动作：

1. 运行类型检查：执行npx tsc --noEmit；
2. 收集全部错误：不放过任何一条报错，作为后续逐修的清单；
3. 逐一修复：对每个错误做最小改动；
4. 验证每个修复：确认本次改动没有引入新错误；
5. 最终复核：确认所有错误已解决。

这条「先全量、后增量」的顺序非常关键：如果只盯着第一条报错修，往往会在连环错误里反复打转。先拿到完整错误清单，才能判断哪些是根因、哪些只是根因引发的连带报错，避免重复劳动。

行为边界：DO 与 DON'T

协议最核心的约束是「只修错，不优化」。原命令文件将其写成两条清单：

DO（允许）：

• 用正确的类型修复类型错误；
• 补充缺失的 import；
• 修复语法错误；
• 做最小改动；
• 保持既有行为不变；
• 每次改动后运行tsc --noEmit。

DON'T（禁止）：

• 重构代码；
• 新增功能；
• 变更架构；
• 使用any类型（除非绝对必要）；
• 添加@ts-ignore注释；
• 修改业务逻辑。

这套边界的本质是把「修构建」与「改代码」两种动作解耦：构建修复追求的是以尽可能小的 diff 让管线恢复绿色，任何重构、功能与架构改动都会放大 diff、拉长评审，并显著提高引入新缺陷的概率。any与@ts-ignore被明令禁止，是因为它们会永久性地削弱类型检查能力——它们是「消灭报错」而不是「修复错误」。

常见错误快速修复对照表

命令文件内置了 TypeScript 最常见的五类报错与对应修复手段：

这些并不是孤立条目。对照 resolver 智能体全文（见下文），其Common Fixes表补充了更细的「症状 → 处方」对，可一并作为排查手册使用，例如：implicitly has 'any' type→ 加类型标注；Hook called conditionally→ 把 Hooks 移到顶层；'await' outside async→ 补async关键字；泛型约束失败 → 补extends { ... }。两张表叠加后基本覆盖了从类型推断、空值收窄到模块解析、React Hooks 规则的大部分日常报错。

修复完成的验证闭环

命令文件规定，修复结束后必须跑完三步才算真正完成：

1. npx tsc --noEmit—— 应显示 0 个错误；
2. npm run build—— 应成功；
3. 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 用于把编译期检查不到的规则性问题也纳入视野（但它们属于第三优先级，见下）。

优先级分级

这一分级告诉 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-resolver（"Fix build/type errors"）；
• COMMANDS-QUICK-REF.md 提供速查入口：构建坏了？→/build-fix；
• docs/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 会话是怎样的

把上述所有机制串起来，一次标准会话大致长这样：

1. 开发者在build（ECC 默认主 agent，见 .opencode/opencode.json 的default_agent与agent.build）中迭代代码，编辑.ts文件后触发 strict 档 TypeScript 钩子，会话内出现类型告警；
2. 主 agent 判断需要系统性修复，调用/build-fix <报错文件或现象>；
3. OpenCode 将命令模板与$ARGUMENTS拼装后，委派给build-error-resolver子代理；
4. resolver 先执行npx tsc --noEmit --pretty（必要时加--incremental false）收集全量错误，按 CRITICAL/HIGH/MEDIUM 分级；
5. 对每个错误做最小修复（补类型标注、加空值检查、修 import、修签名……），每修一条就重跑一次tsc --noEmit确认没有引入新错误；
6. 全部类型错误清零后，依次执行npm run build与npm test，确认构建成功且测试不受影响；
7. 若问题不在类型而在依赖或缓存，则按需使用快速恢复手段（清理.next/缓存、重装依赖）；
8. 若构建错误背后其实是需要重构或改架构的深层问题，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