前言¶

在 DeepSeek Harness 中做多轮会话时，常见需求不只是得到模型输出，还包括确认当前轮次和整个会话累计消耗了多少 token、按当前合同价格大致花费多少，以及是否接近设定的会话额度。

dsh-billing 针对这个场景提供本地计费、投影和 Web 界面展示。它适合在 DSH 开发或调试过程中查看费用参考值，但不是账单系统，也不会自动阻止模型调用。

这是什么¶

Wanbinyu/dsh-billing 是面向 DeepSeek Harness 的会话计费与额度插件，由 Wanbinyu 维护。这是一个独立社区项目，不属于 DeepSeek Harness 官方发行版。

它主要做三件事：

1. 按 provider/model 统计 token 费用。
2. 生成 billing session projection。
3. 在 Web composer dock 显示本轮/会话费用、额度进度、未定价模型提示和模型明细。

费用是本地参考值，不是账单，也不会自动阻止模型调用。

核心功能¶

dsh-billing 的能力集中在会话级计费和 Web 展示：

• 按 provider/model 统计 token 费用。
• 生成 billing session projection。
• 支持每会话额度。
• 在 Web composer dock 显示本轮/会话费用、额度进度、未定价模型提示和模型明细。
• bundle 同时导出 host 与 Web client 入口。
• 价格优先使用配置，其次使用内置 USD 模型目录。
• 相同模型 ID 在不同 provider 下会分开统计，例如 deepseek/deepseek-v4-flash 和 openrouter/deepseek-v4-flash。
• 额度达到 50%、80% 和 100% 时会逐级增强提示颜色。

host 侧负责计价和 projection，浏览器侧从 host 已计算的 projection 渲染界面。

安装与启用¶

作为 bundle 安装¶

仓库 README 给出的安装命令如下。这条命令安装的是 v0.6.3 community bundle：

dsh plugin --profile web add https://github.com/Wanbinyu/dsh-billing/releases/download/v0.6.3/dsh-billing-community-bundle-0.6.3.tgz

安装后重启 dsh。

bundle 通过一个 billing 配置条目同时启用 host projection 和 Web 费用条。价格优先使用配置，其次使用内置 USD 模型目录。

手动安装¶

如果宿主项目需要自己控制组合层，可以安装两个包：

npm install ./packages/dsh-billing ./packages/dsh-client-ui-billing

然后在 profile 的 cordis.patch.yml 中加入：

- insert:
    - id: billing
      name: dsh-billing
      config: {}
    - id: ui-billing
      name: dsh-client-ui-billing

这样 host 侧启用 dsh-billing，Web 侧启用 dsh-client-ui-billing。

典型用法¶

配置价格与额度¶

配置价格时，优先使用精确的 provider/model。只写模型 ID 仍然有效，并作为所有 provider 的兼容回退。

示例配置如下：

- id: billing
  config:
    models:
      deepseek/deepseek-v4-flash:
        input: 1
        output: 2
        cacheRead: 0.02
        cacheWrite: 0
    currency: CNY
    quota:
      limit: 5

上面的价格只是文档示例，实际价格按合同配置。

使用 CNY 或其他货币时，请为每个模型显式配置价格。没有价格的模型仍会统计 token，但会进入 unpricedModels。它们不会伪造费用，quota.estimated 会变为 true，表示额度进度只包含已知价格，不能当作完整账单。

如果在 bundle 已插入后修改 billing 行，Harness 的 patch 会替换整段 config，因此需要保留所有希望继续使用的配置字段。

查看投影结果¶

billing session projection 包含货币、总费用、分模型费用、token 明细、未定价模型和额度状态。接口如下：

interface BillingProjection {
  currency: string
  totalCost: number
  models: {
    provider: string
    model: string
    cost: number
    uncachedInputTokens: number
    outputTokens: number
    cacheReadTokens: number
    cacheWriteTokens: number
  }[]
  unpricedModels: string[]
  latestTurn?: {
    turn: number
    cost: number
    uncachedInputTokens: number
    outputTokens: number
    cacheReadTokens: number
    cacheWriteTokens: number
    unpricedModels: string[]
  }
  quota?: {
    limit: number
    used: number
    remaining: number
    percent: number
    estimated: boolean
  }
}

latestTurn 在首次收到 usage 后出现，供客户端显示最近一轮的费用和 Token 明细。

投影会按 request/header 对 step 归属 usage。同一 (turn, step) 的后续样本会同时替换会话累计和本轮数据中的早期样本，避免重复计费。没有前置 header 的 usage 会放入保留的 (unknown) bucket。

生成内置目录与完整验证¶

内置目录只使用 USD，通过以下脚本从 pi-ai model catalog 生成：

node packages/dsh-billing/scripts/generate-catalog.mjs

运行完整验证：

npm run build
npm run verify

适用场景与注意¶

适合以下场景：

• 需要在 DSH Web 会话中查看本轮和会话累计费用。
• 需要按 provider/model 查看 token 明细。
• 需要每会话额度进度提示。
• 需要在本地 DSH 项目中启用计费与额度展示。

使用前需要明确以下限制：

• 这是独立社区项目，不属于 DeepSeek Harness 官方发行版。
• 费用是本地参考值，不是发票或强制限流依据。
• 额度不会自动阻止模型调用。
• quota 目前按 session 计算，部署级预算暂未实现。
• 兼容 DeepSeek Harness 0.1.0-rc.6 至 rc.8、0.1.1-rc.1 至 rc.2；开发依赖固定在 0.1.1-rc.2。
• package.json 要求 node >=22.19.0。
• 许可证为 MIT。
• 插件以当前 dsh 进程权限运行，安装前应检查源码与许可证。

结尾¶

dsh-billing 提供的是本地会话计费与额度视图：它把费用、token 明细和额度进度放进 DSH Web 会话中，方便开发时查看和核对。使用时请把它当作本地参考值，而不是账单或限流。

已核实的公开入口：

• GitHub 仓库：https://github.com/Wanbinyu/dsh-billing