简体中文 · English

DoboCache v0.4.9

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

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

官方入口声明 DoboCache 的官方代码仓库只有 https://github.com/dobo123123/dobocache 一处，官方发布物只在它的 Releases 页面。 在其他渠道看到同名项目、同名服务或付费版本，均非官方出品。本项目免费，不通过任何第三方平台售卖。

第一次用？请先看 零基础三分钟上手 —— 从装 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-<hash> / sid-<hash>），贴日志片段足够定位问题。

Related MCP server: distil-mcp

一、它解决什么问题

现代厂商 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 的 prompt_cache_hit_tokens / prompt_cache_miss_tokens）。累计统计用 cf_report 查看。详见 FAQ-使用须知.md 第一节。

白盒报告默认关闭（v0.4.6）

白盒报告卡片是给你看的，但它写进对话上下文就要占 token（每张约 300+ tokens，每次工具调用都可能带一张）。因此从 v0.4.6 起：

• 默认（quiet）：报告只写本地日志，不随工具返回，不占对话 token；

• 想看累计数据：随时调 cf_report，它读本机日志、不产生额外 token；

• 想看每次的详情：设环境变量 DOBOCACHE_WHITEBOX：

  • once —— 下一次调用返回一次详情，之后自动回落 quiet（适合临时排查一次）；

  • always —— 每次调用都带详情（适合正在做对照实验，代价就是每张卡的 token）；

  • quiet —— 关闭（默认值，等价于不设）；

• 首次运行提示：本机第一次跑时会给一条一次性提示（告诉你白盒在哪、怎么开），之后永不再出。

一句话：平时不用管它；需要证据时用 cf_report（不花 token），需要看单次细节时再开 once / always。

六、安装与挂载（三种启动写法）

1. 从 Releases 下载 dobocache-v0.4.9-portable.zip 并解压（内含 dist 与仅生产依赖的 node_modules，无需 npm install；包内不含任何原生 .node 二进制，换机器换平台不会因 ABI 不匹配崩掉）；不想下载也可以用下文写法 B / C 从 npm 装；

2. 在你所用客户端的 MCP 配置里加一个 stdio server（下面三种写法任选其一）；

3. 重启客户端，确认工具列表里出现 9 个（ping + cf_judge / cf_tier / cf_inject / cf_warmup / cf_report / cf_meter / cf_prune / cf_normalize）。少任何一个都说明 server 没起来，先看客户端日志里的 stderr。

前置条件：Node.js 18 或更高。进程启动时会自检，版本过低会直接打印一句中文提示然后退出（不会静默失效）。 通用建议：配置里的路径一律填绝对路径——客户端拉起 server 时不继承你 shell 的当前目录与 PATH，只写 node 或相对路径是最常见的翻车原因。

写法 A：绝对路径 node + 入口 js（推荐）

Windows：

{
  "mcpServers": {
    "dobocache": {
      "command": "C:\\Program Files\\nodejs\\node.exe",
      "args": ["D:\\<解压目录>\\dist\\index.js"]
    }
  }
}

macOS / Linux：

{
  "mcpServers": {
    "dobocache": {
      "command": "/usr/local/bin/node",
      "args": ["/Users/<你>/dobocache/dist/index.js"]
    }
  }
}

• 适用：便携包解压即用、内网/离线机器、客户端以非登录用户或非常规工作目录拉起。

• 怎么找 node 路径：Windows where node；macOS / Linux which node（Homebrew 常见 /opt/homebrew/bin/node、/usr/local/bin/node；用 nvm 的请填具体版本目录下的绝对路径）。

• 该写法不需要 npm、不联网，跨机器最稳。

写法 B：npx -y 一次性运行

ℹ️ 渠道说明：写法 B / C 要求该版本已能从 npm registry 取到。若 npm view dobocache 返回 404（该版本尚未发布，或所用镜像尚未同步），请直接用写法 A（便携包）——功能、内容与日志行为完全一致，不需要改任何配置。

关于仓库内的 server.json：它是提交给 MCP Registry 的条目描述文件，其中 packages[].registryType 只有 npm / pypi / oci 等固定取值（schema 不存在"便携包"这个类型），因此 identifier / version 标注的是 npm 上的发布目标；若 npm 上暂时取不到该版本，一律以写法 A 为准。

