前言¶
用 DeepSeek Harness（dsh）跑智能体任务时，步数、轮次、吞吐、缓存命中、上下文占用这些数字都挤在 web UI 原有的 stats 行里。信息在，但都是平铺文本，长任务跑到一半想快速回答「现在吞吐多少、上下文还剩多少、缓存效率如何」，得逐个读数。
dsh-stats-hud 解决的就是这个读数问题：它把会话统计渲染成一块固定在页面最右缘的竖排面板，用等级条、速度表和滚动计数器呈现，同时不动原有 stats 行。下面介绍它的功能、安装方式和工作原理。
这是什么¶
dsh-stats-hud 由 lauytgary 维护，MIT 许可证，分类为客户端（web 端）插件。一句话定位：把 DSH 会话统计行变成游戏风格的等级条、速度表和滚动 token 计数器，竖排显示在 dsh web UI 最右侧。它是纯浏览器侧插件，不改宿主代码，数据全部来自宿主已有的 projections。
面板上的仪表¶
- CLOCK 徽章：本地 24h 时间，附 DS API PEAK / OFF PEAK 峰谷标识。峰值为北京时间周一至五 09:00-12:00 / 14:00-18:00，周末恒为 OFF-PEAK。
- STEPS / TURN 滚动里程表：数字鼓轮样式，挂载时上卷，数值变化时滚动，进位按 9→0 处理。
- LLM / TOOLS 双条形：两列布局，标签在值上方；条形分段按原始 LLM:TOOLS 时间比例划分，无上限，时间比例直接映射为条形比例。
- THROUGHPUT 仪表盘：tokens/s 读数居中显示，红线初始 200，按 100 tok/s 步进自动扩展。
- CONTEXT USAGE 条：按 token 比例分三段——Sys Prompt（灰）/ Tools（蓝）/ Messages（紫）；占用 ≥80% 时整条变红；悬停弹出 tooltip，显示三类 token 明细。
- CACHE HIT 条：<50% 红、<80% 黄、≥80% 绿。
- CONTEXT 滚动计数器：三行里程表——CACHE HIT（绿）/ CACHE MISSED（橙）/ OUTPUT（粉）。
agent 运行期间，整个面板有呼吸效果，条形随之脉动。
响应式布局¶
面板按右侧空闲空间分三档，用 ResizeObserver 实时测量：
| 档位 | 条件 | 显示内容 |
|---|---|---|
| full | 窗口 ≥800px 且空闲 ≥180px | 全部仪表 |
| mini | 窗口 ≥800px 但空闲 <180px | 时钟（短 PEAK / OFF PEAK 徽章）+ 紧凑滚动行 |
| hidden | 窗口 <800px | 不显示（display:none） |
窗口宽度 <800px 是硬性下限；测量失败时回退到 full。mini 档在窄窗口下可能轻微遮挡聊天列，但面板可点击穿透，不影响操作。
安装与启用¶
从 GitHub 安装：
dsh plugin --profile web add https://github.com/lauytgary/dsh_hud_plugin
或从本地路径安装：
dsh plugin --profile web add /path/to/dsh-stats-hud
安装后重启 dsh web（loader 条目在启动时扫描），再刷新页面，插件会出现在 Settings → Plugins。依赖要求：DeepSeek Harness dsh（在 0.1.0-rc.6、macOS 上测试过）和 pnpm（用于插件管理）。
注意一个细节：仓库地址是 lauytgary/dsh_hud_plugin，插件名是 dsh-stats-hud，两者不一致，卸载时用插件名：
dsh plugin --profile web remove dsh-stats-hud
工作原理¶
1、插件注册到 conversation.composer.dock 槽位（id dsh-stats-hud，order 1）；面板本身 position: fixed，不占布局空间，原 stats 行保持不变。
2、数据来自宿主既有 projections：sessionStats、tokenUsage、contextPressure、contextBreakdown，零宿主侧改动。
3、exports.inject = ["slots"] 是必需项：DSH 的 ctx 是严格代理，访问未声明的服务会直接抛错。
4、整个面板 pointer-events: none，可点击穿透；仅 CONTEXT USAGE 条恢复指针事件，以支持悬停 tooltip。
开发与测试¶
lib/client.js 是手写的 loader bundle（window.__ModuleLoader__.load），无需构建步骤。插件以 link: 依赖安装，本地编辑 lib/client.js 后只需重启，不用重装。
运行测试：
npm test
测试基于 node:test，零依赖，要求 Node ≥ 18。测试专用的 __test 导出由 DSH_HUD_TEST 环境变量控制，浏览器包不受影响。
如果想发布到 npm：移除 package.json 中的 private 后执行 npm publish，之后用户可用 dsh plugin --profile web add dsh-stats-hud 安装。当前默认未发布到 npm，安装走 GitHub 或本地路径。
适用场景与注意¶
适合长期盯着 dsh web 跑任务、希望更快读出吞吐、缓存和上下文状态的人。如果你只想偶尔看一眼，原 stats 行仍在，装了插件也不破坏任何原有布局。
两点提醒：mini 档在窄窗口下可能轻微遮挡聊天列（点击穿透所以安全）；插件以当前 dsh 进程权限运行，安装任何第三方插件前都应检查源码与许可证，本插件采用 MIT。
结尾¶
dsh-stats-hud 展示了 DSH「一切皆插件」的一种典型做法：不动宿主一行代码，把已有数据换成更易读的呈现。源码与文档见 GitHub：https://github.com/lauytgary/dsh_hud_plugin；也可在社区目录查看：https://www.skillhub.cn/plugins/lauytgary/dsh_hud_plugin（社区维护的独立站点，与 DeepSeek、幻方无官方从属关系）。
