context-mode 在 Codex CLI 上不生成压缩前快照怎么排查？-育师

context-mode 在 Codex CLI 上不生成压缩前快照怎么排查？

【免费下载链接】context-modeContext window optimization for AI coding agents. Sandboxes tool output (98% reduction), persists session memory, and enforces routing across 17 platforms via MCP + hooks.项目地址: https://gitcode.com/GitHub_Trending/cl/context-mode

在 Codex CLI 里使用 context-mode 时，对话被压缩（compaction）之后，模型应该能从上次的工作状态继续：文件、任务、决策、未解决的错误都在。这个能力依赖PreCompact钩子——它在压缩发生前把会话事件写成一份恢复快照存进session_resume表，随后由SessionStart（source 为"compact"）把快照取回并注入上下文。

如果你在压缩后发现 context-mode 没有生成这份压缩前快照，问题通常出在三处之一：

Codex CLI 版本较旧，运行时根本不发PreCompact事件（文档明确说明该支持是 runtime-gated）；
钩子功能开关没打开，hooks.json里的PreCompact命令没有真正执行；
precompact钩子执行了但内部报错，错误被写进了调试日志。

下面按这条线索逐步排查。排查前请确认你的环境满足前提：Node.js >= 22.5（或 Bun）、Codex CLI 已安装、context-mode 已按 README 的 Codex CLI 章节安装（插件路径或手动路径均可）。

第一步：确认快照机制依赖的两个事件都已触发

先理解数据流，排查才有方向。context-mode 的恢复流程是：

PreCompact fires → Read all session events from SQLite → Build priority-tiered XML snapshot (≤2 KB) → Store snapshot in session_resume table SessionStart fires (source: "compact") → Retrieve stored snapshot → Write structured events file → auto-indexed into FTS5 → Build Session Guide with 15 categories → Inject <session_knowledge> directive into context

也就是说，"不生成快照"的直接原因只能是PreCompact没有触发，或者钩子触发了但执行失败。而PreCompact能否触发，第一道门槛是 Codex 本身的构建版本。

第二步：检查 Codex CLI 版本是否发出 PreCompact 事件

docs/platform-support.md 在 Codex CLI 一节的 Known Issues 中写明：

PreCompact support is runtime-gated: context-mode configures it and treats a missing registration as a warning, because older Codex builds may not emit the event.

README 的 Codex CLI 安装章节也有对应说明：PreCompact支持是 runtime-gated 的，在 Codex CLI 0.130.0 中已存在，而公开的 Codex hooks 文档可能滞后于实际发布的 hook 事件列表——旧版本 Codex 构建不会发出PreCompact，也就不会创建压缩前快照。

用终端确认你的版本：

codex --version

如果你的版本低于 0.130.0，这就不是 context-mode 的配置问题，而是构建能力缺失。对应的解决路径是升级 Codex CLI 到会发出PreCompact的版本；在旧版本上，context-mode 侧没有可以绕过该限制的开关。
如果版本满足要求，继续往下排查钩子配置。

第三步：确认钩子功能开关已启用

Codex 的钩子受[features]开关控制。context-mode 的钩子（包括precompact）只有在功能开关打开、且 Codex 信任这些钩子命令时才会执行。

插件安装路径

如果你是通过 marketplace 安装的插件，检查~/.codex/config.toml（Windows 下为%USERPROFILE%\.codex\config.toml），确认存在：

[features] plugin_hooks = true hooks = true

两个标志缺一不可：hooks打开 Codex 的钩子系统，plugin_hooks让插件自带的钩子生效。README 同时说明了一个判断细节：ctx stats能跑通只能证明插件的 MCP server 已安装且可达，不能证明钩子被信任或正在运行。所以不要用ctx stats正常来推断钩子状态。

另外，插件钩子在 Codex 提示批准钩子命令（hook approval）之后才真正激活——如果 Codex 弹过钩子审批而你没确认，PreCompact不会被触发。

手动安装路径

如果 Codex 构建没有plugin_hooks，你走的是手动路径（npm install -g context-mode+ 配置~/.codex/config.toml与~/.codex/hooks.json），那么：

