Agent Introspection Debugging

---
name: agent-introspection-debugging
description: "针对 AI 代理 (Agent) 失败的结构化自调试工作流，包括捕捉、诊断、受控恢复和内省报告。"
origin: ECC
---

# 代理内省调试 (Agent Introspection Debugging)

当代理运行反复失败、在没有进展的情况下消耗令牌 (Tokens)、循环调用相同的工具，或者偏离预期任务时，请使用此技能。

这是一个工作流技能，而不是隐藏的运行时。它教导代理在升级到人工处理之前系统地调试自身。

## 何时激活

- 达到最大工具调用次数 / 循环限制导致的失败
- 反复尝试但没有向前进展
- 上下文膨胀或提示词漂移导致输出质量开始下降
- 文件系统或环境状态与预期不符
- 经过诊断和较小的纠正操作后可能恢复的工具故障

## 范围界限

在以下情况下激活此技能：
- 在盲目重试前捕捉失败状态
- 诊断常见的代理特定失败模式
- 应用受控的恢复操作
- 生成结构化的、人类可读的调试报告

不要将此技能作为以下情况的主要来源：
- 代码更改后的功能验证；请使用 `verification-loop`
- 当已存在更具体的 ECC 技能时进行框架特定调试
- 当前框架无法自动执行的运行时承诺

## 四阶段循环

### 第一阶段：失败捕捉 (Failure Capture)

在尝试恢复之前，精确记录失败情况。

捕捉内容：
- 错误类型、消息和堆栈跟踪（如果可用）
- 最近一次有意义的工具调用序列
- 代理当时试图完成的任务
- 当前上下文压力：反复出现的提示词、过大的粘贴日志、重复的计划或失控的笔记
- 当前环境假设：当前工作目录 (cwd)、分支、相关服务状态、预期文件

最低限度的捕捉模板：

```markdown
## 失败捕捉
- 会话 / 任务:
- 进行中的目标:
- 错误:
- 最后一个成功的步骤:
- 最后一个失败的工具 / 命令:
- 观察到的重复模式:
- 待验证的环境假设:
```

### 第二阶段：根本原因诊断 (Root-Cause Diagnosis)

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

| 模式 | 可能的原因 | 检查项 |
| --- | --- | --- |
| 达到最大工具调用次数 / 反复执行同一命令 | 循环或无退出的观察者路径 | 检查最后 N 次工具调用是否存在重复 |
| 上下文溢出 / 推理能力下降 | 无限制的笔记、重复的计划、过大的日志 | 检查最近的上下文是否存在重复和低信号的冗余信息 |
| `ECONNREFUSED` / 超时 | 服务不可用或端口错误 | 验证服务健康状况、URL 和端口假设 |
| `429` / 配额耗尽 | 重试风暴或缺少退避机制 | 统计重复调用次数并检查重试间隔 |
| 写入后文件丢失 / 差异过时 | 竞态、错误的 cwd 或分支漂移 | 重新检查路径、cwd、git 状态以及文件的实际存在情况 |
| “修复”后测试仍然失败 | 假设错误 | 隔离确切的失败测试并重新推导错误原因 |

诊断问题：
- 这是逻辑失败、状态失败、环境失败还是策略失败？
- 代理是否丢失了真实目标并开始优化错误的子任务？
- 失败是确定性的还是瞬态的？
- 能够验证诊断结果的最小可逆操作是什么？

### 第三阶段：受控恢复 (Contained Recovery)

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

安全的恢复操作：
- 停止重复重试并重新陈述假设
- 修剪低信号上下文，仅保留活动目标、阻塞项和证据
- 重新检查实际的文件系统 / 分支 / 进程状态
- 将任务缩小到单个失败的命令、单个文件或单个测试
- 从推测性推理转向直接观察
- 当失败风险较高或受到外部阻塞时，升级到人工处理

除非您确实在当前环境中使用真实工具执行这些操作，否则不要声称不支持的自动修复操作，如“重置代理状态”或“更新框架配置”。

受控恢复检查清单：

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

### 第四阶段：内省报告 (Introspection Report)

最后提交一份报告，使恢复过程对下一个代理或人类清晰可见。

```markdown
## 代理自调试报告
- 会话 / 任务:
- 失败情况:
- 根本原因:
- 恢复操作:
- 结果: 成功 | 部分成功 | 被阻塞
- 令牌 / 时间损耗风险:
- 之后需要的跟进:
- 稍后需要编码的预防性变更:
```

## 恢复启发法

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

1. 用一句话重新陈述真实目标。
2. 验证世界状态，而不是信任记忆。
3. 缩小失败范围。
4. 执行一项具有辨别力的检查。
5. 然后再重试。

错误模式：
- 用略微不同的措辞重复尝试相同的操作三次

正确模式：
- 捕捉失败
- 对模式进行分类
- 执行一项直接检查
- 仅在检查支持的情况下更改计划

## 与 ECC 的集成

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

## 输出标准

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

始终提供：
- 失败模式
- 根本原因假设
- 恢复操作
- 证明情况已改善或仍被阻塞的证据