Token Saver 省 99% token 是真的，但有个前提没人告诉你

一份 233 页的法院判决书，塞进 Claude 是 133349 个 token。用上 Token Saver 之后，同样的问题只花 740 个。省了 99.4%。

我第一眼看到这个数字的反应和你一样，营销话术。但把它的八阶段管道扒开看完，我改口了，数字是真的，只是这个 99.4% 成立有一个前提，几乎所有转载的文章都没说。

更要命的是，网上叫 Token Saver 的开源项目有三个，干的事完全不一样。你照着某篇爆款文去搜，装到的大概率不是你想要的那个。

一句话摘要，把整本 PDF 塞进上下文的钱，本质上是重复搬运费，不是压缩费。

为什么你的 PDF 账单越问越贵

先算一笔让人不太舒服的账。

Claude 处理 PDF 的默认路径是双通道，每一页既转成图片保留版式，又抽一份纯文本出来。光纯文本这一路，每页就是 1500 到 3000 个 token。一本 200 页的技术手册，取下限 1500 算，30 万 token。

30 万。Claude 的上下文窗口是 20 万。也就是说这本手册连一次都塞不进去，你根本走不到烧钱那一步，先撞的是墙。

真正的杀手在后面。对话历史每一轮都要完整重发给模型，这是无状态 API 的基本盘。你第一轮塞进去的那本 PDF，第二轮还在，第十轮还在。它不是花了一次钱，是花了 N 次钱，N 等于你追问的轮数。

这就是那些爆款标题里「问 20 轮烧掉二十几万 token」的真实来源。不是模型贪心，是同一份内容你付了二十遍钱。

做法	单轮成本	20 轮累计	幻觉风险
整本 paste 进上下文	极高，还可能超窗口	线性叠加，翻 20 倍	高，长上下文中段信息容易被忽略
Prompt Caching 加 Projects	中等，缓存命中后降价	有折扣但整本仍越界到 provider	中，检索仍靠模型自己在长文里找
本地 RAG 只取相关段	低，千 token 级	几乎不叠加	低，命中段落带精确页码

Prompt Caching 这条路我用过，它确实能把重复部分的单价打下来，但它解决的是「便宜地重复搬」，不是「不搬」。整本文档该出本机还是出本机，该占窗口还是占窗口。

问题定义清楚了，剩下的是工程活。

它到底做了什么，把整本变成只取几段

Token Saver 的做法在后端工程师眼里其实一点都不新鲜，它就是把搜索团队干了十几年的事，塞进了一个跑在你本机的 MCP server 里。

这个项目由 Marktechpost AI Media 发布，MIT 许可，v1.0，作者是 RIT 的实习生 Arnav Rai，上面挂着 Jean-Marc Mommessin 和 Asif Razzaq 两位。一个实习生的项目能被五家媒体同时报道，靠的不是代码量，是它把一个所有人都在忍受的成本问题捅破了。

架构上有两个决定性的选择。

第一，纯本地。它是标准的 MCP server，走 stdio 和客户端通信，不开网络端口，PDF 从头到尾不出本机。对做金融和医疗的同学，这一条比省 99% 更重要。第二，文件夹白名单。你显式授权哪几个目录，白名单外的文件一律拒绝访问，防的是模型被绕出去读你的私钥。

真正值钱的是检索这一层。它用的是 Hybrid RAG，两路召回加权融合。

BM25 那一路走 SQLite 的 FTS5 全文索引，权重 0.4。这东西你熟，就是倒排索引，和 MySQL 的 FULLTEXT、Elasticsearch 的默认打分是一个家族。它的强项是精确术语，法律条款编号、API 方法名、错误码，这类词向量模型经常认不出来。

语义那一路加载本地的 all-MiniLM-L6-v2 模型算向量，用余弦相似度，权重 0.6。这条路你也熟，就是推荐系统里的向量召回。它负责的是「怎么退款」要能命中写着 refund policy 的段落。

两路的分工，恰好补上了对方的死角。

为什么权重给到 0.4 比 0.6，我的理解是文档问答场景里用户提问天然口语化，语义召回的贡献更大，但又不能把 BM25 的权重压太低，否则一遇到条款编号就抓瞎。这个配比没有普适最优解，它是在两类失败模式之间做的一次工程折中。

融合之后是一条八阶段的管道，你完全可以按 ETL 的思路去读它。

