dsh-provider-usage 0.3.10 → 0.3.12

package/README.md

@@ -15,15 +15,15 @@
 ## Features
 
 - **Auto-detection** — enumerates the provider routes registered in the current profile (`ctx.llm`); zero configuration for well-known routes.
-- **Per-kind wire adapters** — routes with no public balance/quota API (Google, Mistral, Groq, Bedrock, Azure, Qwen Token Plan, …) are listed as `unsupported` instead of being silently dropped:
+- **Per-kind wire adapters** — routes with no public balance/usage API (Google, Mistral, Groq, Bedrock, Azure, Qwen Token Plan, …) are listed as `unsupported` instead of being silently dropped:
 
   | kind | routes | query | shows |
   |---|---|---|---|
   | `deepseek` | `deepseek-official`, `deepseek` | `GET {baseURL}/user/balance` | total / granted / topped-up balance |
   | `moonshot` | `moonshotai-cn`, `moonshotai` | `GET {baseURL}/users/me/balance` | available / voucher / cash balance |
-  | `kimi-coding` | `kimi-coding` | `GET {baseURL}/v1/usages` | weekly quota + rate-limit windows, reset countdown |
+  | `kimi-coding` | `kimi-coding` | `GET {baseURL}/v1/usages` | weekly usage + rate-limit windows, reset countdown |
   | `openrouter` | `openrouter` | `GET {origin}/api/v1/credits` | credits used / total |
-  | `github-copilot` | `github-copilot` | `GET api.github.com/copilot_internal/user` | plan quota snapshots (paid) or monthly quotas (free) |
+  | `github-copilot` | `github-copilot` | `GET api.github.com/copilot_internal/user` | plan usage snapshots (paid) or monthly usage (free) |
   | `openai-codex` | `openai-codex` | `GET {baseURL}/wham/usage` | ChatGPT subscription 5h / weekly windows + credits + spend control (**OAuth login**, not an API key — see [OpenAI Codex via OAuth](#openai-codex-via-oauth)) |
   | `openai` | `openai` | `GET {origin}/v1/organization/costs` | current-month spend (**admin key required**; a regular key fails with 403) |
   | `anthropic` | `anthropic` | `GET {baseURL}/v1/organizations/cost_report` | current-month spend (**admin key required**, `x-api-key` auth) |
@@ -33,7 +33,7 @@
   | `vercel-ai-gateway` | `vercel-ai-gateway` | `GET {baseURL}/v1/credits` | team credit balance |
   | `xai` | `xai` | `GET {baseURL}/billing/credits` | prepaid balance (USD) |
 - **Credentials stay safe** — API keys are resolved per request through the harness credentials service (environment variables / `~/.dsh/.credentials.yaml`); never cached, never written to disk. For OAuth providers (OpenAI Codex) the plugin reads the grant record the sign-in flow stored, and refreshes it transparently when it is about to expire.
-- **Floating ball widget** — a draggable floating ball opens the usage panel. Drop it anywhere in the viewport (position persisted); it docks by default at the bottom-left of the chat area with equal margins, and the panel-header home button sends it back. The panel scrolls when the provider list grows past its height, and its top edge is draggable to resize it taller or shorter (height persisted). The halo around the ball encodes the health of the provider **in use** — the focused session's own selection (its composer's model seat), tracked live on the client, so switching sessions re-highlights that session's provider immediately without re-selecting a model: green all good, amber some quota below 30% left or a balance below the yellow threshold, red on query failure / missing key / usage ≥90% / balance below the red threshold. Idle providers with low quota do not color the ball — switch to another provider with enough quota and the ball turns green again; the panel marks the in-use provider and still lists every provider's numbers.
+- **Floating ball widget** — a draggable floating ball opens the usage panel. Drop it anywhere in the viewport (position persisted); it docks by default at the bottom-left of the chat area with equal margins, and the panel-header home button sends it back. The panel scrolls when the provider list grows past its height, and its top edge is draggable to resize it taller or shorter (height persisted). The halo around the ball encodes the health of the provider **in use** — the focused session's own selection (its composer's model seat), tracked live on the client, so switching sessions re-highlights that session's provider immediately without re-selecting a model: green all good, amber when a usage window has under 30% left or a balance below the yellow threshold, red on query failure / missing key / usage ≥90% / balance below the red threshold. Idle providers running low do not color the ball — switch to another provider with enough headroom and the ball turns green again; the panel marks the in-use provider and still lists every provider's numbers.
 - **Version badge** — the panel header shows the running plugin version next to the title, so it is obvious which release is loaded.
 - **Bilingual panel** — built-in Chinese/English UI; follows the harness language by default, with a one-click toggle in the panel header (persisted in localStorage).
 - **Configurable refresh** — adjustable in the panel (15s–30min, persisted in localStorage); the default comes from the plugin config.
@@ -50,7 +50,7 @@ The floating ball (bottom-left, with the green healthy halo) and the open usage
 
 ## OpenAI Codex via OAuth
 
