token-optimizer-mcp

Token Optimizer MCP

压缩优化的是你的账单，而非字节数 &mdash； 并附上基准测试，方便你自行验证。

一个本地账本，记录优化器工具、实时图谱替换、每个 Agent，以及图谱本身的成本。

与 HeadRoom 的比较

提供商会缓存提示词前缀：重新读取缓存 Token 的计费倍率为 0.1x，重写的 Token 则按 1.25x 计费。大多数压缩器只优化删除的字节数，而忽略这一倍率。这个工具优化的是账单。

使用对方自己的测试数据，针对其真实实现进行测量。 并非重新实现，也不是使用我们的测试数据：对方的测试框架会压缩载荷并将其导出，然后由他们的解析器还原他们自己的标记；我们拿到的则是完全相同的字节。表格中对方一列按行列出能捕获保持状态的九种配置中的最佳结果。

表格中列出了我们的两种模式，它们回答的是不同的问题。ours 是无法移动内容块的区块引擎，其运行方式与 MCP 工具和钩子相同：它删除的所有内容都通过压缩来删除，不会有任何内容离开请求。ours, proxy 是 Claude Code 会话所使用的代理，它也会将无法压缩的内容块移到文件中，并留下标明路径的标记——与他们的内容缓存参考采用同类权衡。ours, preset 是启用了内容移出的区块引擎，其 spillWholeBlockBelow: 0.9 设置已开启。

记录于 2026-10-17，版本为 b1231a8c，由记录的 regenerate 字段中的命令生成，使用 HeadRoom 0.37.0 自带的测试数据和测试框架。该测试分支运行的是 HeadRoom 本身，因此 CI 不会重新计算这些数据，而是会根据记录核对这些数值及其来源。

在整个语料库中，代理可减少 82.5% 的字符和 91.5% 的 token；他们的最佳配置可减少 51.5% 和 61.4%。在完全不取回任何内容时，代理在 18 行中的 18 行都比他们的最佳分支更省，这正是其标记机制适用的范围；即使取回所有已移动的区块，也有 18 行中的 17 行更省。仅区块引擎就能减少 72.0% 的字符和 55.9% 的 token：减少的字符比他们更多，减少的 token 则更少。 它们仍有优势的场景及原因。 在 codebase-exploration、grep-output、 raw-build-log、sre-debugging 和 4 个原始数据行中，它们的最佳方案可减少 83.2-99.8% 的令牌，而块引擎可减少 12.7-62.4%。它们在这些行中的数值代表 内容缓存引用：块本身并没有变小，而是从请求中移出，放入存储，再替换为 <<ccr:hash,kind,size>> 标记。没有存放块的位置的引擎无法做到这一点，因此在这些行中， ours 列的压缩率较低；如果没有任何内容被取回，成本也更高。代理采用了同样的做法： 在这 8 行中，有 5 行优于它们，在 grep-output 和 raw-build-log 上持平，在 codebase-exploration 上落后 0.1 个百分点。只有在取回它移出的所有块时，代理在 agentic-conversation 这一行的成本才高于它们：它们不会将这段对话的任何内容移出， 所以无论在哪一端，成本都相同；而代理会移出其中一部分，并为每个想要取回的部分支付一次检索成本。

另一个列项是轮次。 标记并不是内容本身：要读取它所代表的内容，Agent 需要发起一次请求。 在语料中植入的 13,792 个保留单元中，块引擎将 5,223 个保留在文本中，还有 8,569 个 仅凭文本即可重建，因此无需额外轮次就能获取全部内容；它们将 6,711 个保留在文本中， 还有 7,075 个存放在其存储中，只需一次检索调用即可获取。 我们这边有 0 个无法恢复，它们那边有 6 个。 它们的最佳方案需要在整个语料中 进行 17 次往返才能取回内容；块引擎则为 0 次。代理与它们一样，会为每个移出的块 付出一次轮次代价；成本模型中按取回率计算的部分正是为这次轮次定价。

它们的标记成本不仅按大小计算，也有其他定价因素。 它们的代理还会随请求发送 一个 headroom_retrieve 工具，标记才能兑现。该工具默认开启（ccr_inject_tool）， 且只要某个会话用过它，之后的每个请求也都会发送。因此，它们的最佳方案留下标记的 每一行，都会计入该工具定义的成本；相关数据由其自有软件包中的 bench/compression/headroom/ccr-tool.py 记录。首次添加该工具的轮次还会重写其后 整个缓存前缀，但这部分未计费，这对它们更有利。我们不需要工具：我们的标记指向一个 路径，Agent 可用已有的 Read 工具打开；路径成本按代理实际写入的长度计算 （<home>/.tok/<pid>/<15 digits>，src/compress/spill-path.ts），而不是按一个人为设定的更短路径计算。

browser-session 主要受测试样例影响。 该负载包含 4 张图像，其中 2 张互不相同； 其中的 base64 数据由程序生成，而非来自照片：仅一张不同的图像就能从 160,032 个字符 缩减到 5,572 个字符，真实的 PNG 不可能达到这种效果。真实会话中仍然适用的是重复内容： 一半图像字节是请求中已有图像的副本，占整个负载的 44.3%。标记所指向的运行记录仍在其上方的 输出中，因此读取者无需请求任何内容即可重建它。这就是字符数下降远大于令牌数的原因： 无论哪种方案，图像令牌都根据像素计算。

重现完整表格：

python bench/compression/headroom/run-theirs.py <headroom-clone> <out-dir>

python bench/compression/headroom/resolve-theirs.py <headroom-clone> <out-dir>
node bench/compression/head-to-head.mjs <out-dir>

与它们已发布的设计对比

第二种方案根据它们自己的基准生成器定义，重新实现了其已发布的设计——不透明哈希标记、 压缩历史记录、注入检索工具和系统消息——因此，对于有已发布对比项的 4 种工作负载， 无需使用它们的克隆即可进行比较。运行 node bench/compression/proof.mjs：

codebase-exploration 原本属于他们，现在属于我们，领先 7.3 个百分点。 本表的早期版本曾声称我们在该行的得分为 61.3%，后来改为持平，再后来公布的结果是我们以 46.0% 输给他们的 47.4%。前两个数字来自一个分支，而非此处；第三个数字在写下时确实适用于当前代码树；随后四次 log 引擎提交将其提升到 54.2%，通过屏蔽内部的 hashbang，让拼接后的代码块仍可解析，将其提升到 64.9%；为每个标记加上六字符戳记又让分数回落了 0.2 个百分点；再后来，不再用计数器中的位置命名溢出文件，而是像代理接收器实际那样用内容摘要命名，又让分数下降了半个百分点，最终达到 64.2%。之后，计量单位不再是估算值：上表中的每个数字现在都是 Anthropic 自有分词器返回的文本计数，并记录在已提交的固件中，因此无需联网；按这一计量方式，该行显示 53.7%。按代理接收器实际写入的方式为路径计价——使用内容寻址和十进制名称，而这个分支却凭空使用了 32 位十六进制名称——又将其提升到 54.7%。这是这段历史中最大的变动，也是唯一一项与引擎本身无关的变动。按字符数除以四计价，之前对控制端的十六进制标记收费过高，却严重低估了我们自己的戳记成本——当时的戳记由六个不含元音的 base-31 字符组成，而大字母表中的随机字符串接近 BPE 分词器最难处理的情况，因此实测成本为 5.52 个 token，按字符数除以四却只计为 2。这三项是此处仅有的三个逆向变动，但都不是回归：每一项都只是测试框架开始向我们收取此前漏算的费用。看清这笔成本，才有了下一步改进：现在戳记改为九位十进制数字，携带的信息熵略高于之前的六个字符，而且每次固定花费 4 个 token，而非平均 5.52 个、且在 4 到 7 个之间波动。与该行的旧戳记相比——代码树相同、固件相同，唯独将戳记恢复为原来的 base-31 形式——这一改动带来了 0.1 个百分点的提升，而这就是实事求是的幅度：单个标记的成本降低了四分之一以上，但标记只占引擎输出的一小部分，因此整体分数的提升远小于每个标记的节省幅度。正文中的数字反映的是测量时对应代码树的情况，因此 bench/compression/readme-table.check.mjs 会根据测试框架重新推导上述内容中的每个数字，而不是盲目采信。

与这个重新实现分支中的四个对比项相比：四项全胜。 若与他们的真实实现相比，答案见本节顶部的表格；结果各有胜负，而非全面领先：在不取回任何内容时，代理在每一行都比他们表现最好的分支更省，但总体上消耗的 token 更多；只有块引擎能在无需额外往返的情况下保留所有标识符，而凡是他们表现最好的分支能将一个代码块移出请求的地方，它在压缩率上都会落败。

这两列来自同一引擎的不同分支，重点就在于此。v3-history 也会压缩历史记录，并与他们逐字节匹配；v1-frontier 则保留缓存前缀不变，让账单降低 11–42%。可以选择最大化移除的字节数，但这不是默认选项，因为处理缓存前缀会产生费用。

竞争对手分支是本仓库对他们已发布设计的重新实现——使用不透明的 hash 标记、压缩历史记录，并注入检索工具和系统消息——并非他们的二进制程序；它也受到与我们自身相同的签名内容防护机制约束。

在完整会话中的表现

node bench/compression/session-replay.mjs 会逐轮重放真实录制的对话，并按照服务商的方式为每轮计价。对四个独立会话进行测试，统计完整请求（包括系统提示词和工具架构），且不使用代理：

这是其他方案都无法触及的部分：对话历史约占实时请求的 65%，也是唯一会逐轮增长的部分。随着会话变长，节省也会增加，因为模型推理内容会不断累积。

在端到端 Agent 任务中的表现

THOL：针对 16 个真实任务，与不使用代理的对照组进行比较：

• 16 个任务中有 11 个更省
• 成本中位数为 0.926x，轮数中位数为 0.671x
• 质量成本为零：平均得分为 0.994，与对照组的 0.994 持平，16 个任务中得分更低的有 0 个

每个任务只运行一次，因此汇总区间仍覆盖 1.0；逐任务统计和得分持平才是可靠的部分。这里的所有数据都由已提交的基准测试重新生成，这些基准测试包含在本仓库中。

30 秒了解

你的 Agent 会把大部分上下文耗在已经做过的工作上：反复读取未更改的文件、为了查看三行内容而输出整个文件、执行没有边界的搜索，以及重新推导上次会话得出的结论——然后又把它们忘掉。

Token Optimizer 从四个方面解决这个问题。

1. 让代价高昂的调用无法执行。 安装插件后，内置工具对 200 KB 文件的 Read 操作会被拒绝，拒绝信息会指出可替代的缓存差异版本。Grep、Glob、Edit、Write，以及通过 shell 调用的 cat / head / grep -r 也是如此。本次会话中已读取过的文件再次读取时，只会返回差异——这通常是最大的收益之一，也是基于大小的规则从机制上无法捕获的情况。无需开启任何设置。

2. 记住 Agent 得出的结论。 每个项目都会随着工作进展，自动积累发现、决策和无效尝试，形成知识图谱；当 Agent 接触相关文件时，图谱就会提供这些信息。传递一条发现约需 150 个 token，重新推导则要耗费 5k–50k。

3. 公开衡量自身表现，并在效果变差时告知你。 对 MCP 渐进式披露进行实测：记录首次返回与实际返回之间的差异，后续展开内容的成本也会从同一净值中扣除。基于图谱替代效果的估算，以及用于衡量图谱下游影响的随机对照组，仍会单独列出。每项数据要么经过测量、正在公开收集、已排除，要么不存在。

4. 归因请求流量。 按操作和 MCP 握手身份分组统计返回的上下文、可选的成本折算值，以及节省的传输量。Codex、Claude Code、Gemini 和其他所有已连接的客户端都会分别列出。缺少身份信息的旧记录会明确标记为未归因，而不会被错误归到当前恰好处于打开状态的 Agent 名下。

无需账户，也无需托管服务。采用 MIT 许可，可用于工作场景。 除非你主动要求，否则不会测量任何与你有关的数据。匿名使用数据默认关闭，并且需要分别选择加入两项设置：TOKEN_OPTIMIZER_TELEMETRY=1 会将计数汇总到你自己磁盘上的文件中，而 TOKEN_OPTIMIZER_BEACON=1 才会上传这些数据。设置第一项不会打开任何套接字。两项都设置后，磁盘上已有的事件会在每次会话启动时发送一次——以批次发送， 绝不在热路径上发送——并且只有在接收方接受后才会清除文件。install_doctor 会显示这两项分别是否开启、有多少事件正在等待，以及数据会发送到哪里；它只报告，不会发送。未包含上传密钥的构建包完全无法传输数据，doctor 会明确说明这一点，而不会让你误以为选择加入后功能正常。 无论其他设置如何，DO_NOT_TRACK=1 都会覆盖这两项。npm run doctor 和 install_doctor 执行的版本检查只是向 npm 安装所用的注册表发送一个普通 GET，不包含任何关于你的信息，而且只会在你主动请求诊断时运行——绝不会在会话期间运行。打开套接字之前，DO_NOT_TRACK=1 或 TOKEN_OPTIMIZER_UPDATE_CHECK=0 都会阻止该检查。事件中只允许包含数字和标记——字符串会在写入前被丢弃，因此路径、提示词或错误消息绝不会意外传出；机器标识符是加盐哈希值，而不是你的主机名。计数取自你自己的项目已经保存的钩子台账：图谱代替工具作答的频率、保留组的各个分支分别交付和扣留了什么，以及节省是否超过成本——每六小时汇总为整数，绝不传输台账本身，因为其中包含你的文件名。使用量按汇总值计数，而不是每个请求单独记一行：每 200 个请求生成一个事件，其中记录请求数、输入和输出字节数、压缩节省成本的频率、注入知识的频率，以及省略的区块数；代理停止时还会生成一个最终事件。这样能确保总数准确——繁忙会话中，每个请求都记一行会使批次溢出，最终只能报告前五百条——代价是无法查看每个请求的分布，而下游并不需要这些信息。npm run doctor 会准确显示这些设置分别是否开启，以及记录了哪些数据。

