Marktechpost/Token-Saver

# Token Saver 由 Marktechpost AI Media Inc 的 [Arnav Rai](https://www.linkedin.com/in/arnav-rai-475033243/)（罗切斯特理工学院的 CS 学生）在 Marktechpost 实习期间开发，由 [Jean-marc Mommessin](https://www.linkedin.com/in/contactjmm/) 和 [Asif Razzaq](https://www.linkedin.com/in/asifrazzaq/) 指导。 一个本地的 Claude Desktop 扩展，只需使用 **92–98%** 更少的 token 即可查询大型 PDF。执行本地混合搜索，引用确切的页码，并将您的文档保密在您的机器上。 Token Saver 是一个 **一键式 Claude Desktop 扩展** (`.mcpb`)。它会读取您电脑上的 PDF， 找到回答您问题的段落，并仅将这些段落连同页码引用交给 模型。这更便宜，而且通常*更准确*， 因为一个埋首于 200 页无关内容中的模型，其推理能力远不如一个 只获得正确的两段内容的模型。 ## 核心理念 **将大量数据排除在 context window 之外。在本地代码中进行搜索。只将 精确、经过验证且标明页码的切片带入模型的推理中。** 这在两个方面同时取得优势： - **成本** —— context 在每次对话时都会被重新发送，因此粘贴到 聊天中的 200 页 PDF 在每次后续跟进时都要重新付费。而一个小切片只需付费一次。 - **准确性** —— 埋首于无关文本中的模型推理能力更差；相关事实 会在中间丢失。紧密、切题的 context 更可靠。 整个工作的核心在于**精确检索**、**引用所有内容**，并在 无匹配时**选择放弃而不是猜测**。 ## 安装与使用 无需 Python、无需终端、无需配置文件——该扩展已捆绑所有内容。 1. 从 [Releases](https://github.com/Marktechpost/Token-Saver/releases/tag/version1) 页面下载 **`token-saver-ccr.mcpb`**。 2. Claude Desktop → **Settings → Extensions → Install extension** → 选择该文件。 （对于任何从文件安装的扩展，出现红色的“not verified by Anthropic”警告是正常的——请参阅[安装指南](INSTALL_GUIDE.md#step-1--install-the-extension)。） 3. 打开 **Enabled** 开关。 4. **必需：**点击 **Configure** 并选择一个包含您想询问的 PDF 的小型专用文件夹（不要直接选择整个 Documents 或 Downloads）。 5. 在您的第一个问题时，Claude 会请求使用该工具的权限——选择 **Always allow**。首次运行时还会下载一次基于 RAG 的搜索引擎 （2-5 分钟）；之后速度就会变快。 | 安装后 | 选择文件夹 | 第一个问题 | |---|---|---| |  |  |  | | 红色警告对于任何从文件安装的扩展都是标准的。请打开 **Enabled** 开关。 | 将其指向一个**小型专用文件夹**——而不是整个 Documents。 | 选择 **Always allow**，否则每次提问都会被询问。 | **第 4 步是其正常运行的关键。** 该文件夹是安全边界，它是您通过名称进行提问而不必输入路径的方式，并且在启动时，扩展会告诉 Claude 您拥有哪些文档——因此一个众所周知的标题会解析为*您的*副本，而不是 Claude 对公开出版版本的记忆。 然后直接与 Claude 交谈即可——无需路径、无需命令、无需“ingest”： Claude 会读取最匹配的文件，并在一步内给出带有页码的回答， 同时命名它所使用的文件（"Reading lease-agreement.pdf…"）。如果它选错了，只需说*“不，我指的是另一个”*；如果有多个文件高度匹配，它会显示一个简短的列表供您选择。后续提问在 30 分钟内会重复使用已加载的文档。每个答案 结尾都会附带一个估计的累计节省量区块。可以说*“list my documents”*或*“clear everything”*来进行切换。 **使用哪种模型？** 任何当前的 Claude 模型都可以——Opus、Sonnet 和 Haiku 都进行了 端到端测试。推荐使用 Sonnet 或 Opus；Haiku 也可以工作并且仍然会引用 页码，但在处理模糊请求时，预计大约需要额外一轮纠正。详情见 [INSTALL_GUIDE.md](INSTALL_GUIDE.md#which-claude-model-should-i-use)。 初学者指南、屏幕截图以及确认其正常工作的 6 项检查： **[INSTALL_GUIDE.md](INSTALL_GUIDE.md)**。如果 AI 模型无法加载，检索 会自动降级为词匹配并说明情况——无需任何配置。 ## 实际节省效果 每个答案结尾都会显示您所节省内容的累计总量：  检索质量是在真实文档上测量的（213 页的 *Dobbs v. Jackson* 判决书和 152 页的伯克希尔哈撒韦 2023 年度报告）；完整方法见 [`eval/RESULTS.md`](eval/RESULTS.md)。 **2026-07-25** 在两份真实文档的 30 个作者编写的标准问题上测得 （尚未经过人工验证）。您可以使用 [复现这些数字](#reproduce-these-numbers)中的命令自行复现。 | 指标 | 结果 | |---|---| | Retrieval recall@5 (hybrid) | **0.90** —— 对于 27/30 个问题，答案页位于前 5 名 | | 错误拒绝率 | **0.00** —— 没有切题的问题被错误拒绝 | | 仅关键词 recall@5 | **0.90** —— 无模型自动回退 | | SEM_FLOOR sweep 0.15→0.35 | recall **稳定在 0.90**，abstain 稳定在 0.00 | | 单元测试 | **index 18 · server 106**，全部通过 | **Token 节省量完全取决于文档大小** —— 无论文件多大，返回的切片大致 恒定（对于多个问题约为 2.5k token），因此节省量随 文档增大而增加。通过真实服务器路径上的 `tiktoken` 测得： | 文档 | 对比粘贴一次 | 对比每次重新粘贴 | |---|---|---| | ~20 页 | ~14% | ~83% | | ~80 页 | ~78% | ~96% | | ~300 页 | ~94% | ~99% | 交叉点大约在 **15–20 页**：低于此值，切片的成本可能比 文件*更高*，因此对于小文档来说 Token Saver 并不划算。请相信 **百分比**和趋势方向；将绝对的 token/美元数字视为 估计值（一个代理 tokenizer，以及一个假设每次都重新粘贴的基线——并且每次搜索都会对每个已加载的文档收费）。 每个数字的详细明细见 [`references/mcp-server.md`](references/mcp-server.md#the-savings-math-and-how-far-to-trust-it)。 ### 已知限制 在此明确说明，因为您在信任它之前应该了解这些： - **abstain 门控取决于关键词的存在。** 与无关段落共享偶然 词汇的查询仍可能会显示该段落——这是一个 *错误接受*。请检查引用。作为已知缺陷进行跟踪： [`docs/known-issues/false-accept-abstain-gate.md`](docs/known-issues/false-accept-abstain-gate.md)。 - **选择正确的文件是其薄弱环节。** 在一个包含 16 个 PDF 的真实文件夹中，解析器 对于 **14 个请求中的 12 个**打开了正确的文档。在正确选择的文件 *内部*进行检索是可靠的；选择文件才是它 失败的地方。 - **一个通用名词可能会选错书。** 如果一个文件夹里有两本约 1000 页的教科书，*“**教科书**怎么说巴甫洛夫”*会解析到错误的一本——因为“textbook”不在任何一个文件名中，而且巴甫洛夫也没有出现在任何一本书的开头几页。说出主题名称即可修复此问题：*“我的**心理学**教科书”* 可以正确解析。在实际测试中，Sonnet 措辞得当或会自我纠正； Haiku 需要**一轮纠正**（“list my documents”，然后再问一次）。 因此这是一个可恢复的路由错误，而不是一条死胡同。 - **仅提供页码的引用没有提供章节来源。** 在包含多数意见和不同意见的裁决中，模型必须推断一段文字来自哪一方—— 并且可能会出错。 完整的跨模型结果：[`eval/RESULTS.md`](eval/RESULTS.md) §5。 ## 复现这些数字 上面的每个数字都来自这三个命令。评估程序会下载自己的 语料库（两份真实 PDF，约 30 MB），并根据锁定的 sha256 哈希值验证它们，因此您评估的正是本 README 测量时所用的相同字节。 ``` python tests/mcp_selftest.py # expect: RESULT: 106 passed, 0 failed python tests/index_selftest.py # expect: RESULT: 18 passed, 0 failed python eval/retrieval_eval.py --download # expect: recall@5 0.90, false-abstain 0.00 ``` 第三个命令的预期输出： ``` # Retrieval eval (3 doc(s): synthetic, berkshire, dobbs) mode: hybrid (semantic+keyword) recall@5 : 0.90 (30 gold questions) false-abstain : 0.00 ``` 两个可选的交叉检查（请在上述 `--download` *之后*运行它们，它会 将语料库留在 `eval/corpus/` 中）： ``` python eval/retrieval_eval.py --keyword-only --download # no-model floor: also 0.90 python eval/retrieval_eval.py --sweep-floor 0.15:0.35:0.05 --download # flat at 0.90 across the range ``` 标准答案标签位于 [`eval/gold/`](eval/gold/) 中并已提交，因此 运行是完全可复现的；只有两份源 PDF 是在运行时获取的 （`eval/corpus/` 被刻意 gitignore 了——因为它们很大，可从原始 来源重新分发）。 ## 工作原理 ``` your question | |--> keyword (BM25, stemmed) -----+ | +--> blend 0.4/0.6 --> abstain gate |--> local embedding (cosine) ----+ | | v | dedup --> trim --> budget --> top-K cited chunks v only those few paragraphs ever reach the model; the PDF never does ``` 提取 → 180 词重叠分块 → 本地 embedding → 混合评分 → 句子窗口修剪，全部在一个驻留的本地进程中完成，该进程将 索引保存在 RAM 中，并在闲置 30 分钟后将其驱逐。embedding 部分是可选的： 如果没有它，服务器将回退到仅关键词评分（今天两者的 recall@5 都为 0.90，但它们遗漏的问题不同——见上文）。 每个选择的基本原理——0.4/0.6 混合比例、abstain 门控、 修剪窗口计数、文档解析、每个调节旋钮，以及每个报告 数字的计算方式——都在 **[`references/mcp-server.md`](references/mcp-server.md)** 中；安全边界 在 **[SECURITY.md](SECURITY.md)** 中。 ## 内部结构 ``` token-saver/ |- INSTALL_GUIDE.md # plain-English install, use, and 6 checks (start here) |- CHANGELOG.md # what changed, and which version has which fix |- SECURITY.md # threat model: folder allowlist, prompt-injection |- docs/known-issues/ # open defects, written up honestly |- mcpb/manifest.json # the extension manifest (tools, folder picker) |- scripts/ | |- mcp_server.py # the server: ask/list_documents/ingest/search/clear/status/savings | |- index_store.py # extraction, chunking, embedding, SQLite index | |- retrieve.py # BM25 + stemming + stop words (shared scorer) | |- pdf_inspect.py # dev CLI: inspect a PDF, pre-build the disk index | `- build_mcpb.sh # builds dist/token-saver-ccr.mcpb <- how you ship |- docs/images/ # screenshots used by the guides |- tests/ # mcp_selftest, index_selftest |- eval/ # retrieval_eval (recall@5 / abstain) + RESULTS.md `- references/ # tool reference + tuning knobs, bundle build/release runbook ``` **交付 = 一个文件。** `bash scripts/build_mcpb.sh` 生成 `dist/token-saver-ccr.mcpb`；这单个文件就是用户安装的 全部内容。 构建 / 签名 / 发布操作手册：[`references/mcpb-bundle.md`](references/mcpb-bundle.md)。 工具参考和环境配置旋钮：[`references/mcp-server.md`](references/mcp-server.md)。 ## 自行验证（开发者） ``` python tests/mcp_selftest.py # server logic, security, savings, trimming python tests/index_selftest.py # index build/query/freshness (both extractors) python eval/retrieval_eval.py # recall@5 / false-abstain on the gold set ``` ## 隐私 文档保留在您的机器上。提取和搜索在本地运行；本地 embedding 模型在首次下载后不需要互联网；只有少数 包含答案的段落会到达模型处。扩展的文件夹选择器限制了它可以读取的文件夹（见 [`SECURITY.md`](SECURITY.md)）——位于它们之外的 文件会被拒绝。 ## License MIT —— 可自由使用、修改和分享。

标签：AI, Claude Desktop, MCP, PDF处理, RAG, 本地知识库, 混合搜索, 自动化代码审查, 逆向工具