---

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:

恢复启发式

按以下顺序优先选择干预措施：

1. 用一句话重新陈述真正的目标。
2. 验证世界状态而非信任记忆。
3. 缩小失败范围。
4. 运行一个判别性检查。
5. 然后才重试。

坏模式：

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

好模式：

• 捕获失败
• 分类模式
• 运行一个直接检查
• 仅在检查支持时才更改计划

与 ECC 的集成

• 如果代码已更改，恢复后使用 verification-loop。