仪表板在真实机器上证明了什么

本 README 中的截图来自已发布的服务读取的本地持久化数据，而非设计稿。上方的截图显示：

• 当前实时验证结果中，经验证的 MCP 传输净减少 43,491 个 token：总减少 54,037 个 token，减去有意造成的 10,546 个 token 扩增；
• 隔离了 486,074,740 个历史记录／工具报告的 token，其中大部分来自从未进入模型上下文的代码库扫描；
• 对 AiDotNet 进行实时 Codex / Claude Code / Gemini stdio 冒烟测试，并分别归因到各个客户端；
• 在 11 个本地项目中，2,648 个图谱节点、6,527 条边和 58 项发现；
• 在选定的滚动 24 小时窗口内，六个活跃 CLI 客户端共运行了 1,000 多次钩子，失败和超时均为零；
• 6,332 个 token 的建模图谱替代潜力；由于因果图谱复用研究仍处于 Collecting 状态，因此未计入经验证的总数。

仪表板现在会读取 CLI 原生使用量凭证，并按照精确捕获的提供商、模型、路由、请求时层级和带版本号的官方来源，为未缓存的输入、缓存读取、缓存写入和输出计价。对于有歧义的模型 ID，会显示 未定价，而不是给出混合估算。API／标价等值费用与提供商报告的费用分开记录，也绝不会标为订阅账单。请参阅 token 计量约定。

快速开始

Claude Code — 请安装插件，而不是直接安装 MCP 服务。插件会强制执行优化；单独添加服务只会给模型提供它可以忽略的工具。

/plugin marketplace add ooples/token-optimizer-mcp
/plugin install token-optimizer@token-optimizer
/reload-plugins

安装就全部完成了。全部十六个客户端 →

然后，每当你想知道接下来该做什么时：

token_audit

一份排序队列：每个会话中成本最高的项目；只有在配置了自己的有效费率后，才会显示可选的月度成本估算。每一项都说明了如何解决。不是仪表板，也不是六份报告——而是一份队列。

子 Agent 和工作流

Agent 是 token 消耗集中的地方。长时间运行的子 Agent 会在每一轮重新发送完整上下文，因此工具添加的每个字节，在之后的每一轮都会再次产生费用。在一次测量过的会话中，42 个工作流子 Agent 发起了 4,483 次模型调用。其中最长的六个各自发起了 218–348 次调用，上下文峰值达到 336K–609K token。它们合计消耗了 4.0M 个输出 token 和 1.0B 个缓存读取 token。费用来自反复读取，而非写入。

无需设置即可生效的功能

插件的钩子对待子 Agent 的方式与主会话完全相同。无需为每个 Agent 单独配置。

• 整文件读取会显示大纲，通过 Read 和 Shell 都是如此。 Agent 大多用 cat、type 或 Get-Content 读取文件，很少使用 Read。在测量过的会话中，Shell 读取有 2,071 次，而 Read 调用只有 9 次。首次完整读取大型源文件时，无论使用哪种方式，都会返回带行号的符号大纲，而非文件内容。同一文件第二次完整读取时，则会返回文件本身。行范围读取不会生成大纲：sed -n 'A,Bp'、head、Get-Content -TotalCount 和分页 Read 都会原样通过。
• 每个子 Agent 只会收到一次简报。 子 Agent 看不到 SessionStart 指引，因此它的首次工具调用会附带一份四行简报：如果列出了优化工具，就加载它们；读取行范围而非整个文件；并让最终报告保持简短。只有在符合条件时才会提及工具，因此仅安装钩子的用户不会被告知调用自己并未安装的工具。
• 建议只会提示一次。 像“使用 smart_grep”这样的路由提示，对于每种调用，在每个 Agent 中最多出现一次，而不会在每条匹配的命令中重复出现。
• 只有在明确指出你正在运行什么时，才会提供过往发现。 如果某项发现没有明确的触发条件，只有当其结论明确提到命令的程序及子命令（例如 npx jest 或 dotnet build）时，才会随命令一同提供；仅仅共享一个词则不会触发。
• 重复的构建和测试输出会受到限制，与主会话中的处理方式相同。
• 通过代理时，你请求的范围会完整返回。 分页 Read 或 Shell 切片绝不会被折叠；整文件读取中的折叠内容会标明文件自身的行号。

在给 Agent 的简报中添加什么

Claude Code 会将 MCP 工具作为延迟加载工具提供给子 Agent：只有 Agent 请求时，才会加载其架构。未加载这些工具的 Agent 会退回使用 Shell 命令。请将以下内容放入 Agent 的提示词中：

Before your first file read or search, load the token-optimizer tools:
ToolSearch("smart_read smart_grep smart_glob").
Use smart_read for files (it returns a diff on re-reads), smart_grep for
searching, and smart_glob for finding files. Do not print whole files or search
the tree through the shell. When you need part of a file, read a line range.

现在，服务自身的指引也会对所有客户端说明同样的内容，无论工具是否延迟加载。

让 Agent 保持简短

插件只能缩减进入 Agent 上下文的内容。工作拆分方式决定了轮数和上下文大小：

• 每个 Agent 只分配一项范围明确的任务。 几个简短的 Agent 比一个运行数百轮的 Agent 成本更低，因为每个 Agent 都从较小的上下文开始。
• 提供 Agent 所需的信息（路径、行号、具体问题），而不是让它重新寻找这些信息。
• 要求结构化结果，让 Agent 得到答案后就停止。

衡量 Agent

每个子 Agent 都会在会话记录旁边写入自己的记录，路径为 ~/.claude/projects/<project>/<session>/subagents/。每条助手记录中的 usage 区块都会记录 input_tokens、output_tokens、 cache_read_input_tokens 和 cache_creation_input_tokens。

每次响应只计一次。 一个模型响应会写成多条共享同一 message.id 的 助手记录，每条记录都会重复当时累计的用量。保留每个 message.id 的最后一条记录，它包含最终用量，然后求和。累加所有记录会高估成本：在上述会话中，缓存读取令牌数被报告为 1.8B，而不是 1.0B。反过来，保留第一条记录则会低估输出，从 4.0M 变成 0.5M。

不同 message.id 的数量就是 Agent 发起的模型调用次数。结合其峰值上下文来查看，就能判断是否应该拆分该 Agent。

知识图谱——其他工具都没有的部分

每个 Agent 会话结束时都会发生同一件事：推理过程随之消散。下一个会话会重新推导一遍，永远如此，而且每次都要付出全部代价。

这会构建一个持续演进的项目级图谱——节点涵盖文件、符号、任务和发现；边包括 derived_from、contains、supersedes、contradicts、 related——并从实际工作中自动填充图谱。无需摄取任务，无需嵌入模型，无需重建步骤，也无需构造查询。

you touch  src/auth.ts
           │
           ├─ verify() compares exp against the LOCAL clock          (finding, 0.9)
           ├─ per-host retry budgets; global was rejected — deadlock (decision)
           ├─ ! the skew fix was reverted once already               (dead end)
           └─ [git] 47 changes in 90d, last three: "fix token expiry",
                    "revert skew fix", "fix token expiry again"

这些内容都不在你的代码库中。它们之所以存在，只是因为某个 Agent 曾经花费令牌找到了它们——而其他工具都会在会话结束时将它们丢弃。

默认安装实际会生成什么。 结构图谱——文件、符号、任务及其相互之间的边——会从普通工具流量中捕获，无需任何配置。发现通过两种方式生成。会话结束时，derive 会读取磁盘上已有的证据（命令结果和退出代码、从红到绿的转换、修正、反复重读），并据此写入发现：不调用模型、不需要凭据，也不会向任何地方发送数据。而活跃模型则会通过 wiki_write 自行记录持久结论。

基于模型的语义收集是第三种方式，也是唯一需要你尚不具备的条件的方式。它并非选择加入——TOKEN_OPTIMIZER_HARVEST=0 会将其关闭——但真正的门槛是凭据：没有凭据时，它会报告 off:no-key；这正是 CI、企业设备和仅使用订阅登录的状态。将 TOKEN_OPTIMIZER_HARVEST_ENDPOINT 指向本地模型后，它便会免费、私密地运行，所有数据都不会离开设备。运行 npx token-optimizer-doctor 可查看当前启用的是哪种方式。

为什么这不是 RAG

遍历加词法搜索：确定、即时、可解释，而且可离线运行。

零轮拒绝

直接拒绝会耗费完整一轮：模型调用 Read，被拒绝后重新规划， 再调用 smart_read。但拒绝时，我们已经持有文件 和 图谱存储的 快照，所以拒绝本身就包含了答案。无需重新规划，也无需第二次调用。 轮次成本从一降为零。

而且，当图谱已经掌握工具输出本应支持的结论时，输出根本不会进入上下文。 不是压缩，而是完全不出现。

仪表板

npm install
npm run build
npm run dashboard      # http://localhost:3100

总览会先回答 Token 优化器应当关注的问题：

1. 避免了多少 MCP 上下文？ 标题数字是物化载荷的总缩减量，减去之后所有关联的展开量。图谱估算值会单独显示。
2. 仍有多少上下文到达了 Agent？ 每个成功的当前 MCP 结果都会记录实际返回的文本，即使没有有效的前置状态。该行会计入上下文，但无法衡量节省量。
3. 哪个 Agent 执行了什么操作，消耗了多少？ 客户端台账和操作表会显示操作、返回的上下文、可选的成本折算值，以及净节省的 Token 数。仅有生命周期事件的客户端会显示 Not measured；不会凭空编造零值。
4. 记忆成本是否高于节省量？ 传递和语义采集所用的 Token 会计入图谱成本。只有通过处理组／对照组证据门槛后，才会计入因果收益。

操作指南：获取有用的数据，而非空荡荡的仪表板

1. 为你的 CLI 安装 MCP 服务和原生适配器。MCP 握手会提供按客户端统计的数据；在客户端协议允许的情况下，原生生命周期钩子会提供自动路由、采集、健康检查和传递功能。
2. 像平常一样使用 smart_read、smart_grep、smart_glob、smart_edit 或其他 MCP 操作。每个成功结果都会记录返回的上下文；具有可比的物化前置状态的工具也会记录总缩减量；之后的 expand 调用会从该缩减量中扣除。
3. 让当前模型通过 wiki_write 记录持久结论。在新的 Agent 重新推导工作之前，针对项目或即将操作的文件调用 wiki_read。原生客户端也可以自动传递匹配的知识。 使用 wiki_query 直接读取图谱——按键读取一条发现、对主张进行 BM25 排序搜索、查看包含邻居节点的节点，或查看图谱自身的审计记录——这样，即使某个子 Agent 从未看到 SessionStart 简报，也能获取之前会话确立的内容。
4. 打开 http://localhost:3100。使用 Overview 查看汇总统计，使用 What it knows 查看采集健康状态、图谱探索、审计和因果证据。
5. 若要注册现有本地仓库而不读取其源代码，请运行 npm run projects:discover -- /absolute/path/to/repos。这会明确显示覆盖缺口，不会捏造发现。

对于维护者，此实时冒烟测试会验证已发布的 stdio 传输，并创建单独归属的统计行，而不会向分析数据库填充种子数据：

npm run dashboard:attribution-smoke -- /absolute/path/to/project /absolute/path/to/large-file
npm run dashboard:verify-live -- http://localhost:3100

健康面板着重呈现运维信息，而非原始文本转储。每个客户端都有活动情况、运行时故障／超时、策略结果和已观察到的覆盖范围。诊断信息不会保留提示词、命令、路径或工具输出。

拖动以旋转，滚动以缩放，点击节点查看来源，或切换到有界的单跳聚焦视图。默认的 所有已知项目 范围通过不透明的项目 ID 汇集本地图谱；文件系统路径不会传到浏览器。

审计选项卡。 矛盾、过时发现和低置信度结论仍可供审核，不会悄然变成模型认定的事实。

证据控制台。 显示客户端／模型／任务分组、带 95% 置信区间的匹配效应、实时结果关联、危害反馈，以及全部 16 个客户端的能力等级。证据缺失时，发布和优越性声明将默认不予通过。

一键导出 Markdown。 累积的图谱会转化为文档，供你检查、编辑和提交。

采用服务端设计：浏览器请求一个邻域、搜索结果或页面。成熟的图谱包含数千个节点，如果一次性全部发送，那么每次加载页面都会下载数 MB 的数据，而视图中实际只显示 20 个对象。

默认的 所有已知项目 范围通过不透明的本机项目注册表合并已捕获的图谱；文件系统路径不会传到浏览器。生命周期钩子会在使用仓库时将其注册。若要补录现有本地检出目录，而不读取其中的源文件，请针对一个或多个明确指定的根目录运行有界发现命令：

npm run projects:discover -- /absolute/path/to/repos /absolute/path/to/worktrees

覆盖情况会区分已有图谱数据的仓库和已知但尚未开始捕获的仓库。各项统计卡片基于已持久化的事件：记忆交付量统计实际提供给 Agent 的图谱上下文，保留作对比统计随机分配的对照组触碰次数，记忆成本则综合已交付上下文的令牌数与测得的语义写入负载成本。避免的读取量在至少有 20 次处理组文件触碰和 5 次具备下游关联的对照样本之前，始终显示为 Collecting 或 Not measured；仪表板不会根据缺失数据凭空估算节省量。

请参阅跨客户端能力契约和实时评估套件。

