dsh-cache-helper

dsh-cache-helper

为 DeepSeek Harness（DSH）显示实际缓存命中量，在发送前确认大规模缓存风险，并保留异常记录与会话统计看板。

当前公开版本：0.2.0（2026-10-24）。 GitHub Release 与 npm 均已公开，两个渠道的安装包与冻结产物逐字节一致。本版包含分页看板、即时图表提示、配置热更新、专项统计、精简副本与 Context 联动。已验证宿主环境为 DSH 0.2.1-rc.2 的 web profile；市场索引刷新、本机是否升级与公开发行分别核对，其他版本仍需验证。

功能

功能	行为
每轮末次缓存	在回答底部的“用量”后、时间前显示该轮最后一次实际模型调用的缓存读取 Token 和命中率；悬停查看步骤与精确值
发送前确认	上下文组装完成后比较上次实际请求的有效前缀；预计大规模损失时暂停，点击“确认并发送”才继续
WARN	在输入框上方保留异常轮次、步骤、实际指标和差异线索；后续恢复命中仍保留记录，可展开、收起
缓存看板	在“设置 → 缓存看板”通过“概览 / 日期与模型 / 会话明细 / 设置”横向标签切换页面；回答尾部也有快捷入口
配置热更新	在看板的“设置”页编辑草稿、统一保存或恢复继承默认；新请求使用新策略，旧确认保留原策略
缓存专项统计	主/子/已记录辅助调用分组，支持最近 7 天、30 天、全部与模型筛选；日期与模型分布改用图表，未知及覆盖范围单列
生成精简副本	把长会话历史归纳为摘要，在新副本继续；保留原会话，生成摘要会产生模型用量，完成后由你手动继续
Context 可选联动	通过公开会话导航与右栏接口打开会话级 Context；缺失、隐藏或不兼容时保留本页证据并提示降级

默认确认阈值是预计损失 至少 50,000 tok，且达到上次输入的 20%。首次冷启动正常放行；正常追加输入不算旧前缀损失。支持历史工具更新的模型按实际工具投影比较，新 deferred 工具在历史末尾激活时不会仅因声明列表变化就误报。

看板怎么用

从“设置 → 缓存看板”进入时默认显示概览，从回答尾部打开时直接查看当前会话。页面通过横向标签切换，避免把配置、统计和完整历史步骤堆在同一页。

页面	看什么、怎么操作
概览	看缓存读取、加权命中率、异常与恢复，以及主/子/辅助调用分组；未知用量和扫描范围分别说明
日期与模型	用日期柱状图和模型条形图比较调用分布；悬停查看对应日期、模型与精确读数，空数据明确显示
会话明细	搜索会话，切换“只看异常”，对照具体轮次和步骤的实际用量、变化线索及恢复状态；可打开 Context 或预览精简副本
设置	修改缓存策略草稿，统一保存或恢复继承默认；切换看板标签不会替你保存草稿

Token 缩写统一使用大写 K（千）和 M（百万），详细读数保留精确值。看板不再显示“分析建议”；异常步骤中的实际指标与变化证据继续保留。

长会话中应把插件安装、移除、启停和更新集中在任务间隙。改变模型可见的工具清单、定义或顺序可能破坏前缀缓存，使旧历史重新按未缓存输入计费。本插件不注册模型工具或注入提示词，但不能阻止其他插件改变请求前缀。

实际效果

下面是 0.1.2 的历史展示，来自作者授权公开的真实会话“DeepSeek Harness 插件依赖修复与回滚”。第 15、16 轮首步的缓存命中率分别降至约 0.4% 和 1.4%；第 16 轮末次调用已恢复至 99.69%，WARN 仍保留异常记录。

独立看板按会话列出异常轮次、步骤与当时观察到的工具声明变化。图中目录和会话标识已遮挡；顶部统计覆盖已扫描会话，右侧表格是所选会话。

每轮末次调用的缓存量与命中率放在原生用量后、时间前；历史 WARN 保留在输入框上方。

原因栏是本地上下文对比线索，不是服务端缓存失效原因的确定证明。

指标口径

缓存量是该次 response 的 cacheReadTokens，表示实际读取的缓存 Token。缓存率为：

