Agent 学习记录 1.5：Codex 会话记录分析

仅是不成熟的思考和理解，对话也比较单薄，后续有时间可能会想看更复杂的会话数据或cli的会话数据（可能会和desktop版的不一样？），也可能分析和cc的区别，也可能看源码，但是现在先这样吧hh，想了解的东西太多了，感觉时间不太够

认真读了会话数据，并在和gpt5.5的多次交互中，逐渐梳理清楚，有了大概的认知，我目前的理解是可以把会话数据拆成两条线来理解：

模型上下文 / 发送返回线

主要看 response_item。它回答：模型实际收到了什么、输出了什么、请求了什么工具、工具结果如何回到模型上下文。

Runtime / 事件状态线

主要看 session_meta、turn_context、event_msg、compacted。它回答：runtime 如何启动、调度、统计、压缩和恢复。

下面我将送从头开始，列出一次查询天气对话+压缩+再发一个你好的会话数据流并简单分析

第一轮：用户让 Codex 查询北京天气

会话启动：写入 session_meta 会话运行现场快照 Runtime 线

{
  "timestamp": "2026-05-28T08:37:05.683Z",
  "type": "session_meta",
  "payload": {
    "id": "019e6dba-b341-7701-96be-43a4435d0357",
    "cwd": "C:\\Users\\15893\\Documents\\test",
    "originator": "Codex Desktop",
    "cli_version": "0.133.0",
    "source": "vscode",
    "thread_source": "user",
    "model_provider": "custom",
    "base_instructions": "Codex 基础行为指令...",
    "dynamic_tools": "本轮可用工具 schema 列表...",
    "git": "当前 git 状态..."
  }
}

会话启动消息

记录这次 session 的 ID、工作目录、来源、版本、工具、指令、Git 信息。
其中base_instructions里面是很长的一段prompt，大体意思是规定了你是 Codex，如何处理代码任务，如何调用工具，如何做前端，如何编辑文件，如何回复用户，格式要求，最终回复要求，具体内容我这里就不放了
值得注意的是，下面的所有response_item的role，都没有system的部分，我推测可能system的部分是内置在Responses API 服务器里面的，也可能这里的base_instructions就会被放进上下文的system/developer部分，有待进一步了解

一轮任务开始：event_msg / task_started 建立 turn 生命周期边界 Runtime 线

{
  "timestamp": "2026-05-28T08:37:05.693Z",
  "type": "event_msg",
  "payload": {
    "type": "task_started",
    "turn_id": "019e6dba-e4db-7022-96ef-2b2f5c4863a5",
    "started_at": 1779957425,
    "model_context_window": 258400,
    "collaboration_mode_kind": "default"
  }
}

设计含义

这表示 runtime 开始处理一轮用户输入。
对于turn这个概念，OpenAI 对 Codex 的抽象是：Thread -> Turn -> Item
- Thread：持久会话，可创建、恢复、fork、归档。
- Turn：用户输入触发的一轮 agent 工作。
- Item：turn 里的原子输入/输出，例如 user message、agent message、tool execution、approval request、diff。
turn_id 标记了这轮turn的id给后面的完成、中断、耗时统计都会使用同一个id标识同一轮turn。
model_context_window 记录当前模型上下文窗口，便于判断上下文压力。

注入 developer 指令权限、工具、skills、plugins 等运行配置模型上下文线

{
  "timestamp": "2026-05-28T08:37:05.740Z",
  "type": "response_item",
  "payload": {
    "type": "message",
    "role": "developer",
    "content": [
      { "type": "input_text", "text": "<permissions instructions>..." },
      { "type": "input_text", "text": "<app-context>..." },
      { "type": "input_text", "text": "<collaboration_mode>..." },
      { "type": "input_text", "text": "<skills_instructions>..." },
      { "type": "input_text", "text": "<plugins_instructions>..." }
    ]
  }
}

developer prompt

developer的prompt：包括权限、协作模式、skills、plugins、Codex Desktop 能力说明。