Extract   pypdfium2 抽文本，失败时回退 pypdf
Chunk     切成 180 词一段，相邻段重叠 40 词
Score     BM25 * 0.4 + 余弦相似度 * 0.6
Gate      与查询无关键词重叠的段落，语义分需 >= 0.25 才放行
Dedup     去掉近似重复的段落
Trim      只保留直接回答问题的句子
Budget    返回内容上限 8000 字符
Envelope  包裹文件名与精确页码后交给模型

有两个阶段值得单独说。

Gate 这一层是防噪声的关键。纯语义召回有个老毛病，一段和问题完全不沾边的文字，因为句式相似度高被捞上来，模型看了就开始编。加一道限制，没有关键词重叠的段落必须语义分过 0.25 才准进，等于给向量召回加了一道人工闸门。这是从工业界踩坑里长出来的设计，不是论文里的漂亮公式。

Trim 这一层则解释了为什么最终 token 数能压到三位数。它不是把整段丢给模型，而是从段落里再抽出直接回答问题的那几句。180 词的 chunk 经过 Trim 之后可能只剩两句话。

还有一个细节体现了作者的工程素养，向量模型加载失败会优雅回退到纯关键词匹配。没有 GPU、没联网、模型下不下来，服务照跑不误，只是召回质量降一档。能想到这一层的人，是真在生产环境上被打过的。

92% 到 99% 是真的，但基准线里藏了一个假设

先把官方 benchmark 摆出来，这三组数据用 tiktoken 的 cl100k_base 编码估算。

测试文档	页数	原始 token	优化后 token	节省
FDA 药品标签	33	23959	1021	95.7%
GDPR 全文	88	70260	996	98.6%
SFFA v. Harvard 判决书	233	133349	740	99.4%

有意思的地方来了。文档从 33 页涨到 233 页，页数翻了 7 倍，但优化后的 token 反而从 1021 降到了 740。

这不是玄学。Budget 阶段卡死 8000 字符上限，Trim 只留直接命中的句子，所以输出端基本是个常数。分母越大，比值越好看。这意味着节省率这个数字本身会随文档变大而无限逼近 100%，它衡量的其实是文档大小，不完全是工具能力。

现在说那个没人告诉你的前提。

官方基准线的原话假设是，每一次搜索，整本文档都会被计费。

请把这句话读两遍。它成立的场景是你反复追问、每一轮都把整本 PDF 重新塞进上下文。在这个场景下 99.4% 完全真实，甚至保守了。但如果你只是把 PDF 丢进去问一个问题就关掉，那省下的只有单次差额，跟 99% 没什么关系。

还有一处口径不一致值得挑明。前面说 Claude 默认每页吃 1500 到 3000 token，但 233 页的判决书基准值只有 133349，平均每页 572。差在哪，差在基准线只算了抽取出来的纯文本，没算图片通道。也就是说真实场景里的原始成本比 133349 更高，节省率只会更夸张，但两个数字口径不同，混着引用就成了数字游戏。

所以我的结论是这样。省 92% 到 99% 不是压缩魔法，是不重复搬运。工具的真实价值是把你的使用模式从「每轮全量重发」改成「按需精准取用」，省下来的钱是你原本浪费掉的搬运费。

理解了这一点，你才知道它对你到底值不值。你如果是拿到一份需求规格反复对着追问三十轮的人，这工具能救命。你如果只是偶尔扫一眼合同，装它纯属折腾。

动手接入，从安装到第一次跑通

本文环境，macOS 14 / Claude Code 已安装并可用 / Node.js >= 18 / Python >= 3.10

动手之前必须先做一次辨伪，这是我踩过的坑。

叫 Token Saver 的开源项目至少有三个，同名不同物。

项目	解决什么	装法
Marktechpost 版	PDF 本地 Hybrid RAG 检索，本文主角	Python MCP server
flightlesstux/token-saver	上下文噪声治理，监控并抑制冗长输出	npm / npx
pozii/tokensaver	token 计量、LSA 摘要压缩、结果缓存	pip

第一步，装一个今天就能跑的 token 哨兵

flightlesstux 那个 token-saver 管的不是 PDF，是上下文里的噪声。它盯着那些动辄几千行的构建日志、堆栈跟踪、重复的历史消息，在它们撑爆窗口之前发出警告并做抑制。对天天用 Claude Code 跑测试的人来说，这部分浪费一点不比 PDF 少。

# 方式一，全局安装
npm install -g github:flightlesstux/token-saver

# 方式二，不装全局，让 Claude Code 每次用 npx 拉起（推荐）
claude mcp add token-saver-mcp -- npx -y token-saver-mcp

推荐第二种，理由是 MCP server 版本更新频繁，交给 npx 管理省得手动升级。

不想用命令行的话，直接改配置文件也行，写进 ~/.claude/settings.json。

