前言¶
在 DeepSeek Harness（DSH）里跑 Agent、多轮对话时，模型调用会不断累积：未缓存输入、缓存命中、输出各占多少，折合参考费用又是多少，往往要事后翻会话或自己记账。若部署环境不固定、也不绑定某一产品的本地数据库，就更难用「读私有库」的方式做统一统计。
下面介绍的 dsh-llm-token-usage（维护者 dgjin，分类：客户端）面向「运行本插件的 harness 自身」：数据来自 harness 官方的会话查询服务 ctx.sessionQuery，不解析任何私有文件，装在同一套 DSH 上即可统计当前实例的用量与参考费用，并在原生界面里给出仪表盘、斜杠命令与 Agent 工具。
这是什么¶
插件统计本 harness 进程内 LLM token 用量与参考费用。每条 assistant/message 事件自带 usage 与 provider/model，按天、按模型、按工作区、按会话的聚合是逐轮精确的。
与依赖某一客户端本地数据库的做法不同，它只调用 ctx.sessionQuery（listSessions → readSession → 逐条读取 usage），只读、不写会话数据。参考费用由本地价表换算；平台账户余额在可用时通过 ctx.deepseekAccount.getBalance() 展示真实值，未登录或查询失败时可回落到本地 balance.json 的估算口径。
- 目录页：https://www.skillhub.cn/plugins/dgjin/dsh-llm-token-usage
- 源码与文档：https://github.com/dgjin/dsh-llm-token-usage
- 当前 package 版本：0.5.4（MIT，Node >= 22.5.0）
核心功能¶
入口一览¶
| 能力 | 入口 |
|---|---|
| 主面板仪表盘 | 左侧图标栏 Token 用量（与 Plugins、Schedules 并列） |
| 文本报表 | /token-usage |
| 平台账户余额（真实值） | 仪表盘 KPI、会话头部胶囊、状态栏、/token-balance |
| 本会话花费 + 余额 | 会话标题栏右侧胶囊（悬停看明细） |
| 状态栏精简显示 | composer 下方：本会话 ¥… · …M tokens · 余 ¥… |
| 价表查看 / 同步 | /token-pricing、/token-pricing update；插件更新时可自动同步 |
| Agent 按需取数 | 工具 llm_token_usage（支持 format: "html" 导出） |
| 独立 HTML 仪表盘 | 面板「打开独立仪表盘 / 下载 HTML」，或 /token-usage-dashboard |
仪表盘内容¶
主面板与设置 → LLM Token 用量 共用同一份组件，与导出 HTML 对齐：
- 6 张 KPI：合计 Tokens、参考费用、账户余额、模型调用（含未缓存输入与输出）、缓存命中率、轮次。
- 每日 Token 用量：缓存命中 / 未缓存输入 / 输出堆叠柱，带峰值与悬停明细。
- 每日参考费用：折线 + 渐变面积。
- 模型 / 工作区分布：横向比例条（合计、占比、费用）。
- 明细表：按天 / 模型 / 工作区 / 会话切换，表头排序，可导出 CSV（UTF-8 BOM）。
- 口径说明：价表版本、未配置单价的模型、余额与数据覆盖范围。
面板打开期间约每 60 秒静默刷新（页面隐藏时跳过）；无调用记录时显示引导空态。点击模型或工作区分布某一行可筛选整个面板，自定义日期区间通过查询参数交给 Host 计算；余额与数据覆盖说明仍按全量口径，避免筛选后误读。
余额与计价¶
余额优先展示平台真实值（充值钱包 + 赠金钱包）；估算口径为：期初余额（balance.json）减去自 as_of（北京时间 00:00）起的参考费用。账户查询带 60s 缓存与 4s 超时，失败不影响统计。
计价字段包括未缓存输入、缓存命中、缓存写入、输出；缓存命中率 = 命中 /（未缓存输入 + 命中）。价表默认复制到 ${DSH_HOME:-~/.dsh}/llm-token-usage/pricing.json，内置常用模型参考价，支持峰谷时段（北京时间工作日 9:00–12:00、14:00–18:00 为高峰）。未配置单价的模型只统计 token，费用列显示 —。
插件通过测试 tests/analytics-parity.mjs 与 harness 自身 tokenUsage 投影对账，文档中给出的冻结基准会话在主要字段上与 harness 账本一致（差异为 0）。
隐私与安全¶
正常使用全程本地、只读；面板数据路由仅接受本机回环直连。只有显式执行 /token-pricing update（或开启自动价表同步）才会从公开仓库拉取价表（HTTPS、校验、备份后写入）。可用环境变量 DSH_TOKEN_USAGE_NO_NET=1 或配置 autoUpdatePricing: false 关闭自动同步。
安装与启用¶
在 DSH 桌面端或 CLI 的插件管理里安装本包。资料中的安装方式如下：
# 打包后安装（将路径换成本地 tgz 的绝对路径）
dsh plugin --profile web add --workspace-root file:/绝对路径/dsh-llm-token-usage-0.5.4.tgz
# 上架 npm 后
dsh plugin --profile web add dsh-llm-token-usage
装完后重启一次 Harness，斜杠命令、工具与设置页入口才会生效。插件不裸导入 harness 包，链接安装与打包安装行为一致。
典型用法¶
斜杠命令¶
近 7 天按天汇总：
/token-usage
近 30 天按模型、全部历史按工作区或会话：
/token-usage 30 --by model
/token-usage all --by project
/token-usage all --by session
/token-usage --since 2026-09-01 --until 2026-09-15
估算余额（期初余额默认从今天起算）：
/token-balance
/token-balance --set 100
/token-balance --set 100 --as-of 2026-09-01
/token-balance --clear
导出 HTML 仪表盘：
/token-usage-dashboard
/token-usage-dashboard --path ./dash.html
价表：
/token-pricing
/token-pricing update
也可直接让 Agent 回答「用了多少 token」「花了多少钱」「哪个模型最费」「缓存命中率多少」等，由 llm_token_usage 工具按需取数。
可选配置¶
插件行 config 均为可选，例如：pricingPath、autoUpdatePricing（默认 true）、pricingSyncIntervalMs（默认 86400000）、balancePath、templatePath、cacheTtlMs（默认 60000）、maxSessions（默认 200，超出按最新会话截断并在报表中标注）。
余额配置文件示例路径：${DSH_HOME:-~/.dsh}/llm-token-usage/balance.json：
{ "balance": 100.0, "as_of": "2026-11-01" }
适用场景与注意¶
适合谁：需要在 DSH Web 客户端侧长期观察本实例 token 与参考费用、对比模型与工作区、导出 CSV 或独立 HTML 报表，并在会话中实时看到本会话花费与余额的开发者或团队。
使用前请知悉：
- 插件以当前 dsh 进程权限运行，安装前应阅读源码与 MIT 许可证，确认行为符合你的安全策略。
- 参考费用依赖本地价表与模型配置，与平台账单可能存在差异；真实余额以平台 API 为准。
- 社区目录 SkillHub 为独立站点，与 DeepSeek / 幻方无官方从属关系；DSH 生态理念是「一切皆插件」，本介绍仅描述该插件在资料中声明的能力。
结尾¶
dsh-llm-token-usage 把 harness 官方会话查询里的 usage 聚合成可读的报表与原生仪表盘，并在状态栏、会话胶囊里补上本会话成本与余额，适合作为 DSH 部署上的本地只读用量面板。进一步了解可访问目录页 https://www.skillhub.cn/plugins/dgjin/dsh-llm-token-usage 与 GitHub 仓库 https://github.com/dgjin/dsh-llm-token-usage。