注入 AGENTS.md 与环境上下文项目规则和当前环境模型上下文线

{
  "timestamp": "2026-05-28T08:37:05.748Z",
  "type": "response_item",
  "payload": {
    "type": "message",
    "role": "user",
    "content": [
      {
        "type": "input_text",
        "text": "# AGENTS.md instructions for C:\\Users\\15893\\Documents\\test..."
      },
      {
        "type": "input_text",
        "text": "<environment_context>cwd、shell、日期、时区..."
      }
    ]
  }
}

项目级规则和一些环境信息。

turn_context：本轮上下文包边界不是完整 prompt Runtime 线

{
  "timestamp": "2026-05-28T08:37:05.750Z",
  "type": "turn_context",
  "payload": {}
}

turn_context 是这一轮上下文包到这里组装好了的边界标记，runtime里面turn的标记。

用户原始输入：给模型看的版本 response_item / message / role=user 模型上下文线

{
  "timestamp": "2026-05-28T08:37:05.753Z",
  "type": "response_item",
  "payload": {
    "type": "message",
    "role": "user",
    "content": [
      {
        "type": "input_text",
        "text": "帮我搜索今天的北京天气\n"
      }
    ]
  }
}

第一次用户消息

用户提问的消息

用户原始输入：runtime 事件版本 event_msg / user_message Runtime 线

{
  "timestamp": "2026-05-28T08:37:05.753Z",
  "type": "event_msg",
  "payload": {
    "type": "user_message",
    "message": "帮我搜索今天的北京天气\n",
    "images": [],
    "local_images": [],
    "text_elements": []
  }
}

为什么同一句话出现两次

这一份属于 runtime 事件流。
它记录“用户消息事件发生了”，同时保留图片、本地图片、文本元素等输入形态。
所以它和上一条内容相似，但职责不同。

空 reasoning：runtime 事件版本 event_msg / agent_reasoning Runtime 线

{
  "timestamp": "2026-05-28T08:37:22.415Z",
  "type": "event_msg",
  "payload": {
    "type": "agent_reasoning",
    "text": ""
  }
}

这一条怎么看

它属于 runtime 事件线，表示 agent reasoning 相关事件出现了。
这里的 text 是空字符串，所以没有给用户展示任何推理摘要。
这类事件可以理解为 runtime 对“模型正在思考 / 推理阶段”的事件化记录。

空 reasoning：模型 item 版本 response_item / reasoning 模型上下文线

{
  "timestamp": "2026-05-28T08:37:22.421Z",
  "type": "response_item",
  "payload": {
    "type": "reasoning",
    "summary": [
      { "type": "summary_text", "text": "" }
    ],
    "content": null,
    "encrypted_content": ""
  }
}

和上一条的区别

这条是模型上下文线里的 reasoning item。
summary 里有一个空的 summary_text，说明没有公开推理摘要。
content: null、encrypted_content: "" 表示这里也没有明文或加密推理内容。

模型请求调用工具：function_call 模型输出工具调用意图模型上下文线

{
  "timestamp": "2026-05-28T08:37:24.114Z",
  "type": "response_item",
  "payload": {
    "type": "function_call",
    "name": "shell_command",
    "arguments": "{ command: Get-Content 某个 SKILL.md, workdir: ... }",
    "call_id": "call_s8ed7YKvykhsf6GPqAhKMRqQ"
  }
}

模型并没有直接执行命令

模型输出的是“我要调用 shell_command”的结构化意图。
真正执行命令的是 Codex runtime。
call_id 用来把请求和结果配对。

工具执行结果回填：function_call_output runtime 执行后把结果放回模型上下文模型上下文线

{
  "timestamp": "2026-05-28T08:37:24.580Z",
  "type": "response_item",
  "payload": {
    "type": "function_call_output",
    "call_id": "call_s8ed7YKvykhsf6GPqAhKMRqQ",
    "output": "Exit code: 0\nWall time: 0.5 seconds\nOutput:\nSKILL.md 内容很长..."
  }
}

为什么输出也进入 response_item

