SuperAPI AI 工具集

agent-introspection-debugging

智能体与模型

查看项目

更新于 11-10 16:22

技能介绍

用途

agent-introspection-debugging 是一个面向 AI Agent 的自我调试工作流技能。当一次 Agent 运行反复失败、不断消耗 token 却没有进展、在同一工具上循环,或逐渐偏离原定任务时,可以使用该技能,让 Agent 在升级给人工之前先系统性地调试自身。

触发场景

资料列出的适用情形包括:

  • 达到最大工具调用次数或循环上限导致失败
  • 反复重试但没有前进
  • 上下文增长或提示漂移开始降低输出质量
  • 文件系统或环境状态与预期不符
  • 工具失败,但通过诊断和更小的纠正动作有较大可能恢复

主要能力

该技能覆盖四类能力:在盲目重试前捕获失败状态、诊断常见的 Agent 特有失败模式、执行受控的恢复动作、生成结构化且便于人阅读的调试报告。

四阶段循环

阶段一:失败捕获。 在尝试恢复前精确记录失败,包括错误类型、消息与可用时的堆栈、最近一次有意义的工具调用序列、Agent 当时想做什么、当前上下文压力(重复提示、过大日志、重复计划、失控笔记),以及当前环境假设(工作目录、分支、相关服务状态、预期文件)。资料提供了最小捕获模板,含会话/任务、进行中的目标、错误、最后成功步骤、最后失败的工具/命令、观察到的重复模式、待验证的环境假设等字段。

阶段二:根因诊断。 在改动任何东西前,先将失败匹配到已知模式。资料给出的模式与成因对应包括:最大工具调用或重复同一命令,可能是循环或无退出观察路径,应检查最近 N 次工具调用是否重复;上下文溢出或推理退化,可能是无边界笔记、重复计划、超大日志,应检查近期上下文中的重复与低信号内容;ECONNREFUSED 或超时,可能是服务不可用或端口错误,应核实服务健康、URL 与端口假设;429 或配额耗尽,可能是重试风暴或缺少退避,应统计重复调用与重试间隔;写入后文件缺失或差异过期,可能是竞态、工作目录错误或分支漂移,应复查路径、工作目录、git 状态与实际文件;修复后测试仍失败,可能是假设错误,应隔离具体失败测试并重新推导缺陷。诊断时还需判断失败属于逻辑、状态、环境还是策略问题,Agent 是否丢失真实目标而优化了错误的子任务,失败是确定性还是暂时性的,以及验证诊断的最小可逆动作是什么。

阶段三:受控恢复。 用能改变诊断面的最小动作恢复,资料列出的安全动作包括:停止重复重试并重述假设、裁剪低信号上下文只保留活跃目标与阻碍和证据、复查实际文件系统/分支/进程状态、将任务缩小到一条失败命令或一个文件或一个测试、从推测性推理切换到直接观察、在失败高风险或受外部阻塞时升级给人工。资料同时强调,除非确实通过当前环境中的真实工具执行,否则不要声称“重置 Agent 状态”或“更新 harness 配置”等不受支持的自动修复动作。技能附有恢复动作清单,记录所选诊断、采取的最小动作、为何安全、何种证据能证明修复有效。

阶段四:自省报告。 以一份让下一个 Agent 或人能理解恢复过程的报告收尾,字段包括会话/任务、失败、根因、恢复动作、结果(成功/部分/受阻)、token 与时间消耗风险、需要的后续动作、日后可固化的预防性改动。

使用方式

资料给出了恢复启发式的优先顺序:用一句话重述真实目标;验证世界状态而非信任记忆;缩小失败范围;运行一个可区分的检查;最后才重试。反面模式是用略有不同的措辞重复同一动作三次;正面模式是捕获失败、归类模式、做一次直接检查,仅在检查支持时才改变计划。

当该技能处于激活状态时,输出标准要求不能只以“我修好了”结束,必须给出失败模式、根因假设、恢复动作,以及表明情况已好转或仍受阻的证据。

与其他技能的配合

资料说明:若恢复后代码有改动,使用 verification-loop;若失败模式值得转化为直觉或后续技能,使用 continuous-learning-v2;若问题不是技术失败而是决策含糊,使用 council;若失败源于本地状态冲突或仓库漂移,使用 workspace-surface-audit。

适用场景与限制

适用场景为 Agent 运行反复失败、循环、上下文退化、环境状态不符或工具可恢复性失败时的自我调试与恢复。资料明确划定的边界是:它不用于代码改动后的功能验证(应使用 verification-loop),不用于已有更窄 ECC 技能覆盖的框架特定调试,也不提供当前 harness 无法自动执行的运行时承诺。该技能是工作流指导而非隐藏运行时,不承诺无法实际执行的自动修复。