rayadesune/DeepSeek-Harness-chat-billing

DeepSeek Harness 计费插件

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

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

显示什么

- 会话头部徽标 —— 两行：剩余余额（剩余金额：¥X，是面板标题去掉 API 前缀的短版，徽标较窄）＋ 本轮对话的计费花费（本会话花费：¥X，含本次对话委派的每个子代理会话，文案与面板完全一致）。
- 详情面板 —— 剩余金额（后跟按余额序列算出的今日消费，见「会话花费是怎么算的」）；今日计费 token 数与今日所有会话合计同一行（今日 Token / 今日花费，token 数按 DSH 的紧凑记数法带自己的单位，如 12.2K tok，token 数值后紧跟当天的缓存命中率（裸数字、无括号）——按 DSH 官方命中率规则渲染：整数百分比，只有部分命中会被凑到 100% 时才逐位多留小数；当天没有 prompt 侧输入就不显示）；紧跟该行下面是今日两行桶明细——token 在上、花费在下——两行各自成行、各自保持自然的  ·  间距（两行之间不做列对齐），排版沿用下方模型分项那一套，行距用第三部分（今日会话花费排行）那一套紧凑节奏；面板上所有花费金额都按三位有效数字渲染（¥9.58），但不细于四位小数——低于 ¥0.0001 的金额显示 ¥0；只有余额行保留四位小数；下一行才是本会话花费（本会话花费——本会话加上它委派的子代理会话，模型分项同样合并；金额后只在这段对话不是今天才创建时才紧跟今日份金额 ¥X——判定用的是会话自身的创建日（子代理读取给出 crossedDay），不再比较两个金额，因为实时的本会话数字与 60 秒缓存的排行行在回合中途本来就会不一致；以及每个模型一行的花费分项（用 DSH 自己的桶名与行序：未缓存输入 ¥X · 缓存读取 ¥Y · 输出 ¥Z），外加手动刷新按钮与「?」上的花费说明（一句估算口径，一行说明金额含本会话委派的子代理会话，一行说明紧跟的金额是本次对话今日花费，最后一行顶格是当前插件版本号，如 v0.3.13）；面板底部是今日会话花费排行：按今日花费从高到低排列的会话列表——一行就是一个对话，子代理会话的花费已并入委派它的那个会话行（会话名取日志中的中文标题，重命名后自动同步；最多显示前 10 条，其余以「…还有 N 个会话」提示）。
- 本轮花费金额 —— 每条已完成回合的收尾消息操作行行尾（时钟之后）显示纯静态的 ¥X：不可点击、无图标、无「花费」字样、不弹卡片，字体样式逐项复刻时钟文本（13px 次级字号、tertiary 色、nowrap），并且始终显示（不随悬停隐藏，与时钟文本一致——整行的悬停显隐规则让两者同进退）；回合没有 DeepSeek 用量（花费为 0）或加载失败时不显示。
- 失败与空态 —— 会话或今日没有可计价消耗时显示「暂无消耗记录」而不是编造数字；未配置 key、凭据被拒或传输错误时显示弱化的「额度不可用」，其提示携带 Remote 自己的错误信息。

数据更新机制

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

显示样式

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

计费插件总览：会话头部徽标与详情面板（剩余金额、今日 Token 与今日花费、本会话花费、按模型分项与今日会话花费排行）

详情面板特写 —— API 剩余金额、今日 Token 与 今日花费、本会话花费（跨天时含括号内的今日份金额）、按模型分项（未缓存输入 · 缓存读取 · 输出）与今日会话花费排行：

详情面板特写：API 剩余金额、今日 Token 与今日花费、本会话花费（含括号内的今日份金额）、未缓存输入/缓存读取/输出分项与今日会话花费排行

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

本轮花费金额特写：操作行行尾的静态金额，位于时钟之后

包结构