跨客户端生命周期诊断

每个原生钩子都会写入相同的有界 JSONL 生命周期记录，包括 Claude Code 的自定义路由和压缩路径。记录包含客户端和插件版本、事件、哈希后的会话／轮次关联 ID、延迟、结果、输入／输出字节数以及响应键结构。记录会有意保留提示词、命令、工具输出、文件内容和原始工作目录路径。字段包含 OpenTelemetry 日志严重性和资源语义，因此无需另行设计一套架构即可收集本地文件。

npm run diagnostics                         # last 24 hours, summary-first JSON
npm run diagnostics -- --hours 72 --output hook-summary.json
npm run diagnostics -- --include-events --limit 100 --output hook-report.json

原始事件行需选择启用，且最多保留 1,000 条。默认报告包含总体运行状况，以及最近最多 20 条失败／超时记录，使日常故障排查输出足够精简，可放入命令行和模型上下文窗口。

仪表板的捕获状况面板按客户端显示运行次数、失败次数、超时次数以及 p50／p95 延迟。日志轮转阈值为 5 MiB，最多保留 40 个文件，保存 14 天；设置状态目录时，日志存放在 .token-optimizer/logs，否则存放在 ~/.token-optimizer/logs。TOKEN_OPTIMIZER_LOG_DIR、TOKEN_OPTIMIZER_LOG_MAX_BYTES、TOKEN_OPTIMIZER_LOG_MAX_FILES 和 TOKEN_OPTIMIZER_LOG_RETENTION_DAYS 可覆盖这些默认运维配置。

它与其他优化器不同之处

压缩不破坏缓存，也不会遗漏关键细节

可选的本地代理会在工具结果、搜索输出、日志和对话历史发送给模型的途中对其进行压缩。钩子做不到这一点：PostToolUse 输出架构为 {hookEventName, additionalContext?, classifierContext?}，而客户端中根本没有 updatedOutput，因此钩子可以添加上下文，却无法替换结果。代理从不尝试这样做——它会改写出站请求，而这些结果已经作为历史内容包含在其中。

有两点让它不同于单纯加大压缩力度。

它从不改写缓存内容。 缓存前缀按 0.1x 计费，写入缓存按 1.25x 计费，因此压缩历史记录可能减少 token，却让账单翻倍。我们在自己的基准测试中测得：在缓存断点之后压缩，会在每种工作负载中移除更多原始 token，也会在每种工作负载中花费更多。压缩会在边界处停止，并在原始 token 旁报告按缓存权重计算的 token，让这个陷阱清晰可见，而不是靠推测发现。

它会保留重要的行。 在这里，一个搜索负载中只保留长数组的前几行，得分为 95.7%，却破坏了其中植入的 UUID 记录和错误记录——也就是任何人最可能搜索的仅有的两行。现在，引擎会保留所有偏离常见结构的行，无论它们位于何处：得分 92.4%，且关键项完好无损。基准测试中的一道检查会在植入的关键项消失时让构建失败，因为仅凭大小指标无法区分压缩与截断。

各策略获准改写的内容的缩减率，基于与 HeadRoom 发布的四种工作负载相匹配的测试样例，见本节前面的受保护表格——分别为 97.5%、97.8%、98.6% 和 54.7%，对比它们的 72.8%、92.1%、92.2% 和 47.4%。这里不再重复，而是在表格中只陈述一次并进行核验；也正因如此，这段文案才会在代码树早已变动之后仍声称缩减率为 98.9%、98.2%、92.8% 和 61.3%。

这些并非他们的语料库，因为他们没有公开；代码工作负载会读取此仓库中的真实文件，其余工作负载则根据他们已发布的基准测试生成器定义，生成符合其形态和规模的测试数据。

缩减率不等于账单，两者并不一致。 缓存会改变计算方式：缓存前缀按 0.1x 重新读取，改写后的内容按 1.25x 计费，因此某个方案即使移除了更多字节，成本仍可能更高。运行 node bench/compression/proof.mjs，结果正是如此——HeadRoom 风格方案在每种工作负载中移除的内容比例更大，但按缓存权重计算的有效 token 数在所有工作负载中都更高：

竞品方案是此仓库根据他们已发布的设计自行重新实现的版本——采用不透明哈希标记、压缩历史记录、注入检索工具和系统消息——并非他们的二进制文件。它的实现会尽可能争取胜出：六种工作负载中，原始内容缩减率一栏全都由他们领先。

整段会话的表现。 node bench/compression/session-replay.mjs 会逐轮重放真实记录的对话，并按服务提供商的方式计算费用：最长的逐字节相同前缀按 0.1x 计费，其余内容全部按 1.25x 计费。四个独立会话，完整请求包含系统提示词和工具架构，并与完全不使用代理的情况进行对比：

回放使用存储的转录记录，其中的推理文本已被丢弃，但签名仍予以保留。因此，回放中的节省并不能证明压缩后仍保留了有用的推理内容。回放还使用了我们对竞品设计的重新实现；这些只是离线估算，并非其已发布代理的实际结果。

与 HeadRoom 已发布代理的实时对比。 commit f712b4ec 中记录的平衡四组测试使用了 bench/live/ab.sh，让每组轮流处于每个测试顺序，并在每项任务后独立重新运行 pytest：

加权输入的计算方式为 input + 1.25 * cache_creation + 0.1 * cache_read；不包括输出成本。与对照组相比，零下限的 Token Optimizer 和 HeadRoom 都将该指标降低了约 64%。Token Optimizer 的用量比 HeadRoom 高约 0.9%。这项简单的算术修复任务无法证明它在不同任务上的优势、压缩质量或总成本。轮换测试顺序可以平衡运行位置，但不能保证消除共享的提供商缓存效应。

Codex 与 HeadRoom 0.37.0 的三项任务对比（2026-09-18）。 三项合成的受控读取任务，重复三次，共三组测试，每组都处于每个测试顺序。全部 27 次运行均返回正确答案，因此本对比是在正确率相同的情况下比较成本，而非比较准确率。HeadRoom 使用了其优先压缩的设置 --mode token，而不是用于固定缓存命中率的默认设置 cache。

与对照组相比，输入量在日志任务上减少了 22.7%，在 JSON 任务上减少了 34.3%，在代码搜索任务上减少了 11.5%；与 HeadRoom 相比，则分别减少了 54.9%、10.0% 和 42.2%。在两组对比中，每项任务都更有利于这个代理；JSON 一栏是 HeadRoom 表现最强、差距最小的任务。

可以从两个彼此独立变化的数字中看出其中的机制。每次 REQUEST 的输入均值为 14,156，低于 HeadRoom 的 16,529 和对照组的 18,544——两个代理都会压缩内容，而这个代理压缩得更多。每次 RUN 的请求均值为 3.0，与对照组相同，而 HeadRoom 为 4.3。如果压缩器省略的内容导致 Agent 之后不得不读回，就会多花一轮来恢复；在这些工作负载中，一轮的成本高于省略内容所节省的成本。这正是本项目设置延迟下限要避免的问题，也是额外 1.3 次请求的由来。 这些数据没有展示的内容：这些是 token 数量，而非美元成本，bench/live/report-codex.mjs 有意不为它们估算价格。三个简短的合成工作负载无法证明普遍优势。每项任务都在全新的临时工作区中运行，没有知识图谱，因此图谱注入没有发挥作用；这项测试衡量的仅是压缩效果。缓存 token 是输入列的子集，并非额外费用。HeadRoom 的压缩效果根据服务商用量计分，而非根据我们自己的监听器记录的字节数计分。

使用 HEADROOM_MODE=token node bench/live/codex.mjs 重现，然后运行 node bench/live/report-codex.mjs <evidence-dir>；只有在报告器返回 valid: true、balanced: true 且没有失败后，才读取了上述数据。此前四轮测试被丢弃而未发布：一轮运行时没有 HeadRoom 的 [proxy] 扩展，因此 HeadRoom 的每次运行都在就绪前报错；一轮使用了 HeadRoom 的 cache 默认模式；一轮因请求捕获不完整而被报告器判定无效；还有一轮因主机磁盘已满而遭遇 ENOSPC 中止。

随后进行的 Claude Code 默认模式与激进模式确认测试触及了 Claude 的每周用量上限，因此未能完成。缺失的用量不能算作胜出。Codex 验证通过 Responses API 独立运行。

最新 Codex 联合确认（2026-09-16）。 这项冻结的十二类别研究完成了 120 组配对测试，对比对象为已安装的 HeadRoom 0.37.0。我们的代理通过了 119/120 次尝试；HeadRoom 通过了 120/120 次。一次本地内存分配崩溃导致用量未知。共有 77 次严格联合胜出（通过测试、更省成本且更快）、20 次仅成本方面落败、12 次仅速度方面落败、9 次两方面均落败、1 组耗时相同但成本更高，以及 1 次失败尝试。仅看 119 组数据完整的配对测试，估算 token 成本降低了 26.9%，Agent 耗时降低了 30.1%。JSON 的 Agent 耗时高出 5.6%。只有 logs 和 refactoring 符合各类别的同步标准；完整研究的优越性门槛未通过。这些结果不能证明每项任务都更省成本或更快。已测量的构建保留了显式 null，保留了完整的数值表，并避免复制未更改的载荷。请参阅完整结果、每次失利和保留的崩溃记录。

此前扩展的本地 Codex 确认测试。 一项预注册的七类别研究进行了 70 组配对测试／140 次尝试，对比对象为已安装的 HeadRoom 0.37.0。我们的冻结代理通过了 70/70 次；HeadRoom 因一次上游 HTTP 503 和缺失的用量数据，通过了 69/70 次。因此，完整账本门槛未通过：未能证明优越性。仅看 69 组数据完整的配对测试，我们的代理描述性汇总结果为：估算成本降低 25.7%、输入降低 38.9%、Agent 耗时降低 30.0%。JSON 仍然落败（估算成本高出 35.1%）。请参阅协议、所有尝试和局限。

随后修复了针对罕见字符串分组的问题，以解决 JSON 测试中的失利。在三组数据完整的新配对测试中，与 HeadRoom 相比，输入降低 17.7%、估算成本降低 13.4%、Agent 耗时降低 13.6%；双方各发出三次请求。第四组测试中，我们这边保留了一次上游 503；另有一组测得的配对测试成本仍然更高。这些是开发阶段的结果，并非对新构建的确认，也不能证明在所有工作负载下都能胜出。请参阅完整筛查结果和排除项。 当前修订版 Codex 研究。 下一轮固定的 70 对测试已完成： 我们的代理通过了 69/70，HeadRoom 通过了 70/70。我们剩余的一次尝试遇到上游 503，使用量未知，因此未能确立严格优势。仅统计 69 对完整测量结果，估算成本低 27.9%，输入低 44.2%，Agent 用时低 31.7%。每个类别的平均成本均对我们的代理有利， 包括 JSON，低 27.5%，但仍有 13 对的单次成本更高。本轮测试披露了一次修复：两次 测试之间发生了文件哈希失败；原产品和测试计划保持不变。请参阅完整结果、修订说明和保留的失败记录。

精确搜索行，后续开发。 在保留每个标识符和值的同时提取共享声明语法后，代码大小 差距已消除：在原先 40 个表现较差的输入上，字节数比归档的 HeadRoom 少 37.5%。 另外 8 个新本地用例发送的字节数也更少。4 对平衡的在线测试全部通过审计； 我们的估算 token 成本低 50.1%，输入低 44.8%，Agent 用时低 51.1%。 这是一项小规模开发后续测试，与范围更广的研究分开。请参阅捕获的请求正文、重建检查和在线证据。

成本较高用例的后续跟进（2026-09-16）。 我们调查了全部 13 对表现较差的用例， 并实现了精确的 ID 前缀提取，以及对截断 shell 信封内记录的支持。针对这 13 个用例 开展的固定后续测试通过了全部 26 次尝试；其中 12 对对我们的代理有利，总估算成本 低 33.4%。剩下的失败暴露了外层信封错误。修复该错误后，两对平衡的受控测试都对 我们的代理有利：全部 4 次尝试均通过，估算成本低 34.3%，输入低 15.9%。这些开发 测试保留了所有原始失败；缓存和模型差异也会影响结果。请参阅逐个用例审计、修复、精确重放和在线证据。

本地代理性能（2026-09-16）。 针对已安装的 HeadRoom 0.37.0，我们在三种轮换的 测试组顺序中，对重复和独特日志、JSON 及代码搜索输出进行了 2,160 次已完成的本地上游 请求。所有六组中，我们的平均延迟和进程 CPU 用量都更低。抽样测得的进程树峰值私有 内存为 80.0 MiB，而 HeadRoom 为 1,909.9 MiB；这是内存占用，不是分配量。独特代码 转发的字节数仍多 5.7%。此次吞吐量测量禁用了 HeadRoom 的速率限制；压缩设置保持默认。 这些测量不衡量模型质量或计费成本。请参阅原始样本、复现命令和限制。

在线 Codex 对比（2026-09-15）。 本地 Codex CLI 0.154.0、gpt-6-astra 和已安装的 HeadRoom 0.37.0 完成了一轮平衡的 27 次测试。三个测试组均通过全部 9 项任务；每次 初始读取均完整，且所有提供商账本总量都与 Codex 报告的使用量一致。

这些计数包含缓存输入和额外的检索轮次；它们不是原始压缩百分比，也不是美元成本。 并非所有工作负载的输出 token 都有所改善。请参阅 Codex 证据和限制 以及复现说明。这三个合成任务不足以证明在所有工作负载上都具有优势。 一项独立的 27 次自然工作流开发测试全部通过，与已安装的 HeadRoom 相比，在重试错误修复、多文件重构和配置刷新任务中，测得输入总量分别减少了 35.5%、43.5% 和 16.6%。这些是使用自然工具选择方式的小型合成代码库。未缓存输入和延迟有单独的结果；请参阅工作流证据和局限。

