1实现原理 · 为什么它能做到
读的是 Codex 三种互不替代的历史面：history.jsonl（prompt ledger，用户提交原文）、state_*.sqlite（清单元数据）、sessions|archived_sessions 下的 rollout-*.jsonl（完整事件流）；每类查询路由到专用脚本，禁止 ad-hoc 重造 join。
daymade-claude-code/read-codex-history/SKILL.md
| `<codex-home>/history.jsonl` | What the user submitted, keyed by Session ID and internal epoch timestamp | Exact recent user-input tables |
SKILL 声明 'Do not substitute one surface for another. A prompt-ledger row proves what was submitted, not what the Agent answered. A state DB path is only a candidate until the rollout's session_meta.id matches.'——这是该 skill 正确性模型的核心。
身份与血统门禁（Identity and lineage gate）：每条行为结论前必须 (1) 核对 prompt-ledger Session ID、(2) 按内部 session_meta.id 而非文件名定位 rollout、(3) 解析后要求 session_meta.id == 请求 ID、(4) fork 边要声明的父 ID + 精确 history_base.end_byte_offset，拒绝缺失/歧义/循环/不匹配的祖先。
daymade-claude-code/read-codex-history/SKILL.md
Locate rollout candidates by their internal `session_meta.id`, not filename alone.
SKILL 明说这是针对两个真实事故的修正：'a prompt-ledger Session whose state DB pointed at another rollout, and a /fork input with no child rollout'。
sqlite 读取被强制只读：_core/codex.py 用 file: URI ?mode=ro 连接并 PRAGMA query_only=ON，schema 不兼容时降级为原生 rollout JSONL 扫描。
daymade-claude-code/read-codex-history/scripts/_core/codex.py
return "file:" + quote(path.resolve().as_posix(), safe="/:@") + "?mode=ro"
同一文件 inspect_codex_database/collect_codex_from_database 均 connection.execute("PRAGMA query_only = ON")——把『读工具不得写库』落到 sqlite 层。
writer-lock 观测为 positive-only：非阻塞读取 .coordination.lock 协调文件，持锁只证明快照时有进程占用 Codex 规范线程锁，不识别进程也不证明活性。
daymade-claude-code/read-codex-history/scripts/list_local_history.py
A held lock proves only that some process owns the advisory lock; it does not
list_local_history.py 251-283 区域先非阻塞取协调锁再看 admitted thread locks，避免与正在写入的 Codex 竞争；输出语义显式声明 'absence is not proof of inactivity'。
输入对账（reconcile_codex_inputs.py）：用既有 ledger + 严格 lineage reader 组合出整会话原始输入计数与引文，保留 occurrence/原文/来源坐标；exit 2 或 complete:false 视为不完整，scope_input_count: null ≠ 0。
daymade-claude-code/read-codex-history/SKILL.md
Use the reconciler to compose the existing ledger and strict lineage readers. It preserves occurrences, original strings, and source coordinates.
SKILL 还约束 'Treat exit 2 or complete: false as an incomplete result'，禁止把未核对记录当成完整总数。
超大 briefing 的上下文纪律：完整简报超模型上下文时先物化一次到私有临时文件并记录 SHA-256+行数，按标题/坐标读有界区间，未读区间一律报为 gap，禁止分片重跑拼出『完整』假象。
daymade-claude-code/read-codex-history/SKILL.md
materialize it once to a private temporary file and record its SHA-256 plus line count before reading
read_codex_session.py --full 输出可能达多 MB；这条是给 agent 的『一条 briefing 可以分多次读，但不能伪造完整性』的读法纪律。
2核心能力
01跨 live/archive rollout 的最近 Codex 会话清单（含 writer-lock 阳性证据、来源标签）
02prompt-ledger 逐字用户输入导出：全局窗口或按 Session 展开、JSON 保真存储串
03整会话原始输入对账（含继承历史计数与引文、hash-bound 排除复核）
04按内部身份定位精确 rollout（秒级，避免全语料扫描）
05单会话时间线重建：fork 血统、父字节边界、compaction、plan、工具调用、end reason
06有界全事件检索（--codex-only 限定 Codex 面，预算超时显式失败不装完整）
3外部依赖
| Kind | Dependency / Endpoint |
|---|---|
| cli | git（工作区状态上下文，read_codex_session 中 subprocess） |
| cli | rg/grep（text.py 可选路径预过滤，与 claude 版共享 core） |
4管控建议与判定依据
建议配套管控措施
面向 Agent
分级或逐次授权，建议在沙箱运行
面向管理者
审批流程、可回滚、全程审计
判定依据（文件路径与关键语句摘要）
- scripts/: 执行本地脚本或命令: python3 运行 5 个自带脚本（纯 stdlib）
审计说明： 。只读本地 Codex 历史（history.jsonl / state_*.sqlite 以 mode=ro + PRAGMA query_only 打开 / rollout JSONL），无网络外发、无凭证读取、无常规文件写入；唯一本地执行是 git 与 rg/grep subprocess 及 agent 按指令物化的私有临时简报文件。数据敏感但设计自防御（身份门禁、显式 gap、不外传约束）。
5第二遍独立确认
- [ok] sqlite 只读强制 — _core/codex.py: sqlite_uri 加 ?mode=ro；inspect/collect 均 PRAGMA query_only=ON。
- [ok] 无任何网络外发 — 全 scripts 目录扫描无 requests/urllib/socket/curl/wget；本 skill 不含 history_index 类下载器。
- [ok] 凭证读取检查 — 全目录无 auth.json/API key/.env/密钥 env 访问；只读 rollout 与 ledger。
- [ok] SKILL 声明的 flag 与脚本存在性 — reconcile --through-record/--omit-first/--omit-last、list_codex_user_inputs --recent/--session-id/--per-session、analyze_sessions search --codex-only、read_codex_session --full 均核对到 argparse。
- [unlocatable] rollout 格式跨版本声明（0.142.2–0.149.0） — codex_rollout_format.md 自述 'Verified against ~2,600 real rollouts'；源码内无法复核该实测声明，未运行 Codex 验证。
- [ok] writer-lock 观测语义 — list_local_history.py 251-283 非阻塞取协调锁 + 输出 positive-only 语义字符串，与 SKILL 描述一致。
6结论
适合： 适合需要『Codex 会话证据』的场景：找回用户原始输入与 Session ID、fork 血统审计、压缩前后对照、上线前行为审计；适合与 continue-codex-work 配对做只读取证→执行接力，以及本地历史隐私敏感、要求零外发的用户。
不适合： 不适合需要继续/恢复 Codex 会话或改动其项目的人（那是 continue-codex-work）；无本地 Codex rollout 的环境无用武之地；需要语义级模糊召回（措辞变了）的场景应找带索引的配套技能——本 skill 只有精确检索，不做混合召回。
Install Agent-Ready
① Verified Mirror 2026-09-09
Option A · Direct DownloadDownload read-codex-history.tar.gz
sha256:
Option B · Copy Guide for Agentc30dd57b4165452f…agent 读 JSON 指南后会自动从本站下载安装，无需更多说明。
② Upstream GitHub
GitHub Repo ↗
Pinned to commit d5c4678cb5.