{
  "mcpServers": {
    "token-saver-mcp": {
      "command": "npx",
      "args": ["-y", "token-saver-mcp"]
    }
  }
}

这个 JSON 结构就是 MCP 的通用范式，后面所有 server 都是这三件套，服务名、command、args。看懂它，你以后接任何 MCP 都不用查文档。

第二步，验证 MCP 是否真的注册上了

claude mcp list

✅ 预期输出，能看到服务名和连接状态。

token-saver-mcp: npx -y token-saver-mcp - ✓ Connected

不同版本的 Claude Code 输出格式略有差异，只要状态位是 Connected 就算成功。显示 Failed to connect 别急着重装，往下看报错章节。

第三步，把 PDF 检索型 MCP 接进来

这里我必须说句实话。Marktechpost 报道的那个 PDF 版本，官方面向的是 Claude Desktop，公开的 clone 地址目前还需要以官方 README 为准。我不编造一条跑不通的 git 命令给你。

但有两件事是确定的。第一，MCP 是协议不是产品，只要它是标准 stdio server，Claude Desktop 能吃，Claude Code 就能吃，区别只在配置文件位置。第二，配置骨架是固定的，你拿到官方仓库后照着填就行。

在项目根目录建 .mcp.json，这是 Claude Code 读项目级 MCP 的入口。

{
  "mcpServers": {
    "pdf-token-saver": {
      "command": "python",
      "args": ["-m", "token_saver_mcp"],
      "env": {
        "ALLOWED_DIRS": "/Users/<YOUR_NAME>/Documents/papers"
      }
    }
  }
}

ALLOWED_DIRS 就是前面说的文件夹白名单，只有这个目录下的 PDF 才允许被读。这个字段的具体名称以官方 README 为准，但白名单机制本身是它的核心设计，一定存在。

想现在就体验检索式省 token，可以先上 pozii 那个 Python 版，它有 10 个工具做计量、压缩和缓存，能跑通完整链路。

git clone https://github.com/pozii/tokensaver.git
cd tokensaver
pip install -e .

# 先手动跑一次，确认能起来再接进去
python -m tokensaver

对应配置。

{
  "mcpServers": {
    "tokensaver": {
      "command": "python",
      "args": ["-m", "tokensaver"]
    }
  }
}

接完之后怎么验证真省了钱，方法很朴素。找一本 100 页以上的 PDF，接入前后各问 20 轮相同的问题，对比 Claude Code 的 token 统计。别只问一轮，一轮看不出差距，这是前面纠偏那一节的直接推论。

常见报错与解决

报错一，claude mcp list 显示 Failed to connect。

九成是 npx 首次拉包超时或者 Node 版本太低。先确认版本，再手动预热一次缓存。

node -v            # 低于 18 直接升级，MCP SDK 不兼容旧版
npx -y token-saver-mcp   # 手动跑一次，看真实报错，Ctrl+C 退出

手动跑能暴露真实错误，比在 Claude Code 里瞎猜快十倍。

报错二，Python 版 server 启动即退出。

绝大多数是解释器串了。你用 pip install -e . 装进了 venv，配置里的 python 却指向系统解释器，模块自然找不到。解法是把绝对路径写死。

which python       # 拿到当前环境的绝对路径
# 例如 /Users/mage/.venvs/tokensaver/bin/python

然后把 command 从 python 换成那个绝对路径。MCP server 是被客户端以子进程拉起的，它不继承你终端里的 conda 或 venv 激活状态，这是新手最容易栽的地方。

报错三，首次查询卡住不动。

如果用的是带语义检索的版本，第一次会去拉 all-MiniLM-L6-v2 模型，几十 MB，国内网络下可能要等很久甚至失败。好消息是设计上会优雅回退到纯 BM25，服务不会崩，只是召回质量降一档。急着用就先让它降级跑，晚点再补模型。

性能表现与真实局限

先说好话，这套设计在长文档反复追问的场景下，效果是结构性的，不是调参调出来的。8000 字符的硬上限意味着无论文档多大，回包成本可预测，这对做成本预算的人非常友好。

然后说局限，四条，都挺硬。

零配置是营销话术。 它本质是个 Python 服务，你要装依赖、要管解释器版本、首次要下模型。真正的零配置是 npx 一行，Python 生态给不了这个。

中文和扫描件是软肋。 抽取质量完全取决于 pypdfium2，中文 PDF 的字体嵌入方式五花八门，抽出乱码不是稀奇事。扫描件更直接，没有文本层，抽出来就是空，OCR 得你自己另外接。

