dsh-cost-meter 1.9.65 → 1.9.67

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/README.md CHANGED
@@ -3,7 +3,7 @@
3
3
  <p align="center">Cost tracking and subscription quotas for DeepSeek Harness</p>
4
4
 
5
5
  <p align="center">
6
- <a href="https://github.com/Han-1413141/dsh-cost-meter/releases/latest"><img src="https://img.shields.io/badge/version-1.9.65-4176E6?style=flat-square" alt="version"></a>
6
+ <a href="https://github.com/Han-1413141/dsh-cost-meter/releases/latest"><img src="https://img.shields.io/badge/version-1.9.67-4176E6?style=flat-square" alt="version"></a>
7
7
  <a href="https://www.npmjs.com/package/dsh-cost-meter"><img src="https://img.shields.io/npm/dm/dsh-cost-meter?label=downloads&style=flat-square&color=4176E6" alt="npm monthly downloads"></a>
8
8
  <a href="https://github.com/Han-1413141/dsh-cost-meter/stargazers"><img src="https://img.shields.io/github/stars/Han-1413141/dsh-cost-meter?label=stars&style=flat-square&color=D9A400" alt="GitHub stars"></a>
9
9
  <a href="LICENSE"><img src="https://img.shields.io/badge/license-MIT-green?style=flat-square" alt="MIT license"></a>
@@ -42,20 +42,20 @@ Restart `dsh web` after installation or updates. **Desktop** uses its bundled CL
42
42
  The PowerShell installer checks pnpm and Git and uses the `web` profile by default:
43
43
 
44
44
  ```powershell
45
- irm https://raw.githubusercontent.com/Han-1413141/dsh-cost-meter/v1.9.65/install.ps1 | iex
45
+ irm https://raw.githubusercontent.com/Han-1413141/dsh-cost-meter/v1.9.67/install.ps1 | iex
46
46
  ```
47
47
 
48
48
  Install a pinned Git tag:
49
49
 
50
50
  ```sh
51
- dsh plugin --profile web add github:Han-1413141/dsh-cost-meter#v1.9.65
51
+ dsh plugin --profile web add github:Han-1413141/dsh-cost-meter#v1.9.67
52
52
  ```
53
53
 
54
54
  See [installation and updates](docs/install.en.md) for uninstalling or installing without Git.
55
55
 
56
56
  </details>
57
57
 
