whatbroke 是一个用于比较 AI Agent 两次运行之间行为差异的命令行工具，由 GitHub 项目 arthi-arumugam-git/whatbroke 提供。它的核心思路是：纯文本 diff 无法发现 Agent 行为层面的问题——例如模型可能嘴上说着「你的订阅已取消」，实则悄悄跳过了 cancel_subscription 调用。看起来文字没问题，行为却已经损坏。whatbroke 正是为了解决这类问题而设计。
主要能力 在更换模型、微调提示词、升级框架版本或修改工具描述之后，运行 whatbroke，即可看到具体变化：哪些工具调用消失了、哪些参数发生了漂移、成本与延迟在哪里变动、哪些输出发生了翻转。工具按 id 对齐两次运行，并在每次运行内对齐工具调用，然后报告差异。当出现破坏性变化时退出码为 1；可使用 --fail-on changed 设置更严格的关卡，或使用 --fail-on never 仅生成报告。
多采样与噪声区分 Agent 不会两次做完全相同的事，因此单次前后对比可能会把 Agent 本身就存在的噪声归咎于变更。可以多次记录同一场景，并在运行 id 后加后缀。whatbroke 会识别后缀，将每个修改前样本与每个修改后样本进行比较，并为每个发现给出比率。在两个基线样本之间也来回波动的项会被降级为 flaky 信息，因为这次变更之前 Agent 就是这样表现的；出现率低于一半配对的破坏性发现会软化为警告，剩下的才是真正的信号。
记录轨迹 轨迹格式被刻意设计得很简单：JSONL，每行一个事件，任何语言十分钟内即可写出。最快的获取方式是使用代理，零代码改动，任何语言均可。将 Agent 指向该代理并照常运行，每次 LLM 调用、工具调用和最终答案都会落入轨迹；流式传输可用，响应原样通过。若驱动多个场景，可在每个请求上发送 x-whatbroke-run 头来命名运行。 Node SDK 可包装现有客户端并自动记录，rec.wrapAnthropic(client) 对 Anthropic SDK 同样有效；其他情况可使用 rec.llmCall()、rec.toolCall()、rec.output()、rec.end()，或自行编写 JSONL。Python 方式形状相同（pip install whatbroke-recorder，零依赖），rec.wrap_anthropic(client) 同样支持同步与异步客户端。从 Python、Node 和代理记录的轨迹可以相互比较。
导入现有轨迹 如果已经在追踪 Agent，可用 whatbroke import 将现有内容转换为可比较的 JSONL，无需重新记录。格式从文件自动检测，--format otel|langfuse|langsmith 可强制指定，--run <name> 设置运行名称，-o 选择输出路径。导入过程会打印源数据未携带的内容（如成本、工具参数），以便了解哪些发现无法显示。
行为契约 差异比较需要两份轨迹，而有时只需声明必须始终成立的条件，并对每次运行进行检查。契约是一个与代码一起提交的 JSON 文件，rules 应用于每次运行，runs 映射可按场景覆盖。不想手写？可以从一个良好的基线学习，生成包含每个样本调用过的工具、观测最大值加 50% 的成本/延迟预算以及预期状态的起始契约。报告会打印契约哈希，便于在 CI 日志中区分「Agent 变了」还是「有人改了契约」。采样轨迹会按规则报告违规率而非直接失败。任何违规时退出码为 1（可用 --fail-on never 禁用），同样支持 --md 和 --json 输出。
监视模式 迭代提示词意味着反复运行相同的差异比较。whatbroke watch 可以固定基线、将记录器指向当前轨迹，每当文件变化时终端重新渲染差异。当前文件不必已存在；写了一半的行也没关系，监视器会等待写入稳定并保留最后一次良好报告。Ctrl-c 停止，--no-clear 保留滚动回看。
CI 集成 两个命令都可作为复合动作运行，Markdown 报告会出现在任务摘要中，也支持前后 diff。在 CI 中，为 diff 添加 --fail-on changed，参数漂移会和破坏性发现一起导致构建失败。
与评估工具的关系 评估套件针对评分标准为每个版本打分，而 whatbroke 回答的是另一个问题：这两个版本之间到底发生了什么变化，精确到工具调用层面，不需要编写评分标准，也不需要付费的评判模型。它适合在新模型发布五分钟后就运行，然后决定评估套件是否还需要跑。
特点与限制 确定性、离线、无需 API 密钥、无需账号，轨迹永远不会离开本机。支持多采样运行，使不稳定行为以波动率而非噪声的形式呈现；代理捕获无需改动代码；提供 OpenTelemetry、Langfuse、LangSmith 轨迹导入；提供行为契约作为无基线时的护栏；提供 Python 记录器；提供 watch 模式；语义输出比较为可选功能，需自带密钥。已知限制：部分导入源中工具参数和模型输出为可选属性，若未被捕获则相应比较为空；Langfuse 免费层没有扁平文件导出，需先通过 SDK 导出；Langfuse 延迟从时间戳重新计算，因为导出的延迟字段在不同集成版本间单位有变化。具体平台支持与收费方式，资料中暂未提供更多信息。
