前言¶
用 DeepSeek Harness（DSH）跑长对话或带子代理的任务时，Provider 侧会累计 Token，上下文也会逐渐顶满窗口，但 Web 界面默认并不把「这一会话花了多少、缓存命中如何、高峰与空闲时段各占多少」集中展示出来。若只靠账单或零散日志，很难在开发调试时对照每一回合的消耗。
dsh-plugin-usage-insights（包名 dsh-usage-insights）是社区维护的纯展示插件：在 dsh web 右侧栏读取 Harness 已有的会话投影，展示单对话用量与跨对话汇总，不写入会话日志、不增加模型可见内容、不上传数据。下面介绍它的能力、安装方式与使用时的口径。
这是什么¶
维护者 Lyoko-Jeremie 在 GitHub 开源 dsh-plugin-usage-insights，目录页见 SkillHub。插件依赖 Harness 默认 Web 组合里已有的 token-meter 与 session-stats 投影，并在 Host 侧半注册 usageSteps、usageBands 两个投影，由客户端在右侧栏渲染「用量」与「用量汇总」两个页面。
核心功能¶
用量（当前对话）¶
会话概览包括请求数、Token 总量、输入 / 缓存读 / 输出（仅在提供商上报显式缓存写入时显示缓存写）、缓存命中率、费用，以及按 Token 与按请求各一行的峰谷比例。
缓存命中区用三条横条分别表示本会话累计、当前回合、最近一步的命中率；条形采用幂次刻度放大 90% 以上区间的差异，百分比保留三位小数并按阈值着色。
上下文窗口区展示已用 / 容量、占用进度条、占用与构成组合条、整窗构成条及图例；若 Host 能读到自动压缩阈值，会在相应位置标注（例如「自动压缩 50%」）。
另有峰谷圈图、会话指标（回合数、步数、每回合 Token、模型耗时、工具耗时、首字时间、解码速度），以及可展开的分步明细：主 agent 与直接子代理的请求合并为时间线，默认最近 30 条，可按请求实际发起时刻做峰谷计价。面板头部区分主 agent 与子 agent，主会话可展开查看各子代理的合计与明细；打开主会话用量页时，缺少峰谷聚合的子代理会自动补读（最多 20 个）。
用量汇总（全部对话）¶
支持最近 24 小时、今天、7 天、30 天、全部等区间切换；展示总 Token、对话数（含主 / 子拆分）、活跃天数、缓存命中率、费用，按 agent 类型分列，以及可展开的会话明细与峰谷比例。每日 Token 柱状图用颜色堆叠区分高峰与空闲时段；缺少分步数据的会话可自动或手动补齐。
数据与架构要点¶
usageSteps 保留最近 200 个请求（含开始时刻与峰谷），usageBands 按天 × 时段 × 模型聚合并保留 90 天与终身累计；二者经 Harness 投影缓存 checkpoint，重开对话、刷新页面或重启应用后可恢复。汇总页读取各会话投影，后台并行对话也会计入。
费用按插件内置价格表估算（元 / 百万 tokens，与 DeepSeek 官方峰谷规则及内置 2025–2026 节假日一致），不是官方账单；未配置价格的模型显示「未配置」。
环境要求¶
- DeepSeek Harness，使用 Web GUI（
dsh web）。 - 仅从源码构建时需要 Node.js 22+。
安装与启用¶
从 GitHub 安装：
dsh plugin install github:Lyoko-Jeremie/dsh-plugin-usage-insights
dsh web
从本地目录安装：
dsh plugin install /absolute/path/to/dsh-plugin-usage-insights
dsh web
安装后需要重启 dsh web：Host 要在启动时注册投影，仅刷新页面不会生效；随后再刷新页面以加载新的浏览器模块。升级时重新安装并同样重启 dsh web 再刷新页面。
典型用法¶
打开面板¶
- 输入框按钮：消息输入框工具行、模型选择器左侧的柱状图图标，点击后展开右侧栏并打开「用量」页（README 称这是最可靠的入口）。
- 右侧栏：展开右侧栏，点标签栏的
+，在指南页选择「用量」或「用量汇总」。
可选配置¶
在插件 config 中可调整步历史窗口、聚合保留天数、节假日与自动同步等，例如：
config:
stepHistory: 200
stepWindow: 200
bandDays: 90
compactionThreshold: 0.5
useBuiltinHolidays: true
holidays: []
holidayRanges: []
holidaySync:
enabled: false
urlTemplate: 'https://cdn.jsdelivr.net/gh/NateScarlet/holiday-cn@master/{year}.json'
years: []
timeoutMs: 4000
修改 src/client/config.ts 中的价格表后需执行 npm run build 重新生成 dist/client.js。
适用场景与注意¶
适合在本地或自托管 DSH Web 上长期调试 agent、对照缓存命中与上下文构成、估算峰谷时段费用，并跨会话做用量汇总。插件以当前 dsh 进程权限运行，安装前应自行查看仓库源码与 MIT 许可证。
需注意的口径：上下文构成来自启发式近似，不是计费值；压缩、标题生成等未写入 assistant/message 的辅助调用不会出现在分步明细；Agent Teams 成员与普通子代理在会话维度无法可靠区分，均按子代理统计；汇总在缺少分步数据时可能对峰谷费用产生区间估计。
结尾¶
dsh-plugin-usage-insights 把 Token、上下文、会话指标与跨对话汇总集中到 Web 右侧栏，数据全部来自 Harness 已有投影与插件本地计价规则，适合需要可观测用量又不想改动会话内容的场景。更多信息见 SkillHub 目录页 与 GitHub 仓库。
