navid-kianfar/dsh-usage-info

@achasoft/dsh-usage-info

一个用于 DeepSeek Harness（dsh）Web 客户端的会话头部读数显示。它显示模型上下文窗口的占用程度、当前会话按你配置的费率产生的费用，以及你的提供商账户当前余额。上下文和费用在浏览器中根据 harness 已发布的 token 数据计算。余额在主机上读取，因此 API 密钥永远不会到达浏览器。

会话头部中仪表按钮下方展开的用量面板，在首次计费请求之前：上下文和费用待定，余额部分显示一个被拒绝密钥的错误以及一个重试按钮

功能

头部读数

会话头部实用工具区域中的一个按钮。一旦会话发出过请求，它就显示一个带有上下文百分比的圆环；一旦读数到达，就显示账户余额的第一种货币。在这两者存在之前，它显示一个仪表图标，当余额无法读取时（例如在提供商被禁用的默认安装上）显示一个琥珀色圆点。当该余额等于或低于 lowBalanceThreshold 时，按钮变为警告色。点击它打开用量面板；点击外部或按 Escape 关闭。

用量面板

| 部分 | 显示内容 |
|---|---|
| 上下文 | 已用百分比、~已用 / 窗口 token 数、一个分为系统提示、工具定义和对话的条形图，以及一条说明各部分为估算值的注释。在首次请求之前："首次请求后显示"。 |
| 会话费用 | 会话以 costCurrency 计的费用、总 token 数，以及每个桶一行：未缓存输入、缓存写入、缓存读取、输出。在任何计费发生之前，token 数显示为"—"，该部分显示"请求计费后显示"。 |
| 余额 | 每种货币的总额，当提供商区分赠送和充值部分时分别显示，读数的年龄（"刚刚更新"、"3 分钟前"），以及一个立即向提供商请求的刷新按钮。它还会在账户被暂停或余额过低时发出警告，并在余额无法读取时显示一行原因。 |

这些数字是如何得出的：

- 上下文百分比是提供商最后报告的提示大小，并根据此后对话的增加或减少进行调整（压缩会立即降低它）。三个彩色部分使用 harness token 计量器的固定估算，因此请将它们视为比例。它们不会加起来等于总数。
- 会话费用汇总会话日志中每次计费的尝试，包括重试。它是 (未缓存输入 + 缓存写入) x 输入 + 缓存读取 x cacheRead + 输出 x 输出，按每百万 token 计算，使用精确十进制算术。缓存写入按输入费率计费。该数字是估算值。你的提供商的账单才是权威。
- 余额数字是提供商发送的精确十进制字符串。它们绝不会被转换为浮点数。

余额状态

当余额无法显示时，余额部分会说明原因，轮询要么继续尝试，要么停止：

| 状态 | 显示的行 | 轮询 |
|---|---|---|
| 未挂载提供商（默认安装） | 未挂载余额提供商；请启用一个，或在设置中隐藏余额 | 每隔一个间隔检查是否有新挂载的提供商 |
| 已挂载提供商，但没有 API 密钥 | 余额提供商没有 API 密钥；存储密钥后会重试一次 | 持续轮询，因此稍后存储的密钥无需重新加载即可被识别 |
| 端点返回 404 | 此端点不发布余额；请在设置中隐藏余额 | 停止。设置更改后会再次询问 |
| 401 或 403 | 余额端点拒绝了 API 密钥 | 持续轮询 |
| 408 或 504，或提供商自身的超时 | 余额端点超时 | 持续轮询 |
| 429、5xx 或无法访问 | 余额端点无法访问 | 持续轮询 |
| 任何其他状态，或响应体格式错误 | 无法读取余额 | 持续轮询 |

设置卡片

打开 设置 > 插件 > 插件配置，然后展开 使用信息。该卡片会显示已挂载的余额提供商、其端点，以及一个“就绪”或“未就绪”徽章。它还有三个部分的开关、以秒为单位的刷新间隔、低余额阈值、费用货币以及三个费率。

没有保存按钮。开关或文本字段一旦持有有效值就会立即保存。刷新间隔在失焦或按 Enter 时保存，如果它短于主机的缓存窗口（cacheTtlMs，默认 240 秒），则会被拒绝。如果主机拒绝某项更改，该字段会显示“未保存：主机拒绝了此更改。”更改无需重新加载即可到达已打开的会话。

使用信息设置卡片已展开，显示提供商状态、开关、刷新间隔、阈值、货币和费率

要求

- 带有 Web 客户端的 dsh。此版本已针对 dsh 0.1.5-rc.2 进行测试。
- Node.js ^22.19 或 >=24，如 engines 中所声明。
- PATH 上有 pnpm。dsh plugin 会在配置文件目录中运行 pnpm。
- 上下文和费用不需要更多东西。它们读取 harness 已经发布的 token-meter 投影。
- 余额需要启用捆绑的 DeepSeek 提供商（参见启用余额），以及一个主机能够解析的 DeepSeek API 密钥。

