| name | agent-introspection-debugging |
| description | 使用捕获、诊断、受控恢复和内省报告的 AI Agent 失败结构化自我调试工作流。 |
Agent 内省调试
当 agent 运行反复失败、消耗 token 而无进展、在相同工具上循环或偏离预期任务时,请使用此技能。
这是一个工作流技能,不是隐藏的运行时。它教 agent 在升级给人类之前系统地调试自己。
何时激活
- 达到最大工具调用/循环限制失败
- 反复重试但无进展
- 上下文增长或提示漂移开始降低输出质量
- 文件系统或环境状态与预期和现实之间不匹配
- 工具失败可能通过诊断和较小的纠正操作来恢复
范围边界
为以下情况激活此技能:
- 在盲目重试之前捕获失败状态
- 诊断常见的特定于 agent 的失败模式
- 应用受控的恢复操作
- 生成结构化的人类可读调试报告
不要将此技能作为主要来源用于:
- 代码更改后的功能验证;使用
verification-loop
- 当存在更窄的 ECC 技能时的框架特定调试
- 当前 harness 无法自动强制执行的运行时承诺
四阶段循环
阶段 1:失败捕获
在尝试恢复之前,准确记录失败。
捕获:
- 错误类型、消息和堆栈跟踪(如果可用)
- 最后有意义的工具调用序列
- agent 试图做什么
- 当前上下文压力:重复提示、超大的粘贴日志、重复的计划或失控的笔记
- 当前环境假设:cwd、分支、相关服务状态、预期文件
最小捕获模板:
## 失败捕获
- 会话/任务:
- 进行中的目标:
- 错误:
- 最后成功的步骤:
- 最后失败的工具/命令:
- 看到的重复模式:
- 需要验证的环境假设:
阶段 2:根本原因诊断
在更改任何内容之前,将失败与已知模式匹配。
| 模式 | 可能原因 | 检查 |
|---|
| 最大工具调用/重复相同命令 | 循环或无退出观察者路径 | 检查最后 N 次工具调用的重复 |
| 上下文溢出/推理降级 | 无界笔记、重复计划、超大日志 | 检查最近上下文的重复和低信号批量 |
ECONNREFUSED / 超时 | 服务不可用或端口错误 | 验证服务健康、URL 和端口假设 |
429 / 配额耗尽 | 重试风暴或缺少退避 | 计算重复调用并检查重试间隔 |
| 写入后文件丢失/陈旧 diff | 竞争、错误的 cwd 或分支漂移 | 重新检查路径、cwd、git 状态和实际文件存在 |
| "修复"后测试仍然失败 | 错误的假设 | 隔离确切的失败测试并重新推导错误 |
诊断问题:
- 这是逻辑失败、状态失败、环境失败还是策略失败?
- agent 是否失去了真正的目标并开始优化错误的子任务?
- 失败是确定性的还是瞬态的?
- 验证诊断的最小可逆操作是什么?
阶段 3:受控恢复
使用更改诊断表面的最小操作来恢复。
安全的恢复操作:
- 停止重复重试并重述假设
- 修剪低信号上下文,仅保留活动目标、阻塞和证据
- 重新检查实际的文件系统/分支/进程状态
- 将任务缩小到一个失败的命令、一个文件或一个测试
- 从投机推理切换到直接观察
- 当失败是高风险或外部阻塞时升级给人类
不要声称不支持的自愈操作,如"重置 agent 状态"或"更新 harness 配置",除非您通过当前环境中的真实工具实际执行它们。
受控恢复清单:
## 恢复操作
- 选择的诊断:
- 采取的最小操作:
- 为什么这是安全的:
- 什么证据将证明修复有效:
阶段 4:内省报告
以使下一个 agent 或人类能够理解恢复的方式结束报告。
## Agent 自调试报告
- 会话/任务:
- 失败:
- 根本原因:
- 恢复操作:
- 结果:成功 | 部分 | 阻塞
- Token/时间消耗风险:
- 需要后续:
- 以后要编码的预防性更改:
恢复启发式
按顺序优先考虑这些干预:
- 用一句话重述真正的目标。
- 验证世界状态,而不是信任记忆。
- 缩小失败范围。
- 运行一个区分检查。
- 然后重试。
错误模式:
良好模式:
- 捕获失败
- 对模式进行分类
- 运行一个直接检查
- 仅当检查支持时才更改计划
与 ECC 集成
- 如果代码已更改,请在恢复后使用
verification-loop。
- 当失败模式值得转化为本能或以后的能力时,使用
continuous-learning-v2。
- 当问题不是技术失败而是决策模糊时,使用
council。
- 如果失败来自冲突的本地状态或仓库漂移,请使用
workspace-surface-audit。
输出标准
当此技能处于活动状态时,不要仅以"我修复了它"结束。
始终提供:
- 失败模式
- 根本原因假设
- 恢复操作
- 证明情况现在更好或仍然被阻止的证据