dsh-usage-dashboard
English | 中文
DeepSeek Harness（DSH）插件：展示 DeepSeek 账户余额、当前会话预估消耗、历史对话明细（每个对话的 token 与金额），并根据历史会话的平均消耗，估算各模型剩余对话次数。
适配 DSH >= 0.1.5-rc.1（Web 与桌面版共用同一套插件体系）。
功能
- 余额：调用 DeepSeek 官方
GET /user/balance 接口，展示账户总余额（CNY 或 USD）。
- 当前会话预估消耗 + 还能几轮：在输入框下方、官方统计行（
N 轮 · M 步）之后另起一行，实时显示「本次会话预估金额 · 余额 · 预估还能几轮」（剩余轮数 = ⌊余额 ÷ 当前会话每轮平均消耗⌋）。
- 对话明细（全局看板）：列出每个历史对话的最近活跃时间、输入 token、输出 token 与折算金额（按最近活跃倒序，自动跳过空会话与子代理会话；「当前」会话会标注），支持按工作区筛选、按时间/金额排序与分页。
- 各模型剩余对话次数：按模型聚合历史会话，
剩余次数 = ⌊余额 ÷ 单次会话平均消耗⌋，同时展示会话数、平均消耗、累计消耗与 token 明细。
展示位置
- 输入框下方一行（
conversation.composer.dock，order 200）：当前会话预估消耗、当前余额、预估还能对话几轮，随对话每 4 秒自动刷新。
- 「设置 → 用量与余额」全局看板（
settings.section）：余额卡片 + 对话明细表 + 各模型剩余对话次数，每 15 秒自动刷新。
安装
插件必须能被 Cordis Loader 从 profile 目录按名称解析。DSH 桌面版（Electron）与 Web 版共用同一套插件体系，只是使用不同的 profile（desktop/web），安装步骤相同，仅把下面的 desktop 换成实际使用的 profile 名（例如 Web 版用 web）。默认 Windows 路径：
- 主目录（
$DSH_HOME）：C:\Users\<you>\.dsh
- 桌面版 profile 目录：
C:\Users\<you>\.dsh\profiles\desktop\
- Web 版 profile 目录：
C:\Users\<you>\.dsh\profiles\web\
- 插件解析来源：
$DSH_HOME\profiles\<profile>\node_modules（pnpm 管理）＋ 扁平回退 $DSH_HOME\profiles\node_modules
下面以 desktop 为例；Web 版把 desktop 换成 web 即可。
方式一（推荐）：从 GitHub 安装
本包尚未发布到 npm，当前分发渠道是 GitHub 仓库。安装 = 「装进 profile 的 node_modules」+「在 cordis.patch.yml 里插入一行」两步。
-
从 GitHub 装进 profile 的 node_modules。必须用 包名@github: 别名写法，否则 pnpm 会按仓库名（dsh-usage-dashboard）建目录，DSH 按包名解析就会失败：
cd "$DSH_HOME/profiles/desktop"
pnpm add '@gongshiyun/dsh-usage-dashboard@github:gongshiyun/dsh-usage-dashboard'
# 需要本机有 git；也可指向某个 tag：...@github:gongshiyun/dsh-usage-dashboard#v1.1.0
验证目录名正确（应是 @gongshiyun/dsh-usage-dashboard，不是 dsh-usage-dashboard）：
node -e "console.log(require.resolve('@gongshiyun/dsh-usage-dashboard'))"
-
编辑 $DSH_HOME\profiles\desktop\cordis.patch.yml 插入组合条目（见方式二第 2 步），然后重启 DSH Desktop（Web 版刷新页面）。
可用 dsh --profile desktop --dump-config 确认 usage-dashboard 条目已生效。
方式二：手动安装（离线 / 无 git）
-
把本包文件放到包名对应的 scope 路径（目录名不对会导致按包名解析失败）：
$DSH_HOME\profiles\desktop\node_modules\@gongshiyun\dsh-usage-dashboard\
package.json cordis.patch.yml lib\index.js lib\client.js README*.md
-
编辑 $DSH_HOME\profiles\desktop\cordis.patch.yml，在顶层插入一行（不要编辑 profile 根目录的 cordis.yml，它每次启动都会被重写为 []）：
- insert:
- id: usage-dashboard
name: '@gongshiyun/dsh-usage-dashboard'
如需覆盖价目，在 name 下追加 config（见下节）。
-
重启 DSH Desktop（Web 版刷新页面）。
关于 npm：本包目前没有发布到 npm（@gongshiyun/dsh-usage-dashboard 在 registry 上是 404）。发布之后才可以用 dsh plugin --profile desktop add @gongshiyun/dsh-usage-dashboard 一键完成「安装 + 组合」——本包声明了 dsh.bundle.patch，dsh plugin add 会自动追加进 dsh.profile.bundles。
另外注意：npm 上不带 scope 的 dsh-usage-dashboard 是另一个同名但无关的插件，与本项目无关。
升级提示：DSH 升级时若重建了 profile，cordis.patch.yml 会被重置为 []、插件目录可能被清理
（旧 node_modules 会留成 node_modules.dsh-backup-*）。升级后请重新执行上面的「安装 + 组合」两步。
配置
| 键 | 类型 | 默认 | 说明 |
|---|
apiKeyEnv | credential-ref | DEEPSEEK_API_KEY | API Key 凭证引用名 |
baseURL | string | https://api.deepseek.com | DeepSeek API 根地址 |
currency | CNY | USD | CNY | 计价与余额展示货币（必须与 pricing 单位一致） |
balanceCacheMs | number | 60000 | 余额缓存时长（毫秒） |
pricing | array | 见下 | 价目表（era 列表），每个 era 有生效时刻与各模型单价 |
pricing 为价目表（按生效时间排序，成本按每次模型调用的事件发生时刻取当时生效的价目计算）。默认即官方当前价目，通常无需配置：
pricing:
- effective: 2026-09-10T04:00:00Z # 官方当前价（北京 2026-09-10 12:00 生效）
models:
- model: deepseek-flash # V4.1 Flash
inputPerM: 1 # 谷段：输入（缓存未命中）
cacheReadPerM: 0.02 # 谷段：输入（缓存命中）
outputPerM: 4 # 谷段：输出
peak: # 高峰时段单价（与 offPeak 同时存在才生效）
inputPerM: 2
cacheReadPerM: 0.04
outputPerM: 8
offPeak: # 谷段单价
inputPerM: 1
cacheReadPerM: 0.02
outputPerM: 4
- 事件时刻早于首个 era 时按首个 era 计价；era 内未显式列出的模型回退到该 era 的
model: "*" 通配条目。
- 官方再调价时，往列表里追加一个
effective 更新的 era 即可（如只想用当前价，也可直接覆盖为单条 era）。
- 兼容旧格式：直接给出平铺的模型条目（无
effective/models）会被当作单个 era 处理。
默定价目（人民币 / 1M token，仅官方当前价）
| 生效时间（UTC） | 模型 | 时段 | 输入（未命中） | 输入（命中） | 输出 |
|---|
| 2026-09-10T04:00 | deepseek-flash / deepseek-v4-flash / deepseek-v4-flash-vision-exp | 高峰 | ¥2 | ¥0.04 | ¥8 |
| 2026-09-10T04:00 | 同上 | 谷段 | ¥1 | ¥0.02 | ¥4 |
| 2026-09-10T04:00 | deepseek-v4-pro | 高峰 | ¥9 | ¥0.30 | ¥27 |
| 2026-09-10T04:00 | deepseek-v4-pro | 谷段 | ¥4.5 | ¥0.15 | ¥13.5 |
| 2026-09-14T04:00 | 全部（V4 Pro 已路由到 V4.1 Flash，按 Flash 价计费） | 高峰 | ¥2 | ¥0.04 | ¥8 |
| 2026-09-14T04:00 | 全部 | 谷段 | ¥1 | ¥0.02 | ¥4 |
deepseek-v4-flash、deepseek-v4-flash-vision-exp 对应模型已下线，官方仍接受调用但路由到 V4.1 Flash 并按 Flash 价计费，故三者同价。- 高峰时段为北京时间周一至周五 09:00–12:00 与 14:00–18:00，其余（夜间、周末、午间 12:00–14:00）为谷段，谷段价为高峰价的一半。
- 表中不含 2026 年 8 月的旧价：早于 2026-09-10T04:00Z 的历史会话也按上表核算，因此历史金额是近似值。官方 8/17 之前的单价明显更低（V4 Pro 输出 ¥6 vs 现在 ¥13.5），所以更早的历史会话金额会偏高；这些旧会话不再精确计价。
来源：https://api-docs.deepseek.com/zh-cn/quick_start/pricing/（英文：https://api-docs.deepseek.com/quick_start/pricing/）。注意：默认价是内置的、不会自动跟随官方后续调价——官方再次调整价格后，需追加一个新 era（或等插件发布新默认值），插件本身不会自动抓取官方页面。
数据口径与假设
- token 口径：直接读取会话日志
assistant/message 事件的 provider usage 字段。DSH 的 TokenUsage
三个输入计数是互斥的：inputTokens = 缓存未命中输入、cacheReadTokens = 缓存命中输入、
cacheWriteTokens = 缓存写入，计费输入 = 三者之和；与 DeepSeek 的
prompt_cache_miss_tokens / prompt_cache_hit_tokens / completion_tokens 对应。
DeepSeek 适配器不产出 cacheWriteTokens（官方无该计费类目），插件仍会把它按「未命中」单价计入，
以免其它 provider 的用量被漏算。
- 重试去重：同一
(turn, step) 的多次 assistant/message（llm/retry 重试）只保留最后一次，
与 token-meter 的口径一致。
- 成本公式：
cost = ((inputTokens + cacheWriteTokens)×inputPerM + cacheReadTokens×cacheReadPerM + outputTokens×outputPerM) / 1e6。
- 历史会话来源：优先走
ctx.sessionQuery（合并内存中的 live 会话与持久化的冷会话）；
无该服务时退化为仅统计当前已加载进内存的会话。持久化会话的用量按会话 id 一次性缓存，
重启后自动重建。
- 「对话明细 / 最近一次」：
conversations 按会话最近活跃时间倒序，仅包含有实际 token 消耗的
用户会话（自动跳过空会话与 origin === 'subagent' 的子代理会话）；其中除当前会话外的第一条即「最近一次对话」。
- 「剩余对话次数（模型）」：
⌊余额 ÷ 该模型单次会话平均消耗⌋；该模型无历史或平均消耗为 0 时显示 —。
- 「预估还能几轮」：
⌊余额 ÷（当前会话累计消耗 ÷ 当前会话轮数）⌋；当前会话尚无输出轮次时显示 —。
- 余额金额字段为字符串：DeepSeek 返回的
total_balance 等为字符串，本插件在展示与计算时转成数字。
架构说明（供二次开发）
- host（
lib/index.js）：Cordis 插件 { name, inject, apply, Config }。核心是一个
TypertRemoteService 子类 UsageDashboardGateway，暴露 balance() 与 overview(sessionId?)
两个 SRC Remote 端点。SRC（source）模式由 dsh-api-gateway 的 TypertGatewayService 在运行时
从 @Remote 标记推导参数与端点，无需 Typert 编译器生成的 strict 描述符——因此本插件用
installRemote() 手动展开装饰器（plain-JS 环境无装饰器语法）。
- 设置区挂载：DSH 0.1.5 起
@deepseek-ai/dsh-settings 不再导出 installSettingsSection() /
settingsNamespace()（SettingsNamespace 已退化为纯类型），改为 ctx.inject(['settings'], ...)
后调用 ctx.settings.installSection(ctx, ns, Config, base, hooks)；插件同时保留了
ctx.settings.register(...) 的降级分支，两者都不可用时仅使用组合配置、不影响余额与统计功能。
- client（
lib/client.js）：window.__ModuleLoader__.load({ id, factory }) 形态，
通过 ctx.slots.inject(...) 在 settings.section 与 conversation.composer.dock 两个槽位注册
React 组件；数据经 ctx.connection.rpc.call('/api', 'usageDashboard/<method>', { args }) 获取。
两个注册都声明 locale: 'usage-dashboard'，使文案随系统语言（中/英）切换。
限制
- 余额接口为按需轮询（输入框下方 4s、仪表盘 15s），非实时推送。
- 无网络或未配置 API Key 时，余额显示错误提示，成本统计仍可用（取决于本地会话数据）。
- 跨会话的历史平均依赖
dsh-session-query 服务（DSH 默认组合已包含）。