| 包 | 侧 | 作用 |
| --- | --- | --- |
| packages/llm-billing —— @rayadesu/dsh-llm-billing | 主机端 | 负责 /user/balance 传输与峰/谷计价表。对外暴露 billing Remote（getBalance(force?)、getSessionSpend、getTodaySpend、getTodaySessionsSpend、getTurnSpend、getSessionTurnSpends），并注册客户端可见的 billingTodaySpend 投影单元。 |
| packages/ui-billing —— @rayadesu/dsh-client-ui-billing | 浏览器端 | 自己挂载 billing Remote，并贡献会话头部徽标与详情面板、消息操作行行尾的静态本轮花费金额。 |

前置条件

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

安装

安装（已发布到 npm，一条命令）

三个包已发布到 npm 的 @rayadesu scope。一条命令同时安装 bundle 与两个插件包
（bundle 把两个插件包声明为 peer 依赖，而 profile 默认不自动安装 peer，所以要显式列出）。

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

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

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

- 源码构建的 dsh（deepseek-harness 源码目录）—— CLI 只在源码目录里能解析，
所以要在这个目录里用 pnpm 跑（pnpm dsh 即源码内二进制，等价于全局 dsh）：

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

pnpm 11 发布龄门槛

dsh profile 通过 pnpm 安装插件，而 pnpm 11 的供应链发布龄门槛默认不会采纳发布不足
24 小时的包——刚发布的新版本不会立即被解析。想在发布后立刻拿到最新版：

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

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

- 或者在 24 小时窗口内用显式钉版本安装（显式钉版本可绕开门槛，把 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 plugin --profile web list    # 列出 web profile 已安装的插件
dsh plugin --profile web add @rayadesu/dsh-billing @rayadesu/dsh-llm-billing @rayadesu/dsh-client-ui-billing
dsh plugin --profile web remove @rayadesu/dsh-billing @rayadesu/dsh-llm-billing @rayadesu/dsh-client-ui-billing
dsh plugin --profile web update  # 把插件更新到当前允许的最新版本
dsh plugin --profile web update --latest  # 忽略声明的版本区间，把所有插件升到最新发布版本

update 遵循 profile package.json 里的版本区间，只在该插件声明的 semver 范围内升级。
加上 --latest（pnpm update 的选项）则忽略这些区间，把所有插件直接升到最新发布的版本——
用于在版本可解析后立刻拿到新发布。源码构建的 dsh 要在 deepseek-harness 目录里用
pnpm dsh … 执行，和其余命令一样。

依赖说明

两个插件包把它们依赖的 DeepSeek Harness 包（@deepseek-ai/cordis、
@deepseek-ai/dsh-credentials、@deepseek-ai/dsh-session 以及客户端运行时包）
声明为 peerDependencies（^0.1.6-alpha.1）。dsh profile 默认不自动安装 peer，所以
这些由 dsh 安装本身通过 profiles/node_modules 回退提供，而不是从 registry 拉取——
无需额外安装，安装机也不需要 registry token。

这些已发布的客户端包里有两个会把只写在 devDependencies 里的运行时模块直接 import 进
产物（dsh-client-store → zustand/immer；dsh-client-ui-primitives → markdown 视图栈
mdast-util-、micromark-、shiki、katex、diff、anser、clsx）。发布的 bundle
把这些留作外部依赖、运行时由 dsh 安装提供，但本仓库是独立 workspace、要自己解析，所以
ui-billing 把它们声明为自己的 devDependencies 供浏览器半测使用。

插件按 0.1.6-alpha.1 发布线构建，同时兼容读取两代 DSH 运行时：live Session 日志面
（0.1.1-rc.2 及以前为 Session.events + header.seedLength，0.1.2-alpha.4 起为
snapshotEvents() + inheritedEventCount），以及持久化服务面（0.1.1-rc.2 及以前为
inspect/listSnapshots，0.1.2-alpha.5 的 handle 化改造后为
open+SessionHandle/list——即含该重构的 checkout master）。投影单元的 init
按新签名声明（带元数据参数），同时保持旧的无参调用方式可用。

