dsh-client-ui-cache-hit

DeepSeek Harness 侧边栏缓存命中率显示插件 / Sidebar cache hit-rate widget for DeepSeek Harness

一个纯浏览器端的 DeepSeek Harness 客户端插件：在侧边栏底部实时显示当前会话的 DeepSeek 上下文缓存命中率（命中 token ÷ 计费输入 token），包括分段堆叠条、命中率状态着色、以及最近一次请求的命中率。

A browser-only DeepSeek Harness client plugin: a sidebar-footer card that visualizes the current session's DeepSeek context-cache hit ratio (cache-read tokens ÷ billed prompt tokens) in real time — segmented stacked bar, rate-state coloring, and the latest-request hit rate.

---

功能特性 / Features

• 📊 侧边栏卡片：注册到 sidebar.footer.action 槽位，侧边栏展开时显示在底部。
• 🟢 分段堆叠条：命中（绿）/ 未命中（灰）/ 写缓存（蓝）三段宽度按 token 占比动态过渡。
• 🎨 命中率着色：≥ 70% 绿色、40%–70% 琥珀色、< 40% 红色。
• ⚡ 本次请求命中率：投影是累计值，插件用相邻两次快照的增量推导出最近一次请求的命中率，无需额外订阅。
• 💬 悬浮提示：显示命中 / 未命中 / 写缓存 / 输出 / 计费输入的 token 数与占比明细。
• 🌐 中英双语：随 DSH 界面语言自动切换。
• 🔘 插件面板开关：状态持久化在 localStorage（dsh.cache-hit.enabled），也可被「我的插件」面板统一管理。
• 🪶 零主机开销：host 侧入口为空操作，全部逻辑在浏览器端；不发起任何网络请求，数据全部来自本地会话投影。

---

工作原理 / How it works

插件订阅会话的 tokenUsage 投影（会话投影机制），其携带的是互斥的计费桶：

字段	含义
cacheReadTokens	缓存命中（读取）token
uncachedInputTokens	未命中（实付）输入 token
cacheWriteTokens	写缓存 token
outputTokens	输出 token

命中率 = cacheReadTokens / (cacheReadTokens + uncachedInputTokens + cacheWriteTokens)

• 百分比保留两位小数（如 96.42%、3.40%），低命中率也不会显示成误导性的 0%。
• 投影为会话累计值；相邻两帧的差值即最近一次请求自身的用量，插件据此显示「本次请求」命中率。
• 会话切换、同帧修正（chunk usage 被最终 usage 替换导致累计值回退）均被安全处理，不会闪烁错误数值。

---

安装 / Installation

需要：DeepSeek Harness（Web profile，即浏览器 GUI http://127.0.0.1:3080 所在服务）。 以下以便携版目录 <DSH>（含 data/profiles/web 与 data/profiles/node_modules）为例。

方式 A：让 AI 助手帮你装（推荐）

本插件就是为 DeepSeek Harness 设计的，最简单的方式是直接请 DSH 的 AI 助手安装：

1. 在 DSH 的会话里粘贴本仓库地址，例如：

   请帮我安装这个插件：https://github.com/sqs404/dsh-client-ui-cache-hit

2. AI 会替你完成全部安装步骤：把 lib/ 与 package.json 放进 profile 的 node_modules、在 cordis.patch.yml 的 insert 列表注册 ui-cache-hit、重启服务并验证加载。

3. 刷新浏览器页面，侧边栏底部就会出现「缓存命中率」卡片。

无需手动复制文件、改配置或重启。

方式 B：手动本地安装（备用）

1. 将本仓库的 lib/ 目录与 package.json 放入 profile 的 node_modules 对应路径：

   <DSH>/data/profiles/node_modules/@deepseek-ai/dsh-client-ui-cache-hit/
   ├── package.json
   └── lib/
       ├── index.js
       └── client.js
   

   也可以直接把整个仓库目录复制为 data/profiles/node_modules/@deepseek-ai/dsh-client-ui-cache-hit。

2. 在 <DSH>/data/profiles/web/cordis.patch.yml 的 insert 列表中加入一行（若已有则跳过）：

   - insert:
       - id: ui-cache-hit
         name: '@deepseek-ai/dsh-client-ui-cache-hit'
   

3. 重启 DSH 服务，刷新浏览器页面。

方式 C：包管理器安装（实验性）

在 profile 的 package.json 中把插件声明为 GitHub 依赖，然后执行 pnpm install（需本机装有 git 与 pnpm）：

{
  "dependencies": {
    "@deepseek-ai/dsh-client-ui-cache-hit": "github:sqs404/dsh-client-ui-cache-hit"
  }
}

安装完成后仍按方式 B 的第 2、3 步在 cordis.patch.yml 中启用并重启。

---

使用 / Usage

1. 选择一个会话（或新建会话并开始对话）。
2. 展开左侧边栏，底部出现「缓存命中率」卡片：
   • 标题行：左侧 缓存命中率，右侧为累计命中率百分比（按状态着色）。
   • 堆叠条：绿 = 命中，灰 = 未命中，蓝 = 写缓存；右侧为 命中 / 未命中 / 写缓存 的紧凑 token 计数（如 517 / 12.2K / 517K）。
   • 本次请求行：最近一次请求自身的命中率。
3. 悬停卡片查看完整明细 tooltip。
4. 在设置页的「我的插件」（插件面板）中可随时开关本插件。

未选择会话、暂无数据、或尚未产生计费输入时，卡片显示对应的占位文案。

---

兼容性 / Compatibility

• 浏览器端插件（dsh.client.platform: "web"），注入依赖：@deepseek-ai/dsh-client-runtime、@deepseek-ai/dsh-client-locale。
• 依赖 peer：react ^18.2.0、@deepseek-ai/dsh-client-web-react、@deepseek-ai/dsh-client-ui-primitives、@deepseek-ai/cordis（对应 DSH 0.1.0-rc.6 时代的客户端 API）。
• 纯前端实现：不发起网络请求、不触碰文件系统，读取的仅是宿主广播的 tokenUsage 会话投影。

---

仓库结构 / Repository layout

dsh-client-ui-cache-hit/
├── lib/
│   ├── index.js    # host 侧加载入口（空操作，仅占位）
│   └── client.js   # 浏览器端组件：卡片、堆叠条、tooltip、双语词典、面板总线注册
├── package.json    # DSH 客户端插件元数据（dsh.client 约定）
├── README.md
└── LICENSE         # MIT

开发 / Development

• 无构建步骤：lib/ 即发布产物，改完 lib/client.js 后复制进 profile 的 node_modules 并重启 DSH 即可。
• 命名空间：组件样式使用 dshCh- 前缀、词典命名空间为 cacheHit、面板条目 id 为 cache-hit，避免与其他插件冲突。

生态说明 / Ecosystem note

遵循 DeepSeek Harness 社区插件建议：插件托管在作者自己的 GitHub 仓库，并添加了 dsh-plugin topic 方便发现。

许可证 / License

MIT © 2026 sqs404