最新文章

第十章从设计角度解释了 rollout 为什么是 canonical replay log，以及 resume、fork、rollback、revert 如何建立在 replay 之上。 本附录进一步落到磁盘格式：一条 JSONL 记录长什么样、有哪些 type、每种 payload 保存什么、不同运行场景会写出怎样的记录序列。

这里讨论的是 Codex 内部的 session rollout，不是附录 A 的 app-server JSON-RPC。两者虽然都可能采用“一行一个 JSON”，但用途、信封和兼容承诺不同。

版本基线：本文按 2026-09-07 所在代码版本整理。Rollout 会持续演进，排查其他版本时应先读取该文件自己的 session_meta.cli_version。

---

B.1 先分清三种 JSONL

Codex 周围至少有三类容易被叫作“JSONL”的数据：

数据	一行代表什么	主要消费者	是否是 session 的事实源
rollout JSONL	一条持久化记录	resume、fork、历史投影、搜索与诊断	是
app-server stdio JSONL	一条请求、响应或通知	IDE、TUI、自动化客户端	否
rollout-trace	一条更细的诊断证据	调试与离线分析	否

本附录只描述第一种。

Rollout 的默认位置是：

$CODEX_HOME/sessions/YYYY/MM/DD/
  rollout-YYYY-MM-DDThh-mm-ss-<thread_id>.jsonl

目录和文件名使用创建机器的本地时间，精确到秒；session_meta.timestamp 与每行 timestamp 则转换成 UTC。不要从文件名推导精确事件时间。

归档后位于：

$CODEX_HOME/archived_sessions/

普通 rollout 中，thread_id 同时也是 rollout_id。执行新版 revert 时，逻辑 thread ID 保持不变，但会创建新的物理 rollout：

rollout-YYYY-MM-DDThh-mm-ss-<thread_id>_<rollout_id>.jsonl

冷历史还可能被压缩成 .jsonl.zst。压缩只改变物理表示，不改变逐行解码后的逻辑 schema。

[!important] Rollout 是内部持久化协议 它需要长期向后兼容，但不是建议第三方直接生产的公共 API。读取工具应容忍新增字段和不认识的非关键记录，不应依赖字段顺序。

---

B.2 每一行的公共信封

每行都是一个独立 JSON object：

{
  "timestamp": "2026-09-07T08:30:12.345Z",
  "ordinal": 42,
  "type": "response_item",
  "payload": {
    "type": "message",
    "role": "assistant",
    "content": [
      { "type": "output_text", "text": "测试已经通过。" }
    ]
  }
}

公共字段：

字段	类型	含义
timestamp	string	记录写入时间，UTC RFC 3339，当前 writer 精确到毫秒
ordinal	uint64，可省略	paginated history 的严格递增序号；legacy history 不写
type	string	顶层记录类型，使用 snake_case
payload	object	该类型的具体载荷
metadata	object，可省略	目前只用于 response_item，位于顶层而非 payload 内

用一个类型表达式表示：

RolloutLine =
  {
    timestamp: string,
    ordinal?: uint64,
    type: RolloutItemType,
    payload: object,
    metadata?: CodexHarnessMetadata
  }

ordinal 的语义不是“当前文件第几行”，而是逻辑历史位置：

• legacy 模式没有 ordinal；
• paginated 模式从 0 开始递增；
• 若当前 rollout 引用另一个 rollout 的前缀，新文件的首个 ordinal 从被引用前缀的 end_ordinal_exclusive 继续；
• HistoryPosition 同时保存 ordinal 和 byte offset，使共享前缀既有逻辑边界，也有物理读取边界。

第一条非空记录必须是当前 rollout 自己的 session_meta。Fork 复制历史时可能在后面再次出现父线程的 session_meta，reader 只把第一条视为当前文件的 canonical identity。

---

B.3 顶层记录总表

当前 canonical RolloutItem 有 9 种：

type	payload	解决的问题
session_meta	SessionMetaLine	这份 rollout 属于谁、从哪里来、采用哪种历史模式
response_item	ResponseItem	模型真正看到的对话、reasoning、工具调用与结果
inter_agent_communication	InterAgentCommunication	agent 之间的持久化消息
inter_agent_communication_metadata	{ trigger_turn }	在裁剪或迁移历史时保留消息的唤醒语义
compacted	CompactedItem	用 replacement history 建立新的模型历史基线
turn_context	TurnContextItem	某个真实 user turn 实际使用的模型、目录与安全设置
world_state	WorldStateItem	模型可见世界状态的 full snapshot 或 merge patch
security_risk_score	SecurityRiskScore	thread 级风险分类快照，不进入模型上下文或 UI 历史
event_msg	EventMsg 的 durable 子集	turn 生命周期、token、UI item 与兼容事件

这 9 类记录不是平级地服务同一个消费者：

flowchart LR
    J["RolloutLine"] --> M["模型历史 reducer"]
    J --> U["UI 历史 reducer"]
    J --> S["Session 状态 reducer"]
    J --> Q["查询 / 索引 projection"]

    M --> R1["response_item"]
    M --> R2["compacted"]
    M --> R3["world_state"]
    M --> R4["inter_agent_communication"]

    U --> E1["event_msg"]
    U --> E2["response_item"]

    S --> S1["session_meta"]
    S --> S2["turn_context"]
    S --> S3["security_risk_score"]

同一行可能被某个 reducer 使用、被另一个 reducer 忽略。Rollout 是多种 projection 的共同输入，不是一份可以直接展示的 transcript。

---

B.4 session_meta：文件的身份页

形状：

type SessionMetaLine = {
  session_id: UUID,
  id: UUID,
  forked_from_id?: UUID,
  parent_thread_id?: UUID,
  timestamp: string,
  cwd: string,
  originator: string,
  cli_version: string,
  source: SessionSource,
  thread_source?: string,
  agent_nickname?: string,
  agent_role?: string,
  agent_path?: string,
  model_provider: string | null,
  base_instructions: BaseInstructions | null,
  dynamic_tools?: DynamicToolSpec[],
  selected_capability_roots?: SelectedCapabilityRoot[],
  memory_mode?: string,
  history_mode: "legacy" | "paginated",
  history_base?: HistoryPosition,
  subagent_history_start_ordinal?: uint64,
  multi_agent_version?: "disabled" | "v1" | "v2",
  context_window?: { window_id: string },
  git?: GitInfo
}

字段说明：

字段	作用
session_id	一棵 agent 树共享的 session 身份；旧记录缺失时回退为 id
id	用户看到的稳定 thread ID
forked_from_id	普通 fork 的来源 thread
parent_thread_id	子 agent 的父 thread
timestamp	session 创建时间；与外层每行写入时间不是同一个概念
cwd	session 建立时的工作目录
originator	创建该 session 的产品或调用方标识
cli_version	writer 版本，用于兼容诊断
source	session 从 CLI、IDE、exec、MCP、内部任务还是 sub-agent 创建
thread_source	更偏分析用途的来源分类；自定义 feature 也编码为字符串
agent_*	子 agent 的昵称、角色和 canonical path
model_provider	初始 provider；可能为 null
base_instructions	thread 级基础指令与来源；旧记录可能为 null
dynamic_tools	thread 创建时冻结的前端动态工具 spec
selected_capability_roots	前端选中的能力根
memory_mode	记忆模式；当前常见特殊值为 "disabled"
history_mode	决定后续 event_msg 的持久化形态
history_base	paginated fork/revert 引用的 immutable prefix
subagent_history_start_ordinal	子 agent 自有历史开始位置；此前内容只是继承上下文
multi_agent_version	多 agent 协议版本
context_window	初始上下文窗口 ID
git	创建时的 Git commit、branch 与 remote URL

嵌套 schema：

BaseInstructions = {
  text: string,
  provenance?: { type: "custom" }
             | { type: "model", model: string }
}

HistoryPosition = {
  thread_id: UUID,              // 名字是历史遗留，语义上指 rollout_id
  end_ordinal_exclusive: uint64,
  end_byte_offset: uint64
}

GitInfo = {
  commit_hash?: string,
  branch?: string,
  repository_url?: string
}

DynamicToolSpec =
  { type: "function", name: string, description: string,
    inputSchema: JSON, deferLoading: boolean }
  | { type: "namespace", name: string, description: string,
      tools: Array<{
        type: "function", name: string, description: string,
        inputSchema: JSON, deferLoading: boolean
      }> }

SelectedCapabilityRoot = {
  id: string,
  location: {
    type: "environment",
    environmentId: string,
    path: string
  }
}

source 是一个兼容性较强的联合类型：

SessionSource =
  "cli" | "vscode" | "exec" | "mcp" | "unknown"
  | { "custom": string }
  | { "internal": "memory_consolidation" }
  | { "subagent":
        "review"
        | "compact"
        | "memory_consolidation"
        | { "thread_spawn": {
              parent_thread_id: UUID,
              depth: int32,
              agent_path: string | null,
              agent_nickname: string | null,
              agent_role: string | null
            }}
        | { "other": string }
    }

典型首行：

{"timestamp":"2026-09-07T08:30:00.000Z","ordinal":0,"type":"session_meta","payload":{"session_id":"0199...","id":"0199...","timestamp":"2026-09-07T08:30:00.000Z","cwd":"/repo","originator":"codex_cli_rs","cli_version":"0.x.y","source":"cli","thread_source":"user","model_provider":"openai","base_instructions":{"text":"...","provenance":{"type":"model","model":"gpt-5"}},"history_mode":"paginated","context_window":{"window_id":"0199..."}}}

场景：

• 新建：作为第一行写入；
• resume：读取第一份 session_meta 恢复身份和历史模式，继续追加原文件；
• fork：新文件有自己的 session_meta，并通过 forked_from_id 或 history_base 说明来源；
• revert：id 不变，文件名中的 rollout_id 变化，history_base 指向被保留的旧前缀；
• sub-agent：session_id 与根 agent 相同，id 不同，并记录父 thread 与 agent path。

---

B.5 response_item：模型历史的原子

基本形状：

{
  "timestamp": "...",
  "ordinal": 7,
  "type": "response_item",
  "payload": { "type": "...", "...": "..." },
  "metadata": { "client_authored": true }
}

metadata 可省略：

CodexHarnessMetadata = {
  client_authored: boolean   // 默认 false
}

它说明某条 developer message 是由 app-server 客户端提供，而不是 harness 自己生成。这个信息不能塞进模型原生 item，因而作为并列 sidecar 保存。

B.5.1 公共嵌套类型

ContentItem =
  { type: "input_text", text: string }
  | { type: "input_image", image_url: string,
      detail?: "auto" | "low" | "high" | "original" }
  | { type: "input_audio", audio_url: string }
  | { type: "output_text", text: string }

AgentMessageInputContent =
  { type: "input_text", text: string }
  | { type: "encrypted_content", encrypted_content: string }

InternalChatMessageMetadataPassthrough = {
  turn_id?: string,
  create_time?: number,
  executed_tool_calls?: ExecutedToolCall[]
}

MemoryCitation = {
  entries: [{
    path: string,
    lineStart: uint32,
    lineEnd: uint32,
    note: string
  }],
  rolloutIds: string[]
}

internal_chat_message_metadata_passthrough 是 provider 侧 metadata 的保真通道。最常用的是 turn_id，用于把 item 重新关联到 turn；create_time 是带小数的 Unix 秒。消费者应保留未知字段，不应把这个对象当成稳定 UI schema。

reasoning.content 还有一条特殊的写入规则：当其中包含 reasoning_text 时，该字段不会再次序列化到 rollout；加密的 encrypted_content 才是跨轮继续传递 raw reasoning 的主要载体。

工具输出允许两种 wire shape：

FunctionCallOutput =
  string
  | Array<
      { type: "input_text", text: string }
      | { type: "input_image", image_url: string, detail?: ImageDetail }
      | { type: "input_audio", audio_url: string }
      | { type: "encrypted_content", encrypted_content: string }
    >

B.5.2 全部 durable ResponseItem

下表中的字段名就是 JSON wire name。标 ? 的字段可以省略；没有 ? 的 T | null 字段会以 null 表达未知值。

payload.type	字段
message	id?, role, content: ContentItem[], phase?: "commentary" | "final_answer", internal_chat_message_metadata_passthrough?
agent_message	id?, author, recipient, content: AgentMessageInputContent[], internal_chat_message_metadata_passthrough?
reasoning	id?, summary: [{type:"summary_text",text}], content?: [{type:"reasoning_text"|"text",text}], `encrypted_content: string
local_shell_call	id?, `call_id: string
function_call	id?, name, namespace?, arguments: string, encrypted_function_args?, call_id, internal_chat_message_metadata_passthrough?
tool_search_call	id?, `call_id: string
function_call_output	id?, call_id, output: FunctionCallOutput, internal_chat_message_metadata_passthrough?
custom_tool_call	id?, status?, call_id, name, namespace?, input: string, internal_chat_message_metadata_passthrough?
custom_tool_call_output	id?, call_id, name?, output: FunctionCallOutput, internal_chat_message_metadata_passthrough?
tool_search_output	id?, `call_id: string
web_search_call	id?, status?, action?, internal_chat_message_metadata_passthrough?
image_generation_call	id?, status, revised_prompt?, result, internal_chat_message_metadata_passthrough?
compaction	id?, encrypted_content, internal_chat_message_metadata_passthrough?
context_compaction	id?, encrypted_content?, internal_chat_message_metadata_passthrough?

不会写入 rollout 的 ResponseItem：

payload.type	原因
additional_tools	请求期控制数据，不是历史事实
compaction_trigger	请求期控制信号
未知类型（reader 映射为 Other）	当前版本不知道怎样安全 replay

local_shell_call.action：

{
  type: "exec",
  command: string[],
  timeout_ms: uint64 | null,
  working_directory: string | null,
  env: object<string,string> | null,
  user: string | null
}

web_search_call.action 使用 Responses API 的 snake_case 形态：

ResponseWebSearchAction =
  { type: "search", query?: string, queries?: string[] }
| { type: "open_page", url?: string }
| { type: "find_in_page", url?: string, pattern?: string }

一次普通工具 LOOP 的核心记录：

{"timestamp":"...","ordinal":4,"type":"response_item","payload":{"type":"message","id":"msg_user","role":"user","content":[{"type":"input_text","text":"运行测试"}]}}
{"timestamp":"...","ordinal":5,"type":"response_item","payload":{"type":"reasoning","id":"rs_1","summary":[{"type":"summary_text","text":"需要先运行测试。"}],"encrypted_content":"..."}}
{"timestamp":"...","ordinal":6,"type":"response_item","payload":{"type":"function_call","id":"fc_1","name":"exec_command","arguments":"{\"cmd\":\"just test\"}","call_id":"call_1"}}
{"timestamp":"...","ordinal":7,"type":"response_item","payload":{"type":"function_call_output","id":"fco_1","call_id":"call_1","output":"42 passed"}}
{"timestamp":"...","ordinal":8,"type":"response_item","payload":{"type":"message","id":"msg_final","role":"assistant","content":[{"type":"output_text","text":"测试通过。"}],"phase":"final_answer"}}

这里有三条关键关联：

• function_call.call_id 与 function_call_output.call_id 成对；
• id 是 item 自身身份，call_id 是调用与结果的关联键，两者不能混用；
• internal_chat_message_metadata_passthrough.turn_id 在需要时把 item 归到具体 turn。

---

B.6 event_msg：持久化的是事件子集

EventMsg 的类型远多于会落盘的类型。是否持久化取决于 history_mode。

B.6.1 两种 history mode

事件	legacy	paginated	用途
task_started	是	是	turn 起点；读取时也接受别名 turn_started
task_complete	是	是	turn 正常终点；读取时也接受别名 turn_complete
turn_aborted	是	是	turn 中止终点
token_count	是	是	恢复累计用量与窗口大小
thread_goal_updated	是	是	thread 长期目标状态
thread_rolled_back	是	是	legacy 逻辑 rollback marker
thread_settings_applied	是	是	thread 有效设置快照
item_completed	仅 Plan / clock.sleep	全部	paginated UI 历史的 canonical item
user_message	是	否	legacy UI replay
agent_message	是	否	legacy UI replay
agent_reasoning	是	否	legacy UI replay
agent_reasoning_raw_content	是	否	legacy UI replay
entered_review_mode	是	否	legacy review UI
exited_review_mode	是	否	legacy review UI
patch_apply_end	是	否	legacy 文件改动 UI
context_compacted	是	否	legacy compaction UI
mcp_tool_call_end	是	否	legacy MCP UI
web_search_end	是	否	legacy 搜索 UI
image_generation_end	是	否	legacy图片生成 UI
sub_agent_activity	是	否	legacy 多 agent UI

下面这些实时 Event 不属于当前 durable set：

• 所有 delta：assistant、reasoning、plan、命令输出、patch preview；
• 所有 started/begin 进度事件，task_started 除外；
• 审批、提问、权限申请、MCP elicitation 等 pending request；
• warning、stream error、模型 reroute、安全 buffering、环境连接状态；
• raw response 透传、hook 进度、MCP 启动进度；
• guardian 实时评估、动态工具 request/response；
• shutdown 通知。

这正是第二章“item 是权威，delta 是加速带”的磁盘版本。

B.6.2 始终持久化的事件 schema

task_started = {
  type: "task_started",
  turn_id: string,
  trace_id?: string,
  started_at?: int64,                 // Unix 秒
  model_context_window: int64 | null,
  collaboration_mode_kind: "default" | "plan"
}

task_complete = {
  type: "task_complete",
  turn_id: string,
  last_agent_message: string | null,
  error?: { message: string, codex_error_info: CodexErrorInfo | null },
  started_at?: int64,
  completed_at?: int64,
  duration_ms?: int64,
  time_to_first_token_ms?: int64
}

