前言¶
在 DeepSeek Harness（DSH）里跑多轮对话、多项目切换时，Token 消耗、API 调用次数和缓存命中往往分散在各次会话日志里，很难一眼看清「最近一周用了多少」「哪个工作目录最费 Token」。DSH-TokenDashboard 是面向 DSH 的客户端插件，从当前 Profile 的本地会话日志只读汇总数据，在原生侧栏里展示用量仪表盘，无需额外构建、无运行时依赖、也不使用额外 API Key。
这是什么¶
插件 npm 包名为 @ningtian-byte/dsh-tokendashboard，GitHub 仓库为 NingTiAn-byte/DSH-TokenDashboard，维护者为 NingTiAn-byte，分类为客户端插件。官方简介：面向 DeepSeek Harness 的本地 Token 用量、API 调用与缓存统计仪表盘（local-first token usage and API call dashboard）。
数据全部来自本机已有会话记录；插件不修改日志、不调用模型 API、不上传用量。摘要中的模型名、会话 ID、工作目录会留在内存供界面展示，不保留提示词与回复正文。
核心功能¶
下面按 README 中已列能力归纳，均可在安装后于侧栏 Usage statistics（用量统计）入口使用。
总览指标
- 总 Token、API 调用次数、未缓存输入、输出、缓存读取、缓存命中率
- 汇总区间可选最近 7、30、90 天或全部时间，并显示活跃会话数
可视化与排行
- 活动日历：52 周方格视图，悬停或键盘聚焦可看当日精确数值
- 每日缓存趋势：堆叠展示输入 Token（未命中在下方、命中在上方），纵轴支持紧凑 K/M/B 标签；趋势图可拖动选择最近 7–30 天，与顶部汇总区间相互独立
- 按模型/提供商与工作目录的 Token 排行与 API 调用次数
界面与刷新
- 跟随 DSH 明/暗主题，响应式布局，支持英文与简体中文
- 可手动刷新，或每 30 秒自动刷新；页面隐藏时暂停轮询
安装与启用¶
安装命令须使用资料原文。Web 环境可用 DSH 自带 CLI：
dsh plugin --profile web add @ningtian-byte/dsh-tokendashboard
也可从 GitHub 安装：
dsh plugin --profile web add github:NingTiAn-byte/DSH-TokenDashboard
桌面端请使用 Desktop 应用捆绑的 CLI：
dsh plugin --profile desktop add github:NingTiAn-byte/DSH-TokenDashboard
若下载 ZIP 解压到本地目录，可通过插件管理器或 CLI 指向含 package.json 的绝对路径安装，例如：
dsh plugin --profile web add "/absolute/path/to/DSH-TokenDashboard"
Windows 下可使用 C:/plugins/DSH-TokenDashboard 等形式；路径含空格时需加引号。若系统 PATH 中没有 dsh，需使用已安装的 DSH 可执行文件；源码侧 CLI 可能不接受 Desktop profile，桌面安装应使用 Desktop 捆绑 CLI。
安装后重启 DSH，在侧栏选择 Usage statistics。已有完成请求会自动出现，无需为了统计再发起一次模型请求。
兼容性说明（来自 README）：需要 DSH 提供 sessionPersistence、connection、slot、locale、theme 等 API；不同 DSH 版本插件 API 可能变化，需与当前安装版本核对。
典型用法¶
- 在仪表盘顶部选择汇总区间；顶部数字与排行榜随区间变化。
- 日历格或趋势柱上悬停/聚焦查看当日用量与 API 次数；按 Escape 关闭提示。
- 拖动趋势滑块查看最近 7–30 天（「一个月」为滚动 30 天窗口）；改汇总区间不会重置趋势缩放。
- 在页面底部开关自动刷新。
统计口径说明¶
理解数字时建议对照 README 中的定义表：
| 指标 | 含义 |
|---|---|
| 总 Token | 优先用提供商报告的 totalTokens；否则为未缓存输入 + 输出 + 缓存读 + 缓存写 |
| 输入 | 仅未缓存输入，不含缓存读写 |
| 输出 | 提供商报告的输出；推理 Token 不重复计入 |
| 缓存命中率 | 缓存读 ÷（未缓存输入 + 缓存读 + 缓存写）；分母为 0 时显示 — |
| API 调用 | 已结算的 assistant/message 与 assistant/attempt 记录（含失败与无 usage 的尝试） |
| 日趋势柱 | 仅输入：未命中 = 未缓存输入 + 缓存写；命中 = 缓存读 |
进行中的请求在结算后才出现；无 usage 的请求仍计入 API 次数但不估 Token。同一 attempt 的重复结算会去重；重试 attempt 单独计数；继承的 fork 记录排除。日期按浏览器 IANA 时区，日历周从周一开始。输出计入总 Token 与提示详情，但不参与输入-缓存堆叠图。
适用场景与注意¶
适合谁
- 需要在本地跨会话观察 Token 与 API 调用、对比项目/模型消耗的智能体或 DSH 日常用户
- 希望查看缓存命中趋势、辅助调 prompt 与上下文策略，但不依赖云端账单面板
使用注意
- 仪表盘为空时：仅能看到当前 DSH Profile 可访问的会话数据源；在该 Profile 完成至少一次请求后刷新；流式未结算的请求不会出现。
- 与提供商账单可能不一致：仪表盘只读本地日志，不做费用估算，也不包含 Profile 外请求。
- 大体积会话日志首次加载或刷新可能较慢；无法读取的会话会显示部分统计警告。
- 这是 Token 会计视图，不是计费或带宽计量。
安全与权限
插件以当前 DSH 进程权限运行，通过只读句柄读取本地会话日志。安装前建议在 GitHub 仓库 查看源码与 MIT 许可证。更新或卸载：替换/重装插件文件后重启 DSH，或通过 DSH 插件管理器移除/禁用；会话日志不会被插件改动。
结尾¶
DSH-TokenDashboard 把分散在本地会话里的用量与缓存行为集中到侧栏仪表盘，适合在 DSH「一切皆插件」的生态里做轻量可观测。社区目录页：skillhub.cn 插件条目；源码与文档：github.com/NingTiAn-byte/DSH-TokenDashboard。