浏览器半测通过 module-loader shim 跑已发布的 client bundle；由于 0.1.2-alpha.5
客户端栈把运行时从 dsh-client-runtime（已删除）拆进 dsh-client-store、
dsh-client-ui-session、dsh-client-ui-chat 与 renderer 持有的 SlotRegistry，
测试底座在回退 require 后会复查已注册的 bundle 导出，并用 resolve alias 固定
react 副本。assistant-actions slot 行从 ui-conversation 移到了 ui-chat，
插件客户端侧也引入了 ui-chat 的类型合并。

配置你的 DeepSeek API key

二选一：在网页「模型」页填入（会把 DEEPSEEK_API_KEY 写入 ~/.dsh/.credentials.yaml），或导出环境变量：

export DEEPSEEK_API_KEY=sk-...

重启

dsh web

开发

本仓库是独立的 pnpm workspace：两个插件包从 npm 解析 @deepseek-ai/ peer 包，
构建不需要完整的 DeepSeek Harness checkout。

环境要求：Node ^22.19 || >=24 与 pnpm。

pnpm install                 # 安装 workspace 与 npm 开发依赖
pnpm run build               # host 面（tsc + tsdown + typert 产物），再 client 面
pnpm run typecheck           # 两个编译面
pnpm run test                # vitest 单元/浏览器测试
pnpm run verify              # 发布前校验（prepublishOnly 也会自动运行）

host 面会从源码重新生成 lib/typert.host.js 与 lib/typert.remote-client.，
包名取自各 package.json；client 面重建 lib/client.js。lib/ 是 git-ignored
的构建产物，不要手工修改。一旦 typert 清单里的 TYPERT.package 与 package.json
的 name 不一致，verify 会在发布前直接失败。

typert 生成器只认工作区内已注册协议包里的 Remote/TypertRemoteService 声明，所以
packages/typert-protocol 内嵌了 npm 上 @deepseek-ai/dsh-typert-protocol@0.1.6-alpha.1 的
声明文件；dsh 依赖线升级时，从安装包重新刷新它。

生成出来的 codec 还横跨了一次基线错位：npm 上最新的发布版生成器输出
{ mode, typeSymbol, schema }，而 Web 实际运行的那份 harness checkout 领先于该次发布
（perf(typert): materialize generated schemas on first use），读的是
{ mode, typeSymbol, create() }，create 不是函数就拒绝注册。scripts/typert-compat.mjs
挂在 build:host 末尾、并由 verify 把关，在生成的 schema 旁补上 create 工厂，
让同一份产物在两条线上都能加载。动到会重新生成这些产物的代码后，请跑
pnpm run build:host，不要只跑 tsdown。

发布（bundle 与两个插件包统一版本号；prepublishOnly 会自动跑 verify 门禁）。
要用 npm publish 且必须在各包目录内执行——pnpm publish 会失败（token 读取方式问题），
而 npm publish packages/llm-billing 这种带路径参数的形式会被 npm 解析成 GitHub 仓库简写，
触发假的 git ls-remote 而不是发布。registry 要求 bypass-2FA 的 token（npm login
的会话 token 会 E403）。

一次性配置 token（之后命令里不再出现 token） —— 在 ~/.npmrc 里写一行并引用环境变量，
npm 发布时从环境展开：

//registry.npmjs.org/:_authToken=${NPM_TOKEN}

然后设置环境变量并直接 npm publish —— token 不在任何命令行参数里，也不进 shell 历史：

export NPM_TOKEN=
cd packages/llm-billing && npm publish
cd packages/ui-billing && npm publish
npm publish   # @rayadesu/dsh-billing bundle（仓库根）

（备选：把真实 token 直接写进 ~/.npmrc，如 npm config set //registry.npmjs.org/:_authToken ，
之后命令行同样不含 token。无论哪种方式，绝不把 token 提交进仓库。）

配置

两个包都有合理默认值，下面都是可选的。

