Codex 系统手册

共享扩展后端和 rollout trace 模型

stage-18.4.63 个文件

这一阶段不是系统开机或干活的主循环,而是幕后用的“记账格式”。它规定追踪记录该怎么写,方便不同模块按同一套说法交换数据。session 文件像登记簿,说明一次运行和智能体线程是进行中、成功、失败还是被打断。runtime 文件像流水账模板,记录模型执行、工具调用、终端操作、压缩历史和多智能体通信。payload 文件像附件索引,大请求、大响应、大日志不塞进主记录,只留下外部文件地址。三者配合,把一次运行的过程轻量、清楚地保存下来。

本阶段的文件3

跟踪会话结构

这些模型建立顶层 rollout 跟踪生命周期,并定义存在于该会话和线程结构中的运行时执行对象。

rollout-trace/src/model/session.rs源码 ↗
data_modelcross-cutting

这个文件主要是在给追踪数据定规矩。可以把它想成一张表格模板:每个参与运行的智能体线程是谁、从哪里来、什么时候开始、什么时候结束、状态如何、它看过哪些对话内容,都要按这里的格式记录。这样后面的查看器、搜索工具或分析程序才不会各说各话。这里特别区分了“整个 rollout 的状态”和“某个线程自己的状态”。rollout 可以理解成一次完整的多智能体运行;线程则是其中一个参与者,根交互会话和后来派生出来的子智能体都用同一种结构表示。文件还用 ExecutionWindow 记录开始和结束时间,以及事件序号。时间适合展示给人看,事件序号更适合判断真实先后顺序,因为两个事件可能发生在同一毫秒。整体上,这个文件不做计算,而是定义可靠的数据形状,保证运行过程能被准确保存、传输和重放。

rollout-trace/src/model/runtime.rs源码 ↗
data_modelcross-cutting

这个文件像一本运行日志的表格模板。系统运行时会发生很多事:模型可能写一段 JavaScript 让运行环境执行,也可能调用工具、启动终端命令、等待后台任务,甚至把很长的对话历史压缩成一段摘要。如果没有这些统一的数据结构,后面的调试器、回放器或可视化界面就很难知道“谁在什么时候做了什么、结果是什么、模型看到了哪些内容”。这里的结构体(带字段的数据盒子)负责描述每类事情,例如 CodeCell 记录一次代码单元的生命周期,ToolCall 记录一次工具调用,TerminalOperation 记录一次终端命令或输入,InteractionEdge 记录不同对象之间的信息流向。它们都支持 serde 的序列化和反序列化,也就是可以方便地变成 JSON 等格式保存,之后再读回来。

载荷引用

此模块提供轻量级标识符,供精简跟踪模型指向外部原始载荷工件。

rollout-trace/src/payload.rs源码 ↗
data_modelcross-cutting

在一次 rollout 追踪里,可能会有很多很大的原始内容,比如模型请求、模型返回、工具执行结果、终端日志等。如果全都直接塞进主追踪数据里,文件会很大,浏览器打开也会慢。这个文件就像给大件行李做“寄存单”:主追踪里只保存一个 RawPayloadRef,里面有稳定的编号 raw_payload_id、这个 payload 是什么类型 kind、以及它在追踪包里的相对路径 path。RawPayloadKind 则列出这些大内容的大致角色,比如推理请求、工具结果、终端事件、会话元数据等。这样界面在展示时间线时可以先轻装上阵,需要看细节时再按路径打开对应的原始文件。