TraceMotive v0.3：AI Agent 执行轨迹的结构化比对调试工具

我刚刚发布了 TraceMotive v0.3.0。

TraceMotive 是一款开源的、本地优先的 AI Agent 执行调试工具。

https://github.com/doraemonfv-glitch/tracemotive

想象你有两个 Agent 执行记录。

传统追踪工具给你的是原始执行数据，这当然有用——但你仍然需要自己回答那个困难的问题：

我该从哪里开始看？

这就是 v0.3 想要专注解决的问题。

reference run
      vs
changed run
      ↓
structural alignment
      ↓
first evidence-supported behavioral divergence
      ↓
deterministic findings
      ↓
investigation starting point

这里的关键词是 supported（有证据支持的）。

TraceMotive 不会试图猜测根本原因。

它只识别那些有现有结构证据支撑的、第一个行为差异。

v0.3 可以产生确定性的发现，例如：

执行子树被添加或移除

工具调用重复次数发生变化

它也能揭示仅上下文层面的变化，例如：

请求参数发生了改变

但这些上下文变化不会自动成为调查起点。

不确定性是一项特性

调试器不应该假装知道自己不知道的事情。

举例来说，重复调用可能很难安全地对齐。

Run A:
weather()
weather()
weather()

Run B:
weather()
weather()
weather()

仅仅因为左边第一个调用和右边第一个调用位置相同，就将它们配对，可能会产生错误的匹配。

TraceMotive 有意避免了这种情况。

当证据模糊、不完整、被编辑或不可用时，结果可能是：

uncertain

而不是凭空编造一个答案。

调查优先的 UI

v0.3 还引入了全新的对比界面。

UI 不再首先展示完整的原始对比，而是优先呈现：

当前调查状态

第一个有证据支撑的调查点

该处观察到的证据

其他行为观察

详细原始对比

现有的详细对比仍可通过 /api/v2 获取。

新的调查 API 位于：

GET /api/v3/compare/{left_trace_id}/{right_trace_id}

无需 API Key 即可试用

v0.3 包含一个确定性的本地演示。

pip install tracemotive==0.3.0

tracemotive serve

然后在另一个终端打开：

tracemotive demo

演示会创建一个参考执行和一个变更后的执行，并打印出一个 URL，直接在调查 UI 中打开。

演示无需 OpenAI API Key。

隐私模式对我来说仍然很重要。

仅 loopback 回环地址的 Collector/UI 服务

本地 SQLite 持久化

隐私可控的内容捕获

传输前脱敏

无 TraceMotive 分析服务

无外部 TraceMotive 遥测

TraceMotive 不声明的事项

TraceMotive 不证明因果关系。

即"This change caused the failure"（这个变更导致了失败）。

它说的是：

"This is the first behavioral divergence supported by the evidence. This is a reasonable place to begin investigating."

（这是证据支持的第一个行为分歧。这是一个开始调查的合理起点。）

这个区别成为了 v0.3 最重要的设计原则。

下一个重要方向是更广泛的真实世界集成验证。

OpenAI Agents SDK 目前是主要验证过的适配器。

我也想继续测试这个调查工作流在真实 Agent 失败场景下是否真的有用，而不是仅仅添加更多可观测性功能。

如果你在构建 AI Agent，我非常希望得到反馈——特别是 TraceMotive 变得过于保守或指向错误方向的例子。

https://github.com/doraemonfv-glitch/tracemotive

pip install tracemotive==0.3.0