ECC build-error-resolver 深度解析：最小 Diff 策略下的构建与 TypeScript 错误修复专家

ECC（Everything Claude Code）的 build-error-resolver 是一个专职“把构建变绿”的 Agent 定义：它只做最小化改动来消除 TypeScript 类型错误、编译失败、依赖冲突和配置错误，明确禁止重构与架构变更。本文以该文档为核心骨架，完整继承其诊断命令、修复工作流、常见错误速查表与成功指标，并结合仓库中 Kiro 侧 JSON 配置、Claude Code 侧 Agent 定义、OpenCode 侧提示词以及配套的质量门禁脚本，讲清楚这个 Agent 在多 Harness 环境中的落地方式与可复用的“最小 Diff”修错方法论。

一、Agent 定位：一个被严格约束的“救火队员”

build-error-resolver.md 的 YAML frontmatter 定义了它的身份边界：

---
name: build-error-resolver
description: Build and TypeScript error resolution specialist. Use PROACTIVELY when build fails or type errors occur. Fixes build/type errors only with minimal diffs, no architectural edits. Focuses on getting the build green quickly.
allowedTools:
  - read
  - write
  - shell
---

三个设计要点值得注意：

1. PROACTIVELY 触发语义：description 中要求“构建失败或类型错误出现时应主动使用”，这是给上层编排层看的信号——不需要用户点名，任何构建失败场景都应路由给该 Agent。
2. 最小化使命：正文第一句即定调——“Your mission is to get builds passing with minimal changes — no refactoring, no architecture changes, no improvements.”（用最小改动让构建通过，不重构、不改架构、不做改进）。
3. 工具白名单：只授予 read、write、shell 三类工具（对应 CLI 侧的 fs_read、fs_write、shell，见 build-error-resolver.json）。这与其职责高度匹配：读代码、改代码、跑诊断命令，不需要其他能力。

该 Agent 的职责边界在文档中以“Core Responsibilities”六条列出，本文后续工作流均围绕这六点展开：

职责	说明
TypeScript 错误修复	类型错误、推断问题、泛型约束
构建错误修复	编译失败、模块解析失败
依赖问题	import 错误、缺失包、版本冲突
配置错误	tsconfig、webpack、Next.js 配置问题
最小 Diff	用尽可能小的改动修错
不改架构	只修错误，不重新设计

二、诊断命令集：先把错误收集全

文档给出四条标准诊断命令，这是整个工作流的输入源：

npx tsc --noEmit --pretty
npx tsc --noEmit --pretty --incremental false   # Show all errors
npm run build
npx eslint . --ext .ts,.tsx,.js,.jsx

各命令的用途与适用前提：

• npx tsc --noEmit --pretty：只做类型检查、不产出文件，--pretty 输出可读性更好的彩色分组结果。适用于存在 tsconfig.json 的 TypeScript 项目。
• npx tsc --noEmit --pretty --incremental false：关闭增量编译，一次性显示全部错误而不是被增量缓存截断——文档特别标注 “Show all errors”，对应工作流第 1 步“Collect All Errors”的要求“捕获所有错误，而不是只看第一个”。
• npm run build：触发真实生产构建（如 Next.js 的 npm run build），验证构建管线整体可通。
• npx eslint . --ext .ts,.tsx,.js,.jsx：捕获 ESLint 可发现的静态问题，与类型检查互补。

补充说明：仓库中 quality-gate.sh 脚本执行了同一组检查的自动化版本——检测包管理器（pnpm/yarn/bun/npm）、依次运行 Build、npx tsc --noEmit 类型检查、Lint（Biome/ESLint/Ruff/golangci-lint 自动选择）、测试，最后以 Quality gate: PASSED / FAILED 收尾并以退出码 0/1 表示结果。build-error-resolver 修完错误后，用该脚本（或其 quality-gate hook）做最终验证正是闭环的自然选择。

三、三步修复工作流：收集、最小化修复、迭代至绿

文档定义的 Workflow 是整个 Agent 的方法论核心，完整继承如下。

第 1 步：Collect All Errors（收集全部错误）

• 运行 npx tsc --noEmit --pretty 获取全部类型错误；
• 分类（Categorize）：类型推断失败、缺失类型定义、import 错误、配置错误、依赖问题，五大类；
• 排序（Prioritize）：build-blocking（阻塞构建的）最先修，然后是类型错误，最后处理警告。

分类的意义在于：不同类别的修复手段完全不同（加类型注释 vs 装依赖 vs 改 tsconfig），混在一起修会导致“改一处炸三处”。

第 2 步：Fix Strategy（最小化修复策略）

对每一个错误执行固定的四拍循环：

