用途
Agent Introspection Debugging 是一个工作流技能，用于在 AI 智能体运行失败时进行结构化自我调试。它适用于智能体反复失败、消耗 token 却无进展、在同一工具上循环调用，或逐渐偏离既定任务的场景。该技能不是隐藏的运行时，而是教会智能体在升级给人类之前，系统性地调试自身。
何时启用
- 达到最大工具调用次数或循环限制而失败
- 反复重试但没有向前推进
- 上下文增长或提示漂移开始降低输出质量
- 文件系统或环境状态与预期不符
- 工具失败但很可能通过诊断和更小的纠正动作恢复
范围边界
该技能适用于：在盲目重试前捕获失败状态、诊断常见的智能体特有失败模式、应用受控的恢复动作、生成结构化的人类可读调试报告。
不应用作以下情况的主要来源：代码变更后的功能验证（应使用 verification-loop）、已有更窄 ECC 技能覆盖的框架特定调试、当前运行环境无法自动强制执行的运行时承诺。
四阶段循环
第一阶段：失败捕获
在尝试恢复之前，精确记录失败。需要捕获：错误类型、消息和堆栈跟踪（如有）；最后一次有意义的工具调用序列；智能体当时试图做什么；当前上下文压力（重复提示、过大的粘贴日志、重复计划或失控笔记）；当前环境假设（工作目录、分支、相关服务状态、预期文件）。
最小捕获模板：
## Failure Capture
- Session / task:
- Goal in progress:
- Error:
- Last successful step:
- Last failed tool / command:
- Repeated pattern seen:
- Environment assumptions to verify:
第二阶段：根因诊断
在改变任何东西之前，将失败匹配到已知模式。
| 模式 | 可能原因 | 检查 |
|---|---|---|
| 最大工具调用 / 重复相同命令 | 循环或无退出观察路径 | 检查最后 N 次工具调用是否重复 |
| 上下文溢出 / 推理退化 | 无界笔记、重复计划、过大日志 | 检查近期上下文是否有重复和低信号内容 |
| ECONNREFUSED / 超时 | 服务不可用或端口错误 | 验证服务健康、URL 和端口假设 |
| 429 / 配额耗尽 | 重试风暴或缺少退避 | 统计重复调用并检查重试间隔 |
| 写入后文件缺失 / 差异过期 | 竞态、错误工作目录或分支漂移 | 重新检查路径、工作目录、git 状态和实际文件是否存在 |
| “修复”后测试仍失败 | 假设错误 | 隔离确切的失败测试并重新推导 bug |
诊断问题：这是逻辑失败、状态失败、环境失败还是策略失败？智能体是否丢失了真实目标并开始优化错误的子任务？失败是确定性的还是暂时性的？验证诊断的最小可逆动作是什么？
第三阶段：受控恢复
用能改变诊断表面的最小动作进行恢复。安全恢复动作包括：停止重复重试并重述假设；裁剪低信号上下文，只保留活跃目标、阻塞项和证据；重新检查实际文件系统 / 分支 / 进程状态；将任务缩小到一个失败命令、一个文件或一个测试；从推测性推理切换到直接观察；当失败高风险或受外部阻塞时升级给人类。
不要声称支持“重置智能体状态”或“更新运行配置”等未经实际工具执行的自动修复动作。
受控恢复检查清单：
## Recovery Action
- Diagnosis chosen:
- Smallest action taken:
- Why this is safe:
- What evidence would prove the fix worked:
第四阶段：自省报告
以一份报告结束，使恢复过程对下一个智能体或人类可读。
## 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。当失败模式值得转化为本能或后续技能时，使用 continuous-learning-v2。当问题不是技术失败而是决策模糊时，使用 council。如果失败来自冲突的本地状态或仓库漂移，使用 workspace-surface-audit。
输出标准
当此技能激活时，不要仅以“我修好了”结束。始终提供：失败模式、根因假设、恢复动作、情况现已改善或仍被阻塞的证据。