主机端（llm-billing）

| 字段 | 默认 | 含义 |
| --- | --- | --- |
| apiKeyEnv | DEEPSEEK_API_KEY | 每次调用时解析的凭据引用（环境变量）名。 |
| baseURL | $DEEPSEEK_BASE_URL，其次 https://api.deepseek.com | 端点基础地址；会追加 /user/balance。 |
| models | V4.1 Flash（deepseek-flash）+ V4 Flash + V4 Pro + V4 Flash Vision Exp + MiMo-V2.5 系列 | 展示用的模型行，按展示顺序；与 DSH llm-deepseek 目录对齐。 |
| billing.peakHours | 09:00–12:00、14:00–18:00（北京，仅工作日） | 高峰时段窗口，仅周一至周五适用；周末与其余时段均为低谷。 |
| billing.models | 官方 V4 + MiMo 费率 | 每个模型的单价行（cacheHitInput、cacheMissInput、output，单位：元/百万 token），可带生效时刻 effectiveFrom（含该时刻）；同一模型的多行即其费率版本。 |

会话花费是怎么算的

- 每条 assistant/message 事件报告三个计费 token 桶：缓存读取、未缓存输入（未缓存输入 + 缓存写入，宿主按未命中单价合并计价）、输出（含推理）。失败或重试的 assistant/attempt 只在自身内嵌 stream 里报告用量，这份样本同样计价（模型取最近一条 request/header）；同一 (turn, step) 的后一份样本替换前一份，llm/retry-started 之后重试的那次累加 —— 与 DSH 自己的回合用量口径一致。
- 每份样本按其发生时刻（北京时间）所在的峰/谷时段单价——以及该时刻生效的费率版本——计价，三个桶分别计费（未缓存输入 ¥X · 缓存读取 ¥Y · 输出 ¥Z，桶名用 DSH 自己的说法），再按模型汇总。高峰窗口仅周一至周五适用；周末全天按低谷价计费。
- 今日花费按同一个计价规则汇总当天（北京时间自然日）所有会话的事件，今日 Token 是同一批计价行的三个计费桶（缓存读取 / 未缓存输入 / 输出）之和，按 DSH 的紧凑记数法加  tok 单位渲染（517 tok、12.2K tok、1.2M tok）；事件归属的日期同样按北京时间计算。
- 本轮花费按同一规则计价该回合 turn/start..turn/end 区间内的事件（定位到收尾消息的会话 id + 消息 id），整会话一趟折出 messageId → 金额 映射后下发。
- 今日会话花费排行按同一规则按会话汇总今日花费（跨天会话只统计今天的部分），从高到低排序；会话名取日志中最后一条 session/title 事件（自动生成的中文标题或用户重命名的新标题）。排行排的是对话：子代理会话（DSH 在其 header 上盖 origin: 'subagent' 与 delegationDepth；用户手动分叉两者都没有）会并入委派它的顶层会话那一行，所以一行就是一个对话。每行给出 total（这次对话的整日花费，含子代理）与 ownTotal（该会话自己的花费）；面板里紧跟的今日份金额读的是 ownTotal，而归组不改变整日合计。
- 没有费率行的模型不计入（内置价目表覆盖 DSH llm-deepseek 目录——V4.1 Flash deepseek-flash、V4 Flash、V4 Pro、V4 Flash Vision Exp——外加已退役的 deepseek-v4.1-flash-expires-on-0910 预览 id 与 MiMo-V2.5 系列；flash 系列各路由同价）。每份样本取自身时刻生效的费率版本：基础价目为 DeepSeek 8 月 17 日实行的费率；flash 系列（V4.1 Flash、V4 Flash、V4 Flash Vision Exp 及退役 id）自 9 月 10 日 12:00（北京时间） 起降为谷时 0.02 / 1.0 / 4.0 元每百万 token、峰时为其两倍——该时刻之前的样本（含 V4.1 Flash 路由自身的早先用量的）沿用被取代的旧价；V4 Pro 路由公告于 9 月 14 日 12:00（北京时间） 改由 V4.1 Flash 服务并按其实施费率计费；MiMo-V2.5 系列不受影响。周末按低谷价计费的规则按 8 月 23 日生效的调整执行。

