前言¶

DeepSeek Harness (DSH) 采用插件化架构，支持 Web GUI。在开发或使用 DSH 时，开发者常需要精确掌握 API 调用的成本，包括单次会话的实时花费、分项详情以及账户余额。现有的 Web 界面缺乏这类细粒度的计费展示，这会导致成本预估困难。dsh-token-billing 插件通过在会话标题栏挂载投影和徽标，解决了这一问题，它将算钱逻辑下沉到 Host 进程，显示端仅负责展示，从而在不触碰密钥的前提下提供可视化的计费与余额查询能力。

插件介绍¶

mrtomtao/dsh-token-billing 是一个为 DeepSeek Harness Web GUI 设计的会话 token 计费插件。

该插件通过 Host 半注册 tokenBilling 投影来计算费用并查询余额，浏览器半则通过只读路由读取数据并渲染 UI。它不依赖任何联网抓取，价格数据直接来自官方文档，且完全在不触碰 DeepSeek API Key 的前提下运行。

安装与启用¶

安装前请确保环境满足要求：DSH（Web / web profile）、Node 22+、以及已安装并在 PATH 中的 pnpm。

从 GitHub 安装¶

这是最省事的安装方式，插件会作为依赖装进 profile，且 profile 不会记录文件路径。

dsh plugin --profile web add github:<you>/dsh-token-billing

从 Release 安装¶

适用于需要校验或离线部署的场景。

dsh plugin --profile web add ./dsh-token-billing-0.2.3.tgz

从目录安装¶

用于本地开发调试。

dsh plugin --profile web add C:\path\to\dsh-token-billing

验证与重启¶

安装后可以通过以下命令验证挂载情况：

# 查看组合层，应能看到 # == dsh-token-billing
dsh --profile web --dump-config

# 验证挂载且不绑定端口
dsh --profile web --help

重启 DSH Web profile 后，打开任意会话，标题栏右侧将出现花费与余额徽标。

核心功能¶

• 实时计费徽标：在会话标题栏显示本次会话的实时花费。尚未产生记录时显示 ¥--，产生后立即更新。
• 分项详情：点击花费徽标（28px 官方头部控件规格），会弹出对话框，展示输入、缓存命中、缓存写入、输出、推理的分项明细。
• 模型账单：展示按模型的 Token 统计与总费用。
• 时段价展示：显示当前使用的是高峰时段还是空闲时段，并提供一键切换。
• 余额查询：显示账户余额徽标。点击可查看充值余额、赠送余额及总额。余额查询由 Host 半执行，浏览器半仅调用本地路由。

计费逻辑¶

插件内置了完整的计费逻辑，基于官方价目表进行计算。

价格来源¶

价格数据直接取自官方文档的原文，不进行联网抓取。支持人民币和美元两种币种，且币种在面板内可一键切换。

高峰与空闲时段¶

高峰判定基于 Token 的实际发生时间：
* 高峰时段：周一至周五 09:00–12:00、14:00–18:00（北京时间）。
* 空闲时段：除高峰外的所有时间。
空闲时段的单价为高峰价的 0.5 倍。

分桶统计¶

插件将 Token 统计为四个互不重叠的桶：
1. 输入 · 未命中缓存
2. 输入 · 缓存命中
3. 缓存写入
4. 输出（推理包含在输出内）

注意：缓存写入按未命中输入价计费，因为官方不单独收取此项费用。

重试与未定价模型¶

• 重试逻辑：与 DSH 的 tokenUsage 投影一致，同一轮对话的重试上报采用替换而非累加策略，确保徽标显示的 Token 数与 GUI 原生面板一致。
• 未定价模型：对于未在官方价目表中列出的模型，插件会按 deepseek-flash 的价格进行估算，并在明细中打上「估算」标签。

余额查询¶

余额显示采用“Host 计算，浏览器显示”的架构。

数据流向¶

• Host 半：负责向 DeepSeek 平台发起查询。查询顺序为：优先查询已登录的 DeepSeek 账号余额（充值+赠送），其次查询 API Key 对应的账户余额。
• 浏览器半：不直接请求 DeepSeek 接口，而是调用 Host 提供的同源只读路由 GET /token-billing/balance 获取数字。

缓存策略¶

为了减少请求频率，余额查询结果会被缓存：
* 成功结果缓存 60 秒。
* 失败结果缓存 15 秒。

禁用余额查询¶

如果不需要余额显示，可以在配置中关闭余额查询功能，此时 Host 半将不发起请求，浏览器半也会隐藏余额徽标。

配置与注意事项¶

手工安装¶

如果不使用 bundle 机制，可以在 profile 的 cordis.patch.yml 中手工添加：

- insert:
    - id: token-billing
      name: dsh-token-billing

价格配置¶

价格支持通过组合配置覆盖，无需修改代码。在 cordis.patch.yml 中覆盖 config.prices 即可：

- id: token-billing
  config:
    prices:
      CNY:
        deepseek-flash: { hit: 0.04, miss: 2, output: 8 }
        deepseek-v4-pro: { hit: 0.3, miss: 9, output: 27 }

关键注意事项¶

1. lib/ 文件夹必须提交：由于 pnpm 默认拒绝执行 git 依赖的构建脚本（ERR_PNPM_GIT_DEP_PREPARE_NOT_ALLOWED），插件无法在安装时现场编译。仓库必须将编译好的 lib/index.js 和 lib/client.js 提交进去，以支持 git 安装。
2. 安装 tarball 后不要删除：Profile 记住的是文件的路径，文件丢失会导致后续命令报 ENOENT。
3. 目录安装需要 node_modules：从目录安装时，插件目录内必须有 node_modules（包含 zod），否则会导致插件导入失败。

结语¶

dsh-token-billing 通过插件化的方式为 DeepSeek Harness Web GUI 填补了计费与余额监控的空白。它利用 DSH 的投影机制实现了精确的费用分项展示，同时通过本地路由避免了跨域和密钥泄露的风险。对于需要精细控制 API 成本的用户，这是一个直接可用的工具。

• 插件目录
• GitHub 仓库