CodexErrorInfo =
  "context_window_exceeded"
  | "session_budget_exceeded"
  | "usage_limit_exceeded"
  | "server_overloaded"
  | "cyber_policy"
  | "misalignment_policy_violation"
  | "internal_server_error"
  | "unauthorized"
  | "bad_request"
  | "sandbox_error"
  | "thread_rollback_failed"
  | "other"
  | { "http_connection_failed": { http_status_code: uint16|null } }
  | { "response_stream_connection_failed": { http_status_code: uint16|null } }
  | { "response_stream_disconnected": { http_status_code: uint16|null } }
  | { "response_too_many_failed_attempts": { http_status_code: uint16|null } }
  | { "active_turn_not_steerable": { turn_kind: "review"|"compact" } }

turn_aborted = {
  type: "turn_aborted",
  turn_id: string | null,
  reason: "interrupted" | "replaced" | "review_ended" | "budget_limited",
  started_at?: int64,
  completed_at?: int64,
  duration_ms?: int64
}

thread_rolled_back = {
  type: "thread_rolled_back",
  num_turns: uint32
}

thread_settings_applied：

{
  type: "thread_settings_applied",
  thread_settings: {
    model: string,
    model_provider_id: string,
    service_tier?: string,
    approval_policy: AskForApproval,
    approvals_reviewer: "user" | "auto_review",
    permission_profile: PermissionProfile,
    active_permission_profile?: { id: string, extends?: string },
    cwd: string,
    reasoning_effort?: ReasoningEffort,
    reasoning_summary?: "auto" | "concise" | "detailed" | "none",
    personality?: "none" | "friendly" | "pragmatic",
    collaboration_mode: CollaborationMode
  }
}

token_count：

{
  type: "token_count",
  info: {
    total_token_usage: TokenUsage,
    last_token_usage: TokenUsage,
    model_context_window: int64 | null
  } | null,
  rate_limits: RateLimitSnapshot | null
}

TokenUsage = {
  input_tokens: int64,
  cached_input_tokens: int64,
  cache_write_input_tokens: int64,
  output_tokens: int64,
  reasoning_output_tokens: int64,
  total_tokens: int64
}

RateLimitSnapshot = {
  limit_id: string | null,
  limit_name: string | null,
  primary: { used_percent: number, window_minutes: int64|null, resets_at: int64|null } | null,
  secondary: { used_percent: number, window_minutes: int64|null, resets_at: int64|null } | null,
  credits: { has_credits: boolean, unlimited: boolean, balance: string|null } | null,
  individual_limit: { limit: string, used: string,
                      remaining_percent: int32, resets_at: int64 } | null,
  spend_control_reached: boolean | null,
  plan_type: string | null,
  rate_limit_reached_type: string | null
}

thread_goal_updated 使用 camelCase：

{
  type: "thread_goal_updated",
  threadId: UUID,
  turnId?: string,
  goal: {
    threadId: UUID,
    objective: string,
    status: "active" | "paused" | "blocked" | "usageLimited"
          | "budgetLimited" | "complete",
    tokenBudget?: int64,
    tokensUsed: int64,
    timeUsedSeconds: int64,
    createdAt: int64,
    updatedAt: int64
  }
}

B.6.3 legacy 专属事件 schema

user_message = {
  type: "user_message",
  client_id?: string,
  message: string,
  images?: string[],
  image_details?: (ImageDetail|null)[],
  local_images: string[],
  local_image_details?: (ImageDetail|null)[],
  audio?: string[],
  local_audio: string[],
  text_elements: TextElement[]
}

agent_message = {
  type: "agent_message",
  message: string,
  phase: "commentary" | "final_answer" | null,
  memory_citation: MemoryCitation | null,
  delivery?: "async"
}

agent_reasoning = {
  type: "agent_reasoning",
  text: string
}

agent_reasoning_raw_content = {
  type: "agent_reasoning_raw_content",
  text: string
}

context_compacted = {
  type: "context_compacted"
}

Review：

entered_review_mode = {
  type: "entered_review_mode",
  target:
    { type: "uncommittedChanges" }
    | { type: "baseBranch", branch: string }
    | { type: "commit", sha: string, title: string|null }
    | { type: "custom", instructions: string },
  user_facing_hint?: string,
  turn_id?: string,
  item_id?: string
}

exited_review_mode = {
  type: "exited_review_mode",
  turn_id?: string,
  item_id?: string,
  review_output: {
    findings: [{
      title: string,
      body: string,
      confidence_score: number,
      priority: int32,
      code_location: {
        absolute_file_path: string,
        line_range: { start: uint32, end: uint32 }
      }
    }],
    overall_correctness: string,
    overall_explanation: string,
    overall_confidence_score: number
  } | null
}

工具与多 agent：

patch_apply_end = {
  type: "patch_apply_end",
  call_id: string,
  turn_id: string,
  stdout: string,
  stderr: string,
  success: boolean,
  changes: object<path, FileChange>,
  status: "completed" | "failed" | "declined"
}

mcp_tool_call_end = {
  type: "mcp_tool_call_end",
  call_id: string,
  invocation: { server: string, tool: string, arguments: JSON|null },
  connector_id?: string,
  mcp_app_resource_uri?: string,
  link_id?: string,
  app_name?: string,
  action_name?: string,
  plugin_id?: string,
  read_only_hint?: boolean,
  duration: { secs: uint64, nanos: uint32 },
  result: { "Ok": CallToolResult } | { "Err": string }
}

web_search_end = {
  type: "web_search_end",
  call_id: string,
  query: string,
  action: ResponseWebSearchAction,
  results?: JSON[]
}

image_generation_end = {
  type: "image_generation_end",
  call_id: string,
  status: string,
  revised_prompt?: string,
  result: string,
  transparent_background?: boolean,
  failure?: ImageGenerationFailure,
  saved_path?: string
}

sub_agent_activity = {
  type: "sub_agent_activity",
  event_id: string,
  occurred_at_ms: int64,
  agent_thread_id: UUID,
  agent_path: string,
  kind: "started" | "interacted" | "interrupted"
}

公共子类型：

FileChange =
  { type: "add", content: string }
  | { type: "delete", content: string }
  | { type: "update", unified_diff: string, move_path: string|null }

CallToolResult = {
  content: JSON[],
  structuredContent?: JSON,
  isError?: boolean,
  _meta?: JSON
}

---

B.7 item_completed：paginated history 的 UI 事实

Paginated 模式不再为每类 UI 内容分别保存一组 legacy 事件，而是统一写：

{
  type: "item_completed",
  thread_id: UUID,
  turn_id: string,
  item: TurnItem,
  started_at_ms?: int64,
  completed_at_ms: int64
}

completed_at_ms 是 Unix 毫秒。旧的 plan 记录可能没有该字段，读取时按 0 处理。

一个容易踩坑的细节：TurnItem.type 当前使用 PascalCase，不是外层记录常见的 snake_case。例如：

{"timestamp":"...","ordinal":9,"type":"event_msg","payload":{"type":"item_completed","thread_id":"0199...","turn_id":"0199...","item":{"type":"AgentMessage","id":"msg_1","content":[{"type":"Text","text":"完成。"}],"phase":"final_answer"},"completed_at_ms":1788770000123}}

B.7.1 全部 TurnItem

UserMessage = {
  type: "UserMessage",
  id: string,
  client_id?: string,
  content: UserInput[]
}

HookPrompt = {
  type: "HookPrompt",
  id: string,
  fragments: [{ text: string, hookRunId: string }]
}

AgentMessage = {
  type: "AgentMessage",
  id: string,
  content: [{ type: "Text", text: string }],
  phase?: "commentary" | "final_answer",
  memory_citation?: MemoryCitation,
  delivery?: "async"
}

Plan = {
  type: "Plan",
  id: string,
  text: string
}

Reasoning = {
  type: "Reasoning",
  id: string,
  summary_text: string[],
  raw_content: string[]
}

UserInput：

{ type: "text", text: string, text_elements: TextElement[] }
| { type: "image", image_url: string, detail?: ImageDetail }
| { type: "local_image", path: string, detail?: ImageDetail }
| { type: "audio", audio_url: string }
| { type: "local_audio", path: string }
| { type: "skill", name: string, path: string }
| { type: "mention", name: string, path: string }

TextElement = {
  byte_range: { start: uint, end: uint },
  placeholder: string | null
}

命令执行：

CommandExecution = {
  type: "CommandExecution",
  id: string,
  plugin_id?: string,
  script_path?: string,
  process_id?: string,
  command: string[],
  cwd: string,                       // Path URI
  parsed_cmd: ParsedCommand[],
  source: "agent" | "user_shell"
        | "unified_exec_startup" | "unified_exec_interaction",
  interaction_input?: string,
  status: "in_progress" | "completed" | "failed" | "declined",
  stdout?: string,
  stderr?: string,
  aggregated_output?: string,
  exit_code?: int32,
  duration?: { secs: uint64, nanos: uint32 },
  formatted_output?: string
}

ParsedCommand =
  { type: "read", cmd: string, name: string, path: string }
  | { type: "list_files", cmd: string, path: string|null }
  | { type: "search", cmd: string, query: string|null, path: string|null }
  | { type: "unknown", cmd: string }

动态工具与多 agent：

DynamicToolCall = {
  type: "DynamicToolCall",
  id: string,
  namespace?: string,
  tool: string,
  arguments: JSON,
  status: "in_progress" | "completed" | "failed",
  content_items?: DynamicToolOutput[],
  success?: boolean,
  error?: string,
  duration?: { secs: uint64, nanos: uint32 }
}

DynamicToolOutput =
  { type: "inputText", text: string }
  | { type: "inputImage", imageUrl: string }
  | { type: "inputAudio", audioUrl: string }

CollabAgentToolCall = {
  type: "CollabAgentToolCall",
  id: string,
  tool: "spawn_agent" | "send_input" | "resume_agent" | "wait" | "close_agent",
  status: "in_progress" | "completed" | "failed",
  sender_thread_id: UUID,
  receiver_thread_ids: UUID[],
  receiver_agents: CollabAgentRef[],
  prompt?: string,
  model?: string,
  reasoning_effort?: ReasoningEffort,
  agents_states: object<UUID, AgentStatus>
}

CollabAgentRef = {
  thread_id: UUID,
  agent_nickname?: string,
  agent_role?: string
}

AgentStatus =
  "pending_init" | "running" | "interrupted" | "shutdown" | "not_found"
  | { "completed": string|null }
  | { "errored": string }

SubAgentActivity = {
  type: "SubAgentActivity",
  id: string,
  kind: "started" | "interacted" | "interrupted",
  agent_thread_id: UUID,
  agent_path: string
}

搜索、图片与扩展：

WebSearch = {
  type: "WebSearch",
  id: string,
  query: string,
  action: ResponseWebSearchAction,
  results?: JSON[]
}

ImageView = {
  type: "ImageView",
  id: string,
  path: string                         // Path URI
}

ImageGeneration = {
  type: "ImageGeneration",
  id: string,
  status: string,
  revised_prompt?: string,
  result: string,
  saved_path?: string
}

Extension =
  { type: "Extension", kind: "clock.sleep",
    id: string, durationMs: uint64 }
  | { type: "Extension", kind: "web.search",
      id: string, query: string,
      action: ExtensionWebSearchAction|null, results: JSON[]|null }
  | { type: "Extension", kind: "image_gen.generation",
      id: string, status: string, revisedPrompt: string|null,
      result: string, transparentBackground?: boolean,
      failure: ImageGenerationFailure|null, savedPath?: string }

ImageGenerationFailure = {
  type: "usageLimitExceeded",
  limitId: string,
  resetsAt: int64 | null
}

ExtensionWebSearchAction =
  { type: "search", query: string|null, queries: string[]|null }
  | { type: "openPage", url: string|null }
  | { type: "findInPage", url: string|null, pattern: string|null }
  | { type: "other" }

文件、MCP、review 与压缩：

FileChange = {
  type: "FileChange",
  id: string,
  changes: object<path, FileChange>,
  status?: "completed" | "failed" | "declined",
  auto_approved?: boolean,
  stdout?: string,
  stderr?: string
}

McpToolCall = {
  type: "McpToolCall",
  id: string,
  server: string,
  tool: string,
  arguments: JSON,
  connectorId?: string,
  mcpAppResourceUri?: string,
  linkId?: string,
  appName?: string,
  actionName?: string,
  pluginId?: string,
  readOnlyHint?: boolean,
  status: "inProgress" | "completed" | "failed",
  result?: CallToolResult,
  error?: { message: string },
  duration?: { secs: uint64, nanos: uint32 }
}

EnteredReviewMode = {
  type: "EnteredReviewMode",
  id: string,
  target: ReviewTarget,
  user_facing_hint: string
}

ExitedReviewMode = {
  type: "ExitedReviewMode",
  id: string,
  review_output: ReviewOutput | null
}

ContextCompaction = {
  type: "ContextCompaction",
  id: string
}

为什么同时保存 response_item 与 item_completed？

• response_item 服务于模型上下文，尽量忠实于 Responses API；
• item_completed 服务于前端历史，把命令、文件改动、MCP、review 等整理成可直接展示的领域对象；
• 两者可以指向同一次行为，但不是同一个 schema，也不能假设一一对应；
• replay 会按消费目标选择 projection，而不是把两份都塞给模型。

---

B.8 compacted：模型历史 checkpoint

CompactedItem = {
  message: string,
  replacement_history?: ResponseItem[],
  replacement_history_metadata?: CodexHarnessMetadata[],
  mcp_resource_origins?: {
    origins: [{
      call_id: string,
      turn_id?: string,
      tool: string,
      connector_id: string,
      link_id?: string,
      uri: string,
      ambiguous_account?: boolean
    }],
    turns: string[],
    current_turn_id?: string
  },
  window_number?: uint64,
  first_window_id?: string,
  previous_window_id?: string,
  window_id?: string
}

约束：

• replacement_history 是 checkpoint 后模型应该使用的完整替代历史；
• replacement_history_metadata 与它按下标一一对应，长度必须相等；
• 只有至少一条 replacement item 带 metadata 时，writer 才写 metadata 数组；没有 metadata 的位置写默认对象；
• 单独出现 replacement_history_metadata 是非法记录；
• 旧记录可能没有 replacement history，此时 message 仍可转换为一条 assistant 摘要，但恢复能力更弱；
• 更老的记录曾把数字窗口号写进 window_id，reader 会把它兼容为 window_number。

典型场景：

flowchart LR
    H["旧模型历史"] --> C["compacted<br/>replacement_history"]
    C --> W["world_state full"]
    W --> T["turn_context"]
    T --> N["后续 response_item"]

compacted 不删除前面的行。它只告诉模型历史 reducer：“从这里起，使用 replacement history 作为新基线。”

---

B.9 turn_context：一轮实际用了什么设置

TurnContextItem = {
  turn_id?: string,
  cwd: string,
  workspace_roots?: string[],
  current_date?: string,
  timezone?: string,
  approval_policy: AskForApproval,
  approvals_reviewer?: "user" | "auto_review",
  sandbox_policy: SandboxPolicy,
  permission_profile?: PermissionProfile,
  active_permission_profile?: { id: string, extends?: string },
  network?: {
    allowed_domains: string[],
    denied_domains: string[]
  },
  file_system_sandbox_policy?: RawFileSystemSandboxPolicy,
  model: string,
  comp_hash?: string,
  personality?: "none" | "friendly" | "pragmatic",
  collaboration_mode?: CollaborationMode,
  multi_agent_version?: "disabled" | "v1" | "v2",
  multi_agent_mode?: MultiAgentMode,
  realtime_active?: boolean,
  effort?: ReasoningEffort,
  summary: "auto" | "concise" | "detailed" | "none"
}

summary 是兼容字段，当前仍然写出，但恢复逻辑不再依赖它。multi_agent_mode 也是读取旧 rollout 的 legacy 字段。

主要嵌套类型：

AskForApproval =
  "untrusted" | "on-request" | "never"
  | { "granular": {
      sandbox_approval: boolean,
      rules: boolean,
      skill_approval: boolean,
      request_permissions: boolean,
      mcp_elicitations: boolean
    }}

SandboxPolicy =
  { type: "danger-full-access" }
  | { type: "read-only", network_access?: boolean }
  | { type: "external-sandbox", network_access: "restricted"|"enabled" }
  | { type: "workspace-write",
      writable_roots?: string[],
      network_access: boolean,
      exclude_tmpdir_env_var: boolean,
      exclude_slash_tmp: boolean }

PermissionProfile =
  { type: "managed",
    file_system:
      { type: "restricted", entries: FileSystemEntry[],
        glob_scan_max_depth?: uint }
      | { type: "unrestricted" },
    network: "restricted" | "enabled" }
  | { type: "disabled" }
  | { type: "external", network: "restricted" | "enabled" }

RawFileSystemSandboxPolicy = {
  kind: "restricted" | "unrestricted" | "external-sandbox",
  glob_scan_max_depth?: uint,
  entries?: FileSystemEntry[]
}

FileSystemEntry = {
  path:
    { type: "path", path: string }
    | { type: "glob_pattern", pattern: string }
    | { type: "special", value:
          { kind: "root" | "minimal" | "tmpdir" | "slash_tmp" }
          | { kind: "project_roots", subpath?: string }
          | { kind: "unknown", path: string, subpath?: string }
      },
  access: "read" | "write" | "deny",
  missing_path_behavior?: "skip"
}

CollaborationMode = {
  mode: "default" | "plan",
  settings: {
    model: string,
    reasoning_effort: ReasoningEffort | null,
    developer_instructions: string | null
  }
}

MultiAgentMode =
  "explicitRequestOnly" | "proactive" | { "custom": string }

ReasoningEffort 的具体可选值随模型协议演进，读取方应把它当作字符串枚举处理，不应在 rollout 分析器里写死模型能力。