cacheReadTokens / (inputTokens + cacheReadTokens + cacheWriteTokens)

DSH 的 inputTokens 是未缓存输入，输出不进分母。回答尾部只取所属轮次末次实际调用，不把步骤累加，也不使用其他轮次的读数。末次回执缺少缓存字段时显示“未知”，不回退到此前的已知值。看板的累计率使用各次输入量加权。

例如，某轮末次调用读取缓存 90,000 tok、未缓存输入 10,000 tok、缓存写入 0 tok，该轮显示 末次缓存 90K tok · 90%。这不是服务端当前缓存容量，也不是会话累计缓存量。

预计前缀损失使用字符位置和上次实际用量校准，属于估计。实际未命中告警会扣除可解释的新增输入影响；观察到的工具、system 或历史变化仅作为原因线索。

安装

需要 Node.js 22.19 或更新的 22.x，或 24 及以上版本，与锁定宿主的范围一致；还需已安装的 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 所需依赖已在本机缓存；依赖不齐时安装会失败。记录缺失依赖，再按自己的包源策略处理。不要为安装候选包绕过版本检查或自动批准额外构建脚本。

打开 DSH 启动输出提供的本机认证地址。登录链接中的 token 只保留在本机，不放进截图、问题反馈或 Git。安装、升级后重启 web 并刷新页面，再检查插件入口和读数。当前文档不提供桌面 profile 的安装步骤。

配置

进入“设置 → 缓存看板”，切换到看板的“设置”标签，在缓存策略表单编辑草稿，点击“保存配置”统一持久化并热生效。恢复继承默认会清除用户覆盖，不写死一组默认数字；保存失败或并发冲突时保留草稿，可重新读取。保存后历史诊断按新策略重算，原始 usage 不变，减少告警不能作为缓存改善。

也可在 web profile 配置插件 ID cache-helper；手动编辑文件后按宿主的配置加载方式生效：

- 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

看板按 Asia/Shanghai 的已记录调用时间筛选：摘要有明确 stream 开始回执时优先用开始时间，其他历史使用结算回执时间，缺少时间保持未知；默认最近 7 个自然日，可切 30 天或全部。辅助调用归属所在会话，继承记录供上下文比较但不重复计入全局用量；失败/取消摘要的已知开销由操作回执补充并与 Session 去重。缺时间、缺缓存字段、归属未知、未记录辅助调用与读取失败分别展示，达到扫描上限不表示所有历史会话都已分析。会话列表保留完整历史累计，步骤表按所选时间和模型筛选。

确认与数据保存

• 确认绑定会话、冻结请求指纹和历史版本，只消费一次；其他会话和后续不同请求不能复用。
• 取消、关闭确认框、Escape、停止任务或卸载都会取消等待。断连不会自动放行，重连后可继续处理。
• 等待期间历史、请求头或消息投影发生变化，旧确认失效，需要重新发送并检查。
• 已确认的风险若实际发生 miss，仍会生成 WARN；恢复命中只标记恢复，不删除该次异常。
• 大上下文的输入投影未知，或无法可靠判断比较规模时，要求人工确认；有可信规模且低于阈值的请求可放行，不把未知指标补成正常命中。

Session 是上下文与用量的事实源。插件不另存完整请求、响应或提示词，不改写普通模型请求，不读取模型凭据，也不新增外部服务。用户明确选择生成精简副本时，使用宿主压缩服务调用摘要模型，产生模型用量。

服务端仅在 $DSH_HOME/storages/cache-helper/web-state.json 保存状态版本和用户收起的告警 ID；WARN 和指标从 Session 重建，一次性确认不落盘。受控操作另在同目录 operations-state.json 保存操作 ID、来源/分支 ID、路由、状态、策略快照与摘要回执等恢复元数据；不保存正文或提示词。重启将未完成操作标为中断，不自动重试或续发。浏览器在 localStorage 的 dsh-cache-helper.only-warnings.v1 保存异常筛选布尔值，设置页与快捷看板共用，并在同源标签页间同步。存储受限时使用当前页面的内存状态。

精简副本与 Context

长会话里有很多已经完成的过程时，可以把这些历史归纳为摘要，再从一个精简副本继续工作。原会话保留，便于回看完整记录；这不会自动修复服务端缓存，也不保证下一次请求的命中率。

