前言¶

在 DeepSeek Harness（DSH）里跑多会话、多模型调用时，token 会分散在会话日志、底层 llm/stream 和开放平台账户账单里，口径并不相同。若只看某一侧，容易把辅助调用漏算，或把其他客户端上的消费误当成「本机用量」。下面介绍的 dsh-usage-monitor 是社区插件，由 Dekurri 维护，在 DSH 左侧栏提供一个本地仪表盘：汇总 token、成本估算、缓存命中率、分模型与会话明细，并采样本机 CPU/GPU/内存，同时支持与 DeepSeek 开放平台账单对账。数据默认只在本机聚合与落盘，插件自述不上报遥测。

这是什么¶

dsh-usage-monitor 归类为 admin-security，当前包版本 1.0.1（MIT 许可）。它在侧栏注册面板，把「会话口径」「全量调用口径」「平台账单口径」并列展示，避免把三组数字简单相加。Host 侧零第三方依赖；浏览器端使用宿主注入的 React 模块，图表为手写 SVG。

面板里有什么¶

打开侧栏图标后，主面板按 README 中的结构组织，主要包括：

• KPI：总 Token、成本（人民币为基准，美元为派生展示）、会话数、活跃会话、缓存命中率、请求数。
• 对账条：全量调用口径与平台账单的对比提示。
• 趋势：堆叠柱（未缓存输入 / 缓存读 / 缓存写 / 输出）、构成饼图、模型占比饼图。
• 实时：CPU、GPU、内存、RSS、heap、运行时长；约 2 秒轮询，sparkline 保留 60 个点。
• 分会话：可排序、可搜索；含 token、命中率、TTFT、token 速度、时长等。
• 分模型：请求数、token 分桶、成本。
• 对话性能：TTFT 分位、平均输出速度、工具耗时占比。
• 全量调用：按 purpose（对话 / 压缩 / 标题 / 其他）与模型拆分。
• 平台账单：余额、今日 / 昨日 / 7 天 / 30 天消费、采样覆盖度（数据不全时金额前会标 ≥）。
• 账单历史：按天的柱状图，覆盖余额账本记录的每一天，含安装插件之前的日期（在可回填范围内）。
• 设置与计费规则：官方价表、峰谷时段、法定节假日、汇率位、各板块显隐（存 localStorage，只影响展示）。

底部可勾选 11 个大板块的显隐；统计逻辑不因隐藏而改变。

三种口径，不要相加¶

插件在文档中明确区分三类数据来源，用途不同：

会话日志主要记录 assistant/message，可能漏掉 Auto review、标题生成、上下文压缩、联网搜索等仍计费的调用；全量调用口径用于与平台「API requests / Tokens」对齐。平台账单是账户级，同账号其他 Key、机器、客户端都会计入，且可能有最多约 5 分钟延迟。余额差法在区间内检测到充值时会标记为不可信，而不是给出错误消费数。

成本、汇率与账单¶

成本估算使用编译进包内的官方人民币价目（元 / 百万 token），按每次调用发生的时刻判断峰谷；周末及内置的中国法定节假日全天按谷价，内置表覆盖 2025–2026 共 61 天法定假日。2027 年及以后若官方尚未发布安排，文档说明未内置年份的工作日 9–12 / 14–18 可能按高峰价计（可能高估）；可用配置追加 pricingHolidays。

汇率启动后异步拉取中国外汇交易中心（央行授权发布）人民币中间价，默认 30 分钟刷新；失败时按「历史中间价 → 非央行市场汇率（面板标注）→ 配置兜底」降级，不会静默沿用旧值。人民币为结算基准，美元仅为展示；实时汇率不会回改已结算的历史成本。

平台相关读写经 DSH 的 deepseekAccount 服务，插件不接触 token 或密码。自建按天复式账本（opening / closing / debit / credit），充值不计入消费；若本机存在其他 DSH 插件的历史账本文件，可作为可选回填逐日合并（观测级，不重复计）。

安装与启用¶