1. 仔细阅读错误信息——搞清楚 expected type 与 actual type 的差异；
2. 寻找最小修复——类型注释、空值检查、import 修正三选其一，类型断言（type assertion）是最后手段（此点在 OpenCode 版提示词 中进一步明确为 “Use type assertion (last resort)”）；
3. 验证修复没有破坏其他代码——再次运行 tsc，确认没有引入新错误；
4. 迭代直到构建通过——一次修一个错误、每修一个就重新编译、并跟踪进度（X/Y errors fixed）。

这套“单点修复 + 全量复检”循环是防回归的关键：类型系统里一个错误常常是另一个错误的掩盖物（shadowing），批量盲改很容易顾此失彼。

第 3 步：Common Fixes 速查表

文档内置了一张“错误 → 修复”对照表，覆盖最高频的八类场景：

错误	修复
implicitly has 'any' type	添加类型注释
Object is possibly 'undefined'	可选链 ?. 或空值检查
Property does not exist	添加到 interface，或改用可选 ?
Cannot find module	检查 tsconfig paths、安装缺失包、或修正 import 路径
Type 'X' not assignable to 'Y'	解析/转换类型，或修正声明类型
Generic constraint	添加 extends { ... } 约束
Hook called conditionally	将 hooks 提升到组件顶层
'await' outside async	添加 async 关键字

其中五个高频模式在 OpenCode 侧的同名提示词 中附带了完整的前后对照代码，可作为速查表的实操展开：

模式 1：类型推断失败

// ERROR: Parameter 'x' implicitly has an 'any' type
function add(x, y) {
  return x + y
}

// FIX: Add type annotations
function add(x: number, y: number): number {
  return x + y
}

模式 2：Null/Undefined 错误

// ERROR: Object is possibly 'undefined'
const name = user.name.toUpperCase()

// FIX: Optional chaining
const name = user?.name?.toUpperCase()

// OR: Null check
const name = user && user.name ? user.name.toUpperCase() : ''

模式 3：缺失属性

// ERROR: Property 'age' does not exist on type 'User'
interface User {
  name: string
}
const user: User = { name: 'John', age: 30 }

// FIX: Add property to interface
interface User {
  name: string
  age?: number // Optional if not always present
}

模式 4：Import 错误

// ERROR: Cannot find module '@/lib/utils'
import { formatDate } from '@/lib/utils'

// FIX 1: Check tsconfig paths are correct
// FIX 2: Use relative import
import { formatDate } from '../lib/utils'
// FIX 3: Install missing package

模式 5：类型不匹配

// ERROR: Type 'string' is not assignable to type 'number'
const age: number = "30"

// FIX: Parse string to number
const age: number = parseInt("30", 10)

// OR: Change type
const age: string = "30"

注意模式 4 的三种修法优先级：先怀疑 tsconfig 的 paths 别名配置（最小代价），再退回相对路径，最后才考虑安装缺失包——这与“最小 Diff”总原则一致。

四、DO / DON'T：最小 Diff 的硬性边界

文档用两张清单把行为边界钉死，这是该 Agent 区别于“随手一改”的根本：

DO（允许做的）：

• 为缺失处添加类型注释
• 在需要处添加空值检查
• 修正 import/export
• 添加缺失依赖
• 更新类型定义
• 修正配置文件

DON'T（禁止做的）：

• 重构无关代码
• 改动架构
• 重命名变量（除非该命名本身导致错误）
• 添加新功能
• 改变逻辑流（除非正在修复错误）
• 优化性能或代码风格

这套约束的实际价值：构建修复发生在“代码已经写好”的上下文里，任何顺手的重构都会让 diff 膨胀、review 困难、回归风险上升。文档结尾的座右铭正是此意——“Fix the error, verify the build passes, move on. Speed and precision over perfection.”

五、优先级分级：何时必须立刻修

文档定义了三级优先级，决定了修复动作的紧迫程度：

级别	症状	动作
CRITICAL	构建完全损坏，dev server 起不来	立即修复
HIGH	单文件失败、新代码的类型错误	尽快修复
MEDIUM	Linter 警告、废弃 API	有条件时修复

这个分级的隐含逻辑是：CRITICAL 阻塞所有人的工作流，必须优先；MEDIUM 虽然不阻塞，但在 ECC 的体系里会由 quality-gate 钩子与 quality-gate.sh 脚本在提交前统一拦截——build-error-resolver 负责“把红变绿”，质量门禁负责“防止绿变红”。

六、Quick Recovery：三板斧快速恢复

当常规修复陷入僵局时，文档给出三组“核选项”：

# Nuclear option: clear all caches
rm -rf .next node_modules/.cache && npm run build

# Reinstall dependencies
rm -rf node_modules package-lock.json && npm install

# Fix ESLint auto-fixable
npx eslint . --fix

逐条解读：

