TracePact：在生产之前捕获 AI 代理工具调用回归

Source: Dev.to

TracePact 的功能

TracePact 是一个面向 AI 代理的行为测试框架。它在 工具调用层面 工作，而不是文本层面。

1. 编写行为合约

import { TraceBuilder } from '@tracepact/vitest';

const trace = new TraceBuilder()
  .addCall('read_file', { path: 'src/service.ts' }, '...')
  .addCall('write_file', { path: 'src/service.ts', content: '...' })
  .addCall('run_tests', {}, 'PASS')
  .build();

// Did it read before writing?
expect(trace).toHaveCalledToolsInOrder([
  'read_file',
  'write_file',
  'run_tests'
]);

// Did it avoid shell?
expect(trace).toNotHaveCalledTool('bash');

无需 API 调用。无需 token。毫秒级运行。

2. 记录与回放

# Record a baseline (one‑time, live)
npx tracepact run --live --record

# Replay without API calls (instant, deterministic)
npx tracepact run --replay ./cassettes

3. 对比运行以捕获漂移

npx tracepact diff baseline.json latest.json --fail-on warn

示例输出

3 changes detected:
- read_file (seq 1) (removed)
+ write_file (seq 3) (added)
~ bash.cmd: "npm test" -> "npm run build"

Summary: 1 removed, 1 added, 1 arg changed

过滤噪声参数和不相关工具

npx tracepact diff baseline.json latest.json \
  --ignore-keys timestamp,requestId \
  --ignore-tools read_file

严重性级别

• none – 完全相同
• warn – 参数已更改
• block – 工具被添加/删除

在 CI 中使用 --fail-on 来控制部署。

适用场景

• 编码代理 – 写入前先读取，完成前运行测试，绝不编辑受限文件
• 运维代理 – 重启前检查，采取行动前核实证据
• 工作流代理 – 变更前验证，避免重复副作用
• 内部助理 – 为正确任务使用正确的系统

不太适用的情况

纯聊天机器人、风格评估、创意任务，或仅文本输出重要的系统。TracePact 关注 行为保证，而非响应质量。

IDE 的 MCP 服务器

TracePact 提供一个 MCP 服务器，可与 Claude Code、Cursor 和 Windsurf 配合使用：

{
  "mcpServers": {
    "tracepact": {
      "command": "npx",
      "args": ["@tracepact/mcp-server"]
    }
  }
}

可用工具：tracepact_audit、tracepact_run、tracepact_capture、tracepact_replay、tracepact_diff、tracepact_list_tests。

入门指南

npm install @tracepact/core @tracepact/vitest @tracepact/cli
npx tracepact init
npx tracepact

GitHub:

我们构建它的初衷是因为提示词或模型的微小变化会悄然破坏代理的行为，而输出看起来仍然正常。如果你正在测试 AI 代理，欢迎分享你目前是如何处理工具调用回归的。