确认~/.codex/config.toml里有[features]且hooks = true（旧别名[features].codex_hooks = true在当前 Codex 构建中仍被接受，但 README 建议优先使用[features].hooks）。
检查钩子配置文件是否存在且包含PreCompact条目。当CODEX_HOME未设置时文件位于~/.codex/hooks.json（设置了CODEX_HOME时为$CODEX_HOME/hooks.json）。其中PreCompact一行应为：
```
"PreCompact": [{ "hooks": [{ "type": "command", "command": "context-mode hook codex precompact" }] }]
```
完整的手动配置参考 configs/codex/hooks.json。如果条目缺失，可以从 Codex CLI 环境里运行context-mode upgrade让 context-mode 重写钩子文件（upgrade只写钩子文件，MCP server 需要单独用codex侧的命令注册）。
如果~/.codex/hooks.json整个文件不存在，说明手动路径没装完整，按 README 的 Codex CLI 章节补齐配置后重启 Codex。

修改任何config.toml或hooks.json之后都需要重启 Codex CLI 再验证。

第四步：查看 precompact 钩子的错误日志

开关和注册都没问题、钩子却仍没产生快照时，看钩子自己的错误日志。context-mode 的 precompact 钩子源码在捕获异常时会把错误追加写入调试日志：

<配置目录>/context-mode/precompact-debug.log

对 Codex 平台，配置目录是~/.codex（CODEX_HOME未设置时），所以实际路径为：

cat ~/.codex/context-mode/precompact-debug.log

日志中每行形如[时间戳] 错误信息。

日志存在且有错误条目：按条目里的报错修复（例如依赖或数据库问题），修复后重新触发一次压缩验证。
日志不存在或为空：说明钩子大概率根本没有被调用，回到第三步复核功能开关和钩子信任状态。

第五步：用诊断工具确认整体注册状态

最后用 context-mode 自带的诊断确认运行环境整体健康：

context-mode doctor

或在 Codex 会话里直接输入ctx doctor（由模型调用ctx_doctorMCP 工具），输出带[OK]/[FAIL]/[WARN]前缀的检查项，覆盖运行时、钩子、FTS5 与版本。若需要一份更完整的报告用于反馈 bug，还可以运行 scripts/ctx-debug.sh：

bash scripts/ctx-debug.sh

该脚本会收集系统信息、运行时版本、better-sqlite3 状态、适配器检测、配置内容（脱敏）、钩子校验、FTS5/SQLite 测试、会话数据库等 18 个部分，把 markdown 和 JSON 报告写到临时目录（/tmp/ctx-debug-<ts>.md和/tmp/ctx-debug-<ts>.json）并在终端显示摘要。

修复后如何确认快照恢复生效：让会话执行多轮工具调用后自然触发压缩，压缩完成后的新一轮会话里，模型应能从上次的任务、文件和决策直接继续（即SessionStart成功取回了session_resume表中的快照并注入了<session_knowledge>指令）。

已知边界与限制

旧版 Codex 构建：不发PreCompact的构建上，快照无法生成，context-mode 把这种缺失当作 warning 处理（fail-open，不阻断压缩）。这是版本能力问题，不是配置问题。
MCP 与钩子相互独立：ctx stats正常只说明 MCP server 可达；钩子路由是另一条链路，必须分别验证。
PreToolUse 能力受限：Codex 的 PreToolUse 目前只支持 deny 规则，不支持additionalContext注入（上下文注入走 PostToolUse 和 SessionStart，context-mode 自动处理）。这不影响快照功能，但排查其他钩子行为时要注意。
快照预算：快照按优先级分层构建，2 KB 预算紧张时低优先级事件（如意图、MCP 工具计数）先被丢弃，关键状态（活动文件、任务、规则、决策）始终保留。

如果按以上步骤走完，版本 ≥ 0.130.0、开关与钩子注册都确认无误、precompact-debug.log无报错，仍然没有快照，建议用bash scripts/ctx-debug.sh生成完整诊断报告反馈给项目方。

创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考