Codex Agent工程实战：测试与可观测性三层验证法

系列终章：验证Agent行为不能只看模型最后说了什么，而要沿着「模型决策→宿主执行→结果回写→状态达成」整条链路找证据。

前12章我们走完了Codex如何推进任务、调用工具、管理上下文、操作界面以及中断恢复。但改完系统后，心里往往没底：工具调用正确吗？审批拒绝后真的停了吗？恢复对话后下一次请求带上了该有的信息吗？这些问题需要单独拿证据证明。这一章就从Codex源码中的测试辅助设施出发，看哪些问题可以固定下来做反复验证，哪些必须留给真实场景判断。

三层验证框架：从固定规则到真实任务

验证Agent行为最忌讳只看最后那句自然语言输出。模型说「问题修好了」，只证明它生成了这句话，不代表它改了文件、跑了相关测试、满足了原始要求。这里面有三个极易混淆的位置：模型认为本轮推理结束、工具返回表示执行达到自身成功条件、用户目标是否真正完成——最后一个必须结合真实文件和任务要求判断。

Codex的测试体系可以拆成三层：

第一层：局部规则测试。给固定输入必须得到固定结果，比如工具输出如何截断、调用参数如何处理。范围小、执行快、稳定性高。

第二层：宿主流程测试。假设模型返回一个工具调用，宿主是否正确地执行、记录结果、构造下一次请求。这一层用可控响应替代真实模型，让测试每次走到同一位置。

第三层：真实任务验收。给一个实际仓库、一个真实问题，看模型和工具协同工作后是否满足验收条件。这一层能发现前两层看不到的悬殊——比如工具漏掉要求——但结果更依赖模型、环境和任务本身。

这三层是递进关系。任务验收放在最下层，因为它需要前面几层的证据共同支撑。集成测试能验证结果回写，但不能因此断定模型在所有真实任务里都会选对工具或选对证据。

用可控响应流复现模型行为

Codex源码里有一组很实用的测试工具，可以拼出模型的响应流：先返回一个函数调用条目，再返回响应完成的时间；下一次请求收到另一段预设响应。测试因此能精确控制模型什么时候要求调用工具。对应的辅助函数把这几段响应顺序挂到本地模拟服务上，Codex仍然走自己的请求和工具处理流程，只是收到的模型输出由测试安排好了。

另一侧，模拟服务会捕捉Codex实际发出的请求，我们就能检查第二次请求有没有带上第一次调用的结果——callid对不对、顺序有没有错。这种测试特别适合固定以前踩过的坑：把当时导致错误的调用顺序固化下来，改完代码重复跑。

但必须记住：模拟模型总会返回我们想要的内容，它不能替代真实模型「能否选对动作」的验证。

callid（调用ID） 是工具调用与结果之间的唯一关联标识。在OpenAI函数调用协议中，模型每次发起工具调用时会生成一个call_id，宿主执行工具后必须将结果与对应的call_id配对回传，模型才能正确理解哪个结果属于哪个调用。Codex的测试特别关注callid，因为一旦关联错乱（例如结果挂到了错误的调用上），模型就会基于错误信息继续推理，导致行为偏差。这也是为什么断言要检查callid的对齐，而不仅仅是工具名和参数。

断言应该写在哪里

响应可控之后，断言位置决定测试质量。Codex的做法分三处：

1. 调用本身：工具名对不对、参数是不是预期那组。
2. 调用与结果的关联：尤其是callid，确保结果挂回正确的调用。
3. 结果最终去了哪里：第一次工具返回测试失败，下一次请求里就应该能找到对应结果。测试辅助对象提供读取请求列表、按callid查找函数输出的方法；工具生命周期测试还会记录工具启动时看到的会话历史，用来核对顺序和内容。

如果工具会改文件，必须读取实际文件检查变化——只看到模型提出一次修改调用，不能证明文件改对了。涉及审批拒绝时，反过来检查不该出现的副作用有没有出现。这些断言最好用用户可观察的结果来表达，而不是绑定内部函数拆分；只要调用关系和最终行为一致，实现结构变化就不该导致测试集体修改。

并发测试：同步屏障比耗时断言可靠

测并发最容易写出不可靠判断：两个任务都很快结束，就认为它们一定并行——机器快慢、进程启动、系统调用都会影响结果。Codex的安排更具体：让两个测试工具都到达同一个同步屏障，只有两个都参与才继续往下执行。如果执行层把它们串行跑，第一个会等到屏障超时，从而暴露串行问题。

Codex保留了较宽松的耗时上限，给慢一点的CI调度留余量——不需要把某个毫秒数当成所有环境的性能承诺。而且执行顺序、完成顺序、写入历史的顺序是三个不同问题：证明两个工具同时在跑之后，还要检查结果如何归集，不能从一个并发测试推出所有排序语义都正确。

