agent-introspection-debugging

代理内省调试

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

这是一个工作流技能，而非隐藏运行时。它教会代理在升级到人工之前系统地进行自我调试。

何时激活

• 最大工具调用/循环限制失败
• 重复重试但无进展
• 上下文增长或提示漂移导致输出质量下降
• 文件系统或环境状态与预期不符
• 可能通过诊断和较小纠正操作恢复的工具故障

范围边界

激活此技能用于：

• 在盲目重试前捕获故障状态
• 诊断常见的代理特定故障模式
• 执行受控恢复操作
• 生成结构化的人类可读调试报告

不要将此技能用作以下情况的主要来源：

• 代码变更后的功能验证；请使用 verification-loop
• 当存在更窄的 ECC 技能时的框架特定调试
• 当前 harness 无法自动强制执行的运行时承诺

四阶段循环

阶段 1：故障捕获

在尝试恢复之前，精确记录故障。

捕获：

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

最小捕获模板：

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

阶段 2：根本原因诊断

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

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

诊断问题：

• 这是逻辑故障、状态故障、环境故障还是策略故障？
• 代理是否丢失了真实目标并开始优化错误的子任务？
• 故障是确定性的还是瞬态的？
• 最小的可逆操作是什么，可以验证诊断？

阶段 3：受控恢复

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

安全恢复操作：

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

不要声称不支持的自动修复操作，如“重置代理状态”或“更新 harness 配置”，除非你通过当前环境中的真实工具实际执行它们。

受控恢复检查清单：

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

阶段 4：内省报告

以一份使恢复对下一个代理或人工可读的报告结束。

## 代理自调试报告
- 会话/任务：
- 故障：
- 根本原因：
- 恢复操作：
- 结果：成功 | 部分 | 阻塞
- 令牌/时间消耗风险：
- 需要后续跟进：
- 稍后编码的预防性更改：

恢复启发式

优先按顺序进行以下干预：

1. 用一句话重新陈述真实目标。
2. 验证世界状态，而不是相信记忆。
3. 缩小失败范围。
4. 运行一次区分性检查。
5. 然后才重试。

不良模式：

• 用略微不同的措辞重试相同操作三次

良好模式：

• 捕获故障
• 分类模式
• 运行一次直接检查
• 仅当检查支持时才更改计划

与 ECC 集成

• 如果代码已更改，在恢复后使用 verification-loop。
• 当故障模式值得转化为本能或后续技能时，使用 continuous-learning-v2。
• 当问题不是技术故障而是决策模糊时，使用 council。
• 如果故障源于冲突的本地状态或仓库漂移，使用 workspace-surface-audit。

输出标准

当此技能激活时，不要仅以“我修复了它”结束。

始终提供：

• 故障模式
• 根本原因假设
• 恢复操作
• 证明情况已改善或仍被阻塞的证据