58
- Current release **v1.9.65**: [release notes](docs/update-notes-1.9.65.md#english) · [troubleshooting](docs/install-troubleshooting.md)
58
+ Current release **v1.9.67**: [release notes](docs/update-notes-1.9.67.md#english) · [troubleshooting](docs/install-troubleshooting.md)
59
59
 
60
60
  ## Feature overview
61
61
 
package/README.zh-CN.md CHANGED
@@ -3,7 +3,7 @@
3
3
  <p align="center">DeepSeek Harness 费用统计与订阅额度插件</p>
4
4
 
5
5
  <p align="center">
6
- <a href="https://github.com/Han-1413141/dsh-cost-meter/releases/latest"><img src="https://img.shields.io/badge/version-1.9.65-4176E6?style=flat-square" alt="version"></a>
6
+ <a href="https://github.com/Han-1413141/dsh-cost-meter/releases/latest"><img src="https://img.shields.io/badge/version-1.9.67-4176E6?style=flat-square" alt="version"></a>
7
7
  <a href="https://www.npmjs.com/package/dsh-cost-meter"><img src="https://img.shields.io/npm/dm/dsh-cost-meter?label=downloads&style=flat-square&color=4176E6" alt="npm monthly downloads"></a>
8
8
  <a href="https://github.com/Han-1413141/dsh-cost-meter/stargazers"><img src="https://img.shields.io/github/stars/Han-1413141/dsh-cost-meter?label=stars&style=flat-square&color=D9A400" alt="GitHub stars"></a>
9
9
  <a href="LICENSE"><img src="https://img.shields.io/badge/license-MIT-green?style=flat-square" alt="MIT license"></a>
@@ -42,20 +42,20 @@ dsh plugin --profile web add dsh-cost-meter
42
42
  PowerShell 脚本自动检查 pnpm 和 Git,默认安装到 `web` Profile:
43
43
 
44
44
  ```powershell
45
- irm https://raw.githubusercontent.com/Han-1413141/dsh-cost-meter/v1.9.65/install.ps1 | iex
45
+ irm https://raw.githubusercontent.com/Han-1413141/dsh-cost-meter/v1.9.67/install.ps1 | iex
46
46
  ```
47
47
 
48
48
  固定 Git tag 安装:
49
49
 
50
50
  ```sh
51
- dsh plugin --profile web add github:Han-1413141/dsh-cost-meter#v1.9.65
51
+ dsh plugin --profile web add github:Han-1413141/dsh-cost-meter#v1.9.67
52
52
  ```
53
53
 
54
54
  更新、卸载及无 Git 的安装方法见[安装说明](docs/install.md)。
55
55
 
56
56
  </details>
57
57
 
58
- 当前版本 **v1.9.65**:[更新说明](docs/update-notes-1.9.65.md#中文) · [安装排障](docs/install-troubleshooting.md)
58
+ 当前版本 **v1.9.67**:[更新说明](docs/update-notes-1.9.67.md#中文) · [安装排障](docs/install-troubleshooting.md)
59
59
 
60
60
  ## 功能总览
61
61
 
@@ -0,0 +1,60 @@
1
+ # 官方余额的凭据来源
2
+
3
+ DSH 的账号登录模式使用推理令牌,它与开放平台 API Key 是不同凭据:把推理令牌当作 `Authorization: Bearer` 发给 `/user/balance` 会返回 401。旧版插件只读取模型设置指定的凭据名,在该名称被宿主进程环境覆盖时无法选用凭据库里的开放平台 Key([#201](https://github.com/Han-1413141/dsh-cost-meter/issues/201))。
4
+
5
+ ## 已登录的官方账号
6
+
7
+ 登录官方账号后,无需另行保存 API Key。未选择其他余额账号、未配置余额专用 Key 或模型 Key 时,插件通过宿主 `deepseekAccount` 服务读取与「设置 → 账号」同源的钱包,包含充值钱包与赠送钱包,再沿用插件自身的多币种挑选规则。凭据由宿主账号服务持有并负责鉴权,插件不接触 token,也不直接请求 `platform.deepseek.com`。账号服务缺席或明确退出时,该来源不可用;已登录账号的查询失败会显示错误。
8
+
9
+ 模型 Key 与登录账号可以属于不同账户。自动模式下,未选择其他余额账号、也未配置专用 Key 时,模型 Key 优先于登录账号钱包。
10
+
11
+ 从 1.9.67 起,可在「设置 → 费用 → 概览 → 官方账户余额 → 余额来源」选择“自动(模型 Key 优先)”或“DSH 登录钱包”。默认仍为自动;选择登录钱包后,未配置专用 Key 且未手选其他余额账号时,只读取宿主登录钱包,忽略模型 Key。未登录或钱包读取失败时显示错误,不改查模型 Key。手选账号和专用余额 Key 始终优先。选择会保存到配置,重启后保留;切换时取消旧请求并重建余额对账基准。登录钱包可能与模型实际计费账户不同。
12
+
13
+ ## 余额专用 API Key
14
+
15
+ 从 1.7.46 起,也可以在「设置 → 费用 → 官方账户余额」的「余额专用 API Key」中填写开放平台 Key,点击「保存」,再点击「刷新余额」。密钥通过现有凭据接口写入 DSH 凭据库中的 `DEEPSEEK_BALANCE_API_KEY`,不写入插件配置、账本或安装目录,不回传到浏览器。输入框保存后清空,只显示是否配置及来源。也可以在启动 DSH 的环境中设置同名变量;来源顺序由宿主决定。已验证的 DSH 0.2.2-rc.1 和 0.2.2-rc.3 优先读取凭据文件,文件未配置该引用时再读取环境变量;旧宿主的来源顺序可能不同。
16
+
17
+ Desktop 使用相同的费用设置页与宿主凭据接口。更新时使用 Desktop 自带 CLI 的 `--profile desktop`,然后完全退出并重新打开 Desktop;[桌面端安装步骤](install-troubleshooting.md#desktop-安装与更新)包含命令来源与重装禁用状态的处理。
18
+
19
+ ## 查询规则
20
+
21
+ 1. 手动选择了其他余额账号时,只使用所选账号的 Key 请求 `https://api.deepseek.com/user/balance`。Key 缺失或查询失败时直接显示错误。
22
+ 2. 使用默认余额账号且配置了专用 Key 时,只使用该 Key 请求官方余额,与模型的 `baseURL`、`apiKeyEnv` 及账号登录状态无关。
23
+ 3. 自动模式下,未配置专用 Key,但配置了模型 API Key 时,用模型 Key 查询余额。支持 DeepSeek 官方 HTTPS 根地址、版本路径以及 `/anthropic`、`/anthropic/v1`;实际余额请求始终发往 `/user/balance`。中转或代理地址不受支持,不发送请求,也不改查登录账号的钱包。
24
+ 4. 未配置显式余额 Key 时,选择登录钱包会直接经宿主账号服务查询;自动模式则在没有模型 API Key 时使用账号钱包。两种情形都不依赖模型设置是否可读。账号服务缺席或明确退出时,该来源不可用;已登录但查询失败时显示账号侧错误,自动查询按刷新间隔重试。
25
+ 5. 专用 Key 返回 401 时显示认证失败及配置方法,不改用其他账户重试。自动查询遵守刷新间隔,手动刷新可立即重试。
26
+ 6. 保存或清除专用 Key 会作废旧余额、取消在途请求并重新建立对账基准;不修改模型凭据。清除后按上面的顺序重新选择来源。
27
+
28
+ 当前余额凭据更换、清除,以及所用模型路由的 `apiKeyEnv` 或 `baseURL` 变化,会作废余额缓存、在途响应与对账基准。无关模型配置不影响手动选择的余额账号或专用 Key。账号退出、凭据失效及账号服务替换同样会清除旧状态。插件只读取宿主公开的配置描述与生命周期事件;重新挂载时,为所有余额来源重新建立对账基准。
29
+
30
+ ## 已保存的 Key 返回 401
31
+
32
+ “已配置,来源为 file”表示 DSH 凭据库里有这个值,不表示开放平台仍接受它。HTTP 401 表示当前请求的凭据未通过官方认证;仅凭状态码无法区分 Key 被撤销、保存内容不完整或凭据类型不对。重新保存相同内容不会改变服务端认证结果,最小化窗口也不会使无效 Key 恢复。
33
+
34
+ 请在 DeepSeek 开放平台确认 Key 状态。旧 Key 已丢失、无法核对时,创建新 Key,保存到“余额专用 API Key”,然后点击“刷新余额”。输入框保存后清空是隐藏密钥的正常行为,不是凭据丢失。不要在 issue 中上传 Key、凭据文件或请求头。
35
+
36
+ [#502](https://github.com/Han-1413141/dsh-cost-meter/issues/502#issuecomment-6877106296) 的报告者 @7WhiteChocolate 确认换用新建 Key 后恢复。旧 Key 未保留,具体失效原因没有得到验证;本次没有把该问题归因于窗口恢复或插件更新,该次排查没有改变余额来源顺序。
37
+
38
+ ## 验证
39
+
40
+ 验证使用合成凭据和 HTTP 响应,覆盖真实 DSH 凭据 provider 的来源优先级、保存/清除、缓存取消、迟到响应、对账基准以及 Host/Client codec。专项回归还覆盖账号与模型 Key 的来源优先级、旧版设置接口与新版配置描述、模型路由切换、官方 Messages 地址、账号异常脱敏、刷新节流、对账基准持久化及客户端错误渲染。
41
+
42
+ ## English
43
+
44
+ DSH account login uses an inference token, which is not an Open Platform API key: sending it as `Authorization: Bearer` to `/user/balance` returns 401. Older plugin versions read only the credential name named by the model settings, so a host-provided environment variable of that name could shadow a stored Open Platform key ([#201](https://github.com/Han-1413141/dsh-cost-meter/issues/201)).
45
+
46
+ **Signed-in official account.** No additional API key is needed. When no other balance account is selected and no dedicated or model Key is configured, the plugin reads the same wallet as **Settings → Account** (topped-up plus bonus) through the host `deepseekAccount` service, then applies its multi-currency selection. The host account service holds and uses the credential; the plugin never sees the token and never requests `platform.deepseek.com` directly. A missing account service or an explicit sign-out makes this source unavailable; a failed query for a signed-in account produces an error.
47
+
48
+ The model Key and the signed-in account can belong to different accounts. In Auto mode, when no other balance account is selected and no dedicated key is configured, a model key takes priority over the signed-in account’s wallet.
49
+
50
+ Since 1.9.67, **Settings → Cost → Overview → Account balance → Balance source** offers **Auto (model key first)** and **DSH account wallet**. Auto remains the default. The wallet choice bypasses model credentials and never falls back to them when the wallet is unavailable. Selected balance accounts and dedicated keys still take priority. The preference survives restart; changing it cancels pending requests and resets reconciliation. The signed-in wallet may belong to a different account from the model key.
51
+
52
+ Alternatively, since 1.7.46, enter an Open Platform key in **Settings → Cost → Account balance → Balance API key**, save it, then refresh the balance. DSH stores it as `DEEPSEEK_BALANCE_API_KEY`; the plugin never stores it in its config or ledger, or returns it to the browser. The same environment variable is supported under the host's normal credential priority rules.
53
+
54
+ In Auto mode, query priority is **manually selected balance account → dedicated Key → model Key → signed-in account**. A manually selected account or dedicated Key uses the fixed official HTTPS balance endpoint. A missing or invalid selected Key produces an error. Model settings support the official root, version paths, `/anthropic`, and `/anthropic/v1`. Balance requests use `https://api.deepseek.com/user/balance`. A relay or proxy `baseURL` produces an unsupported-endpoint error without sending the Key or querying the signed-in wallet. Account-query failures remain visible, and automatic retries follow the refresh interval. Saving or clearing the dedicated Key leaves model credentials intact. Account-login inference tokens cannot query the Open Platform balance endpoint directly.
55
+
56
+ Changes to the active balance credential or its model route (`apiKeyEnv` or `baseURL`) invalidate cached and in-flight balances and clear reconciliation baselines. Unrelated model changes leave manually selected accounts and dedicated Keys unchanged. Account sign-out, expiry, and account-service replacement also clear old state. The plugin reads public configuration descriptions and lifecycle events. Every balance source establishes a new reconciliation baseline when the plugin mounts again.
57
+
58
+ When no model API key is resolved, an unavailable model settings service does not block the signed-in account wallet. Manual refresh retries an unavailable route; a resolved model Key still requires a verified official endpoint.
59
+
60
+ **A stored key returns HTTP 401.** “Configured, source: file” only confirms that DSH has a stored value. HTTP 401 means that the official API rejected the credential; the status alone cannot distinguish a revoked key, an incomplete value or the wrong credential type. Check the key in the DeepSeek Open Platform. If the old value is unavailable, create a new key, save it as the dedicated balance key and refresh. Clearing the input after saving hides the secret; it does not delete the stored credential. Never post keys, credential files or request headers in an issue. In [#502](https://github.com/Han-1413141/dsh-cost-meter/issues/502#issuecomment-6877106296), @7WhiteChocolate confirmed that a new key restored the balance. The reason the old key stopped working was not established.
@@ -4,6 +4,8 @@
4
4
 
5
5
  **Display currency** changes how amounts are shown. **Official price currency** selects the DeepSeek price table fetched by Sync. USD prices multiplied by a display exchange rate are not the official CNY prices.
6
6
 
7
+ The display-currency selector lists 26 ECB reference currencies (USD, CNY, EUR, GBP, JPY, KRW, INR, HKD, SGD, AUD, CAD, CHF, NZD, BRL, MXN, ZAR, TRY, SEK, NOK, DKK, PLN, THB, IDR, MYR, PHP, ILS). CNY and EUR keep the amount recorded at the time of each call; every other currency converts at the latest daily reference rate, so its historical totals follow that rate. Switching the display currency never changes the ledger, which stays in USD.
8
+
7
9
  For a CNY account, open **Settings → Cost → Prices → Official price sync**, choose **CNY**, wait for auto-save, then click **Sync from official docs** and apply. The CNY hint includes a button to select CNY; this selection alone does not fetch prices or reprice history. Check the sync result: if the CNY page is unavailable and syncing falls back to USD, the hint remains. Switching the table currency preserves recorded amounts. Historical repricing is a separate, explicitly confirmed action that creates a backup and skips records with incomplete logs. No setting changes merely because the hint appears.
8
10
 
9
11
  For the September 2026 Flash off-peak rates, USD prices of $0.003 / $0.15 / $0.60 correspond to CNY prices of ¥0.02 / ¥1 / ¥4 per million cache-read / uncached-input / output tokens. Multiplying the USD prices by 7.2 gives ¥0.0216 / ¥1.08 / ¥4.32, 8% above that CNY table. The ratio is a comparison of those published prices, not a market exchange rate or a universal rule for every model. Sources: [DeepSeek USD prices](https://api-docs.deepseek.com/quick_start/pricing/) and [DeepSeek CNY prices](https://api-docs.deepseek.com/zh-cn/quick_start/pricing/).
@@ -14,6 +16,8 @@ Use the matching official table when comparing bills. Exchange-rate changes appl
14
16
 
15
17
  **显示币种**只决定金额如何展示;**官方价格币种**决定同步哪套 DeepSeek 价格。美元价格乘以显示汇率,不等于官方人民币报价。
16
18
 
19
+ 展示币种选择器提供 26 种 ECB 参考汇率(USD、CNY、EUR、GBP、JPY、KRW、INR、HKD、SGD、AUD、CAD、CHF、NZD、BRL、MXN、ZAR、TRY、SEK、NOK、DKK、PLN、THB、IDR、MYR、PHP、ILS)。人民币和欧元保留每次调用发生时记录的金额,其他币种按最新每日参考汇率折算,因此历史合计会跟随该汇率变动。切换展示币种不会改动账本,账本恒以美元保存。
20
+
17
21
  人民币账户请进入**设置 → 费用 → 价格 → 官方价格同步**,选择 **CNY**,等待自动保存,再点击同步并应用。提示中的按钮可以直接选择 CNY;仅选择币种不会抓取价格或重算历史。同步后应查看结果:若人民币页面不可用、回退到美元表,提示仍然保留。切换价目表币种保留已有金额;历史重定价是需要确认的独立操作,会保存备份并跳过日志不完整的记录。出现提示本身不会修改设置。
18
22
 
19
23
  以 2026 年 9 月 Flash 谷价为例,每百万缓存读取/未命中输入/输出为 $0.003/$0.15/$0.60,对应官方 ¥0.02/¥1/¥4;美元报价乘以 7.2 后是 ¥0.0216/¥1.08/¥4.32,比这套人民币价高 8%。这个比值只描述这些报价,不是市场汇率,也不适用于所有模型。来源见上方 DeepSeek 中英文官方价格页。
@@ -1,182 +1,184 @@
1
- # Custom balance configuration
2
-
3
- [简体中文](custom-balance-sources.md) · [Features](features.en.md)
4
-
5
- ## Request and response configuration
6
-
7
- **POST with a JSON body:** in **Settings → Cost → Quota**, expand a custom balance entry, select **POST**, then fill in **Request body (JSON)**. For example, if the endpoint expects an account and returns `{"data":{"balance":12.5}}`:
8
-
9
- ```json
10
- {"account_id":"example-account","include_credit":true}
11
- ```
12
-
13
- Set **Extract rules (JSON)** to `{"remaining":"data.balance"}`. Valid JSON is saved per entry and sent exactly as entered, including nested values and large integer IDs. Invalid JSON shows an error and keeps the last valid configuration; clearing the editor removes the body. GET/HEAD send no body while retaining it for a later switch back to POST. `Content-Type: application/json` is added automatically unless you supply a Content-Type header (any capitalization).
14
-
15
- Existing `request.body` objects and raw strings remain supported. The body is ordinary saved configuration; `{{VAR}}` credential substitution applies only to request headers. For header authentication, use a reference such as `{"Authorization":"Bearer {{MY_API_KEY}}"}` and the credential input below it.
16
-
17
- **Display currency conversion:** open **Settings → Cost → Quota**, expand a custom balance entry, and enable **Convert USD balance to display currency**. It defaults to off for each entry. Keep **Source currency** set to the endpoint's actual currency. With a USD balance of 54.3792, a CNY display rate of 7.2 and two decimal places, the balance displays as **¥391.53**. Spend and API/manual limits convert together in the sidebar, settings and tooltips; progress percentages and stored balances do not change. Enter a manual limit in the source currency. The setting persists as `convertToDisplayCurrency: true` inside that `customBalances[]` entry (legacy `customBalance` is also supported).
18
-
19
- The global exchange rate converts **USD to the display currency**. CNY/EUR source balances and Credits keep their original units; the switch is disabled for them. Alibaba Cloud balances use the currency returned by its API. No exchange-rate lookup or extra balance request is made when toggling this setting. Turning it off restores the original currency immediately.
20
-
21
- **DeepSeek CNY billing:** USD prices × the display exchange rate and the official CNY table can give different amounts. Settings → Cost → Prices now explains this and provides a CNY selection button. See [currency selection, sync and settlement timing](billing-currency.md#english).
22
-
23
- For Qianwen / Alibaba Cloud fund accounts, use **Add Qianwen / Alibaba Cloud balance** to query available funds with a RAM AccessKey signature. The card uses the currency returned by the API. See the [setup, permissions and balance definition](qianwen-balance.md#english).
24
-
25
- Qwen Token Plan can use the [official CLI subscription quota](qwen-cli-quota.md#english). Install the CLI on the DSH host and run `qianwen auth login` as the same OS user. Local estimates remain the default; CLI mode shows current account credits without changing the local ledger.
26
-
27
- Local Qwen Token Plan credits include Plan calls assigned to Qwen. Existing subscription aliases such as `qwen` and `qwen-tokenplan` remain supported; custom providers can select Qwen under Model statistics → Billing class, or use an explicit vendor name and plan marker for auto detection. Explicit API calls are excluded. The pay-as-you-go `qianwen` provider is not assigned merely because its model ID is identical. Models outside the credits table need all three rates configured.
28
-
29
- Baidu Qianfan Token Plan Personal now supports [quota queries via console Cookie](baidu-token-plan.md), including credits and Token modes. Store the Cookie in the Baidu quota card or set `BAIDU_QIANFAN_COOKIE` on the DSH host.
30
-
31
- Xiaomi MiMo Token Plan quotas are queried with the **MiMo console cookie**, not an API key: log in at `platform.xiaomimimo.com`, press F12 → Network → find the `balanceAlertConfig` request and paste the full `cookie` request header into the MiMo card in Settings → Cost → Quotas (it must include `serviceToken` and `userId`; the DSH credential store keeps it as `MIMO_COOKIE`). The card shows the plan/compensation credit windows with the period-end reset (Beijing time) plus a balance row. Copy a fresh console cookie when the card reports an expired login. Token Plan inference keys (`tp-*` / `ttp-*`) are not accepted by this console adapter. Local plan statistics use the calendar month; compensation and balance are displayed without estimates because local calls cannot be attributed to those pools.
32
-
33
- Each CLIProxyAPI source has a **Gemini quota only** option for its Antigravity groups. It defaults to off. Intentional filtering to no visible quota shows an empty list; malformed quota data still reports an error.
34
-
35
- The `extract` rules support constants, dot paths, arithmetic, nested operations, `expression` formulas and `sum` over arrays. See the formula examples below. **`divide` fits NewApi and other endpoints that meter balance in integer quota** (1 USD = 500000 quota — the same conversion cc-switch uses).
36
-
37
- - **`unit: "CREDITS"`**: displays non-monetary credits using the configured decimal precision and a Credits suffix. Dollar spend is not converted to credits or shown as today's credit usage. Credit bars use the endpoint's credit cap; the global monetary budget does not apply.
38
- - **Plain HTTP is allowed for loopback endpoints**: `http://` is accepted when the host is `127.0.0.1` / `localhost` / `[::1]` (the traffic never leaves the machine), which covers local read-only routes that listen on loopback only and serve no TLS (e.g. `dsh-workbuddy-connect`'s `/plugins/dsh-workbuddy-connect/status`). **LAN HTTP** requires `allowInsecureHttp` and an exact `host:port` allowlist entry.
39
-
40
- ### WorkBuddy credits example (local plugin route)
41
-
42
- The dedicated **WorkBuddy credits** quota card now supports dsh-xdpool. Select **Credit source → dsh-xdpool** when using multiple connectors; current, all and selected accounts work across CN/global pools. See the [integration notes](update-notes-1.9.38.md#english).
43
-
44
- With `dsh-workbuddy-connect` installed, its web status route already returns the aggregated credit total — no credential needs to be copied:
45
-
46
- ```json
47
- {
48
- "enabled": true,
49
- "display": "sidebar",
50
- "refreshMinutes": 15,
51
- "label": "WorkBuddy 积分",
52
- "labelEn": "WorkBuddy Credits",
53
- "unit": "CREDITS",
54
- "request": { "url": "http://127.0.0.1:3080/plugins/dsh-workbuddy-connect/status", "method": "GET", "headers": {} },
55
- "extract": { "remaining": "credits.total" }
56
- }
57
- ```
58
-
59
- Adjust the port and response fields to the local service. This example requires the other plugin to expose that route. Cost-meter refuses redirects and continues to enforce configured credential host allowlists.
60
-
61
- For NewApi `GET /api/usage/token` (response `{ "code": 200, "data": { "total_granted": ..., "total_used": ..., "total_available": ..., "unlimited_quota": false } }`):
62
-
63
- ```json
64
- {
65
- "enabled": true,
66
- "display": "both",
67
- "refreshMinutes": 15,
68
- "label": "NewApi",
69
- "labelEn": "NewApi",
70
- "unit": "USD",
71
- "request": {
72
- "url": "https://your-newapi-host/api/usage/token",
73
- "method": "GET",
74
- "headers": { "Authorization": "Bearer {{NEWAPI_API_KEY}}" }
75
- },
76
- "extract": {
77
- "remaining": { "op": "divide", "path": "data.total_available", "by": 500000 },
78
- "maxBudget": { "op": "divide", "path": "data.total_granted", "by": 500000 },
79
- "spend": { "op": "divide", "path": "data.total_used", "by": 500000 },
80
- "unit": "USD"
81
- }
82
- }
83
- ```
84
-
85
- - `{{NEWAPI_API_KEY}}` resolves from the DSH credential vault or an environment variable (**placeholders work in headers only** — URLs accept full addresses or host-relative paths beginning with one slash, without placeholders);
86
- - Unlimited-quota tokens (`unlimited_quota: true`) have no `total_available`, so `remaining` cannot be extracted and the query reports “remaining is missing or not numeric” — use a limited-quota token or a middle-layer endpoint that converts the units;
87
- - Entry point: Settings → Cost (Quota tab) → “Custom provider balance” → expand config; or write `config.customBalance` in `storages/cost-meter/ledger.json`.
88
-
89
- ### Credentials & security
90
-
91
- - **Variable naming**: `{{VAR_NAME}}` follows the `<ROUTE>_API_KEY` convention — `<ROUTE>` is the Provider ID from the DSH Models page (Settings → Models), uppercased with non-alphanumeric characters replaced by underscores, e.g. `openai`→`{{OPENAI_API_KEY}}`, `anthropic`→`{{ANTHROPIC_API_KEY}}`, `abc23-d`→`{{ABC23_D_API_KEY}}`. Sharing a name with the Models page means the balance query and model calls **share the same key** (both resolve from the DSH credential store). This note is also shown above the “Headers (JSON)” input in Settings.
92
- - **Credential input fields**: after expanding an entry, the “Credential input” section renders one write-only field per `{{VAR}}` placeholder found in the headers — the key goes straight into the DSH credential store (excluded from plugin configuration and ledger files, and never echoed back); no need to hand-edit environment variables or credential files.
93
- - **Automatic plaintext migration**: older versions let a literal `Bearer sk-…` in the headers leak into `ledger.json` in plaintext. The plugin imports such keys into the DSH credential store at startup and replaces the header value with a `{{CUSTOM_BALANCE_KEY_…}}` placeholder (derived from the entry's host + header name, stable across restarts) — nothing breaks. From now on `ledger.json` and the config shipped to the browser **never contain plaintext keys**: suspected secret headers (Authorization / X-Api-Key / Bearer / sk- prefixes / long opaque strings) are blanked, while placeholders and ordinary headers pass through.
94
- - **Credential allowlist `allowedHosts`**: when headers carry credentials (placeholders or plaintext), the outbound host must be on this list or the request is refused — protection against leaked keys when importing someone else's config. Without a list, requests proceed with a one-time logged warning. The entry panel provides an “Allowed hosts” input (comma-separated).
95
- - **Mixed credential templates**: a header containing both a static secret and dynamic placeholders cannot be migrated as one nested credential. It is reported as pending and excluded from persisted/client config. Store the static part separately and use credential references throughout. Pure forms such as `Bearer {{VAR}}` and `{{USER}}:{{PASS}}` remain supported.
96
-
97
-
98
- ## Formulas and subscription balances
99
-
100
- Since 1.9.47, **Cost → Quotas → Custom balance → Extract rules (JSON)** supports `expression` formulas and nested operations. Use `remaining` for available balance, `spend` for usage and `maxBudget` for the total allowance; do not map a usage field directly to `remaining`.
101
-
102
- For example, if the endpoint returns `{"data":{"amount_total":15000000,"amount_used":2500000}}` and uses 500000 quota units per USD, enter:
103
-
104
- ```json
105
- {
106
- "remaining": {"expression": "(data.amount_total - data.amount_used) / 500000"},
107
- "spend": {"expression": "data.amount_used / 500000"},
108
- "maxBudget": {"expression": "data.amount_total / 500000"}
109
- }
110
- ```
111
-
112
- This example shows $25 remaining, $5 used and $30 total. Adjust field paths and the conversion factor to the endpoint's actual response. NewAPI subscription objects use `amount_total` and `amount_used`, but their response wrapper differs from the account-balance endpoint; adapt the paths accordingly. See the [upstream field definitions](https://github.com/QuantumNous/new-api/blob/main/web/src/features/subscriptions/types.ts).
113
-
114
- If `data.subscriptions` is an array and each item contains `subscription.amount_total` and `subscription.amount_used`, calculate each item's value and sum the results:
115
-
116
- ```json
117
- {
118
- "remaining": {
119
- "op": "sum",
120
- "path": "data.subscriptions",
121
- "value": {"expression": "(subscription.amount_total - subscription.amount_used) / 500000"}
122
- },
123
- "spend": {
124
- "op": "sum",
125
- "path": "data.subscriptions",
126
- "value": {"expression": "subscription.amount_used / 500000"}
127
- },
128
- "maxBudget": {
129
- "op": "sum",
130
- "path": "data.subscriptions",
131
- "value": {"expression": "subscription.amount_total / 500000"}
132
- }
133
- }
134
- ```
135
-
136
- The array must contain the active subscriptions you intend to display. Existing paths, constants, `add`/`subtract` rules with `paths`, and `divide` rules with `path`/`by` remain supported. Use `args` for nested operations:
137
-
138
- ```json
139
- {"remaining":{"op":"divide","args":[{"op":"subtract","args":["data.amount_total","data.amount_used"]},500000]}}
140
- ```
141
-
142
- Expressions support `+ - * / % **`, parentheses, array indices, and `min`, `max`, `abs`, `round`, `floor` and `ceil`. They do not run JavaScript. Missing fields, non-numeric values, division by zero and non-finite results report a parsing failure instead of showing a zero balance.
143
-
144
- A `sum` rule also accepts an optional `where` object: only array items whose listed fields strictly equal the given values are summed, for example `{"op":"sum","path":"data","where":{"provider":"workbuddy"},"value":{"expression":"windows[2].limit"}}`. `where` allows at most 16 fields and rejects `__proto__` / `prototype` / `constructor` keys.
145
-
146
- ## Dashboard links and local services
147
-
148
- Each custom balance entry has an optional **Dashboard link** (`dashboardUrl`) under **Cost → Quotas**. Use a complete HTTP(S) account or billing URL without embedded credentials. The sidebar row and progress card show an arrow next to that entry's name; it opens a new tab without refreshing the balance. Leave it blank to omit the link. Query URLs, headers and credentials are never used to construct navigation links.
149
-
150
- Root-relative URLs such as `/plugins/dsh-workbuddy-connect/status` follow the running DSH web server's actual port. Independent WorkBuddy2API deployments use an absolute URL. Non-loopback HTTP requires both `allowInsecureHttp: true` and an exact `host:port` in `allowedHosts`; this explicitly permits plaintext transport. Redirects remain blocked.
151
-
152
- The **+ WorkBuddy2API credits** preset reads `GET /api/credits/expiry?package_limit=1` with an admin `X-Admin-Token` stored as `WORKBUDDY2API_ADMIN_TOKEN` in DSH credentials. Set the real server address and matching allowlist, update expired admin tokens, then enable the card. The displayed `summary.available_remaining` is the active account pool's available credits, not currency, a single model API key's allowance, or the incomplete expiry snapshot total. No model request or upstream credit-refresh task is triggered. Authentication was tested with synthetic responses, not a live account.
153
-
154
- ## Magpie WorkBuddy credits example
155
-
156
- Under **Cost → Quotas → Custom provider balance**, choose **Add entry** and fill in:
157
-
158
- ```json
159
- {
160
- "label": "Magpie WorkBuddy credits",
161
- "unit": "CREDITS",
162
- "refreshMinutes": 5,
163
- "request": {
164
- "url": "http://127.0.0.1:3425/v1/magpie/quotas",
165
- "method": "GET",
166
- "headers": {}
167
- },
168
- "extract": {
169
- "remaining": { "op": "sum", "path": "data", "where": { "provider": "workbuddy" }, "value": { "expression": "windows[2].limit * windows[2].remaining / 100" } },
170
- "maxBudget": { "op": "sum", "path": "data", "where": { "provider": "workbuddy" }, "value": { "expression": "windows[2].limit" } },
171
- "spend": { "op": "sum", "path": "data", "where": { "provider": "workbuddy" }, "value": { "expression": "windows[2].limit * windows[2].used / 100" } }
172
- },
173
- "allowedHosts": ["127.0.0.1:3425"],
174
- "allowInsecureHttp": false
175
- }
176
- ```
177
-
178
- Magpie's `/v1/magpie/quotas` returns multiple providers and accounts. The `where` clause on a `sum` rule matches fields exactly, so only `provider=workbuddy` accounts are summed; Trae, MiniMax and other providers are excluded. WorkBuddy's `used` / `remaining` values are percentages (0–100) and `limit` is the credit capacity, so the example converts them to absolute credits with `limit * percentage / 100`. It uses `windows[2]` (`Total credits`, base plus extra credits) as the total. Change all three `windows[2]` references to `windows[0]` to show only the base monthly credits, or `windows[1]` for extra credits only.
179
-
180
- No API key is needed when Magpie runs locally on the default `127.0.0.1:3425`. If Magpie runs on another host or enables authentication, edit the URL, add `Authorization: Bearer {{MAGPIE_API_KEY}}` to the request headers, add the exact `host:port` to the allowlist and save the key in the credential field. Prefer HTTPS; enable **Allow non-loopback HTTP** only for a non-loopback HTTP URL. The query only reads Magpie's existing statistics and makes no model requests.
181
-
182
- This preset does not depend on the official WorkBuddy desktop login or a WorkBuddy connector. Users who already run `dsh-magpie-quota` can keep using it; the two displays are independent.
1
+ # Custom balance configuration
2
+
3
+ [简体中文](custom-balance-sources.md) · [Features](features.en.md)
4
+
5
+ ## Request and response configuration
6
+
7
+ **POST with a JSON body:** in **Settings → Cost → Quota**, expand a custom balance entry, select **POST**, then fill in **Request body (JSON)**. For example, if the endpoint expects an account and returns `{"data":{"balance":12.5}}`:
8
+
9
+ ```json
10
+ {"account_id":"example-account","include_credit":true}
11
+ ```
12
+
13
+ Set **Extract rules (JSON)** to `{"remaining":"data.balance"}`. Valid JSON is saved per entry and sent exactly as entered, including nested values and large integer IDs. Invalid JSON shows an error and keeps the last valid configuration; clearing the editor removes the body. GET/HEAD send no body while retaining it for a later switch back to POST. `Content-Type: application/json` is added automatically unless you supply a Content-Type header (any capitalization).
14
+
15
+ Existing `request.body` objects and raw strings remain supported. The body is ordinary saved configuration; `{{VAR}}` credential substitution applies only to request headers. For header authentication, use a reference such as `{"Authorization":"Bearer {{MY_API_KEY}}"}` and the credential input below it.
16
+
17
+ **Display currency conversion:** open **Settings → Cost → Quota**, expand a custom balance entry, and enable **Convert USD balance to display currency**. It defaults to off for each entry. Keep **Source currency** set to the endpoint's actual currency. With a USD balance of 54.3792, a CNY display rate of 7.2 and two decimal places, the balance displays as **¥391.53**. Spend and API/manual limits convert together in the sidebar, settings and tooltips; progress percentages and stored balances do not change. Enter a manual limit in the source currency. The setting persists as `convertToDisplayCurrency: true` inside that `customBalances[]` entry (legacy `customBalance` is also supported).
18
+
19
+ The global exchange rate converts **USD to the display currency**. CNY/EUR source balances and Credits keep their original units; the switch is disabled for them. Alibaba Cloud balances use the currency returned by its API. No exchange-rate lookup or extra balance request is made when toggling this setting. Turning it off restores the original currency immediately.
20
+
21
+ **Balance display currency (official and custom balances):** under **Settings → Cost → Display → Sidebar → Official balance → Balance currency**, choose **Native currency** (default), **Follow display currency**, or any code in the currency catalog. The official balance, granted/top-up split and custom balance remaining/spend amounts are then shown converted with the current daily reference rate; amounts use the symbol from the currency catalog (for example `£7.5`). A code without a rate (outside the catalog, or missing) keeps the native amount and symbol so they cannot disagree. While this is not **Native currency**, the per-entry **Convert USD balance to display currency** switch above no longer applies. Budget limits and progress percentages are still calculated in the balance's own currency while amounts are shown converted; raw snapshots stay unchanged. The switch is display-only: it makes no extra balance request, keeps the fetched snapshot, looks up no rate, and never changes the ledger.
22
+
23
+ **DeepSeek CNY billing:** USD prices × the display exchange rate and the official CNY table can give different amounts. Settings → Cost → Prices now explains this and provides a CNY selection button. See [currency selection, sync and settlement timing](billing-currency.md#english).
24
+
25
+ For Qianwen / Alibaba Cloud fund accounts, use **Add Qianwen / Alibaba Cloud balance** to query available funds with a RAM AccessKey signature. The card uses the currency returned by the API. See the [setup, permissions and balance definition](qianwen-balance.md#english).
26
+
27
+ Qwen Token Plan can use the [official CLI subscription quota](qwen-cli-quota.md#english). Install the CLI on the DSH host and run `qianwen auth login` as the same OS user. Local estimates remain the default; CLI mode shows current account credits without changing the local ledger.
28
+
29
+ Local Qwen Token Plan credits include Plan calls assigned to Qwen. Existing subscription aliases such as `qwen` and `qwen-tokenplan` remain supported; custom providers can select Qwen under Model statistics → Billing class, or use an explicit vendor name and plan marker for auto detection. Explicit API calls are excluded. The pay-as-you-go `qianwen` provider is not assigned merely because its model ID is identical. Models outside the credits table need all three rates configured.
30
+
31
+ Baidu Qianfan Token Plan Personal now supports [quota queries via console Cookie](baidu-token-plan.md), including credits and Token modes. Store the Cookie in the Baidu quota card or set `BAIDU_QIANFAN_COOKIE` on the DSH host.
32
+
33
+ Xiaomi MiMo Token Plan quotas are queried with the **MiMo console cookie**, not an API key: log in at `platform.xiaomimimo.com`, press F12 → Network → find the `balanceAlertConfig` request and paste the full `cookie` request header into the MiMo card in Settings → Cost → Quotas (it must include `serviceToken` and `userId`; the DSH credential store keeps it as `MIMO_COOKIE`). The card shows the plan/compensation credit windows with the period-end reset (Beijing time) plus a balance row. Copy a fresh console cookie when the card reports an expired login. Token Plan inference keys (`tp-*` / `ttp-*`) are not accepted by this console adapter. Local plan statistics use the calendar month; compensation and balance are displayed without estimates because local calls cannot be attributed to those pools.
34
+
35
+ Each CLIProxyAPI source has a **Gemini quota only** option for its Antigravity groups. It defaults to off. Intentional filtering to no visible quota shows an empty list; malformed quota data still reports an error.
36
+
37
+ The `extract` rules support constants, dot paths, arithmetic, nested operations, `expression` formulas and `sum` over arrays. See the formula examples below. **`divide` fits NewApi and other endpoints that meter balance in integer quota** (1 USD = 500000 quota — the same conversion cc-switch uses).
38
+
39
+ - **`unit: "CREDITS"`**: displays non-monetary credits using the configured decimal precision and a Credits suffix. Dollar spend is not converted to credits or shown as today's credit usage. Credit bars use the endpoint's credit cap; the global monetary budget does not apply.
40
+ - **Plain HTTP is allowed for loopback endpoints**: `http://` is accepted when the host is `127.0.0.1` / `localhost` / `[::1]` (the traffic never leaves the machine), which covers local read-only routes that listen on loopback only and serve no TLS (e.g. `dsh-workbuddy-connect`'s `/plugins/dsh-workbuddy-connect/status`). **LAN HTTP** requires `allowInsecureHttp` and an exact `host:port` allowlist entry.
41
+
42
+ ### WorkBuddy credits example (local plugin route)
43
+
44
+ The dedicated **WorkBuddy credits** quota card now supports dsh-xdpool. Select **Credit source → dsh-xdpool** when using multiple connectors; current, all and selected accounts work across CN/global pools. See the [integration notes](update-notes-1.9.38.md#english).
45
+
46
+ With `dsh-workbuddy-connect` installed, its web status route already returns the aggregated credit total — no credential needs to be copied:
47
+
48
+ ```json
49
+ {
50
+ "enabled": true,
51
+ "display": "sidebar",
52
+ "refreshMinutes": 15,
53
+ "label": "WorkBuddy 积分",
54
+ "labelEn": "WorkBuddy Credits",
55
+ "unit": "CREDITS",
56
+ "request": { "url": "http://127.0.0.1:3080/plugins/dsh-workbuddy-connect/status", "method": "GET", "headers": {} },
57
+ "extract": { "remaining": "credits.total" }
58
+ }
59
+ ```
60
+
61
+ Adjust the port and response fields to the local service. This example requires the other plugin to expose that route. Cost-meter refuses redirects and continues to enforce configured credential host allowlists.
62
+
63
+ For NewApi `GET /api/usage/token` (response `{ "code": 200, "data": { "total_granted": ..., "total_used": ..., "total_available": ..., "unlimited_quota": false } }`):
64
+
65
+ ```json
66
+ {
67
+ "enabled": true,
68
+ "display": "both",
69
+ "refreshMinutes": 15,
70
+ "label": "NewApi",
71
+ "labelEn": "NewApi",
72
+ "unit": "USD",
73
+ "request": {
74
+ "url": "https://your-newapi-host/api/usage/token",
75
+ "method": "GET",
76
+ "headers": { "Authorization": "Bearer {{NEWAPI_API_KEY}}" }
77
+ },
78
+ "extract": {
79
+ "remaining": { "op": "divide", "path": "data.total_available", "by": 500000 },
80
+ "maxBudget": { "op": "divide", "path": "data.total_granted", "by": 500000 },
81
+ "spend": { "op": "divide", "path": "data.total_used", "by": 500000 },
82
+ "unit": "USD"
83
+ }
84
+ }
85
+ ```
86
+
87
+ - `{{NEWAPI_API_KEY}}` resolves from the DSH credential vault or an environment variable (**placeholders work in headers only** — URLs accept full addresses or host-relative paths beginning with one slash, without placeholders);
88
+ - Unlimited-quota tokens (`unlimited_quota: true`) have no `total_available`, so `remaining` cannot be extracted and the query reports “remaining is missing or not numeric” — use a limited-quota token or a middle-layer endpoint that converts the units;
89
+ - Entry point: Settings → Cost (Quota tab) → “Custom provider balance” → expand config; or write `config.customBalance` in `storages/cost-meter/ledger.json`.
90
+
91
+ ### Credentials & security
92
+
93
+ - **Variable naming**: `{{VAR_NAME}}` follows the `<ROUTE>_API_KEY` convention — `<ROUTE>` is the Provider ID from the DSH Models page (Settings → Models), uppercased with non-alphanumeric characters replaced by underscores, e.g. `openai`→`{{OPENAI_API_KEY}}`, `anthropic`→`{{ANTHROPIC_API_KEY}}`, `abc23-d`→`{{ABC23_D_API_KEY}}`. Sharing a name with the Models page means the balance query and model calls **share the same key** (both resolve from the DSH credential store). This note is also shown above the “Headers (JSON)” input in Settings.
94
+ - **Credential input fields**: after expanding an entry, the “Credential input” section renders one write-only field per `{{VAR}}` placeholder found in the headers — the key goes straight into the DSH credential store (excluded from plugin configuration and ledger files, and never echoed back); no need to hand-edit environment variables or credential files.
95
+ - **Automatic plaintext migration**: older versions let a literal `Bearer sk-…` in the headers leak into `ledger.json` in plaintext. The plugin imports such keys into the DSH credential store at startup and replaces the header value with a `{{CUSTOM_BALANCE_KEY_…}}` placeholder (derived from the entry's host + header name, stable across restarts) — nothing breaks. From now on `ledger.json` and the config shipped to the browser **never contain plaintext keys**: suspected secret headers (Authorization / X-Api-Key / Bearer / sk- prefixes / long opaque strings) are blanked, while placeholders and ordinary headers pass through.
96
+ - **Credential allowlist `allowedHosts`**: when headers carry credentials (placeholders or plaintext), the outbound host must be on this list or the request is refused — protection against leaked keys when importing someone else's config. Without a list, requests proceed with a one-time logged warning. The entry panel provides an “Allowed hosts” input (comma-separated).
97
+ - **Mixed credential templates**: a header containing both a static secret and dynamic placeholders cannot be migrated as one nested credential. It is reported as pending and excluded from persisted/client config. Store the static part separately and use credential references throughout. Pure forms such as `Bearer {{VAR}}` and `{{USER}}:{{PASS}}` remain supported.
98
+
99
+
100
+ ## Formulas and subscription balances
101
+
102
+ Since 1.9.47, **Cost → Quotas → Custom balance → Extract rules (JSON)** supports `expression` formulas and nested operations. Use `remaining` for available balance, `spend` for usage and `maxBudget` for the total allowance; do not map a usage field directly to `remaining`.
103
+
104
+ For example, if the endpoint returns `{"data":{"amount_total":15000000,"amount_used":2500000}}` and uses 500000 quota units per USD, enter:
105
+
106
+ ```json
107
+ {
108
+ "remaining": {"expression": "(data.amount_total - data.amount_used) / 500000"},
109
+ "spend": {"expression": "data.amount_used / 500000"},
110
+ "maxBudget": {"expression": "data.amount_total / 500000"}
111
+ }
112
+ ```
113
+
114
+ This example shows $25 remaining, $5 used and $30 total. Adjust field paths and the conversion factor to the endpoint's actual response. NewAPI subscription objects use `amount_total` and `amount_used`, but their response wrapper differs from the account-balance endpoint; adapt the paths accordingly. See the [upstream field definitions](https://github.com/QuantumNous/new-api/blob/main/web/src/features/subscriptions/types.ts).
115
+
116
+ If `data.subscriptions` is an array and each item contains `subscription.amount_total` and `subscription.amount_used`, calculate each item's value and sum the results:
117
+
118
+ ```json
119
+ {
120
+ "remaining": {
121
+ "op": "sum",
122
+ "path": "data.subscriptions",
123
+ "value": {"expression": "(subscription.amount_total - subscription.amount_used) / 500000"}
124
+ },
125
+ "spend": {
126
+ "op": "sum",
127
+ "path": "data.subscriptions",
128
+ "value": {"expression": "subscription.amount_used / 500000"}
129
+ },
130
+ "maxBudget": {
131
+ "op": "sum",
132
+ "path": "data.subscriptions",
133
+ "value": {"expression": "subscription.amount_total / 500000"}
134
+ }
135
+ }
136
+ ```
137
+
138
+ The array must contain the active subscriptions you intend to display. Existing paths, constants, `add`/`subtract` rules with `paths`, and `divide` rules with `path`/`by` remain supported. Use `args` for nested operations:
139
+
140
+ ```json
141
+ {"remaining":{"op":"divide","args":[{"op":"subtract","args":["data.amount_total","data.amount_used"]},500000]}}
142
+ ```
143
+
144
+ Expressions support `+ - * / % **`, parentheses, array indices, and `min`, `max`, `abs`, `round`, `floor` and `ceil`. They do not run JavaScript. Missing fields, non-numeric values, division by zero and non-finite results report a parsing failure instead of showing a zero balance.
145
+
146
+ A `sum` rule also accepts an optional `where` object: only array items whose listed fields strictly equal the given values are summed, for example `{"op":"sum","path":"data","where":{"provider":"workbuddy"},"value":{"expression":"windows[2].limit"}}`. `where` allows at most 16 fields and rejects `__proto__` / `prototype` / `constructor` keys.
147
+
148
+ ## Dashboard links and local services
149
+
150
+ Each custom balance entry has an optional **Dashboard link** (`dashboardUrl`) under **Cost → Quotas**. Use a complete HTTP(S) account or billing URL without embedded credentials. The sidebar row and progress card show an arrow next to that entry's name; it opens a new tab without refreshing the balance. Leave it blank to omit the link. Query URLs, headers and credentials are never used to construct navigation links.
151
+
152
+ Root-relative URLs such as `/plugins/dsh-workbuddy-connect/status` follow the running DSH web server's actual port. Independent WorkBuddy2API deployments use an absolute URL. Non-loopback HTTP requires both `allowInsecureHttp: true` and an exact `host:port` in `allowedHosts`; this explicitly permits plaintext transport. Redirects remain blocked.
153
+
154
+ The **+ WorkBuddy2API credits** preset reads `GET /api/credits/expiry?package_limit=1` with an admin `X-Admin-Token` stored as `WORKBUDDY2API_ADMIN_TOKEN` in DSH credentials. Set the real server address and matching allowlist, update expired admin tokens, then enable the card. The displayed `summary.available_remaining` is the active account pool's available credits, not currency, a single model API key's allowance, or the incomplete expiry snapshot total. No model request or upstream credit-refresh task is triggered. Authentication was tested with synthetic responses, not a live account.
155
+
156
+ ## Magpie WorkBuddy credits example
157
+
158
+ Under **Cost → Quotas → Custom provider balance**, choose **Add entry** and fill in:
159
+
160
+ ```json
161
+ {
162
+ "label": "Magpie WorkBuddy credits",
163
+ "unit": "CREDITS",
164
+ "refreshMinutes": 5,
165
+ "request": {
166
+ "url": "http://127.0.0.1:3425/v1/magpie/quotas",
167
+ "method": "GET",
168
+ "headers": {}
169
+ },
170
+ "extract": {
171
+ "remaining": { "op": "sum", "path": "data", "where": { "provider": "workbuddy" }, "value": { "expression": "windows[2].limit * windows[2].remaining / 100" } },
172
+ "maxBudget": { "op": "sum", "path": "data", "where": { "provider": "workbuddy" }, "value": { "expression": "windows[2].limit" } },
173
+ "spend": { "op": "sum", "path": "data", "where": { "provider": "workbuddy" }, "value": { "expression": "windows[2].limit * windows[2].used / 100" } }
174
+ },
175
+ "allowedHosts": ["127.0.0.1:3425"],
176
+ "allowInsecureHttp": false
177
+ }
178
+ ```
179
+
180
+ Magpie's `/v1/magpie/quotas` returns multiple providers and accounts. The `where` clause on a `sum` rule matches fields exactly, so only `provider=workbuddy` accounts are summed; Trae, MiniMax and other providers are excluded. WorkBuddy's `used` / `remaining` values are percentages (0–100) and `limit` is the credit capacity, so the example converts them to absolute credits with `limit * percentage / 100`. It uses `windows[2]` (`Total credits`, base plus extra credits) as the total. Change all three `windows[2]` references to `windows[0]` to show only the base monthly credits, or `windows[1]` for extra credits only.
181
+
182
+ No API key is needed when Magpie runs locally on the default `127.0.0.1:3425`. If Magpie runs on another host or enables authentication, edit the URL, add `Authorization: Bearer {{MAGPIE_API_KEY}}` to the request headers, add the exact `host:port` to the allowlist and save the key in the credential field. Prefer HTTPS; enable **Allow non-loopback HTTP** only for a non-loopback HTTP URL. The query only reads Magpie's existing statistics and makes no model requests.
183
+
184
+ This preset does not depend on the official WorkBuddy desktop login or a WorkBuddy connector. Users who already run `dsh-magpie-quota` can keep using it; the two displays are independent.