agent-introspection-debugging

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