代理默认启用，且仅绑定到本地回环地址。

现在无需通过我们的程序启动任何东西，代理也会启用。 在 7.1.0 之前，只有通过我们的封装程序启动客户端，流量才会经过代理。因此，任何使用 /plugin 安装后，再通过快捷方式、IDE 或桌面应用打开 Claude Code 的用户都不会获得任何优化——而 doctor 会将其报告为安装损坏，而不是报告为功能根本未生效。现在，安装程序会将端点写入 Claude Code 自己的 settings.json；这是我们未启动的会话也会读取的配置文件，并由一个小型后台代理为其提供服务。以下四条规则确保启用代理是安全的：

• 记录在案。 写入的每个值都会与原有值一同保存。token-optimizer-uninstall --apply 会原样恢复；如果该值已不再是我们写入的值，则会拒绝恢复——如果你更改了它，它就归你所有。
• 绝不抱侥幸写入。 只有在代理实际提供路由服务后，才会写入该配置项。配置文件指向一个已失效的端口，并不会让情况平稳降级：客户端将完全无法连接到其服务提供方。
• 自动修复。 每次会话开始时，系统都会在首次模型请求前重新检查；一旦无法提供路由服务，就会立即移除该配置项。
• 不碰非本程序所有的配置。 如果客户端已指向其他本地代理，就不会改动；无法解析的配置文件也绝不会被重写。

设置 TOKEN_OPTIMIZER_DEFAULT_ROUTING=0 可保留仅通过封装程序路由的行为；如果完全不需要本地后台服务，则设置 TOKEN_OPTIMIZER_PROXY_AUTOSTART=0。这两种设置也会撤销已写入的配置项。

托管命令。 全局 npm 安装会启用 Claude 钩子，并在启用生命周期脚本时，于命令提示符、PowerShell、Bash 和 Zsh 中封装你实际安装的客户端命令——claude、codex、gemini、opencode、qwen、crush、droid、cn（Continue）、copilot 和 amp。只有已在 PATH 中的命令才会被封装，因此安装本工具不会占用你尚未安装的客户端名称；如果某个客户端位于 PATH 无法访问的位置，TOKEN_OPTIMIZER_MANAGED_CLIENTS 可接受逗号分隔的列表（或 all）；设置为 0 则会完全跳过 Shell 激活。Windows 安装会将本程序管理的 .cmd 启动器添加到用户 PATH，因此无需更改配置文件或 PowerShell 执行策略。本地安装或禁用生命周期脚本时，请运行 token-optimizer-install。重新打开终端，以加载更新后的 PATH 和 Shell 激活配置。每个托管会话都会启动自己的代理、注册打包的核心 MCP 工具（包括 wiki），并在退出时关闭代理。不启用 Shell 激活也可以使用 token-optimizer-run <client> ...。

哪些客户端可以路由，哪些不行。 其中有 10 个客户端支持重定向模型流量，已在上文列出。Claude Code 和 Gemini 各自只有一个服务提供方，因此安装后即可路由。其余客户端会在各自配置中选择服务提供方；只有配置指定了端点后，才会启用路由——因为如果凭猜测转发，就可能把某个服务提供方的凭据发送给另一家公司。另有 6 个客户端完全无法路由：Cursor、Cline、Windsurf、Kilo、Roo 和 Zed 会在编辑器进程内部运行助手，且没有公开文档说明如何重定向。优化器工具、图谱、钩子等其他功能仍然适用于这些客户端；doctor 会说明此限制，而不会将其计为故障。 token-optimizer-route 会显示当前运行的内容，以及代表你写入的配置。Zed 是唯一一个既可以配置路由、又无法替你配置路由的客户端——它的提供方是你在编辑器中选择的命名条目，只有你知道它应使用哪个端点和模型：

token-optimizer-route                                                  # what is routed right now
token-optimizer-route zed --upstream https://api.openai.com/v1 --model gpt-4o
token-optimizer-route zed --remove

此处 Zed 的提供方架构来自其已发布的设置文档，且本仓库尚未在已安装的 Zed 上进行验证。它会写入一个可由该命令取回的文件，而且只有在路由已开始提供服务时才会写入内容。

现有的自定义提供方身份验证会留在客户端中，你自己的端点也仍由你掌控：代理会插入你所配置内容的前面，而不会取代它。TOKEN_OPTIMIZER_PROXY=0 会禁用路由，TOKEN_OPTIMIZER_MODE=off 会禁用优化。npm 生命周期脚本可能会被阻止，因此仅安装软件包并不能证明激活脚本已运行。 OpenCode 的会话插件使用解析后的配置和项目目录；账户凭据和提供方文件会保留原样。不受支持的端点和提供方模式会保留原生路由。由本地托管策略文件或 Windows 注册表策略控制的 Claude 路由也会保留原生路由。远程/MDM 策略可能会在启动后生效；启动器报告的是观察到的模型流量，而不只是监听器启动情况。 doctor 会检查路由配置。 请求正文捕获需通过 TOKEN_OPTIMIZER_PROXY_CAPTURE 显式启用；启用后，会将明文请求内容写入指定目录。 捕获队列最多可容纳 128 个请求和 16 MiB 的排队快照及元数据。超出上限的捕获会被拒绝并发出警告，同时请求会继续处理；实时审计会拒绝不完整的捕获证据。有关已复现的 OOM 修复、受限内存回放和仍存在的成本损失，请参阅分配加固和后续结果。

你的提供方密钥会通过请求头转发，代理绝不会读取、存储或写入该密钥。这一说法的范围比“不会写入任何敏感信息”更窄，区别很重要：代理确实会将_消息内容_写入磁盘，详情见下文，而且不会检查其中是否包含机密。如果对话中包含机密，它就可能像其他文本一样进入溢出文件。

不过，机密不会被发送到未加密的网络：上游既不是 https 也不是回环地址时，代理会拒绝转发；如果未配置上游，代理只会提供 Anthropic 自己的路由——因此，使用其他提供方的客户端会被告知需要指定其提供方，而不会把密钥发送给错误的公司。

代理确实会将部分负载写入磁盘，你应该清楚具体何时会发生。 删除内容时必须提供一种找回原内容的方式，而来自工具结果的内容没有自己的文件——因此，这些内容会写入一个_溢出文件_，标记中会记录其路径。只有当引擎实际删除了可通过路径找回的内容时，才会发生这种情况：JSON 数组的尾部、若干函数体，或一段文字。小于大小下限的请求、没有任何规则命中的请求，以及所有无损删除操作，都不会写入任何内容。

溢出文件会写入操作系统的临时目录下的 token-optimizer-spill/，每份不同的内容对应一个文件，文件权限为 0600（仅所有者可读写），文件名则是使用每个代理进程中新生成的盐对内容计算的 HMAC——因此文件名不会泄露任何信息，而且不同运行之间不会发生冲突。我们绝不会读回这些文件；Agent 会使用已有的 Read 工具读取它们，这正是使用路径而非哈希值的全部意义。 代理运行期间不会删除它们，这是有意为之：其溢出内容已被清理的标记，正是此设计旨在避免的悬空引用，而且 Agent 可能在写入许多轮之后才会沿着路径访问。因此，单次运行中的保留量只受你省略的不同内容量限制——没有配额；如果一个很长的会话不断省略内容，数据就可能不断累积。

代理停止时，其溢出目录会被移除。每个代理进程都会在 token-optimizer-spill/ 下拥有自己的目录，因此停止一个代理绝不会清理其他代理仍在使用的路径；而代理停止的那一刻，也正是没有 Agent 会继续访问这些路径的时刻。如果一次运行结束时没有完成清理——例如收到终止信号或断电——该目录会留在操作系统的临时目录中，可以放心手动删除。关闭代理运行时，完全不会写入溢出数据。

四个开关及其取舍

在 7.1.0 之前，两个默认值为“开”的选项在这里都写成了“关”。这不是默认值发生了变化，而是与实际发布的代码不符：未设置值时始终表示启用；0、false、no 和 off 才会关闭它们。

TOKEN_OPTIMIZER_PROXY_NET_SAVING 默认关闭，因为知识块的设计目的就是增大请求：它只在写入缓存时计费一次，之后在整个会话中按 0.1 倍计费；对于较长的对话，这样做更划算，对于较短的对话则不然。开启此选项后，凡是发送知识块会导致发送给上游的字节数超过客户端提供的字节数，该轮就会丢弃知识块——线路传输量绝不会膨胀，但你也会失去前缀知识。

发布渠道

上面的每个开关都需要单独决定，直到开关多达十个。 渠道只需做一个决定：stable 是目前默认启用的渠道；每个更宽泛的渠道都包含更窄渠道中的所有内容，外加仍在测试的功能。

beta 会启用安装自修复；canary 会增加紧凑工具定义。这两项功能采用分阶段发布：由渠道决定是否启用。

更宽泛渠道所包含的其他功能都只能按请求启用，而且渠道不会替你开启任何功能——它只允许你提出请求。beta 允许请求启用输出整形器和共享知识图谱，canary 增加标识符替换和丢弃思考块，dev 则不设限制。这些功能要么会改变模型生成的内容，要么会强制使用代码原本会从其运行目录中推断出的答案；这类决定值得明确命名，而不是继承默认值：

TOKEN_OPTIMIZER_ROLLOUT_CHANNEL=canary TOKEN_OPTIMIZER_FEATURES=substitution

你已设置的变量仍优先于渠道。如果你的设置中有 TOKEN_OPTIMIZER_PROXY_SUBSTITUTE=1，那么即使在 stable 渠道中，替换功能也会启用，因为该开关在渠道出现之前就已发布，而切换渠道不应悄悄关闭你自己的配置。TOKEN_OPTIMIZER_DISABLE_FEATURES 是唯一不会被任何设置覆盖的选项。

无法识别的名称不会启用任何功能，无法读取的值也不会被视为“是”。两种情况都会报告出来，而不是自行猜测：

npm run doctor           # the channel and what it turned on
npm run doctor -- --features   # every feature and the reason for each

遥测开关

密钥不在此代码库中。它是公开的，而且该软件包已发布，因此提交密钥就意味着每个运行 npm view 的人都能获得它，并且无法从已安装的副本中轮换掉；发布工作流会将密钥写入压缩包。不含密钥的构建仍可正常工作，也仍会在本地汇总——只是无法上传，并且 install_doctor 会打印 packed without a key，而不是让用户以为选择加入后功能正在工作。

lossless 值得了解：它禁止所有会删除输出无法还原内容的转换——函数体、数组尾部、信号较弱的文本——同时保留可以还原的内容处理方式，例如空白、null 键、带时间戳列表的折叠重复行、重复的路径前缀，以及对请求中仍存在内容的反向引用。在代码库探索工作负载上的测量结果显示，它仍能删减 12.2%，且不会有任何有损省略。对于审查或审计工作，如果“模型能读取该路径”不是可接受的答案，这就是适用的设置。

预设是起点，不是上限：该库会在预设基础上叠加 CompressionOptions 对象，因此可以实现“积极压缩，但保留六条顶部行”这样的设置。

缓存前缀中的图谱

这里代价高昂的失败在于轮次，而非令牌。 本项目测得一种策略，尽管没有删减任何内容，却仅因增加轮次就造成了 1.471 倍的开销。因此，能避免一次无用轮次的发现，就能抵消大量上下文开销。

知识图谱中包含可避免这些问题的信息，但此前它只有两种方式传递给模型，而且都来得太迟或代价太高：一种是在 SessionStart 时根据开场任务文本一次性选定索引；另一种是 PreToolUse 提示，它在模型已经决定发起被提示的调用后才触发——因此，采纳提示反而要付出它原本想帮你省下的那一轮。

默认情况下，经过验证的项目发现会进入缓存前缀，预算为 2,000 个字符。代理会为一次对话固定所选内容块，以保留缓存；新会话可以选取新记录的发现。这也包括 Codex Responses API 路径。共享图谱会排除特定于项目的声明。设置 TOKEN_OPTIMIZER_PROXY_KNOWLEDGE=0 可停用注入。

添加的知识会单独报告为 injectedChars。它会增加输入令牌；要实现净成本改善，必须测量它能否避免足够多的工作。此前的正面对比结果并不能证明新启用的组合在所有工作负载上都能胜出。

图像

直到最近，图像块对所有这些处理都不可见——每个遍历器都只查找 block.text。这很重要，因为图像的 token 开销约为 width * height / 750，因此一张 1456x816 的截图大约需要 1,585 个 token，并且之后每一轮都会作为历史记录重新发送。驱动浏览器的 Agent 会反复发送同一帧，而现在这些重复内容会折叠为对请求中已有副本的引用。尺寸取自文件头，因此不依赖编解码器；出于同样的原因，我们特意不进行缩放。

相关性：默认使用 BM25，也可以选择模型

保留内容按 BM25 排名，因此不需要 Python、模型权重，也没有最低 RAM 要求；它的确定性也足以确保缓存前缀的字节保持稳定。不过，词法匹配有其局限：“数据库句柄用尽”与“连接池耗尽”没有共同 token；更糟的是，BM25 遇到这种情况时不会保持沉默——它会自信地选出错误的行。

因此，有两种改进方式。registerRanker 可以注册任意同步排序器。或者提供一个 SemanticEncoder，让代理预热嵌入缓存：在请求级异步预处理中，将候选单元批量嵌入，然后引擎像之前一样同步读取向量。我们提供了一个 onnxruntime-node 适配器，它会动态加载，因此该运行时绝不会成为此软件包的依赖项。

预处理未处理的内容会回退到 BM25，而不是计为零分——缺少向量是我们的疏漏，并非有关该行的证据。