模型下一步要基于工具结果继续工作，所以结果必须回到模型上下文。
这条不是模型生成的自然语言回答，而是 runtime 给模型的工具结果。

加密 reasoning：模型保留的推理状态 response_item / reasoning / encrypted_content 模型上下文线

{
  "timestamp": "2026-05-28T08:37:48.809Z",
  "type": "response_item",
  "payload": {
    "type": "reasoning",
    "summary": [],
    "content": null,
    "encrypted_content": "gAAAAABqF_7dG49MUwA5...很长的加密内容..."
  }
}

reasoning加密了

这里不给用户看的原始reasoning，而是加密后的 reasoning 状态。
关于这个reasoning加密，官方文档说的是reasoning models 会产生 reasoning tokens，模型用它们来思考、规划、比较方案、处理工具调用等。但这些 reasoning tokens “not visible via the API”。官方文档又说：使用 reasoning model 做 function calling 时，建议把前一次响应里的 reasoning items 一起传回下一次请求。这样模型能继续之前的推理过程，结果更好，也更省 token（命中缓存而且不用重新思考）。
既然有reasoning又要用又不想给用户看（怀疑是不想被蒸馏），那就只能加密了

Web 搜索结束：runtime 事件版本 event_msg / web_search_end Runtime 线

{
  "timestamp": "2026-05-28T08:37:53.517Z",
  "type": "event_msg",
  "payload": {
    "type": "web_search_end",
    "call_id": "ws_0ed3b16bb031c342016a17feddd3c881919442335097dbc7ce",
    "query": "weather: Beijing, China",
    "action": {
      "type": "search",
      "queries": ["weather: Beijing, China"]
    }
  }
}

这条记录搜索动作完成

它属于 runtime 事件线，说明一次 web search 已经结束。
call_id 用来标识这次搜索动作。
query 和 action.queries 记录了实际搜索的查询词。

Web 搜索调用：模型 item 版本 response_item / web_search_call 模型上下文线

{
  "timestamp": "2026-05-28T08:37:53.517Z",
  "type": "response_item",
  "payload": {
    "type": "web_search_call",
    "status": "completed",
    "action": {
      "type": "search",
      "queries": ["weather: Beijing, China"]
    }
  }
}

为什么搜索也有 response_item

这条属于模型上下文线，记录模型侧看到的搜索调用 item。
status: completed 表示这个搜索调用已经完成。
它和上一条 web_search_end 描述的是同一件事，但一个是 runtime 事件，一个是模型 item。

最终回答：runtime 事件版本 event_msg / agent_message Runtime 线

{
  "timestamp": "2026-05-28T08:37:55.609Z",
  "type": "event_msg",
  "payload": {
    "type": "agent_message",
    "message": "北京今天（2026年5月28日）天气：晴，目前约 29°C...",
    "phase": "final_answer",
    "memory_citation": null
  }
}

这一条表示什么

runtime 对外发布了一条助手消息事件。
phase: final_answer 表示这是最终回答阶段。
它适合被日志、状态系统、界面等上层消费者读取。

最终回答：模型输出版本 response_item / assistant message 模型上下文线

{
  "timestamp": "2026-05-28T08:37:55.615Z",
  "type": "response_item",
  "payload": {
    "type": "message",
    "role": "assistant",
    "content": [
      {
        "type": "output_text",
        "text": "北京今天（2026年5月28日）天气：晴，目前约 29°C..."
      }
    ],
    "phase": "final_answer"
  }
}

和上一条的差异

数据模型上下文线，也就是会进入上下文，role是assitant，代表是llm输出的内容。
上一条是 runtime 事件，这一条是模型输出 item。

任务完成：task_complete 和 task_started 配对 Runtime 线

{
  "timestamp": "2026-05-28T08:37:55.822Z",
  "type": "event_msg",
  "payload": {
    "type": "task_complete",
    "turn_id": "019e6dba-e4db-7022-96ef-2b2f5c4863a5",
    "last_agent_message": "北京今天（2026年5月28日）天气...",
    "completed_at": 1779957475,
    "duration_ms": 50449,
    "time_to_first_token_ms": 15112
  }
}

