agent-introspection-debugging

Files (1)

• SKILL.md

SKILL.md (first lines)

# 智能体内省调试

当智能体运行反复失败、消耗令牌而无进展、在同一工具上循环或偏离预期任务时，使用此技能。

这是一个工作流技能，而非隐藏运行时。它教导智能体在升级到人工之前系统地调试自己。

## 何时激活

- 最大工具调用 / 循环限制失败
- 重复重试且没有进展
- 上下文增长或提示漂移开始降低输出质量
- 文件系统或环境状态与预期和现实之间不匹配
- 可能通过诊断和较小的纠正操作恢复的工具失败

## 范围边界

激活此技能用于：
- 在盲目重试之前捕获失败状态
- 诊断常见的智能体特定失败模式
- 应用受控的恢复操作
- 生成结构化的可人工阅读的调试报告

不要将此技能作为主要来源用于：
- 代码更改后的功能验证；使用 `verification-loop`
- 更窄的 ECC 技能已存在的框架特定调试
- 当前工具无法自动强制执行的运行时承诺

## 四阶段循环

### 阶段 1：失败捕获

在尝试恢复之前，精确记录失败。

捕获：
- 错误类型、消息和堆栈跟踪（如果可用）
- 最后有意义的工具调用序列
- 智能体试图做什么
- 当前上下文压力：重复提示、过大粘贴日志、重复计划或失控注释
- 当前环境假设：cwd、分支、相关服务状态、预期文件

最小捕获模板：

```markdown
## 失败捕获
- 会话 / 任务：
- 进行中的目标：
- 错误：
- 最后成功步骤：
- 最后失败的工具 / 命令：
- 看到的重复模式：
- 要验证的环境假设：
```

### 阶段 2：根本原因诊断

在更改任何内容之前，将失败与已知模式匹配。

| 模式 | 可能原因 | 检查 |
| --- | --- | --- |
| 最大工具调用 / 重复相同命令 | 循环或无退出观察者路径 | 检查最后 N 次工具调用的重复 |
| 上下文溢出 / 退化推理 | 无限制注释、重复计划、过大日志 | 检查最近上下文的重复和低信号批量 |
| `ECONNREFUSED` / 超时 | 服务不可用或端口错误 | 验证服务健康、URL 和端口假设 |
| `429` / 配额耗尽 | 重试风暴或缺少退避 | 计算重复调用并检查重试间隔 |
| 写入后文件缺失 / 过时差异 | 竞争、错误 cwd 或分支漂移 | 重新检查路径、cwd、git 状态和实际文件存在 |
| "修复"后测试仍然失败 | 错误假设 | 隔离确切的失败测试并重新推导错误 |

诊断问题：
- 这是逻辑失败、状态失败、环境失败还是策略失败？
- 智能体是否失去了真实目标并开始优化错误的子任务？
- 失败是确定性的还是瞬态的？
- 什么是最小的可逆操作来验证诊断？

### 阶段 3：受控恢复

使用改变诊断表面的最小操作进行恢复。

安全的恢复操作：
- 停止重复重试并重新陈述假设
- 修剪低信号上下文，仅保留活动目标、阻止器和证据
- 重新检查实际文件系统 / 分支 / 进程状态
- 将任务缩小到一个失败命令、一个文件或一个测试
- 从推测推理切换到直接观察
- 当失败高风险或外部阻塞时升级到人工

除非您通过当前环境中的实际工具实际执行它们，否则不要声明不受支持的自愈操作，如"重置智能体状态"或"更新工具配置"。

受控恢复清单：

```markdown
## 恢复操作
- 选择的诊断：
- 采取的最小操作：
- 为什么这是安全的：
- 什么证据将证明修复有效：
```

### 阶段 4：内省报告

以使恢复对下一个智能体或人类可读的报告结束。

```markdown
## 智能体自我调试报告
- 会话 / 任务：
- 失败：
- 根本原因：
- 恢复操作：
- 结果：success | partial | blocked
- 令牌 / 时间消耗风险：
- 需要跟进：
- 稍后编码的预防性变更：
```

## 恢复启发式

按顺序优先考虑这些干预：

1. 用一句话重新陈述真实目标。
2. 验证世界状态而非信任记忆。
3. 缩小失败范围。

From aaione/everything-claude-code-zh, MIT.

More from aaione/everything-claude-code-zh