该适配器通过真实推理验证，而非使用模拟： npm run verify:onnx 会针对一个带有真实权重的 2.3 KB ONNX 计算图运行九项检查，该计算图与用于生成它的生成器一同提交。它采用脚本而非 jest 测试，因为 onnxruntime 会在原生代码中检查 instanceof Float32Array，而 jest 的每个测试套件 VM realm 都有自己的类型化数组；CI 会安装可选运行时并运行该脚本。

**不作此声称：**嵌入模型在这些工作负载上的表现确实优于 BM25。我们证明了机制，但尚未进行测量。

压缩是整合，而非丢失

其他方案都会检查点并恢复你_已有的内容_——这会把会话中最稀缺的预算花在重放你已经付过代价的上下文上。

这里的选择是推导得出的，而不是类别列表：重新推导成本 × 不可恢复性 × 复用概率，并为死路和决策设定保底值，因为容易找到不等于容易再次找到。随后，恢复过程会根据具体情况调整——问题进行中、冷启动恢复或流程中恢复——并控制在经过测量的预算内：

**你进行到哪里了：**时钟偏差能解释这些 401 吗？ 已排除：令牌签名、客户端时钟漂移 未测试：服务器上的 NTP 偏差

这才是接续思路。摘要描述的只是思路本身。

了解你所问问题的渐进式披露

大型工具结果会变成一个根据会话的实际问题挑选的预览；系统会先解析输出的结构（测试报告、差异、堆栈跟踪、日志、JSON），而不是因为最前面的 40 行排在前面就直接选它们。

[selected against: "which shard fails?"]
--- failures ---
  FAILED  DBNetTests.BceOnRelu -- expected 0.0 got NaN
  FAILED  TftGradientFlow -- gradient did not reach the encoder
---- omitted: 1,760 lines of passing tests (expand 8bb6bd66) ----

每次截断都会标明，因为面对无提示的截断进行推理的模型，不会知道自己遗漏了内容。expand 会从内容寻址存储中提供内容——它绝不会重新运行你的测试套件；展开操作还会帮助改进下一次预览，并将你需要的内容提升到图中，因此第二次展开不会发生。

根据你自己的对话记录衡量提示词缓存的成本效益

服务商缓存会计费，且因服务商而异；缓存命中并不意味着输入 token 免费。例如，Anthropic 会公布独立的缓存读取和缓存写入倍率，而 OpenAI 和 Gemini 也有各自的缓存输入用量和定价规则。当客户端提供原生缓存字段时，Token Optimizer 会读取这些字段，并分别统计读取、写入、未缓存输入和输出。它绝不会把一家服务商的缓存倍率套用到另一家客户端。归因视图还能做到命中率无法做到的事：

! CLAUDE.md:2 has an embedded timestamp, invalidating everything after it
    about 329,421 tokens re-written per session

将成本归因到某一行，并按照它背后的内容定价。是否保持缓存温热，取决于根据你观测到的间隔计算出的预期收益，并按 TTL 层级分别判断；如果两个层级都不划算，它会明确说明。

根据结果而非任务大小决定模型路由

大家都根据任务类型猜测，却从不验证。此工具会读取每个任务片段使用的模型和结果——重试、错误、轮次——并计算两种错误的代价：使用能力过强的模型造成的浪费，以及使用能力不足的模型导致重试的成本。如果某个层级超过一半的任务片段需要重试，无论价格多低都会将其排除，因为四轮廉价调用若以失败告终，也算不上便宜。

将浪费检测转化为持续改进机制

一份报告只看一次就被遗忘。在这里，检测结果会转化为持久、可衡量、可逆的修复方案——跳过规则、组合触碰——再加上一份约 50-token 的会话启动简报，让浪费从一开始就不再发生。检测器既包含内置的基础规则，_也_包含从你项目自身历史中提取的模式；每项都会注明实际节省的成本：

generated/schema.d.ts: read in 9/9 sessions, never the source of a finding
    3,400 tokens/session; cost equivalent not priced; apply: waste_audit action="apply"

任何会修改你的文件的操作，都会先以差异形式提出，绝不会直接应用。

跨所有项目进行统一审计

fleet_audit 会根据实际测得的成本为整台机器上的项目排序，还能做到单项目扫描器无法做到的事：在一个项目中验证有效的修复方案，会提供给其他包含相同文件内容的项目，并附上该方案在测量时收集的证据。匹配依据是内容哈希，而非文件名。

它还会进行其他工具无法做到的自然实验——对比强制遵循规则的客户端与仅提供指示的客户端——并如实报告结果，无论结果如何，都会说明混杂因素。

离线学习过往错误中的经验

你已经为每次失败的工具调用付过费；这些调用都留在 Agent 自己的对话记录中。npx token-optimizer-learn 会在本地读取这些记录，将反复出现的失败归类，并把值得记住的内容写入该 Agent 已经会读取的说明文件——Claude Code 使用 CLAUDE.md，Codex 使用 AGENTS.md。

npx token-optimizer-learn                  # what it found, printed, nothing written
npx token-optimizer-learn --projects       # which projects have transcripts
npx token-optimizer-learn --since 14 --write

--agent <claude|codex|auto>、--project <path>、--since <days>、--max-sessions <n>、--json。未指定 --write 时不会写入任何内容；写入的内容会用标记括起来，因此再次运行时会替换自身的建议，而不是再追加一份副本——标记之外的内容绝不会被触碰。

有三件事它绝不会做，因为在真实语料中，每一件都曾导致生成一个看似可信、实际错误的规则：

• 它不会归咎于串联的命令行。 对话记录会记录命令行和退出代码，却不会说明 cd X && git grep a && ls b 中究竟哪条命令失败。因此，这类情况会被计为无法归因，并以数量报告，而不会归咎于第一条命令。
• 它不会把构建失败转化为建议。 测试或编译失败代表工作出了问题，并非需要避免的习惯。
• 它会说明无法读取的内容。 无法解析的对话记录和无法分类的失败都会以数量形式列出，因为它们限定了结果的可信范围。

它只读取本地文件——不联网、不上传——并会在写入任何建议文本之前将你的主目录路径替换为 ~。TOKEN_OPTIMIZER_LEARN_PLUGINS 接受以逗号分隔的模块说明符列表，用于添加其他 Agent 的格式；除非你明确指定，否则不会发现或导入任何内容。

信任：我们提供会拒绝工具调用的钩子

这比普通依赖要求更高，因此：

验证发布版本。 通过 npm provenance 从 CI 发布——npm audit signatures 可将构件与工作流运行和提交关联起来，无需信任我们。CHECKSUMS.sha256 也会随附，供离线校验。

如果看起来什么都没发生，很可能是生命周期包未安装。 MCP 服务进程无法修改启动它的宿主，而 npm 11 会通过 allow-scripts 限制生命周期脚本。请安装下方为你的客户端列出的原生插件／钩子包；只添加 MCP 服务只能让模型获得工具，无法在执行前否决。对于旧版全局 Claude Code 安装，可通过一行命令恢复：

npx token-optimizer-install     # wire Claude Code hooks
npx token-optimizer-doctor      # prove the Claude hooks work

检查它是否有效，而不是检查文件是否存在。

npx token-optimizer-doctor      # or npm run doctor, from a clone

它会向 真实 钩子二进制发送合成负载，并断言大容量读取会被拒绝，小容量读取则不会。对于这个项目曾经发布的那个确切错误，清单检查也会放行：插件已连接、在 /mcp 中可见，却什么也没保存。每个失败项都会说明对应的修复方法。

每次拒绝都附带自己的关闭开关。 隐藏禁用方式的强制机制带有胁迫性，而需要它的人正处于被拒绝的过程中，不会去读 README：

auth.ts is 91 KB. Call smart_read instead.
(Not what you wanted? TOKEN_OPTIMIZER_MODE=off disables enforcement.)

卸载操作精确无误。 安装程序会记录其写入的每个文件及其哈希值。卸载时只会移除仍与记录相符的文件；你之后编辑过的文件会保留，并列出名称。绝不会触碰你自己的钩子，也绝不会重写你的 settings.json——我们会合并配置。

npm run uninstall-hooks              # show the plan; changes nothing
npm run uninstall-hooks -- --apply   # carry it out

它将直接节省与因果图证据分开

这个领域里的每种工具都会根据自身假设报告“节省的 token 数”。这个数字不可能出错，因为没有任何东西会核验它。

对于优化器结果，它会记录物化前状态以及实际返回给客户端的文本，然后减去所有相关的展开响应。原生图替换反事实仍会标记为建模结果，不计入主要摘要数字。

对于图谱更广泛的主张——已交付的知识是否避免了后续重新读取——这属于因果问题，因此我们会进行随机留出实验。在一部分文件触碰事件中静默地不提供知识，并按文件分层；实验效果即两组之间下游读取量的差异。在实验能够提供充分依据之前，该效果不会计入合并净值，页面也会明确告知你：

图谱目前尚未收回成本

只能报告好消息的工具不是真正在报告。我们始终遵循同一原则：无法测量的节省会显示为未知，绝不会显示为零，也不会显示为 $0.00——因为把“目前无法判断”显示成“没有节省”属于悄无声息的假阴性，而且金额会被转述给其他人。

它可在所有平台运行，并标明所属层级

层级是协议保证，而非偏好：

• 生命周期延续： Claude Code、Codex、GitHub Copilot CLI、Gemini CLI、 Qwen Code 和 Cursor。原生路由／捕获／交付，以及一次针对当前活动模型的补全反思。
• 原生观测： Cline、OpenCode、Kilo 和 Windsurf。原生路由／捕获／交付；语义写入由当前活动模型执行。
• MCP + 规则： Roo Code、Zed、Amp、Continue、Crush 和 Droid。可通过 MCP 查看活动并使用显式图谱工具；不声称能控制隐藏的内置调用。

具体支持的功能仍有差异。例如，能够在大型读取到达模型前替换它的协议，比只能观测该读取的协议提供更强的 token 保证。生成的注册表、适配器、仪表板和认证报告都读取同一份能力来源，因此这些声明不会各自偏离。

每种配置格式都已根据对应客户端发布的文档核实，来源 URL 记录在其 README 中。

这里的所有内容均已验证，你可以实际运行

npm run verify:all

这些并非装饰。它们发现了六个会悄无声息失败的客户端配置、一个会破坏用户钩子的安装程序、一个导致强制执行机制无法识别自身一半拒绝行为的 Windows 路径错误，以及一个只打印计划却什么也没删除的卸载程序。

OrcaRouter

OrcaRouter 是一个兼容 OpenAI 的 AI 网关，可通过一个端点路由多个提供商。此处已将其接入，作为优化器自身模型调用的一等提供商，并提供两种独立的接入方式：

两种方式都会生成相同的普通 OrcaRouter API 密钥；无论使用哪一种，下游行为都完全相同——包括 Bearer 标头、端点、模型发现和 401 恢复。UI 中有意不将两种方式合并：同一个按钮有时要求输入密钥、有时打开浏览器，会让退出登录、重新认证和获取支持变得更复杂。

配置

打开仪表板（npm run dashboard）并使用 OrcaRouter 卡片，或通过环境变量进行配置：

export ORCAROUTER_API_KEY=sk-orca-…          # the API-key choice
export TOKEN_OPTIMIZER_ORCA_MODEL=orcarouter/auto   # which model the optimizer calls

也可以改用账号连接；签发的密钥会以仅所有者可访问的权限写入 $TOKEN_OPTIMIZER_HOME（默认为 ~/.token-optimizer）：

token-optimizer-route orcarouter --connect   # opens a browser, then stores the key
token-optimizer-route orcarouter --status    # shows a redacted status and the origins in use
token-optimizer-route orcarouter --clear     # removes the stored key

通过 PKCE 签发的密钥是持久密钥，不是刷新令牌。 OrcaRouter 返回的是长期有效的密钥，而不是访问令牌／刷新令牌对，因此密钥会一直重复使用，直到你在 https://www.orcarouter.ai/console/authorized-apps 撤销它——无需安排刷新；每次启动都重新授权会触及账号每 24 小时最多创建十个密钥的限制。当中继返回 401 时，系统会将发出被拒请求的确切账号和凭据代次标记为需要重新认证，且不会尝试刷新。可刷新的 OAuth 令牌会自动轮换；OrcaRouter 这类持久密钥授权会一直重复使用，直到提供商撤销为止。

来源

身份验证和推理使用不同的主机，二者互不派生：

https://api.orcarouter.ai/v1/auth/keys 会返回 404——身份验证端点不在中继服务下。可自托管的安装可以设置 ORCA_BASE_URL 以使用单一共享来源，也可以分别设置 ORCA_AUTH_BASE_URL / ORCA_API_BASE_URL；显式值优先，且仅允许回环地址使用明文 HTTP。

模型

模型控件是一个列表框，通过在已配置的来源调用 GET /v1/models 构建，并使用你自己的密钥，因此列表中的模型确实可供你的工作区调用。模型 ID 保留其 vendor/model 命名空间。选项会按入口进行筛选；未声明某项能力的模型不会显示，而不是先显示再遭拒：

• 文本聊天——使用 ?capability=chat，且模型必须声明 openai、anthropic、gemini 或 openai-response 端点类型；
• 多模态——要求相同，此外还必须在 architecture.input_modalities 中明确列出所发送的模态（未声明的能力会被安全地视为不支持）；
• 嵌入、图像、视频和重排——严格匹配 embeddings、image-generation、openai-video 和 jina-rerank 端点类型。

如果发现过程失败，则会显示一个较短的已验证备用列表并标注为备用（openai/gpt-5.5、anthropic/claude-opus-4.8、google/gemini-3.5-flash、deepseek/deepseek-v4-pro、orcarouter/auto），并保留其上下文、模态和推理力度元数据。成功获取的实时结果具有权威性，绝不会与备用列表混合。