{
  "mcpServers": {
    "dobocache": {
      "command": "npx",
      "args": ["-y", "dobocache@0.4.9"]
    }
  }
}

• ⚠️ Windows 上必须写 npx.cmd（"command": "npx.cmd"）。npm 在 Windows 上只安装 npx.cmd，没有 npx.exe，客户端 spawn("npx") 会直接报 ENOENT——这是 MCP 客户端在 Windows 上最高频的报错。

• macOS / Linux 保持 npx 即可；若客户端用非登录 shell 拉起且 PATH 里没有 node，可写死绝对路径（如 /usr/local/bin/npx）。

• 适用：希望自动跟随版本、机器可联网、不想手工解压。

• 前提：该版本能从 npm 取到（npm view dobocache@0.4.9 version 能返回版本号）；取不到时改用写法 A。另外 npx 有本地缓存，升级后行为仍是旧的时，执行 npm cache clean --force 或改用写法 C。

写法 C：全局安装后直接调命令

npm install -g dobocache@0.4.9

{
  "mcpServers": {
    "dobocache": {
      "command": "dobocache"
    }
  }
}

• ⚠️ Windows 上同样注意扩展名：写 "command": "dobocache.cmd"；若客户端仍找不到命令，直接填全局安装目录下的绝对路径（npm root -g 显示的目录的上一级里的 dobocache.cmd）。

• macOS / Linux 权限报错时：npm install -g dobocache@0.4.9 --prefix ~/.npm-global，配置里填 /Users/<你>/.npm-global/bin/dobocache 绝对路径。

• 适用：一台机器长期固定使用、不想每次下载。升级时重跑 npm install -g dobocache@<新版本> 并重启客户端。

三种写法对照：

要跑 npm test / npm run lint？ 便携包只带生产依赖，先在该包目录执行一次 npm install 补齐开发依赖（需要网络），再运行脚本。

日志目录（v0.4.4 起不再依赖进程"当前目录"，客户端用任意 cwd 拉起都能写对位置）：

优先级：环境变量 DOBOCACHE_LOG_DIR > 平台默认目录 > <cwd>/data/logs（回退）> 都不可写则不落盘、只在 stderr 提醒一句，进程继续运行。实际使用的目录可在 cf_report 返回的 logDir / logFile 里看到。

日志不会无限长大（默认即生效，不需要你配置）：

• 单个日志文件到 10MB 就滚动成 .1，最多保留 3 份副本（即单日最坏情况约 40MB 上限）；

• 超过 7 天 的旧日志会在当天首次写盘时被清理；

• 清理只认本模块自己的命名（dobocache-YYYY-MM-DD.log.jsonl 与其 .1/.2/.3），同目录下你自己的文件一个都不会动；

• 清理失败（权限、文件被占用等）一律静默跳过，不影响写日志，更不影响缓存主流程；

• 想放宽或收紧，用下面的 DOBOCACHE_LOG_MAX_MB / DOBOCACHE_LOG_KEEP_DAYS；当前策略与实际维护结果可在 cf_report 返回的 logPolicy / logMaintenance 里看到。

目标厂商门槛明显高于默认值时（部分厂商需要 1806+），在 cf_inject 里指定 minPrefixTokens，例如 minPrefixTokens=3000；实际生效门槛为该值 × 1.15（安全余量）。

全部环境变量（都可省略，省略即用默认值）：

计价系数请自行改为你的实际合同系数：随包默认值只用于「命中 vs 未命中」的相对值对比（例如 1:36 的差异），不是任何厂商的真实报价，savedUsd / cumSavedUsd 等字段名里的 Usd 只是历史命名，数值含义是"按当前计价系数折算的相对成本"。改系数后统计曲线整体等比缩放，命中率不受影响。

七、隐私：日志里没有你的提问原文

从 v0.4.4 起：

• requestId 只存 req-<8 位 hash>（固定盐 + 64bit 指纹），同文恒同值，不可反推原文；

• sessionId 只存 sid-<8 位 hash>；

• cf_normalize 的返回键只存 nk-<16 位 hash>；

• 新增 round（请求序号，v0.4.6 起日志字段更名为 reqIndex，含义是"本机第几次请求"，与对话阶段无关）与 promptChars（字符数）两个纯数字字段，保留"可对照"能力但不含内容；