-OpenAI Codex is a **ChatGPT-subscription** provider: it authenticates with an OAuth access token, not an API key, so there is nothing to paste into a key field. dsh itself has no OAuth *button* for this route — but this plugin can still query its quota, because it reads the OAuth grant out of the harness credential store. Set the provider up once, and the usage panel shows your real 5-hour / weekly Codex windows.
+OpenAI Codex is a **ChatGPT-subscription** provider: it authenticates with an OAuth access token, not an API key, so there is nothing to paste into a key field. dsh itself has no OAuth *button* for this route — but this plugin can still query its usage, because it reads the OAuth grant out of the harness credential store. Set the provider up once, and the usage panel shows your real 5-hour / weekly Codex windows.
 
 ### 1. Make sure the route exists
 
@@ -80,7 +80,7 @@ records:
 
 > The grant must land in the harness credential store (the record above). Codex clients that keep their own credential file (e.g. `dsh-codex`'s `$DSH_HOME/.openai-codex-auth.json`, or the Codex CLI's `~/.codex/auth.json`) do not write this record, so this plugin cannot see them.
 
-### 3. Watch the quota
+### 3. Watch the usage
 
 That's it. The route is auto-detected (`ctx.llm` lists `openai-codex`), and the plugin:
 
@@ -90,6 +90,37 @@ That's it. The route is auto-detected (`ctx.llm` lists `openai-codex`), and the
 
 The panel then shows your subscription's **5h limit**, **weekly** windows (used %, reset countdown) plus **credits** and **spend control** balances when the plan reports them. If the grant is missing the card reads "OAuth authorization missing (llm-pi-ai/openai-codex)" — sign in again with step 2.
 
+### 4. Troubleshooting: intermittent "Our servers are currently overloaded"
+
+The Codex backend occasionally answers with `Codex error: Our servers are currently overloaded. Please try again later.`, and the harness fails the round with `PI_AI_ERROR`. This is **transient overload on OpenAI's side** (account, quota, and network are usually fine — `GET /wham/usage` confirms window headroom), yet the default configuration never retries, for two reasons:
+
+1. pi-ai's Codex client recognizes `overloaded` as retryable, but its default retry count is 0 (`dsh-llm-pi-ai` explicitly passes `maxRetries: 0`);
+2. once the error bubbles up, its text contains no `5xx` / `rate limit` / `timeout` keyword, so it is classified as the catch-all `PI_AI_ERROR` — which is **not** among `dsh-llm-retry`'s default retryable codes (`EMPTY_RESPONSE` / `RATE_LIMIT` / `SERVER` / `TIMEOUT` / `TRANSPORT`), so the round fails immediately.
+
+Add a `retryPolicy` for this provider in `~/.dsh/settings.yaml` that includes `PI_AI_ERROR` in the retryable codes (takes effect on a new session):
+
+```yaml
+llm-pi-ai:
+  providers:
+    openai-codex:
+      retryPolicy:
+        mode: normal
+        maxRetries: 10
+        retryableCodes:
+          - EMPTY_RESPONSE
+          - RATE_LIMIT
+          - SERVER
+          - TIMEOUT
+          - TRANSPORT
+          - PI_AI_ERROR
+        backoff:
+          initialDelayMs: 2000   # first retry delay, doubled each attempt
+          maxDelayMs: 60000      # per-attempt delay cap
+          jitterRatio: 0.2       # ±20% jitter
+```
+
+Do not confuse this with the other, **deterministic** failure: some models are unavailable to ChatGPT-subscription accounts, and the backend answers `400 The '<model>' model is not supported when using Codex with a ChatGPT account.` (observed with e.g. `gpt-5.3-codex-spark`, `gpt-5-codex`). That is a permanent error — retrying won't help; switch to a model your account supports (e.g. the `gpt-5.4` / `gpt-5.5` / `gpt-5.6` families).
+
 ## Install
 
 > [!NOTE]
@@ -112,7 +143,7 @@ pnpm pack   # produces dsh-provider-usage-<version>.tgz
 dsh plugin --profile web add ./dsh-provider-usage-<version>.tgz
 ```
 
-Install the **tarball**, not the repo directory: `dsh plugin add .` links the repo, whose own `node_modules` then shadows the harness's shared `@deepseek-ai/cordis` instance and the host half never registers (RPC 404). The link form is still handy for client-only UI iteration — the browser bundle is self-contained, so a rebuild + page refresh picks it up — but switch to the tarball (or the npm release) whenever you need the host half. If pnpm fails with `EPERM ... symlink` while replacing a linked install, delete the stale `node_modules/dsh-provider-usage` junction in the profile directory and retry.
+Install the **tarball**, not the repo directory: `dsh plugin --profile web add .` links the repo, whose own `node_modules` then shadows the harness's shared `@deepseek-ai/cordis` instance and the host half never registers (RPC 404). The link form is still handy for client-only UI iteration — the browser bundle is self-contained, so a rebuild + page refresh picks it up — but switch to the tarball (or the npm release) whenever you need the host half. If pnpm fails with `EPERM ... symlink` while replacing a linked install, delete the stale `node_modules/dsh-provider-usage` junction in the profile directory and retry.
 
 Restart `dsh web` after changing the plugin set (a plugin add/remove requires a restart; afterwards, code changes only need a rebuild + re-add + page refresh).
 
@@ -122,7 +153,7 @@ Restart `dsh web` after changing the plugin set (a plugin add/remove requires a
 dsh plugin --profile web add dsh-provider-usage@latest
 ```
 
