dsh-cache-helper

dsh plugin --profile web add dsh-cache-helper

dsh-cache-helper

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

版本：0.3.3（2026-11-03）。 本版补齐风险弹窗的项目与会话身份，以“忽略该会话”替换精简副本入口，并修复附件比较与 Windows 事实缓存读取。实际公开版本见 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.2 冻结包；升级前保留 profile 与插件状态备份，旧版不继承 v2 的忽略/收起偏好。

功能

功能 · 行为

每轮末次缓存 · 在回答底部的“用量”后、时间前显示该轮最后一次实际模型调用的缓存读取 Token 和命中率；悬停查看步骤与精确值

发送前确认 · 上下文组装完成后比较上次实际请求的有效前缀；预计大规模损失时暂停，点击“确认并发送”才继续

WARN · 在输入框上方保留异常轮次、步骤、实际指标和差异线索；后续恢复命中仍保留记录，可展开、收起

缓存看板 · 在“设置 → 缓存看板”通过“概览 / 日期与模型 / 会话明细 / 设置”横向标签切换页面；回答尾部也有快捷入口

配置热更新 · 在看板的“设置”页编辑草稿、统一保存或恢复继承默认；新请求使用新策略，旧确认保留原策略

缓存专项统计 · 主/子/已记录辅助调用分组，支持最近 7 天、30 天、全部与模型筛选；日期与模型分布改用图表，未知及覆盖范围单列

忽略该会话 · 放行当前有效候选并持续跳过该会话的发送前检查；保留统计与历史告警，可在会话明细或设置恢复

本地分析缓存 · 重启先显示带水位的未校验缓存；校验日志前缀后复用事实，正常追加只规范化新调用，阈值变化只重算派生结果

选择会话分析 · 元数据筛选、多选、可选包含子 Agent；预览固定范围后本地串行分析，支持复用/重算、进度、取消与中断恢复

主/子请求确认 · 原生子任务按自身/继承回执比较；父页面与侧栏共享待确认队列，每条冻结候选单独确认或取消，支持有限观察的定向停止

Context 可选联动 · 通过公开会话导航与右栏接口打开会话级 Context；缺失、隐藏或不兼容时保留本页证据并提示降级

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

看板怎么用

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

页面 · 看什么、怎么操作

概览 · 看缓存读取、加权命中率、异常与恢复，以及主/子/辅助调用分组；未知用量和扫描范围分别说明

日期与模型 · 用日期柱状图和模型条形图比较调用分布；悬停查看对应日期、模型与精确读数，空数据明确显示

会话明细 · 查看已扫描统计，或点“选择会话分析”筛选更早历史、多选并预览固定范围；分析后查看步骤证据，也可打开 Context、忽略或恢复该会话检查

设置 · 保存缓存阈值与子任务保护模式，查看并清理分析缓存；切换标签不会替你保存草稿

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 服务。源码开发和候选生成见 [开发说明](docs/DEVELOPMENT.md)；用实际包路径替换下例：

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

配置 · 默认值 · 含义

minLostTokens · 50000 · 旧前缀损失估计的 Token 下限

minLossRatio · 0.2 · 损失占上次输入的比例下限

dashboardLimit · 50 · 按缓存的最近活跃信息最多扫描的主/子会话总数，最大 200；缺少投影时按创建时间回退并标注

maxEvents · 200000 · 单会话分析事件数上限；超限且存在历史基线时等待未知检查确认

maxCachedSessions · 64 · 内存中保留事实/派生结果的会话数，最大 200；另受事实字节预算限制

childProtection · block · 原生子 Agent 高风险请求阻断并确认；observe 只记录风险

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

确认与数据保存

• 单次确认绑定会话、冻结请求指纹和历史版本，只消费一次；其他会话和后续不同请求不能复用。显式“忽略该会话”另行保存持续偏好。
• 取消、关闭确认框、Escape、停止任务或卸载都会取消等待。断连不会自动放行，重连后可继续处理。
• 等待期间历史、请求头或消息投影发生变化，旧确认失效，需要重新发送并检查。
• 已确认的风险若实际发生 miss，仍会生成 WARN；恢复

…(truncated)