runtape Skill 技能

技能简介

runtape 是面向 AI 代理的「反事实调试器加回归测试生成器」。给它一次搞砸了的代理运行，它会定位上下文里真正导致坏决策的那一部分，把候选修复放到原始失败上下文上实测验证，然后写下一条回归测试让问题不再复发。命令只有三条：runtape why 回答「是什么导致了它」，runtape fix 回答「哪些修复真的成立（用测量说话）」，--write-test 直接产出 pytest 用例。官方示例里，邮件助手因供应商邮件 HTML 注释里的一句指令把发票转发到外部地址——runtape 追溯到那唯一一句话：有它 10 次运行 10 次转发，没它 0 次（p = 5e-6）。它与 LangSmith/Langfuse（展示代理看到了什么）和 ContextCite（给单次响应打分）互补，专注在本机针对具体失败做归因并固化修复。Python 3.10+，MIT 协议，GitHub 1 星（新项目）。

核心能力

• 反事实归因：why 在记录的失败运行上做对照重放，把坏决策定位到上下文中的具体片段（如一封邮件里的一行注释），给出可复现的因果证据。
• 修复实测验证：fix 把候选修复（系统提示规则、改源头数据等）逐个放进原始失败上下文重跑决策，只有真正成立的修复才通过，用测量而非猜测下结论。
• 回归测试落盘：fix --write-test 为验证成立的修复生成 pytest 文件，问题从此进入测试套件，后续改动再失败会被 CI 抓住。
• 多故障类型样例：内置三个可运行示例——邮件助手被隐藏指令诱导外发、客服机器人依据过期论坛帖退款 2400 美元、运维代理照旧手册删掉共享预发布数据库。
• 广泛兼容：支持 OpenAI 与 Anthropic SDK、LangChain 与 LangGraph、Ollama/LM Studio/vLLM 等 OpenAI 兼容本地服务，以及自定义代理循环；运行来源可用 runtape 自录，也可从 OpenTelemetry 或 Langfuse 导入。
• 本地离线可用：示例默认用规则化模型替身离线跑，不花一分钱就能复现与验证；--local（Ollama 免费）、--openai、--anthropic 可切真模型。
• 狩猎模式：examples/hunt.py 反复运行某示例直到复现失败，报告 token 用量并直接打印可用的 why 命令，解决真模型不是每次都失败的问题。

安装配置

1. 安装：pip install runtape，要求 Python 3.10+。
2. 克隆示例（可选）：git clone https://github.com/RehanMohammed985/runtape && cd runtape && pip install . openai anthropic。
3. 模型接入：按你的代理栈选装 OpenAI/Anthropic SDK 或 LangChain；本地模型可用 Ollama 免费驱动。
4. 接入既有观测：已有 Langfuse 或 OpenTelemetry 埋点的团队可直接导入历史运行，不必改埋点。

使用步骤

1. 复现失败：跑内置示例或你自己的代理，用 runtape why last tool:forward_email --model-fn examples/inbox_agent.py:simulated_model 定位致因。
2. 查看归因：why 输出指向上下文里的具体片段，并附带「有它/没它」的对照重放统计作为证据。
3. 验证修复：runtape fix last tool:forward_email ... 尝试系统提示规则与源头修复，逐个重放失败决策，输出哪些修复实测成立。
4. 固化回归：加 --write-test tests/test_inbox.py 生成 pytest 用例，pytest tests/test_inbox.py 验证全绿。
5. 持续防护：把生成的测试并入 CI，代理或提示词后续改动导致回潮时立即报警。

适用场景

• 提示注入归因：定位外部内容（邮件、网页、检索结果）里诱发越权动作的隐藏指令。
• 错误决策取证：回答「代理为什么这样决策」，用对照重放给出统计显著的因果结论。
• 修复有效性验证：改提示词或改源头后，确认修复在原始失败上下文上真的成立。
• 代理行为回归测试：把每次事故固化为 pytest，纳入 CI 长期防护。
• 本地开发调试：离线规则模型快速迭代，真模型狩猎模式抓偶发失败。

适用人群

调试 AI 代理「鬼迷心窍」式失败的开发者；负责代理安全（防提示注入、防越权操作）的工程师；维护 LangChain/LangGraph 生产流水线、需要失败取证与回归防护的团队；为代理写测试、苦于失败偶发难复现的质量工程师。

工作原理

runtape 基于记录的代理运行做反事实对照：保留原始上下文，干预其中单个片段后重放决策，比较有无该片段时的行为差异，从而把归因收敛到因果级证据（而非相关性打分）。验证阶段把候选修复注入同一失败上下文批量重放，统计通过率；通过的修复被翻译成独立的 pytest 用例，测试内部重放该决策场景。运行可由 runtape 本地录制，也可从 OpenTelemetry/Langfuse 导入，全部在本机执行，数据不出门。

官方链接

• GitHub 仓库：https://github.com/RehanMohammed985/runtape
• PyPI 主页：https://pypi.org/project/runtape/