mirror of
https://github.com/affaan-m/everything-claude-code.git
synced 2026-05-14 18:44:44 +08:00
162 lines
5.0 KiB
Markdown
162 lines
5.0 KiB
Markdown
---
|
||
name: agent-introspection-debugging
|
||
description: 针对AI代理故障的结构化自调试工作流程，包括捕获、诊断、受限恢复和内省报告。
|
||
origin: ECC
|
||
---
|
||
|
||
# 智能体内省调试
|
||
|
||
当智能体运行反复失败、消耗令牌却无进展、在相同工具上循环或偏离预期任务时，使用此技能。
|
||
|
||
这是一个工作流技能，而非隐藏运行时。它教会智能体在升级给人类之前，系统性地自我调试。
|
||
|
||
## 何时激活
|
||
|
||
* 达到最大工具调用/循环限制失败
|
||
* 重复重试但无任何进展
|
||
* 上下文增长或提示漂移导致输出质量下降
|
||
* 文件系统或环境状态与预期不匹配
|
||
* 可通过诊断和较小纠正措施恢复的工具故障
|
||
|
||
## 范围边界
|
||
|
||
激活此技能用于：
|
||
|
||
* 在盲目重试前捕获失败状态
|
||
* 诊断常见的智能体特定失败模式
|
||
* 应用受限的恢复操作
|
||
* 生成结构化的人类可读调试报告
|
||
|
||
请勿将此技能作为以下情况的主要来源：
|
||
|
||
* 代码变更后的功能验证；请使用 `verification-loop`
|
||
* 当已有更窄的 ECC 技能时的框架特定调试
|
||
* 当前框架无法自动强制执行的运行时承诺
|
||
|
||
## 四阶段循环
|
||
|
||
### 阶段 1：失败捕获
|
||
|
||
在尝试恢复之前，精确记录失败信息。
|
||
|
||
捕获内容：
|
||
|
||
* 错误类型、消息和堆栈跟踪（如可用）
|
||
* 最后有意义的工具调用序列
|
||
* 智能体当时试图完成的任务
|
||
* 当前上下文压力：重复提示、过大的粘贴日志、重复的计划或失控的笔记
|
||
* 当前环境假设：工作目录、分支、相关服务状态、预期文件
|
||
|
||
最小捕获模板：
|
||
|
||
```markdown
|
||
## 失败捕获
|
||
- 会话/任务：
|
||
- 进行中的目标：
|
||
- 错误：
|
||
- 最后成功的步骤：
|
||
- 最后失败的工具/命令：
|
||
- 观察到的重复模式：
|
||
- 需验证的环境假设：
|
||
```
|
||
|
||
### 阶段 2：根因诊断
|
||
|
||
在更改任何内容之前，将失败与已知模式匹配。
|
||
|
||
| 模式 | 可能原因 | 检查 |
|
||
| --- | --- | --- |
|
||
| 最大工具调用/重复相同命令 | 循环或无退出观察路径 | 检查最后 N 次工具调用是否存在重复 |
|
||
| 上下文溢出/推理能力下降 | 无界笔记、重复计划、过大日志 | 检查近期上下文是否存在重复和低信号批量内容 |
|
||
| `ECONNREFUSED` / 超时 | 服务不可用或端口错误 | 验证服务健康状态、URL 和端口假设 |
|
||
| `429` / 配额耗尽 | 重试风暴或缺少退避 | 统计重复调用次数并检查重试间隔 |
|
||
| 写入后文件缺失/差异过时 | 竞态、工作目录错误或分支漂移 | 重新检查路径、工作目录、git 状态和实际文件是否存在 |
|
||
| “修复”后测试仍然失败 | 假设错误 | 隔离确切失败的测试并重新推导错误 |
|
||
|
||
诊断问题：
|
||
|
||
* 这是逻辑失败、状态失败、环境失败还是策略失败？
|
||
* 智能体是否丢失了真实目标并开始优化错误的子任务？
|
||
* 失败是确定性的还是瞬态的？
|
||
* 能够验证诊断的最小可逆操作是什么？
|
||
|
||
### 阶段 3：受限恢复
|
||
|
||
使用改变诊断面的最小操作进行恢复。
|
||
|
||
安全恢复操作：
|
||
|
||
* 停止重复重试并重新陈述假设
|
||
* 修剪低信号上下文，仅保留活跃目标、阻碍因素和证据
|
||
* 重新检查实际文件系统/分支/进程状态
|
||
* 将任务缩小到一个失败的命令、一个文件或一个测试
|
||
* 从推测性推理切换到直接观察
|
||
* 当失败风险高或受外部阻碍时升级给人类
|
||
|
||
不要声称不支持的自动修复操作，如“重置智能体状态”或“更新框架配置”，除非你正在当前环境中通过真实工具实际执行这些操作。
|
||
|
||
受限恢复检查清单：
|
||
|
||
```markdown
|
||
## 恢复操作
|
||
- 选择的诊断方式：
|
||
- 采取的最小操作：
|
||
- 为何此操作安全：
|
||
- 哪些证据能证明修复生效：
|
||
```
|
||
|
||
### 阶段 4：内省报告
|
||
|
||
以一份使恢复过程对下一个智能体或人类清晰可读的报告结束。
|
||
|
||
```markdown
|
||
## 代理自调试报告
|
||
- 会话/任务：
|
||
- 失败原因：
|
||
- 根本原因：
|
||
- 恢复措施：
|
||
- 结果：成功 | 部分成功 | 受阻
|
||
- Token/时间消耗风险：
|
||
- 是否需要后续跟进：
|
||
- 后续需编码的预防性变更：
|
||
```
|
||
|
||
## 恢复启发式方法
|
||
|
||
按顺序优先选择以下干预措施：
|
||
|
||
1. 用一句话重新陈述真实目标。
|
||
2. 验证世界状态，而非依赖记忆。
|
||
3. 缩小失败范围。
|
||
4. 运行一次判别性检查。
|
||
5. 然后才重试。
|
||
|
||
错误模式：
|
||
|
||
* 用略微不同的措辞重复相同操作三次
|
||
|
||
正确模式：
|
||
|
||
* 捕获失败
|
||
* 分类模式
|
||
* 运行一次直接检查
|
||
* 仅当检查支持时才更改计划
|
||
|
||
## 与 ECC 集成
|
||
|
||
* 如果代码已更改，在恢复后使用 `verification-loop`。
|
||
* 当失败模式值得转化为本能或后续技能时，使用 `continuous-learning-v2`。
|
||
* 当问题不是技术失败而是决策模糊时，使用 `council`。
|
||
* 如果失败源于冲突的本地状态或仓库漂移，使用 `workspace-surface-audit`。
|
||
|
||
## 输出标准
|
||
|
||
当此技能激活时，不要仅以“我已修复”结束。
|
||
|
||
始终提供：
|
||
|
||
* 失败模式
|
||
* 根因假设
|
||
* 恢复操作
|
||
* 证明情况已改善或仍受阻的证据
|