余额悬浮窗 Timur-Ziyangareev/llm-balance-widget

LLM Balance Widget

一个可拖动的小组件，给 DeepSeek Harness 用，显示你自己的 LLM API 余额——DeepSeek 或 OpenRouter——并在应用角落换算货币。

功能

- 自带密钥。 密钥存在应用窗口本地，只发给服务商。
- DeepSeek —— 余额来自 GET /user/balance（USD 或 CNY 钱包），外加 ≈ N tokens 估算。
- OpenRouter —— 剩余额度来自 GET /api/v1/credits。
- Token 用量 —— 今天、本月、全部时间，从已登录的 DeepSeek 平台会话读取（公开 API 不提供用量）。
- 换算器 —— 输入所选货币的任意金额，同时显示其他所有货币；点一下数值即可复制。
- 汇率来自本地央行 —— RUB 用俄罗斯央行，USD 用美联储（H.10），CNY 用 PBOC 中间价；某家央行不报某货币时，改用 CBR 交叉汇率。
- 显示货币： 默认 USD，一键切换 RUB 或 CNY —— 余额和换算器都跟着变。
- 语言： 默认 English，另有 Russian 和 中文。语言和货币会被记住。
- 每 60 秒自动刷新，点金额也能刷新；可拖到任意位置，可折叠成一行，位置会被记住。

安装

1. 把本文件夹复制到 <DSH profile>/node_modules/@local/llm-balance-widget。
2. 在 <DSH profile>/package.json 的 dependencies 里加上 "@local/llm-balance-widget": "1.10.1"，在 dsh.profile.bundles 里加上 "@local/llm-balance-widget"。
3. 重启 DeepSeek Harness。

Windows 上桌面配置档位于 %USERPROFILE%\.dsh\profiles\desktop。

获取 API 密钥

1. 打开 <https://platform.deepseek.com>（OpenRouter 则打开 <https://openrouter.ai/keys>）。
2. 用你调用 API 的账号登录。
3. 打开 API keys → Create new API key，随便起个名字。
4. 立刻复制密钥 —— 它只显示一次，以 sk- 开头。
5. 在小组件里点 ⚙，粘贴密钥，点 Save。

如果密钥列表显示 Managed by Harness，说明该密钥由应用保管，无法复制。请自己新建一个密钥——它打开的是同一个账号。

余额属于账号，不属于密钥

钱存在你的账号上；API 密钥只是访问它的密码。所以：

- 新建的密钥显示相同余额，和旧密钥一样——不会丢失，也不会重复；
- 删除密钥不会带走钱；
- 充值一次，账号下所有密钥都能看到；
- 如果两个密钥显示的余额不同，它们属于不同账号——检查一下你用的是哪个登录。

读懂小组件

$ USD [100] = 8 053,07 ₽
1 $ = 80,53 ₽
Convert [10000] RUB
$ 124,18 · € 110,99 · ¥ 828,66 · …
Balance ₽220,90 ≈ 9.8 M tokens ⚙ ▁▃▅▇↗

- 这一行读作等式：外币金额 = 所选货币的结果；
- 下面小字是单位汇率和当日涨跌；
- token 估算按 每 100 万输入 token 0.28 美元（缓存未命中）计算，所以这是上限——输出 token 更贵。

隐私

密钥保存在应用窗口的 localStorage 里，键名为 llm-balance.key.<provider>，只会发往 api.deepseek.com 或 openrouter.ai。没有代理，没有遥测，也没有分析统计。服务端路由有三个：/llm-balance/open（打开服务商页面）、/llm-balance/bank（获取美联储和 PBOC 汇率，这两家不允许浏览器直接请求）、/llm-balance/usage（用 DSH 平台会话读取 token 用量，绝不用你的密钥）；密钥不会到达其中任何一个。

供其他插件使用

每次刷新成功后，小组件会为本地消费者发布最后已知余额——desktop-notify 读取它，在余额偏低时发出警告：

// localStorage
llm-balance.snapshot → { currency: 'USD', amount: 1.42, rub: 131.35, at: 1793362943000 }

