前言¶
在 DeepSeek Harness（DSH）里跑 Agent、长对话和工具调用时，Token 会分散在大量会话日志里。宿主界面侧重对话与任务，一般不会把「近 30 天用了多少、缓存命中率如何、各模型占比、输出速度与首 Token 是否变慢」集中展示在一页。若只靠肉眼翻会话或外部脚本统计，口径难统一，也谈不上按日、按小时对比。
下面介绍社区插件 dsh-usage-panel（维护者 chunrichi，分类：客户端）：在 Harness 侧边栏增加入口，用整页看板对本机会话日志做实时聚合，不联网、不读价格与账户余额，适合需要本地掌握用量与性能趋势的开发者。
这是什么¶
dsh-usage-panel 是 DSH 的本地优先 Token 用量看板插件。它在侧边栏「插件」入口旁增加看板图标，主面板以全局时间作用域（今日 / 7 天 / 30 天 / 90 天 / 全部，以及月历任选一天）驱动下方所有区域；数字均来自本机 assistant/message 事件中的 usage 及 Host 侧对会话日志的扫描与快照，不做网络请求。
仓库：https://github.com/chunrichi/dsh-usage-panel
目录页：https://www.skillhub.cn/plugins/chunrichi/dsh-usage-panel
当前 package 版本为 1.1.0，许可证 MIT；环境要求为 DeepSeek Harness Desktop（Web UI profile）与 Node.js >= 20。
核心功能¶
看板各区域在切换时间作用域后一并更新，作用域在切走面板再返回时仍会保留。
| 区域 | 作用 |
|---|---|
| 时间作用域 | 顶部 sticky 条：分段选择今日 / 7 / 30 / 90 天 / 全部，「日期」打开自绘月历选任意一天；有用量日期带圆点，可选范围受快照窗口限制（默认最近 182 天） |
| 读数条 | 五张卡随作用域变化：区间模式含近 N 天 Token、较前 N 天、峰值单日、加权输出速度、缓存命中率；单日模式为当日指标与较前一日；全部模式为全历史总量、活跃日均、峰值与全历史速度/命中率 |
| Token 构成 | 输入（未命中缓存）、缓存命中、缓存写入、输出的堆叠比例与逐项计数、占比 |
| 模型占比 | 当前作用域按 Token 降序的模型份额（含 provider 标签）；区间与单日另有按日模型表 |
| 趋势与性能 | 双轴组合图：左轴 Token 柱（区间/全部按本地日，单日按小时），右轴各 provider 的「速度」或「首 Token」中位数折线；共享 tooltip 与方向键逐日/逐小时浏览 |
| 活跃热力图 | 最近 119 天逐日方格，区间外压暗；点击方格可将整块看板切换到该日 |
数据口径要点（与 README 一致）：
- 一次读数对应一条
assistant/message的data.usage；prompt = input + cacheRead + cacheWrite，tokens = prompt + output；cacheHitRate = cacheRead / prompt。 - 输出速度与 Chat 面板 detailed 模式 tok/s 同口径；首 Token 为「首个 token 时间 − step/start」；组合图性能线按本地日期 × 小时 × provider 取中位数。
- 页脚展示更新时间、扫描会话数与不可读会话数；空数据、读取失败、同步失败有独立状态文案。
Host 侧可通过 historyDays（默认 182，7–365）控制 daily[]、组合图、热力图与日历回看窗口；maxSessions（默认 800，1–5000）限制最多扫描的会话数（按 createdAt 取最新）。
安装与启用¶
仓库已提交构建产物，从 GitHub 安装不需要本地构建。
方式一：DSH CLI（推荐）
在任意目录执行（web 换成你的 profile 名）：
dsh plugin --profile web add github:chunrichi/dsh-usage-panel
固定版本可带 ref，例如：
dsh plugin --profile web add github:chunrichi/dsh-usage-panel#v1.1.0
切换版本时先移除再重新 add：
dsh plugin --profile web remove dsh-usage-panel
方式二：Harness 插件管理页或 Agent
desktop profile 推荐在应用内安装以便热应用：
plugin_manager action=install_bundle target=github:chunrichi/dsh-usage-panel
说明：
- CLI 会在
$DSH_HOME/profiles/<profile>下通过 pnpm 安装，并把dsh-usage-panel写入该 profile 的dsh.profile.bundles，下次启动生效。 desktop为 Desktop 保留 profile：若用 CLI，需完全退出 Desktop，并使用 Desktop 自带 CLI（macOS：DeepSeek Harness.app/Contents/Resources/runtime/cli/bin/dsh）；普通 npm 安装的dsh操作desktopprofile 会被拒绝。应用内安装则立即热应用。- 安装成功后侧边栏面板列表会出现看板图标；若界面未更新，刷新窗口即可。
本地改代码时（README 方式二）：将插件目录以绝对路径交给 install_bundle，依赖以 link: 接入，改 Host 后重新 install_bundle，改客户端刷新窗口即可。本文不展开 clone 步骤。
可选 Host 配置示例（写入 bundle patch 的 config）：
- insert:
- id: usage-panel
name: dsh-usage-panel
config:
historyDays: 182
maxSessions: 800
典型用法¶
- 按上文命令为目标 profile 安装插件并启动（或刷新）Harness。
- 在侧边栏点击紧邻「插件」的看板入口，中栏整页打开用量面板。
- 用顶部作用域条选择「近 30 天」等区间，查看读数条、Token 构成与模型占比是否符合预期。
- 在「趋势与性能」中切换「速度 / 首 Token」，用 tooltip 对照某日 Token、调用次数与各 provider 样本。
- 点击热力图某一天，或点「日期」在月历中选日，进入单日视图查看按小时柱线与峰值时段；非今日单日时，标题栏或日历底部可用「回到今天」。
- 需要更长历史或更多会话时，在 Host
config中调整historyDays/maxSessions后按 DSH 方式重新加载 bundle。
再次点击其它侧边栏面板即可回到原会话；看板作用域状态在模块级保留，重进看板不会丢当前区间或所选日期。
适用场景与注意¶
适合谁：长期在 DSH 本机跑 Agent、希望用统一口径观察 Token 总量、缓存结构、模型分布，以及 provider 速度与首 Token 中位数趋势的开发者；强调隐私与离线聚合、不需要云端账单对接的场景。
务必注意：
- 插件以当前 DSH 进程权限读取本机会话日志；安装前请自行查看仓库源码与 MIT 许可证，确认符合你的安全与合规要求。
- 所有统计仅反映本机已持久化的会话；
maxSessions截断时页脚会提示，更早会话不会进入快照。 - 更早日志若无 durable stream 时间，可能只参与速度统计、不参与首 Token，对应折线可能显示「无样本」。
- SkillHub 等社区目录为独立站点，与 DeepSeek / 幻方无官方从属关系；插件由社区维护，星标与版本以仓库与目录页为准。
结尾¶
dsh-usage-panel 把 DSH 会话里的 Token 与性能信号收拢到一页：全局时间作用域、构成与模型占比、热力图，以及 Token 柱与 provider 性能线共用的组合图，全部本地聚合、不碰账户与定价 API。若你已在用 Harness Desktop 并希望量化自己的用量与响应表现，可按 README 安装后在侧边栏打开看板试用。
