Codex Speed Doctor

只读优先 不自动清理、删除或改配置。

默认脱敏 默认隐藏真实本地路径和 session 文件名。

先 handoff 归档前先让长对话可继续接上。

备份意识 清理动作放到单独确认过的维护步骤里。

v0.5.0：先预检，再归档

新版本把安全边界写进执行路径：路径、handoff、数据库状态、重复项和目标冲突全部在任何移动发生前完成验证。

路径被严格圈定

只接受 Codex sessions 根目录内的 active JSONL，外部文件无法进入归档计划。

文件与数据库一致

每个 session 都必须在 state_5.sqlite 中仍是 active thread。

Blocker 检查 fail-closed

Desktop、app-server、helper 与 Crashpad 都会阻止维护；检查失败也不会被当成安全。

安全行为可回归验证

新增边界逃逸、未登记 session、blocker 识别和进程检查失败测试。

识别真正的日志燃烧

新版本不会只因为 TRACE 多或日志大就动数据库。它用 TRACE 占比加增长采样判断是不是正在写盘，再建议退出 Codex 后做备份优先轮转。

组合信号

只有 TRACE 达到 70% 且采样期间行数或文件组继续增长，才标记 active log burn。

不粗暴掐写入

默认不创建 SQLite trigger，不把日志库软链到临时目录，避免隐藏诊断证据。

尊重 SQLite 文件组

处理日志时把主库、WAL 和 SHM 作为一组，只在确认后做备份优先轮转。

给谁用，解决什么

可以把它理解成 Codex 的本地体检报告。它不诊断患者，也不读取医学资料；它只检查你的 Codex 本地状态，帮你判断为什么工具变慢，以及下一步怎样处理更安全。

医疗与科研人员

当 Codex 用来写综述、做数据分析、整理课程或长期项目时，大会话很有价值。工具帮你先保留交接说明，再把不常用的大文件移出启动热路径。

刚开始用 Codex 的小白

不用先理解数据库、日志或插件缓存。报告会把问题拆成 sessions、logs、plugins、skills、cache 和进程，并给出可读建议。

工具维护者

适合在清理前做一次只读盘点，确认是大 session、日志膨胀、Skill warning，还是 app-server 进程仍在阻塞。

重视安全边界的人

默认不删除、不归档、不改配置、不读取凭证。阈值只提醒你该复查，不代表自动清理。

用普通话说，它在查什么

如果 Codex 像一间工作室，Speed Doctor 会先看桌面上是不是摊着太多大项目，日志本是不是太厚，工具箱有没有坏工具，而不是直接把东西扔掉。

打开慢

检查是否有超过 50 MB 的 active session 还留在启动路径里。

日志变大

64 MB 开始提醒观察，100 MB 建议关闭 Codex 后备份轮转。

插件或 Skill 报 warning

先定位 warning 来源，再决定是否移动某个插件或 Skill。

一条命令先体检

先在本地运行报告。第一次输出应该解释问题形状，再决定是否归档、恢复、移动插件或重建缓存。

git clone https://github.com/2023Anita/codex-speed-doctor.git
cd codex-speed-doctor
PYTHONPATH=src python3 -m codex_speed_doctor.cli

# JSON output
PYTHONPATH=src python3 -m codex_speed_doctor.cli --json

# Static snapshot without the 5-second growth sample
PYTHONPATH=src python3 -m codex_speed_doctor.cli --log-growth-seconds 0

本地状态地图

Codex 启动变慢可能来自多个本地因素。工具把这些检查拆开，避免把日志问题误判成 session 问题，也避免把插件 warning 误判成模型问题。

Sessions

标记 50 MB 以上、需要先写 handoff 再归档的大 active session。

Logs

汇总日志大小和 warning target；64 MB 开始观察，100 MB 建议备份后轮转。

Plugins and Skills

统计本地加载面，并突出插件与 Skill 的 warning 模式。

Doraemon guiding a map of Codex local-state modules — 哆啦A梦带着检查工具走过五个区域：sessions、logs、plugins、skills 与 model cache；真正的诊断来自这些证据的组合。

归档前先 handoff

更安全的流程是：诊断、给重要线程写继续说明、只归档不活跃的大 session、建立索引，并保留恢复路径。

1 诊断

测量 active sessions、logs、plugins、skills、cache 和进程。

2 Handoff

写下目标、当前状态、关键文件、命令和下一步。

3 归档

只移动不再需要留在热路径里的 session。

4 索引

留下可检索记录，之后能按主题找回旧工作。

5 恢复

需要找回 session 时使用备份和恢复脚本。

An engineer and Doraemon preserving a handoff before archive — 红线代表上下文连续性：先理解大会话，再写 handoff，最后进入带备份和恢复路径的归档。

安全边界

Codex Speed Doctor 是诊断工具，不是清理器。它先回答“可能慢在哪里”，再让维护动作进入明确确认流程。

不自动清理

CLI 不删除 sessions、不轮转日志、不移动 worktree。

不读取凭证文件

报告不会读取或输出 auth.json 内容。

详细信息需主动开启

真实路径和 session 文件名需要显式传入 --details。

清理保持可审阅

归档和恢复应放在 backup-first 的维护流程里。

Doraemon guarding the read-only diagnostic boundary — 中央区域保持只读；凭证继续密封，备份独立保存，只有 blocker 清空并确认后，维护动作才会进入。