dsh-cache-helper

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

版本：0.3.2（2026-10-30）。 本版仅更新发行工作流和维护文档：GitHub Release 可通过 Actions OIDC 将同一冻结包发布到 npm，账号保留二次验证。安装产物及实际公开状态见 GitHub Releases 与 npm。

主会话与子任务触发风险时自动弹窗，多个请求共用一个弹窗；选择“稍后处理”后才显示居中铺满的“缓存失效待确认”侧栏入口，处理完毕或到期后自动隐藏。

本版保留有预算的持久分析缓存、选择历史会话的本地分析任务和原生子 Agent 保护。历史事实用于分析和展示，实时发送独立校验当前请求。“稍后处理”不批准发送，也不延长原有等待期限。

已验证宿主为 DSH 0.2.1-rc.2 的 web profile，Node 范围为 ^22.19.0 || >=24.0.0。此前公开的 0.3.0 tag 与原包保留，市场索引、本机安装来源及其他宿主版本分别核对。

原生子任务默认 childProtection: block：高风险请求等待可达浏览器确认，缺可信原生证据或确认入口时明确拒绝；需要只记录时可在设置改为 observe。原待确认请求不会因策略保存自动放行。派生缓存/分析任务不修改 Session 真源，不注册模型工具或注入 system；安装和重启请安排在任务间隙。回滚使用 v0.3.0 冻结包，保留原会话和配置。

功能

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

看板怎么用

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

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

在“会话明细”点“选择会话分析”，按标题/ID/目录、创建/活跃时间、主/子/人工分支、内存/历史和分析状态筛选。目录只读取元数据；缺少标题或活跃投影时显示 ID 或创建时间回退，未分析项的模型和异常保持未知。

勾选后可选择“包含子 Agent”，先点“预览分析范围”核对展开数量，再执行“分析所选”或“重新分析”。前者复用通过校验的结果，后者跳过结果缓存。普通人工分支不会自动加入子树；多次选择同一子任务会去重。进度中逐项显示缓存命中、完成、失败、超限或取消，已完成结果可独立查看；结果按固定水位计算，当前明细已更新时会显示不同的分析切点。

“取消分析”只退出这个分析任务，不停止 Agent、不回答缓存确认、不取消精简副本。关闭页面不停止已开始的本地任务，重连可继续查询；进程重启会将未完成任务标为中断，只有手动重试才继续。超过元数据、读取量或时间预算的项会明确标记，部分失败不拖垮整批。

主会话和子任务触发缓存风险时自动打开确认弹窗，并发请求在同一个弹窗内逐项处理。选择“稍后处理”后，侧栏才显示居中铺满的“缓存失效待确认”入口与数量；折叠侧栏保留图标和数量，重新打开可继续处理。相同候选不会因轮询反复弹出，新请求或候选变化会再次主动提醒。没有待确认请求时入口自动隐藏。父会话输入区同步显示子任务等待，停止结果继续留在父页面；从弹窗发起的停止操作会保留结果，直到手动关闭。

默认 childProtection: block：有可信原生 activation 和可达确认入口时暂停高风险子请求；缺少这些证据时明确拒绝高风险发送，避免父任务无限等待。可切换为 observe 仅记录风险。新 spawn 没有旧基线，多次/并发委派本身不会触发阻断；fork 首笔比较继承前缀，后续有自身回执才使用自身基线。“稍后处理”不批准、取消或重发请求，也不延长子请求原有的 120 秒期限。主会话单条弹窗仍可用 Escape 或关闭按钮取消本次发送；子任务/多条弹窗的关闭操作按“稍后处理”收起。

每条子请求最多等待 120 秒，断连/重连不会续期；到期只取消，不自动批准或重发。“停止此子任务”核对直接父归属和同一代际，最多观察 3 秒，分别显示正在停止、已静止、未确认静止或已有新输入；不会自动停止它的子任务。父任务停止不视为子树自动停止，仍有效的子请求可从全局队列在原期限内处理。

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

实际效果

下面是 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
childProtection: block

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

确认与数据保存

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

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

$DSH_HOME/storages/cache-helper/web-state.json 保存状态版本和用户收起的告警 ID，一次性发送确认不落盘。analysis-cache-v1/ 保存可丢弃的数值、hash、身份与有限比较事实；analysis-jobs.json 保存任务范围、水位、状态与恢复引用，不复制提示词、回答、完整工具定义、标题或 cwd。本插件的宿主投影只保留有界用量汇总；明细淘汰后仍可显示带水位的已知汇总，步骤、日期和模型覆盖明确缺失，未知不会补零。受控操作另在同目录 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、外部代理和网关内部追加的请求仍不在门禁内。仅有 subagent 标签不等于有可控制的原生 activation；身份不足的高风险原生请求会明确拒绝。

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

服务端 TTL、淘汰和缓存域实现不可由客户端精确观测；上下文不变也可能发生 miss。插件提供确认、原因线索和用户选择的精简副本，不自动修复服务端缓存。测试使用假上游，不要求发送真实付费模型请求。验证前缀仍可能读取/折叠完整日志；跨重启依赖语义未知或前缀变化会明确重建，单次宿主投影/规范化仍同步，极大会话可能有可感知开销。

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