场景：

• 每个真实 user turn 在计算完本轮模型可见更新后保存一次；
• mid-turn compaction 重建完整上下文后再保存一次；
• resume 用最后一个仍然有效的 user turn context 恢复模型、cwd 和安全基线；
• rollback 必须同时排除被回退 turn 内的 turn_context，否则旧 turn 的模型或权限会泄漏到新时间线。

---

B.10 world_state：full snapshot 与 merge patch

WorldStateItem = {
  full: boolean,
  state: object<string, JSON>
}

state 故意是开放 map，而不是封闭字段表。每个 key 对应一个世界状态 section，例如环境、指令、权限、工具可见性或扩展贡献的状态。section 自己拥有内部 schema 和版本演进责任。

B.10.1 当前 section 目录

下面列出当前版本可能写入的核心 section，以及随首方扩展启用后可能出现的 section。它不是对未来 key 的封闭枚举：extension 可以注册新的稳定 ID，并以任意非 null JSON 值作为 snapshot。

section ID	snapshot	何时存在
model	model slug 字符串	始终
personality	model 与 personality	Personality feature 启用时
context_window	AgentPath 字符串	Token Budget 启用且模型有 context window 时
context_window_guidance	guidance 字符串	Token Budget 配置了非空 guidance 时
realtime	realtime 是否 active	始终
agents_md	当前生效的 AGENTS.md 目录与正文	始终；无指令时保存空 object
permissions	权限指令指纹与已批准命令前缀	完整权限指令启用时
approved_command_prefixes	已批准命令前缀集合	不注入完整权限指令时；与 permissions 二选一
collaboration_mode	mode、model 与指令指纹	collaboration mode 指令启用时
environments	环境、日期、时区、网络、文件系统与 subagent 摘要	environment context 启用时
environments_instructions	是否启用环境使用说明	始终
apps_instructions	是否已有可用 Apps 使用说明	始终
plugins_instructions	是否已有可用 plugin 使用说明	始终
tools	deferred tool namespace 到描述的映射	Deferred Tool World State 启用且映射非空时
multi_agent_usage_hint	multi-agent usage hint 的稳定指纹	本轮存在 usage hint 时
multi_agent_mode	effective mode 与 usage hint 指纹	始终
skills	selected-environment skills 的渲染状态	Skills 扩展贡献时
orchestrator_skills	orchestrator skills 的渲染状态	Skills 扩展贡献时
host_skills	前端提供的 skills 渲染状态	Skills 扩展贡献时
git_attribution	是否启用 Git attribution	Git attribution 扩展贡献时

这些 section 的 snapshot schema 如下：

WorldStateHash = string                 // 对模型可见 fragment 的稳定 SHA-1 指纹
AgentPath = string                      // 例如 "/root"、"/root/reviewer"

state.model = string

state.personality = {
  model: string,
  personality?: "none" | "friendly" | "pragmatic"
}

state.context_window = AgentPath
state.context_window_guidance = string
state.realtime = { active: boolean }

state.agents_md = {
  directory?: string,
  text?: string
}

state.permissions =
  | WorldStateHash                     // legacy
  | {
      instructions: WorldStateHash,
      approved_command_prefixes: string[][]
    }

state.approved_command_prefixes = string[][]

state.collaboration_mode =
  | "plan" | "default"                 // legacy
  | {
      mode: "plan" | "default",
      model: string,
      instructions?: WorldStateHash
    }

state.environments = {
  environments: object<string, {
    cwd: string,
    status: "starting" | "available",
    shell?: string,
    is_primary?: boolean
  }>,
  current_date?: string,
  timezone?: string,
  network?: string,
  filesystem?: string,
  subagents?: string
}

state.environments_instructions = boolean
state.apps_instructions = boolean
state.plugins_instructions = boolean
state.tools = object<string, string>
state.multi_agent_usage_hint = WorldStateHash

state.multi_agent_mode = {
  mode?: "explicitRequestOnly"
      | "proactive"
      | { custom: string },
  usage_hint_hash?: WorldStateHash
}

SkillSectionSnapshot = {
  body?: string,
  includeInstructions: boolean,
  enabled?: boolean
}

state.skills = SkillSectionSnapshot
state.orchestrator_skills = SkillSectionSnapshot
state.host_skills = SkillSectionSnapshot
state.git_attribution = boolean

state.<extension_owned_id> = non-null JSON

保存 snapshot 时会递归移除 object 中值为 null 的字段，因此上面标有 ? 的字段会直接缺席。数组里的 null 不会被这一规则删除。

WorldStateHash 只用于比较两次模型可见 fragment 是否相同。它不能还原原始指令正文，也不应被当作安全哈希或内容寻址 ID。

两种语义：

// 建立新基线
{"type":"world_state","payload":{"full":true,"state":{"environments":{"environments":{"local":{"cwd":"/repo","status":"available"}}},"permissions":{"instructions":"70e11c...","approved_command_prefixes":[]}}}}

// RFC 7386 风格 merge patch
{"type":"world_state","payload":{"full":false,"state":{"environments":{"environments":{"local":{"cwd":"/repo/web"}}},"tools":null}}}

• full: true：丢弃旧基线，以 state 建立完整基线；
• full: false：把 state 作为 JSON merge patch 应用到现有基线；
• patch 中字段为 null 表示删除；
• 没有 full baseline 时不能可靠解释 patch，应走保守恢复；
• compaction 后通常重新写 full snapshot，使新窗口可以独立恢复。

这类记录保存的不是“机器当前真实状态”，而是模型最后被告知的世界状态。文件系统可能已继续变化，resume 后仍要重新观察现实。

---

B.11 多 agent 与安全记录

B.11.1 inter_agent_communication

InterAgentCommunication = {
  id?: string,
  author: string,                    // AgentPath
  recipient: string,                 // AgentPath
  other_recipients: string[],
  content: string,
  encrypted_content?: string,
  internal_chat_message_metadata_passthrough?: InternalChatMessageMetadataPassthrough,
  trigger_turn: boolean
}

它既是跨 agent 的通信事实，也可以成为接收方模型历史。trigger_turn 区分：

• true：消息应该唤醒接收方并触发工作；
• false：只进入邮箱/历史，等接收方自然运行时消费。

当前 live 接收路径通常会把通信正文转换成 response_item.agent_message，并在它前面追加：

inter_agent_communication_metadata = {
  trigger_turn: boolean
}

它只保留“紧随其后的 agent message 会不会触发 turn”的控制语义，不重复正文。完整的 inter_agent_communication 仍是可读取、可持久化的 canonical variant，主要用于旧记录、fork 输入和迁移路径。

B.11.2 security_risk_score

SecurityRiskScore = {
  scores: object<string, number>,
  sampled_at?: string
}

• scores 是分类器名称到分数的 map；
• sampled_at 是 RFC 3339 时间；
• 它属于 thread-owned 风险状态；
• 它不会进入模型可见 conversation，也不会投影成用户可见 item；
• fork 子 agent 时不会作为普通历史继承。

这体现了安全数据的一个边界：可以持久化用于恢复决策，但不应因此自动暴露给模型或 UI。

---

B.12 典型写入序列

下面只列记录顺序，省略大部分字段。

B.12.1 新建空 thread

新建时 recorder 可以处于 deferred 状态，文件尚不存在。第一次跨过有意义的持久化边界后才 materialize：

session_meta

因此“创建过内存 Session”不等于“一定存在 rollout 文件”。

B.12.2 普通对话

Legacy：

session_meta
event_msg(task_started)
event_msg(user_message)
turn_context
world_state(full 或 patch)
response_item(message:user)
response_item(reasoning)
event_msg(agent_reasoning)
response_item(message:assistant)
event_msg(agent_message)
event_msg(token_count)
event_msg(task_complete)

Paginated：

session_meta
event_msg(task_started)
turn_context
world_state(full 或 patch)
response_item(message:user)
event_msg(item_completed:UserMessage)
response_item(reasoning)
event_msg(item_completed:Reasoning)
response_item(message:assistant)
event_msg(item_completed:AgentMessage)
event_msg(token_count)
event_msg(task_complete)

两份记录看起来有重复，是因为它们分别服务模型历史与 UI projection。

B.12.3 工具调用

response_item(function_call 或 custom_tool_call)
event_msg(item_completed:CommandExecution / FileChange / McpToolCall ...)
response_item(function_call_output 或 custom_tool_call_output)

关键时序是先调用、后结果。并行工具可以并发执行，但结果按调用顺序回灌 response_item，保持模型历史确定。

审批请求本身通常不持久化。若进程在“用户已批准、外部动作已发生、结果尚未落盘”之间崩溃，rollout 只能表达“调用存在、结果未知”，不能据此自动重试。

B.12.4 Steer

Steer 不创建新 turn：

... 当前 turn 的已有记录
response_item(message:user, metadata.turn_id = 当前 turn)
... 下一次 step 继续

它在步骤边界进入历史，而不是插入已经发出的模型请求中。Paginated UI 还会有对应 UserMessage completed item。

B.12.5 Interrupt 与 recover

正常中断：

event_msg(task_started, turn_id=T)
... 已完成的 response_item / item_completed
event_msg(turn_aborted, turn_id=T, reason="interrupted")

同进程 recover 沿用 T：

... 新的 response_item / item_completed
event_msg(task_complete, turn_id=T)

如果进程崩溃，只看到 task_started 而没有 terminal event，reader 应把它理解为 stale in-progress turn，而不是仍在后台运行的任务。

B.12.6 Compaction

... 旧历史
compacted(replacement_history, window_id ...)
world_state(full)
turn_context
... 新窗口的增量历史

Legacy 还可能写 event_msg(context_compacted) 供 UI replay；paginated 用 item_completed:ContextCompaction。

B.12.7 Resume

Resume 不复制文件：

读取原 rollout
→ replay 有效历史与设置
→ 创建新的运行时连接和 channel
→ 继续向原 rollout 尾部追加

恢复过程会分别寻找：

• 第一条 canonical session_meta；
• 最新有效 compacted；
• 最新有效 turn_context；
• world_state 的最近 full baseline 与后续 patch；
• 最新 token_count；
• rollback 后仍然有效的 turn；
• 未闭合的最后 turn。

B.12.8 Fork

Copy 型 fork：

子 rollout.session_meta(forked_from_id=父 thread)
复制选定的父历史前缀
追加子线程自己的记录

Reference 型 fork：

子 rollout.session_meta(
  history_base={
    thread_id: 父 rollout_id,
    end_ordinal_exclusive: N,
    end_byte_offset: B
  }
)
只追加子线程后缀

引用边界是 exclusive。读取子线程完整历史时，先读父 rollout 的 [0, N)，再读子 rollout。

B.12.9 Rollback

Legacy rollback 只追加 marker：

... turn A
... turn B
event_msg(thread_rolled_back, num_turns=1)

物理文件仍保留 turn B，模型历史 reducer 与 UI reducer 在 replay 时把它从有效视图中排除。连续 marker 可以累计。

B.12.10 Revert

Paginated history 不写 thread_rolled_back 来完成 revert，而是：

旧 rollout：保持不变
新 rollout：session_meta(id=同一 thread, history_base=目标前缀)
状态库：把 thread 当前指针原子切到新 rollout

因此：

• thread ID 不变；
• rollout ID 改变；
• 旧时间线仍可审计；
• 并发切换必须检测指针冲突；
• 外部文件与网络副作用不会被撤销。

B.12.11 多 agent

父线程：

response_item(function_call: spawn_agent)
event_msg(item_completed:CollabAgentToolCall)
response_item(function_call_output)

子线程：

session_meta(
  session_id=父树 session_id,
  id=新的 thread_id,
  parent_thread_id=父 thread_id,
  source={subagent:{thread_spawn:{...}}}
)
... 继承的上下文或 history_base
inter_agent_communication_metadata(trigger_turn=...)
response_item(agent_message, author=..., recipient=...)
... 子线程自己的 turn

每个 agent 独立记账。跨 thread 消息不是一个跨文件原子事务，因此通信必须依赖稳定 ID、sender/recipient 与幂等处理，而不能假设 exactly-once。

---

B.13 读取、容错与兼容规则

一个可靠 reader 至少应遵守以下规则：

1. 逐行解析。 空行忽略；单行 JSON 损坏时记录 parse error 并继续，避免一条坏记录拖垮整份历史。
2. 第一条元数据定身份。 第一条有效 session_meta 是当前 rollout 的 canonical metadata；后续同类记录可能来自复制的父历史。
3. 按 history_mode 解释事件。 不要把 legacy 事件和 paginated item_completed 同时当成两份独立用户内容，否则 UI 会重复。
4. 按关联键归并。 turn 用 turn_id，工具调用用 call_id，item 用 id；不要用行号猜关系。
5. 按 ordinal 而非文件行号分页。 注释不存在于真实文件，但空行、损坏行和共享前缀都会让物理行号失去业务意义。
6. 先应用 rollback，再找最新状态。 被回退 turn 中的 turn_context、world state patch 和 item 不能污染有效历史。
7. Compacted 是替换基线。 有 replacement_history 时，模型上下文从它继续；不是把它再追加到全部旧历史末尾。
8. World state 先 full 后 patch。 patch 使用 merge semantics；缺少 baseline 时不能猜。
9. Replay 不执行工具。 调用没有结果只代表 outcome unknown，不代表动作未发生。
10. 保留未知字段。 做搬运、迁移或归档时不要重建成自己理解的最小对象，否则会丢掉新版本字段。

B.13.1 历史兼容形态

旧 rollout 可能出现：

• session_meta 缺少 session_id，此时用 id 补齐；
• turn_started / turn_complete，读取为当前的 task_started / task_complete；
• agent_type，读取为 agent_role；
• on-failure approval policy，读取为 on-request；
• guardian_subagent reviewer，读取为 auto_review；
• none 文件访问模式，读取为 deny；
• 数字 window_id，读取为 window_number；
• 旧式 permission profile、sandbox policy、review target、命令 cwd；
• 已退休的 ghost_snapshot、guardian_assessment、thread_name_updated、undo_completed 等记录；
• 来自相邻版本或实验 writer、但当前 reader 不认识的顶层记录。

兼容策略不是“所有旧字段永远参与当前语义”。有些记录会被归一化，有些只为 UI 迁移读取，有些明确跳过；无法解析的行进入 parse error 计数并被隔离。

这也说明为什么不能用一份静态 JSON Schema 粗暴验证整份历史：读取协议是“schema + alias + normalization + replay policy”的组合。

---

B.14 常用检查命令

查看每种顶层记录数量：

jq -r '.type' rollout.jsonl | sort | uniq -c

查看 response_item 子类型：

jq -r 'select(.type == "response_item") | .payload.type' rollout.jsonl \
  | sort | uniq -c

查看 durable event 子类型：

jq -r 'select(.type == "event_msg") | .payload.type' rollout.jsonl \
  | sort | uniq -c

只看 turn 边界：

jq -c '
  select(
    .type == "event_msg"
    and (.payload.type == "task_started"
      or .payload.type == "task_complete"
      or .payload.type == "turn_aborted")
  )
  | {ordinal, timestamp, event: .payload.type, turn_id: .payload.turn_id}
' rollout.jsonl

检查 paginated ordinal 是否连续：

jq -r 'select(.ordinal != null) | .ordinal' rollout.jsonl \
  | awk 'NR == 1 { expected = $1 } $1 != expected { print "gap:", expected, "->", $1 } { expected = $1 + 1 }'

查看工具调用是否有结果：

jq -r '
  select(.type == "response_item")
  | .payload
  | select(.type == "function_call" or .type == "function_call_output"
        or .type == "custom_tool_call" or .type == "custom_tool_call_output")
  | [.type, .call_id] | @tsv
' rollout.jsonl

这些命令适合检查结构，不应把包含 reasoning、工具输出或凭证片段的完整 rollout 上传到第三方服务。

---

B.15 一张总图：一份文件如何支撑多种恢复

flowchart TD
    META["session_meta<br/>身份 / lineage / history mode"] --> LOAD["加载 rollout"]
    RESP["response_item<br/>模型历史"] --> LOAD
    EVT["event_msg<br/>turn / UI / token"] --> LOAD
    CP["compacted<br/>replacement history"] --> LOAD
    WS["world_state<br/>full + patch"] --> LOAD
    TC["turn_context<br/>有效设置"] --> LOAD
    MAIL["inter_agent_communication<br/>跨 agent 消息"] --> LOAD
    RISK["security_risk_score<br/>安全状态"] --> LOAD

    LOAD --> MH["模型上下文 projection"]
    LOAD --> UI["thread / turn / item projection"]
    LOAD --> ST["Session 设置与状态"]
    LOAD --> IX["SQLite 查询索引"]

    MH --> RESUME["Resume：同 thread 继续追加"]
    MH --> FORK["Fork：新 thread 继承前缀"]
    MH --> ROLLBACK["Rollback / Revert：改变有效历史"]

最值得记住的不是字段数量，而是三层分工：

1. response_item 保存模型认知。 它回答“下一次采样应该看到什么”。
2. event_msg 保存生命周期与展示事实。 它回答“一个 turn 如何开始、结束，前端应怎样重建历史”。
3. checkpoint 与 metadata 保存解释这些事实所需的坐标。 它们回答“这是哪个 thread、哪条时间线、哪套设置、哪个上下文窗口”。

因此，Codex session JSONL 不是把 Session 对象序列化到磁盘，也不是简单的聊天导出。它是一份由多个 reducer 共同解释的 append-only protocol：同一组记录分别投影出模型记忆、用户界面、运行时基线和历史 lineage。

