error-recovery

资源

scripts/
  validate-error-recovery.sh
references/
  common-errors.md

错误恢复协议

任务失败时，Agent 必须遵循系统化的恢复流程，在效率与全面性之间取得平衡。本技能定义了如何对错误进行分类、利用组织经验、应用多来源恢复策略，以及判断何时升级处理。

立即响应

任务执行期间发生错误时：

1. 切勿盲目重试。阅读完整的错误消息、堆栈跟踪和所有诊断输出。

2. 将错误归为以下六种类型之一：

   • TOOL_FAILURE —— 精准工具或 MCP 工具返回错误
   • BUILD_ERROR —— 构建／编译命令失败（npm、tsc、vite 等）
   • TEST_FAILURE —— 测试套件失败（vitest、jest 等）
   • TYPE_ERROR —— TypeScript 类型检查失败
   • RUNTIME_ERROR —— 代码在执行期间崩溃
   • EXTERNAL_ERROR —— 第三方服务或 API 故障

3. 使用 precision_read 检查 .goodvibes/memory/failures.json，查找匹配的关键词：

   • 搜索错误消息中的关键词
   • 如果找到匹配的故障记录，请应用其中记载的 resolution
   • 如果该解决方案无效，请记录下来并继续恢复阶段
   • 如果未找到，请直接进入恢复阶段

错误类别：详细指南

TOOL_FAILURE

常见原因：

• 文件路径错误（绝对路径与相对路径混淆、拼写错误、文件不存在）
• 工具参数语法错误（JSON 格式错误、正则表达式不正确）
• 沙盒阻止访问外部路径
• 缺少必需参数
• 工具使用不当（提取模式错误、输出格式错误）

恢复步骤：

1. 重新阅读工具的架构和参数说明
2. 使用 precision_glob 检查文件／路径是否存在
3. 使用 precision_config get 检查沙盒设置（检查 sandbox.enabled）
4. 对于精准工具，检查是否使用了正确的提取／输出模式
5. 首先使用最少的参数尝试操作，然后再增加复杂度
6. 如果精准工具反复失败，请判断是用户错误还是实际的工具缺陷：
   • 用户错误：参数错误、路径错误、误解了工具行为
   • 工具缺陷：参数正确，但工具崩溃或返回了错误结果
7. 对于用户错误，修正后使用精准工具重试
8. 对于工具缺陷，仅针对该特定操作使用原生工具作为回退方案，然后继续使用精准工具

来自记忆的常见模式：

• 格式／模式不匹配：MCP 架构发送 output.format，处理程序读取 output.mode。始终使用 ?? 检查两者。
• Ripgrep glob 失败：src/**/*.ts 这类模式在 ripgrep 中会静默失败。使用正则表达式检测字面前缀并强制使用 fast-glob。
• 路径规范化：Ripgrep 返回的路径可能是绝对路径，也可能是相对路径。使用 path.resolve() 前，始终先调用 path.isAbsolute()。
• 沙盒选择性启用：仅当 sandbox === true || sandbox === 'true' 时启用。切勿检查 === false。

BUILD_ERROR

常见原因：

• 缺少依赖项（尚未安装、版本错误）
• 编辑期间未发现的类型错误
• 导入错误（路径错误、循环依赖）
• 配置错误（tsconfig、vite.config 等）
• 缺少环境变量

恢复步骤：

1. 阅读完整的构建输出（使用 precision_exec 和 expect.exit_code 捕获 stderr）
2. 找出错误链中的第一个错误（后续错误通常是连锁错误）
3. 对于缺少的依赖项：检查 package.json，运行 npm install
4. 对于类型错误：参阅下文的 TYPE_ERROR 部分
5. 对于导入错误：确认文件存在、检查导入路径，并查找循环依赖
6. 对于配置错误：与代码库中的可用示例进行比较
7. 搜索所用框架／构建工具的第一方文档

TEST_FAILURE

常见原因：

• 测试断言错误（预期值已更改）
• 缺少模拟对象或存根
• API 契约已更改（函数签名、返回类型）
• 测试环境设置不正确
• 异步时序问题

恢复步骤：

1. 阅读测试失败输出（断言错误、预期值与实际值）
2. 确定失败的测试文件和具体测试用例
3. 阅读测试文件，了解它测试的内容
4. 阅读实现代码，查看其是否符合测试预期
5. 判断是测试有误还是实现有误：
   • 如果实现是有意更改的 → 更新测试
   • 如果实现出现故障 → 修复实现
6. 对于异步问题，检查是否缺少 await、是否不当使用 done()，或是否存在竞态条件
7. 对于环境问题，检查测试设置文件（vitest.config、jest.setup.js）

TYPE_ERROR

常见原因：

• 不安全的成员访问（obj.prop，其中 obj 可能为 null/undefined）
• 赋值时类型不匹配（将 string 赋给 number）
• 函数调用签名错误（缺少参数、类型错误）
• 不安全的 any 用法绕过了类型系统
• 违反泛型约束

