前言¶
DeepSeek Harness（DSH）在每轮对话里会给出 token 明细，但缺少跨会话的汇总视图。想长期看消耗、请求数和缓存命中率，常见做法是装 cc-switch 等外部工具，通过解析本机会话日志来统计，额外多一个桌面应用，还要跟着 DSH 日志格式变化做维护。
下面介绍社区插件 dsh-usage-dash-board（维护者 sixzjd）：在 DSH 设置 → 用量统计（英文界面为 Usage Statistics）里，用原生分区展示 token 消耗、总请求数、缓存命中率与按天趋势，数据全部来自本机会话日志，不联网、不上传、不需要 API Key。
这是什么¶
dsh-usage-dash-board 是 DSH 的客户端插件（当前 GitHub 星标 0，版本 0.4.2，MIT 许可）。它消费宿主公开的 ctx.sessionQuery 服务：会话日志的解压、排序与中断轮次平衡由 DSH 负责，插件只处理结构化事件，不做文件解析或格式猜测，因此不依赖 DSH 是否改动 $DSH_HOME/sessions 下的布局。
分类上属于「客户端」：浏览器半区挂载在设置页的 settings.section 插槽；宿主半区负责扫描、聚合、持久化与 HTTP 路由。
数据从哪来、怎么算¶
处理链路¶
durable session log
│ ctx.sessionQuery.listSessions() / readSession()
▼
事件流（已解压、已排序）
│ assistant/message.usage ▸ 覆盖同轮的 assistant/chunk
│ request/header / request/context ▸ 模型与供应商标识
▼
按 (session, turn, step) 折叠成「一次调用」
│ 本地日历日分桶
▼
日聚合 / 模型聚合 / 区间汇总 + 价格表计价
│ GET /api/dsh-usage-dash-board/summary
▼
设置页原生分区（settings.section slot）
一次调用只计一份用量：同一 turn:step 上，assistant/message 的最终 usage 替换流式 assistant/chunk，而不是相加；全零的重放事件也不会覆盖已记录的真实数字。
指标口径¶
token 桶遵循宿主 @deepseek-ai/dsh-llm 的 DISJOINT 语义：inputTokens 只含未命中缓存的输入，缓存部分在 cacheReadTokens / cacheWriteTokens。
| 指标 | 计算方式 |
|---|---|
| 消耗 token | 输入 + 输出 + 缓存写 + 缓存读 |
| 总请求数 | 携带 usage 的调用次数（按 session:turn:step 去重） |
| 缓存命中率 | 缓存读 ÷ (输入 + 缓存写 + 缓存读) |
OpenAI 式协议不上报 cacheWriteTokens 时该项恒为 0，命中率分母同样不含它，属于上游字段缺失而非统计漏算。
核心功能¶
面板能力以 README 为准，主要包括：
| 区域 | 内容 |
|---|---|
| 顶部三张卡 | 消耗 token、总请求数、缓存命中率；点击可看构成明细 |
| 使用趋势 | 柱状图，可切 Tokens / 请求；默认按天，选「今天」或起止同一天的自定义区间时自动按小时 |
| 筛选 | 供应商、模型、时间范围（今天 / 近 7 / 30 / 90 天 / 全部时间 / 自定义）；打开时默认近 30 天 |
| 请求明细 | 每次调用的时间、供应商、模型、token、费用 |
| 供应商 / 模型 | 分组聚合与占比 |
| 定价 | 可编辑价格表，按 USD / 百万 token 计四桶价格 |
趋势图 X 轴按日历日（或按小时视图的 24 时段）补齐，无数据日期显示为 0。「全部时间」起点为实际最早一条记录；无记录时退化为「今天」，仍按天展示。标题下会标抓取时刻（例如 · 数据更新于 15:27:45）；面板不自动刷新，改筛选或点「刷新」才更新。
内置 DeepSeek 官方峰谷价（含中国法定节假日全天谷价），例如 deepseek-v4-flash、deepseek-v4-pro 的 in / out / 缓存读单价；峰时段为 UTC 01:00–04:00 与 06:00–10:00（对应北京时间工作日上午与下午峰段，法定节假日除外）。没有公开单价的模型标为「未计价」，可在「定价」里手工补价。
安装与启用¶
包尚未发布到 npm，安装命令以仓库 README 为准：
dsh plugin --profile web add github:sixzjd/dsh-usage-dash-board
发布后 README 说明可改用：
dsh plugin --profile web add dsh-usage-dash-board
安装后刷新浏览器页面即可。插件兼容 DSH >=0.2.0-rc.2 <0.3.0（见 package.json 中 dsh.compatibility）。
卸载：
dsh plugin --profile web remove dsh-usage-dash-board
典型用法¶
- 按上文命令为 web profile 安装插件并刷新页面。
- 打开 DSH 设置，进入 用量统计（Usage Statistics）。
- 用顶部筛选选择供应商、模型与时间范围；需要核对单次调用时查看「请求明细」。
- 估算成本与官方价不一致时，在「定价」编辑价格表（保存走受保护的写接口，需进程令牌）。
- 需要程序化核对汇总时，可请求宿主注册的
GET /api/dsh-usage-dash-board/summary（仅回环地址可访问；响应不含提示词与回复正文）。
部分供应商用路由别名暴露模型（如 Qoder 的 qfmodel）。插件可能读取 dsh-qoder-connect 在 $DSH_HOME/profiles/*/.dsh-qoder-connect/state/*-catalog.json 的模型发现缓存，仅用于显示名；分组、计数、筛选与计价仍按路由 id。可通过 summary 响应中的 catalog.aliasCount 判断是否解析到别名。
适用场景与注意¶
适合谁：长期在 DSH web 客户端里跑智能体、希望在本机汇总 token、请求数、缓存命中率并做估算成本，又不想依赖外部日志解析工具的用户。
运行边界：插件以当前 DSH 进程权限运行，会经 ctx.sessionQuery 读取全部列出的会话（不限于已注册工作区），并在 $DSH_HOME/storages 持久化价格表。安装前应自行查看 GitHub 源码 与 MIT 许可证。
务必知晓的限制（摘自 README）：
- 成本为按内置/手工价格表的估算值，不等于供应商账单。
- Qoder 等按 credits 配额计费的路由，套用 USD 单价只是「等价 API 价」，不是实际支付金额；插件只做名称解析，不自动为别名填价。
- 上游中断且缺少最终
assistant/message时可能只保留 chunk 用量；完全没有 usage 事件则无法精确还原 token。 - 缺少
request/header/request/context时会话模型显示为unknown。 - 面板正文目前为中文，侧栏标签跟随浏览器语言。
HTTP 接口限制回环地址并拒绝跨站 Sec-Fetch-Site，写价格需进程令牌；响应仅含用量数字、模型标识与会话 UUID，不含提示词、标题或工作区路径。
结尾¶
dsh-usage-dash-board 把跨会话用量统计收进 DSH 设置页：基于公开 sessionQuery 接缝，本地聚合、可选定价，不依赖外网。社区目录页：skillhub.cn/plugins/sixzjd/dsh-usage-dash-board；源码与完整说明：github.com/sixzjd/dsh-usage-dash-board。
