余额与花费 Antisakrum2004/deepseek-balance

DeepSeek Balance

在 DeepSeek Harness 聊天面板里，实时查看 DeepSeek 余额和本次会话的预估花费。

仓库：deepseek-balance · 插件与技能 id：dsh-token-balance · 俄语版：README.ru.md

DeepSeek Harness 会话中的状态条与弹出面板

为什么做这个

DeepSeek Harness 已经在消息框下方显示 token 数量和缓存统计，但从不显示花了多少钱。想知道一次长会话花了多少，只能打开 DeepSeek 账单页面。

这个插件把两个数字放到你本来就在看的地方：输入框下方一行。

● ¥23.13 · $2.24 · потрачено $0.17

- ¥23.13 · $2.24 — 来自 GET https://api.deepseek.com/user/balance 的实时余额，覆盖 API 返回的两种货币（绿点表示上次请求成功）。
- потрачено $0.17 — 本次会话到目前为止的花费，根据服务商上报的 token 数量和 DeepSeek 官方价目表估算。

点击这一行查看完整明细。

你会看到什么

在输入框停靠区 — 状态条紧挨着内置的轮次/步数和 token 统计，不重复显示：

输入框停靠区中的状态条

在弹出面板里（点击状态条）— 余额拆分、本次会话花费（美元和 ¥）、缓存命中率、未缓存输入、缓存读取/写入、输出、总 token 数、上次刷新时间、手动刷新按钮，以及估算所用的精确价格：

余额与花费弹出面板

功能

| 实时余额 | 每分钟轮询一次，服务端缓存 45 秒，弹出面板里可手动刷新。 |
| 两种货币 | CNY 和 USD，按货币代码查找，绝不按数组下标。 |
| 精确 token 数 | 取自服务商上报的 tokenUsage 投影，不是估算值。 |
| 区分高峰/低谷 | 按当前 UTC 时间选择高峰或低谷价目表。 |
| 感知模型 | 从会话读取 modelSelection，使用该模型对应的价格行。 |
| 对钱诚实 | 花费标注为估算；¥ 是标注过的换算值（DeepSeek 以 USD 计费）。 |
| 安静降级 | 网络或 API 失败时保留上次正常余额，圆点变红。 |
| 无需构建 | 手写的浏览器 bundle，面向 window.__ModuleLoader__——不用打包器，不用 node_modules。 |
| 经得起应用更新 | 只改动 DSH 配置档（plugins/ 加一行补丁记录）。绝不修改 app.asar。 |
| 可逆 | uninstall.ps1 会删除补丁行（先备份）、插件和技能。 |

环境要求

- DeepSeek Harness 带 Web GUI（桌面应用或 dsh web），已在 DSH Desktop 0.2.1-rc.2 上验证。
- <DSH_HOME>/.credentials.yaml 里有 DeepSeek API key，和 harness 用的是同一个 key。
芯片在宿主进程上读取它，绝不发给浏览器。
- PowerShell 7（pwsh）或 Windows PowerShell 5.1。
- 宿主进程能对外访问 api.deepseek.com 的 HTTPS。

安装

三条等效路径。都幂等——重复执行只会刷新文件。

1. 让助手来装（技能装好之后）：

«поставь dsh-token-balance» / "install the token balance chip"

2. 自己运行安装脚本：

powershell -ExecutionPolicy Bypass -File .\skill\scripts\install.ps1

3. 双击 install.cmd——优先用 pwsh，没有就回退到 Windows PowerShell。

然后按 F5 重新加载 DeepSeek Harness 窗口。客户端 bundle 只在页面加载时读一次，已经打开的窗口会一直渲染旧 UI，直到重新加载。

安装脚本只写三个位置：

| 路径 | 内容 |
| <DSH_HOME>\profiles\<desktop\|web>\plugins\token-balance\ | 插件（3 个文件） |
| <DSH_HOME>\profiles\<desktop\|web>\cordis.patch.yml | 一行带标记的 insert 记录（先做带时间戳的备份） |
| <DSH_HOME>\skills\dsh-token-balance\ | 配套技能（加 -NoSkill 跳过） |

DSH_HOME 默认是 %USERPROFILE%\.dsh。DSH 安装目录、它的 app.asar、任何 node_modules 都不改动——所以应用更新不会弄坏它。

验证

the host half is mounted and can reach the API
Invoke-WebRequest http://127.0.0.1:<port>/token-balance | Select-Object -Expand Content
{"ok":true,"at":1792784049918,"available":true,
"balances":[{"currency":"USD","total":"2.24","granted":"0.00","toppedUp":"2.24"},
{"currency":"CNY","total":"23.93","granted":"0.00","toppedUp":"23.93"}]}

node --check skill/assets/plugin/lib/client.js # client bundle parses

端口就是 GUI URL 的端口（$env:DSH_WEB_URL，通常由应用打印出来）。

工作原理

flowchart LR
subgraph Host["DSH host process (Node)"]
P["token-balance pluginlib/index.js"]
C["45 s cache"]
P --- C
end
subgraph Browser["GUI renderer"]
W["client.jscomposer-dock slot"]
end
K["~/.dsh/.credentials.yaml(sk-...)"]
A["api.deepseek.com/user/balance"]

W -- "GET /token-balance" --> P
P -- read key --> K
P -- Bearer key --> A
A -- JSON --> P
P -- "balance JSON(never the key)" --> W