1. 清缓存重建：Next.js 的 .next 目录与 node_modules/.cache 会累积陈旧的编译产物；当报错信息与实际源码对不上、或“改对了却还报错”时，清缓存往往是根因。注意这会丢失增量缓存，重建耗时更长，属于诊断性手段而非常规步骤。
2. 重装依赖：针对依赖树损坏、lockfile 与实际安装不一致的场景；package-lock.json 一并删除后重新解析版本，代价较高，应在清缓存无效后再用。
3. ESLint 自动修复：--fix 只处理可自动修复的规则（格式化、未使用变量等），能批量消灭 MEDIUM 级警告，不触碰业务逻辑。

七、成功指标：如何验收“修好了”

文档给出的验收标准是可量化、可脚本化的五条：

• npx tsc --noEmit 以退出码 0 结束；
• npm run build 成功完成；
• 未引入任何新错误；
• 改动行数最少（小于受影响文件的 5%）；
• 既有测试仍然全部通过。

其中“小于 5% 的受影响文件行数”是最具辨识度的指标，它把“最小 Diff”从口号变成了可检验的数字约束；“既有测试仍然全部通过”则与 ECC 仓库 testing.md 中 80% 覆盖率、TDD 的测试标准相呼应——修错不能以牺牲测试为代价。OpenCode 版提示词还额外提供了标准化的“Build Error Resolution Report”输出模板（初始错误数、修复数、每条错误的定位/根因/修复 diff/影响面），让每次修复都留下可追溯的记录。

八、何时不用它：ECC Agent 路由中的位置

文档的 “When NOT to Use” 一节把职责外溢的出口指向了 ECC 的其他专业 Agent，这实际是多 Agent 路由的边界声明：

• 需要重构 → 用 refactor-cleaner
• 需要架构变更 → 用 architect
• 需要新功能 → 用 planner
• 测试失败 → 用 tdd-guide
• 安全问题 → 用 security-reviewer

在 Kiro 侧 README 的 Agent 清单中，build-error-resolver 被描述为 “Build and TypeScript error resolution specialist. Fixes build/type errors with minimal diffs, no architectural changes.”，与 33 个 Agent 并列；该 README 的示例工作流（Example 8）还给出了标准用法：

# 1. Fix build errors with build-error-resolver
kiro-cli --agent build-error-resolver
> "Fix the TypeScript compilation errors"

此外，文档中的路由表指向的五个目标 Agent 在仓库中都有对应实现，例如 refactor-cleaner、security-reviewer、planner、tdd-guide，可在 docs/COMMAND-AGENT-MAP.md 中查看命令与 Agent 的完整映射。也就是说，build-error-resolver 不是一个孤立工具，而是 ECC “每个 Agent 只做一件事、越界即路由”体系中的构建守护位。

九、多 Harness 一致性：同一 Agent 的三种形态

该 Agent 在仓库中存在三个同步维护的载体，值得对照理解 ECC 的跨平台分发方式：

载体	路径	形态差异
Kiro IDE	build-error-resolver.md	Markdown + frontmatter，allowedTools 为 read/write/shell
Kiro CLI	build-error-resolver.json	JSON，allowedTools 映射为 fs_read/fs_write/shell，prompt 内嵌同一份提示词
Claude Code	build-error-resolver.md	frontmatter 增加 tools: Read, Write, Edit, Bash, Grep, Glob 与 model: sonnet，并在正文前置“Prompt Defense Baseline”安全基线（禁止泄露机密、警惕注入内容等）
OpenCode	build-error-resolver.txt	纯文本提示词，额外补充了“单文件检查”命令（npx tsc --noEmit path/to/file.ts）、五种带代码的修复模式与修复报告模板

从源码结构看，四个版本的核心工作流（收集 → 分类 → 最小化修复 → 迭代验证）完全一致，差异仅在工具命名与附加增强（Claude Code 版的安全基线、OpenCode 版的代码示例）。这种“一份方法论、多端适配”的模式意味着：无论你在哪个 Harness 里使用它，得到的行为约束和验收标准是同一套。

配套的前置防线也值得一提：typecheck-on-edit 钩子 在每次保存 .ts/.tsx 文件时即触发类型检查提醒，把错误拦截在产生时刻。两者构成“事前提醒 + 事后修复”的组合：hook 降低 build-error-resolver 被调用的频率，而当错误终究出现时，它保证修复动作是最小、最快、可验收的。

十、小结

build-error-resolver 的价值不在于它知道多少错误类型，而在于它用工程化约束把“修构建”这件容易越界的事收敛为一个可重复的闭环：全量收集错误 → 分类排序 → 单点最小化修复 → 全量复检 → 按五条成功指标验收。诊断命令、Common Fixes 速查表、优先级分级、Quick Recovery 三板斧与 5% 行数约束，构成了一个可直接搬入自己项目的修错 SOP；而仓库中同一 Agent 在 Kiro/Claude Code/OpenCode 三端的同步定义，则展示了 ECC 多 Harness 分发下“提示词即组件”的工程化形态。对使用 ECC 的开发者而言，记住两条就够用：构建红了，交给它；需要重构或改架构，立刻移交对应 Agent。