它和 task_started 配对

标记这一轮 turn 完成。
记录最后一条助手消息，方便恢复和快速展示。
记录总耗时和首 token 延迟，用于性能分析。

压缩：上下文如何被整理成摘要-完成上一个对话之后我手动触发了一次压缩

下一轮任务开始：新的 task_started 压缩前后仍然是新的 turn Runtime 线

{
  "timestamp": "2026-05-28T08:50:14.269Z",
  "type": "event_msg",
  "payload": {
    "type": "task_started",
    "turn_id": "019e6dc6-ee7b-7523-b672-1a9f099a65b6",
    "started_at": 1779958214,
    "model_context_window": 258400,
    "collaboration_mode_kind": "default"
  }
}

这里说明什么

同一个 session 里可以有多个 turn。
这条表示 runtime 又开始处理一轮任务。
后面的 token 统计和 compacted 都发生在这轮上下文维护过程中。

第一次 token_count：记录累计和本轮 token 上下文压力和用量统计 Runtime 线

{
  "timestamp": "2026-05-28T08:50:57.012Z",
  "type": "event_msg",
  "payload": {
    "type": "token_count",
    "info": {
      "total_token_usage": {
        "input_tokens": 30056,
        "cached_input_tokens": 11648,
        "output_tokens": 367,
        "reasoning_output_tokens": 143,
        "total_tokens": 30423
      },
      "last_token_usage": {
        "input_tokens": 18546,
        "cached_input_tokens": 11648,
        "output_tokens": 188,
        "reasoning_output_tokens": 79,
        "total_tokens": 18734
      },
      "model_context_window": 258400
    },
    "rate_limits": "当前速率限制状态..."
  }
}

压缩前的第一次token count

total_token_usage 是当前会话累计到这里的用量。
last_token_usage 是最近一次模型请求的用量。
cached_input_tokens 可以帮助理解哪些输入命中了缓存。
这些数据能辅助 runtime 判断是否需要压缩上下文。

第二次 token_count：压缩前的进一步统计上下文继续增长 Runtime 线

{
  "timestamp": "2026-05-28T08:51:07.910Z",
  "type": "event_msg",
  "payload": {
    "type": "token_count",
    "info": {
      "total_token_usage": {
        "input_tokens": 41472,
        "cached_input_tokens": 16000,
        "output_tokens": 917,
        "reasoning_output_tokens": 290,
        "total_tokens": 42389
      },
      "last_token_usage": {
        "input_tokens": 11416,
        "cached_input_tokens": 4352,
        "output_tokens": 550,
        "reasoning_output_tokens": 147,
        "total_tokens": 11966
      },
      "model_context_window": 258400
    },
    "rate_limits": "当前速率限制状态..."
  }
}

为啥连着又有一次token count

这里可以看到累计 token 从三万多增长到四万多，那么新增的token是什么呢，我仔细分析了一下
last_token_usage也变了，而30056+11416=41472，同时5ms之后就写入了compacted，所有新增的一条消息应该是压缩请求，这里则进行了压缩完成前的一次统计，

compacted：把旧历史替换成交接摘要影响后续模型上下文，不删除本地日志 Runtime 线

{
  "timestamp": "2026-05-28T08:51:07.915Z",
  "type": "compacted",
  "payload": {
    "message": "Another language model started... 交接摘要：天气查询已完成...",
    "replacement_history": [
      { "type": "message", "role": "user", "content": "帮我搜索今天的北京天气" },
      { "type": "message", "role": "user", "content": "交接摘要文本..." }
    ]
  }
}

压缩是如何实现的

首先本地日志不会因为压缩而删除前面的原始事件。
payload.message = 压缩后生成的摘要正文
replacement_history = 被这次摘要替换掉的历史片段记录 / 替换关系记录

所以压缩前后的过程应该是这样的

压缩前：

