@rayadesu/dsh-billing

dsh plugin --profile web add @rayadesu/dsh-billing

DeepSeek Harness 计费插件

[English](README.md) | 中文

一个 DeepSeek Harness 插件，在 Web 会话头部直接显示你的 DeepSeek 账户余额与今日所有会话的合计花费，而当前会话（本轮对话）自己的计费花费显示在输入框下方的 pill 上；每条已完成的回合还会在消息操作行行尾以静态金额显示本轮花费，详情面板底部带今日各会话花费排行。

余额是 GET /user/balance 的真实数字；会话花费、本轮花费与今日花费是按官方峰/谷单价对每条消息的计费 token 逐条计价的结果，不是计费承诺。

显示什么

• 会话头部徽标 —— 两行：剩余余额（剩余金额：¥X，是面板标题去掉 API 前缀的短版，徽标较窄）＋ 今日所有会话的合计花费（今日花费：¥X，文案与面板逐字一致——徽标第二行与面板那一行读的是同一份 state，所以不可能互相矛盾）。它是账户级的：只在当日自身的读取（挂载、手动刷新、回合定稿、打开面板）时变动，不随回合实时跳动。
• 详情面板 —— 剩余金额（后跟按余额序列算出的今日消费，见「会话花费是怎么算的」）；今日计费 token 数与今日所有会话合计同一行（今日 Token / 今日花费，token 数按 DSH 的紧凑记数法带自己的单位，如 12.2K tok，token 数值后紧跟当天的缓存命中率（裸数字、无括号）——按 DSH 官方命中率规则渲染：整数百分比，只有部分命中会被凑到 100% 时才逐位多留小数；当天没有 prompt 侧输入就不显示）；紧跟该行下面是今日两行桶明细——token 在上、花费在下——两行各自成行、各自保持自然的 · 间距（两行之间不做列对齐），字体沿用模型分项行那一套，行距用第三部分（今日会话花费排行）那一套紧凑节奏（6px）；面板上所有花费金额都按三位有效数字渲染（¥9.58），但不细于四位小数——低于 ¥0.0001 的金额显示 ¥0；只有余额行保留四位小数；外加手动刷新按钮与「?」上的花费说明（一句估算口径，一行说明会话金额含它委派的子代理会话，最后一行顶格是当前插件版本号，如 v0.3.13）；面板底部是今日会话花费排行：按今日花费从高到低排列的会话列表——一行就是一个对话，子代理会话的花费已并入委派它的那个会话行（会话名取日志中的中文标题，重命名后自动同步；最多显示前 10 条，其余以「…还有 N 个会话」提示）。
• 本轮花费金额 —— 每条已完成回合的收尾消息操作行行尾（时钟之后）显示纯静态的 ¥X：不可点击、无图标、无「花费」字样、不弹卡片，字体样式逐项复刻时钟文本（13px 次级字号、tertiary 色、nowrap），并且始终显示（不随悬停隐藏，与时钟文本一致——整行的悬停显隐规则让两者同进退）；回合没有 DeepSeek 用量（花费为 0）或加载失败时不显示。
• 输入框花费 pill —— 输入框自己的统计行（官方 time/token pill 所在那条）多一枚：本插件的「环 + 四角星」标记 + 本会话的计费花费，精度与徽标同为三位有效数字；点击向上弹出花费卡片，三行就是花费的三个计费桶（未缓存输入 / 缓存读取 / 输出），文案沿用 DSH token 卡那一套。金额是整段对话的——本会话加上它委派的子代理会话，合并方式与主机自己的汇总一致；它是唯一显示会话自身花费的界面（徽标第二行与面板报的都是当日口径），所以任何地方都没计价的会话不显示 pill，而自身没计价、委派的子代理却烧了钱的会话照常显示。
• 失败与空态 —— 会话或今日没有可计价消耗时显示「暂无消耗记录」而不是编造数字；未配置 key、凭据被拒或传输错误时显示弱化的「额度不可用」徽标，而 API 明确报告「该 key 没有可用余额」时显示普通的 — 徽标。两者点开都是同一个详情面板：第一行用一句本地化短句说明上面为什么是 —（「额度不可用，请检查 API key」，或「该 API key 当前没有可用余额」；Remote 的英文原文不在卡片里渲染），刷新按钮仍在面板里；今日花费来自会话日志，两种情况下都照常在徽标与面板里显示。

数据更新机制

• 会话花费自动跟随 —— 主机端把每条已提交事件计价进每会话投影（billingTodaySpend）并推送给浏览器，本会话自身的花费因此零 Remote 调用、实时更新——显示在输入框 pill 上，那是展示它的界面；投影注册表不存在时回退到 Remote 读取，而 billing/getDelegatedSpend 再把本会话委派的子代理会话加上去（挂载时、切换会话时、手动刷新时与回合结束时各拉一次），所以显示的是整次对话的金额。今日花费（徽标第二行与面板那一行，与同一行的今日 Token）在回合结束时重算（聚合、排行与子代理小计共用同一次扫描）；每条消息的行尾金额来自每会话一次批量拉取，不再逐条消息各发一次请求。
• 切会话只重取会话自己的两条线 —— 余额与今日花费都不随「切到哪个会话」变化，所以切换时不再重取，只有 billing/getSessionSpend 与 billing/getDelegatedSpend 会重发。回合结束与手动刷新会带 force 要一个新值，所以今日行不会把上一轮的花费拖到下一轮才显示；打开详情面板也会补读今日行，因此闲置时来回切会话不会把它落下。不带 force 的读取则先拿到手上的值、重扫在背后跑——凡不是用户刚造成的读取，都不会等当天那次全会话扫描。
• 额度有缓存、可见时每 5 分钟轮询 —— 主机端 15 秒内复用同一份 /user/balance 快照（手动刷新强制取新），单次请求 5 秒超时；浏览器保留最后一次结果，切会话时立即渲染旧值。此外页面可见时每 5 分钟轮询一次（页面隐藏则暂停，回到前台立刻补一次）——下面那条「余额口径的今日消费」以当天第一次采样到的余额为基准，这个节奏就是它的分辨率。
• 刷新期间旧值保留 —— 刷新失败保留上一次有效值，不会清空。