第二章讲的是协议设计：为什么是两条消息河流、事件为什么分层。本附录是对接手册： 如果你要自己写一个前端（IDE 插件、Web 面板、聊天机器人、自动化脚本……）接入 Codex， 这一章给出完整的消息目录、字段约定、时序和最小客户端骨架。

对外对接的标准入口是 app-server：一个独立进程，说 JSON-RPC 风格的消息。 TUI 内部跑的是同一套语义（只是传输换成内存通道），所以学会本附录，你就掌握了所有前端形态的共同语言。

约定：消息名、字段名一律用线上原名（英文，camelCase）；解释性文字用中文。标注 [EXP] 的方法/字段需要在握手时声明实验能力，见 A.3。

---

A.1 启动与传输

启动一个 app-server 进程（codex app-server），支持三种监听方式：

启动方式	传输形态	适用场景
默认 / --stdio（或 --listen stdio://）	标准输入输出上跑 JSONL：一行一条 JSON 消息	本地 IDE 插件、CLI 内嵌（最常用）
--listen ws://127.0.0.1:PORT	WebSocket：一个 text frame 一条消息；同端口有 GET /healthz、GET /readyz	浏览器/多客户端/远程面板（实验性）
--listen unix://	Unix domain socket 上跑 WebSocket 握手	本机多进程共享（默认 socket 位于 $CODEX_HOME/app-server-control/）
--listen off	不暴露端口	只想要进程内形态时

要点：

• 消息是 JSON-RPC 2.0 风格，但不带 "jsonrpc": "2.0" 字段；
• stdio 模式下一行就是一条消息（换行分隔，不要在消息内换行）；
• 字段命名统一 camelCase；时间戳：通知里用 Unix 毫秒（startedAtMs），线程/轮次元数据用 Unix 秒（createdAt）；
• 进程随父进程生死：父进程退出，子进程被回收。

---

A.2 消息信封：四种消息

线上只有四种消息，靠 id 和 method 字段区分：

// ① 请求（有 id，必须回响应）
{ "id": 30, "method": "turn/start", "params": { ... } }

// ② 通知（无 id，不回响应）—— 服务端 → 客户端方向最常见
{ "method": "turn/started", "params": { ... } }

// ③ 成功响应
{ "id": 30, "result": { "turn": { ... } } }

// ④ 错误响应
{ "id": 30, "error": { "code": -32600, "message": "...", "data": { ... } } }

• id：字符串或整数，由发起方分配，响应原样带回；建议用自增整数；
• 双向：客户端给服务端发请求（方法调用），服务端也会给客户端发请求（审批、提问，见 A.10）——后者同样有 id，客户端必须回响应；
• 请求可选带 trace 字段传播 W3C 追踪上下文；
• 特殊错误码：-32001 = 服务端正忙（队列饱和），客户端应稍后重试；握手前调用返回 “Not initialized”，重复握手返回 “Already initialized”。

---

A.3 连接生命周期：握手、订阅、退订

sequenceDiagram
    participant C as 客户端
    participant S as app-server

    C->>S: 请求 initialize（clientInfo + capabilities）
    S-->>C: 响应（userAgent / codexHome / 平台信息）
    C->>S: 通知 initialized（无参数）
    Note over C,S: 之后才允许其他请求
    C->>S: 请求 thread/start（或 thread/resume）
    S-->>C: 响应 { thread }
    S-->>C: 通知 thread/started（含 thread.status）
    Note over C,S: 本连接自动订阅该线程的全部通知
    C->>S: 请求 turn/start（用户输入）
    S-->>C: 响应 { turn: { status: "inProgress" } }
    S-->>C: 通知 turn/started → item/* → turn/completed
    C->>S: 请求 thread/unsubscribe（可选）
    Note over S: 最后一个订阅者离开后，线程保留约 30 分钟<br/>空闲后卸载，发 thread/closed

握手请求：

{
  "method": "initialize",
  "id": 0,
  "params": {
    "clientInfo": { "name": "my_client", "title": "My Client", "version": "0.1.0" },
    "capabilities": {
      "experimentalApi": true,                       // 想用 [EXP] 方法时开启
      "requestAttestation": false,                  // 桌面宿主可同意生成 attestation
      "optOutNotificationMethods": [                // 按精确方法名屏蔽不想要的通知
        "item/agentMessage/delta"
      ]
      // "extensions": { ... }                      // MCP 扩展声明（如表单能力）
    }
  }
}

• clientInfo.name 用于合规日志识别客户端，接入方应起稳定的名字；
• optOutNotificationMethods 是精确方法名数组（无通配），可用来压低流量（比如不渲染打字机效果就可以屏蔽 delta 类通知）；
• 未声明 experimentalApi 时调用 [EXP] 方法会收到错误：<reason> requires experimentalApi capability；实验字段在输出时也可能被裁剪；
• thread/start、thread/resume、thread/fork 会自动订阅当前连接；thread/unsubscribe 显式退订；线程在最后一个订阅者离开后保留约 30 分钟无活动才卸载（跑收尾 hooks，发 thread/closed）。

---

A.4 对象模型：thread → turn → item

app-server 的世界只有三个核心对象，通知和查询都围绕它们：

对象	含义	标识
thread	一段持续会话（对应内核的线程/会话），持久化在磁盘上	threadId（如 thr_123）
turn	一轮“用户输入 → agent 回复”	turnId（如 turn_456）
item	turn 内的一个个条目：一条消息、一次命令执行、一次文件改动……	itemId

turn 状态（turn.status）：

值	含义
inProgress	运行中
completed	正常完成
interrupted	被中断（用户中断；turn/interrupt 的终态）
failed	出错终止（错误在 turn.error）

thread 状态（thread.status，判别对象）：

• notLoaded：未载入内存（列表里的历史线程默认如此）；
• idle：已载入、空闲；
• active：有轮次在跑，附带 activeFlags：waitingOnApproval（等审批）、waitingOnUserInput（等用户回答）；
• systemError：线程出错。

item 类型（item.type，判别联合，渲染层按此分发 UI）：

type	是什么
userMessage	用户消息（turn/start 的输入回显）
agentMessage	assistant 的最终回复
reasoning	reasoning（思考摘要，可能含多个分段）
plan	任务计划清单
commandExecution	一次命令执行（含命令、cwd、状态、输出）
fileChange	一次文件改动（补丁/差异）
mcpToolCall	一次 MCP 工具调用
dynamicToolCall	一次动态工具调用（执行方可能是客户端）
webSearch / imageGeneration / imageView / sleep	联网搜索 / 图片生成 / 看图 / 等待
subAgentActivity	子 agent 活动
collabAgentToolCall	协作模式 agent 调用
hookPrompt	hook 注入的提示
enteredReviewMode / exitedReviewMode	进入/退出代码审查模式
contextCompaction	上下文压缩记录

item 自身状态（commandExecution / fileChange 等）：inProgress → completed / failed / declined（被用户拒绝）。

---

A.5 最小会话流程（端到端时序）

一次完整对话的消息序列（客户端视角）：

sequenceDiagram
    participant C as 客户端
    participant S as app-server

    C->>S: turn/start { threadId, input }
    S-->>C: { turn: { id, status: "inProgress", items: [] } }
    S-->>C: 通知 turn/started
    S-->>C: 通知 item/started（userMessage，回显输入）
    S-->>C: 通知 item/completed（userMessage）
    S-->>C: 通知 item/started（reasoning）
    S-->>C: 通知 item/reasoning/summaryTextDelta ×N（思考流）
    S-->>C: 通知 item/completed（reasoning）
    S-->>C: 通知 item/started（commandExecution，inProgress）
    S-->>C: 请求 item/commandExecution/requestApproval（id=R1）
    Note over C: 弹审批框
    C-->>S: 响应 R1 { decision: "accept" }
    S-->>C: 通知 serverRequest/resolved { requestId: R1 }
    S-->>C: 通知 item/commandExecution/outputDelta ×N（命令输出流）
    S-->>C: 通知 item/completed（commandExecution，completed）
    S-->>C: 通知 item/started（agentMessage）
    S-->>C: 通知 item/agentMessage/delta ×N（回复打字机）
    S-->>C: 通知 item/completed（agentMessage）
    S-->>C: 通知 turn/completed（status: "completed" + token usage）

三条渲染铁律（第二章 2.4.5/2.8 的协议化版本）：

1. item 是权威，delta 是加速带。UI 的数据模型以 item/completed 为准重建；delta 只用来拼“正在生成”的临时气泡。断线重连/迟到订阅后，用 thread/items/list 或 turn/completed 里的 items 对齐，delta 漏了不补发；
2. 所有通知带坐标：threadId / turnId / itemId，按坐标归位到对应线程面板；
3. turn 的终态只看 turn/completed。turn/interrupt 的响应只表示“已受理”，轮次真正结束以 turn/completed（status: "interrupted"）为准。

---

A.6 客户端 → 服务端方法速查

只列对接常用方法；完整字段以随包发布的 JSON Schema / TypeScript 类型为准。

会话与轮次（最常用）

方法	作用	关键 params / result
initialize	握手	params：clientInfo{name,title?,version?}、capabilities?；result：userAgent、codexHome、platformFamily、platformOs
thread/start	新建线程	params：cwd?、model?、approvalPolicy?、sandbox?/sandboxPolicy?、personality? 等；result：{ thread }；随后有 thread/started 通知并自动订阅
thread/resume	恢复历史线程	params：threadId（+ 可选策略覆盖）；result：{ thread }
thread/fork	分叉线程	params：threadId、lastTurnId?、ephemeral?；result：{ thread }（含 forkedFromId）
thread/list	线程列表（游标分页）	params：cursor?、limit?、过滤项；result：{ data, nextCursor }
thread/read	读线程（不恢复）	params：threadId、includeTurns?
thread/loaded/list	当前内存中的线程	—
thread/unsubscribe	退订通知	params：threadId
thread/archive / unarchive / delete	归档/恢复/删除	params：threadId
turn/start	发起一轮	见 A.7；result：{ turn: { id, status, items, error } }
turn/steer	插话（见第一章 1.6）	params：threadId、input、expectedTurnId（必填）、clientUserMessageId?；result：{ turnId }
turn/interrupt	中断当前轮	params：threadId、turnId；result：{}；终态等 turn/completed
review/start	代码审查	params：threadId、target、delivery: "inline"/"detached"
thread/compact/start	手动压缩上下文	params：threadId
thread/shellCommand	跑一次性 !命令	params：threadId、command
thread/rollback（废弃）	丢弃最近 N 个用户轮次的历史（不动磁盘文件）	params：threadId、numTurns；result：更新后的 thread
thread/revert [EXP]	新版回滚：把历史替换为某个 turn 之前的前缀	params：threadId、beforeTurnId
thread/inject_items	往历史注入原始 item（不开轮次）	params：threadId、items（Responses API item 格式）

配置 / 模型 / 功能

方法	作用
config/read / config/value/write / config/batchWrite	读/写 config.toml（写支持 reloadUserConfig 热加载）
configRequirements/read	托管环境（MDM/requirements.toml）的强制约束
model/list	可用模型目录
modelProvider/capabilities/read	provider 能力
experimentalFeature/list / experimentalFeature/enablement/set	实验特性开关（带 stable/beta/underDevelopment 阶段标记）
permissionProfile/list	可用权限 profile
config/mcpServer/reload / mcpServerStatus/list	MCP 重载/状态
mcpServer/oauth/login / mcpServer/resource/read / mcpServer/tool/call	MCP 登录/资源/工具直调

扩展生态

方法	作用
skills/list / skills/config/write / skills/extraRoots/set	skills
hooks/list	hooks 清单与信任状态
plugin/list / plugin/search [EXP] / plugin/installed / plugin/install / plugin/uninstall / plugin/read / plugin/skill/read	插件
marketplace/add / remove / upgrade	插件市场
app/list / app/read / app/installed	连接器应用

文件系统与进程

方法	作用
fs/readFile / writeFile / readDirectory / getMetadata / createDirectory / remove / copy	文件操作（路径用 file URI）
fs/watch / fs/unwatch	目录监听，变更走 fs/changed 通知（自带 watchId）
command/exec（+ /write、/terminate、/resize）	独立命令会话，输出走 command/exec/outputDelta
process/spawn / writeStdin / kill / resizePty [EXP]	通用 PTY 进程

账户与其他

方法	作用
account/login/start / login/cancel / logout / account/read	登录与账户
account/rateLimits/read / account/usage/read	配额与用量
feedback/upload	反馈
thread/queue/* [EXP]	持久化的用户消息队列（空闲时自动 FIFO 提交）
thread/backgroundTerminals/list / clean / terminate [EXP]	后台终端管理
thread/realtime/* [EXP]	实时语音（start/appendAudio/appendText/stop/listVoices）
environment/* [EXP]、remoteControl/* [EXP]、project/* [EXP]、server/diagnostics [EXP]	远程环境 / 远程控制 / 项目分组 / 诊断

分页约定：列表方法统一 params: { cursor?, limit? } → result: { data: [...], nextCursor: string | null }。

---

A.7 turn/start 请求体详解

{
  "method": "turn/start",
  "id": 30,
  "params": {
    "threadId": "thr_123",
    "clientUserMessageId": "client_msg_123",        // 可选：客户端自己的消息幂等 ID
    "input": [
      { "type": "text", "text": "帮我跑一下测试" }
      // 也可附带 { "type": "skill", "name", "path" }   —— 显式调用 skill
      // 或 { "type": "mention", "name", "path" }       —— @插件 / $应用
    ],

    // —— 以下都是可选的本轮覆盖项 ——
    "cwd": "/Users/me/project",
    "model": "gpt-5.1-codex",
    "effort": "medium",                             // reasoning effort
    "summary": "concise",                           // reasoning summary 详细度
    "personality": "friendly",                      // friendly | pragmatic | none
    "approvalPolicy": "unlessTrusted",              // 审批策略
    "sandboxPolicy": {                              // 沙箱（旧简写 "sandbox": "workspaceWrite"）
      "type": "workspaceWrite",
      "writableRoots": ["/Users/me/project"],
      "networkAccess": true
    },
    // "permissions": ":workspace",                 // [EXP] 推荐用权限 profile id，与 sandboxPolicy 二选一
    "outputSchema": {                               // 可选：约束最终回复为结构化 JSON
      "type": "object",
      "properties": { "answer": { "type": "string" } },
      "required": ["answer"],
      "additionalProperties": false
    }
  }
}

响应是即时的（第二章 2.3 的“确认即回”）：

{ "id": 30, "result": { "turn": {
  "id": "turn_456",
  "status": "inProgress",
  "items": [],
  "error": null
} } }

之后的一切通过通知到达。turn/steer 字段类似但必须带 expectedTurnId（防止串台），且不接受策略覆盖、不产生新的 turn/started。

---

A.8 服务端 → 客户端通知速查

线程与轮次生命周期

通知	时机 / 载荷要点
thread/started	线程载入完成（start/resume/fork 后），含完整 thread 对象
thread/status/changed	thread.status 变化（如 idle → active）
thread/closed	线程卸载（最后订阅者离开约 30 分钟后）
thread/archived / unarchived / deleted	归档/恢复/删除
thread/tokenUsage/updated	token 用量（fork 回放历史用量也用它）
thread/name/updated、thread/goal/updated / cleared	重命名、长期目标变化
turn/started	轮次真正开始运行
turn/completed	轮次终态：完整 turn 对象（status、items、error、token usage）
turn/diff/updated	本轮累计代码 diff 更新
turn/plan/updated	计划更新
hook/started / hook/completed	hook 执行进度

item 生命周期与流式 delta

通知	时机
item/started	新 item 出现（载荷 { threadId, turnId, item, startedAtMs }）
item/completed	item 完成（权威终态，渲染以它为准）
item/agentMessage/delta	assistant 文本增量 { itemId, delta }
item/reasoning/summaryTextDelta	reasoning summary 增量
item/reasoning/summaryPartAdded	reasoning 新分段（标题块）
item/reasoning/textDelta	加密 raw reasoning 增量
item/plan/delta	计划文本增量
item/commandExecution/outputDelta	命令输出增量
item/commandExecution/terminalInteraction	交互式终端的回显
item/fileChange/patchUpdated	补丁流式预览
item/mcpToolCall/progress	MCP 工具进度
item/autoApprovalReview/started / completed	自动审批审查进度

状态与旁路

通知	含义
error / warning / guardianWarning	错误/警告（error 完整载荷见 A.9.4 与 A.11）
deprecationNotice	某功能将废弃
model/rerouted	服务端把请求改道到了别的模型
model/safetyBuffering/updated	安全审查缓冲状态
model/verification	账号验证建议
serverRequest/resolved	一个反向请求已被解决或清理（见 A.10）
fs/changed、account/updated、account/rateLimits/updated、app/list/updated、skills/changed、mcpServer/startupStatus/updated	各类资源变更广播
rawResponseItem/completed、rawResponse/completed	内部/高级：原始模型 item 与精确 usage 透传（普通前端不需要）

---

A.9 服务端 → 客户端通知：完整 JSON 示例

A.8 是通知目录，本节给出可直接对照实现的载荷示例。通知都是无 id 的 JSON-RPC 通知：{ "method": ..., "params": { ... } }。 字段名即线上字段（camelCase）；示例值是虚构但形状真实的。所有通知都带 threadId/turnId 坐标（少数全局通知除外），用它归位到对应线程。

A.9.1 一个完整 turn 的通知流（JSONL）

下面是用户说“跑一下测试”，agent 思考 → 申请执行命令 → 执行 → 回复，整个过程客户端收到的通知序列：

// ① 轮次真正开始运行（turn/start 的即时响应之后，才来这条）
{ "method": "turn/started", "params": {
  "threadId": "thr_123",
  "turn": {
    "id": "turn_456",
    "status": "inProgress",
    "items": [],
    "itemsView": "full",
    "error": null,
    "startedAt": 1788516346,
    "completedAt": null,
    "durationMs": null
  }
} }

// ② 用户消息回显（item 生命周期：started → completed）
{ "method": "item/started", "params": {
  "threadId": "thr_123", "turnId": "turn_456", "startedAtMs": 1788516346100,
  "item": {
    "type": "userMessage",
    "id": "item_01",
    "clientId": "client_msg_123",        // 来自 turn/start 的 clientUserMessageId
    "content": [ { "type": "text", "text": "跑一下测试" } ]
  }
} }
{ "method": "item/completed", "params": {
  "threadId": "thr_123", "turnId": "turn_456", "completedAtMs": 1788516346102,
  "item": {
    "type": "userMessage",
    "id": "item_01",
    "clientId": "client_msg_123",
    "content": [ { "type": "text", "text": "跑一下测试" } ]
  }
} }

// ③ reasoning 开始，思考摘要流式到达
{ "method": "item/started", "params": {
  "threadId": "thr_123", "turnId": "turn_456", "startedAtMs": 1788516347200,
  "item": { "type": "reasoning", "id": "item_02", "summary": [], "content": [] }
} }
{ "method": "item/reasoning/summaryPartAdded", "params": {
  "threadId": "thr_123", "turnId": "turn_456", "itemId": "item_02", "summaryIndex": 0
} }
{ "method": "item/reasoning/summaryTextDelta", "params": {
  "threadId": "thr_123", "turnId": "turn_456", "itemId": "item_02",
  "summaryIndex": 0, "delta": "用户要求运行测试。"
} }
{ "method": "item/reasoning/summaryTextDelta", "params": {
  "threadId": "thr_123", "turnId": "turn_456", "itemId": "item_02",
  "summaryIndex": 0, "delta": "项目是 Rust，用 cargo test。"
} }
// reasoning 完成：summary 是分段字符串数组，content 是 raw reasoning（开源模型才有）
{ "method": "item/completed", "params": {
  "threadId": "thr_123", "turnId": "turn_456", "completedAtMs": 1788516351800,
  "item": {
    "type": "reasoning", "id": "item_02",
    "summary": [ "用户要求运行测试。项目是 Rust，用 cargo test。" ],
    "content": []
  }
} }

// ④ 命令执行 item 出现（inProgress），随后触发审批——审批是【反向请求】，见 A.10
{ "method": "item/started", "params": {
  "threadId": "thr_123", "turnId": "turn_456", "startedAtMs": 1788516352000,
  "item": {
    "type": "commandExecution",
    "id": "item_03",
    "command": "cargo test",
    "cwd": "/Users/me/project",
    "processId": null,
    "source": "agent",
    "status": "inProgress",
    "commandActions": [],          // 对命令意图的结构化解析（读/写/执行等），可能为空数组
    "aggregatedOutput": null,
    "exitCode": null,
    "durationMs": null
  }
} }
// 审批请求是反向请求（带 id，需响应）——完整载荷见 A.10.1
{ "method": "item/commandExecution/requestApproval", "id": "req_1", "params": {
  "threadId": "thr_123", "turnId": "turn_456", "itemId": "item_03",
  "startedAtMs": 1788516352010, "environmentId": "local", "approvalId": null,
  "command": "cargo test", "cwd": "/Users/me/project", "commandActions": [],
  "reason": "命令需要在工作区执行"
} }
// 客户端回 {"id":"req_1","result":{"decision":"accept"}} 后：
{ "method": "serverRequest/resolved", "params": { "threadId": "thr_123", "requestId": "req_1" } }

// ⑤ 命令输出流式到达（delta 是纯文本，拼接即终端输出）
{ "method": "item/commandExecution/outputDelta", "params": {
  "threadId": "thr_123", "turnId": "turn_456", "itemId": "item_03",
  "delta": "    Compiling codex v0.1.0\n"
} }
{ "method": "item/commandExecution/outputDelta", "params": {
  "threadId": "thr_123", "turnId": "turn_456", "itemId": "item_03",
  "delta": "    Finished test result: ok. 42 passed\n"
} }
// 命令 item 完成：终态、退出码、耗时、聚合输出（权威结果）
{ "method": "item/completed", "params": {
  "threadId": "thr_123", "turnId": "turn_456", "completedAtMs": 1788516360500,
  "item": {
    "type": "commandExecution", "id": "item_03",
    "command": "cargo test", "cwd": "/Users/me/project",
    "processId": null, "source": "agent",
    "status": "completed",          // completed | failed | declined
    "commandActions": [],
    "aggregatedOutput": "    Compiling codex v0.1.0\n    Finished test result: ok. 42 passed\n",
    "exitCode": 0,
    "durationMs": 8490
  }
} }

// ⑥ assistant 最终回复，打字机式 delta
{ "method": "item/started", "params": {
  "threadId": "thr_123", "turnId": "turn_456", "startedAtMs": 1788516360700,
  "item": { "type": "agentMessage", "id": "item_04", "text": "", "phase": null, "memoryCitation": null, "delivery": null }
} }
{ "method": "item/agentMessage/delta", "params": {
  "threadId": "thr_123", "turnId": "turn_456", "itemId": "item_04", "delta": "测试全部通过"
} }
{ "method": "item/agentMessage/delta", "params": {
  "threadId": "thr_123", "turnId": "turn_456", "itemId": "item_04", "delta": "，42 个用例 ok。"
} }
// agentMessage 完成：text 是拼接后的完整回复；phase: commentary/finalAnswer；delivery: "async" 表示不结束轮次的中途插话
{ "method": "item/completed", "params": {
  "threadId": "thr_123", "turnId": "turn_456", "completedAtMs": 1788516362000,
  "item": {
    "type": "agentMessage", "id": "item_04",
    "text": "测试全部通过，42 个用例 ok。",
    "phase": "finalAnswer", "memoryCitation": null, "delivery": null
  }
} }

// ⑦ 轮次终态（status: completed；turn 里只附最后的 agent 消息作摘要，完整列表以 item/* 为准）
{ "method": "turn/completed", "params": {
  "threadId": "thr_123",
  "turn": {
    "id": "turn_456",
    "status": "completed",        // completed | interrupted | failed
    "items": [ /* 通常只含最后一条 agentMessage 摘要；完整 item 流来自 item/completed */ ],
    "itemsView": "full",
    "error": null,
    "startedAt": 1788516346,
    "completedAt": 1788516362,
    "durationMs": 16000
  }
} }