[真实用户消息]
[developer / AGENTS / environment]
[reasoning]
[tool call]
[tool output]
[web search]
[assistant answer]
[各种历史 item]

        ↓ compacted

压缩后：

[developer / AGENTS / environment 重新注入]
[一条交接摘要 message]
[新用户消息]

压缩后的下一轮上下文重新组装

压缩后重新注入 developer 指令当前运行配置每轮都要重新提供模型上下文线

{
  "timestamp": "2026-05-28T08:51:52.862Z",
  "type": "response_item",
  "payload": {
    "type": "message",
    "role": "developer",
    "content": [
      { "type": "input_text", "text": "<permissions instructions>..." },
      { "type": "input_text", "text": "<app-context>..." },
      { "type": "input_text", "text": "<collaboration_mode>..." },
      { "type": "input_text", "text": "<skills_instructions>..." },
      { "type": "input_text", "text": "<plugins_instructions>..." }
    ]
  }
}

为什么压缩完又出现

压缩的是旧对话历史，不是当前运行配置。
权限、工具、skills、plugins 这些又被重新注入了上下文。
为什么不直接用之前的，可能考量是压缩后就要这么设计？清空原来的上下文，将摘要和不变的一些信息重新拼接上下文？

压缩后重新注入 AGENTS.md 和环境上下文项目规则和环境也会重新进入上下文模型上下文线

{
  "timestamp": "2026-05-28T08:51:52.862Z",
  "type": "response_item",
  "payload": {
    "type": "message",
    "role": "user",
    "content": [
      {
        "type": "input_text",
        "text": "# AGENTS.md instructions for C:\\Users\\15893\\Documents\\test..."
      },
      {
        "type": "input_text",
        "text": "<environment_context>cwd、shell、current_date、timezone..."
      }
    ]
  }
}

为什么压缩后又有 AGENTS.md

同上，又重新注入，组装上下文了

第二轮：用户发“你好”

第二轮不用像第一轮那样每条都拆开，因为很多机制前面已经讲过了。这里更适合按阶段合并看：压缩后的上下文包、用户消息双线、运行现场重现、最后响应与收尾。

压缩后新请求的上下文包 developer、AGENTS.md、environment_context 重新出现模型上下文线

{
  "timestamp": "2026-05-28T08:51:52.862Z",
  "type": "response_item",
  "payload": {
    "type": "message",
    "role": "developer",
    "content": [
      { "type": "input_text", "text": "<permissions instructions>..." },
      { "type": "input_text", "text": "<app-context>..." },
      { "type": "input_text", "text": "<skills_instructions>..." },
      { "type": "input_text", "text": "<plugins_instructions>..." }
    ]
  }
}

{
  "timestamp": "2026-05-28T08:51:52.862Z",
  "type": "response_item",
  "payload": {
    "type": "message",
    "role": "user",
    "content": [
      { "type": "input_text", "text": "# AGENTS.md instructions..." },
      { "type": "input_text", "text": "<environment_context>..." }
    ]
  }
}

这里不用重复细讲

第一轮已经讲过 developer 指令和 AGENTS.md 的作用。
有趣的是这里又重新注入了，或许每次对话都会重新注入？还是压缩完才这样，还没太搞明白

用户“你好”：模型上下文和 runtime 事件合并看同一句消息仍然写两条双线

{
  "timestamp": "2026-05-28T08:51:52.868Z",
  "type": "response_item",
  "payload": {
    "type": "message",
    "role": "user",
    "content": [
      { "type": "input_text", "text": "你好\n" }
    ]
  }
}

{
  "timestamp": "2026-05-28T08:51:52.868Z",
  "type": "event_msg",
  "payload": {
    "type": "user_message",
    "message": "你好\n",
    "images": [],
    "local_images": [],
    "text_elements": []
  }
}

第一条是模型上下文线：真正给模型看的用户输入。
第二条是 Runtime 事件线：记录用户消息事件和输入形态。
这个模式第一轮已经详细讲过，所以第二轮只需要确认它仍然成立。

