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 里插入一行」两步。

1. 从 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'))"
   

2. 编辑 $DSH_HOME\profiles\desktop\cordis.patch.yml 插入组合条目（见方式二第 2 步），然后重启 DSH Desktop（Web 版刷新页面）。

可用 dsh --profile desktop --dump-config 确认 usage-dashboard 条目已生效。

方式二：手动安装（离线 / 无 git）

1. 把本包文件放到包名对应的 scope 路径（目录名不对会导致按包名解析失败）：

   $DSH_HOME\profiles\desktop\node_modules\@gongshiyun\dsh-usage-dashboard\
     package.json  cordis.patch.yml  lib\index.js  lib\client.js  README*.md
   

2. 编辑 $DSH_HOME\profiles\desktop\cordis.patch.yml，在顶层插入一行（不要编辑 profile 根目录的 cordis.yml，它每次启动都会被重写为 []）：

   - insert:
       - id: usage-dashboard
         name: '@gongshiyun/dsh-usage-dashboard'
   

   如需覆盖价目，在 name 下追加 config（见下节）。

3. 重启 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 默认组合已包含）。