-Then restart `dsh web` and refresh the page. If the release you want was published very recently, your profile's supply-chain cooldown (`minimumReleaseAge`) may silently keep the older version — pin the exact version instead (`dsh plugin --profile web add dsh-provider-usage@0.3.1`) and dsh will exempt it automatically. The version badge in the panel header confirms which release is actually loaded.
+Then restart `dsh web` and refresh the page. If the release you want was published very recently, your profile's supply-chain cooldown (`minimumReleaseAge`) may silently keep the older version — pin the exact version instead (`dsh plugin --profile web add dsh-provider-usage@0.3.10`) and dsh will exempt it automatically. The version badge in the panel header confirms which release is actually loaded.
 
 ## Configuration
 
@@ -136,6 +167,9 @@ Defaults work out of the box: the plugin auto-detects every provider route of th
     balanceRedThreshold: 10     # balance below this turns red (per the balance's own currency)
     balanceYellowThreshold: 30  # balance below this turns yellow (per the balance's own currency)
     autoDetect: true            # enumerate provider routes from the llm registry
+    queryTimeoutMs: 20000       # per-attempt query timeout; each retry gets a fresh timeout
+    queryRetries: 2             # retries for transient errors (timeout/network/HTTP 408/425/429/5xx)
+    queryRetryDelayMs: 2000     # base retry delay, doubled per attempt, capped at 10s
     providers: []               # manual specs; an id matching a detected route overrides it
 ```
 
@@ -145,6 +179,9 @@ Defaults work out of the box: the plugin auto-detects every provider route of th
 | `balanceRedThreshold` | number | `10` | Balance below this amount turns red, compared in the balance's own currency |
 | `balanceYellowThreshold` | number | `30` | Balance below this amount turns yellow, compared in the balance's own currency |
 | `autoDetect` | boolean | `true` | Enumerate live provider routes from the llm registry |
+| `queryTimeoutMs` | number | `20000` | Per-attempt query timeout (1000–120000); each retry gets a fresh timeout |
+| `queryRetries` | number | `2` | Retries for transient errors — timeout / network / HTTP 408, 425, 429, 5xx (0–10); permanent 4xx errors fail immediately |
+| `queryRetryDelayMs` | number | `2000` | Base delay between retries (100–60000), doubled per attempt, capped at 10s |
 | `providers` | array | `[]` | Manual provider specs: `{id, kind, baseURL, apiKeyEnv, displayName?, enabled?}`; `kind` is one of the adapter table above |
 
 The same fields can be hot-updated under the `provider-usage:` namespace in `~/.dsh/settings.yaml`.
@@ -163,7 +200,7 @@ config:
 
 ## How it works
 
-- **Host half** (`src/index.ts`): `UsageService extends TypertRemoteService` exposes `usage/list` via `@Remote('list')` (SRC mode, no codegen). Config is declared with schemastery, and `installSettingsSection` enables hot updates from settings.
+- **Host half** (`src/index.ts`): `UsageService extends TypertRemoteService` exposes `usage/list` via the `Remote('list')` marker, applied without decorator syntax (SRC mode, no codegen). Config is declared with schemastery, and the settings provider's `installSection` enables hot updates from the settings document.
 - **Client half** (`src/client/`): a `window.__ModuleLoader__.load({id, factory})` bundle (built by tsdown) mounts through the `sidebar.footer.action` slot (used purely as a mount point — the trigger itself is a floating ball portaled to `document.body`) and polls `usage/list` through `ctx.connection.rpc.call('/api', 'usage/list', {args:{}})` on its own interval. The service stays stateless — every poll fetches live values.
 
 ## License

package/README_ZH.md

@@ -10,20 +10,20 @@
 
 # dsh-provider-usage
 
-[DeepSeek Harness](https://github.com/deepseek-ai/deepseek-harness) 插件：在 Web GUI 上悬浮一个可任意拖动的用量球，实时查看所有已配置 LLM provider 的账户余额与配额用量——不用再逐个登录 provider 控制台确认。
+[DeepSeek Harness](https://github.com/deepseek-ai/deepseek-harness) 插件：在 Web GUI 上悬浮一个可任意拖动的用量球，实时查看所有已配置 LLM provider 的账户余额与用量——不用再逐个登录 provider 控制台确认。
 
 ## 功能
 
 - **自动探测** —— 自动枚举当前 profile 中已注册的 provider 路由（`ctx.llm`），常见路由零配置。
-- **按 provider 类型查询额度** —— 没有公开余额/配额接口的路由（Google、Mistral、Groq、Bedrock、Azure、Qwen Token Plan 等）会在面板中标注为「不支持」，而不是被静默忽略：
+- **按 provider 类型查询额度** —— 没有公开余额/用量接口的路由（Google、Mistral、Groq、Bedrock、Azure、Qwen Token Plan 等）会在面板中标注为「不支持」，而不是被静默忽略：
 
   | kind | 路由 | 查询接口 | 展示内容 |
   |---|---|---|---|
   | `deepseek` | `deepseek-official`、`deepseek` | `GET {baseURL}/user/balance` | 余额（含赠送/充值明细） |
   | `moonshot` | `moonshotai-cn`、`moonshotai` | `GET {baseURL}/users/me/balance` | 可用/代金券/现金余额 |
-  | `kimi-coding` | `kimi-coding` | `GET {baseURL}/v1/usages` | 每周配额及各限速窗口，含重置倒计时 |
+  | `kimi-coding` | `kimi-coding` | `GET {baseURL}/v1/usages` | 每周用量及各限速窗口，含重置倒计时 |
   | `openrouter` | `openrouter` | `GET {origin}/api/v1/credits` | credit 已用/总额 |
-  | `github-copilot` | `github-copilot` | `GET api.github.com/copilot_internal/user` | 付费档配额快照 / 免费档月度配额 |
+  | `github-copilot` | `github-copilot` | `GET api.github.com/copilot_internal/user` | 付费档用量快照 / 免费档月度用量 |
   | `openai-codex` | `openai-codex` | `GET {baseURL}/wham/usage` | ChatGPT 订阅 5h/周窗口 + credits + spend control（**OAuth 登录**，非 API key，见 [通过 OAuth 添加 OpenAI Codex](#通过-oauth-添加-openai-codex)） |
   | `openai` | `openai` | `GET {origin}/v1/organization/costs` | 当月花费（**需 Admin key**，普通 key 会 403） |
   | `anthropic` | `anthropic` | `GET {baseURL}/v1/organizations/cost_report` | 当月花费（**需 Admin key**，`x-api-key` 头） |
@@ -33,7 +33,7 @@
   | `vercel-ai-gateway` | `vercel-ai-gateway` | `GET {baseURL}/v1/credits` | 团队 credit 余额 |
   | `xai` | `xai` | `GET {baseURL}/billing/credits` | 预付余额（USD） |
 - **密钥安全** —— 通过 harness 凭据服务按次解析（环境变量 / `~/.dsh/.credentials.yaml`），不缓存、不落地。对 OAuth 类 Provider（OpenAI Codex）则直接读取登录流程存入的授权记录，并在令牌临近过期时自动刷新。
-- **悬浮球入口** —— 可任意拖动的悬浮球点击弹出用量面板，位置持久化；默认停靠在主对话区域左下角（左边距 = 底边距），面板头部的归位按钮一键回到默认位置；Provider 列表超过面板高度时自动滚动，面板**顶部边缘可拖拽**调整面板高度（变长/变短，localStorage 持久化）；球体光晕表达**当前正在使用**的 Provider——即**当前聚焦 session 自己的模型选择**（composer 模型座同源，客户端实时跟踪），因此切换 session 后无需重新选择模型，面板会立即把"使用中"标记切到该 session 的 Provider：绿色正常、黄色配额剩余不足 30% 或余额低于黄阈值、红色查询失败/缺密钥/用量 ≥90% 或余额低于红阈值。闲置的 Provider 余量不足不再影响悬浮球颜色——切换到余量充足的另一个 Provider 后球体会恢复绿色；面板会标注"使用中"的 Provider，并照常列出所有 Provider 的用量明细。
+- **悬浮球入口** —— 可任意拖动的悬浮球点击弹出用量面板，位置持久化；默认停靠在主对话区域左下角（左边距 = 底边距），面板头部的归位按钮一键回到默认位置；Provider 列表超过面板高度时自动滚动，面板**顶部边缘可拖拽**调整面板高度（变长/变短，localStorage 持久化）；球体光晕表达**当前正在使用**的 Provider——即**当前聚焦 session 自己的模型选择**（composer 模型座同源，客户端实时跟踪），因此切换 session 后无需重新选择模型，面板会立即把"使用中"标记切到该 session 的 Provider：绿色正常、黄色用量窗口剩余不足 30% 或余额低于黄阈值、红色查询失败/缺密钥/用量 ≥90% 或余额低于红阈值。闲置的 Provider 余量不足不再影响悬浮球颜色——切换到余量充足的另一个 Provider 后球体会恢复绿色；面板会标注"使用中"的 Provider，并照常列出所有 Provider 的用量明细。
 - **版本徽章** —— 面板标题旁显示当前运行的插件版本，一眼确认加载的是哪个发布版。
 - **中英双语** —— 面板内置中英文界面，默认跟随 harness 系统语言，标题栏按钮一键切换（localStorage 持久化）。
 - **刷新周期可调** —— 面板内调整（15s–30min，localStorage 持久化），默认值由插件配置提供。
@@ -90,6 +90,37 @@ records:
 
 面板随即展示订阅的 **5h 上限**、**每周**窗口（已用百分比 + 重置倒计时），以及计划上报的 **credits** 与 **spend control** 余额。若授权记录缺失，卡片会显示「未完成 OAuth 授权（llm-pi-ai/openai-codex）」，按第 2 步重新登录即可。
 
+### 4. 故障排除：间歇性 "Our servers are currently overloaded"
+
+Codex 后端偶尔会返回 `Codex error: Our servers are currently overloaded. Please try again later.`，harness 随即以 `PI_AI_ERROR` 判本轮失败。这是 **OpenAI 端的间歇性过载**（账号、配额、网络通常都正常——可用 `GET /wham/usage` 确认窗口余量），但默认配置下不会自动重试，原因有两层：
+
+1. pi-ai 的 Codex 客户端内部认得 `overloaded` 是可重试错误，但默认重试次数为 0（`dsh-llm-pi-ai` 显式传 `maxRetries: 0`）；
+2. 错误冒泡后，其文本不含 `5xx` / `rate limit` / `timeout` 等关键词，被归类为兜底的 `PI_AI_ERROR`——而它**不在** `dsh-llm-retry` 的默认可重试码（`EMPTY_RESPONSE` / `RATE_LIMIT` / `SERVER` / `TIMEOUT` / `TRANSPORT`）里，于是整轮直接失败。
+
+在 `~/.dsh/settings.yaml` 中给该 provider 加一段 `retryPolicy`，把 `PI_AI_ERROR` 纳入可重试码即可（重开 session 后生效）：
+
+```yaml
+llm-pi-ai:
+  providers:
+    openai-codex:
+      retryPolicy:
+        mode: normal
+        maxRetries: 10
+        retryableCodes:
+          - EMPTY_RESPONSE
+          - RATE_LIMIT
+          - SERVER
+          - TIMEOUT
+          - TRANSPORT
+          - PI_AI_ERROR
+        backoff:
+          initialDelayMs: 2000   # 首次重试延迟，指数翻倍
+          maxDelayMs: 60000      # 单次延迟上限
+          jitterRatio: 0.2       # ±20% 抖动
+```
+
+注意区分另一类**必然失败**：部分模型对 ChatGPT 订阅账号不可用，后端直接返回 `400 The '<model>' model is not supported when using Codex with a ChatGPT account.`（实测如 `gpt-5.3-codex-spark`、`gpt-5-codex`）。这类是永久错误，重试无效——请换用账号支持的模型（如 `gpt-5.4` / `gpt-5.5` / `gpt-5.6` 系列）。
+
 ## 安装
 
 > [!NOTE]
@@ -112,7 +143,7 @@ pnpm pack   # 产出 dsh-provider-usage-<version>.tgz
 dsh plugin --profile web add ./dsh-provider-usage-<version>.tgz
 ```
 
