keep-codex-fast

保持 Codex 快速运行

使用此技能检查并安全维护本地 Codex 状态。目标是在不让用户感到意外或丢失连续性的前提下，减少本地负担。

首要原则：应用更改前先保持连续性。对于用户可能会继续处理的活跃仓库聊天，建议先创建一份全面的交接文档和重新激活提示词，再进行归档。

安全规则

• 先检查，再修改。
• 首次运行必须仅生成报告。报告模式不得写入文件、创建备份、移动文件夹或更改本地 Codex 状态。
• 应用更改前先备份。用户希望备份但不移动或更改本地状态时，使用 --backup-only。
• 归档或移动文件，而不是删除文件。不得永久删除用户的聊天记录、日志、工作树、记忆、技能、插件或自动化配置。
• 移动会话或工作树时，编写清单和恢复脚本。
• 如果 Codex 正在运行，默认仅生成报告。只有在 Codex 已关闭，或用户明确同意等待 Codex 退出后，才能应用更改。
• 除非用户明确要求，否则不得修改或复制凭据文件。触碰本地状态前，先备份记忆、技能、插件和自动化配置文件。
• 将备份文件夹视为私密的本地产物，因为其中可能包含 Codex 元数据。除非用户已先行检查，否则不要要求用户发布或分享备份。
• 除非用户要求查看详情或运行 --details，否则不要输出原始线程 ID、聊天标题、本地路径或进程路径。
• 应用更改前，告知用户为可能继续处理的活跃仓库聊天创建交接文档。
• 归档用户可能希望继续处理的任何活跃仓库聊天前，建议创建一份全面的交接文档和重新激活提示词。
• 只有在用户确认交接文档已存在，或确认不需要交接文档后，才归档较早但仍重要的活跃仓库聊天。

心智模型

共有三种模式：

• 检查：仅生成报告，不写入任何内容。
• 维护：使用常规的 --apply；备份并归档旧会话、移动过时的工作树、轮换日志、清理无效配置并规范化路径。不会精简线程标题或预览元数据。
• 可选修复：--apply --repair-thread-metadata-bloat；备份后缩短过大的 SQLite 显示标题和预览元数据。滚动记录的对话内容保持不变。

默认工作流

1. 让用户放心：首次运行只读且注重隐私；之后应用更改时，此工具会归档而不是删除。
2. 以报告模式运行随附脚本：

python scripts/keep_codex_fast.py

3. 总结：
   • 活跃会话大小
   • 已归档会话大小
   • 最大的活跃会话
   • 线程元数据膨胀：活跃标题／预览的字符总数、标题／预览的最大长度，以及超限数量
   • 陈旧工作树候选项
   • 日志大小
   • 异常 Windows \\?\ 路径数量
   • 配置中的项目清理候选项
   • 占用资源最多的 Node／开发进程
4. 应用更改前，建议用户为所有可能继续使用的活跃仓库聊天创建交接文档。说明交接文档能让他们归档占用较大的聊天，并在新线程中根据文档继续工作。
5. 找出可能仍有用的大型／旧版活跃仓库聊天。对于用户想要继续的每个聊天，创建或更新：
   • 仓库本地的交接文档
   • 可在新聊天中启动并延续上下文的重新激活提示词
6. 如果用户想应用建议的维护操作，请让他们关闭 Codex 或使用 --wait-for-codex-exit，然后运行：

python scripts/keep_codex_fast.py --apply --archive-older-than-days 10 --worktree-older-than-days 7

7. 应用后验证：

python scripts/keep_codex_fast.py

8. 询问用户是否需要定期收到仅报告模式的提醒：
   • 如果经常在多个仓库／终端中使用 Codex，则每周一次
   • 如果使用频率较低，则每两周一次
   • 如果用户更喜欢手动维护，则不设置提醒

如果用户想要自动化，且 Codex 应用的自动化工具可用，则仅创建定期报告／提醒自动化。不要建议定期执行会修改数据的维护操作，因为自动化无法知道用户是否已创建交接文档。提示词必须说明：不要传入 --apply，不要归档／移动／清理／轮换／规范化／删除／修改本地状态，并提醒用户只有在确认交接文档已创建且 Codex 已关闭后，才能手动应用更改。

应用操作的内容

• 将重要元数据备份到 ~/Documents/Codex/codex-backups/keep-codex-fast-*。
• 将旧的非固定会话归档到 ~/.codex/archived_sessions/。
• 规范化本地 SQLite 文本字段中的 Windows 扩展路径，例如 \\?\C:\...。
• 从 config.toml 中清理缺失／临时项目块，并以无 BOM 的 UTF-8 格式写入。
• 将陈旧工作树移至 ~/.codex/archived_worktrees/。
• 仅当超过阈值时，才将 logs_2.sqlite* 轮换至 ~/.codex/archived_logs/。
• 报告占用资源较多的 Node 进程，但不终止它们。
• 报告异常膨胀的活跃线程标题和 first_user_message 预览。仅当用户明确选择启用 --repair-thread-metadata-bloat 时才会修复这些内容。

报告模式不会执行任何上述修改，只会打印数量和匿名候选项。诊断时需要原始 ID、标题或路径，请使用 --details。

建议策略

• 活跃聊天中只保留最近 7-10 天的非固定聊天。
• 使用交接文档记录重要的旧线程。
• 根据交接文档启动新线程，而不是反复恢复超大型聊天。
• 如果每天都在多个仓库／终端中使用 Codex，则每周执行维护。
• 首次成功应用后，可提供每周或每两周一次的仅报告模式提醒；不要默认用户需要定期维护。
• 如有疑问，请保留聊天为活跃状态，或询问用户。没有交接文档时，绝不要归档已固定、当前正在使用或明确标记为仍需要的聊天。
• 将标题／预览修复视为仅修复元数据。完整的发布过程记录仍保留在会话 JSONL 中；受限的 SQLite 字段用于列表／导航显示。