// ⑧ token 用量单独一条（total 为线程累计，last 为本轮；上下文窗口大小用于画用量条）
{ "method": "thread/tokenUsage/updated", "params": {
  "threadId": "thr_123", "turnId": "turn_456",
  "tokenUsage": {
    "total": { "totalTokens": 12840, "inputTokens": 11020, "cachedInputTokens": 9800,
               "cacheWriteInputTokens": 0, "outputTokens": 1820, "reasoningOutputTokens": 640 },
    "last":  { "totalTokens": 2100,  "inputTokens": 1700,  "cachedInputTokens": 1200,
               "cacheWriteInputTokens": 0, "outputTokens": 400,  "reasoningOutputTokens": 220 },
    "modelContextWindow": 272000
  }
} }

要点回顾：item/started → 若干专属 delta → item/completed 是每个 item 的固定节奏；UI 以 item/completed 和 turn/completed 为权威，delta 只做实时拼接。

A.9.2 文件改动、计划与压缩

fileChange item（apply_patch 类工具）与流式补丁预览：

// 补丁边生成边给结构化预览（changes 是当前累计快照，不是增量）
{ "method": "item/fileChange/patchUpdated", "params": {
  "threadId": "thr_123", "turnId": "turn_456", "itemId": "item_05",
  "changes": [
    { "path": "src/lib.rs", "kind": "update",
      "diff": "@@ -10,3 +10,4 @@\n pub fn add(a: i32, b: i32) -> i32 {\n-    a + b\n+    a + b + 0\n+    // 新的一行\n" }
  ]
} }
{ "method": "item/completed", "params": {
  "threadId": "thr_123", "turnId": "turn_456", "completedAtMs": 1788516400000,
  "item": {
    "type": "fileChange", "id": "item_05",
    "changes": [
      { "path": "src/lib.rs", "kind": "update", "diff": "@@ ..." }
      // kind: "add"（新增文件）| "delete"（删除）| "update"（修改，rename 时带 movePath）
    ],
    "status": "completed"          // inProgress | completed | failed | declined（用户拒绝）
  }
} }

// 本轮累计 diff 的整图快照（不用自己拼 fileChange）
{ "method": "turn/diff/updated", "params": {
  "threadId": "thr_123", "turnId": "turn_456",
  "diff": "diff --git a/src/lib.rs b/src/lib.rs\n..."
} }

// 计划模式：plan item + 结构化 plan 更新
{ "method": "turn/plan/updated", "params": {
  "turnId": "turn_456",
  "explanation": "我先跑测试再修回归",
  "plan": [
    { "step": "运行测试定位失败", "status": "completed" },
    { "step": "修复回归",       "status": "inProgress" },
    { "step": "重跑验证",       "status": "pending" }
  ]
} }

// 上下文被压缩（自动或手动）时出现，只有 id；历史在此被摘要替换
{ "method": "item/completed", "params": {
  "threadId": "thr_123", "turnId": "turn_456", "completedAtMs": 1788516500000,
  "item": { "type": "contextCompaction", "id": "item_09" }
} }

A.9.3 线程生命周期与模型旁路通知

// thread/started：线程载入完成（start/resume/fork 后），thread 是完整对象
{ "method": "thread/started", "params": {
  "thread": {
    "id": "thr_123", "sessionId": "sess_abc", "forkedFromId": null, "parentThreadId": null,
    "preview": "跑一下测试", "ephemeral": false,
    "modelProvider": "openai", "cwd": "/Users/me/project", "cliVersion": "0.0.0",
    "source": "vscode", "createdAt": 1788516340, "updatedAt": 1788516340, "recencyAt": 1788516340,
    "status": { "type": "active", "activeFlags": [] },
    "turns": []
  }
} }

// 状态变化：空闲 ↔ 活跃（活跃时可能带 waitingOnApproval / waitingOnUserInput）
{ "method": "thread/status/changed", "params": {
  "threadId": "thr_123",
  "status": { "type": "active", "activeFlags": ["waitingOnApproval"] }
} }
{ "method": "thread/status/changed", "params": {
  "threadId": "thr_123",
  "status": { "type": "idle" }
} }

// 最后一个订阅者离开约 30 分钟后，线程卸载
{ "method": "thread/closed", "params": { "threadId": "thr_123" } }

// 服务端把请求改道到另一个模型（如高风险安全检查触发）
{ "method": "model/rerouted", "params": {
  "threadId": "thr_123", "turnId": "turn_456",
  "fromModel": "gpt-5.1-codex", "toModel": "gpt-5-codex",
  "reason": "highRiskCyberActivity"
} }

// 安全审查缓冲：输出被暂存，UI 可显示"审查中"；可能换更快的模型
{ "method": "model/safetyBuffering/updated", "params": {
  "threadId": "thr_123", "turnId": "turn_456",
  "model": "gpt-5.1-codex",
  "useCases": ["cyber_safety"], "reasons": ["policy_review"],
  "showBufferingUi": true, "fasterModel": null
} }

A.9.4 错误与警告通知

// 瞬时故障（断流/限流）：willRetry=true，轮次没死，UI 只提示"重连中"，不要改状态
{ "method": "error", "params": {
  "threadId": "thr_123", "turnId": "turn_456", "willRetry": true,
  "error": {
    "message": "Reconnecting... 2/5",
    "codexErrorInfo": { "responseStreamDisconnected": { "httpStatusCode": 200 } },
    "additionalDetails": "stream closed before response.completed"
  }
} }

// 终态错误：willRetry=false；同样内容会出现在随后的 turn/completed（status:"failed"）
{ "method": "error", "params": {
  "threadId": "thr_123", "turnId": "turn_456", "willRetry": false,
  "error": {
    "message": "Usage limit reached",
    "codexErrorInfo": "usageLimitExceeded"
  }
} }

// 非致命警告（线程相关时带 threadId）
{ "method": "warning", "params": { "threadId": "thr_123", "message": "部分已启用的 skill 未列入本会话的模型可见列表" } }

// 配置类诊断（初始化或 thread/start 时的 exec-policy 解析问题）
{ "method": "configWarning", "params": {
  "summary": "config.toml 中有无法识别的字段",
  "details": "unknown field `foo` at line 12",
  "path": "/Users/me/.codex/config.toml"
} }

codexErrorInfo 的常见取值（字符串形式或带 HTTP 状态码的对象形式）： contextWindowExceeded、sessionBudgetExceeded、usageLimitExceeded、serverOverloaded、 cyberPolicy、misalignmentPolicyViolation、badRequest、unauthorized、sandboxError、 internalServerError、other；对象形式有 httpConnectionFailed、responseStreamConnectionFailed、 responseStreamDisconnected、responseTooManyFailedAttempts（均带 httpStatusCode，可为 null）、 activeTurnNotSteerable（带 turnKind: "review" | "compact"）。

反向请求（审批、提问、表单、动态工具）也是服务端 → 客户端，但它们带 id、必须应答，不是通知。完整载荷与应答格式见下一节 A.10。

---

A.10 反向请求：服务端向客户端“要东西”

这是对接时最容易漏掉的部分：服务端也会发带 id 的请求，客户端必须响应（第二章 2.3 的“问与答”）。轮次结束/中断时未决请求会被服务端自动中止，并发 serverRequest/resolved 清理。

方法	触发场景	客户端应答
item/commandExecution/requestApproval	命令需审批	{ "decision": ... }，见下表
item/fileChange/requestApproval	文件改动需审批	{ "decision": "accept" | "acceptForSession" | "decline" | "cancel" }
item/permissions/requestApproval	工具申请额外权限（网络/路径）	{ permissions, scope: "turn"|"session" }
item/tool/requestUserInput	agent 向用户提问	按请求的 schema 返回答案；含 isBlocking 标识
mcpServer/elicitation/request	MCP 服务器弹表单/URL	{ action: "accept"|"decline"|"cancel", content? }
item/tool/call	动态工具交给客户端执行	返回工具执行结果
attestation/generate	上游需要客户端证明（需握手声明 requestAttestation）	{ token: "v1.<opaque>" }
currentTime/read [EXP]	外部时钟模式下读时间	{ currentTimeAt: <Unix 秒> }
account/chatgptAuthTokens/refresh	刷新 ChatGPT 令牌	新令牌

命令审批的 decision 取值（文件改动审批是其子集）：

decision	含义
"accept"	本次允许
"acceptForSession"	本线程内同类操作不再询问
"decline"	拒绝，但轮次继续（模型会看到拒绝结果）
"cancel"	拒绝并立即中断轮次
{ "acceptWithExecpolicyAmendment": { ... } }	允许并把该命令前缀沉淀为持久规则
{ "applyNetworkPolicyAmendment": { ... } }	允许网络访问并沉淀域名规则

审批消息序列（以命令为例）：

sequenceDiagram
    participant S as app-server
    participant C as 客户端
    S-->>C: 通知 item/started（commandExecution, inProgress）
    S-->>C: 请求 item/commandExecution/requestApproval（id=R1，含 command/cwd/reason）
    Note over C: 展示命令与风险，用户选择
    C->>S: 响应 R1 { "decision": "accept" }
    S-->>C: 通知 serverRequest/resolved { requestId: "R1" }
    S-->>C: 通知 item/commandExecution/outputDelta ×N
    S-->>C: 通知 item/completed（commandExecution, status: completed）

A.10.1 反向请求的完整载荷

命令审批请求与应答（请求带 id，响应 id 原样带回）：

// 服务端 → 客户端：请求（注意它是 request，有 id）
{
  "method": "item/commandExecution/requestApproval",
  "id": "req_1",
  "params": {
    "threadId": "thr_123",
    "turnId": "turn_456",
    "itemId": "item_03",
    "startedAtMs": 1788516352010,
    "environmentId": "local",
    "approvalId": null,
    "command": "cargo test",
    "cwd": "/Users/me/project",
    "commandActions": [],
    "reason": "命令需要在工作区执行"
    // [EXP] 可能还有 additionalPermissions（申请的沙箱权限）、
    // networkApprovalContext（纯网络审批时）、availableDecisions（建议的可选项）、
    // proposedExecpolicyAmendment / proposedNetworkPolicyAmendments（持久规则建议）
  }
}

// 客户端 → 服务端：应答（id 必须与请求一致，包在 result 里）
{ "id": "req_1", "result": { "decision": "accept" } }
// 其他 decision 示例：
// { "id": "req_1", "result": { "decision": "acceptForSession" } }   // 本线程不再问
// { "id": "req_1", "result": { "decision": "decline" } }            // 拒绝但轮次继续
// { "id": "req_1", "result": { "decision": "cancel" } }             // 拒绝并中断轮次
// { "id": "req_1", "result": { "decision": {
//     "applyNetworkPolicyAmendment": { "networkPolicyAmendment": { "host": "example.com", "action": "allow" } }
// } } }

// 服务端随后发一条通知，表示该请求已结算（清理 UI 上的审批框）
{ "method": "serverRequest/resolved", "params": { "threadId": "thr_123", "requestId": "req_1" } }

向用户提问（item/tool/requestUserInput）：

{
  "method": "item/tool/requestUserInput",
  "id": "req_2",
  "params": {
    "threadId": "thr_123", "turnId": "turn_456", "itemId": "item_07",
    "isBlocking": true,
    "questions": [ /* 按请求中的结构化问题渲染表单 */ ]
  }
}
// 客户端按问题回填答案，用同一个 id 响应；轮次结束前未答会收到 serverRequest/resolved 清理
{ "id": "req_2", "result": { /* answers */ } }

