ctx-stats 技能深度解析：用 context-mode 量化 AI 编码会话的上下文节省

ctx-stats 技能深度解析用 context-mode 量化 AI 编码会话的上下文节省【免费下载链接】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-modectx-stats是 context-mode 项目内置的元工具技能之一用于向用户展示当前会话中 context-mode 到底替你省下了多少上下文窗口。本文以 skills/ctx-stats/SKILL.md 为主干结合 src/server.ts 中的 MCP 工具实现、docs/adr/0004-stats-strict-compression-formula.md 架构决策记录以及相关测试完整还原它的调用流程、输出语义与底层统计口径帮助你理解12.4x、92%这类数字究竟是怎么算出来的以及如何在 17 个 AI 平台上使用它。一、ctx-stats 是什么context-mode 通过 MCP Hooks 机制在运行时把工具输出重定向进沙箱sandbox把会话记忆持久化到本地 SQLite从而让最终进入模型上下文窗口的字节数大幅下降。ctx-stats就是负责证明这件事发生了多少的诊断工具它报告本次会话的 Token 消耗、上下文节省比例以及按工具拆分的明细。从技能元数据skills/ctx-stats/SKILL.md可以确认它的三个定位只读Read-only只展示统计没有任何重置能力无参调用调用mcp__context-mode__ctx_stats时不需要任何参数会话级视角展示的是当前会话的节省情况。触发方式有两种平台触发方式Claude Code插件/context-mode:ctx-stats其他平台在对话中直接输入ctx stats模型会自动调用对应的 MCP 工具二、Agent 执行流程三步走skills/ctx-stats/SKILL.md 为 Agent 规定了严格的执行顺序这也是所有平台共用同一套行为契约的原因见 CLAUDE.md 与各平台配置中的ctx stats指令行。调用mcp__context-mode__ctx_statsMCP 工具无需任何参数。MCP 工具的全名在 Claude Code 等平台写作mcp__context-mode__ctx_stats在 Gemini CLI、Kiro、OMP 等平台的指令中写作stats本质是同一个工具。CRITICAL——必须逐字粘贴完整输出Agent 必须把工具返回的整段输出以 Markdown 文本形式原样复制进回复不得摘要、不得折叠、不得转述。这是为了让用户无需按ctrlo查看原始工具输出就能看到完整表格。追加一句话高亮关键指标在完整输出之后用一句话点出最关键的节省数字例如context-mode saved **12.4x** — 92% of data stayed in sandbox.如果还没有任何数据No context-mode calls yet this session.这套完整粘贴 一句话总结的契约之所以被写成CRITICAL是因为 ctx-stats 的价值完全在于原始表格的完整性——用户需要看到按工具拆分的明细Bash 重定向省了多少、Read 省了多少、ctx_* 工具自身输出了多少而不是一个被模型二次加工的摘要。仓库中 configs/cursor/context-mode.mdc、configs/qwen-code/QWEN.md 等 17 个平台的指令文件都镜像了这一要求。三、只读语义与 ctx_purge 的边界ctx-stats 技能特别强调了它与重置能力之间的边界ctx_stats只读——只展示统计不删除、不重置任何内容若用户要求清空知识库wipe the knowledge base必须改用ctx_purge(confirm: true)通过/context-mode:ctx-purge触发。这一边界在 skills/ctx-purge/SKILL.md 中同样被重申ctx_statsis read-only — shows statistics only且ctx_purge是删除会话数据的唯一途径/clear与/compact都不会影响 context-mode 的任何数据。两篇技能文档互为对照构成了看统计用 ctx-stats、删数据用 ctx-purge的清晰职责划分。值得一提的是ctx-purge 还支持两种删除范围issue #520scope: project会清空知识库、全部会话 DB 行、事件 Markdown 与统计文件sessionId: id只清理匹配会话的行与 FTS5 分块。因此先跑 ctx-stats 预览分类计数再决定是否 purge是官方建议的排查路径见 src/server.ts 中 ctx-doctor 的诊断提示。四、底层实现ctx_stats 工具的注册与数据装配表面上一个无参调用的简单工具在 src/server.ts 中对应一段相当严谨的实现工具注册于src/server.ts:3936起。拆开来看有四层4.1 工具注解annotationsannotations: { readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: false, },注释中明确记录了背景issue #846Codex 会取消未标注的只读诊断工具因此必须显式声明readOnlyHint否则在 Codex 平台上ctx_stats可能根本不执行。4.2 空参数 SchemainputSchema: z.object({}),与技能文档no parameters needed完全一致——这是项目中唯一一个零参数的工具也侧面说明它是一条纯读路径。4.3 单一数据源AnalyticsEngine.queryAll()工具描述写着Returns context consumption statistics for the current session. Shows total bytes returned to context, breakdown by tool, call counts, estimated token usage, and context savings ratio.处理器内部遵循ONE call, ONE source原则以只读方式打开 SessionDBreadonly: true调用AnalyticsEngine.queryAll(sessionStats)生成主报告。随后会尽力装配以下补充数据且每一步都包裹在 try/catch 中遵循corrupt sidecar can never break ctx_stats的容错纪律数据块作用mcpUsage各 MCP 工具的使用量lifetime跨项目生命周期统计经getSessionDir()定位到当前适配器的会话目录multiAdapter跨适配器聚合支撑across N AI tools的标题行conversation/realBytes会话级实时统计包含getConversationWindowStats以 worktreeHash sha256(cwd) 为作用域把子代理与ctx_execute子进程会话的沙箱节省归入同一窗口indexState持久化存储的total_chunks/last_indexed_at供渲染器展示4.4 降级路径如果 SessionDB 不存在或不可用处理器会退回最小报告模式用createMinimalDb()空适配器生成queryAll结果再尽力附加 lifetime 与 multiAdapter 数据Pi 适配器还会通过patchPiLifetimeFromStatsFiles从stats-*.json边车文件读取真实bytes_sandboxed。所以无论存储状态如何ctx_stats永远不会因为 I/O 失败而崩掉——这是代码中反复出现的 never block ctx_stats 容错原则。五、统计口径严格压缩公式ADR-0004ctx-stats 展示的节省百分比背后有一个重要的语义决策记录在 docs/adr/0004-stats-strict-compression-formula.md 中。5.1 历史问题ctx_stats的 Section 1 百分比柱曾因两次无关的 bug 级联而悄悄漂移先是 v1.0.134 的一个退化为 100%显示修复引入了eventDataBytes双侧计入的临时公式随后 v1.0.148 让真实的bytesAvoided信号终于流入统计后该公式开始对用户明显应为 95% 的会话报出约 56%。报告者机器的实测数据是bytesAvoided 2,898 KBBash/Read 重定向节省 沙箱 PID 突发bytesReturned 140 KB打印的 ctx_* 输出eventDataBytes 2,136 KB其中 84% 是同一份 CLAUDE.md 在 resume 周期中被 SessionStart 钩子捕获的 496 份重复拷贝5.2 最终公式ADR-0004 裁决Section 1 的百分比柱必须使用严格压缩公式——if (bytesAvoided bytesReturned 0) { // 空状态——还没有可测量的重定向活动。 // 不绘制退化柱输出一行诚实提示 No measurable redirect activity captured yet — bars will appear once context-mode diverts its first payload. } else { Without bytesAvoided bytesReturned With max(1, bytesReturned) pct (1 - With / Without) * 100 }关键决策是eventDataBytes从两侧都排除钩子捕获的载荷字节写入 SessionDB 是为了构建知识库它们属于分析基础设施从未进入模型上下文窗口计入比例会混淆两类不同的量。eventDataBytes仍可出现在 Section 2捕获计数1,000 things — files, errors, decisions, agent runs中在那里它准确代表钩子层记录了什么东西。5.3 修复前后的对比指标v1.0.147损坏v1.0.148 SLICE Bv1.0.148 本 ADRWithout158 KB5,177 KB3,038 KBWith158 KB2,279 KB140 KB% kept out0%恒等56%偶然95.4%运行时倍数1×2×22×其中 22× 就是这个会话因 context-mode 重定向而获得的真实上下文窗口延展——正是用户直觉上期望看到的那个数字。技能文档示例中的saved **12.4x** — 92% of data stayed in sandbox正是这套口径在真实会话中的典型形态。5.4 不同区块的语义差异ADR 同时澄清生命周期区块Section 3/4的累计总数如 14.7 MB kept out across 200 projects不受本 ADR 影响——它们聚合bytesAvoided eventDataBytes snapshotBytes衡量context-mode 存入存储的所有字节与仅纠正了百分比语义的会话级 Section 1 是两个不同的度量。因此当你看到会话级 95% 而生命周期 14.7 MB时二者并不矛盾。六、输出报告的构成与缓存统计ctx_stats的完整输出由formatReport渲染为叙事式五区块布局源码注释称之为 timeline、ladder、receipt、example cost、auto-memory 五段叙事对应关系大致为Section 1Where you are now——实时会话窗口的节省百分比严格压缩公式Section 2捕获计数——知识库收录的 1,000 things文件、错误、决策、Agent 运行Section 3/4生命周期累计——跨项目、跨适配器的总节省字节。此外README.md 明确说明ctx_stats单独报告缓存性能——TTL 缓存命中次数、因命中而避免的数据量、节省的网络请求数以及包含缓存在内的总上下文节省。这对应ctx_fetch_and_index的 24 小时默认 TTL 缓存机制命中时只返回约 0.3KB 缓存提示而不是重新抓取 48KB 的文档这些被避免的字节同样计入统计。七、statusline 镜像统计永不漂移仓库根目录的 bin/statusline.mjs 是一份与ctx_stats同源的常驻状态行实现。文件头部注释明确说明它mirroring thectx_statsMCP handler at src/server.ts ... so the statusline and ctx_stats never drift且内部注释指出Mirrors src/server.ts:2860 — the same call ctx_stats useslifetime 日均值计算与 ctx_stats 的开场统计使用同一套实现。这意味着你在状态栏看到的数字与ctx stats完整报告中的数字永远一致。八、跨平台验证方式ctx-stats 是各平台安装验证的首选命令README.md 为 17 个平台给出了几乎一致的验证步骤Copilot Chat / Copilot CLI / OpenCode / KiloCode / Kimi / Zed / Pi 等在会话中直接输入ctx stats确认工具能出现并响应Cursor打开 Settings MCP 确认 context-mode 显示 connected然后在 Agent 对话中输入ctx statsOpenClawctx stats同时验证插件 MCP 服务器的可达性src/adapters/openclaw/mcp-tools.ts 中ctx_stats通过cliRedirect(ctx_stats)注册Codex / Kimi重启 CLI 后用ctx stats验证 MCP 注册它能证明插件 MCP 服务器已安装且可达但 hook 路由需另行验证。建议在安装后立即运行/context-mode:ctx-stats或ctx stats首次调用会显示空状态提示行而完成任意一次工具重定向后再调用即可看到百分比柱出现。九、验证资产测试与渲染证明仓库为 ctx-stats 的口径提供了多层验证格式测试tests/analytics/format-report.test.ts、tests/analytics/format-report-real-bytes.test.ts与tests/analytics/stats-output-format.test.ts断言报告渲染语义其中 ADR-0004 提到有四个 fixture 测试锁定新语义空状态提示、诚实的混合百分比、仅有bytesAvoided时的 100%生命周期与多适配器tests/analytics/lifetime-stats.test.ts、tests/session/multi-adapter-render.test.ts、tests/session/multi-adapter-stats.test.ts覆盖跨项目、跨适配器的聚合行为离线渲染证明scripts/prove-narrative-render.ts用生产环境的ctx_stats调用路径src/server.ts:2636 附近验证叙事渲染无需等待真实会话即可检查输出格式统计文件测试tests/analytics/lifetime-stats-config-dir.test.ts、tests/session/stats-output-format.test.ts等覆盖统计文件的读写与降级路径。十、与其他元工具的分工ctx-stats 属于 context-mode 的五个元工具之一另外四个是ctx_doctor、ctx_upgrade、ctx_purge、ctx_insight与六个沙箱工具ctx_batch_execute、ctx_execute、ctx_execute_file、ctx_index、ctx_search、ctx_fetch_and_index共同构成 11 个 MCP 工具面。在诊断场景中的协作方式为用户想看节省效果→ctx stats只读统计用户想排障→ctx doctor用户想释放内存或提升性能→ 官方建议先跑 ctx_stats 预览分类计数不要直接 purge确认要清空 →ctx_purge(confirm: true, scope: project)才是唯一途径。结语ctx-stats看似只是一个显示统计的小技能但它背后是完整的数据管线Hook 层重定向与捕获、SessionDB 只读查询、严格压缩公式的百分比语义、跨适配器与跨项目的生命周期聚合以及永不因边车损坏而失败的容错纪律。理解了 skills/ctx-stats/SKILL.md 的三步执行契约和 docs/adr/0004-stats-strict-compression-formula.md 的统计口径你就能准确解读任何一次ctx stats输出——无论是 95.4% 的会话级节省还是 22× 的上下文窗口延展倍数。【免费下载链接】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创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考