线程元数据膨胀

如果 threads.title 或 threads.first_user_message 存储的是完整提示词／历史记录大小的内容，而不是显示标题或预览，Codex Desktop 可能会变慢。此问题会影响线程列表／导航流程，发生在 UI 渲染任何内容之前。

脚本会报告活跃线程数量、标题／预览字符总数、标题／预览最大长度、超出配置标题限制的活跃标题，以及超出配置预览限制和 10k 字符的活跃预览。

常规应用模式会报告元数据膨胀候选项，但不会进行修复。如果用户明确选择启用，则在备份完成后且仅在 Codex 未运行时，运行：

python scripts/keep_codex_fast.py --apply --repair-thread-metadata-bloat

这会限制活跃的 threads.title 和 threads.first_user_message 值。标题默认限制为 120 个字符，预览默认限制为 240 个字符。它还会将修复后的标题追加到 session_index.jsonl，与当前上游的名称更新存储方式一致，因此协调／名称查找不会立即优先采用旧的完整消息回退值。

定向修复清单会保存旧的完整标题／预览值，以便撤销更改。请将 thread-metadata-repairs.jsonl、restore-thread-metadata.py 和整个备份文件夹视为本地私有文件。

这是针对元数据膨胀的本地维护变通方案。它无法解决应用渲染器对超大型 rollout 历史记录的加载问题；这需要上游实现分阶段／分页式线程加载。

交接文档 + 重新激活提示词

对于重要的活跃仓库聊天，在归档前创建交接文档。优先选择仓库本地路径，例如 docs/codex-handoffs/YYYY-MM-DD-topic.md，或用户认可的文档存放位置。

如果用户需要具体模板，请使用 references/handoff-template.md。

交接文档会将旧聊天转化为持久的项目记忆。阅读仓库和交接文档后，新建的 Codex 线程应能继续工作，而无需原始聊天历史记录。

对于用户可能希望继续的每个活跃仓库聊天，提供以下提示词：

Create a comprehensive handoff document for this repo/session before I archive Codex history.

Include:
- repo/path and branch
- current goal
- what we already completed
- files touched or investigated
- commands/tests already run
- known errors, warnings, or failing checks
- open decisions
- constraints, user preferences, and do-not-touch areas
- the next 3-7 concrete steps

Also include a reactivation prompt I can paste into a fresh Codex chat so it can continue from this handoff without relying on the old chat context.

Save the handoff in a sensible repo-local place like docs/codex-handoffs/YYYY-MM-DD-topic.md unless this repo already has a better handoff location.

交接文档应记录：

• 仓库／路径和分支
• 当前目标
• 已完成的工作
• 已修改或调查的关键文件
• 已运行的命令／测试
• 已知故障或警告
• 尚待决定的事项
• 接下来 3-7 个具体步骤
• 任何约束、用户偏好或“请勿触碰”的区域

在顶部或底部添加重新激活提示词：

We are continuing from this handoff. Read this document first, inspect the current repo state, verify what still applies, and continue from the next steps without assuming the old chat context is available.

自动化提醒提示词

首次完成报告／应用／验证周期后，提供此提示词：

Use $keep-codex-fast to create a recurring Codex maintenance reminder.

Schedule it weekly if I use Codex heavily, or biweekly if that seems safer.

The reminder should:
- run the keep-codex-fast report first
- never pass --apply or run mutating maintenance automatically
- never archive, move, prune, rotate, normalize, delete, or mutate local Codex state
- remind me to create comprehensive handoff docs and reactivation prompts for active repo chats before any manual apply
- summarize active session size, archived session size, extended path candidates, old session candidates, worktree candidates, log size, and top Node/dev processes
- report heavy Node/dev processes without killing them
- tell me that manual apply should only happen after I confirm handoffs exist or are not needed and Codex is closed

反模式

避免以下行为：

• 永久删除会话、日志、工作树、记忆、插件或技能
• Codex 正在写入数据库时应用更改
• 创建交接文档前归档重要的仓库聊天
• 未确认用户是否需要保持连续性，就将活跃历史记录的大小视为“糟糕”
• 将预览元数据修复视为删除实际 rollout 记录
• 自动终止 Node／开发进程
• 未备份且未进行解析检查就改写 config.toml
• 在 Windows 上写入带 BOM 的 UTF-8 TOML
• 将速度提升说成普遍事实；应将改进描述为本地状态维护结果
• 让用户觉得频繁使用 Codex 是做错了

面向用户的注意事项

请告知用户，此操作不会永久删除聊天记录、工作树或日志，而是将它们移入归档文件夹，并写入恢复辅助脚本。唯一会被移除的内容是过时的元数据，例如指向已不存在文件夹的项目条目；而且这也会在备份 config.toml 后进行。

另请告知用户，修复线程标题／预览膨胀不属于常规应用流程。常规使用只会报告标题／预览膨胀。只有当报告显示元数据负载较大，且用户了解 SQLite 显示元数据会被缩短、而实际对话记录仍保留在 rollout JSONL 中时，才建议将 --repair-thread-metadata-bloat 作为可选的额外操作。

还请告知用户，备份文件夹可能包含私密的本地 Codex 元数据，包括旧线程标题和首条消息预览。备份应保留在本地；除非已检查其中的内容，否则不要发布或分享。