-注意要安装 **tarball** 而不是仓库目录：`dsh plugin add .` 会链接整个仓库，仓库自带 `node_modules` 里的 `@deepseek-ai/cordis` 会遮蔽 harness 的共享实例，导致 host 半注册不上（RPC 404）。link 方式仍适合纯 UI 迭代（浏览器 bundle 自包含，重新 build + 刷新页面即生效），但需要 host 半时请切换到 tarball 或 npm 正式版。若替换 link 安装时 pnpm 报 `EPERM ... symlink`，手动删除 profile 目录下残留的 `node_modules/dsh-provider-usage` 联结后重试即可。
+注意要安装 **tarball** 而不是仓库目录：`dsh plugin --profile web add .` 会链接整个仓库，仓库自带 `node_modules` 里的 `@deepseek-ai/cordis` 会遮蔽 harness 的共享实例，导致 host 半注册不上（RPC 404）。link 方式仍适合纯 UI 迭代（浏览器 bundle 自包含，重新 build + 刷新页面即生效），但需要 host 半时请切换到 tarball 或 npm 正式版。若替换 link 安装时 pnpm 报 `EPERM ... symlink`，手动删除 profile 目录下残留的 `node_modules/dsh-provider-usage` 联结后重试即可。
 
 插件集合变化后需重启 `dsh web`；之后仅改动代码时重新 build + 重新 add + 刷新页面即可。
 