需要 DSH 0.2.x（Host 提供 sessionQuery / webServer；deepseekAccount、llm 为可选服务，缺失时对应卡片显示「不可用」，其余面板照常）。插件不需要在包内执行 npm install。

完整步骤与排错见仓库 INSTALL.md。README 给出三条路径，任选其一：

1、下载即用（推荐给普通用户）

从 Releases 下载 dsh-usage-monitor-<版本>.tgz，解压到长期目录，在 DSH 插件管理器里对 install_bundle 传入该目录的绝对路径，然后刷新页面。

2、源码安装

将仓库克隆或解压到本地目录，同样把含 package.json 的目录绝对路径交给 install_bundle：

plugin_manager({ action:"install_bundle", target:"<插件目录绝对路径>" })

安装结果里 application 必须是 "applied"。若 failed 且 failedAt === "registry"，文档建议原样重试一次（多为网络抖动）。不要手工改 profile 的 package.json / cordis.patch.yml。

3、交给 DSH 助手

把 README 中的安装校验段落发给助手，由其执行 clone 或解压、install_bundle、以及 cordis_inspect_query 与 HTTP 校验。

验证示例（将 <DSH Web 地址> 换成你的实例地址）：

GET <DSH Web 地址>/usage-monitor/api/overview?range=today  → 200 且含 kpi
GET <DSH Web 地址>/usage-monitor/api/live                   → 200 且含 host.cpuPercent

侧栏注册检查：

cordis_inspect_query({ platform:"client", provider:"Slots", method:"listSubTree",
                       input:{ root:"sidebar.panellist" } })
→ occupants 中应有 { registrant:"usage-monitor", id:"usage-monitor", active:true }

卸载：在插件管理器中移除 dsh-usage-monitor。

配置要点¶

默认值在 cordis.patch.yml，可在 profile 层覆盖。常用项包括：

缓存与账本文件落在 $DSH_HOME/usage-monitor/ 等路径，详见 README 配置表。

典型用法¶

日常使用时，在 DSH Web 界面打开左侧栏 usage-monitor 面板即可。按时间范围查看 KPI 与趋势，在分会话列表里搜索慢会话或高 token 会话，用「全量调用」块核对是否包含压缩、标题等辅助调用，用「平台账单」块对照开放平台消费（需已登录且 deepseekAccount 可用）。

需要程序化探活或对接监控时，可调用 Host 暴露的 REST 路由（契约见 CONTRACT.md）：

• GET /usage-monitor/api/overview
• GET /usage-monitor/api/live
• 以及 ledger、account、bill-history、fx 等（见 lib/routes.js）。

适用场景与注意¶

适合：在本机 DSH 上长期跑 agent、希望同时看清会话用量、全量 API 调用与账户账单差异的开发者；需要粗略成本估算（官方价表 + 峰谷 + 汇率规则）与运行资源占用（CPU / 内存，有 nvidia-smi 时含 GPU）的场景。

注意：

• 插件以当前 DSH 进程权限运行，安装前应阅读源码与 MIT 许可证，确认可接受其本地读写与对外汇率请求行为。
• 成本为按官方价目表的估算值，与开放平台账单可能存在口径差，请以平台为准；README 标明为非官方项目，与 DeepSeek 无隶属关系。
• GPU 监控依赖 nvidia-smi，无则 gpu.available:false，面板隐藏显卡块。
• 版本升级若触发 CACHE_VERSION 变化，首次打开面板可能略慢（全量冷扫后走缓存）。
• 对外网络除汇率外自述无遥测；价目表运行时不再联网抓取。

结尾¶

dsh-usage-monitor 把会话、全量调用与平台账单三种口径拆开展示，并在同一侧栏面板里补上缓存命中率、分模型统计与本机实时资源采样，适合在 DSH 0.2.x 上做用量观测与对账参考。

• 社区目录页：skillhub.cn/plugins/Dekurri/dsh-usage-monitor
• 源码与文档：github.com/Dekurri/dsh-usage-monitor