MCP 表单（mcpServer/elicitation/request）：

{
  "method": "mcpServer/elicitation/request",
  "id": "req_3",
  "params": {
    "threadId": "thr_123", "turnId": "turn_456",
    "serverName": "github",
    "mode": "form",                          // "form" | "openai/form" | "url"
    "message": "授权访问 GitHub 仓库",
    "requestedSchema": { /* JSON Schema，客户端据此渲染表单；不认识的字段要能回 decline */ }
  }
}
// 应答：
// { "id": "req_3", "result": { "action": "accept", "content": { ... } } }
// { "id": "req_3", "result": { "action": "decline", "content": null } }
// { "id": "req_3", "result": { "action": "cancel",  "content": null } }

可靠性提示：反向请求绝不允许不答。客户端无法处理时（比如不认识的表单），也要回 decline/cancel 或错误响应，否则轮次会永远挂起。过载时普通通知可能被丢弃，但反向请求会失败返回而不是静默消失。

---

A.11 错误处理

两层错误，别混淆：

1. RPC 层错误（请求本身失败）：{ "id": <id>, "error": { "code", "message", "data?" } }

• -32001：服务端过载，退避重试；
• 握手前 / 重复握手：“Not initialized” / “Already initialized”；
• turn/steer 目标轮次不存在或不可插话：invalid request 类错误；
• 未开实验能力调 [EXP] 方法：requires experimentalApi capability。

2. turn 层错误（轮次跑起来之后失败）：走 error 通知：

{
  "method": "error",
  "params": {
    "threadId": "thr_123",
    "turnId": "turn_456",
    "willRetry": true,            // true = 瞬时故障（断流/限流），app-server 正在自动重试，轮次没死
    "error": {
      "message": "Reconnecting... 2/5",
      "codexErrorInfo": "responseStreamDisconnected",  // 可选，机器可读分类
      "additionalDetails": "..."
    }
  }
}

处理规则：

• willRetry: true 不要动 UI 状态：这是“重连中”提示（第二章 2.4.5），轮次仍在 inProgress，重试成功后 delta 流继续；
• 终态错误出现在 turn/completed 的 turn.error 里（status: "failed"）；
• codexErrorInfo 常见值：contextWindowExceeded（上下文超长，触发压缩而非崩溃）、usageLimitExceeded（额度耗尽）、serverOverloaded、responseStreamDisconnected / httpConnectionFailed（带 HTTP 状态码）、cyberPolicy / misalignmentPolicyViolation（安全策略拦截）、activeTurnNotSteerable（插话目标是审查/压缩轮次）等。

---

A.12 最小客户端骨架（伪代码）

proc = spawn(["codex", "app-server"])          # 默认 stdio，JSONL
next_id = 0
pending = {}                                   # id -> Future

def send(method, params=None, notify=False):
    msg = {"method": method, **({"params": params} if params else {})}
    if not notify:
        msg["id"] = (next_id := next_id + 1)
    proc.stdin.write(json.dumps(msg) + "\n")

def on_message(line):
    msg = json.loads(line)
    if "method" in msg and "id" in msg:
        on_server_request(msg)                 # 反向请求：必须响应
    elif "method" in msg:
        on_notification(msg["method"], msg.get("params"))
    elif "id" in pending:
        pending.pop(msg["id"]).resolve(msg.get("result", msg.get("error")))

def on_notification(method, p):
    if method == "turn/completed":
        render_turn(p["turn"])                 # 权威终态
    elif method == "item/completed":
        upsert_item(p["item"])                  # 权威 item
    elif method == "item/agentMessage/delta":
        append_delta(p["itemId"], p["delta"])   # 临时渲染
    elif method == "item/commandExecution/requestApproval":
        decision = show_approval_dialog(p)     # 弹框
        send_response(p["id"], {"decision": decision})
    # ...其余通知按 A.8 分发

# 启动三步
send("initialize", {"clientInfo": {"name": "my_client", "version": "0.1"}})
wait_response()
send("initialized", notify=True)
thread = send("thread/start", {"cwd": "/path/to/project"})["thread"]
send("turn/start", {"threadId": thread["id"],
                    "input": [{"type": "text", "text": "你好"}]})

对接 checklist：

• 按行/按 frame 切分消息，响应靠 id 配对；
• 严格走完 initialize → initialized 握手再发其他请求；
• 维护 thread/turn/item 三级 UI 模型，item/completed 与 turn/completed 为准，delta 只做临时态；
• 实现全部反向请求的应答（哪怕不支持也回 decline/cancel）；
• willRetry: true 的 error 只提示、不改状态；
• 用 optOutNotificationMethods 关掉不需要的通知控流量；
• 断线重连后用 thread/resume + thread/read（或 thread/items/list）重新对齐状态；
• 字段以随版本发布的 JSON Schema / TypeScript 类型为最终准绳（实验方法会演进，稳定方法保持兼容）。

---

A.13 与第二章正文的对照表