@@ -122,7 +153,7 @@ dsh plugin --profile web add ./dsh-provider-usage-<version>.tgz
 dsh plugin --profile web add dsh-provider-usage@latest
 ```
 
-然后重启 `dsh web` 并刷新页面。如果目标版本刚发布不久，profile 的供应链冷静期（`minimumReleaseAge`）可能会静默停留在旧版——这时指定精确版本号（如 `dsh plugin --profile web add dsh-provider-usage@0.3.1`），dsh 会自动豁免该版本。面板标题旁的版本徽章可以确认实际加载的版本。
+然后重启 `dsh web` 并刷新页面。如果目标版本刚发布不久，profile 的供应链冷静期（`minimumReleaseAge`）可能会静默停留在旧版——这时指定精确版本号（如 `dsh plugin --profile web add dsh-provider-usage@0.3.10`），dsh 会自动豁免该版本。面板标题旁的版本徽章可以确认实际加载的版本。
 
 ## 配置说明
 
@@ -136,6 +167,9 @@ dsh plugin --profile web add dsh-provider-usage@latest
     balanceRedThreshold: 10     # 余额低于该值变红（按余额自身币种比较）
     balanceYellowThreshold: 30  # 余额低于该值变黄（按余额自身币种比较）
     autoDetect: true            # 自动枚举 llm 注册表中的 provider
+    queryTimeoutMs: 20000       # 单次查询超时（毫秒），每次重试独立计时
+    queryRetries: 2             # 瞬时错误（超时/网络/HTTP 408/425/429/5xx）重试次数
+    queryRetryDelayMs: 2000     # 重试基础延迟（毫秒），逐次翻倍，封顶 10 秒
     providers: []               # 手动补充/覆盖 provider（id 相同则覆盖自动探测结果）
 ```
 