恢复步骤：

1. 阅读 TypeScript 错误消息（其中包含文件、行号和具体的类型问题）
2. 如果可用，使用 analysis-engine 工具 explain_type_error
3. 对于成员访问：添加可选链（?.）或空值检查
4. 对于赋值：在源头修正类型，或使用正确的类型断言
5. 对于函数调用：检查函数签名并提供正确的参数
6. 对于绕过类型检查的 any：将 any 替换为适当的类型
7. 对于泛型：确保类型参数满足约束

常见模式：

• 添加类型守卫：if (obj && 'prop' in obj)
• 使用可选链：obj?.prop?.nestedProp
• 使用可辨识联合收窄类型
• 使用类型谓词编写自定义守卫

RUNTIME_ERROR

常见原因：

• 访问 null/undefined（读取 null 的属性、将 undefined 作为函数调用）
• 未处理的 Promise 拒绝
• 未捕获的异常
• 缺少环境变量
• 网络故障（fetch、API 调用）
• 文件系统错误（ENOENT、EACCES）

恢复步骤：

1. 阅读堆栈跟踪，找到出错的确切行
2. 确定根本原因（访问 null、缺少环境变量、网络等）
3. 对于 null/undefined：添加运行时检查或使用可选链
4. 对于 Promise：添加 .catch() 处理程序，或在 await 周围使用 try/catch
5. 对于环境变量：检查 .env 文件，确认它们已加载
6. 对于网络：添加重试逻辑、检查凭据并验证 URL
7. 对于文件系统：确认路径存在并检查权限

常见模式：

• 在 React 组件中添加错误边界
• 在所有 await 表达式周围使用 try/catch
• 在启动时验证环境变量
• 添加防御性检查：if (!value) throw new Error('...')

EXTERNAL_ERROR

常见原因：

• 身份验证已过期或无效（401）
• 超出速率限制（429）
• 服务宕机或无法访问（503、ECONNREFUSED）
• API 请求无效（400）
• 超出配额

恢复步骤：

1. 检查错误状态码或消息
2. 对于身份验证错误（401）：检查 .goodvibes/secrets/ 中的凭据，确认令牌尚未过期
3. 对于速率限制（429）：实现指数退避，并检查是否可以提高配额
4. 对于服务宕机（503）：使用退避策略重试，并查看服务状态页
5. 对于错误请求（400）：阅读 API 文档并验证请求格式
6. 对于配额：查看用量仪表板、申请提高配额，或等待重置

常见模式：

• 指数退避：1s、2s、4s、8s
• 通过 precision_fetch 检查状态端点的服务状态
• 如果有多个 API 密钥可用，则轮换使用
• 缓存响应以减少 API 调用

恢复策略：一次性多来源

对错误进行分类并检查 failures.json 后，采用一次性策略，同时（而非依次）查阅所有知识来源，并应用最佳解决方案：

1. 内部知识——你的训练数据、代码库模式（discover、precision_grep、precision_read）、GoodVibes 记忆
2. 一手文档——官方文档、API 参考、变更日志、迁移指南
3. 社区知识——Stack Overflow、GitHub Issues、论坛
4. 开放互联网——通过更广泛的网络搜索查找边缘情况

应用最佳解决方案

查阅所有来源后：

1. 根据以下因素评估解决方案：

   • 时效性（优先选择适用于相近版本的解决方案）
   • 权威性（官方文档 > 社区 > 随机博客）
   • 针对性（完全匹配错误 > 一般性指导）
   • 项目契合度（符合你的技术栈和模式）

2. 完整应用解决方案：

   • 不要只应用一部分修复
   • 一次性完成所有相关更改
   • 使用 precision_edit 进行更改，而不是逐步微调

3. 验证修复：

   • 重新运行失败的操作
   • 使用 precision_exec 运行相关测试
   • 检查是否引入了新错误

解决问题后

成功解决错误后：

1. 记录到 .goodvibes/memory/failures.json

使用 precision_edit 追加一条新记录，内容如下：

{
  "id": "fail_YYYYMMDD_HHMMSS",
  "date": "ISO-8601 timestamp",
  "error": "Brief description of the error",
  "context": "What was being attempted when error occurred",
  "root_cause": "Why it happened (technical explanation)",
  "resolution": "How it was fixed (specific steps taken)",
  "prevention": "How to avoid this in the future",
  "keywords": ["relevant", "search", "terms"]
}

示例：

