前言¶
DSH 的插件化思路是把 Web GUI 的扩展能力拆成可安装、可移除的包。使用 DSH 做模型调用时，本机用量、余额和费用估算往往分散在不同地方。dsh-billing 把这部分监控集中到 DSH Web GUI：侧边栏显示余额，设置页管理单价与账本，Agent 可以查询余额和用量。
这是什么¶
dsh-billing 是 DSH Web GUI 的实时计费监控插件。它统计本机模型调用用量与费用，按供应商和模型单价计费，支持 DeepSeek v4 峰谷价、官方余额同步、官方单价同步和账本持久化。仓库地址中的账号为 nianpangzhi233，许可证为 MIT。插件通过官方接口与客户端 slots 系统实现，不修改 DSH 源码。
核心功能¶
实时余额¶
侧边栏底部会出现余额 pill，刷新周期为 2 秒。余额状态点会区分“充足 / 不足 / 耗尽”，告警时会闪烁。
概览面板¶
点击余额 pill 后，会在侧边栏内展开面板，显示已消费、调用次数、输入 token、输出 token 和最近流水。流水带有峰谷标签。收起侧边栏时，面板也会自动收起。
供应商与峰谷单价¶
单价匹配顺序为：
供应商+模型 → 同名模型 → 供应商默认 → 全局默认
DeepSeek v4 自 08-17 起采用峰谷定价：高峰为北京 9–12、14–18，空闲时按半价计；命中缓存输入按低单价计。
官方余额与单价同步¶
填入 DeepSeek API Key 后，可以调用官方接口：
GET /user/balance
拉取总余额、赠金和充值，并自动锚定到插件余额；也支持手动粘贴校准。
官方单价同步可以一键拉取 DeepSeek 官方模型单价，按内置基础价与持久化覆盖合并。该能力仅在官方价目页可达时生效，需要平台 web provider。
设置页与 Agent 工具¶
DSH 设置中会出现「计费」分段，内容覆盖：
余额、阈值、默认单价、供应商单价表格、数据管理
Agent 提示词中会自动出现工具说明：
billing_balance
它用于查询余额、费用、token 用量和按模型明细。
持久化¶
账本 JSON 原子写入工作区。DSH 重启后会自动恢复余额、单价和流水。
安装与启用¶
先确认本机环境满足以下要求：
Node: ^22.19.0 || >=24.0.0
peerDependencies:
- @deepseek-ai/cordis ^4.0.1
- @deepseek-ai/dsh-tools ^0.1.0-rc.6
- react ^18.2.0
- react-dom ^18.2.0
本包为纯 JS，无构建步骤，lib/ 即发布产物，git 安装即可用，无需 prepare 脚本，也无需构建授权。
从仓库安装：
dsh plugin --profile web add github:nianpangzhi233/dsh-billing
本地 checkout 或 tarball 安装也可以：
dsh plugin --profile web add ./dsh-billing
dsh plugin --profile web add ./dsh-billing-0.1.0.tgz
经过上面的步骤，重启 dsh web。之后侧边栏底部会出现余额 pill，DSH 设置中会出现「计费」分段，Agent 提示词中会自动出现 billing_balance 工具说明。
典型用法¶
1、进入配置入口：
DSH 设置 → 「计费」分段
也可以点击侧边栏底部余额 pill 展开面板。
2、配置余额：使用 DeepSeek API Key 自动同步官方余额，或手动粘贴锚定；也可以设置初始余额和低余额告警阈值，默认阈值为 ¥20。
3、配置单价：设置未知供应商默认单价，单位为 ¥ / 1M tokens；维护按供应商/模型的单价表，可增删行；需要时点击「同步官方单价」拉取 DeepSeek 官方价目。
4、管理数据：查看账本路径与保存时间、保存配置、重置用量；重置用量需要两次点击确认。
5、查询用量：在 Agent 中使用 billing_balance 工具，查询余额、费用、token 用量与按模型明细。
数据与环境¶
账本文件为：
.dsh-billing-ledger.json
查找顺序是工作区目录优先，spRoot 兜底。v2 结构包含：
config / usage / ledger / startedAt
token 用量按分离计数：
inputTokens
cacheReadTokens
outputTokens
路由限制为：
/api/dsh-billing/*
仅限 loopback，并做同源校验。
适用场景与注意¶
- 只统计本机 DSH 的模型调用；官方余额包含其他渠道消费，建议定期同步校准。
- API Key 以明文存于本机账本文件，与
~/.dsh/dsh-ssh.json使用同一信任模型，文件权限为0600；同步请求仅发给api.deepseek.com，响应只取余额字段。 - 计费结果为估算，单价与费率以 DeepSeek 官方为准。
- 插件以当前
dsh进程权限运行。安装前建议检查源码、许可证（MIT）和依赖要求。 - DSH 插件生态强调可插拔，社区目录是独立站点，不等同于官方应用商店。
结尾¶
dsh-billing 的价值在于把本机 DSH 的用量、余额和费用估算放进 Web GUI 和 Agent 工具里，方便日常使用时查看。
GitHub：
https://github.com/nianpangzhi233/dsh-billing
如果通过 DSH 插件目录安装，可按插件名 dsh-billing 查找具体条目。