显示样式

真实会话中的会话头部徽标与展开的详情面板：

详情面板特写 —— API 剩余金额、今日 Token 与 今日花费、今日桶明细行（未缓存输入 · 缓存读取 · 输出）与今日会话花费排行：

本轮花费金额特写 —— 操作行行尾（时钟之后）的静态 ¥ 金额：

包结构

包 · 侧 · 作用

[packages/llm-billing](packages/llm-billing) —— @rayadesu/dsh-llm-billing · 主机端 · 负责 /user/balance 传输与峰/谷计价表。对外暴露 billing Remote（getBalance(force?)、getSessionSpend、getTodaySpend、getTodaySessionsSpend、getTurnSpend、getSessionTurnSpends），并注册客户端可见的 billingTodaySpend 投影单元。

[packages/ui-billing](packages/ui-billing) —— @rayadesu/dsh-client-ui-billing · 浏览器端 · 自己挂载 billing Remote，并贡献会话头部徽标与详情面板、消息操作行行尾的静态本轮花费金额、以及输入框下方统计行里的花费 pill（与官方 token pill 并排，金额 = 本会话自身 + 委派的子代理）。

插件管理页的展示元数据

侧栏「插件」页与 设置 → 插件 清单里，每一项的标题、描述与图标都取自包自身的文件——宿主不读插件代码：

• locale/en.json 与 locale/zh.json —— 形状 {"meta": {"title": …, "description": …}}，按当前界面语言解析、回落英文。
• icon.svg —— 自包含 SVG（不引用任何外部字体或图片；它经 <img> 以 data URL 渲染），由 package.json 顶层的 icon 字段声明。条目那圈圆角方块由页面绘制（深色 #151517 + #3b3b3c 边框，浅色白底 + 浅灰边框），所以图标本身必须透明底——不要把底色画进 SVG，否则浅色主题下会变成一块黑方。

两者都经包的 exports 对外暴露，所以声明了 exports 的包必须同时导出 ./locale/*.json：否则 locale 文件会被静默丢弃，条目回落到裸包名。三个包各自带一套 locale 与自己的图标。

前置条件

• DeepSeek Harness（dsh）—— 插件运行在 dsh profile 内。
• 一个 DeepSeek API key —— 余额从 DeepSeek API 读取，所以每个用户都需要自己的 key。

安装

从 Web 插件页安装（官方）

三个包已发布到 npm 的 @rayadesu scope。bundle 把两个插件包声明为普通

dependencies，所以只需一个包名即可装全：pnpm 会把 bundle 的依赖闭包一并装进

profile，hoisted 的 node_modules 让两个组件行名可解析。

1. 侧栏进入 插件 → 添加插件。

2. 输入 @rayadesu/dsh-billing。支持的分发来源就是 npm：bundle 以真实包解包，

pnpm 随之解析它的两个 dependencies。对话框也接受 GitHub 仓库地址或本地目录路径，

但那样装出来的 profile 里只有 bundle、没有那两个插件包——pnpm 不安装 link: 或 git

来源包的依赖，启动会报 2 entries did not activate llm-billing … failed to import。

3. 选安装源（默认 npm 源或中国大陆镜像源），点安装，完成后立即启用。

用命令行安装

用哪个 dsh 命令取决于你的 dsh 安装方式：

• 全局安装 —— 任意目录直接用全局 dsh：

  dsh plugin --profile web add @rayadesu/dsh-billing

• 源码构建的 dsh（deepseek-harness 源码目录）—— CLI 只在源码目录里能解析，

所以要在这个目录里用 pnpm 跑（pnpm dsh 即源码内二进制，等价于全局 dsh）：

  cd deepseek-harness
  pnpm dsh plugin --profile web add @rayadesu/dsh-billing

pnpm 11 发布龄门槛

dsh profile 通过 pnpm 安装插件，而 pnpm 11 的供应链发布龄门槛默认不会采纳发布不足

24 小时的包——刚发布的新版本不会立即被解析。想在发布后立刻拿到最新版：

• 在 profile 的 pnpm 配置里关掉发布龄门槛：

  # ~/.dsh/profiles/web/pnpm-workspace.yaml
  minimumReleaseAge: 0

• 或者在 24 小时窗口内用显式钉版本安装（显式钉版本可绕开门槛；三个包名都要钉——两个

插件包随 bundle 传递安装，也要各自钉住才能过门槛；把 0.3.0 换成你要的版本；

源码构建的 dsh 用 pnpm dsh …，同上）：

  dsh plugin --profile web add @rayadesu/dsh-billing@0.3.0 @rayadesu/dsh-llm-billing@0.3.0 @rayadesu/dsh-client-ui-billing@0.3.0

手动补行（仅当不想用 bundle 时）：

# ~/.dsh/profiles/web/cordis.patch.yml
- insert:
    - id: llm-billing
      name: '@rayadesu/dsh-llm-billing'
    - id: ui-billing
      name: '@rayadesu/dsh-client-ui-billing'

常用命令

下面以全局 dsh 为例；源码构建的 dsh 用 pnpm dsh 并在 deepseek-harness 源码目录执行，

子命令完全一致。

dsh plug

…(truncated)