session_meta 再次出现：运行现场重现不是新聊天内容，而是 runtime 快照 Runtime 线

{
  "timestamp": "2026-05-28T08:51:52.966Z",
  "type": "session_meta",
  "payload": {
    "id": "019e6dba-b341-7701-96be-43a4435d0357",
    "timestamp": "2026-05-28T08:36:57.687Z",
    "cwd": "C:\\Users\\xxx\\Documents\\test",
    "originator": "Codex Desktop",
    "base_instructions": "完整 Codex 基础指令...",
    "dynamic_tools": [
      { "namespace": "codex_app", "name": "automation_update", "inputSchema": "..." },
      { "namespace": "codex_app", "name": "read_thread_terminal", "inputSchema": "..." },
      { "namespace": "codex_app", "name": "load_workspace_dependencies", "inputSchema": "..." }
    ]
  }
}

这一条值得单独看一下

session_meta 这个又出现了一次，其实没有太清楚为什么这样设计，感觉一个session有一个session_meta不就行了

第二轮响应和收尾：合并看即可 assistant message、token_count、task_complete 双线

{
  "type": "response_item",
  "payload": {
    "type": "message",
    "role": "assistant",
    "content": [
      { "type": "output_text", "text": "你好！..." }
    ],
    "phase": "final_answer"
  }
}

{
  "type": "event_msg",
  "payload": {
    "type": "agent_message",
    "message": "你好！...",
    "phase": "final_answer"
  }
}

{
  "type": "event_msg",
  "payload": {
    "type": "token_count",
    "info": "本轮和累计 token 用量..."
  }
}

{
  "type": "event_msg",
  "payload": {
    "type": "task_complete",
    "turn_id": "第二轮 turn_id...",
    "last_agent_message": "你好！...",
    "duration_ms": "本轮耗时..."
  }
}

这些就和之前一样了

assistant 回复仍然会有模型输出版本和 runtime 事件版本。
token_count 仍然记录本轮和累计用量。
task_complete 仍然和本轮 task_started 配对，标记 turn 结束。
这些机制第一轮已经讲过，第二轮只需要看到它们按同样模式继续运转。

最终整个会话的模型

用户输入
  ↓
Codex runtime 创建 turn_id
  ↓
event_msg: task_started
  ↓
组装 developer 指令、AGENTS.md、环境、历史摘要
  ↓
turn_context 标记上下文包边界
  ↓
response_item: user message      event_msg: user_message
  ↓
模型 reasoning / function_call
  ↓
runtime 执行工具
  ↓
response_item: function_call_output
  ↓
response_item: assistant message event_msg: agent_message
  ↓
event_msg: token_count / task_complete
  ↓
必要时 compacted，把旧历史替换成交接摘要

目前的结论：

.jsonl 不是单纯聊天记录，而是一份完整的runtime trace。
response_item 主要负责模型上下文线：模型收到什么、输出什么、调用什么工具。
event_msg 主要负责 Runtime 事件线：turn 开始、用户事件、工具进度、token 统计、任务完成。

模型上下文 / 发送返回线

Runtime / 事件状态线

第一轮：用户让 Codex 查询北京天气#

会话启动消息#

设计含义#

developer prompt#

第一次用户消息#

为什么同一句话出现两次#

这一条怎么看#

和上一条的区别#

模型并没有直接执行命令#

为什么输出也进入 response_item#

reasoning加密了#

这条记录搜索动作完成#

为什么搜索也有 response_item#

这一条表示什么#

和上一条的差异#

它和 task_started 配对#

压缩：上下文如何被整理成摘要-完成上一个对话之后我手动触发了一次压缩#

这里说明什么#

压缩前的第一次token count#

为啥连着又有一次token count#

压缩是如何实现的#

压缩后的下一轮上下文重新组装#

为什么压缩完又出现#

为什么压缩后又有 AGENTS.md#

第二轮：用户发“你好”#

这里不用重复细讲#

这一条值得单独看一下#

这些就和之前一样了#

最终整个会话的模型#