@@ -145,6 +179,9 @@ dsh plugin --profile web add dsh-provider-usage@latest
 | `balanceRedThreshold` | number | `10` | 余额低于该值变红，按余额自身币种比较 |
 | `balanceYellowThreshold` | number | `30` | 余额低于该值变黄，按余额自身币种比较 |
 | `autoDetect` | boolean | `true` | 从 llm 注册表自动枚举 provider |
+| `queryTimeoutMs` | number | `20000` | 单次查询超时（毫秒），1000–120000，每次重试独立计时 |
+| `queryRetries` | number | `2` | 瞬时错误（超时/网络/HTTP 408/425/429/5xx）的重试次数，0–10；4xx 永久错误不重试 |
+| `queryRetryDelayMs` | number | `2000` | 重试基础延迟（毫秒），100–60000，指数翻倍，封顶 10 秒 |
 | `providers` | array | `[]` | 手动 provider 规格：`{id, kind, baseURL, apiKeyEnv, displayName?, enabled?}`，`kind` 取上表中的任一适配器 |
 
 也可以在 `~/.dsh/settings.yaml` 中通过 `provider-usage:` 命名空间热更新同样字段。
@@ -163,7 +200,7 @@ config:
 
 ## 架构
 
-- **Host 半**（`src/index.ts`）：`UsageService extends TypertRemoteService`，`@Remote('list')` 暴露 `usage/list`（SRC 模式，无需代码生成）；`Config` 用 schemastery 声明，`installSettingsSection` 支持 settings 热更新。
+- **Host 半**（`src/index.ts`）：`UsageService extends TypertRemoteService`，通过 `Remote('list')` 标记（以非装饰器方式应用）暴露 `usage/list`（SRC 模式，无需代码生成）；`Config` 用 schemastery 声明，通过 settings provider 的 `installSection` 支持 settings 热更新。
 - **Client 半**（`src/client/`）：`window.__ModuleLoader__.load({id, factory})` 格式 bundle（tsdown 构建），通过 `sidebar.footer.action` slot 挂载（仅作为挂载点——触发器本体是 portal 到 `document.body` 的悬浮球），通过 `ctx.connection.rpc.call('/api', 'usage/list', {args:{}})` 轮询。服务本身无状态——每次轮询都取实时值。
 
 ## 许可证

package/docs/provider-quota-endpoints.json