支持的余额提供商

此包附带一个提供商：usage-info-deepseek。它使用 Authorization: Bearer  调用 DeepSeek 的 GET /user/balance。密钥来自 harness 凭据接缝，使用 apiKeyEnv 中给出的名称（默认 DEEPSEEK_API_KEY，与 harness DeepSeek 模型适配器使用的名称相同）。对于 harness 的本地凭据存储，第一个有值的来源胜出：

1. 启动 dsh 时所处的环境，
2. 存储的凭据文件（$DSH_HOME/.credentials.yaml，其中 $DSH_HOME 默认为 ~/.dsh），
3. dsh 启动目录中的 .env，
4. $DSH_HOME/.env。

位于 DeepSeek 前面的 OpenAI 兼容网关通常对 /user/balance 返回 404。此时读数会显示“publishes no balance”这一行并停止轮询。

要读取不同的计费后端，请实现从包根导出的 AccountBalanceProvider Service Definition，然后挂载你的插件来替代 usage-info-deepseek。只能挂载一个 provider。如果两个都声明 ctx.accountBalance，加载会失败。

安装

安装到 web profile（即 dsh web 启动时使用的那个）：

dsh plugin --profile web add @achasoft/dsh-usage-info

dsh plugin 会把参数传给 $DSH_HOME/profiles/web 中的 pnpm。之后它会把该包添加到该 profile 的 dsh.profile.bundles，因为该包声明了一个 dsh.bundle patch。重启 dsh web 以加载它。

其他来源的工作方式相同，因为 pnpm 会解析它们：

dsh plugin --profile web add ./dsh-usage-info           # 本地检出，以链接方式安装；先在其中运行 npm run build
dsh plugin --profile web add ./achasoft-dsh-usage-info-0.1.0.tgz

相对路径从你运行 dsh 的目录解析。git 安装会通过该包的 prepare 脚本进行构建。在你把该包添加到 profile 的 pnpm-workspace.yaml 中的 allowBuilds 下之前，pnpm 会阻止该脚本。当安装失败时，dsh plugin 会把你指向 pnpm 打印的那个键。

无需启动即可检查组合后的配置：

dsh --profile web --dump-config

输出中包含一个 # == @achasoft/dsh-usage-info 层，其中有 usage-info、usage-info-ui 和 usage-info-deepseek 这些行。

配置如何分层

组合后的树按以下顺序构建，后面的层优先：

1. 每个 bundle 的 cordis.patch.yml，按 dsh.profile.bundles 的顺序（本包自己的 patch 就是其中之一），
2. 你的 profile 的 $DSH_HOME/profiles/web/cordis.patch.yml，
3. $DSH_HOME/cordis.patch.yml，
4. 任何 --patch 覆盖层。

通过 id 定位某一行的 patch 条目会替换该行的整个 config。它不会合并，因此请重新声明你想保留的每一个键。你在 Settings 卡片中更改的值会作为用户覆盖单独存储在 harness 设置文档的 usage-info: 部分中（默认是 $DSH_HOME/settings.yaml）。这些覆盖会应用在组合后的行之上。

卸载

dsh plugin --profile web remove @achasoft/dsh-usage-info

这会把该包从 profile 的 bundles 中移除。同时还要从你的 profile 的 cordis.patch.yml 中删除任何 usage-info* 行。指定了不存在行的 patch 只会打印警告，但它是无效配置。

启用余额

provider 行默认是禁用的，因为本包无法知道你的部署使用哪个端点或键名。在 $DSH_HOME/profiles/web/cordis.patch.yml 中启用它：

- id: usage-info-deepseek
disabled: false
config:
baseURL: https://api.deepseek.com
apiKeyEnv: DEEPSEEK_API_KEY
timeoutMs: 15000

重启 dsh web。密钥解析成功后，设置卡片上的徽章会显示 Ready。如果没有，卡片会显示 no value for DEEPSEEK_API_KEY。

配置

usage-info（读数偏好）

| 键 | cordis.patch.yml 中的默认值 | Schema | 设置卡片 |
|---|---|---|---|
| showContext | true | 必填布尔值 | 是 |
| showCost | true | 布尔值，默认为 true | 是 |
| costCurrency | USD | 字符串，默认为 USD；必须匹配 ^[A-Z]{3}$ | 是 |
| costRates.input | '0.28' | 十进制字符串，默认为 '0.28'；非负 | 是 |
| costRates.cacheRead | '0.028' | 十进制字符串，默认为 '0.028'；非负 | 是 |
| costRates.output | '0.42' | 十进制字符串，默认为 '0.42'；非负 | 是 |
| showBalance | true | 必填布尔值 | 是 |
| refreshIntervalMs | 300000 | 必填整数，>= 1000 | 是，以整秒为单位 |
| cacheTtlMs | 240000 | 必填整数，>= 0 | 否 |
| lowBalanceThreshold | 未设置（已注释掉） | 可选十进制字符串；留空则禁用警告 | 是 |