第二章的概念	app-server 线上的样子
Op（前端 → 内核）	客户端请求：turn/start、turn/steer、turn/interrupt……
Event（内核 → 前端）	服务端通知：turn/*、item/*……
“确认即回”（2.3）	turn/start 立即返回 { turn: { status: "inProgress" } }，后续走通知
“问与答”反向请求（2.3）	服务端请求：*/requestApproval、requestUserInput、elicitation……
item 权威 / delta 易失（2.4.5、2.8）	item/completed 重建状态；*/delta 只做打字机；重连不补发
错误是事件（2.4.4）	error 通知（willRetry 区分重试中 vs 终态）
中断即翻篇（第一章 1.5）	turn/interrupt → turn/completed（status: "interrupted"），后台终端不受影响
三代事件并存（2.6）	稳定 item/* 通知 + 内部 rawResponse* 透传；废弃方法保留但标注 deprecated
实验门控（2.7）	capabilities.experimentalApi + [EXP] 标记

第十一章最后留下了一个问题：当 skill、MCP、hook、dynamic tool 和多 agent 都进入同一套 LOOP，系统怎样解释“为什么模型没用某项能力”？ 传统服务的可观测性主要回答“请求是否成功、耗时多少、哪里报错”。Agent harness 还必须回答更难的问题：模型当时看到了什么、为什么决定调用这个工具、审批和策略怎样改变了行动、结果是否真正回到上下文、恢复后的执行与过去有什么关系。 因此，Codex 的可观测性不只是 logs、traces 和 metrics。前端事件、rollout 与诊断 replay 共同组成了一条从实时现象到历史证据的观察链。 本章关心的不是“埋了多少点”，而是如何把一次不可预先确定的 agent 行为，还原成一条可定位、可归因、可解释的因果链。

---

12.1 为什么 agent 比普通服务更难观察

普通 HTTP 服务通常有相对确定的控制流：

收到请求 → 校验参数 → 查询数据库 → 返回响应

请求慢了，可以沿着固定调用链检查数据库、缓存和下游服务；请求错了，可以从状态码和异常堆栈定位失败点。

Agent 的控制流不是提前写死的。一次用户输入可能经历：

构造上下文
→ 模型采样
→ 输出 reasoning
→ 调用两个工具
→ 等待用户批准
→ 并行派生三个子 agent
→ 再次采样
→ 触发压缩
→ 切换模型连接
→ 给出最终回答

下一步做什么，由模型根据当时可见的历史、instruction、工具 spec 和工具结果临时决定。相同输入在不同世界状态下，可能走出完全不同的路径。

这给可观测性增加了四种困难。

12.1.1 控制流是运行时生成的

工具调用不是业务代码里固定的一行函数调用，而是模型输出的 item。要解释一次行动，不能只看工具执行阶段，还要知道：

• 本轮有哪些工具对模型可见；
• 模型生成了什么调用；
• harness 是否接受并正确解析；
• policy、审批和沙箱是否允许；
• 工具结果是否回灌；
• 回灌后模型是否继续采样。

只观察执行器，会错过行动产生之前和结果回灌之后的半条链路。

12.1.2 “成功”有多个层次

一次 MCP 请求返回成功，不代表任务成功；命令退出码为零，不代表模型正确理解了输出；turn 正常结束，也不代表用户目标达成。

至少要区分：

层次	“成功”意味着什么
传输	请求和流没有断开
协议	item、delta、工具参数能被正确解析
执行	工具或外部服务完成了动作
LOOP	结果进入上下文，循环正常推进
任务	agent 给出了结果或明确说明阻塞
用户目标	最终产物真的满足需求

前四层可以由 harness 较可靠地观察；最后一层通常仍需要用户反馈、评测或业务系统验证。

12.1.3 等待与计算混在同一条时间线上

一个 turn 用了十分钟，可能是：

• 模型首 token 很慢；
• 工具在排队；
• 命令执行很慢；
• MCP server 响应很慢；
• 等了用户九分钟才批准；
• 上下文过长，触发了 compaction；
• 模型流断开后发生重试；
• 子 agent 尚未返回。

只记录一个 turn_duration = 10min 几乎没有诊断价值。Agent 可观测性必须把模型时间、工具时间、调度时间、人工等待时间和 harness 自身开销拆开。

12.1.4 现在看到的状态，不一定能解释过去

工具目录会刷新，配置会变化，plugin 会升级，工作区文件会被修改。故障发生半小时后再查看当前状态，可能已经无法回答：

• 当时模型看到的是哪一版 tool spec？
• 那个 skill 是否已经激活？
• 策略为何拒绝了命令？
• 子 agent 收到的究竟是哪条消息？
• 模型请求中实际包含哪些历史 item？

因此，agent harness 不仅需要实时 telemetry，还需要能在事后重建语义关系的 replay 证据。

可观测性的目标不是证明“系统记录过什么”，而是让人能从证据回答：发生了什么、为何发生、时间花在哪里、现在能否安全继续。

---

12.2 五种证据：每一种都只回答一部分问题

Codex 中可以观察到五类互补的信息：

证据	最擅长回答	不擅长回答
前端 Event	用户当时看到了什么，turn/item 如何推进	跨服务内部耗时、未对前端公开的细节
Logs	某个时刻发生了什么错误，携带哪些局部字段	完整调用树、总体趋势
Traces	一次请求跨组件经过哪里，各阶段耗时和父子关系	长期统计、完整恢复语义
Metrics	错误率、延迟分布、吞吐、资源和容量趋势	单次异常的完整上下文
Replay evidence	过去的语义事实如何关联，模型实际看到了什么	低成本实时告警

它们不是重复记录同一件事，而是从不同角度投影同一段执行。

flowchart TB
    RUN["一次真实执行"]

    RUN --> EVT["前端 Event<br/>实时交互事实"]
    RUN --> LOG["Logs<br/>局部诊断细节"]
    RUN --> TR["Traces<br/>跨组件因果与耗时"]
    RUN --> MET["Metrics<br/>聚合趋势与告警"]
    RUN --> REP["Replay evidence<br/>离线语义重建"]

    EVT --> UI["重建用户所见"]
    LOG --> DEBUG["定位具体错误"]
    TR --> PATH["追踪请求路径"]
    MET --> SLO["发现系统性退化"]
    REP --> WHY["解释过去为何如此行动"]

这五类证据对应五种不同的问题：

Event：界面为什么停在这里？
Log：这一刻具体报了什么？
Trace：时间花在哪条链路？
Metric：这是个例，还是系统性问题？
Replay：模型当时依据哪些事实作出决定？

如果只保留其中一种，都会产生盲区。

• 只有 logs：能搜索错误，却难以拼出并发链路。
• 只有 traces：能看调用树，却未必知道模型上下文和恢复语义。
• 只有 metrics：知道 P95 变差，却不知道哪一次请求发生了什么。
• 只有 rollout：能恢复对话，却没有足够细的 timing 和内部决策证据。
• 只有前端 Event：能复现界面，却不一定能解释底层策略和网络行为。

成熟的设计不是把所有数据塞进一套系统，而是让它们共享稳定的标识符，可以互相跳转和交叉验证。

---

12.3 先建立坐标：trace ID 不等于业务身份

分布式 tracing 常用 trace_id 串起一次请求。但对 agent 来说，仅靠 trace_id 不够。

一个 thread 可以活几天，包含很多 turns；一个 turn 内可能有多次模型采样和几十次工具调用；一个子 agent 的工作可能由父 agent 触发，却在另一条异步链路上执行；进程重启后，旧 span 已经结束，但同一个 thread 还会 resume。

所以 Codex 同时需要两类坐标。

12.3.1 运行时坐标：这件事属于谁

标识符	回答的问题
thread_id	发生在哪个 agent thread
turn_id	属于哪一次用户驱动的工作
root_turn_id	整棵多 agent 工作由哪个根 turn 发起
parent_turn_id	当前工作直接由哪个 turn 派生
item_id	对应哪条消息、reasoning、工具调用或结果

12.3.2 调用坐标：这次交互是哪一次

标识符	回答的问题
call_id	某次 tool call 与结果如何配对
inference_call_id	属于哪一次模型采样
mcp_call_id	MCP 请求、响应和工具语义如何关联
communication_id	多 agent 消息从发送到接收如何配对
trace_id	这次在线执行跨越了哪些进程和传输

可以把二者理解为：

• 业务坐标说明“这是故事中的哪一段”；
• trace 坐标说明“这一次运行经过了哪些机器和函数”。

flowchart LR
    ROOT["root_turn_id"]
    PARENT["parent_turn_id"]
    TURN["turn_id"]
    INF["inference_call_id"]
    ITEM["item_id"]
    CALL["call_id"]
    TRACE["trace_id"]

    ROOT --> PARENT --> TURN
    TURN --> INF
    INF --> ITEM
    ITEM --> CALL
    TRACE -. "贯穿本次在线执行" .-> TURN
    TRACE -.-> INF
    TRACE -.-> CALL

这套双坐标解决了一个常见误区：span tree 不等于 agent 的业务树。

异步任务可能脱离原来的调用栈；消息经过队列后，发送者和接收者不再是直接父子 span；resume 可能为同一个业务 turn 创建新的 trace；多 agent 的父子关系也不是普通函数调用关系。

因此，tracing 系统应该同时使用：

• parent-child span 表示真实的在线调用嵌套；
• link 或业务 ID 表示跨队列、跨进程、跨恢复的因果关系；
• rollout 中的 lineage 表示长期稳定的 agent 历史关系。

不要为了让 trace 图看起来像一棵整齐的树，就伪造并不存在的同步父子关系。

---

12.4 端到端 tracing：把一次 turn 串起来

一次来自网络前端的 turn，通常会跨过这些边界：

sequenceDiagram
    participant FE as 前端程序
    participant AS as App Server
    participant Q as Submission Queue
    participant T as Turn Task
    participant L as LOOP
    participant M as Model Service
    participant P as Policy / Approval
    participant X as Tool / MCP / Exec Server

    FE->>AS: thread/turn 请求 + trace context
    AS->>AS: app-server request span
    AS->>Q: Submission + trace context
    Q->>T: dispatch turn
    T->>T: turn span
    T->>L: run LOOP
    L->>M: inference request + W3C trace context
    M-->>L: streaming item / delta
    L->>P: 工具决策与权限判断
    P-->>L: allow / deny / ask user
    L->>X: 执行工具 + trace context
    X-->>L: tool result
    L->>M: 回灌结果，继续采样
    M-->>L: final response
    L-->>T: turn complete
    T-->>AS: Event stream
    AS-->>FE: 通知与最终 item

W3C traceparent 和 tracestate 负责让上下游接续同一条 trace。它们可以穿过：

• 前端到 app-server 的请求；
• app-server 到内核的 submission；
• 内核到模型服务的 HTTP 请求；
• WebSocket 建连时的 metadata；
• harness 到独立 exec-server 或其他支持 tracing 的组件。

但“把 header 传过去”只是第一步。真正有诊断价值的 trace，还需要合理的 span 层级。

12.4.1 Span 应围绕语义阶段，而不是每个函数

典型层级可以是：

app-server request
└── submission dispatch
    └── turn
        ├── prepare context
        ├── inference call #1
        │   ├── send request
        │   ├── receive stream
        │   └── handle response items
        ├── tool call A
        │   ├── wait for concurrency permit
        │   ├── policy / approval
        │   └── execute
        ├── tool call B
        ├── inference call #2
        └── finalize turn

好的 span 有三个特点：

1. 对应人能理解的阶段。 “模型流接收”比某个内部函数名更稳定。
2. 有明确的开始和结束。 结束时才能计算 duration 和 outcome。
3. 不会因为实现重构就完全失效。 可观测语义应比代码调用栈更稳定。

如果给每个小函数都建 span，会得到一张巨大但无法阅读的火焰图；如果只给整个 turn 建一个 span，又无法解释时间去哪了。观察粒度应该围绕生命周期边界和外部交互。

12.4.2 Event 与 span 各司其职

持续一段时间的动作适合 span：

• 一次模型采样；
• 一次工具执行；
• 一次 MCP 调用；
• 一次 compaction；
• 一次 hook；
• 一段等待或重试。

瞬时事实适合 event：

• 收到首个 token；
• 模型改道；
• policy 给出 deny；
• sandbox 拒绝；
• SSE 重连；
• token usage 结算；
• 某个 item 完成。

把所有事实都做成 span，会制造大量零时长节点；把长操作只记成开始、结束两条 log，又容易在并发环境中配错。span 表示区间，event 表示区间中的关键点。

---

12.5 Turn latency：总耗时只是答案的开头

用户最直接的感受是“这个 turn 很慢”。但一个总时长不能指导优化。Codex 会把 turn 的时间拆成若干阶段：

阶段	含义
before_first_sampling	turn 开始后，到第一次模型采样前的准备时间
sampling	所有模型采样和流式接收累计时间
compaction	上下文压缩消耗的时间
between_sampling_overhead	两次采样之间未归入工具和压缩的 harness 开销
tool_blocking	LOOP 等待工具 future 完成的时间
after_last_sampling	最后一次采样结束后，到 turn 完成前的收尾时间

同时还要记录：

• sampling request 数量；
• sampling retry 数量；
• TTFT（time to first token）；
• TTFM（time to first meaningful output）；
• 输入、输出、缓存和 reasoning token；
• 最终 outcome。

flowchart LR
    START["Turn 开始"] --> PRE["采样前准备"]
    PRE --> S1["Sampling 1"]
    S1 --> MID["采样间阶段"]
    MID --> S2["Sampling 2"]
    S2 --> POST["采样后收尾"]
    POST --> DONE["Turn 完成"]

    MID -. "主要等待" .-> TOOL["Tool blocking"]
    MID -. "harness 开销" .-> OVER["Between-sampling overhead"]
    MID -. "按需触发" .-> COMP["Compaction"]

这张图最重要的含义是：

E2E 慢，不等于模型慢。

例如：

• TTFT 高：更可能是模型排队、网络或请求体过大；
• TTFT 正常但 sampling 长：可能是输出很多、reasoning 很长或流速慢；
• sampling 不长但 tool blocking 高：应继续检查工具、MCP、审批或并发闸门；
• compaction 占比高：说明上下文压力已经进入用户可感知路径；
• between-sampling overhead 高：可能是结果归一化、上下文重建、hook 或调度开销；
• sampling retry 增加：最终请求虽成功，但连接质量或服务限流正在恶化。

12.5.1 TTFT 与 TTFM 不是一回事

第一个流式字节可能只是协议心跳、response created 或空 delta。用户真正感知到“agent 开始回应”，往往要等到首段可显示文本、reasoning summary、计划或工具动作出现。

因此：

• TTFT 更适合观察传输和模型服务是否开始返回；
• TTFM 更接近用户感知到有效进展的时间。

如果 TTFT 很低、TTFM 很高，问题可能不在网络，而在模型长时间生成不可见 reasoning、前端过滤策略或 item 聚合逻辑。

12.5.2 当前时间分类仍然可能有空白

时间分解不是天然准确的。每一毫秒只能在埋点边界足够清楚时被正确归类。

例如，tool_blocking 表示 LOOP 等待工具 future 的时间。这个 future 内部可能包含：

• 等待并发 permit；
• 路由和参数校验；
• policy 判断；
• 等待用户审批；
• 选择 sandbox；
• 真正执行；
• 结果归一化。

所以 tool_blocking = 60s 不能直接推导出“命令执行了 60s”。还要进入单工具 timing 继续拆解。

同样，Human in the loop 的等待虽然是非常重要的用户体验指标，但如果系统没有统一的 approval_wait 或 human_wait 阶段，它就可能被包含在工具 handler 或其他等待中。指标缺少一个分类，本身也是可观测性结论，而不是应该被报表掩盖的问题。

---

12.6 工具链路：一次调用至少经过四段

第六章把工具调用拆成 spec、路由、policy、执行和结果回灌。可观测性也必须沿着同样的边界展开。

flowchart LR
    A["模型生成 tool call"] --> B["解析与路由"]
    B --> C["等待 runtime ready<br/>等待并发 permit"]
    C --> D["policy / guardian<br/>审批 / sandbox"]
    D --> E["真实执行<br/>local / MCP / dynamic"]
    E --> F["结果归一化"]
    F --> G["tool result 回灌"]
    G --> H["下一次 sampling"]

一条有用的工具记录至少应该包含：

• 所属 thread_id、turn_id 和 trace_id；
• tool_name、call_id 和执行类型；
• 开始、结束、总耗时；
• 排队或 dispatch 耗时；
• handler 耗时；
• outcome 和错误类别；
• 是否经过审批、沙箱升级或 guardian；
• 结果大小，而不是默认记录全部结果正文。

12.6.1 不要把 handler duration 当成纯执行时间

工具 timing 常见三个值：

指标	通常覆盖什么
dispatch_duration	runtime readiness、并发 permit 等进入 handler 前的等待
handler_duration	路由后的完整处理，包括 policy、审批、sandbox 和真实执行
total_duration	从调用被接收到结果返回的总时间

handler_duration 并不等于 shell process 的 wall time。它是“handler 拿到调用以后直到返回”的黑盒区间。

如果要回答“为什么命令慢”，还需要执行域自己的子指标：

• exec-server queue duration；
• process spawn duration；
• process running duration；
• stdout/stderr drain 与退出收尾；
• MCP request latency；
• dynamic tool 等待前端响应的时间。

只有逐层拆开，才能区分：

慢在 harness 排队
≠ 慢在等用户
≠ 慢在沙箱准备
≠ 慢在外部服务
≠ 慢在进程本身

12.6.2 错误要按阶段分类

“工具失败”也不是一个充分的错误类别。

阶段	示例
模型输出	tool name 不存在、参数 JSON 不完整
路由	catalog revision 已过期、runtime 不可用
policy	命令被规则拒绝、guardian 否决
approval	用户拒绝、请求超时、前端断开
sandbox	OS 拒绝访问、沙箱后端启动失败
transport	MCP 断连、请求超时、协议错误
tool result	MCP 请求成功，但工具返回业务错误
feedback	结果过大、编码失败、无法进入上下文

尤其要区分 MCP 的请求失败和工具结果为 error：

• 请求失败表示没有正常完成协议交互；
• error result 表示 server 正常回复，只是业务动作失败。

二者的重试、告警和责任归属完全不同。

---

12.7 决策也要可观察：不仅记录“做了什么”

Agent 的问题经常不是某个函数报错，而是“为什么没有走预期路径”。

例如用户问：

为什么 agent 明明安装了数据库 skill，却没有调用数据库工具？

要回答这个问题，至少要检查一条完整的能力因果链：

flowchart LR
    P["能力来源<br/>plugin / project / user"] --> D["Discovery<br/>是否被发现"]
    D --> A["Activation<br/>是否启用与受信任"]
    A --> V["Visibility<br/>本 step 是否对模型可见"]
    V --> M["Model decision<br/>是否生成调用"]
    M --> R["Routing<br/>是否绑定正确 runtime"]
    R --> S["Safety<br/>policy / approval / sandbox"]
    S --> X["Execution<br/>是否成功执行"]
    X --> F["Feedback<br/>结果是否进入上下文"]

如果只记录最后的 tool call，模型没有调用时就什么也看不到。可观测系统还需要记录“未发生之前”的关键状态：

• catalog 是否发现能力；
• activation 是否禁用，以及禁用原因；
• step snapshot 中是否包含对应 tool spec；
• 是否因为 deferred exposure 尚未展开；
• 模型是否输出了相近但不存在的工具名；
• policy 是否在执行前拒绝；
• 结果是否因为过大或协议错误未能回灌。

这并不意味着要保存模型内部不可见的“真实思想”。系统只能观察协议上出现的 reasoning、item、调用和配置事实，不能从 telemetry 推断模型心里一定在想什么。

可解释性必须建立在可验证证据上。记录“模型看到了什么”和“模型输出了什么”，比事后编造一个看似合理的动机更可靠。

12.7.1 安全裁决需要结构化字段

第八章讨论过 policy、guardian 和网络管控。它们的可观测结果不能只是一行自然语言：

request denied

至少应结构化记录：

• decision：allow、deny、ask；
• rule 或 policy 来源；
• risk 分类；
• authorization 类型；
• 是否发生 sandbox escalation；
• 网络目标的域名、协议和端口；
• 耗时和失败阶段。

这样既能聚合“最近 deny 是否暴增”，也能在单次 trace 中解释“谁做了最终决定”。

网络审计尤其应遵循最小披露：通常记录域名、协议、端口和裁决已经足够，不必保存完整 URL、query 或认证信息。

12.7.2 Hook 要区分控制结果和旁路结果

同步 hook 可能阻止流程，异步 hook 通常只做通知或上报。两者在 telemetry 中必须区分：

• hook 名称、来源和版本；
• 触发生命周期点；
• sync 或 async；
• duration；
• allow、block、modify、error 或 timeout；
• 是否改变了最终控制流。

否则一个异步上报失败可能被误读成任务失败，或者一个真正阻断执行的 hook 只留下一条不起眼的 warning。

---

12.8 多 agent：调用树之外还有一棵协作树

第七章中，多 agent 通过 spawn、消息和结果交付形成一棵 thread tree。可观测性必须同时面对两棵树：

1. 执行树：span 的父子关系，表示这次在线调用如何展开；
2. 协作树：root turn、parent turn、thread lineage 和 communication，表示任务如何委派。

它们经常重合，但并不等价。

flowchart TB
    RT["Root turn T0"]
    A["Agent A / thread A"]
    B["Agent B / thread B"]
    C["Agent C / thread C"]
    M1["message c1"]
    M2["message c2"]

    RT --> A
    RT --> B
    A --> C
    B --> M1 --> A
    C --> M2 --> A

    subgraph Traces["可能分散在多条在线 trace 中"]
        TR1["trace x：spawn A/B"]
        TR2["trace y：B 完成后投递"]
        TR3["trace z：resume A 并消费结果"]
    end

如果只看 trace_id，可能看到三段互不相连的执行；如果只看 thread_id，又无法知道一条消息属于哪个根任务。

多 agent 观测至少需要：

• root、parent、child 的 thread 与 turn 坐标；
• spawn 请求与 agent 启动结果；
• communication ID；
• 发送、排队、投递、消费四个时刻；
• 子 agent 的最终状态和结果 item；
• 并发 permit 的等待时间；
• 父 turn 是否在等待、取消或已经结束。

12.8.1 “子 agent 很慢”仍然需要拆解

父 agent 等待子 agent 30 秒，可能是：

• 子 agent 排队等并发名额；
• 子 agent 自己在等模型；
• 子 agent 在跑工具；
• 结果已产生，但消息尚未投递；
• 消息已投递，但父 agent 尚未进入下一个 step；
• 父 turn 已中断，结果成为迟到消息。

因此，多 agent latency 不能只记录 spawn → result。它应至少区分：

spawn queue
→ child active
→ child result ready
→ message delivered
→ parent consumed

这和第二章的 Event 原则、第五章的 LOOP 边界以及第十章的恢复语义是同一个问题：事实产生、事实送达、事实被消费，是三个不同时间点。

---

12.9 Metrics：用聚合信号发现系统性问题

Trace 适合解释一次请求，metrics 适合回答：

• 最近一小时 turn 错误率是否升高？
• P95 TTFT 是否只在某个模型上恶化？
• MCP timeout 是否集中于某个 server？
• 工具队列是否接近容量？
• compaction 是否越来越频繁？
• guardian 的 deny 比例是否异常？
• SQLite 初始化或 fallback 是否增加？

12.9.1 三种基础指标

类型	含义	Agent 场景
Counter	只增加的累计次数	turn、请求、错误、重试、tool call
Gauge	某一时刻的当前值	活跃 turn、队列长度、连接数、运行中进程
Histogram	一组数值的分布	TTFT、turn duration、tool duration、token

平均值常常会掩盖 agent 的长尾。比如九个 turn 用 5 秒，一个 turn 因审批等待用了 10 分钟，平均值看起来只有约 65 秒，却同时误导了两类用户。

延迟应重点看分位数，并按有意义的阶段拆分：

• P50 反映常见体验；
• P95/P99 揭示长尾；
• max 帮助发现极端挂起，但不适合单独告警。

12.9.2 指标应围绕用户体验和容量

一套实用指标通常覆盖：

请求与模型

• API 请求次数、状态和 duration；
• SSE/WebSocket 连接、事件和重连；
• TTFT、TTFM；
• token usage；
• sampling retries。

Turn 与 LOOP

• turn E2E duration；
• 各 timing phase；
• 每个 turn 的 sampling 次数；
• compaction 次数和耗时；
• complete、interrupt、error 等 outcome。

工具与扩展

• tool、MCP、hook、plugin、skill 的调用或激活结果；
• 排队、handler、执行 duration；
• timeout、deny、approval 和 sandbox outcome；
• catalog 刷新和启动失败。

运行时资源

• submission queue；
• tool concurrency；
• child agent permit；
• exec-server queue、process、connection；
• telemetry 自身队列和丢弃数；
• 持久化初始化、写入和 fallback。

12.9.3 Tag 基数是一项架构约束

Metrics 系统最怕高基数标签。把 thread_id、turn_id、call_id、完整错误信息、文件路径或用户 prompt 放进 tag，会让时间序列数量无限增长。

适合作为 metric tag 的字段通常是：

• model family；
• tool category；
• outcome；
• error class；
• transport；
• sandbox mode；
• approval decision；
• feature name。

不适合作为 tag 的字段通常是：

• 任意 ID；
• URL 和路径；
• 用户名和项目名；
• 原始异常文本；
• 工具参数和输出。

单次 ID 应进入 trace 或 log，聚合维度才进入 metrics。所有 tag 还应经过白名单、长度限制和 sanitize。

Metrics 负责“分组”，traces 负责“定位”。试图让 metrics 同时完成定位，会把监控系统变成另一个高成本数据库。

---

12.10 三种 replay：恢复、重建界面与诊断不是一回事

“回放”在 agent 系统里经常指三种完全不同的机制。

Replay	目的	主要输入	结果
Rollout replay	恢复 Session 和模型历史	canonical rollout item	可继续工作的运行时状态
UI event replay	重建前端看到的 turn/item	持久化 item 和状态投影	对话、工具和状态界面
Rollout-trace replay	离线分析因果链	更细粒度的原始诊断事件与 payload	语义关系图和调查证据

12.10.1 Rollout replay：为了继续工作

第十章已经说明，rollout 保存的是恢复所需的 canonical facts：

• 用户和 assistant item；
• 工具调用与结果；
• turn 边界；
• compaction；
• 配置和世界状态相关事实；
• 多 agent lineage。

它的兼容性要求高，生命周期长，但不会保存所有内部细节。它不需要记录每个函数耗时，也不应该默认保存每个流式 delta。

Rollout replay 的问题是：

“恢复后，模型应该看到怎样的有效历史？”

12.10.2 UI event replay：为了重建用户所见

前端关心的是：

• 哪个 turn 开始或结束；
• 哪个 item 已完成；
• 命令和补丁显示什么状态；
• 哪些审批仍需处理；
• token 与 warning 如何展示。

它可以从 canonical item 与运行时状态生成一份 UI projection。瞬时 delta 丢失后，完整 item 仍能恢复最终界面；但“当时每个字以什么速度出现”通常不值得长期保存。

UI event replay 的问题是：

“重新连接以后，前端应该显示什么？”

12.10.3 Rollout-trace replay：为了理解过去

诊断 replay 需要比 canonical rollout 更细的证据，例如：

• 每次 inference 的请求与响应关系；
• 模型实际接收的 conversation；
• tool call、MCP call 与返回 item 的关联；
• terminal session 和 operation；
• compaction 前后的语义关系；
• 多 agent 消息从来源 item 到目标 conversation 的投递；
• 必要时引用独立保存的大 payload。

它遵循一个关键原则：

Observe first, interpret later：先忠实记录观察到的原始事实，再离线归约成语义图。

flowchart LR
    R["Raw events<br/>带 seq 的追加事实"] --> RED["Reducer<br/>严格按 seq 归约"]
    PAY["Payload files<br/>请求、响应、输出"] --> RED
    RED --> G["Semantic graph"]

    G --> TH["threads / turns"]
    G --> IN["inference calls"]
    G --> TO["tool / MCP calls"]
    G --> CO["conversation items"]
    G --> CP["compactions"]
    G --> ED["interaction edges"]

原始事件按单调递增的 seq 排序，而不是只相信 wall clock。原因很简单：并发任务的系统时间可能相同，跨线程写入也可能出现微小乱序；reducer 需要一个稳定顺序才能得到确定结果。

大 payload 通常与事件信封分开保存，并遵循：

先写 payload
→ 再追加引用它的 event
→ 每条 event 及时 flush

这样 event 一旦可见，它引用的 payload 就已经存在。反过来，即使进程在两步之间崩溃，最多留下一个未被引用的 payload，不会留下指向不存在内容的正式事件。

12.10.4 为什么不能让 rollout-trace 取代 rollout

诊断 trace 更详细，看起来似乎更适合作为“终极事实源”，但这样做会破坏几个重要边界：

• 它可能包含敏感 prompt、response、路径、终端输出和工具参数；
• 它是显式开启、本地保存的诊断机制，不保证始终存在；
• 内部事件结构可以比公共恢复格式更快演进；
• 数据量更大，不适合作为每个 Session 的长期负担；
• 诊断证据描述“运行时观察到什么”，不一定等于“恢复时应向模型呈现什么”。

Canonical rollout 追求长期兼容和安全恢复；rollout-trace 追求故障现场的解释力。二者目标不同，不应合并。

---

12.11 Reducer：从原始事件还原语义，而不是还原调用栈

Raw trace 只是一串按序到达的证据。真正有价值的是 reducer 构造出的语义图。

为什么需要 reducer？因为并发和流式协议会让事件以“不方便理解”的顺序出现：

• 某个工具结果先被观察到，来源 item 稍后才完成；
• MCP transport ID 与模型 tool call ID 属于不同命名空间；
• 子 agent 先完成，父 agent 过一会儿才消费消息；
• runtime 为方便前端产生了一条 output，但模型并没有看到它；
• compaction 改变了后续 conversation，却没有改写旧事实。

Reducer 的职责是：

1. 严格按 seq 消费原始事件；
2. 建立 thread、turn、inference、item、tool 和通信实体；
3. 用稳定 ID 连接实体；
4. 暂存尚未找到来源的 pending 关系；
5. 在后续证据到达时补全关联；
6. 区分模型真正看到的 conversation 与 runtime 的便利输出；
7. 保留无法解释的原始证据，而不是静默丢弃。

flowchart TB
    E1["事件：tool result 到达"]
    E2["事件：来源 item 完成"]
    P["Pending association"]
    C["建立 call → result → item 关系"]

    E1 -->|"暂时缺少来源"| P
    E2 --> P
    P --> C

这是一种比在线日志更稳健的设计。在线路径不必为了立即得到完美语义而阻塞主流程；离线 reducer 可以接受“证据迟到”，只要 ID 和顺序足够稳定。

但 reducer 也不能随意猜测。如果找不到唯一关联，应把关系标为 unresolved，并保留原始引用。错误的确定答案，比明确的不确定更危险。

---

12.12 隐私：观察得越深，越要限制谁能看到

Agent telemetry 天然接近敏感数据：

• 用户 prompt 可能包含源代码、商业信息和个人数据；
• 工具参数可能包含路径、查询、收件人和命令；
• 工具输出可能包含密钥、日志、数据库记录；
• reasoning 和 assistant response 可能复述上下文；
• 网络 URL 可能包含 query token；
• rollout-trace 可能重建整个工作过程。

所以可观测性不能只有“开或关”，而需要分层。

12.12.1 Trace-safe metadata

默认 trace 应优先记录结构和规模，而不是正文：

• prompt 长度；
• 输入 item 类型和数量；
• 工具名称与参数长度；
• 输出字节数和行数；
• error class；
• duration；
• policy decision；
• token usage。

例如，记录“用户输入 2,431 字符，包含文本和一张图片”，通常足以分析请求大小和模型延迟，不必上传 prompt 正文。

12.12.2 Logs 比 traces 更可能包含细节

为了本地故障排查，logs 可能记录更详细的工具参数、错误和输出。Log exporter 因此应被视为比 trace exporter 更高风险的出口：

• 默认关闭远程导出；
• 明确区分安全 event 与详细 log；
• 用户 prompt 默认 redact；
• 限制字段长度；
• 对认证 header、WebSocket frame 和已知敏感字段做过滤；
• 配置导出目标时清楚说明数据边界。

“日志只给内部人看”不是隐私策略。只要数据离开本机，就应该按外发数据处理。

12.12.3 Rollout-trace 是本地、显式开启的诊断证据包

为了回答“模型当时究竟看到了什么”，rollout-trace 可能不得不保存：

• 完整 prompt 和 response；
• 工具参数与结果；
• 终端输出；
• 工作区路径；
• 多 agent 消息；
• 原始协议 payload。

这种能力不能默认上传，也不应在用户不知情时长期启用。合理边界是：

• 显式 opt-in；
• 本地存储；
• 明确生命周期和清理方式；
• 分享前由用户检查；
• 诊断失败不影响主任务；
• 不把它误当成普通匿名 telemetry。

12.12.4 Feedback 是一次有 consent 的证据提交

用户主动提交反馈时，可以附带诊断日志或其他材料。但这仍然需要：

• 前端明确展示将上传什么；
• 用户主动确认；
• 过滤高风险、高流量且不必要的原始 frame；
• 对附件大小设上限；
• 区分产品反馈与自动 telemetry。

Consent 不是一个永久开关，而是对这次具体数据提交的授权。

---

12.13 可观测系统自身也会失败

Telemetry 是辅助系统，不能成为 agent 主流程的新单点故障。

合理的失败语义是：

• exporter 初始化失败：记录本地 warning，agent 仍可启动；
• 单次 event 发送失败：吸收错误，不改变 tool 或 turn outcome；
• metrics backend 不可用：丢失指标，但不阻塞 LOOP；
• analytics 队列满：有界丢弃并计数，不能无限占用内存；
• rollout-trace 写入失败：停止或降级诊断记录，不让任务失败；
• shutdown flush 超时：在固定时间预算后退出；
• reducer 遇到未知事件：保留原始证据并继续处理可理解部分。

flowchart LR
    MAIN["Agent 主流程"] --> BUF["有界 telemetry 队列"]
    BUF --> EXP["Exporter"]
    EXP --> BACK["外部 backend"]

    BUF -. "队列满：丢弃 + 计数" .-> DROP["Dropped telemetry"]
    EXP -. "失败：warning + 重试预算" .-> DEG["降级"]
    BACK -. "不可用" .-> DEG
    DEG -. "不得反向阻塞" .-> MAIN

这里有一个看似矛盾的要求：

1. telemetry 不能影响主任务；
2. telemetry 丢失又不能悄无声息。

解决方式不是“永不丢失”，而是有界、可见的失败：

• 队列必须有容量上限；
• 丢弃数量本身是 metric；
• 本地保留简短 warning；
• shutdown 有时间预算；
• 高价值 canonical rollout 与普通 telemetry 使用不同可靠性承诺。

Canonical facts 需要更强的持久化语义；可重建的 metrics 和 traces 可以 best-effort。把所有信号都提升到事务级可靠，会让观察系统反过来绑架主流程。

---

12.14 一次完整调查：为什么这个 turn 又慢又没用上工具

假设用户反馈：

我让 agent 查询线上告警并修复配置。它停了两分钟，最后只给了文字建议，明明已经安装了运维 plugin。

一个有效调查不应该从搜索某句错误日志开始，而应按因果链逐层缩小范围。

第一步：确认业务坐标和用户所见

从前端 Event 找到：

• thread_id 和 turn_id；
• turn 开始、结束和最终 outcome；
• 用户看到了哪些 item；
• 是否出现工具开始、审批或 warning；
• 最终 assistant item 是正常完成还是中断后的残留。

此时确认：前端没有漏渲染工具事件，turn 确实只产生了文字回复。

第二步：用 metrics 判断是否为系统性问题

检查同一时间窗口：

• 模型 TTFT 是否普遍升高；
• MCP server 的 timeout 是否增加；
• tool call 数是否下降；
• plugin activation failure 是否增加；
• sampling retry 是否异常。

结果发现整体 TTFT 正常，只有这个 turn 很慢。问题更像单次上下文、等待或决策链，而不是模型服务整体退化。

第三步：在 trace 中拆解时间

Turn profile 显示：

E2E                 121s
before sampling       1s
sampling             14s
tool blocking       105s
finalize              1s

这已经排除了“模型推理用了两分钟”。继续展开 tool span，发现 105 秒主要在等待 dynamic tool 的前端响应，最后以 timeout 结束。

用户没有看到工具，是因为这次 dynamic tool 只产生了一个等待中的内部调用，前端连接切换后没有成功展示并应答。

第四步：检查能力因果链

运维 plugin 的记录显示：

discovered: yes
enabled: yes
skill visible: yes
MCP server required: yes
MCP activation: failed
reason: authentication unavailable

模型看到了运维 skill 的方法说明，却没有看到实际查询告警的 MCP tool。它先尝试让前端 dynamic tool 获取当前环境，超时后退化为文字建议。

因此，“安装了 plugin”与“本 step 能调用 MCP tool”不是同一件事。第十一章的 discovery、activation、visibility、execution 四道门，在这里通过观测证据完整显现。

第五步：用 rollout-trace 验证模型实际输入

离线 replay 显示：

• 本轮 conversation 中包含 skill 摘要；
• tool snapshot 中没有告警查询工具；
• dynamic tool spec 存在；
• 模型生成了 dynamic tool call；
• timeout result 已回灌；
• 第二次 sampling 基于这个失败结果生成了文字建议。

现在可以给出有证据的结论：

慢：主要慢在等待前端 dynamic tool，不是模型。
没用 MCP：server 因认证失败未激活，所以本 step 不可见。
只给建议：dynamic tool timeout 已回灌，模型在缺少可执行能力时完成了降级回答。

进一步的根因修复也很明确：

1. 修复 MCP 认证和 required server 的启动反馈；
2. 让前端连接切换时显式失败所有悬空 dynamic tool 请求；
3. 单独记录 frontend_tool_wait，不要只归入笼统的 tool blocking；
4. required capability 不可用时应尽早、响亮地告知用户，而不是让模型带着残缺能力继续。

这就是可观测性的价值：不是给现象贴标签，而是把性能、能力、安全和协议证据拼成同一条因果链。

---

12.15 常见失败模式

失败模式	表面现象	根因	更好的做法
只记录 turn 总耗时	知道慢，却不知道慢在哪里	模型、工具、人工和调度混在一起	按 sampling、tool、compaction、human wait 等阶段拆分
把 handler time 当执行时间	错怪 shell 或 MCP 性能	handler 还包含 policy、审批和 sandbox	继续分解 queue、approval、sandbox、process
只靠 trace ID 关联	resume 和多 agent 链路断裂	trace 是在线执行身份，不是长期业务身份	同时记录 thread、turn、item、call 和 lineage
每个函数都建 span	trace 巨大、无法阅读、成本失控	把调用栈当成业务语义	围绕生命周期阶段和外部交互建 span
只记录发生的工具调用	无法解释为什么没调用某工具	缺少 discovery、activation 和 visibility 证据	记录能力从来源到回灌的完整链
把所有错误归为 tool error	无法决定由谁修复、是否重试	混淆模型输出、policy、transport 和业务结果	按失败阶段和责任域分类
把 prompt 放进 metric tag	指标基数爆炸并泄露数据	混淆聚合维度与单次证据	低基数 tag；详细内容只进受控 log/trace
默认上传详细 trace	源码、路径和工具输出外泄	诊断深度没有对应隐私边界	trace-safe 默认；详细 evidence 本地 opt-in
用 rollout-trace 做恢复源	无 trace 时无法恢复，格式难兼容	混淆诊断证据与 canonical fact	rollout 负责恢复，rollout-trace 负责解释
用 wall clock 排 replay	并发事件顺序不稳定	时钟不能提供可靠全序	writer 分配单调 seq，reducer 按 seq 处理
Reducer 猜测缺失关联	报告看似完整，结论却错误	把不确定性隐藏了	pending、unresolved 和原始引用显式保留
Telemetry 队列无界	后端故障拖垮 agent 内存	观察系统没有资源预算	有界队列、丢弃计数、固定 flush 预算
Telemetry 失败中断主任务	监控故障变成用户故障	辅助系统侵入控制流	best-effort 隔离，canonical 持久化另行保证
只看机器时间，不看人等多久	审批型 turn 被误判为性能退化	Human in the loop 没有独立阶段	显式记录 ask、display、answer 和 timeout
把产品 analytics 当 tracing	能看使用量，不能还原因	产品事实流缺少单次因果关系	analytics、telemetry、feedback 分别建模

这些失败背后有一个共同问题：系统记录了结果，却没有记录结果成立所依赖的边界和关系。

---

12.16 更深一层：可观测性是运行时模型的可验证投影

回看前十一章，会发现可观测性并不是最后才加上的横切功能。它是所有设计边界是否真实存在的一次验收。

• 第一章定义了 thread、turn、task、step；可观测系统必须能按这些层级归因。
• 第二章区分 Op、Event、item 与 delta；可观测系统必须知道哪些是权威事实，哪些只是实时表现。
• 第三章区分请求构造、传输、流处理与重试；模型 latency 必须沿这些阶段拆开。
• 第四章强调历史增量、窗口和片段注入；诊断 replay 必须能回答模型实际看到了什么。
• 第五章要求 LOOP 在边界上推进；span 和 timing 也应围绕这些边界建立。
• 第六章拆开 spec、policy、执行与回灌；工具 trace 不能只包住最终进程。
• 第七章定义多 agent lineage 与通信；trace tree 之外必须保留协作树。
• 第八章把安全做成结构化裁决；审计必须记录决策来源和结果。
• 第九章把等待人类视为显式状态；latency 也应把人的时间独立出来。
• 第十章区分 canonical fact 与 runtime state；rollout 和诊断 replay 因而不能混用。
• 第十一章区分 discovery、activation、visibility 与 execution；“为何能力未生效”必须沿这四道门调查。

如果某个模块无法被观察，往往意味着它的边界还没有被真正建模。

例如：

• 无法区分工具排队和执行，说明调度边界不清；
• 无法解释谁拒绝了命令，说明 policy 决策没有统一结构；
• 无法关联子 agent 结果，说明通信缺少稳定身份；
• 无法重建模型输入，说明上下文构造没有留下证据；
• 无法分开恢复和诊断，说明 canonical state 的定义还不够清楚。

因此，可观测性并不是“给代码加日志”，而是把运行时模型投影成一套可验证证据。

12.16.1 从故障定位走向行为解释

传统 observability 通常停在：

哪个组件失败？

Agent harness 还要继续追问：

当时有哪些能力？
模型看到了哪些事实？
哪个主体作了哪项决定？
决定经过哪些安全边界？
外部世界发生了什么？
结果如何影响下一次采样？

这不是要求系统解释模型的全部内部机制，而是要求 harness 对自己掌握的部分负责。模型为什么选择某个词，可能无法完全解释；但某个工具是否可见、某条 policy 是否命中、某个结果是否回灌，必须是可证明的工程事实。

12.16.2 可观测性也是一份成本预算

观察越细，成本越高：

• 更多 span 和 event 增加 CPU 与序列化开销；
• 更长保留期增加存储成本；
• 更详细 payload 增加隐私风险；
• 更高基数增加 metrics 成本；
• 同步写入增加关键路径 latency；
• 完整 replay 增加格式兼容负担。

所以每一类信号都应该回答四个问题：

1. 它用于实时告警、单次定位、历史恢复，还是深度诊断？
2. 它是否需要完整内容，还是元数据已经足够？
3. 它需要保留多久，谁可以读取？
4. 丢失它会影响用户任务，还是只降低诊断能力？

这四个问题决定了信号应该进入 metric、trace、log、rollout 还是本地 rollout-trace。

12.16.3 最好的诊断路径是从聚合到证据

一个高效的调查顺序通常是：

Metrics 发现异常范围
→ Event 确认用户所见
→ Trace 定位阶段与组件
→ Logs 查看局部错误
→ Replay 验证历史语义和模型输入

不必每次都走到最后。系统性延迟可能在 metrics 和 traces 阶段就能定位；只有涉及“为什么做出这个决定”“恢复前后发生了什么”时，才需要更昂贵的 replay 证据。

这是一种 progressive disclosure：不仅上下文和工具按需展开，诊断证据也应按需展开。

---

12.17 小结：可观测性的七条设计原则

1. 观察完整因果链，不只观察最终动作。 从能力来源、step visibility、模型输出、policy、审批、执行到结果回灌，每个边界都应留下可关联的事实。没有发生的调用，也要能从上游状态解释原因。

2. 业务坐标与 trace 坐标同时存在。 trace_id 描述一次在线执行，thread、turn、item、call 和 lineage 描述长期业务关系。异步队列、多 agent 与 resume 需要 link 和稳定 ID，不能硬塞进一棵 span tree。

3. 总耗时必须按责任域拆开。 E2E latency 要区分 sampling、tool、compaction、调度、人工等待和收尾；工具还要继续区分 queue、policy、approval、sandbox 与真实执行。无法分类的时间应该显式暴露，而不是藏进“其他”。

4. Logs、traces、metrics、Event 与 replay 各司其职。 Metrics 找趋势，traces 找路径，logs 看局部细节，Event 重建用户所见，replay 解释历史语义。它们通过稳定 ID 互相连接，但不强行合并成一种万能数据。

5. 恢复 replay 与诊断 replay 分离。 Rollout 保存长期兼容的 canonical facts；UI replay 重建展示；rollout-trace 以本地、显式开启的方式保存更详细证据。Replay 历史永远不等于 re-execute 副作用。

6. 隐私、基数和保留期都是架构边界。 默认 trace 记录长度、类型、耗时和结果类别；正文、路径、参数和输出进入更受控的通道。Metrics 只使用低基数 tag，详细诊断数据必须 opt-in、有上限、可清理。

7. 可观测系统必须 best-effort，但失败要可见。 Exporter、analytics 和诊断 writer 不能阻塞或改变 agent outcome；队列、重试和 shutdown 都有预算。Canonical 持久化获得更强保证，辅助 telemetry 可以降级，但丢弃和缺口必须被记录。

留给读者思考的几个问题：

• 如果一个 turn 同时等待两个并行工具和一次人工审批，tool_blocking 应按 wall time、各任务耗时之和，还是关键路径计算？哪一种最能解释用户感知，哪一种最适合容量规划？
• 模型没有调用某个工具时，应该保存整份 step tool snapshot，还是只保存 catalog revision 与内容摘要？二者在可解释性、存储和隐私上如何权衡？
• Rollout-trace 能重建模型所见，但也可能包含最敏感的数据。怎样设计自动脱敏，才不会在删除秘密的同时破坏 tool call 与结果之间的语义关联？
• 多 agent 的 communication 跨越多个 trace 和进程。应该用 span link、独立 message trace，还是只依赖业务 ID？不同 backend 对这些关系的查询能力是否会反过来限制协议设计？
• Telemetry 必须 best-effort，canonical rollout 又必须可靠。如果二者对同一事件给出不同结果，调查工具应该以谁为准，怎样向用户表达“不完整证据”？
• TTFM 比 TTFT 更接近用户感知，但“meaningful”会随前端而变化：文本、reasoning、plan、工具开始，哪一个才算首个有效反馈？这个定义应该由 harness 统一，还是由前端分别计算？
• 当可观测系统已经能完整还原模型输入、工具行为和结果回灌时，我们能解释的是 harness 的因果链，而不是模型全部内部动机。产品界面应该怎样清楚表达这条能力边界，避免把证据推断包装成确定解释？

至此，我们已经从运行时层级、协议、模型、上下文、LOOP、工具、多 agent、安全、Human in the loop、持久化、扩展一直走到可观测性。十二个模块最终汇合成同一个判断标准：一个生产级 agent harness 不仅要能行动，还要能约束行动、恢复行动，并对自己的行动给出可验证的解释。