当缓存的 CBR 汇率无法换算该货币时，rub 为 null；清除密钥时，这条记录会被删除。除此之外不暴露任何东西：没有密钥，也没有服务商返回的数据。

限制

- token 用量不属于公开 API：它从 DSH 已持有的平台会话中读取，所以只在 DeepSeek 已登录时可用；如果这个私有端点发生变化，它会悄无声息地消失。
- OpenRouter 受 Cloudflare 保护，某些网络下可能返回 403；此时小组件显示 unavailable。
- 美联储每周发布 H.10，PBOC 每天北京时间 09:15 发布中间价；本地银行数据超过 7 天就不再采用，改用 CBR 交叉汇率。
- RUB 汇率每小时重新检查一次；CBR 每天发布一次。

测试

node test/providers.test.cjs
node test/banks.test.mjs

一个小巧的可拖动小组件，用于 DeepSeek Harness：显示你自己的 API 余额（DeepSeek 或 OpenRouter），并在应用角落换算货币。

功能

- 自己的密钥。 保存在应用窗口本地，只发给服务商。
- DeepSeek —— 余额来自 GET /user/balance（USD 和 CNY 钱包），并给出 ≈ N токенов 估算。
- OpenRouter —— 剩余额度来自 GET /api/v1/credits。
- token 消耗 —— 今天、本月和全部时间；数据取自 DeepSeek 平台会话（公开 API 里没有这些数据）。
- 换算器 —— 所选货币下的任意金额都会显示成其他所有货币；点击数值即可复制。
- 本地央行汇率 —— 卢布来自俄罗斯银行，美元来自美联储（H.10），人民币来自 PBOC（中间价）；央行不报价的货币，改用 CBR 交叉汇率。
- 显示货币： 默认美元，一键切换卢布或人民币；余额和换算器都跟着变。
- 语言： 默认英语，另有俄语和中文。语言和货币会被记住。
- 每 60 秒自动刷新，点击金额也可刷新；支持拖动、折叠、记住位置。

安装

1. 把文件夹复制到 <DSH 配置档>/node_modules/@local/llm-balance-widget。
2. 在 <DSH 配置档>/package.json 的 dependencies 中加入 "@local/llm-balance-widget": "1.10.1"，并在 dsh.profile.bundles 中加入 "@local/llm-balance-widget"。
3. 重启 DeepSeek Harness。

Windows 上的配置档路径：%USERPROFILE%\.dsh\profiles\desktop。

如何创建密钥

1. 打开 <https://platform.deepseek.com>（OpenRouter 则打开 <https://openrouter.ai/keys>）。
2. 登录你用来调用 API 的那个账号。
3. 进入 API keys → Create new API key，名字随便填。
4. 立刻复制密钥 —— 它只显示一次，以 sk- 开头。
5. 在小部件里点 ⚙，粘贴密钥，点 保存。

如果密钥列表里写着 Managed by Harness，说明这个密钥存在应用里，复制不出来。自己新建一个：它打开的是同一个账号。

余额绑定的是账户，不是密钥

钱存在账户上，API 密钥只是进入账户的通行证。所以：

- 新密钥显示的是同一个余额，和旧密钥一样：不会丢失，也不会重复；
- 删除密钥不会带走钱；
- 一次充值，账户下所有密钥都能看到；
- 如果两个密钥显示的余额不同，它们来自不同账户，查一下密钥是用哪个登录名创建的。

怎么看小部件

- 每一行读起来像一个等式：某币种金额 = 换算成所选币种的结果；
- 下面那行小字是单位汇率和当日变动；
- token 估算按 每 1M 输入 token $0.28 计算（cache miss），所以这是上限：输出 token 更贵。

隐私

密钥存在窗口的 localStorage 里，键名为 llm-balance.key.<服务商>，只会发送到 api.deepseek.com 或 openrouter.ai。没有代理，也没有遥测。服务端路由有两个：/llm-balance/open（打开密钥页面）和 /llm-balance/bank（美联储和中国人民银行汇率，它们没有 CORS）；密钥不会传给这两个路由。

限制