同步屏障（barrier） 是一种并发编程原语，它要求指定数量的线程或任务都到达某个点后，才能一起继续执行。在测试中，屏障用来验证两个操作是否真正并行：如果宿主串行执行工具，第一个工具会一直等待屏障超时，从而暴露问题。与依赖耗时阈值相比，屏障不依赖机器速度，结果更确定。但屏障只能证明“同时运行”，不能证明结果归集顺序正确，因此仍需额外断言检查结果如何写入历史。

失败用例与可观测性：两条腿走路

正常完成的用例只覆盖一部分。Agent真正难查的地方，常是任务走到一半被拒绝、被取消，或恢复后少了一段历史。失败用例要先写清预期：审批拒绝后不应产生被拒动作的副作用；运行中追加的输入要在允许消费的位置进入后续请求；压缩并恢复后，当前可见历史应保留约定内容。这份仓库分别有审批、输入提交、压缩恢复、分叉等测试，检查对象各不相同，而不是用一个「出错时也能结束」的断言代替。

测试帮我们提前发现问题，运行时记录帮我们解释已经发生的事——两个维度。如果日志里只有「开始了」「结束了」，很难判断是不是同一个任务。Codex的遥测带有会话信息、工具决策和工具结果，记录工具名称、命名空间和call ID，这样能把某次许可判断和后续执行结果对应起来。请求记录包含耗时、状态、尝试次数；工具结果还有一个进程内递增序号，表示结果被记录的顺序——不是工具开始的顺序，也不是重启后仍连续的永久编号。并发下不能靠它做调用关联。

排错页面时，我会先让同一次调用的几段记录连起来，再考虑加多少图表。用户说「刚才那一步卡住了」，我们才有机会定位是在请求审批还是工具执行阶段。记录越多排错越方便，但也带来体积和信息暴露问题：工具结果事件里的完整日志可包含参数和受限输出预览；追踪事件使用参数长度、输出长度、函数和工具来源等元数据。两边共享调用ID、报时、成功标记和预览截断信息。输出预览按预算截断，尽量停在字符边界并追加说明——这个标记只说明遥测层删掉了内容，不能证明原始工具结果在更早阶段一直完整。用户提示词有单独记录开关，关闭时用占位符替代，但别理解成所有日志里的敏感信息都会自动清除；部署时仍需检查工具参数、日志保留范围和读取权限。

遥测（telemetry） 在这里指Agent运行时产生的结构化事件记录，包括请求尝试、工具决策、工具结果等。Codex的遥测事件携带会话ID、调用ID、工具名称和命名空间，目的是将一次调用的多个阶段串联起来。工具结果事件还有一个进程内递增序号，表示结果被记录的顺序，而非工具开始顺序或持久化编号。这些元数据帮助排错时还原时间线，但需注意预览截断标记只说明遥测层删减，不代表原始结果完整性。

性能排错：先拆时间线再改超时

用户抱怨「任务又跑很久」，只看总耗时不够：可能模型请求重试了几次、可能在等许可、也可能命令进程本身没结束。要拆时间线找到时间花在哪一段：请求侧看尝试次数、状态和耗时；工具侧看决策记录、调用ID、执行耗时和结果；还需知道当前轮次状态，结合会话事件和界面显示判断。不是每项等待都有现成独立计时器，缺少时要补观测再改。重复请求查重试原因，等待确认把待办状态展示清楚，命令慢看进程和输出——别没定位原因就放大模型或所有超时时间。

运行快也不等于任务做对。性能指标要解释开销、文件和测试结果、用户要求决定的验收，几类工具一起看，优化才不会只剩一条越来越短的耗时曲线。

收尾：把故障变成可复现的证据

整个系列合起来是一条完整链路：任务进入后模型依据上下文决策，工具经过权限和执行处理，结果写入记录，下一次请求继续使用；任务变长要管理进程和上下文，中途新要求要处理输入，重启后要重建可恢复状态，测试和可观测性沿流程安排——重要规则用固定输入检查，宿主流程用可控响应复现，真实任务按实际产物验收，运行中把必要事件关联起来，遇到故障才能定位偏差位置。

最后，把解决过的问题留下来：能稳定复现的故障补充回归用例；属于真实场景判断的问题，把验收条件和场景保存清楚。这样下次调整工具权限或上下文策略时，才有东西可以对照。如果你也在准备做一个Agent，建议先拿一个小任务，把输入、调用、结果、期望条件和验证证据这五项跑完整，再考虑增加能力——每多加一个机制，就补上对应的状态检查点。