- 余额口径的「今日消费」（API 剩余金额 后紧跟的那个数字）是纯账户加减，不参与上面的 token 计价：当天（本地自然日）第一次查询到的余额 − 当前余额 + 当天识别出的充值（余额上涨按 10 元步进向上取整，因为厂商只按整十充值）。这条口径与本插件对标的 balanceinfo 程序一致，并且刻意与计价的「今日花费」分成两个数——别的客户端花的钱、或本浏览器打开前花的钱，只体现在这里；两个数字不一致是正常的。当日记录写在本浏览器的 localStorage（键 dsh.billing.balance-day.v1），跨页面刷新与 dsh 重启保留，按本地自然日翻篇（浏览器所在的日，不是宿主的北京日键）；采样发生在挂载、切换会话、手动刷新与页面可见时的 5 分钟轮询，只有当天已经有过一次采样才显示，且不在客户端之间共享。细则见 packages/ui-billing/README.zh.md。

已知限制

- 有费率行才计价 —— 会话花费、本轮花费与今日花费（以及同一行的今日 Token：token 数也只统计这些行）只统计价目表（billing.models）里有的模型。
- 按需聚合 —— 今日花费／今日 Token 与今日会话排行在主机端 60 秒缓存之后计算，且共用同一次扫描；未命中时，活跃会话直接读投影单元，冷会话若缓存行自身的日期不是查询日则零 I/O 直接作答，只有持久化修订变化（或缓存行覆盖查询日）的会话才读日志。读取失败的会话按修订号记住，不再每轮重试。排行的子代理归组在同一趟扫描里完成，不额外读日志；合计仍然对每个会话求和，所以合并只在总额之间归组、不搬钱。
- 排行按需拉取 —— 详情面板打开（或手动刷新）时才拉取排行，徽标一直关着就不会为全量会话扫描买单；「本会话花费」行紧跟的今日份金额也来自这次读取（读该行的 ownTotal，合并进来的子代理金额不会被当成这个会话自己的），所以它不额外发请求（代价是排行未落定时不显示这个数字，且最多滞后 60 秒）。
- 排行只显示前 10 —— 详情面板最多展示前 10 个会话，其余以「…还有 N 个会话」提示；上限在子代理合并之后生效，所以一行就是一个对话。
- 子代理小计随回合更新，不逐事件跟进 —— 会话行里本会话自身那部分是实时的（推送投影），子代理那部分来自 billing/getDelegatedSpend：挂载、手动刷新与回合结束时各拉一次，并与今日花费共用同一个 60 秒宿主缓存。因此子代理在回合中途烧掉的钱会在下一次读取（回合结束、手动刷新或打开面板）时落到父会话金额上，而不是逐事件实时跳动。
- 合并行可能显示「未命名」 —— 子代理的父会话不在本次扫描范围内时（例如父日志已被删除或归档），该行仍按 header 里写的父会话 id 归属，但那份日志从未被读取，标题要等父会话被扫描到才显示。
- 本轮花费只出现在已定稿的收尾消息 —— 中断的回合没有操作行，不显示本轮花费；冷会话（投影缓存直接命中）排行标题可能显示「未命名」，待其日志被重新读取后恢复。
- 额度在两次轮询之间最多旧 15 秒 —— 主机端最多复用 15 秒内的同一份快照，单次请求 5 秒超时；账户在其他客户端产生消耗时，界面值会在下一次轮询（页面可见时 5 分钟一次，隐藏时没有轮询）、手动刷新或刷新浏览器时变化。
- 是估算，不是承诺 —— 会话花费按官方单价对 token 计价；实际计费以服务商为准。

许可证

MIT