Chronicle：给 LLM Agent 做回归测试——像数据库事务一样重放每一步

一个真实的困境

你的 AI 客服 Agent 上线了。它处理退款、下单、查询订单——一切正常。直到有一天，一个用户说："我让它退款，它居然又下了一笔单！"

你查看日志，发现问题出在 Agent 的某次工具调用——它先调了 place_order，又调了 refund，顺序错了。你修了一个 guard（守卫条件），让它先检查是否已有订单。

怎么验证这个修复有效？

方法一：重新跑一遍 Agent，让它处理同样的请求。但 LLM 是非确定性的——同样的输入，它可能走完全不同的路径。你修的 bug 可能根本没被触发。

方法二：写 mock，手动构造测试用例。但 mock 是你"猜"的——和真实运行的行为可能完全不同。而且 mock-heavy 测试被证明在验证真实交互方面效果很差。

方法三：用 Chronicle。

Chronicle 是什么

Chronicle 是一个为 LLM Agent 设计的"记录-重放-测试"框架。它的核心思想来自一个古老的软件工程传统：确定性记录-重放（deterministic record-replay）。

但 Chronicle 做了一个关键创新：在语义边界（semantic boundaries）处记录，而不是在系统调用处。

什么是语义边界？

一个 LLM Agent 的执行轨迹由三种"边界"组成：

1. 模型调用：Agent 调用 LLM 生成下一步
2. 工具调用：Agent 调用外部工具（下单、退款、查询）
3. 路由决策：Agent 决定走哪条分支

每个边界都是一个"可重放点"——在这里，执行可以分叉：要么用记录的结果，要么重新执行。

三种重放模式

Chronicle 支持三种重放：

1. Full Replay（全重放）：所有边界都用记录的结果。零模型调用，完全确定性。用于验证"胶水代码"（边界之间的逻辑）没有改变。

2. Cut-Point Replay（切点重放）：选一部分边界"live"（重新执行），其余用记录。用于测试修复——比如只让 place_order 工具 live，其余 stub，就能测试新的 guard 是否拦截了错误调用。

3. Any Subset Live（任意子集 live）：任意组合哪些边界 live、哪些 stub。比如工具 live、模型 stub——测试工具 gate 而不重新调用模型。

技术实现

记录

开发者只需在代码中加一行注解：

@boundary("place_order", kind="tool")
def place_order(symbol, qty):
    ...

每次这个函数被调用，Chronicle 记录一个"信封"（envelope），包含：

• 输入参数
• 输出结果
• 元数据（模型版本、采样参数等，用于检测 drift）

记录开销：每次边界穿越仅 23 微秒，相对于一次模型调用（~300ms）的 0.008%。存储增长：每次穿越最多 1.44 KB。

重放

重放时，每个边界按计划返回记录结果或重新执行。边界用"名字+出现次数"寻址——比如 agent[1]、agent[2]、place_order[1]。

测试

结构断言（structural assertion）：检查 Agent 做了什么——调用了哪个工具、参数是什么、是否拒绝了受保护的操作。在 full replay 下完全确定性，不需要模型调用。

咨询性 LLM-as-judge：对于非结构化属性（忠实度、安全性），用 LLM 判断。但论文明确说这不评估其可靠性。

实验结果

1. 记录开销几乎为零

在真实 Qwen3.5 4B 调用上对比：

• 开启记录：平均 3136ms（标准差 379ms）
• 关闭记录：平均 3045ms（标准差 387ms）
• 差异：+91ms，95% 置信区间 [-59, +241]——与零无法区分

23 微秒的记录开销，比模型调用的运行间波动小四个数量级。

2. Full Replay 完全确定性

20 次重复重放，0 次分歧，0 次 live 边界穿越。完全比特级稳定。

3. Cut-Point 测试在已知事件上的效果

6 个精心策划的事件（unguarded fail / guarded pass / benign pass）：

• 6/6 正确判定：unguarded 被捕获，guarded fix 和良性修改通过
• 30 个无关修改被容忍：不改变安全不变量的重写不会误报

4. 突变测试：比全 stub 基线强多少？

生成了 192 个一阶突变体（修改关系运算符、逻辑运算符、常量等）：

• Cut-Point 测试杀死 51 个
• 全 stub 基线杀死 0 个——因为工具从不真正执行