文本入口	切换到图像后的状态

第二张截图是在将入口切换到图像后拍摄的：仅支持文本的选项已清除，只保留目录条目中声明了图像输入的模型。

npm run evidence:orcarouter 会重新生成该卡片的截图和断言，并写入 orca-evidence/（不跟踪——这是运行产物）。本 README 链接的副本位于 docs/media/orcarouter/，与其他仪表板截图放在一起。交付检查会读取 orca-evidence/，并拒绝包含该目录的补丁，因此此目录会被忽略而不是提交。

客观比较

安装

每个客户端都会启动同一个 stdio 服务——npx -y @ooples/token-optimizer-mcp@latest—— 但它们允许 hook 执行 的操作各不相同，而这正是整个产品的核心区别。拥有 执行前否决功能的客户端可以拒绝浪费的调用；没有此功能的客户端则只能发出提示。 下方如实列出了两者。

全部 16 个客户端的现成配置都位于 integrations/，由同一来源生成，并通过 npm run verify:clients 验证。 完整矩阵：docs/CLIENT_SUPPORT.md。

每个 MCP 连接还会在其 initialize 响应中收到具备能力感知能力的强制路由 说明。这为所有客户端提供了通用的常驻策略，但只有具备原生工具调用前置接口的 10 个客户端 才能硬性否决浪费的内置调用；要实际执行拦截，请安装它们的生命周期配置包。

强制执行层 — 拒绝浪费调用

这十个客户端都提供执行前钩子。它们打包的生命周期套件共享一个具备能力感知的决策引擎，默认模式为 assist：路由、检索、捕获和收集全部开启，不会拒绝调用。如果要否决开销较大的内置调用，请设置 TOKEN_OPTIMIZER_MODE=enforce；设置为 off 则可完全禁用这些钩子。

规则层 — 宿主没有否决 API 时的强制路由

Roo Code、Zed、Amp、Continue、Crush 和 Droid 没有提供打包的执行前桥接，无法安全地否决内置调用。它们生成的常驻规则会在可见精确 MCP 架构时强制采用优化路由；如果无法获取架构，则会回退到有界的原生操作。各集成目录都包含 MCP 配置和规则文件，路径为对应宿主文档所述的路径。

这些路径经过核验，并非凭空假设。 对照各客户端发布的文档进行核验后发现，有六项配置即使能成功安装，也始终不会加载 — 其中包括 Kilo，它的架构与其他客户端采用的 mcpServers 惯例毫无关联。惯例不是架构。

Codex

1. 添加 MCP 服务或原生插件

为获得最佳体验，请安装 Codex 插件。它打包了 MCP 服务、令牌优化技能、会话指南和大规模读取钩子：

codex plugin marketplace add ooples/token-optimizer-mcp
codex plugin add token-optimizer@token-optimizer

通过 /hooks 检查并信任打包的钩子，然后开始新对话。如果你更倾向于仅安装 MCP，请使用：

codex mcp add token-optimizer -- npx -y @ooples/token-optimizer-mcp@latest

在 Windows 上，如果 PowerShell 阻止了 codex.ps1 启动器，请直接使用命令启动器：

codex.cmd mcp add token-optimizer -- npx -y @ooples/token-optimizer-mcp@latest

这会将服务写入 ~/.codex/config.toml。同一主机上的 Codex CLI、Codex IDE 扩展和 Codex 应用会共用此配置。

2. 验证安装

codex mcp get token-optimizer
codex mcp list

安装后，请开始新的 Codex 对话，以便发现新工具。在交互式 CLI 会话中，/mcp 会显示当前对话可用的工具。

3. 添加优化指导和钩子

插件会自动提供这两项。若仅安装 MCP，请将 integrations/AGENTS.md 中的指导添加到项目级或全局 AGENTS.md。在 integrations/codex/hooks 下也提供了可直接使用的独立钩子；将其 hooks.json 合并到 ~/.codex/hooks.json，把脚本复制到 ~/.codex/hooks/，然后使用 /hooks 检查一次。

Codex 钩子会在 SessionStart 注入指导。在 TOKEN_OPTIMIZER_MODE=enforce 模式下，如果捆绑的 MCP 有精确替代方案，它会阻止开销较大的原生操作，包括像 cat 或 Get-Content 这样单次且无歧义的代码模式 shell 调用；多操作编排仍仅提供建议，以免丢弃无关工作；如果 MCP 不可用，对同一目标的第二次尝试会放行。默认模式为 assist，保留检索和捕获功能，但从不否决；TOKEN_OPTIMIZER_MODE=advise 会添加路由建议，但不会否决；off 则会禁用钩子。AGENTS.md/技能指导仍然很重要。

如果你希望指令块更短：

## Token optimization

Use the token-optimizer MCP for large or repeated reads:

- `smart_read` for files over roughly 400 lines and for files already read once.
- `smart_glob`/`smart_grep` for large search results.
- `optimize_text` to store bulky text outside the model context.
- `get_optimization_report` when the user asks for token or compression stats.

Use normal tools for small, one-off operations.

有关钩子信任、匹配和工具覆盖范围的详细信息，请参阅最新的 Codex 钩子文档。

等效的手动 Codex 配置

如果你更愿意自行编辑 ~/.codex/config.toml：

[mcp_servers.token-optimizer]
command = "npx"
args = ["-y", "@ooples/token-optimizer-mcp@latest"]

# Optional: keep the cache in a custom location.
# env = { TOKEN_OPTIMIZER_CACHE_DIR = "/absolute/path/to/cache" }

Claude Code

请安装插件，而不是裸 MCP 服务。 插件是唯一默认执行优化的安装方式；仅添加 MCP 服务只会向模型提供一组它可以完全不调用的工具。

/plugin marketplace add ooples/token-optimizer-mcp
/plugin install token-optimizer@token-optimizer
/reload-plugins

安装到此为止。无需配置，也无需启用任何标志。

立即获得的功能

从下一次会话的第一条消息开始，开销较大的内置调用会被拒绝并重定向到优化后的等效工具：

重新读取的情况通常是收益最大的单项优化，也最容易被忽略：在一次会话中反复读取 15 次的 5 KB 配置文件，成本远高于只读取一次的 200 KB 文件。基于大小的规则永远无法捕获这种情况。

不会让你陷入困境

以下三项特性均经过测试：

• 出错时放行。 优化器中的任何错误——无效负载、无法读取文件、意外异常——都会放行原始调用，效果与未安装插件完全相同。
• 打破循环。 对每个目标最多拒绝一次。再次尝试时会放行。因此，如果 MCP 服务缺失或配置错误，每个文件只会浪费一个回合，并会自动恢复，无需人工干预。
• 不拦截低成本调用。 小文件、分页读取、git log | head 和二进制文件路径都不会受到影响。

调低强制程度

只需更改一个变量，无需重新安装：

TOKEN_OPTIMIZER_MODE=advise   # nudge instead of refuse (the pre-5.2 behaviour)
TOKEN_OPTIMIZER_MODE=off      # disable the hooks entirely
TOKEN_OPTIMIZER_LARGE_READ_BYTES=51200   # raise the "large file" threshold

仅安装 MCP 服务（不推荐）

如果你只想使用工具，不启用强制执行：

claude mcp add --transport stdio --scope user token-optimizer -- \
  npx -y @ooples/token-optimizer-mcp@latest

使用 claude mcp get token-optimizer 验证，或在 Claude Code 中运行 /mcp。然后将 integrations/AGENTS.md 中的建议添加到你的 CLAUDE.md 中——但请注意，上下文文件中的指导仅供参考，而且模型经常会忽略它。

安装软件包不会更改你机器上的任何内容。钩子以及托管的 Claude Code、Codex 和 OpenCode 命令都需要通过一条明确的命令接入：

npm install -g @ooples/token-optimizer-mcp@latest
token-optimizer-install

只有 token-optimizer-install 会编辑 ~/.claude/settings.json；安装过程本身只会打印它要写入的路径，然后退出。它添加的钩子会匹配这台机器上每个项目中的几乎所有工具调用，因此这不应成为 npm install 的副作用。运行 token-optimizer-uninstall 可撤销更改；除非传入 --apply，否则它只会试运行。若要在容器映像或配置脚本中启用此功能，请在安装前设置 TOKEN_OPTIMIZER_AUTO_INSTALL=1。打开新的 shell 以启用托管的 CLI 命令，或直接使用 token-optimizer-run。请参阅钩子安装指南。

GitHub Copilot CLI

1. 添加 MCP 服务

对于当前版本的 Copilot CLI：

copilot mcp add token-optimizer -- npx -y @ooples/token-optimizer-mcp@latest

如果你的 Copilot CLI 尚未提供 copilot mcp，请将以下内容保存为 ~/.copilot/mcp-config.json：

{
  "mcpServers": {
    "token-optimizer": {
      "type": "local",
      "command": "npx",
      "args": ["-y", "@ooples/token-optimizer-mcp@latest"],
      "tools": ["*"]
    }
  }
}

可在 integrations/copilot/mcp-config.json 获取现成的配置文件。

2. 验证安装

copilot mcp get token-optimizer
copilot mcp list

在交互式 Copilot 会话中，运行 /mcp show token-optimizer 可查看连接状态和可用工具。

3. 添加优化指导和钩子

将 integrations/AGENTS.md 保留为仓库中的 AGENTS.md，或将相同的指导调整后写入 .github/copilot-instructions.md。

如需原生生命周期集成，请使用附带的命令安装钩子。该命令会复制入口文件，并将共享核心与其一同组合；普通的 cp -r 无法做到这一点：软件包只附带一份核心代码，而非十份随附副本。

npx -y @ooples/token-optimizer-mcp@latest token-optimizer-install-client --client copilot

默认情况下，它会写入 .github/hooks/；--check 会报告将要写入的内容，但不会实际写入。--dest <dir> 会将文件写入其他目录，但不会更改任何客户端配置，因此该目录必须是客户端自身配置已读取的目录——这也是为什么需要它的客户端（在运行时解析该目录的 Gemini、Qwen 和 Codex 插件）都要求这样设置。

这些钩子会在 sessionStart 时注入优化指导。在 TOKEN_OPTIMIZER_MODE=enforce 模式下，它们会拒绝内置的大型 view，让 Copilot 重试并使用 smart_read；默认的 assist 模式则不会干预调用。局部读取和小于 25 KB 的文件始终会原样通过；TOKEN_OPTIMIZER_MODE=advise 则只提供建议，不会否决调用。仓库级钩子无需覆盖用户级文件即可使用；也可以将全局钩子放在 ~/.copilot/hooks/ 中，并相应调整其中的脚本路径。

更改钩子文件后，请重启 Copilot CLI。请参阅 GitHub 官方的 MCP 设置指南和钩子参考。

Gemini CLI

1. 添加 MCP 服务

直接在用户级配置中添加 Token Optimizer：

gemini mcp add --scope user token-optimizer npx -y @ooples/token-optimizer-mcp@latest

或者，将此仓库安装为 Gemini 扩展，以便将 MCP 配置和 GEMINI.md 指导打包在一起：

gemini extensions install https://github.com/ooples/token-optimizer-mcp --auto-update

2. 验证安装

gemini mcp list
gemini extensions list

在 Gemini CLI 中运行 /mcp 以检查连接。安装或更新扩展后，请重启 Gemini CLI。

3. 添加优化指导和钩子

直接使用 MCP 的用户应将 GEMINI.md 复制到项目中，或将其中的规则合并到现有的 GEMINI.md 中。扩展用户会自动获得该上下文文件和原生钩子。

扩展的 SessionStart 钩子会注入优化指导。其 AfterTool 钩子会检测超过 25 KB 的完整文件 read_file 结果，并建议使用 smart_read。要让 Gemini 自动将这些大型结果替换为令牌优化器的尾部工具调用，请将扩展设置 Automatic large-read routing 配置为 true：

gemini extensions config token-optimizer

自动路由使用 Gemini 原生的 tailToolCallRequest：在结果到达模型之前，smart_read 的结果会替换内置读取结果。部分读取保持不变。安装、更新或重新配置扩展后，请重启 Gemini CLI。请参阅官方 Gemini MCP 指南、扩展指南和钩子参考。

OpenCode

1. 添加 MCP 服务

在项目中创建或更新 opencode.json：

{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "token-optimizer": {
      "type": "local",
      "command": ["npx", "-y", "@ooples/token-optimizer-mcp@latest"],
      "enabled": true
    }
  },
  "instructions": ["./AGENTS.md"]
}

对于全局安装，请将相同的 mcp 条目合并到 ~/.config/opencode/opencode.json 中。

2. 验证安装

opencode mcp list

输出会显示已配置的服务及其连接状态。

3. 添加优化指导和本地插件

将 integrations/AGENTS.md 复制到项目中并命名为 AGENTS.md；上方的 instructions 条目会加载此文件。然后复制现成的本地插件：

mkdir -p .opencode/plugins
cp integrations/opencode/.opencode/plugins/token-optimizer.js .opencode/plugins/

New-Item -ItemType Directory -Force .opencode/plugins | Out-Null
Copy-Item integrations/opencode/.opencode/plugins/token-optimizer.js .opencode/plugins/

对于 OpenCode 1.3.3 或更早版本（请检查 opencode --version），请改为将 integrations/opencode/legacy/.opencode/plugins/token-optimizer.js 复制到同一位置。这些版本会将插件文件的每个导出项都作为插件函数调用，因此无法加载当前文件；当前文件的默认导出是 OpenCode 2.x 所需的对象。两个文件名称相同，因此复制一个文件会替换另一个。