@@ -0,0 +1,184 @@
+{
+  "$comment": "LLM provider 余额/配额查询接口调研结论（机器可读版）。详见 provider-quota-endpoints.md。均经官方文档/开源实现验证，未臆造端点。",
+  "providers": [
+    {
+      "id": "openai",
+      "support": "partial",
+      "credentialType": "admin_api_key",
+      "credentialHint": "OpenAI Admin key (sk-admin-...)，platform.openai.com → Organization → Admin keys；普通 sk- key 与 project service-account key 均不可用",
+      "endpoints": [
+        {
+          "kind": "cost",
+          "method": "GET",
+          "url": "https://api.openai.com/v1/organization/costs",
+          "headers": { "Authorization": "Bearer {ADMIN_KEY}" },
+          "query": {
+            "start_time": "unix 秒，必填",
+            "end_time": "unix 秒",
+            "bucket_width": "1d|1h|1m",
+            "group_by": "project_id|line_item",
+            "project_ids": "proj_... 可重复",
+            "limit": "int", "page": "cursor"
+          },
+          "responseShape": "{ object:'page', data:[{ start_time, end_time, results:[{ amount:{value,currency}, line_item, project_id }] }], has_more, next_page }"
+        },
+        {
+          "kind": "usage",
+          "method": "GET",
+          "url": "https://api.openai.com/v1/organization/usage/completions",
+          "headers": { "Authorization": "Bearer {ADMIN_KEY}" },
+          "query": { "start_time": "unix 秒，必填", "bucket_width": "1d|1h|1m", "group_by": "model|project_id|api_key_id|..." },
+          "responseShape": "{ data:[{ results:[{ model, input_tokens, output_tokens, input_cached_tokens, num_model_requests }] }], has_more, next_page }",
+          "siblings": ["embeddings", "images", "moderations", "audio_speeches", "audio_transcriptions", "vector_stores", "code_interpreter_sessions"]
+        },
+        {
+          "kind": "balance_legacy_best_effort",
+          "method": "GET",
+          "url": "https://api.openai.com/v1/dashboard/billing/credit_grants",
+          "headers": { "Authorization": "Bearer {LEGACY_USER_KEY}" },
+          "responseShape": "{ object:'credit_summary', total_granted, total_used, total_available, expires_at }",
+          "warnings": ["不在现行公开 API 文档", "多数普通 key 已失效", "仅作静默兜底，失败视为不可用"]
+        }
+      ],
+      "consoleUrl": "https://platform.openai.com/usage",
+      "sources": [
+        "https://developers.openai.com/api/reference/resources/admin/subresources/organization/subresources/usage/methods/costs",
+        "https://github.com/steipete/CodexBar/blob/main/docs/openai.md"
+      ]
+    },
+    {
+      "id": "openai-codex",
+      "support": "yes_oauth_only",
+      "credentialType": "oauth_access_token",
+      "credentialHint": "~/.codex/auth.json 中的 ChatGPT/Codex OAuth access token；stale 时引导用户运行 codex CLI，不要自行回写 auth.json",
+      "endpoints": [
+        {
+          "kind": "rate_limit_windows",
+          "method": "GET",
+          "url": "https://chatgpt.com/backend-api/wham/usage",
+          "headers": { "Authorization": "Bearer {OAUTH_TOKEN}" },
+          "responseShape": "{ plan_type, rate_limit:{ allowed, limit_reached, primary_window:{used_percent,limit_window_seconds,reset_after_seconds,reset_at}, secondary_window:{...} }, additional_rate_limits:[], credits:{has_credits,unlimited,balance} }",
+          "mapping": { "primary_window": "5 小时会话窗口", "secondary_window": "周窗口" }
+        },
+        {
+          "kind": "reset_credits",
+          "method": "GET",
+          "url": "https://chatgpt.com/backend-api/wham/rate-limit-reset-credits",
+          "headers": { "Authorization": "Bearer {OAUTH_TOKEN}" }
+        }
+      ],
+      "alternatives": ["本地 codex app-server JSON-RPC: account/read, account/rateLimits/read"],
+      "warnings": ["未公开内部接口，可能随时变更"],
+      "consoleUrl": "https://chatgpt.com/codex/settings/usage",
+      "sources": ["https://github.com/steipete/CodexBar/blob/main/docs/codex.md"]
+    },
+    {
+      "id": "anthropic",
+      "support": "partial",
+      "credentialType": "admin_api_key",
+      "credentialHint": "Anthropic Admin key (sk-ant-admin-...)，Console → Settings → Admin keys；普通 sk-ant-api key 不可用；认证头是 x-api-key 而非 Bearer",
+      "endpoints": [
+        {
+          "kind": "usage",
+          "method": "GET",
+          "url": "https://api.anthropic.com/v1/organizations/usage_report/messages",
+          "headers": { "x-api-key": "{ADMIN_KEY}", "anthropic-version": "2023-06-01" },
+          "query": {
+            "starting_at": "RFC3339，必填",
+            "ending_at": "RFC3339",
+            "bucket_width": "1d|1h",
+            "group_by": "workspace_id|api_key_id|model|service_tier|context_window（多值）",
+            "models": "多值", "workspace_ids": "多值", "limit": "≤1000", "page": "cursor"
+          },
+          "responseShape": "{ data:[{ starting_at, ending_at, results:[{ model, workspace_id, api_key_id, service_tier, uncached_input_tokens, output_tokens, cache_read_input_tokens, cache_creation_5m_input_tokens, cache_creation_1h_input_tokens, server_tool_use }] }], has_more, next_page }"
+        },
+        {
+          "kind": "cost",
+          "method": "GET",
+          "url": "https://api.anthropic.com/v1/organizations/cost_report",
+          "headers": { "x-api-key": "{ADMIN_KEY}", "anthropic-version": "2023-06-01" },
+          "query": { "starting_at": "RFC3339，必填", "group_by": "workspace_id|description", "limit": "int", "page": "cursor" },
+          "responseShape": "{ data:[{ starting_at, ending_at, results:[{ amount(字符串美元), currency, cost_type, description, model, workspace_id, service_tier }] }], has_more, next_page }",
+          "warnings": ["bucket_width 仅支持 1d"]
+        },
+        {
+          "kind": "subscription_usage_oauth",
+          "method": "GET",
+          "url": "https://api.anthropic.com/api/oauth/usage",
+          "headers": { "Authorization": "Bearer {CLAUDE_CODE_OAUTH_TOKEN}", "anthropic-beta": "oauth-2025-04-20" },
+          "responseShape": "{ five_hour:{utilization,resets_at}, seven_day:{...}, seven_day_sonnet:{...}, ... }",
+          "warnings": ["仅 Claude Pro/Max 订阅", "需 user:profile scope", "非 API key 方案"]
+        }
+      ],
+      "consoleUrl": "https://console.anthropic.com/",
+      "sources": [
+        "https://platform.claude.com/docs/en/manage-claude/usage-cost-api",
+        "https://platform.claude.com/docs/en/api/admin/usage_report/retrieve_messages",
+        "https://github.com/steipete/CodexBar/blob/main/docs/claude.md"
+      ]
+    },
+    {
+      "id": "gemini",
+      "support": "no",
+      "credentialType": null,
+      "reason": "AI Studio API key 无任何配额/用量/余额查询 HTTP 接口；官方文档无此 API，响应无 rate-limit 头，社区仅能靠 429 反推。",
+      "greyArea": {
+        "comment": "Gemini CLI 私有 OAuth 接口，非 API key 方案，且 Google 已对个人账号关闭",
+        "endpoints": [
+          { "method": "POST", "url": "https://cloudcode-pa.googleapis.com/v1internal:retrieveUserQuota", "body": "{ project }", "responseShape": "buckets[].{modelId, remainingFraction, resetTime}" },
+          { "method": "POST", "url": "https://cloudcode-pa.googleapis.com/v1internal:loadCodeAssist", "body": "{ metadata:{ideType,pluginType} }", "responseShape": "{ paidTier, currentTier }" }
+        ]
+      },
+      "consoleUrl": "https://aistudio.google.com/usage",
+      "sources": [
+        "https://github.com/steipete/CodexBar/blob/main/docs/gemini.md",
+        "https://discuss.ai.google.dev/t/gemini-api-429-resource-exhausted-error-on-tier-1/114413"
+      ]
+    },
+    {
+      "id": "xai",
+      "support": "yes",
+      "credentialType": "management_key",
+      "credentialHint": "xAI Management key（console.x.ai → Management Keys；xai- 前缀但与推理 key 不同），需相应 ACL；team_id 在 console Team settings 复制；baseURL 是 management-api.x.ai 不是 api.x.ai",
+      "endpoints": [
+        {
+          "kind": "balance",
+          "method": "GET",
+          "url": "https://management-api.x.ai/v1/billing/teams/{team_id}/prepaid/balance",
+          "headers": { "Authorization": "Bearer {MANAGEMENT_KEY}" },
+          "responseShape": "{ total:{val}, changes:[{ teamId, changeOrigin:PURCHASE|SPEND|REFUND|MANUAL|AUTO_PURCHASE, topupStatus, amount:{val}, createTime }] }",
+          "warnings": ["金额单位=美元美分", "符号反直觉：SPEND 为正、PURCHASE 为负；可用余额 = -total.val/100 美元"]
+        },
+        { "kind": "spending_limits", "method": "GET", "url": "https://management-api.x.ai/v1/billing/teams/{team_id}/postpaid/spending-limits", "headers": { "Authorization": "Bearer {MANAGEMENT_KEY}" } },
+        { "kind": "invoice_preview", "method": "GET", "url": "https://management-api.x.ai/v1/billing/teams/{team_id}/postpaid/invoice/preview", "headers": { "Authorization": "Bearer {MANAGEMENT_KEY}" } },
+        {
+          "kind": "usage_analytics",
+          "method": "POST",
+          "url": "https://management-api.x.ai/v1/billing/teams/{team_id}/usage",
+          "headers": { "Authorization": "Bearer {MANAGEMENT_KEY}" },
+          "body": "{ analyticsRequest:{ timeRange:{startTime,endTime,timezone}, timeUnit, values:[{name,aggregation}], groupBy:[], filters:[] } }",
+          "responseShape": "{ timeSeries:[{ group, groupLabels, dataPoints:[{timestamp, values[]}] }], limitReached }"
+        },
+        { "kind": "model_rate_limits", "method": "GET", "url": "https://management-api.x.ai/auth/teams/{teamId}/models", "headers": { "Authorization": "Bearer {MANAGEMENT_KEY}" } },
+        { "kind": "key_validation", "method": "GET", "url": "https://management-api.x.ai/auth/management-keys/validation", "headers": { "Authorization": "Bearer {MANAGEMENT_KEY}" } }
+      ],
+      "consoleUrl": "https://console.x.ai/team/default/billing",
+      "sources": [
+        "https://docs.x.ai/developers/rest-api-reference/management",
+        "https://docs.x.ai/developers/rest-api-reference/management/billing",
+        "https://docs.x.ai/console/billing"
+      ]
+    },
+    {
+      "id": "mistral",
+      "support": "no",
+      "credentialType": null,
+      "reason": "无任何公开余额/用量查询接口；官方文档无 billing API，开源余额工具均标注 Console only。",
+      "consoleUrl": "https://console.mistral.ai/usage",
+      "sources": [
+        "https://github.com/hanmumuHL/check_balance",
+        "https://theneuralbase.com/mistral-api/learn/advanced/la-plateforme-dashboard-overview/"
+      ]
+    }
+  ]
+}