这 51 个被杀死的突变体，都是改变了工具行为、被 cut-point 测试检测到的。其余 141 个中，110 个是任何基于这些记录的测试都无法杀死的（改变了 stub 不会触发的代码路径）。

5. CI 工作流

一个团队记录一次生产事件，提交 trace 和 cut-point 断言到代码仓库。之后每次提交都运行这个测试，零模型调用。当边界的契约改变（stub 的边界被穿越次数不同），计数检查会标记 fixture 需要重新记录，而不是静默通过。

和现有方法的区别

vs 传统确定性重放

传统方法（如 rr）记录整个执行，忠实重放。Chronicle 在语义边界重放，可以选择性运行新代码——测试修复而非重放运行。

vs Mock 测试

Mock 是手写的，和真实行为可能完全不同。Chronicle 用真实记录的信封替代手写 mock，任意子集可以 live。

vs 失败归因方法

失败归因方法（rewinding、editing）是修改记录来理解过去失败的原因。Chronicle 是在切点执行新代码，记录结果作为回归测试。

vs Agent Benchmark

Benchmark 是构造的评估环境。Chronicle 的场景来自真实记录的失败，不是构造的。

更深的洞察

1. "边界"是 Agent 测试的天然单元

传统软件测试的单元是函数或模块。但 LLM Agent 的执行是"模型调用→工具调用→路由决策"的流，传统单元不适用。

Chronicle 的洞察是：语义边界才是正确的测试单元。每个边界是一个可观测、可重放、可断言的点。在边界处记录，就能重建整个轨迹。

2. "切点"思想：测试修复而非重放

Cut-Point 的精髓是：你不需要重放整个执行，只需要在关键点重新执行新代码。

这和数据库的"检查点"（checkpoint）思想类似——你不需要从头重放整个事务日志，只需要从检查点开始应用新变更。

在 Agent 测试中，这意味着：修复一个工具的 guard，只需要让这个工具 live，其余 stub。测试成本从"重新运行整个 Agent"降到"运行一个工具"。

3. "信封"作为不可变契约

每个信封是一个边界的完整契约：输入、输出、元数据。这个不可变性有两个好处：

• 可重现：任何人都能从信封重放
• 可演化：当边界契约改变（参数变了、调用次数变了），计数检查会检测到，强制重新记录

这和"事务化技能管理"的 Local Gate + Big Gate 思想一致——修改不能破坏局部一致性，全局指标净正向才提交。

4. "0 模型调用"的 CI 测试

这是 Chronicle 最实用的一点：记录一次，CI 永久运行，零模型调用。

LLM Agent 测试的最大痛点是成本——每次测试都要调用 LLM，又慢又贵。Chronicle 的 full replay 模式完全不需要模型调用，让 Agent 回归测试可以像传统软件测试一样频繁运行。

5. "判断-闸门解耦"的体现

Cut-Point 测试的 guard 机制是"判断-闸门解耦"的实例：

• 判断：guard 检查是否已有订单
• 闸门：guard 决定是否阻止 place_order

Chronicle 的测试验证的是"闸门"是否正确工作——在记录的真实输入下，guard 是否拦截了错误调用。

局限

• 不捕获流式响应：记录的是组装后的完整响应
• 不支持并行工具调用：目前只支持顺序执行
• 不重抛异常：stub 边界记录的异常不会被重抛
• 确定性部分是构造的：benchmark 的模型边界是模拟的，不是真实非确定性 provider
• 安全限制：对破坏性工具的 live cut-point 应该在沙箱中运行
• 密钥处理：记录在写入前 redact，但需要信任 redaction 逻辑

开源

• 论文：https://arxiv.org/abs/2609.20625
• 代码：https://github.com/theagentplane/chronicle

一句话总结：Chronicle 在 LLM Agent 的语义边界（模型调用、工具调用、路由决策）处记录不可写信封，支持全重放（零模型调用、完全确定）和切点重放（任意子集 live、其余 stub）。记录开销 23 微秒/次，20 次重放 0 分歧，在 192 个突变体中杀死 51 个（全 stub 基线杀死 0 个）。核心思想：像数据库事务一样管理 Agent 执行——记录一次，CI 永久运行，零模型调用。