DoboCache

[简体中文](https://github.com/dobo123123/dobocache/blob/main/README.md) · [English](https://github.com/dobo123123/dobocache/blob/main/release/README.en.md)

DoboCache v0.4.9

命中缓存 + 白盒报告 —— 每一步都看得见、可复算。

DoboCache 是一个以 stdio 方式挂载的 MCP Server，作用是在你已有的编码 CLI / Agent 客户端和模型厂商 API 之间，把每一次请求的上下文整理成稳定、可复用、过长会自动补足的前缀，从而让厂商的前缀缓存（prompt caching）真正命中；命中与否、命中多少、哪一步做了调整，全部写进本地白盒日志并可随时查询。

官方入口声明

DoboCache 的官方代码仓库只有 https://github.com/dobo123123/dobocache 一处，官方发布物只在它的 Releases 页面。

在其他渠道看到同名项目、同名服务或付费版本，均非官方出品。本项目免费，不通过任何第三方平台售卖。

第一次用？请先看 [零基础三分钟上手](https://github.com/dobo123123/dobocache/blob/main/release/零基础三分钟上手.md) —— 从装 Node 到验证成功，六步走完，不用懂原理。

装的过程中报错，直接翻 FAQ 的「安装报错速查」，按报错原文查。

装不上、配不通、不知道怎么写配置？先看上面的 FAQ；还不行就到 Discussions 提问（安装类问题不用开 Issue）。

平台支持状态（装之前先看这一节）

DoboCache 是纯 JavaScript 的 stdio MCP Server，包内不含任何原生二进制（.node / .exe / .dll 数量均为 0），因此不存在 ABI 层面的平台锁定。但"能跑"和"验证过"是两件事，本版按实际验证程度如实标注：

我们把边界说清楚：

1. Windows 是主打平台，也是唯一做过真机端到端验证（真实客户端挂载 + 厂商 usage 回读）的平台；
2. Linux 已在 linux/amd64 容器环境做过真实运行验证（协议链路 + 日志 + 只读降级 + Node 版本自检），但桌面发行版的图形客户端挂载、arm64 仍未验证；macOS 从未在真机运行过。因此 macOS 只写"未验证"，Linux 只写"容器已实测"，都不写"完整支持"；成功率我们没有真实数据，不做任何百分比承诺；
3. 欢迎反馈后修：在 Linux / macOS 上跑通或跑挂，都请反馈。我们不把这些平台当作"理论上没问题所以不用管"。

反馈渠道

反馈时不要把提问原文粘进 issue：日志已脱敏（req- / sid- ），贴日志片段足够定位问题。

一、它解决什么问题

现代厂商 API 都提供前缀缓存：请求开头部分如果与上一次完全一致，这部分 token 按缓存价计费，不再全价重算。但真实对话里前缀经常"差一点点"：

• 系统提示词顺序不稳定、拼接顺序每次不同；
• 历史消息被裁剪后长度对不齐缓存块边界（常见是 128 token 对齐）；
• 前缀长度小于厂商的最小缓存门槛，压根不进入缓存；
• 重复指令、重复文档块让前缀越来越长却越来越脏。

任何一处不一致，缓存就整个失效——你以为在用缓存，其实一直在全价重算。DoboCache 就是把这些"差一点点"逐条修掉，并且把每一步的调整原因写清楚，让你能自己核对而不是只看一个漂亮数字。

二、九个可调用的工具（8 个业务工具 + 1 个 ping 健康检查）

server 共暴露 8 个业务工具 + 1 个健康检查（`ping`），均为 stdio 本地调用，不联网、不上传：

典型参数：cf_inject(reset=true, sessionId=<你的会话标识>, minPrefixTokens=<目标厂商门槛>)。

参数在协议层做类型与范围校验（如 threshold ≥ 0、topK ≥ 1、maxChars ≥ 1、maxTokens > 0），越界会返回标准 -32602 校验错误并指明字段，不会静默生效。

三、版本说明（请先读这一节）

v0.4.9 = 发布通道切换版。npm 已公告自 2027-01 起限制「可绕过 2FA 的长寿命 token」直接发布，本版把发布通道整体切到 GitHub Actions OIDC Trusted Publishing：打 tag 时由 GitHub 签发短期令牌、npm 侧校验后直接收包，仓库与其设置里不再存放任何发布密钥，产物附带 provenance 签名、可追溯到具体 commit 与工作流运行。代码与缓存核心零改动，行为与 v0.4.8 逐字节一致。

为什么会有 v0.4.3：v0.4.2 正式包里，injectIncremental 第 4 步 topUpPrefixToMin(...) 之后缺少 prefix = topUp.prefix;，导致补足结果没有接回、参数形同虚设。厂商 D 系默认门槛低（295），正常前缀本就够长，所以一直没暴露；厂商 G 系真实门槛 1806+，必须靠补足才能过线，一补不上立刻露馅——这就是回归用厂商 G 的原因。v0.4.3 补上了这一行。

四、实测数据（20 次连续请求对照）

本组实测：同一套 20 次递进式连续话题。请求端为「某常见编码 CLI 工具」接入（模型来自厂商 G），白盒引擎以 stdio MCP 挂载 DoboCache；同一台机器、同一模型、同一套参数，只区分"挂载 / 不挂载"。

先说三个读表约定：① 「厂商 D」「厂商 G」是匿名代号，「某常见编码 CLI 工具」指某一商业化编码客户端，匿名是为了不把第三方产品的实测表现绑进本文；② 三种请求端统一用代号指代——WBX（自研白盒直连）/ DXH（官方 Harness headless）/ COD-X（常见编码 CLI），代号是请求端类型的缩写，不对应任何具体产品名，也不含第三方商标；③ 表中只报命中率与相对比例，不报任何金额，成本相关字段按 README §六 的计价系数折算相对值。

关键读法，请连同三条一起看：

1. 对照组每次都注入了不同的随机噪音制造前缀漂移，所以 20 次全 0——这不是"对照组很差"，而是"前缀一变，厂商前缀缓存就整段失效"的真实写照；
2. 实验组 20 次全部命中，前缀 prefixTokens 稳定落在 3456–4480，每一次 prefixReady 均为 true；
3. 命中率是单次请求输入内部的缓存命中占比，不是绝对 token 节省量。两组输入量本就不同（对照组输入随请求次数从 39 累积到 2738 tokens，实验组稳定在"前缀 + 尾部"），因此不可跨组直接换算成绝对 token 数，也不要在不同实验之间横向混比。

把视角拉高一层：不挂载并不总是 0%。 命中率不是只由"挂不挂"决定，请求端自己怎么构造请求，决定了对照组的起点。同一套挂载逻辑换到三种请求端形态各跑 20 次：

先把三个请求端分别是什么讲清楚——对照组起点之所以差这么多，全在这里：

一句话讲明白：A 的 0% 是"这个请求端本来就没有前缀可命中"（我们自己搭的底座，故意什么都不做，用来测零基线）；B 的 66% 是"官方客户端自带前缀垫在下面"。两者都不是 DoboCache 的作用结果。 这三个起点只说明一件事——对照组的高度由请求端自身的前缀处理能力决定。所以本表只能横着读同一形态内的「挂 vs 不挂」，不能竖着比"谁的对照组更高"，更不能把跨形态百分比相减当作本方案的提升幅度。

三条读法：

1. 形态 B 的 66%–68% 不是 DoboCache 的功劳，也不是"提升幅度小"——那是请求端自己就挂了全局系统前缀缓存，对照组天生占便宜；而它随噪音累积一路劣化（84.27% → 54.54%），恰恰说明这种请求端的缓存同样脆弱；
2. 三种形态的对照组起点从 0% 到 68%，差别全在请求端怎么构造请求，跨形态的对照值不可互比；唯一可比的是同一形态内部的"挂 vs 不挂"；
3. 挂载后三种形态都落在 90%–98%，说明"静态前缀复用"这件事与请求端形态无关，不是某一家请求端的特例。
4. 口径提醒（比数字本身更要紧）：形态 A / B 是「20 次请求累计口径」（累计命中 tokens ÷ 累计 prompt tokens），形态 C 是「20 次逐次请求命中率的均值」——两种统计算法不同，跨形态只能看量级，不能拿百分比互相加减；同一形态内部的「挂 vs 不挂」才是同口径对比。

再单独说清 COD-X 那两轮（组 7 与组 8）——这一格最容易被读歪：

两轮是同一形态、同一套 20 轮任务、同样的对照组构造方式（每轮在请求头部注入不同的随机噪音，故意让前缀漂移），唯一差别是挂载的版本。对照组不挂载、与版本无关，所以「组 7 = 9.87%、组 8 = 0.00%」不是"版本越高、不挂载越差"，而是噪音注入本身的随机性：

• 组 7 里 R10、R20 这两次，历史已累积到 10 轮 / 19 轮，长历史前缀足够长，厂商侧缓存自己对上了，这两次读到 99.27% / 98.10%；其余 18 次被噪音打散、读数为 0，20 次平均下来才是 9.87%；
• 组 8 那 20 次的噪音把前缀全部打散，于是次次为 0，均值为 0.00%。

这两个数反过来说明了一件对本工具"不算功劳"的事：厂商自带缓存本身很好用——只要前缀稳定，它能吃到接近 99%。 全程的卡点只有一件事：前缀稳不稳。DoboCache 做的是把前缀稳定下来、让"稳"发生在每一次请求上，不是凭空制造命中。所以「不挂载 0%–9.87%」是压力条件下的读数，既不是"厂商缓存很差"，也不该被读成"挂上就从 0 涨到 98 个点"。

组 7 实验组均值 90.58% 偏低同理：R9、R13、R16 三轮遇到厂商侧抖动（53.08% / 85.53% / 0.00%），剔除这 3 次后其余 17 次均值 98.41%，与组 8 按同一位置剔除后的 98.57% 只差 0.16pp——两个版本在稳定段上一致，不存在"版本升级带来 8 个点提升"这回事。逐次对照见 release/testdata/hitrate-regression-report-20261103.md 第六节。

统一口径：不挂载约 0%–68%（随请求端形态浮动），挂载后 90%–98%。表中每一行都能落到实验档案的实测记录上（实验 031 / 032 / 033 / 034 与组 7 / 组 8），并与汇总 CSV 的 source_exp / recompute_file 字段一一对应：release/testdata/hitrate-multi-platform-summary-20261105.csv——形态 A / B 的分子分母以 token 列同表落盘，形态 C 为逐次均值、逐次数据在同目录，任一行都可自行复算。逐次曲线与重绘图脚本见 release/scripts/hitrate-comparison.py。本表不含任何估算值或取整凑数。

关于测试规模：一句实话

这套数据来自 8 组对照实验，正式组每组 20 次连续请求，另有两组 5 次、10 次的前期门槛探测。

但要先把边界讲清楚：这些测试的单次请求体量都很小——每轮输入是同一份 AI 资讯盘点话题，前缀几百到数千 tokens，任务原文与逐次 usage 都在 release/testdata/，谁都能自己算一遍。

我们没有测「特别长的长任务」：单轮上万 tokens 的长文档问答、整个代码库的分析、几十轮的超长会话，都不在样本里。缓存前缀复用在这种体量下是否一样成立，我们没测过，也不打算替它下结论。

如果你手上正好有这类长任务，欢迎自己挂上去跑一遍再回来说话——把逐次 usage 记下来，比我们的任何承诺都有用。这也正是我们把逐次数据、任务原文、复跑步骤全部放进包里的原因：让你能自己验证，而不是只能信我们。

五、白盒报告：每一步都看得见

每次 cf_judge / cf_inject 之后，白盒日志会记录这一步做了什么、为什么做、效果如何。下面是一条按当前口径（v0.4.9）输出的记录示例：

{

"requestId": "req-1b0ff98f", "ts": 1793709231484, "reqIndex": 2, "promptChars": 36, "rawTokens": 201, "optimizedTokens": 4096, "hitRate": null, "savedTokens": 0, "savedPct": 0, "changes": [ {"kind": "align128", "label": "前缀 128-token 对齐：减少尾部部分命中", "detail": "追加 98 个对齐块"}, {"kind": "topup", "label": "前缀过门槛补充：达到最小有效缓存长度", "detail": "补充 63 块（高价值片段/文档块）"}, {"kind": "scenario", "label": "首条请求或缓存为空：轻量约束放行自由回答"} ], "note": "cf_inject：原始 201 tokens → 优化后 4096 tokens（前缀 4096 + tail）；实际门槛 3450 tokens。", "sessionId": "sid-b6ca1662", "scenario": "first", "mode": "rebuild", "alignBlocks": 98, "prefixTokens": 4096 }

三类常用对照能力都在：第几次请求（reqIndex）、是否同一提问（req-... 相同即同一提问）、每一步动了什么（changes[] + note）。内容本身不落盘。

记录里 hitRate 为 null 表示本次请求未判定：cf_inject 处在注入阶段、请求尚未发出，且调用方没有把厂商返回的缓存 usage 回传给 DoboCache，本机就无法得知真实命中率——此时如实记 null（未判定），不再写 0。看到 null 不要读成"命中率 0%"：要得到可判定的命中率，请在 cf_judge / cf_inject 里带上 hitTokens / missTokens（取自厂商 usage 的