该插件会在 OpenCode 的压缩提示词中保留 Token Optimizer 的使用状态。在 TOKEN_OPTIMIZER_MODE=enforce 模式下，其 tool.execute.before 钩子会拒绝超过 25 KB 的完整文件读取，并引导 Agent 使用 smart_read；默认的 assist 模式则允许读取。小型和部分读取始终正常通过，而 TOKEN_OPTIMIZER_MODE=advise 会提供非阻断式指导。添加插件后，请重启 OpenCode。请参阅官方 OpenCode MCP 指南和插件钩子指南。

通用 MCP 配置

任何支持 stdio 的 MCP 客户端都可以通过以下方式启动 Token Optimizer：

{
  "mcpServers": {
    "token-optimizer": {
      "command": "npx",
      "args": ["-y", "@ooples/token-optimizer-mcp@latest"]
    }
  }
}

还提供了适用于 Claude Desktop、Codex、Gemini CLI、OpenCode和 GitHub Copilot 的现成集成文件。

使用方法

通常，你只需用自然语言向 Agent 提出请求，即可使用 Token Optimizer：

Use token-optimizer smart_read for the large server file, then use it again
after the edit so only the diff comes back.

Cache this API response with optimize_text under the key customer-schema,
then retrieve it only if we need the full payload again.

Show my token savings with get_optimization_report.

对于支持直接调用 MCP 工具的客户端，核心输入是小型 JSON 对象：

{
  "tool": "smart_read",
  "arguments": {
    "path": "/absolute/path/to/large-file.ts"
  }
}

{
  "tool": "optimize_text",
  "arguments": {
    "text": "A large response, log, document, or generated artifact...",
    "key": "stable-reference-key",
    "quality": 11
  }
}

{
  "tool": "get_optimization_report",
  "arguments": {
    "topN": 10
  }
}

了解压缩统计信息

每次调用 optimize_text 都会返回测量数据。此示例使用了刻意重复的内容，以便清楚展示每个字段；这不是基准测试：

{
  "success": true,
  "key": "customer-schema",
  "originalTokens": 4180,
  "compressedTokens": 72,
  "tokensSaved": 4108,
  "percentSaved": 99.55,
  "cached": true,
  "compressionUsed": true
}

get_optimization_report 使用与仪表板相同的版本化测量规范，并汇总符合条件的操作，包括：

• 预览内容的总缩减量、关联的扩展扣减量，以及净减少的传输量；
• 实际返回的上下文量和净缩减百分比；
• 跟踪的已验证操作，不包括旧版声明和工具报告的声明；
• 按操作/工具、钩子阶段和 MCP 服务划分的明细；
• 可选的日期范围和会话筛选条件。

这两个工具名称相似，但用途不同：

如果目标是缩短提示词，请优先使用 optimize_text。只有在确实需要按字节压缩时，才使用 compress_text。

包含的内容

详细的工具输入和示例请参阅 docs/TOOLS.md。

要求和数据

• Node.js 22 或更高版本
• npm 9 或更高版本
• 支持 stdio 传输的 MCP 客户端

默认本地数据位置包括：

• 缓存：~/.token-optimizer-cache/
• 分析数据：~/.token-optimizer-mcp/analytics.db
• 会话和配置：~/.token-optimizer/

设置 TOKEN_OPTIMIZER_CACHE_DIR 可覆盖缓存位置。

验证它、检查它、移除它

这会安装一些会拒绝你的工具调用的钩子。相比普通依赖，这需要你承担更大的风险，因此这里提供了检查和撤销所需的一切。

验证发布内容是否可信。 该软件包通过 npm CI 发布，并带有来源证明，用于签署一份证明，将制品与运行该工作流的记录以及构建它的提交绑定起来：

npm audit signatures

无需信任我们即可完成验证。每个 GitHub 发布版本都附有 CHECKSUMS.sha256，可供离线检查（sha256sum -c CHECKSUMS.sha256）——适用于镜像站，但安全性较弱：它与被校验的内容共享同一个信任根。

检查它是否确实能正常工作。 检查的不只是文件是否就位，而是它_能否正常工作_：

npm run doctor

它会将合成载荷传递给真正的钩子二进制文件，并断言大型读取会被拒绝、小型读取不会；会话启动时会输出策略；图目录可写；MCP 服务能够启动并列出其工具。每项故障都会说明对应的修复方法。此外，还有一个 install_doctor MCP 工具。

立即关闭强制执行。 每次拒绝操作都会显示这条信息，因此你无需回到这里查找：

TOKEN_OPTIMIZER_MODE=off      # no enforcement, no hooks
TOKEN_OPTIMIZER_MODE=advise   # suggestions only, nothing is ever denied

移除它。 安装程序会记录它写入的每个文件及其哈希值，因此可以精确移除，而非尽力而为：

npm run uninstall-hooks              # show the plan; changes nothing
npm run uninstall-hooks -- --apply   # carry it out

它只会移除仍与我们写入的内容一致的文件。任何你之后编辑过的内容都会保留并列出名称，因为移除这些内容会破坏你的工作，而悄无声息地移除则更糟。你自行添加的钩子不会列入清单，也绝不会被触碰。我们添加的配置条目会列出来供你移除——我们不会改写你的 settings.json。

技术参考

以下详细的操作资料专为希望了解完整工具范围、钩子流程、性能控制、分析和故障排查行为的用户保留。

完整工具参考（共 74 个）

核心缓存与优化（8 个工具）

// Cache large content to remove it from context window
optimize_text({
  text: 'Large API response or file content...',
  key: 'api-response-key',
  quality: 11,
});
// Result: 60-90% token reduction

智能文件操作（10 个工具）

// Read a file with automatic caching
smart_read({ path: '/path/to/file.ts' });
// First read: full content
// Subsequent reads: only diff (80% reduction)

// Fetch API with automatic caching
smart_api_fetch({
  method: 'GET',
  url: 'https://api.example.com/data',
  ttl: 300,
});
// Cached responses: 95% token reduction

构建与测试操作（10 个工具）

// Run tests with caching
smart_test({
  onlyChanged: true, // Only test changed files
  coverage: true,
});

高级缓存（10 个工具）

// Configure multi-tier cache
smart_cache({
  operation: 'configure',
  evictionStrategy: 'LRU',
  l1MaxSize: 1000,
  l2MaxSize: 10000,
});

监控与仪表板（7 个工具）

// Create an alert
alert_manager({
  operation: 'create-alert',
  alertName: 'high-cpu-usage',
  channels: ['slack', 'email'],
  threshold: { type: 'above', value: 80 },
});

// View session token usage
get_session_stats({});
// Result: Detailed breakdown of token usage by tool

智能与摘要（6 个工具）

令牌分析（5 个工具）

上下文状态与存储（2 个工具）

架构与全局钩子

原生客户端生命周期覆盖

MCP 服务在所有客户端中都相同，但生命周期 API 并不相同。该代码库提供客户端原生适配器，而不是把 Claude 事件名称照搬到会静默忽略这些事件的工具中。

默认模式为 assist：路由、检索、捕获和收集均已启用，且绝不会拒绝操作。两个独立测试框架测得，这是我们的最佳设置——在 THOL 上，assist 在 14.4 轮中得分为 0.971，而对照组在 16.2 轮中得分为 0.969；enforce 在 20.3 轮中得分为 0.960，每项任务的成本是对照组的 1.471 倍（17 项任务的中位数；仅有 2 项任务成本更低）。将 TOKEN_OPTIMIZER_MODE=enforce 设为上述拒绝模式，该模式使用 25,600 字节的阈值；可通过 TOKEN_OPTIMIZER_LARGE_READ_BYTES 覆盖此值；使用 TOKEN_OPTIMIZER_MODE=advise 启用路由建议而不进行拦截，或使用 TOKEN_OPTIMIZER_MODE=off 禁用生命周期集成。部分读取始终会放行，因为它们可能已经比完整的缓存读取更高效；在 enforce 模式下，允许重试一次，以免 MCP 服务故障导致工作永久受阻。

分析工作流与存储

// Get per-hook analytics
get_hook_analytics({
  startDate: '2025-01-01T00:00:00Z',
  endDate: '2025-12-31T23:59:59Z',
});
// Result: Shows which hooks consume the most tokens

// Get per-action analytics
get_action_analytics({});
// Result: Shows which tools use the most tokens

// Export analytics as CSV
export_analytics({
  format: 'csv',
  hookPhase: 'PreToolUse',
});
// Result: CSV export filtered by PreToolUse hook

全局钩子系统（7 阶段优化）

这条完整的七阶段管线适用于可选的 Claude Code 全局钩子安装。Codex、Copilot、Gemini 和 OpenCode 使用上述更精简的原生适配器，因为它们的事件名称、载荷和结果替换能力各不相同。

安装全局钩子后，token-optimizer-mcp 会自动在每次工具调用时运行：

┌─────────────────────────────────────────────────────────────┐
│ Phase 1: PreToolUse - Tool Replacement                      │
│ ├─ Read   → smart_read   (80% token reduction)             │
│ ├─ Grep   → smart_grep   (80% token reduction)             │
│ └─ Glob   → smart_glob   (75% token reduction)             │
└─────────────────────────────────────────────────────────────┘
                          ↓
┌─────────────────────────────────────────────────────────────┐
│ Phase 2: Input Validation - Cache Lookups                   │
│ └─ get_cached checks if operation was already done          │
└─────────────────────────────────────────────────────────────┘
                          ↓
┌─────────────────────────────────────────────────────────────┐
│ Phase 3: PostToolUse - Output Optimization                  │
│ ├─ optimize_text for large outputs                          │
│ └─ compress_text for repeated content                       │
└─────────────────────────────────────────────────────────────┘
                          ↓
┌─────────────────────────────────────────────────────────────┐
│ Phase 4: Session Tracking                                   │
│ └─ Log all operations to operations-{sessionId}.csv         │
└─────────────────────────────────────────────────────────────┘
                          ↓
┌─────────────────────────────────────────────────────────────┐
│ Phase 5: UserPromptSubmit - Prompt Optimization             │
│ └─ Optimize user prompts before sending to API              │
└─────────────────────────────────────────────────────────────┘
                          ↓
┌─────────────────────────────────────────────────────────────┐
│ Phase 6: PreCompact - Pre-Compaction Optimization           │
│ └─ Optimize before Claude Code compacts the conversation    │
└─────────────────────────────────────────────────────────────┘
                          ↓
┌─────────────────────────────────────────────────────────────┐
│ Phase 7: Metrics & Reporting                                │
│ └─ Track token reduction metrics and generate reports       │
└─────────────────────────────────────────────────────────────┘

性能证据

工具描述中的减少目标是设计目标，并非生产环境测量结果。它们不会计入已验证账目。使用仪表板或 get_optimization_report 查看请求级测量结果，并使用 npm run dashboard:audit-savings 检查符合条件和被排除的行。 我们不宣称存在通用的美元价值：只有在有效费率反映你自己的提供商、模型、缓存、路由、套餐、层级和额度时，才配置该费率。

使用示例

基本缓存

// Cache large content to remove from context window
const result = await optimize_text({
  text: 'Large API response or file content...',
  key: 'cache-key',
  quality: 11,
});
// Result: Original tokens removed, only cache key remains (~50 tokens)

// Retrieve later
const cached = await get_cached({ key: 'cache-key' });
// Result: Full original content restored

智能文件读取

// First read: full content
await smart_read({ path: '/src/app.ts' });

// Subsequent reads: only changes (80% reduction)
await smart_read({ path: '/src/app.ts' });

API 缓存

// First request: fetch and cache
await smart_api_fetch({
  method: 'GET',
  url: 'https://api.example.com/data',
  ttl: 300,
});

// Subsequent requests: cached (95% reduction)
await smart_api_fetch({
  method: 'GET',
  url: 'https://api.example.com/data',
});

会话分析

// View token usage for current session
await get_session_stats({});
// Result: Breakdown by tool, operation, and savings

// Analyze entire project
await analyze_project_tokens({
  projectPath: '/path/to/project',
});
// Result: Cost estimation and optimization opportunities

技术栈

• 运行时：Node.js 22+
• 语言：TypeScript
• 数据库：SQLite（better-sqlite3）
• Token 计数：tiktoken（GPT-4 分词器）
• 压缩：Brotli（Node.js 内置）
• 缓存：多层 LRU/LFU/FIFO 缓存
• 协议：MCP SDK（@modelcontextprotocol/sdk）

支持的 AI 工具

Token Optimizer 适用于支持 stdio 的 MCP 客户端，并提供以下工具的一方设置指南：

• OpenAI Codex - 直接配置 MCP，或使用随附的插件、技能和钩子
• Claude Code - 直接配置 MCP，或使用随附的插件、技能和钩子
• GitHub Copilot CLI - MCP 配置、AGENTS.md 指南和仓库钩子
• Google Gemini CLI - 直接配置 MCP，或使用随附的上下文与钩子扩展
• OpenCode - 本地 MCP 配置、AGENTS.md 说明和压缩插件
• Claude Desktop、Cursor、Cline 和 Windsurf - 标准 MCP JSON 配置

请参阅安装，了解支持的命令和配置文件。

性能特征

• 压缩比：典型为 2-4 倍（重复内容最高可达 82 倍）
• 上下文窗口节省：所有操作平均为 60-90%
• 缓存命中率：典型使用中 >80%
• 操作开销：缓存操作 <10ms（已从 50-70ms 优化）
• 压缩速度：每 KB 文本约 1ms
• 钩子开销：每次操作 <10ms（通过内存优化提升 7 倍）

性能优化

PowerShell 钩子经过优化，将开销从 50-70ms 降至 <10ms，具体方式如下：