- OpenRouter 有 Cloudflare 防护，某些网络下会返回 403 —— 小部件显示「不可用」。
- 美联储每周发布一次 H.10，中国人民银行每天北京时间 09:15 发布；超过 7 天的数据会被忽略，改用俄罗斯央行交叉汇率。
- 卢布汇率每小时复核一次；俄罗斯央行每天发布一次。

测试

node test/providers.test.cjs
node test/banks.test.mjs

一个小巧的可拖动窗口小部件，用于 DeepSeek Harness：在应用角落显示你自己的 API 余额（DeepSeek 或 OpenRouter），并换算货币。

功能

- 使用自己的密钥。 只保存在应用窗口中，只发送给服务商。
- DeepSeek —— 通过 GET /user/balance 显示余额（USD 与 CNY 钱包），并估算 ≈ N 个 token。
- OpenRouter —— 通过 GET /api/v1/credits 显示剩余额度。
- token 用量 —— 今日、本月与总计，取自已登录的 DeepSeek 平台会话（公开 API 不提供用量数据）。
- 换算器 —— 输入所选货币的金额，立即显示其余所有货币；点击数值即可复制。
- 使用各国央行汇率 —— 卢布用俄罗斯央行，美元用美联储（H.10），人民币用中国央行中间价；央行不报价的货币使用俄罗斯央行的交叉汇率。
- 显示货币： 默认美元，一键切换卢布或人民币；余额和换算器都会跟着切换。
- 语言： 默认英文，另有俄文和中文。语言与货币都会被记住。
- 每 60 秒自动刷新，点击金额也会刷新；可拖动、可折叠，位置会被记住。

安装

1. 把本文件夹复制到 <DSH 配置目录>/node_modules/@local/llm-balance-widget。
2. 在 <DSH 配置目录>/package.json 的 dependencies 中加入 "@local/llm-balance-widget": "1.10.1"，并在 dsh.profile.bundles 中加入 "@local/llm-balance-widget"。
3. 重启 DeepSeek Harness。

Windows 上的配置目录：%USERPROFILE%\.dsh\profiles\desktop。

如何创建 API 密钥

1. 打开 <https://platform.deepseek.com>（OpenRouter 为 <https://openrouter.ai/keys>）。
2. 用你调用 API 的账号登录。
3. 进入 API keys → Create new API key，名称随意。
4. 立即复制密钥 —— 它只显示一次，并以 sk- 开头。
5. 在小部件中点击 ⚙，粘贴密钥，点击 保存 / Save。

如果密钥列表里写着 Managed by Harness，说明该密钥由应用保管，无法复制。请自己新建一个密钥，它使用的是同一个账号。

余额属于账户，而不属于密钥

钱存在账户里，API 密钥只是访问它的通行证。因此：

- 新建的密钥显示与旧密钥相同的余额，不会丢失也不会重复；
- 删除密钥不会带走余额；
- 充值一次，账户下的所有密钥都能看到；
- 如果两个密钥显示的余额不同，说明它们属于不同账户，请确认登录的是哪个账号。

如何阅读小部件

- 每一行是一个等式：外币金额 = 所选货币的结果；
- 下面一行小字是单位汇率和当日涨跌；
- token 估算是按 每百万输入 token $0.28 计算的（cache miss），因此是上限：输出 token 更贵。

隐私

密钥保存在应用窗口的 localStorage（llm-balance.key.<提供方>），只会发送到 api.deepseek.com 或 openrouter.ai。没有代理、没有遥测。服务端只有两个接口：/llm-balance/open（打开密钥页面）和 /llm-balance/bank（获取美联储和中国央行汇率，它们不允许浏览器直接请求）；密钥不会传给它们。

限制

- OpenRouter 受 Cloudflare 保护，部分网络会返回 403，此时小部件显示「不可用」。
- 美联储 H.10 每周发布一次，中国央行中间价每天北京时间 09:15 发布；超过 7 天的数据会被忽略，改用俄罗斯央行的交叉汇率。
- 卢布汇率每小时重新检查，俄罗斯央行每天发布一次。

测试

node test/providers.test.cjs
node test/banks.test.mjs