别把 Agent 轨迹只当日志：用 TraceLint 把工具调用里的结构性错误变成可复查证据
AI 编码 Agent 失败时，团队往往只看到两种信号：最终回答看起来不对，或者某个工具调用报错。两者都不足以解释问题。一次错误可能早已发生在中间：调用参数不符合工具 Schema、失败结果被后续写操作继续使用，或者 Agent 在没有任何进展的情况下重复请求同一个工具。
TraceLint 是一个面向工具调用型 Agent 执行轨迹的确定性 linter。它不评价最终自然语言答案，也不再调用一个 LLM 来充当裁判；它读取调用、结果、Schema 和来源信息等结构化数据，用规则输出可定位的证据。对希望把 Agent 行为接进 CI、回归测试或事故复盘的团队，这是一种比“再让模型判断一次”更容易复现和审计的路径。
本文用一个订单取消工作流说明它适合解决什么问题、如何接入，以及哪些结论不能从一次 lint 结果中直接推出。
先区分：最终答案错误，还是执行链已经断裂
假设客服 Agent 要取消订单。它先查询订单，再调用取消接口，最后给用户回复结果。传统日志可能记录了很多文本，却没有把以下问题提升为可测试的工程信号：
cancel_order收到了不符合 JSON Schema 的参数；- 查询工具返回错误，但错误结果中的值仍被拿去发起有副作用的取消；
- 某次调用的参数不是有效 JSON；
- Agent 调用了并未在声明工具集中注册的工具；
- 调用在相同输入、相同结果下连续循环，却没有任何状态进展。
这些问题不必等待用户投诉后才发现。TraceLint 的目标是把它们变成带规则编号和 trace 位置的发现项。重要的是边界：它能说明“调用结构存在风险”或“已违反可验证约束”，却不能证明 Agent 最终给出的业务结论一定正确。订单是否真的应当取消，仍取决于权限、业务规则和外部系统状态。
把 trace 和工具定义一起交给检查器
项目要求 Python 3.10 或更高版本，发布包名为 tracelint。最小安装与内置示例如下：
pip install tracelint tracelint demo --html demo.html
demo 会生成可浏览的报告，适合先确认团队理解的事件字段与工具调用顺序。真正接入流水线时，更关键的是同时提供 trace 和工具定义：
tracelint check ./trace.json --tools ./tools.json
--tools 中保存工具的 JSON Schema 与元数据。没有 Schema，检查器仍可观察一部分调用序列和结果信号，但参数是否符合某个工具的契约就无从精确判断；与值来源有关的高置信检查也会失去依据。因此，工具注册表不应只作为 Agent 运行时配置，还应像 API 契约一样进入版本控制。
TraceLint 的 check 接受单个 JSON、JSONL、JSON 数组以及多个输入文件，并声明了 native、openinference、otel、openai、langfuse 等格式。例如已有 OpenInference span 导出时，可显式指定格式：
tracelint check spans.json --format openinference
显式标明格式比“让脚本猜”更稳妥：事故发生后，团队可以确认是转换层遗漏字段，还是 Agent 本身给出了异常调用。
用规则等级决定 CI 应该拦什么
不是每一个异常模式都该阻断合并。TraceLint 将发现分为 hard_defect、hard_event 与 candidate 等层级；后两类的含义尤其值得在团队规范中写清楚。
| 场景 | 可检查的信号 | 实践建议 |
|---|---|---|
| 参数违反工具 JSON Schema | 调用参数与声明契约冲突 | 作为阻断项处理，先修调用或 Schema |
| 工具调用参数不是有效 JSON | 无法按预期解析 | 作为阻断项处理，避免把损坏事件送往生产工具 |
| 错误结果继续流入副作用调用 | 失败值被后续写操作消费 | 重点复盘恢复逻辑与状态隔离 |
| 调用了未声明的工具 | 调用名不在工具集合中 | 作为集成漂移线索，核对注册表与运行配置 |
| 无进展的重复调用 | 相同输入/结果连续出现 | 先人工判断是否为合理轮询或重试 |
| 参数来源无法推导 | 值无法从已知来源解释 | 作为可疑线索，不要直接定性为幻觉 |
其中 JSON Schema 不匹配、无效 JSON 等是结构上可确定的问题，适合设为质量门。循环、可疑来源等默认是候选项：合理的值转换、刻意的重试、外部轮询都可能触发它们。项目将“相同调用且没有进展”的模式作为候选信号，并在规则说明中把轮询和重试排除在循环判断之外；这能降低噪声，但不等于消除了业务语境。
CI 的退出码也应按等级处理：无问题时为 0，出现 hard_defect 时为 2，输入错误为 3；候选项本身不会让 CI 失败。一个稳妥的起步方式是：先把所有报告作为 PR 附件观察一周，确认候选项的真实噪声来源；再只对 Schema、无效 JSON 和明确的失败结果误用启用阻断。这样不会因为规则上线而把正常重试全部变成发布事故。
让 lint 服务于“恢复是否正确”而非只看有没有报错
Agent 的异常处理常见误区是：工具超时后重试一次、进程没有崩溃，就被当成恢复成功。实际上，重试可能重复执行写操作，也可能把上一次错误响应中的字段带入新调用。
TraceLint 提供 recovery scorecard 的命令入口，可通过内置演示注入超时、错误和限流类故障：
tracelint scorecard --demo --faults timeout,error,rate_limit --runs 5
如果团队为场景提供了成功 oracle，报告可以讨论正确性恢复率及其 Wilson 置信区间；但没有 oracle 时，得到的只是更弱的“行为恢复”指标，例如程序没有崩溃。两者不能混写。对取消订单这类带副作用的流程，oracle 至少应检查：是否只发出一次有效取消请求、状态是否最终一致、用户回复是否与订单系统记录相符。
把这类检查加入回归集后，价值不在于为 Agent 打一个抽象分数，而在于固定失败模式。每次修改工具包装层、提示词或重试策略，都能重放同一批 trace，观察是否重新出现 Schema 漂移、错误值传播或循环。
可观测性完整度决定检查上限
确定性分析并不会自动补齐缺失事实。若 trace 没有记录工具输入、结果状态、调用间关联或工具定义，规则会因为依赖字段缺失而被抑制，而不是神奇地还原完整上下文。这是正确的保守行为，却也意味着团队需要先定义采集边界。
建议把以下字段作为 Agent 工具层的最小可观测性合同：调用 ID 与父子关系、工具名、原始或规范化参数、结果状态、错误类别、是否有副作用，以及对应的 Schema 版本。对敏感参数可做脱敏或只保留可验证摘要，但不要为了脱敏把判断恢复链所需的状态关系一并删掉。
TraceLint 目前在项目元数据中仍标为 Alpha，适合先在离线 trace、测试环境与 PR 报告中使用，而不是未经评估地当作生产裁决器。它最适合回答的问题是：“这条执行链是否违反了我们已经明确的结构约束？”当答案是肯定的，开发者可以直接回到具体调用和工具契约修复；当答案只是候选项，则应连同业务语境进入人工审阅。
结语
Agent 系统的可靠性不只取决于模型是否能写出漂亮回答，也取决于每一次工具调用是否遵守契约、错误是否被隔离、重试是否真的带来进展。TraceLint 提供的是一层确定性、可复查的执行链检查：它不能代替业务验证，也不该把候选信号伪装成事实；但在已有 trace 和工具 Schema 的团队里，它能把“感觉 Agent 跑偏了”转化为可重复的工程问题。