前言¶
在 DeepSeek Harness（DSH）里跑长会话时，上下文前缀缓存能显著降低重复输入的计费；但一旦工具清单、历史投影或 system 发生变化，整段前缀可能一次性失效，而界面上的用量数字往往只反映「这一轮末次调用」，很难在发送前判断「这次会不会把上次攒下的缓存打没」。社区插件 dsh-cache-helper（维护者 ghang，当前版本 0.1.2）面向 web profile，在回答尾部展示末次实际缓存读数与命中率，在组装完上下文后按阈值拦截大规模前缀损失风险，并保留 WARN 与会话级缓存看板，便于对照 Session 里的真实用量回执做排查。
这是什么¶
dsh-cache-helper 是 DSH 的缓存助手插件：展示 cacheReadTokens 与命中率、发送前确认预计大规模缓存失效、记录异常轮次并提供「设置 → 缓存看板」中的会话统计与步骤明细。插件不注册模型工具、不注入提示词，也不改写模型请求；Session 仍是上下文与用量的事实源。文档已验证的宿主为 DSH 0.2.1-rc.2 的 web profile，其他版本需自行验证。预构建包见 GitHub Releases；目录页：skillhub.cn/plugins/ghang/dsh-cache-helper。
核心功能¶
下面按 README 中的行为表归纳四项能力。
每轮末次缓存¶
在回答底部的「用量」之后、时间之前，显示该轮最后一次实际模型调用的缓存读取 Token 与命中率；悬停可查看步骤与精确值。口径上只取所属轮次末次调用，不把多步累加，也不混用其他轮次；末次回执缺少缓存字段时显示「未知」，不回退到更早的已知值。
发送前确认¶
上下文组装完成后，插件会比较上次实际请求的有效前缀；当预计损失达到阈值时会暂停发送，需点击「确认并发送」才继续。默认阈值为：预计损失至少 50,000 tok，且达到上次输入的 20%。首次冷启动正常放行；仅追加用户输入不算旧前缀损失。对支持历史工具更新的模型，按实际工具投影比较；新 deferred 工具在历史末尾激活时，不会因声明列表单独变化而误报。
WARN¶
在输入框上方保留异常轮次、步骤、实际指标和差异线索（工具、system 或历史变化等本地对比线索，不是服务端失效的确定证明）。后续即使恢复命中，记录仍保留，可展开或收起。
缓存看板¶
在「设置 → 缓存看板」查看会话累计指标与步骤明细，支持搜索、异常筛选和翻页；回答尾部也有快捷入口。看板会标明扫描范围、失败数与未知用量；达到扫描上限不表示所有历史会话都已分析。
指标口径（阅读读数前建议先看）¶
缓存量为该次 response 的 cacheReadTokens。缓存率为：
cacheReadTokens / (inputTokens + cacheReadTokens + cacheWriteTokens)
DSH 的 inputTokens 为未缓存输入，输出不计入分母。看板累计率对各次输入量加权。预计前缀损失用字符位置与上次实际用量校准，属于估计；实际未命中告警会扣除可解释的新增输入影响。
安装与启用¶
需要 Node.js 22 或更新，以及已安装的 DSH CLI。从 Releases 下载对应版本的 dsh-cache-helper.tgz 与 SHA256SUMS，在两者所在目录校验完整性：
shasum -a 256 -c SHA256SUMS
首次试用建议只装到 web：先结束当前任务并停止 web 服务，再用实际包路径替换下例中的路径：
dsh plugin --profile web add /absolute/path/dsh-cache-helper.tgz --offline
dsh --profile web --port 3099
--offline 要求 DSH 所需依赖已在本机缓存；依赖不齐时安装会失败。打开启动输出中的本机认证地址登录；链接中的 token 勿写入截图或公开反馈。安装或升级后重启 web 并刷新页面，检查插件入口与读数。当前文档未提供桌面 profile 的安装步骤。
长会话中，安装、移除、启停和更新宜集中在任务间隙。改变模型可见的工具清单、定义或顺序可能破坏前缀缓存；本插件不能阻止其他插件改变请求前缀。
配置¶
通过 DSH web profile 覆盖插件 ID cache-helper，保存后重启 web：
- id: cache-helper
config:
minLostTokens: 50000
minLossRatio: 0.2
dashboardLimit: 50
maxEvents: 200000
maxCachedSessions: 64
| 配置 | 默认值 | 含义 |
|---|---|---|
minLostTokens |
50000 | 旧前缀损失估计的 Token 下限 |
minLossRatio |
0.2 | 损失占上次输入的比例下限 |
dashboardLimit |
50 | 按创建时间从新到旧最多扫描的主会话数（最大 200） |
maxEvents |
200000 | 单会话分析事件数上限 |
maxCachedSessions |
64 | 内存中保留派生指标的会话数（最大 200） |
典型用法与交互¶
- 正常对话后，在每条回答尾部查看「末次缓存」读数与命中率，判断该轮最后一步是否仍吃满前缀缓存。
- 当上下文变化较大、即将发送时，若触发门禁，阅读确认框中的预计损失说明，选择「确认并发送」或取消；取消、关闭框、Escape、停止任务或卸载都会取消等待，断连不会自动放行。
- 输入框上方出现 WARN 时，展开查看轮次、步骤与原因线索；需要跨会话汇总时打开「设置 → 缓存看板」，用异常筛选定位问题轮次。
确认绑定当前会话与请求指纹，只消费一次；等待期间若历史或投影变化，旧确认失效，需重新发送。已确认的风险若实际发生 miss，仍会生成 WARN；恢复命中只标记恢复，不删除该次异常。
数据保存与隐私边界¶
服务端仅在 $DSH_HOME/storages/cache-helper/web-state.json 保存状态版本与用户收起的告警 ID；WARN 与指标从 Session 重建，一次性确认不落盘。浏览器在 localStorage 的 dsh-cache-helper.only-warnings.v1 保存异常筛选开关。插件不另存完整请求、响应或提示词，不读取模型凭据，也不新增外部服务。
停用、卸载与回滚¶
先停止任务或取消待确认请求，在 web → 设置 → 插件管理 中停用；重启 web 确认入口消失。完整卸载先关闭 web，再执行：
dsh plugin --profile web remove dsh-cache-helper --config.offline=true
升级前保留上一份已验证的 .tgz。回滚时停止 web、卸载当前包，再安装旧包：
dsh plugin --profile web add /absolute/path/dsh-cache-helper-PREVIOUS.tgz --offline
dsh --profile web --port 3099
PREVIOUS 为所保留旧包的版本占位符；回滚后核对配置、末次缓存读数与确认流程。
适用场景与注意¶
适合在 DSH web 下长期使用 Agent、工具较多的会话，需要发送前感知大规模前缀损失，并在 miss 后保留可检索的 WARN 与看板线索。README 说明当前门禁覆盖原生 AgentLoop 主会话各步骤与正常用户 fork，排除部分辅助 purpose、子代理会话等；图片、文件与其他适配器路径按未知检查处理。服务端 TTL 与缓存域实现无法由客户端精确观测，上下文不变也可能 miss——插件提供确认与线索，不自动修复服务端缓存。
插件以当前 dsh 进程权限运行；安装前应阅读源码与 MIT 许可证，从 Releases 校验包完整性后再 --offline 安装。社区目录 skillhub.cn 与 DeepSeek / 幻方无官方从属关系，DSH 生态理念是「一切皆插件」，本介绍不代表官方背书。
结尾¶
dsh-cache-helper 把缓存命中从「偶尔看一眼用量」变成「每轮末次可见、发送前有门槛、异常可回看」的三段式工作流，适合在意长会话缓存成本与前缀稳定性的 DSH 用户。进一步了解可访问目录页 ghang/dsh-cache-helper 与仓库 github.com/ghang/dsh-cache-helper。