180 词的 chunk 会切断长逻辑。 40 词重叠能缓解，但一条横跨三页的论证链，检索系统给你的永远是碎片。需要通读全文做总结的任务，这个方案天然不适合。

检索质量决定回答质量。 没召回到的段落，对模型来说就等于不存在。而且这种失败是静默的，模型不会告诉你「我没看到相关内容」，它会拿着不完整的片段自信作答。这比整本塞进去更需要你自己交叉验证。

最后是模型档位的经验值。日常检索用 Sonnet 档就够，它能处理模糊的文件名、不确定时会主动澄清。Opus 留给需要精确推理的任务，把它当检索工人用是浪费。

什么时候用，什么时候别用

判断标准其实就一条，你会不会对同一份文档追问超过五轮。

适合的场景。 论文精读，合规文档查条款，需求规格反复核对，技术手册查 API。共同点是文档大、问题多、每次只需要其中一小块。

别用的场景。 只问一次的临时文档，需要通读全文写总结的任务，扫描件和图表密集的 PDF，以及文档本身不到 20 页的情况。20 页以下整本塞进去更省事，工具链的复杂度反而成了负担。

还有一类特殊情况必须用，就是文档涉密。本地 stdio 加白名单，PDF 不出本机，这一条对金融、医疗、法务团队的价值远超省钱。

投票，你现在读大 PDF 是怎么处理的？

• A. 整本 paste，烧就烧了
• B. 靠 Prompt Caching 加 Projects 扛
• C. 手动切片挑章节喂
• D. 已经在用 RAG 类 MCP

常见问题

Q1，装了这个之后，Claude 还能看到 PDF 里的图表吗？

基本看不到。这套方案走的是文本抽取加检索，图片通道被绕过了。图表信息密集的 PDF，比如财报和架构文档，用它会丢掉关键信息，这种场景老老实实走原生多模态。

Q2，和 Prompt Caching 冲突吗，能一起用吗？

不冲突，而且互补。Caching 优化的是重复前缀的单价，RAG 优化的是塞进去的总量。同时开的效果是，你既只塞相关段落，这部分内容还能命中缓存。

Q3，SQLite FTS5 索引建在哪，会不会越来越大？

建在本地的数据目录下。索引大小和文档文本量同数量级，几百 MB 的 PDF 库对应百 MB 级索引，比起省下的 token 完全划算，定期清理不用的文档索引即可。

Q4，Gate 阶段的 0.25 阈值能不能调？

这类参数通常暴露为配置项。调高更严格，噪声少但可能漏召回，调低反过来。建议先跑默认值，只有明确观察到大量无关段落被召回时才动它，凭感觉调阈值是 RAG 调优里最常见的自我欺骗。

Q5，三个同名项目我到底该装哪个？

按痛点选。日志和输出太长撑爆上下文，装 flightlesstux 那个。想要 token 计量和缓存能力，装 pozii 那个。就是要解决大 PDF 反复追问，等 Marktechpost 版的官方仓库，或者自己按八阶段管道的思路搭一个，说实话技术栈没有秘密。

我的判断

这个项目真正的价值不在那 99%，在于它把一件被默认接受的荒谬事捅破了。我们花大价钱买的是模型的推理能力，结果绝大部分 token 消耗在把同一份文档反复搬进搬出。这就像每次问朋友一个问题，都要先把整个书架搬到他面前，问完搬走，下次再搬一遍。

所以我更愿意把它看成一个信号。上下文窗口的军备竞赛快要见顶了，从 20 万卷到 100 万，边际收益在肉眼可见地递减，而成本是线性甚至超线性上涨的。下一阶段的竞争会回到检索这个老战场上，谁能在有限窗口里放进最相关的内容，谁就赢。一个实习生用 BM25 加 MiniLM 就能把这件事做到 99%，恰恰说明这条路的技术门槛不高，缺的一直是有人认真去做。

顺手把公众号设个星标吧，微信改版之后不加星标的号很容易在信息流里沉底，我这种更新频率不算高的号尤其吃亏。下一篇我打算把 Claude Code 的 .mcp.json 完整配置项挨个拆一遍，包括项目级和用户级的优先级、env 注入、以及怎么给团队做一套共享的 MCP 配置模板，这套东西配好一次能用一整年。另外想问一句，你们现在最想让我拆的是 MCP 的 Sampling 机制，还是 Claude Code 的 Hooks 实战，评论区留个关键词，票多的先写。

如果你团队里正好有人在拿 Claude 啃合规文档或者大部头技术手册，把这篇转给他，光是「别每轮重发整本」这一条认知，就够省下不少冤枉钱。