- 费率以每百万 token 为单位，写成精确的十进制字符串。根据补丁注释，随附的值是 DeepSeek 的 deepseek-chat 费率。请将它们设置为你实际使用的模型。
- showCost、costCurrency 和 costRates 有 schema 默认值，因此重新声明的 usage-info 行即使省略它们，仍会以上述值加载。其他所有必填键都必须重新声明。
- cacheTtlMs 不得超过 refreshIntervalMs。否则加载会失败，会破坏该规则的设置写入也会失败。
- refreshIntervalMs 是每个打开的标签页轮询的频率。cacheTtlMs 控制实际向提供方请求的频率：每个标签页共享同一份宿主端读数，缓存窗口内的轮询会由它来应答。刷新按钮和更改已存储的凭据都会跳过缓存。
- 关闭 showBalance 会完全停止余额请求。

usage-info-deepseek（余额提供方）

| 键 | 默认值 | Schema | 设置卡片 |
|---|---|---|---|
| disabled | true | 行标志 | 否 |
| baseURL | https://api.deepseek.com | 必填字符串；会移除一个末尾斜杠 | 否 |
| apiKeyEnv | DEEPSEEK_API_KEY | 必填凭据引用：键的名称，绝不是它的值 | 否 |
| timeoutMs | 15000 | 必填整数，>= 1 | 否 |

RPC 与面向模型的接口

浏览器在 usageInfo 命名空间上使用两个宿主方法：

| 方法 | 用途 |
|---|---|
| describe() | 是否已挂载提供方并准备就绪、其端点、可见性标志、费率、货币、刷新间隔和阈值。当 showCost 关闭时，费率会被省略。 |
| balance({ refresh }) | 一次余额读数，除非 refresh 为 true，否则来自缓存。失败会以 { ok: false, code, message } 值返回，而不是抛出错误。 |
没有任何内容是面向模型的。该插件不添加任何工具、提示文本或会话事件。

隐私与安全

- API 密钥保留在主机上。 提供程序在每次读取时解析它，且从不缓存。它不属于任何 RPC 响应的一部分。describe() 仅报告密钥是否已配置。
- 一种出站请求类型： 从主机发起 GET /user/balance，最多每 cacheTtlMs 一次，外加手动刷新。除此之外没有任何内容离开本机。
- 上下文和成本在浏览器中计算，基于它已经接收到的会话投影。它们不会产生额外请求。
- 设置卡片显示端点 URL，并在密钥缺失时显示密钥的名称。失败的 balance() 调用的 message 最多可包含端点错误正文的 512 个字符。读数本身仅显示上面列出的固定单行原因。

已知限制

- 默认安装会显示一行“无余额提供程序”。 提供程序行默认处于禁用状态。按上述方式启用它，或在设置卡片中关闭 显示账户余额。
- 标题中仅显示第一种货币。 所有货币都会在面板中列出，低余额阈值会按各自货币对每个金额进行比较。
- 缓存窗口无法在卡片中编辑。 在你的配置文件补丁中，或在设置文档的 usage-info: 部分中更改 cacheTtlMs。

开发

开发会链接到上两级目录中的 deepseek-harness 检出（../../deepseek-harness，由 package.json 中的 link: devDependencies 设置）：

workspace/
├── deepseek-harness/
└── dsh-plugins/
└── dsh-usage-info/   <- this repository

pnpm install
npm test                 # Typert drift check, then vitest
npm run build            # tsc emit, then tsdown bundle into lib/
npm run check:typert     # only the Typert drift check
npm run typecheck        # tsc --noEmit over src, generated and tests

npm run typecheck 会从链接的检出中解析 harness 类型。比此插件所针对的 harness 更旧的检出会报告缺少类型的错误，例如 TypertClientRemote 上的 usageInfo 或 contextPressure 投影键。

generated/ 存放 Typert RPC 契约。只有 harness 生成器才能生成它，因此它被提交到仓库中。当它不再与 src/host/ 中的 @Remote 方法匹配时，npm test 会失败。要从干净的 harness 检出中重新生成它（这需要几分钟，且不得与另一个插件针对同一检出的重新生成同时运行）：

node scripts/regen-typert.mjs ../../deepseek-harness

许可证

MIT。参见 LICENSE。