- 宿主半边——一个普通 Cordis 插件。它在 ctx.webServer 上注册 GET /token-balance，把上游响应缓存 45 s，并用 in-flight promise 守卫合并并发请求。出错时返回 { ok: false, error }—— no-api-key、upstream-<status> 或一条消息。
- 客户端部分 —— 手写的 CommonJS 包，由 window.__ModuleLoader__ 加载。
它在 conversation.composer.dock 插槽里注册一个控件（order: 2），并从插槽 props 读取会话的 tokenUsage 和 modelSelection 投影。
没有构建步骤，除平台预置的 react / react/jsx-runtime 外没有其他依赖。
- 技能 —— skill/SKILL.md，安装到 <DSH_HOME>/skills/，这样以后的智能体可以直接安装、验证或移除整套东西，不必重新推导细节。

更深入的说明 —— 补丁语义、插槽契约、客户端包格式，以及已经踩过的坑 ——见 MEMORY.md 和 docs/ARCHITECTURE.md。

准确性

token 数量是精确的 —— 来自服务商上报的 tokenUsage 投影。金额是估算：客户端用 DeepSeek 官方标价给这些 token 计价，价格表在 PRICES，单位为美元 / 1M token，分低谷 / 高峰：

| 模型 | 缓存命中 | 缓存未命中 | 输出 |
| deepseek-flash (V4.1-Flash) | 0.003 / 0.006 | 0.15 / 0.30 | 0.60 / 1.20 |
| deepseek-v4-pro | 0.022 / 0.044 | 0.66 / 1.32 | 1.98 / 3.96 |

高峰时段为 UTC 周一至周五 01:00–04:00 和 06:00–10:00，不含中国法定节假日；其余时间都是低谷，按半价计。¥ 金额按 7.2 CNY/USD 换算 —— DeepSeek 本身以美元计费，所以弹层里写的是 ≈ ¥。

价格表用一次真实余额下降验证过：18 985 856 缓存输入 + 96 828 未缓存输入 + 107 807 输出 token，按 Flash 低谷价计算为 $0.136 ≈ ¥0.98，而同一时间窗口内钱包实际减少了 ¥1.00。

DeepSeek 调价后请更新 PRICES；来源链接在代码注释里。
余额本身是从 GET /user/balance 读到的事实，不是估算。

安全与隐私

- 余额路由绑定在 harness webserver 的 127.0.0.1 上，只响应 GET/HEAD，不发送 CORS 头 —— 其他网页读不到响应。
- 只返回余额，绝不返回 API key、key 前缀或任何其他凭据。key 在宿主进程内读取，只用于一次出站请求。
- 不向任何第三方发送数据。没有遥测，没有分析，除 api.deepseek.com 外没有其他远程端点。
- 插件不修改 DSH 安装，每次改 cordis.patch.yml 之前都会先做带时间戳的备份。
- 任何已经能访问回环端口的进程都能读到同样的数字 —— 这和 harness 本身处于同一信任边界。

项目结构

deepseek-balance\
README.md, README.ru.md 用户文档（英文 / 俄文） MEMORY.md 工程笔记与来之不易的 DSH 细节 AGENTS.md 给编码智能体的指引 CHANGELOG.md, CONTRIBUTING.md LICENSE MIT install.cmd、uninstall.cmd 双击即可运行的包装脚本
docs\
ARCHITECTURE.md 请求流程、契约、失败状态 images\ README 里用到的截图
skill\
SKILL.md 面向智能体的安装 / 验证 / 卸载操作手册 scripts\install.ps1 安装脚本 scripts\uninstall.ps1 卸载脚本 assets\plugin\package.json DSH 插件清单（dsh.client 声明） assets\plugin\lib\index.js 宿主端：GET /token-balance + 密钥 + 缓存 assets\plugin\lib\client.js 浏览器端：输入框停靠区的状态标签 + 弹层

卸载

powershell -ExecutionPolicy Bypass -File .\skill\scripts\uninstall.ps1

或者双击 uninstall.cmd。加上 -KeepSkill 可保留已安装的技能。两个脚本都支持 -DshHome <path> 和 -Profile <name>。

故障排查

| 现象 | 原因 / 修复 |
| 输入框下方没有状态行 | 页面没重新加载，或者配置档的补丁行缺失——检查 cordis.patch.yml，然后按 F5。 |
| 红点，报错 no-api-key | <DSH_HOME>\.credentials.yaml 里没有 sk-... 密钥；登录或补上密钥。 |
| 余额一直显示 ··· | 宿主进程连不上 api.deepseek.com（代理 / 防火墙）。 |
| 只有消费，没有余额 | 路由能通，但上游返回非 200；弹层里会显示错误文本。 |
| 数字看起来是旧的 | 状态标签缓存上游数据 45 秒，每 60 秒轮询一次；用弹层里的刷新按钮。 |
| 状态标签显示余额但不显示消费 | 会话还没有 tokenUsage 投影——发一条消息就会出现。 |

路线图

- 弹层里可选的按天 / 按会话历史表（投影缓存里已有数据）。
- 价格表改为从配置读取，不再写死常量。
- 为纯命令行的 dsh web 安装提供 web 配置档路径（已实现，尚未在纯命令行环境上测试）。
- 默认隐藏费用，改由设置项控制。

许可证

MIT。与 DeepSeek 无隶属关系；相关名称仅作描述性使用。