Codex 会话与 RolloutTrace 存储机制解析

1. 会话持久化架构与存储引擎

在长期会话维护与状态恢复方面，Codex 构建了一套基于 SQLite 结构化数据 + JSON-Lines 增量 Trace 流的双轨存储机制。

┌─────────────────────────────────────────────────────────┐
│                     Thread Storage                      │
│                                                         │
│  ┌──────────────────────┐    ┌───────────────────────┐  │
│  │ SQLite DB (~/.codex) │    │  rollout-trace (JSONL)│  │
│  │  • state_5.sqlite    │    │  • 增量 Event Trace   │  │
│  │  • threads/turns 表  │    │  • Tool / Agent 轨迹  │  │
│  └──────────┬───────────┘    └───────────┬───────────┘  │
└─────────────┼────────────────────────────┼──────────────┘
              │                            │
              ▼                            ▼
      会话检索与线程关联              完整会话重放与状态恢复

数据归档与解析逻辑主要包含：

• codex-thread-store ([codex-rs/thread-store](file:///Users/util6/fork-code/codex/codex-rs/thread-store))：管理 threads 和 turns 数据表，记录会话元数据（标题、模型、环境配置、建立与修改时间）。
• codex-rollout-trace ([codex-rs/rollout-trace](file:///Users/util6/fork-code/codex/codex-rs/rollout-trace))：负责高频追加全量底层推理链路 Trace，记录每个 Turn 内系统提示词、模型回复、工具输入输出及压缩事件。

---

2. 上下文压缩与 Token 溢出防御 (compact.rs)

在长对话处理中，系统可能会遇到大模型 Context Window 越界问题。在 [codex-rs/core/src/compact.rs](file:///Users/util6/fork-code/codex/codex-rs/core/src/compact.rs) 中，Codex 实现了系统化的上下文压缩逻辑：

2.1 压缩策略与触发时机

Codex 区分了三种触发场景：

1. Auto Compaction (自动阈值压缩)：当当前对话历史估算 Token (approx_token_count) 达到模型配置上限的预警阈值时自动触发。
2. Pre-turn Compaction (Turn 前主动压缩)：在用户发起新提交前主动蒸馏压缩过长历史。
3. Mid-turn Compaction (Turn 中硬上限防御)：在工具多次循环批处理阶段，当输出过大时，使用 BeforeLastUserMessage 模式在 Turn 内部实时插入压缩块。

2.2 摘要生成与结构裁剪

• 使用 SUMMARIZATION_PROMPT 引导模型将早期 Turn 历史归纳为简洁结构化摘要，前缀增加 SUMMARY_PREFIX。
• 保留最重要与最新的上下文块（如系统设定、当前环境配置、最近一次用户指令），删除冗余的中间工具大文本输出（如大型文件读取、详细终端日志）。
• 压缩完成后发送 EventMsg::ContextCompacted 消息并写入 Rollout Trace，通知终端更新上下文使用指标。

---

3. 会话恢复与历史追踪

得益于 SQLite 与 Rollout Trace 的解耦架构，Codex 能够实现无损的会话恢复与调试跟踪：

• 快速恢复：应用启动时，客户端只需读取 state_5.sqlite 迅速加载线程列表与基本元数据，无需解析几十兆的完整 Trace 日志。
• 精确追踪：当需要回溯特定历史、分析 Token 消耗或审计工具行为时，系统按照 thread_id 抓取对应 Rollout Trace 逐帧重放，支持精准到毫秒级的运行性能分析。

---

4. 与 OpenCode 及 Claude Code 的落盘对比

对比项	Codex	OpenCode	Claude Code
存储介质	SQLite DB + 增量 JSONL Trace	SQLite DB + Parts/Messages JSON	本地 JSON/Text 文件与日志
压缩机制	多阶段蒸馏 (compact.rs v1/v2)	动态裁减历史 Part	Microcompact / SnipCompact
可追踪性	具备独立的 rollout-trace 机制	依赖 session 消息表	依赖运行日志与标准输出