
关于
AI 代理故障的结构化自调试工作流,包含捕获、诊断、受控恢复和内省报告四个阶段。
name: agent-introspection-debugging description: 使用捕获、诊断、受控恢复和内省报告的结构化 AI 代理自我调试工作流。 origin: ECC
代理内省调试
当代理运行反复失败、消耗 token 却无进展、在相同工具上循环、或偏离预期任务时使用本技能。
这是一个工作流技能,不是隐藏的运行时。它教代理在升级到人工之前系统地自我调试。
何时激活
- 最大工具调用/循环限制失败
- 反复重试却无前进进展
- 上下文增长或提示漂移开始降低输出质量
- 文件系统或环境状态与预期不匹配
- 工具失败但可能通过诊断和较小的纠正操作恢复
范围边界
在以下情况激活本技能:
- 在盲目重试前捕获失败状态
- 诊断常见的代理特定失败模式
- 应用受控恢复操作
- 生成结构化的人类可读调试报告
不要将本技能用作以下的主要来源:
- 代码更改后的功能验证;使用
verification-loop - 当已有更窄的 ECC 技能时的框架特定调试
- 当前工具链无法自动执行的运行时承诺
四阶段循环
阶段 1:失败捕获
在尝试恢复之前,精确记录失败。
捕获:
- 错误类型、消息和可用时的堆栈跟踪
- 最后有意义的工具调用序列
- 代理正在尝试做什么
- 当前上下文压力:重复提示、过大的粘贴日志、重复的计划或失控的笔记
- 当前环境假设:工作目录、分支、相关服务状态、预期文件
最小捕获模板:
## Failure Capture
- Session / task:
- Goal in progress:
- Error:
- Last successful step:
- Last failed tool / command:
- Repeated pattern seen:
- Environment assumptions to verify:
阶段 2:根因诊断
在更改任何内容之前,将失败匹配到已知模式。
| 模式 | 可能原因 | 检查方法 |
| --- | --- | --- |
| 最大工具调用/重复相同命令 | 循环或无退出观察路径 | 检查最后 N 次工具调用是否重复 |
| 上下文溢出/推理退化 | 无界笔记、重复计划、过大日志 | 检查最近上下文中的重复和低信号批量内容 |
| ECONNREFUSED / 超时 | 服务不可用或端口错误 | 验证服务健康状态、URL 和端口假设 |
| 429 / 配额耗尽 | 重试风暴或缺少退避 | 计算重复调用次数并检查重试间隔 |
| 写入后文件丢失/过时差异 | 竞态、错误工作目录或分支漂移 | 重新检查路径、工作目录、git 状态和实际文件存在性 |
| "修复"后测试仍然失败 | 错误假设 | 隔离确切失败的测试并重新推导 bug |
诊断问题:
- 这是逻辑失败、状态失败、环境失败还是策略失败?
- 代理是否丢失了真正的目标并开始优化错误的子任务?
- 失败是确定性的还是瞬态的?
- 能验证诊断的最小可逆操作是什么?
阶段 3:受控恢复
用改变诊断面的最小操作进行恢复。
安全恢复操作:
- 停止重复重试并重新陈述假设
- 修剪低信号上下文,仅保留活跃目标、阻碍因素和证据
- 重新检查实际文件系统/分支/进程状态
- 将任务缩小到一个失败的命令、一个文件或一个测试
- 从推测性推理切换到直接观察
- 当失败是高风险或外部阻塞时升级到人工
不要声称不支持的自动修复操作如"重置代理状态"或"更新工具链配置",除非你确实在当前环境中通过真实工具执行它们。
受控恢复检查清单:
## Recovery Action
- Diagnosis chosen:
- Smallest action taken:
- Why this is safe:
- What evidence would prove the fix worked:
阶段 4:内省报告
以使恢复对下一个代理或人类可读的报告结束。
## Agent Self-Debug Report
- Session / task:
- Failure:
- Root cause:
- Recovery action:
- Result: success | partial | blocked
- Token / time burn risk:
- Follow-up needed:
- Preventive change to encode later:
恢复启发式
按以下顺序优先选择干预措施:
- 用一句话重新陈述真正的目标。
- 验证世界状态而非信任记忆。
- 缩小失败范围。
- 运行一个判别性检查。
- 然后才重试。
坏模式:
- 用略有不同的措辞重试相同操作三次
好模式:
- 捕获失败
- 分类模式
- 运行一个直接检查
- 仅在检查支持时才更改计划
与 ECC 的集成
- 如果代码已更改,恢复后使用
verification-loop。
兼容工具
Claude CodeCursor
标签
AI与机器学习