• 落盘走字段白名单，后续即使新增字段携带正文，也不会写进日志；

• 日志只存本地，不上传任何服务器；默认落在系统标准日志位置（Windows %LOCALAPPDATA%\DoboCache\logs，macOS ~/Library/Logs/DoboCache，Linux ~/.local/state/dobocache），该目录不随包分发。

前后对照（同一条记录）：

⚠️ 历史日志仍需你自行清理：v0.4.4 无法追溯修改旧版本已生成的文件。若你的机器上存在 v0.4.3 及以前产生的 data/logs/*.jsonl（旧版本默认写在"启动时的当前目录"下），其中 requestId 仍是提问原文，请按需删除或归档。

八、客户端兼容性

结论只写有官方文档或明确来源支撑的内容；证据不足的写"未确认"，不做推测。

怎么读这张表：

• 挂载（stdio MCP）：上表 8 家中 7 家有官方文档明确写 stdio 配置；Windsurf 无法取证，暂不列入支持清单。

• 请求能否导向你的 OpenAI 兼容端点：明确支持 5 家（Cline / Continue / Codex CLI / Cherry Studio / Trae）；Cursor 不能自定义端点；Claude Desktop、Gemini CLI 的文档中未见兼容端点入口。

• 缓存命中数据在哪看：只有 2 家有文档级证据，且都不是"客户端面板里直接显示缓存命中率"——Codex CLI 是 OTel 遥测字段，Gemini CLI 是 /stats。因此本文不宣称"客户端面板直接显示缓存命中率"。准确表述是：DoboCache 在服务端读取厂商 API 返回的 usage 缓存字段并记录、回传；客户端侧可视化需逐个实测。

完整版（含每个客户端的配置文件路径、格式与 18 条来源链接、未确认清单）见 兼容性说明.md。

九、如何复现

本文所有数字都放在 release/testdata/ 里，可自行核对与重跑：

最短复现路径：

1. 解压 v0.4.9 便携包，MCP 指向 <解压目录>\dist\index.js；

2. 实验组：cf_inject(reset=true, sessionId=<新会话>, minPrefixTokens=<厂商门槛>)，按 20 次任务清单逐次发送；

3. 对照组：同样任务文本，但每次头部注入不同随机噪音（这是关键，见下）；

4. 每次取第二遍请求的厂商 usage（第一遍建缓存，第二遍才是命中读数）；

5. 验收：日志 prefixReady=true、effectiveMinPrefixTokens = 配置门槛 × 1.15；实验组命中率应稳定在 90% 以上，对照组以 0 为主。

⚠️ 复跑必读：对照组若不给每次前缀注入随机噪音，厂商的自动前缀缓存会让对照组也命中，对照就失去意义。这是本套实验最容易做错的一步。

十、已知限制与不承诺项

装在机器上之前，请先把这一节读完。以下每一条都是能力边界，不是待办事项。

1. 命中前提是前缀逐字节稳定，本工具无法替你保证

缓存命中取决于请求前缀（系统提示、工具列表、历史消息顺序、头部字段）是否与上一次完全一致。只要客户端在头部注入时间戳、随机 ID、动态工具集，或历史消息顺序变化，命中就会下降。cf_inject 只能把可控部分整理成稳定形态，不能阻止客户端改动前缀，也无法在客户端已经改动后强行命中。

2. 服务商必须支持前缀缓存并已开启

各家对"最小可缓存前缀长度"有各自门槛（本项目实测口径取"配置门槛 × 1.15"作为有效门槛）。若所用端点不支持前缀缓存、或账号侧未开启，命中率就是 0，本工具不修改服务商行为，也无法在不支持的服务商上凭空产生命中。

3. 只读服务商已经回传的 usage 字段，不做推算

命中相关数字来自厂商 API 返回的 usage 缓存字段。客户端或服务商不回传该字段时，报告里就没有这个数——本项目选择显示"未判定"而不是用字符数估算一个好看的数字。

4. savedUsd / cumSavedUsd 是相对值，不是账单

随包默认计价系数只用于"命中 vs 未命中"的相对对比，不是任何厂商的真实报价，字段名里的 Usd 只是历史命名。真实金额请换成你自己的合同系数后自行折算，命中率不受系数影响。

5. 不做语义缓存，不跨会话复用内容

本工具不代理、不转发、不存储你的提问正文，也不做相似度/语义层面的复用。相同问题换个说法不会被"当成命中"。

6. 传输形态仅 stdio MCP

当前包只提供 stdio 挂载。HTTP / SSE 形态未提供；客户端兼容性表中标"未确认"的项（含 Windsurf）没有官方文档取证，不列入支持清单，也不做效果承诺。

7. 实测规模有限，不是基准测试

第四节数据为 20 次连续请求的对照实验（同形态 + 跨 4 种请求形态），可复现，但不等于你所在场景的预期表现。样本量说明见「关于测试规模：一句实话」。

8. 明确不承诺的事项

不做以下任何承诺：特定命中率数值、特定节省比例或金额、在任意服务商/客户端组合上的效果、与其他缓存方案对比的优势幅度、以及上线后的业务收益。能否命中取决于你的请求形态与服务商策略，本工具提供的是可控的稳定前缀、准入判断和可核对的测量，不是效果担保。

9. 升级或换客户端后需要重新观察

更换客户端、升级版本、修改系统提示或工具列表后，此前建立的缓存前缀即失效，需重新按第九节方式观察。旧版本产生的历史日志不会被自动改写或删除，需自行清理。

十一、常见问题

hitRate 是 null 是不是没生效？第一次请求为什么没命中？日志在哪、怎么读？换机器后要不要清日志？——见 FAQ-使用须知.md。

口径声明

本 README 及其同批文档遵循同一份对外口径约定：

1. 宿主匿名：被测宿主统一称"某常见编码 CLI 工具"，不出现具体产品名；

2. 不报金额：只报命中率与相对比例，不含任何费用数字；

3. 不宣称提升：v0.4.9 是发布通道切换版，缓存核心与 v0.4.8 一致，对外表述为"命中行为与 v0.4.8 一致"，不写"更高/更快/更强"；

4. 不混比：不同实验、不同接入方式、不同厂商的数字不横向混比。

许可证

DoboCache 采用 Apache License 2.0 发布，全文见仓库根目录的 LICENSE，标准文本也可在 https://www.apache.org/licenses/LICENSE-2.0 查阅。

这意味着：

• 允许商用。你可以在公司内部、商业产品或对外服务中使用、修改、再分发 DoboCache，无需付费、无需授权申请、无需向我们报备。

• 允许闭源衍生物。你可以把它集成进闭源产品，但需保留版权与许可声明，并对你修改过的文件保留变更说明。

• 提供专利许可。Apache-2.0 第 3 条包含对贡献者的明示专利授权，对使用者更友好。

• 无担保。软件按"现状"提供，不附带任何明示或默示担保；使用风险由你自行承担。

• 保留商标与名称。许可证不授予 "DoboCache" 名称、项目名及相关标识的使用权（见 Apache-2.0 第 6 条）。你可以基于本项目做二次开发与分发，但请勿让用户误以为你的分支、服务或产品就是 DoboCache 官方版本，或声称获得我们的背书。注明"基于 DoboCache"是允许且受欢迎的。

关于收费

DoboCache 是免费的开源项目，没有付费版本、没有订阅、没有商业授权门槛，也没有任何形式的收费计划。

如果你有商业合作、定制开发或企业级支持的需求，欢迎通过仓库 Issues 联系作者洽谈；这类合作是独立服务，不会改变你在 Apache-2.0 下已经获得的任何权利。

第三方组件

本项目依赖若干第三方开源包，其许可证与声明保留在各自的包目录中（例如 node_modules/<package>/LICENSE）。这些许可证不受本项目 Apache-2.0 协议的替换或覆盖，再分发时请一并保留。

版权与声明文件

• LICENSE：Apache License 2.0 标准全文（未做任何修改）

• NOTICE：项目名称、版权年与商标声明（Apache-2.0 第 4(d) 条要求随分发保留）

关于衍生版本的命名：Apache-2.0 不授予商标使用权，因此任何基于本项目的分支或二次开发，不得使用「DoboCache」作为其产品名或服务名，也不得暗示获得官方背书。注明「基于 DoboCache」是允许且欢迎的。