在“会话明细”选择目标会话，点击“生成精简副本”先查看说明和可用状态。预览不会创建副本或调用摘要模型。只有点击“创建副本并生成摘要”才会停止旧尝试、等待空闲、创建并保存新分支，再调用宿主摘要模型。生成过程中可点击“取消生成”；已经创建的副本和已产生的用量会保留。结果中会显示实际模型、用量和耗时；生成摘要会产生模型用量，原消息不会自动续发。

首版仅支持已激活的主会话；离线历史可以查看统计，缺少可用 Agent 时无法生成副本，插件不会替你发送唤醒消息。排队输入需要先处理；已接纳的输入只继承一份，输入框草稿不自动复制，原有工具调用不重放。

分支使用公开 Agent 选项与最新请求头中的 provider/model 等路由；尚未入日志的私有 UI 选择无法读取。摘要采用宿主压缩配置，结果显示实际模型、usage 和耗时。缺少可恢复持久化能力时不可执行；取消、来源变化、摘要失败或落盘未确认会保留可用的分支/预留 ID 和明确状态，不自动重复副作用。

“分支与摘要已生成”、上下文估计变化、后续实际缓存恢复分别展示。压缩后的预期重建只有实际历史替换证据才单列；缺少后续回执时保持待观察，不宣称精确节省金额。检查摘要后，点击结果页的“打开副本，手动继续”进入新副本，由你决定下一条消息。

Context 联动需要 dsh-context 的公开右栏注册、宿主会话导航与右栏服务。只打开目标会话，不承诺精确步骤跳转；不存在或已隐藏的面板不会自动安装或启用，也不通过 DOM 或私有状态强行跳转。

停用、卸载与回滚

先停止当前任务或取消待确认请求，再在 web 的设置 → 插件管理 中停用本插件；重启 web，确认入口已消失。停用期间后续模型请求不再受本插件的确认门禁保护。

完整卸载时先关闭 web，再执行：

dsh plugin --profile web remove dsh-cache-helper --config.offline=true

随后重启 web 并刷新页面。卸载撤销插件拦截和界面节点，并取消当前压缩任务；已创建的分支和原 Session 不删除。插件的告警收起状态可保留在本机；若手工删除该状态文件，历史告警仍可从 Session 重建。

升级前保存上一份已验证的 .tgz 和配置差异。需要回滚时，停止 web、卸载当前候选，再从本机安装已保存的旧包：

dsh plugin --profile web add /absolute/path/dsh-cache-helper-PREVIOUS.tgz --offline
dsh --profile web --port 3099

PREVIOUS 是所保存包的版本占位符；只有实际保留并验证过的旧包才能据此回滚。回滚后核对配置兼容性、末次缓存读数和确认流程。版本切换放在任务间隙进行。

验证与限制

已有本地测试通过真实 Cordis、AgentLoop、LlmRuntime 和 DeepSeekAdapter 向假上游发送 HTTP，覆盖显式确认、取消、停止、卸载、确认过期和会话隔离；输入重建与生产适配器序列化结果进行过逐字段比较。浏览器回归覆盖每轮末次值、页脚顺序、WARN、设置页看板、异常筛选、窄窗和暗色布局。每个候选的实际测试结果仍需按 发布准备流程 重新记录。

当前门禁覆盖原生 AgentLoop 主会话各步骤和正常用户 fork；排除辅助 purpose 调用、origin=subagent 或有 delegationDepth 的子会话。外部代理和网关内部追加的请求不在该门禁内。

已验证默认 DeepSeek Messages 的文本路径。图片、文件和其他适配器尚未完成等价证明，按未知检查处理。旧 Session 没有完整记录所有适配器配置，默认 Flash 历史按已核查的标准 addition-only 行为投影；定制同名模型的历史策略可能无法确认。

服务端 TTL、淘汰和缓存域实现不可由客户端精确观测；上下文不变也可能发生 miss。插件提供确认、原因线索和用户选择的精简副本，不自动修复服务端缓存。测试使用假上游，不要求发送真实付费模型请求。极大会话在新增回执后重分析仍可能产生可感知开销。

变更记录 · 开发说明 · 发布准备 · MIT 许可证