{
  "id": "fail_20260215_143000",
  "date": "2026-02-15T14:30:00Z",
  "error": "precision_read returns 'file not found' for valid path",
  "context": "Reading component file at src/components/Button.tsx",
  "root_cause": "Path was relative, but precision tools require absolute paths. Sandbox was enabled, blocking CWD resolution.",
  "resolution": "RESOLVED - Used absolute path with process.cwd() to create absolute path before calling precision_read.",
  "prevention": "Always use absolute paths with precision tools. Use path.resolve() to convert relative to absolute.",
  "keywords": ["precision_read", "path", "absolute", "relative", "sandbox", "file-not-found"]
}

2. 记录到 .goodvibes/logs/errors.md

使用 precision_edit 追加一条 Markdown 记录：

## [YYYY-MM-DD HH:MM] ERROR_CATEGORY: Brief Description

**Error**: Full error message

**Context**: What was being done

**Resolution**: How it was fixed

**Time to resolve**: X minutes

---

3. 继续执行任务

记录完成后，返回原任务。无需等待确认。

达到最大尝试次数后（尝试 3 次）

如果你已尝试修复错误 3 次，但仍然失败：

1. 记录尚未解决的失败

在 failures.json 中添加 "resolution": "UNRESOLVED - <what was tried>"：

{
  "id": "fail_20260215_143500",
  "date": "2026-02-15T14:35:00Z",
  "error": "Vitest tests hang indefinitely on CI",
  "context": "Running npm run test in CI pipeline",
  "root_cause": "Unknown - tests pass locally but hang in CI environment",
  "resolution": "UNRESOLVED - Tried: 1) Added --no-watch flag, 2) Increased timeout to 60s, 3) Disabled coverage collection. Tests still hang.",
  "prevention": "Need deeper investigation into CI environment differences",
  "keywords": ["vitest", "ci", "hang", "timeout", "unresolved"]
}

2. 向协调器报告

在回复中使用结构化格式：

## Task Status: BLOCKED

### Error
[ERROR_CATEGORY] Brief description

### Attempts Made
1. **Attempt 1**: What was tried -> Result
2. **Attempt 2**: What was tried -> Result
3. **Attempt 3**: What was tried -> Result

### Root Cause Analysis
Best guess at why this is failing based on investigation.

### Suggested Next Steps
- Option 1: [Describe approach that requires different permissions/access]
- Option 2: [Describe alternative architecture/design decision]
- Option 3: [Describe manual intervention needed]

### Files Changed
- `path/to/file.ts` - [what was changed during troubleshooting]

3. 不要将任务标记为已完成

将任务保持在 BLOCKED 状态。协调器将决定是否：

• 向用户升级处理
• 尝试其他方法
• 指派给能力不同的其他 Agent
• 暂缓任务

立即升级处理（跳过恢复）

对于某些错误类型，不要尝试恢复。应立即向协调器升级处理：

1. 权限错误

EACCES: permission denied
EPERM: operation not permitted

原因：这些错误需要用户介入授予权限。Agent 无法修复。

升级时说明："遇到权限错误。需要用户执行以下操作：[授予文件访问权限 / 以 sudo 身份运行 / 更改所有权]。"

2. 缺少凭据/密钥

Error: OPENAI_API_KEY is not defined
Error: Database connection failed: authentication error
401 Unauthorized

原因：Agent 无法创建或修改密钥。只有用户能提供凭据。

升级时说明："缺少凭据：[ENV_VAR_NAME 或服务名称]。用户需要通过 .env 或密钥管理工具提供。"

3. 架构上的模糊之处

Context clues indicate multiple valid approaches:
- Use REST API vs GraphQL
- Use Prisma vs Drizzle
- Component composition pattern unclear

原因：这些是会影响更广泛系统的设计决策。Agent 不应擅自做出架构选择。

升级时说明："需要做出架构决策：[描述选择]。选项：[列出 2-3 个选项及其利弊]。"

4. 发现范围变更

Original task: "Add user profile page"
Discovered: Requires new database schema, auth changes, API endpoints

原因：任务规模超出最初设定的范围。协调器需要重新规划。

升级时说明："发现范围扩大。原任务：[任务]。所需内容：[新的依赖项/更改]。建议：[拆分为子任务 / 征求用户批准]。"

摘要

发生错误时：

1. 立即分类（TOOL_FAILURE、BUILD_ERROR 等）
2. 检查 failures.json 中是否有已知模式
3. 通过一次性多来源恢复方案进行恢复（内部资料 + 文档 + 社区 + 网络）
4. 完整应用最佳解决方案
5. 将解决情况记录到 failures.json 和 errors.md
6. 继续执行任务

尝试 3 次后：

1. 记录为 UNRESOLVED
2. 向编排器报告结构化摘要
3. 不要将任务标记为已完成

遇到以下情况时立即升级处理：

1. 权限错误
2. 缺少凭据
3. 架构存在歧义
4. 范围变更

请记住：

• 精准工具是默认选择，原生工具是备用方案
• 用户错误 ≠ 工具故障
• 恢复尝试应有系统性，而非随机进行
• 记忆是组织知识——请加以利用并为其贡献