• 内存中的会话状态：会话数据保存在内存中，而非每次操作都进行磁盘 I/O
• 批量写入日志：操作日志先缓存在缓冲区，每 5 秒或每 100 次操作刷新一次
• 延迟持久化：仅在必要时写入磁盘（会话结束、优化、生成报告）

环境变量

使用以下环境变量控制钩子行为：

默认情况下，MCP 服务会公开包含 19 个工具的核心目录，避免工具架构占用模型上下文的大量空间。在启动服务前设置 TOKEN_OPTIMIZER_TOOL_PROFILE=full，即可公开全部 104 个专业工具。TOKEN_OPTIMIZER_TOOL_PROFILE=core 是明确指定默认配置的写法。实时图谱捕获使用 TOKEN_OPTIMIZER_TOOL_PROFILE=continuity，此配置仅公开捕获和查询工具。扩展的 cognitive 配置还会添加检查点、结果和回执证明。原生令牌审计测得，continuity 启动时消耗 480 个令牌，扩展 cognitive 消耗 694 个，core 消耗 4,815 个，full 消耗 30,125 个。有状态的使用方通常不会收到任何 MCP 工具：宿主在操作前通过客户端生命周期通道仅传递所选的胶囊。其他已启用的 MCP 服务会独立添加各自的架构。

对于以文件为重点的工作，可选择 TOKEN_OPTIMIZER_TOOL_PROFILE=files，以公开七个工具：smart_read、smart_write、smart_edit、smart_glob、smart_grep、get_cached 和 expand。此配置保留文件和缓存检索功能，但不包含 Wiki、审计和会话工具。它可与压缩代理配合使用；有关 full-files 配置和实测权衡，请参阅实时对比运行器。

当前经过加固的跨 CLI 冒烟测试不符合要求。在最终的 Codex 到 Claude 对抗性测试对中，两位后继者都给出了正确结果，运行时胶囊也在附带准确的提供方模型证明且使用方 MCP 工具数为零的情况下成功传递；但运行时多消耗了 5.383% 的令牌，延迟也增加了 41.758%。反向运行时测试因 Claude 提供方配额而受阻，Antigravity 1.1.11 则要求先进行账户身份验证，才能运行 Gemini 模型。这些已签名结果使发布结论仍为 insufficient；它们证明了来源追踪有效且系统会安全地拒绝操作，但不能证明效果已得到充分验证，也不能证明其普遍优越。

可替代该冒烟测试、达到正式评估要求的协议有意设计得更大：54,054 个涵盖所有系列和测试组的试验封装、113,022 次提供方调用、三个独立的模型系列、按方向评估非劣效性，以及每个方向和测试组各 1,056 个硬负例机会。因此，经 Bonferroni 校正的 95% 家族错误率假阳性传递上限（而不只是点估计）必须低于 1%。运行 npm run verify:ucr:study-design，验证已冻结的指标覆盖范围。完整协议和 CLI 驱动程序契约见 evals/ucr/FULL_STUDY_CONTRACT.md。

性能控制

• TOKEN_OPTIMIZER_USE_FILE_SESSION（默认值：false）

  • 设置为 true，可恢复基于文件的会话跟踪（旧版模式）
  • 如果遇到内存会话状态问题，可使用此选项
  • 示例：$env:TOKEN_OPTIMIZER_USE_FILE_SESSION = "true"

• TOKEN_OPTIMIZER_SYNC_LOG_WRITES（默认值：false）

  • 设置为 true，可禁用批量日志写入
  • 强制立即写入磁盘（速度较慢，但更可靠）
  • 可用于调试，或在日志丢失时使用
  • 示例：$env:TOKEN_OPTIMIZER_SYNC_LOG_WRITES = "true"

• TOKEN_OPTIMIZER_DEBUG_LOGGING（默认值：true）

  • 设置为 false，可禁用 DEBUG 级别日志记录
  • 减小日志文件大小并提升性能
  • 仍会写入 INFO/WARN/ERROR 日志
  • 示例：$env:TOKEN_OPTIMIZER_DEBUG_LOGGING = "false"

开发路径

• TOKEN_OPTIMIZER_DEV_PATH
  • 本地开发安装路径
  • 如果未指定，则自动设为 ~/source/repos/token-optimizer-mcp
  • 可覆盖为自定义开发路径
  • 示例：$env:TOKEN_OPTIMIZER_DEV_PATH = "C:\dev\token-optimizer-mcp"

性能影响：使用内存模式（默认）可使钩子开销提升 7 倍：

• 之前：每次钩子操作耗时 50-70ms
• 之后：每次钩子操作耗时 <10ms
• 钩子延迟降低 85%

监控令牌节省情况

实时会话监控

如需查看实际节省的 token 数量，请使用 get_session_stats 工具：

// View current session statistics with token savings breakdown
await get_session_stats({});

输出包括：

• 节省的 token 总数（这才是实际节省量！）
• Token 减少百分比（例如，“减少 60%”）
• 缓存命中率和压缩率
• 按工具分类的明细（Read、Grep、Glob 等）
• 优化效果最显著的 10 项操作，附优化前后对比

输出示例：

{
  "sessionId": "abc-123",
  "totalTokensSaved": 125430, // ← THIS is your savings!
  "tokenReductionPercent": 68.2,
  "originalTokens": 184000,
  "optimizedTokens": 58570,
  "cacheHitRate": 72.0,
  "byTool": {
    "smart_read": { "saved": 45000, "percent": 80 },
    "smart_grep": { "saved": 32000, "percent": 75 }
  }
}

会话跟踪文件

所有操作都会自动记录在会话数据文件中：

位置：~/.claude-global/hooks/data/current-session.txt

格式：

{
  "sessionId": "abc-123",
  "sessionStart": "20251031-082211",
  "totalOperations": 1250, // ← Number of operations
  "totalTokens": 184000, // ← Cumulative token COUNT
  "lastOptimized": 1698765432,
  "savings": {
    // ← Auto-updated every 10 operations (Issue #113)
    "totalTokensSaved": 125430, // Tokens saved by compression
    "tokenReductionPercent": 68.2, // Percentage of tokens saved
    "originalTokens": 184000, // Original token count before optimization
    "optimizedTokens": 58570, // Token count after optimization
    "cacheHitRate": 42.5, // Cache hit rate percentage
    "compressionRatio": 0.32, // Compression efficiency (lower is better)
    "lastUpdated": "20251031-092500" // Last savings update timestamp
  }
}

v1.x 新增：现在每执行 10 次操作，savings 对象都会自动更新，无需手动调用 get_session_stats() 进行实时监控。这样可以即时查看 token 优化效果。

工作原理：

• 每执行 10 次操作，PowerShell 钩子都会自动调用 get_cache_stats() MCP 工具
• 根据缓存性能数据（压缩率、压缩前后的大小）计算节省指标
• 使用最新的节省数据原子性地更新会话文件
• 如果 MCP 调用失败，将跳过更新，不影响操作

注意：如需详细分析每项操作，请使用 get_session_stats()。会话文件提供的是较高层级的汇总指标。

项目范围分析

分析整个项目中的 token 使用情况：

// Analyze project token costs
await analyze_project_tokens({
  projectPath: '/path/to/project',
});

提供的信息：

• Token 总成本估算
• 按 token 数量排列的最大文件
• 优化机会
• 按当前 API 费率计算的成本预测

缓存性能

监控缓存命中率和存储效率：

// View cache statistics
await get_cache_stats({});

指标：

• 条目总数
• 缓存命中率（%）
• 平均压缩率
• 总存储节省量
• 访问频率最高的键

故障排除

CLI 连接与发现

工具未在 Codex 中显示

1. 运行 codex mcp get token-optimizer。
2. 使用 codex mcp list 确认该条目已启用。
3. 开始新的 Codex 对话。
4. 在交互式 CLI 中运行 /mcp 并检查服务状态。

Windows 上的 codex 被阻止

在限制性执行策略下，PowerShell 可能会拒绝运行 codex.ps1 shim。请在安装和验证命令中使用 codex.cmd，或检查用户范围的 PowerShell 执行策略。

从 Codex 中移除 Token Optimizer

codex mcp remove token-optimizer

这会移除 Codex 注册信息，但不会删除本地缓存或分析数据库。

常见问题与解决方案

问题：“Claude Code Settings 中出现 Invalid or malformed JSON”

症状：运行 install-hooks 后，Claude Code 显示“Invalid Settings”错误

原因：settings.json 文件中添加了 UTF-8 BOM（字节顺序标记）

解决方案：升级到 v3.0.2+，该版本已修复 BOM 问题：

npm install -g @ooples/token-optimizer-mcp@latest

如果你已经使用 v3.0.2+，请手动移除 BOM：

# Windows: Remove BOM from settings.json
$content = Get-Content "~/.claude/settings.json" -Raw
$content = $content -replace '^\xEF\xBB\xBF', ''
$content | Set-Content "~/.claude/settings.json" -Encoding utf8NoBOM

# Linux: Remove BOM from settings.json
sed -i '1s/^\xEF\xBB\xBF//' ~/.claude/settings.json

# macOS: Remove BOM from settings.json (BSD sed requires empty string after -i)
sed -i '' '1s/^\xef\xbb\xbf//' ~/.claude/settings.json

问题：安装后钩子无法工作

症状：未自动进行 token 优化

诊断：

1. 检查是否已安装钩子：

   # Windows
   Get-Content ~/.claude/settings.json | ConvertFrom-Json | Select-Object -ExpandProperty hooks
   

   # macOS/Linux
   cat ~/.claude/settings.json | jq .hooks
   

2. 确认 dispatcher.ps1 是否存在：

   # Windows
   Test-Path ~/.claude-global/hooks/dispatcher.ps1
   

   # macOS/Linux
   [ -f ~/.claude-global/hooks/dispatcher.sh ] && echo "Exists" || echo "Missing"
   

解决方案：重新运行安装程序：

# Windows
powershell -ExecutionPolicy Bypass -File install-hooks.ps1

# macOS/Linux
bash install-hooks.sh

问题：缓存命中率低于 50%

症状：会话统计显示缓存命中率低于 50%

原因：

1. 正在处理大量新文件（符合预期）
2. 缓存最近已清除
3. TTL（生存时间）过短

解决方案：

1. 开始工作前预热缓存：

   await cache_warmup({
     paths: ['/path/to/frequently/used/files'],
     recursive: true,
   });
   

2. 对稳定的 API延长 TTL：

   await smart_api_fetch({
     url: 'https://api.example.com/data',
     ttl: 3600, // 1 hour instead of default 5 minutes
   });
   

3. 检查缓存大小限制：

   await smart_cache({
     operation: 'configure',
     l1MaxSize: 2000, // Increase from default 1000
     l2MaxSize: 20000, // Increase from default 10000
   });
   

问题：内存使用量过高

症状：Node.js 进程占用过多内存

原因：内存中缓存过大（L1/L2 层）

解决方案：配置缓存限制：

await smart_cache({
  operation: 'configure',
  evictionStrategy: 'LRU', // Least Recently Used
  l1MaxSize: 500, // Reduce L1 cache
  l2MaxSize: 5000, // Reduce L2 cache
});

或清除缓存：

await clear_cache({});

问题：首次操作速度慢

症状：初次执行 Read/Grep/Glob 操作时速度较慢

原因：缓存为空，正在构建索引

解决方案：这是预期行为。后续操作的速度会提升 80-90%。

若要预热缓存：

await cache_warmup({
  paths: ['/src', '/tests', '/docs'],
  recursive: true,
  schedule: 'startup', // Auto-warm on every session start
});

问题：Windows 上出现“Permission denied”错误

症状：无法写入缓存或日志文件

原因：PowerShell 执行策略或文件权限

解决方案：

1. 设置执行策略：

   Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser
   

2. 检查文件权限：

   icacls "$env:USERPROFILE\.token-optimizer"
   

3. 如有需要，以管理员身份重新运行安装程序

问题：缓存文件过大

症状：~/.token-optimizer/cache.db 大于 1GB

原因：缓存了非常大的文件或大量 API 响应

解决方案：

1. 清除旧条目：

   await clear_cache({ olderThan: 7 }); // Clear entries older than 7 days
   

2. 缩短缓存保留时间：

   await smart_cache({
     operation: 'configure',
     defaultTTL: 3600, // 1 hour instead of 7 days
   });
   

3. 手动删除缓存（终极方案）：

   rm -rf ~/.token-optimizer/cache.db
   

获取帮助

如果遇到此处未涵盖的问题：

1. 检查钩子日志：~/.claude-global/hooks/logs/dispatcher.log
2. 检查会话数据：~/.claude-global/hooks/data/current-session.txt
3. 提交问题：GitHub Issues
   • 附上调试日志
   • 附上操作系统和 Node.js 版本
   • 附上 get_session_stats 的输出

限制

• 较短文本：最适用于超过 500 个字符的内容（较短片段会产生缓存开销）
• 一次性内容：对于不会再次引用的内容没有帮助
• 缓存存储：7 天后自动清理，以避免磁盘空间占用问题
• Token 计数：使用 GPT-4 分词器（对 Claude 的计数为近似值，但足够接近）

开发

git clone https://github.com/ooples/token-optimizer-mcp.git
cd token-optimizer-mcp
npm ci
npm run build
npm test
node scripts/mcp-smoke.mjs

开发期间，让 Codex 使用本地构建版本：

codex mcp add token-optimizer-local -- node /absolute/path/to/token-optimizer-mcp/dist/server/index.js

文档

• 快速入门
• 工具参考
• Codex 和 Agent 指南
• 钩子安装
• 测试
• 贡献
• 安全策略
• 更新日志

许可证

MIT 许可证 - 详情请参阅 LICENSE

作者

由 ooples 团队打造，为受支持的编码 Agent 提供可衡量的 Token 效率提升。