AI Agent库的兼容性不止语义版本号

一个库在发布时可能保留了所有导出的 TypeScript 类型，但用户的实际观察行为仍然会发生变化。

一个适配器可能捕获不同的字段。一次 trace 检查可能对重复工具做出不同解释。一个 CLI 命令可能返回新的退出码。一个脱敏配置可能移除更多数据。一条持久化的 trace 可能仍然可解析，但重构后会得到不同的执行树。

Semantic Versioning 仍然是必要的。但对于 AI Agent 工具链而言，它并不是完整的兼容性故事。

我维护着 AgentInspect，一个 TypeScript 先行的本地证据调试器和轨迹测试工具包。维护这个项目让我开始把兼容性看作多个表面而非单一的程序包 API。

本文示例涉及 agent-inspect@6.19.0、持久化 schema 1.0 以及 Node.js 20 或更高版本。

Map every compatibility surface

对于一个 Agent 库，至少要审查这些契约：

SemVer 描述了发布的程序包版本如何传达兼容性，但它不能决定你的用户依赖哪些行为。维护者必须将这些清单明确化。

"The type still compiles" is a weak test

考虑一个适配器选项：

type CaptureMode = "metadata-only" | "preview";

假设两个适配器都接受 preview，但一个静默地只记录元数据。后续版本使 preview 行为一致，并添加了有限的、脱敏后的预览。公共的联合类型没有变化，但配置的含义变了。

这类改进是受欢迎的，但它仍然值得：

• 在发布说明中描述该行为变化；
• 提供明确的隐私指导；
• 适配器级别的前后对比 fixture；
• 证明 metadata-only 仍为默认值的测试；
• 证明没有发生意外网络传输的测试。

AgentInspect 6.18.0 在 bounded preview 一致性方面的工作就是一个真实案例，说明为什么运行时语义需要自己的变更记录，而不是只靠 API 签名。

Persisted artifacts need reader contracts

本地 trace 的生命周期可能超过产生它的代码。读取者应该能够：

• 正确打开 schema；
• 显式迁移它；或
• 给出可操作的错误后拒绝它。

不要"尽力而为"地将未知字段塞进一个看似合理实则虚假的树中。

Golden fixture 使这变得可测试：

fixtures/
  v0.1/minimal-success.jsonl
  v1.0/parallel-tools.jsonl
  v1.0/multi-run-session.jsonl
  malformed/missing-parent.jsonl

每个版本都应该用当前的读取器、检查器、报告生成器和导出器来运行支持的 historical fixture。对于自定义摄入，fixture 契约应该覆盖从外部事件到规范读取模型的映射。

6.19.0 版本添加了自定义 TraceReader 编写和更丰富的失败角色互操作性。这些能力增加了集成的数量；也增加了测试架构意图的重要性，而不仅仅是文件是否被解析。

CLI exit codes are an API

人类阅读 CLI 文本输出。CI 读取退出状态和 JSON。

措辞的无害变更可以接受。将失败契约从 exit 1 改为 exit 0、重命名 JSON key、或者将诊断信息从 stderr 打印到 stdout，这些都会在不改变任何 TypeScript 声明的情况下破坏自动化。

为以下场景维护 fixture：

• 成功和失败的检查；
• 未知的 schema 版本；
• 完整性验证失败。

记录哪些输出是机器稳定的，哪些是面向人类的展示。

Privacy changes deserve a higher bar

捕获默认值和脱敏语义是具有安全影响的兼容性问题。一个看起来很小的变更——比如在只有元数据的地方写入 prompt 预览——可能违反用户的数据边界。

对于每个版本，测试负面承诺：

metadata-only capture contains no prompt or response preview
redaction produces a separate artifact
no adapter uploads by default
integrity verification does not imply safety certification

这些断言和"命令成功执行"一样重要。

Publish a behavioral compatibility note

对于每个变更，我现在发现四个问题比"主版本还是次版本？"更有用：

• 哪个表面发生了变化？
• 现有用户会观察到什么？
• 哪些旧 artifacts 和配置被测试过了？
• 需要什么迁移或 opt-in？

将答案转化为机器可比较的发布 artifact：

{
  "packageVersion": "6.19.0",
  "node": ">=20",
  "persistedSchemasRead": ["0.1", "0.2", "1.0"],
  "defaultWriterSchema": "1.0",
  "stableCliContracts": ["check", "gate", "report"],
  "privacyDefaults": { "capture": "metadata-only", "upload": false }
}

上述字段阐明了兼容性清单的形态；它们应该从精确的发布契约生成，而不是手工复制。将其与 golden traces 和 CLI 快照一起存放，这样升级既能揭示预期的变化，也能揭示意外的变化。

SemVer 仍然是发布上的标签。行为说明则解释了其背后的工程现实。

AI Agent 库介于非确定性模型和确定性软件系统之间。它们的职责通常是将行为转化为证据、策略或控制。因此用户依赖的不仅仅是函数签名。他们依赖的是：什么被捕获了、如何被解释的、CI 看到了什么、以及哪些数据被排除在外。

更广泛的契约也值得被版本化管理。

Semantic Versioning 2.0.0

AgentInspect changelog

AgentInspect 6.19.0 source