dsh-plugin-subscriptions 0.5.2 → 0.6.0

package/README.md

@@ -2,7 +2,7 @@
 
 English | [中文](README.zh.md)
 
-Use your **ChatGPT (Codex)**, **Claude**, and **Grok (X Premium)** subscriptions as LLM providers in [DeepSeek Harness](https://github.com/deepseek-ai/deepseek-harness) — no API keys. Codex and Grok log in via OAuth in the dsh web UI (Settings → Subscriptions); Claude imports credentials from an existing Claude Code session when there is one (macOS Keychain or `~/.claude/.credentials.json`) and otherwise falls back to the same browser OAuth flow, so the Claude Code CLI is not required. Tokens live at `~/.dsh/plugins/subscriptions/auth.json` (mode 0600) and refresh automatically.
+Use your **ChatGPT (Codex)**, **Claude**, **Grok (X Premium)**, and **GitHub Copilot** subscriptions as LLM providers in [DeepSeek Harness](https://github.com/deepseek-ai/deepseek-harness) — no API keys. Codex and Grok log in via OAuth in the dsh web UI (Settings → Subscriptions), while Copilot uses the GitHub OAuth device flow; Claude imports credentials from an existing Claude Code session when there is one (macOS Keychain or `~/.claude/.credentials.json`) and otherwise falls back to the same browser OAuth flow, so the Claude Code CLI is not required. Tokens live at `~/.dsh/plugins/subscriptions/auth.json` (mode 0600) and refresh automatically.
 
 ## Demo
 
@@ -106,19 +106,32 @@ Either way, restart `dsh web` afterwards so the new version loads.
 ## Use
 
 1. `dsh web`, open the printed URL.
-2. Settings → **Subscriptions**: click **Connect** on a provider. For Claude, credentials are imported instantly if you have run `claude` and logged in at least once; without them, Claude authorizes in the browser like the others. For Codex and Grok, authorize in the opened browser tab; if the browser flow can't complete (headless host), expand the manual fallback and paste the callback URL or code.
-3. In any session, open the model picker (`/model`) and choose a model under **ChatGPT (Codex)** / **Claude (Subscription)** / **Grok (Subscription)**.
+2. Settings → **Subscriptions**: click **Connect** on a provider. For Claude, credentials are imported instantly if you have run `claude` and logged in at least once; without them, Claude authorizes in the browser like the others. For Codex and Grok, authorize in the opened browser tab; Copilot shows a GitHub device code to enter at `github.com/login/device`; if a browser flow can't complete (headless host), expand the manual fallback and paste the callback URL or code.
+3. In any session, open the model picker (`/model`) and choose a model under **ChatGPT (Codex)** / **Claude (Subscription)** / **Grok (Subscription)** / **GitHub Copilot**.
 
 Not logged in? The provider stays out of the picker, and requests fail with `MISSING_CREDENTIAL` pointing at the Settings page; nothing else breaks.
 
+### Multiple accounts
+
+Every provider accepts several accounts: once one is connected, the card grows an **Add account** button (Claude offers **Browser authorization** and **Import Claude Code** separately). Accounts are keyed by their identity (email / login) — re-logging the same account updates it in place, a different account appends. Browser authorization signs in whichever account the browser currently uses, so switch accounts there first (or use an incognito window with the manual code) to add a different one. The ★ default account serves the direct provider routes; pool routes use every account. A Claude account imported from Claude Code stays synced with the CLI's credential store; OAuth-added Claude accounts refresh standalone so several accounts never fight over the Keychain entry.
+
+### Default reasoning effort per model
+
+Every logged-in provider card in Settings → Subscriptions carries a collapsible **Default reasoning effort** section. It starts collapsed — the header shows how many models advertise reasoning levels and how many you have overridden — and the model list (with its live catalog lookup) loads only once you expand it, so a provider with dozens of models does not stretch the page or make it pay for a lookup nobody asked for. Expanded, each model that advertises reasoning levels gets a row whose options are the levels that provider's live catalog advertises for that exact model; past 8 such models the section also offers a name filter, and models without reasoning levels collapse into a single count line instead of one dead row each. With several accounts connected, the model list is the union across that provider's accounts, so a model any account advertises gets a row; the levels offered for it come from the first account whose catalog lists it (the ★ default account first), matching what the session picker resolves.
+
+Pick a level to make the session model picker preselect it whenever you switch to the model — no more settling for the provider's own default (e.g. Claude shows `Default`, Codex models follow `default_reasoning_level`). Choose **Follow provider** to clear the override. The choice is stored in `~/.dsh/plugins/subscriptions/model-defaults.json` (mode 0600) and survives restarts.
+
 ## Config
 
 ```yaml
 - id: llm-subscriptions
   name: dsh-plugin-subscriptions
   config:
-    providers: [codex, claude]        # subset; default all three
+    providers: [codex, claude]        # subset; default all four
     streamIdleTimeoutMs: 300000
+    rateLimit:
+      wait: true                       # wait out a closed rate-limit window (default)
+      maxWaitMs: 21600000              # ceiling on one wait; 6 h, covers a 5-hour session window
     models:                            # override the discovered/built-in catalogs
       codex:
         - { id: gpt-5.6-sol, name: GPT-5.6 Sol, contextWindow: 272000, inputModalities: [text, image] }
@@ -132,6 +145,67 @@ catalog does not know would otherwise default to `/chat/completions`, which
 responses-only families (gpt-5.5/5.6, …) reject. Pinning `chat-completions` also opts
 out of the tools+effort auto-reroute described above.
 
+## Model pools
+
+When a provider has **two or more logged-in accounts**, the picker shows the **union** of every account's catalog (duplicates dropped). Pick `claude-sonnet-5` under Claude (or `gpt-5.4` under ChatGPT) as usual — there is no extra pool group and no new model id.
+
+- **Shared models.** A model listed by ≥2 accounts failovers between them (sticky, quota-aware). Each account is discovered separately, so a Plus login is not asked to serve a Pro-only model.
+- **Account-only models.** A model listed by only one account is sent to that account. It still appears in the picker even if that account is not the default.
+- **Explicit account lists (`families`).** Replace the auto member list for one catalog model (same provider only; cross-provider members are ignored). Pin `account` or omit it for the default.
+- **Tier extras (`tiers`, optional).** Extra picker rows with heterogeneous fallbacks, listed under the first member's provider. Not created automatically.
+
+Selection is sticky per session (prompt caches survive) with two strategies: `priority` (first healthy member wins) and `quota_aware` (the default — each member is scored by its required burn rate, `remaining quota / time until window reset`, so a window about to reset with plenty left gets spent instead of wasted; the sticky member holds until a challenger out-scores it by `switchMargin`). Members past 95% on any usage window are gated out; failures fail over before the first stream chunk with cooldowns (`retry-after`, or the window's own disclosed reset when the provider sends one) — quota and rate-limit failures cool the whole account down (its quota is account-level; Claude's model-scoped lanes cool per member), transient server failures cool only the failing member. Copilot exposes no usage telemetry, so it scores zero and naturally serves as the fallback of last resort.
+
+```yaml
+- id: llm-subscriptions
+  name: dsh-plugin-subscriptions
+  config:
+    pool:
+      enabled: true                   # default; needs ≥2 accounts of one provider
+      strategy: quota_aware           # or priority
+      switchMargin: 2                 # hysteresis factor for quota_aware
+      autoAccounts: true              # pool each catalog model across that provider's accounts
+      families:                       # explicit account list for one catalog model (same provider)
+        claude-sonnet-5:
+          - { provider: claude, model: claude-sonnet-5 }                   # default account
+          - { provider: claude, account: bob@example.com, model: claude-sonnet-5 }
+      tiers:                          # optional extra picker rows
+        smart:
+          - { provider: claude, model: claude-sonnet-5 }
+          - { provider: codex, model: gpt-5.6-sol }
+          - { provider: grok, model: grok-4.6 }
+```
+
+### Waiting out a rate-limit window
+
+A subscription plan is rate-limit shaped by design — a 5-hour session window, a weekly one, and on some plans a per-model weekly one — so a 429 is not a dead end: the window reopens at a time the provider discloses. Each route reads that reset off its own 429 and turns it into that account's pool cooldown (see Model pools above) instead of a fixed 5-minute guess.
+
+Only a signal that names the window which actually rejected the request is read: Anthropic's `anthropic-ratelimit-unified-reset`, the seconds Codex puts on a `usage_limit_reached` rejection, the delay xAI names in the error body, or a plain `retry-after`. The per-bucket rollover snapshots (`anthropic-ratelimit-{requests,tokens,…}-reset`, `x-codex-*-reset-after-seconds`, `x-ratelimit-reset-*`) ride every response and cannot say which bucket refused — the earliest is usually one that still had room — so a 429 carrying nothing else is logged through the plugin's warning sink, naming the headers and the head of the body, rather than parking the turn (or the pool cooldown) on a guess.
+
+Reading is confined to a 429. Every other failure keeps its short local backoff: those same headers ride a transient 500 too, and honouring them there would hold a turn for the rest of the window over an overload that clears in a second.
+
+With a pool, this is what actually does the waiting: a 429'd account is parked until its own disclosed reset and the request fails over to another account of the same provider immediately — no wait, no lost turn. Only once **every** account (the whole pool) is cooling down does the adapter report a `RATE_LIMIT` carrying the pool's *earliest* reset as the wait to take. With a single account (no pool, or a provider with only one login), that same disclosed reset is reported directly.
+
+Waiting on that reported delay is executed by [`@deepseek-ai/dsh-llm-retry`](https://www.npmjs.com/package/@deepseek-ai/dsh-llm-retry), which every route's retry policy is written for: add it to the composition, or nothing waits and a closed window fails the turn as before (falling back to whichever other pool accounts are healthy, if any).
+
+```yaml
+- name: '@deepseek-ai/dsh-llm-retry'
+```
+
+```yaml
+- name: dsh-plugin-subscriptions
+  config:
+    rateLimit:
+      wait: true            # default; false keeps the previous seconds-scale behaviour
+      maxWaitMs: 21600000   # 6 h — covers a 5-hour session window with slack
+```
+
+A reset further out than `maxWaitMs` — a weekly window days away, or a whole pool cooling down past it — fails the turn immediately with the reset time attached, rather than parking the session for days. `wait: false` drops back to local backoff alone.
+
+All four routes share Claude Code's own retry shape: ten retries after the first attempt, backing off from 1 s with 20% jitter under a 60 s cap. These are consumer subscription endpoints that shed load in bursts, and the dsh-llm defaults (five retries from 500 ms to 10 s) give up after about fifteen seconds, which is short for that. A 429 that discloses no reset is now retried locally for roughly 17 minutes before the turn fails — about 5 minutes with `wait: false`, where the 60 s cap actually binds. Copilot currently uses the generic `retry-after` signal; unrecognized GitHub rate-limit headers are surfaced through the plugin warning sink for a future provider-specific reader.
+
+One trade-off worth knowing: the delay ceiling is shared with that local backoff, so raising `maxWaitMs` also raises how long an unrelated transient failure (`TRANSPORT`, `SERVER`, `TIMEOUT`) can back off for before the finite retry budget runs out — up to 512 s on the last of the ten retries instead of the 60 s cap.
+
 ## Proxy
 
 Every subscription request — token exchanges, model-API streams, usage lookups, model discovery, and the `x_search` / `image_generate` / `video_generate` tools — can be routed through an HTTP(S) proxy. Configure it in **Settings → Subscriptions → Proxy → Configure…**: enable the flag, enter the proxy URL (`http://127.0.0.1:7890`), optional username/password, and an optional comma-separated bypass list of hostnames that stay direct (`127.0.0.1`, `localhost`, `*.example.com`). The password is stored in `~/.dsh/plugins/subscriptions/proxy.json` (mode 0600) and is never returned to the browser. A "Test" button probes one endpoint through the current configuration and shows the HTTP status/latency.
@@ -154,7 +228,7 @@ After `pnpm build`, restart `dsh web` to pick up changes.
 
 - `src/index.ts` — plugin entry: config schema, adapter registration, auth-change re-announce, RPC wiring
 - `src/auth/` — PKCE/JWT helpers, token store, OAuth flow engine (temp loopback callback server), Claude Code credential reader (Keychain/file), `/subscriptions-auth` RPC channel
-- `src/providers/` — per-provider OAuth constants/exchange/refresh + `LlmAdapter`s
+- `src/providers/` — per-provider OAuth constants/exchange/refresh + `LlmAdapter`s, multi-account token plumbing (`accounts.ts`), the pool (`pool.ts` + `pool-health.ts` / `pool-usage.ts` / `pool-family.ts`), and `rate-limit.ts` (reset-instant parsing + retry policy)
 - `src/translate/` — dsh `Message[]` ⟷ OpenAI Responses / Anthropic Messages wire formats, SSE → `StreamChunk`
 - `src/tools/` — `x_search`, `image_generate`, and `video_generate`
 - `src/client/` — the Settings → Subscriptions page (browser half, zh/en, theme-token aware)

package/README.zh.md

@@ -106,19 +106,32 @@ GitHub 安装的:重新执行一遍 `add github:V1ki/dsh-plugin-subscriptions`
 ## 使用
 
 1. `dsh web`,打开打印的 URL。
-2. **设置 → 订阅**:点对应 provider 的「连接」。若先运行过 `claude` 并登录,Claude 会即时导入凭据;没有凭据时,Claude 也和其他 provider 一样在浏览器里授权。Codex 和 Grok 在打开的标签页里授权;无浏览器环境下可展开手动兜底,粘贴回调 URL 或授权码。
-3. 在任意会话里打开模型选择器(`/model`),选择 **ChatGPT (Codex)** / **Claude (Subscription)** / **Grok (Subscription)** 下的模型。
+2. **设置 → 订阅**:点对应 provider 的「连接」。若先运行过 `claude` 并登录,Claude 会即时导入凭据;没有凭据时,Claude 也和其他 provider 一样在浏览器里授权。Codex 和 Grok 在打开的标签页里授权;Copilot 会显示 GitHub 设备码,需在 `github.com/login/device` 输入;无浏览器环境下可展开手动兜底,粘贴回调 URL 或授权码。
+3. 在任意会话里打开模型选择器(`/model`),选择 **ChatGPT (Codex)** / **Claude (Subscription)** / **Grok (Subscription)** / **GitHub Copilot** 下的模型。
 
 未登录时:该 provider 不出现在选择器里;直接请求会报 `MISSING_CREDENTIAL` 并提示去设置页登录,不影响其他功能。
 
+### 多账号
+
+每个 provider 可以登录多个账号:连上第一个之后,卡片会出现「添加账号」按钮(Claude 拆分为「浏览器授权」和「导入 Claude Code」两种)。账号按身份(邮箱/用户名)归档——重复登录同一账号是覆盖更新,不同账号才是新增。浏览器授权以浏览器当前登录的账号为准,要添加不同账号请先在浏览器切换账号,或用无痕窗口走手动授权码。★ 默认账号服务直连路由;池路由会使用所有账号。从 Claude Code 导入的 Claude 账号会与 CLI 的凭据存储保持同步;OAuth 添加的 Claude 账号独立刷新,多个账号不会互相覆盖 Keychain。
+
+### 按模型的默认推理档
+
+**设置 → 订阅**里每个已登录 provider 卡片都有一个可折叠的**默认推理档**区块。默认收起,标题栏直接给出「多少个模型声明了推理档 / 已覆盖多少个」;模型列表(以及它背后的 live 目录查询)只在展开时才加载 —— 这样模型数量很多的 provider(Copilot 动辄几十个)既不会把页面撑长,也不会白跑一次目录查询。展开后,凡声明了推理档的模型各占一行,可选档位就是该 provider live 目录为这个模型声明的档位;此类模型超过 8 个时区块还会给出一个名称筛选框;没有推理档的模型不再一行一条占位,而是合并成一行计数说明。登录了多个账号时,模型列表是该 provider 各账号目录的并集 —— 任一账号声明的模型都会出现;而某个模型可选的档位取自**第一个列出它的账号**(★ 默认账号优先),与会话选择器解析到的一致。
+
+选中某档后,会话模型选择器在切换到该模型时会自动预选该档位,不必再接受 provider 自己的默认值(例如 Claude 只显示 `Default`,Codex 模型跟随 `default_reasoning_level`)。选择「跟随服务商」可清除覆盖。配置存于 `~/.dsh/plugins/subscriptions/model-defaults.json`(权限 0600),重启后依然生效。
+
 ## 配置
 
 ```yaml
 - id: llm-subscriptions
   name: dsh-plugin-subscriptions
   config:
-    providers: [codex, claude]        # 子集;默认三个全启用
+    providers: [codex, claude]        # 子集;默认四个全启用
     streamIdleTimeoutMs: 300000
+    rateLimit:
+      wait: true                       # 等待限流窗口重开(默认开启)
+      maxWaitMs: 21600000              # 单次等待上限;6 小时,足够覆盖 5 小时会话窗口
     models:                            # 覆盖实时发现/内置目录
       codex:
         - { id: gpt-5.6-sol, name: GPT-5.6 Sol, contextWindow: 272000, inputModalities: [text, image] }
@@ -131,6 +144,67 @@ GitHub 安装的:重新执行一遍 `add github:V1ki/dsh-plugin-subscriptions`
 responses-only 系列（gpt-5.5/5.6 等）会拒绝该端点。固定为 `chat-completions` 也会退出上文所述
 tools+effort 的自动改道。
 
+## 模型池
+
+同一订阅下登录了**两个及以上账号**时,选择器显示该 provider **所有账号目录的并集**(按模型 id 去重)。照常在 Claude 组选 `claude-sonnet-5`、在 ChatGPT 组选 `gpt-5.4`——不会多出一个池分组,也不会换 model id。
+
+- **共有模型**：至少两个账号的目录都列出的模型,在这些账号之间 failover(粘性、可按配额调度)。每个账号各自做一次目录发现,Plus 不会被拿去打 Pro 才有的模型。
+- **单账号模型**：只有一个账号目录里有的模型,请求就打到那个账号。即使它不是默认账号,选择器里也会出现。
+- **显式账号列表(`families`)**：覆盖某个目录模型的自动成员(仅同一 provider;跨 provider 的成员会被忽略)。可钉 `account`,省略则用默认账号。
+- **档位额外项(`tiers`,可选)**：额外的选择器条目,failover 可以跨模型;出现在首个成员所在的 provider 分组。不会自动创建。
+
+成员选择按会话粘性(prompt 缓存不失效),两种策略:`priority`(按顺序取第一个健康成员)和 `quota_aware`(默认——按"必需消耗速率 = 剩余配额 / 距重置时间"给成员打分,快重置且剩余多的窗口优先被用掉而不是浪费;粘性成员除非被挑战者以 `switchMargin` 倍分差击败否则不换)。任一用量窗口超过 95% 的成员会被硬门槛挡下;首个流式 chunk 之前的失败会记冷却并切换下一家(provider 给了 `retry-after` 就用它)——配额与认证类失败按整个账号冷却(配额是账号级的;Claude 的分模型窗口则只冷却出错成员),瞬时服务端失败只冷却出错成员。Copilot 没有用量接口,恒为 0 分,自然充当最后的保底。
+
+```yaml
+- id: llm-subscriptions
+  name: dsh-plugin-subscriptions
+  config:
+    pool:
+      enabled: true                   # 默认开;需同一 provider ≥2 个账号
+      strategy: quota_aware           # 或 priority
+      switchMargin: 2                 # quota_aware 的滞后切换倍率
+      autoAccounts: true              # 把该 provider 各账号自动池到每个目录模型
+      families:                       # 某个目录模型的显式账号列表(同一 provider)
+        claude-sonnet-5:
+          - { provider: claude, model: claude-sonnet-5 }                   # 默认账号
+          - { provider: claude, account: bob@example.com, model: claude-sonnet-5 }
+      tiers:                          # 可选的额外选择器条目
+        smart:
+          - { provider: claude, model: claude-sonnet-5 }
+          - { provider: codex, model: gpt-5.6-sol }
+          - { provider: grok, model: grok-4.6 }
+```
+
+### 等待限流窗口
+
+订阅套餐天然是按限流窗口计费的 —— 5 小时会话窗口、周窗口，部分套餐还有按模型的周窗口 —— 所以 429 并不是终点：窗口会在 provider 自己告知的时刻重开。每条路由从自己的 429 里读出这个时刻，把它变成该账号在模型池里的冷却时长（见上文「模型池」），而不是固定猜测的 5 分钟。
+
+只有能指明「是哪个窗口拒绝了这次请求」的信号才会被读取：Anthropic 的 `anthropic-ratelimit-unified-reset`、Codex 在 `usage_limit_reached` 上给出的秒数、xAI 在错误体里给出的延迟，或通用的 `retry-after`。各分桶的滚动快照（`anthropic-ratelimit-{requests,tokens,…}-reset`、`x-codex-*-reset-after-seconds`、`x-ratelimit-reset-*`）每个响应上都有，说不出是哪个桶拒绝的 —— 其中最早的那个往往正是还有余量的桶 —— 所以只带这些的 429 会通过插件的告警回调打印出相关 header 与响应体开头，而不是照着猜测把本轮(或池冷却)挂起。
+
+读取只发生在 429 上。其他失败仍走各自的短本地退避:同样这些 header 也会出现在瞬时 500 上,在那里照办等于为一次一秒就恢复的过载把本轮挂满整个窗口。
+
+有模型池时，真正在做等待这件事的其实是账号 failover：某个账号 429 了就按它自己披露的重开时刻冷却下来，请求立刻切到同 provider 的下一个账号 —— 不等待，也不丢本轮对话。只有**整个池**（所有账号）都在冷却时，adapter 才会上报一个 `RATE_LIMIT`，携带池里**最早**的重开时刻作为应等待的时长。单账号（没配池，或该 provider 只登了一个号）时，同样的披露时刻会被直接上报。
+
+真正执行这段等待的是 [`@deepseek-ai/dsh-llm-retry`](https://www.npmjs.com/package/@deepseek-ai/dsh-llm-retry)，四条路由的重试策略都是为它写的：把它加进编排，否则不会有任何等待，关闭的窗口仍旧直接让本轮失败（如果池里还有别的健康账号，会先 failover 过去）。Copilot 当前使用通用的 `retry-after` 信号；GitHub 未识别的限流 header 会通过插件告警回调暴露出来，后续再添加 provider 专用解析器。
+
+```yaml
+- name: '@deepseek-ai/dsh-llm-retry'
+```
+
+```yaml
+- name: dsh-plugin-subscriptions
+  config:
+    rateLimit:
+      wait: true            # 默认；false 恢复此前秒级的行为
+      maxWaitMs: 21600000   # 6 小时 —— 留有余量地覆盖 5 小时会话窗口
+```
+
+重开时刻超过 `maxWaitMs`(比如几天后才重置的周窗口,或者整个池的冷却时间超过这个上限)会立即失败并带上重开时刻,而不是把会话挂上好几天。`wait: false` 则只保留本地退避。
+
+四条路由共用 Claude Code 自己的重试形状:首次尝试之后重试 10 次,从 1 秒开始退避,带 20% 抖动,上限 60 秒。这些都是面向消费者的订阅端点,过载时按突发丢流量,而 dsh-llm 默认值(5 次重试,500 毫秒到 10 秒)约 15 秒就放弃,对这种场景偏短。没有给出重开时刻的 429 现在会本地重试约 17 分钟才让本轮失败 —— `wait: false` 下约 5 分钟,那时 60 秒上限才真正生效。
+
+一个需要知道的取舍:延迟上限与这份本地退避共用,调高 `maxWaitMs` 同时也抬高了无关瞬时失败(`TRANSPORT`、`SERVER`、`TIMEOUT`)在有限重试预算耗尽前的退避时长 —— 第 10 次重试最长会从 60 秒上限变成 512 秒。
+
 ## 代理
 
 所有订阅相关请求 —— token 交换、模型 API 流式调用、用量查询、模型目录发现,以及 `x_search` / `image_generate` / `video_generate` 工具 —— 都可以通过 HTTP(S) 代理发出。在 **设置 → 订阅 → 代理 → 配置…** 中设置:勾选启用,填写代理地址(`http://127.0.0.1:7890`)、可选用户名/密码,以及可选的逗号分隔绕过列表(保持直连的主机名,如 `127.0.0.1`、`localhost`、`*.example.com`)。密码保存在 `~/.dsh/plugins/subscriptions/proxy.json`(权限 0600),不会回传给浏览器;「测试」按钮会用当前配置探测一次端点,显示 HTTP 状态码与耗时。
@@ -153,7 +227,7 @@ pnpm test      # 编译后跑 node --test 单测
 
 - `src/index.ts` —— 插件入口:配置 schema、adapter 注册、登录态变更通告、RPC 接线
 - `src/auth/` —— PKCE/JWT 工具、token 存储、OAuth 流程引擎(临时本地回调服务)、Claude Code 凭据读取器(Keychain/文件)、`/subscriptions-auth` RPC 通道
-- `src/providers/` —— 各 provider 的 OAuth 常量/换发/刷新 + `LlmAdapter` 实现
+- `src/providers/` —— 各 provider 的 OAuth 常量/换发/刷新 + `LlmAdapter` 实现，多账号 token 管理（`accounts.ts`），模型池（`pool.ts` + `pool-health.ts` / `pool-usage.ts` / `pool-family.ts`），以及 `rate-limit.ts`（限流重开时刻解析 + 重试策略）
 - `src/translate/` —— dsh `Message[]` 与 OpenAI Responses / Anthropic Messages 格式互转,SSE → `StreamChunk`
 - `src/tools/` —— `x_search`、`image_generate` 与 `video_generate`
 - `src/client/` —— 设置 → 订阅页面(浏览器面,中英文,跟随明暗主题)

package/lib/auth/rpc.d.ts

@@ -37,19 +37,30 @@ export interface SpeedController {
     /** Set one session's speed tier. */
     setSpeed(sessionId: string, tier: SpeedTier): Promise<void>;
 }
+/** One logged-in account, as rendered by the Settings page. */
+export interface AccountStatus {
+    /** Stable account key (store identity). */
+    key: string;
+    /** Display identity (email / login), when known. */
+    account?: string;
+    /** Epoch milliseconds at which the stored access token expires. */
+    expiresAt?: number;
+    /** Plan name the session carries (codex planType / claude subscriptionType), when known. */
+    plan?: string;
+    /** Whether direct (non-pool) routes serve this account. */
+    isDefault: boolean;
+}
 /** Login state of one provider, as rendered by the Settings page. */
 export interface ProviderStatus {
-    /** Whether a session exists in the store. */
-    loggedIn: boolean;
     /** Whether a login attempt is currently waiting for its code. */
     busy: boolean;
-    /** Epoch milliseconds at which the stored access token expires. */
-    expiresAt?: number;
-    /** Account email or account id, when known. */
-    account?: string;
-    /** Subscription detail (plan) or the last login error. */
+    /** Logged-in accounts, default first. */
+    accounts: AccountStatus[];
+    /** The last login error, shown until the next success. */
     detail?: string;
 }
+/** How a Claude login should acquire credentials (other providers ignore it). */
+export type LoginMethod = 'oauth' | 'keychain';
 /** Proxy config operations behind the `proxyGet/proxySet/proxyTest` endpoints. */
 export interface ProxyConfigController {
     /** Current proxy configuration (secrets omitted). */
@@ -62,17 +73,49 @@ export interface ProxyConfigController {
         proxy?: ProxyDraft;
     }): Promise<ProxyTestResult>;
 }
+/** One model's default-effort picker state, as rendered by the Settings page. */
+export interface ModelDefaultView {
+    /** Wire model id. */
+    id: string;
+    /** Human-readable display name. */
+    name: string;
+    /** Advertised effort levels, in catalog order (empty when the model has no reasoning). */
+    efforts: {
+        id: string;
+        name: string;
+    }[];
+    /** The user-configured default effort, when set. */
+    configured?: string;
+}
+/** One provider's default-effort picker state. */
+export interface ModelDefaultsCatalog {
+    /** The subscription provider route. */
+    provider: ProviderId;
+    /** Models the picker can configure, in catalog order. */
+    models: ModelDefaultView[];
+}
+/** Default-effort picker operations behind the `modelDefaults/setModelDefault` endpoints. */
+export interface ModelDefaultsController {
+    /** Per-provider picker state for the Settings page. */
+    catalog(): Promise<ModelDefaultsCatalog[]>;
+    /** Set one model's configured default effort; undefined clears the override. */
+    set(provider: ProviderId, model: string, effort: string | undefined): Promise<void>;
+}
 /** Provider-agnostic auth operations the RPC handler delegates to. */
 export interface AuthController {
     /** Current status of one provider. */
     status(provider: ProviderId): Promise<ProviderStatus>;
     /**
      * Start a background login attempt.
+     * @param provider - the provider route.
+     * @param method - Claude only: force the OAuth browser flow or the Claude
+     *   Code credential import; omitted keeps the auto behavior (import when
+     *   available, else OAuth).
      * @returns the authorize URL for the user's browser; device-flow providers
      *   (copilot) also return the `userCode` the user types at that URL.
      * @throws when an attempt is already running for this provider.
      */
-    login(provider: ProviderId): Promise<{
+    login(provider: ProviderId, method?: LoginMethod): Promise<{
         authorizeUrl: string;
         userCode?: string;
     }>;
@@ -83,15 +126,19 @@ export interface AuthController {
     manual(provider: ProviderId, input: string): Promise<void>;
     /** Abort the pending attempt; a no-op when none is pending. */
     cancel(provider: ProviderId): Promise<void>;
-    /** Delete the stored session. */
-    logout(provider: ProviderId): Promise<void>;
+    /** Delete one account's stored session. */
+    logout(provider: ProviderId, account: string): Promise<void>;
+    /** Pin the account direct (non-pool) routes serve. */
+    setDefault(provider: ProviderId, account: string): Promise<void>;
     /**
-     * Current subscription usage of one provider.
+     * Current subscription usage of one account.
      * @param signal - caller cancellation from the RPC transport.
+     * @param force - bypass a fresh cached snapshot for an honest re-check
+     *   (the manual Refresh button); a live failure cooldown still applies.
      * @returns `{ supported: false }` when the provider has no usage endpoint.
      * @throws when logged out or the usage lookup fails.
      */
-    usage(provider: ProviderId, signal: AbortSignal): Promise<ProviderUsage>;
+    usage(provider: ProviderId, account: string, signal: AbortSignal, force?: boolean): Promise<ProviderUsage>;
     /**
      * Read one image attachment's bytes for inline display.
      * @param ref - the full durable reference (`readImage` verifies against it).
@@ -110,11 +157,15 @@ export interface AuthController {
      */
     readVideo(name: string, signal: AbortSignal): Promise<VideoBytesResult>;
 }
+/** Payload carried no usable provider id — an RPC client bug, not a server failure. */
+export declare class BadRequest extends Error {
+}
 /**
  * Register the `/subscriptions-auth` RPC channel when a host connection exists.
  * @param ctx - the plugin context (headless profiles have no `connection`).
  * @param controller - the auth operations backing the endpoints.
  * @param speed - the per-session speed-tier state backing the Speed toggle.
  * @param proxy - optional proxy-config controller backing `proxyGet`/`proxySet`/`proxyTest`.
+ * @param modelDefaults - optional per-model default-effort state backing `modelDefaults`/`setModelDefault`.
  */
-export declare function registerAuthRpc(ctx: Context, controller: AuthController, speed: SpeedController, proxy?: ProxyConfigController | undefined): void;
+export declare function registerAuthRpc(ctx: Context, controller: AuthController, speed: SpeedController, proxy?: ProxyConfigController | undefined, modelDefaults?: ModelDefaultsController | undefined): void;

package/lib/auth/rpc.js

@@ -13,7 +13,7 @@ const IMAGE_MEDIA_TYPES = ['image/png', 'image/jpeg', 'image/webp', 'image/gif']
 /** Bare MP4 file names the `video` endpoint accepts (no path separators). */
 const VIDEO_NAME_PATTERN = /^[\w.-]+\.mp4$/;
 /** Payload carried no usable provider id — an RPC client bug, not a server failure. */
-class BadRequest extends Error {
+export class BadRequest extends Error {
 }
 function ok(value) {
     return { ok: true, value };
@@ -42,6 +42,36 @@ function readString(payload, field) {
     }
     return value;
 }
+/** Validate the `setModelDefault` endpoint's payload. */
+function readModelDefaultInput(payload) {
+    const provider = readProvider(payload);
+    const model = readString(payload, 'model');
+    const record = payload;
+    let effort;
+    if (record.effort !== undefined) {
+        if (typeof record.effort !== 'string' || record.effort.length === 0) {
+            throw new BadRequest('payload.effort must be a non-empty string when present');
+        }
+        effort = record.effort;
+    }
+    return {
+        provider,
+        model,
+        ...(effort === undefined ? {} : { effort }),
+    };
+}
+/** Validate the optional Claude login method. */
+function readLoginMethod(payload, provider) {
+    const method = payload.method;
+    if (method === undefined)
+        return undefined;
+    if (provider !== 'claude')
+        throw new BadRequest('payload.method is only valid for claude');
+    if (method !== 'oauth' && method !== 'keychain') {
+        throw new BadRequest('payload.method must be "oauth" or "keychain"');
+    }
+    return method;
+}
 /** Validate the `setSpeed` endpoint's tier. */
 function readSpeedTier(payload) {
     const tier = payload.tier;
@@ -96,6 +126,17 @@ function readVideoName(payload) {
     }
     return name;
 }
+/** Validate the `usage` endpoint's optional force flag. */
+function readForce(payload) {
+    if (typeof payload !== 'object' || payload === null)
+        return false;
+    const force = payload.force;
+    if (force === undefined)
+        return false;
+    if (typeof force !== 'boolean')
+        throw new BadRequest('payload.force must be a boolean when present');
+    return force;
+}
 /** Validate the session id both speed endpoints carry. */
 function readSessionId(payload) {
     if (typeof payload !== 'object' || payload === null)
@@ -184,14 +225,16 @@ function readProxyTestPayload(payload) {
         ...proxy === undefined ? {} : { proxy },
     };
 }
-async function dispatch(controller, speed, proxy, endpoint, payload, signal) {
+async function dispatch(controller, speed, proxy, modelDefaults, endpoint, payload, signal) {
     switch (endpoint) {
         case 'status': {
             const entries = await Promise.all(PROVIDER_IDS.map(async (provider) => [provider, await controller.status(provider)]));
             return ok({ providers: Object.fromEntries(entries) });
         }
-        case 'login':
-            return ok(await controller.login(readProvider(payload)));
+        case 'login': {
+            const provider = readProvider(payload);
+            return ok(await controller.login(provider, readLoginMethod(payload, provider)));
+        }
         case 'manual': {
             const provider = readProvider(payload);
             await controller.manual(provider, readString(payload, 'input'));
@@ -200,11 +243,20 @@ async function dispatch(controller, speed, proxy, endpoint, payload, signal) {
         case 'cancel':
             await controller.cancel(readProvider(payload));
             return ok({ ok: true });
-        case 'logout':
-            await controller.logout(readProvider(payload));
+        case 'logout': {
+            const provider = readProvider(payload);
+            await controller.logout(provider, readString(payload, 'account'));
+            return ok({ ok: true });
+        }
+        case 'setDefault': {
+            const provider = readProvider(payload);
+            await controller.setDefault(provider, readString(payload, 'account'));
             return ok({ ok: true });
-        case 'usage':
-            return ok(await controller.usage(readProvider(payload), signal));
+        }
+        case 'usage': {
+            const provider = readProvider(payload);
+            return ok(await controller.usage(provider, readString(payload, 'account'), signal, readForce(payload)));
+        }
         case 'image':
             return ok(await controller.readImage(readImageRef(payload), signal));
         case 'video':
@@ -226,6 +278,18 @@ async function dispatch(controller, speed, proxy, endpoint, payload, signal) {
             if (proxy === undefined)
                 throw new BadRequest('proxy configuration is unavailable');
             return ok(await proxy.test(readProxyTestPayload(payload)));
+        case 'modelDefaults':
+            if (modelDefaults === undefined)
+                throw new BadRequest('model defaults are unavailable');
+            return ok(await modelDefaults.catalog());
+        case 'setModelDefault':
+            if (modelDefaults === undefined)
+                throw new BadRequest('model defaults are unavailable');
+            {
+                const input = readModelDefaultInput(payload);
+                await modelDefaults.set(input.provider, input.model, input.effort);
+            }
+            return ok({ ok: true });
         default:
             throw new BadRequest(`unknown /subscriptions-auth endpoint "${endpoint}"`);
     }
@@ -236,8 +300,9 @@ async function dispatch(controller, speed, proxy, endpoint, payload, signal) {
  * @param controller - the auth operations backing the endpoints.
  * @param speed - the per-session speed-tier state backing the Speed toggle.
  * @param proxy - optional proxy-config controller backing `proxyGet`/`proxySet`/`proxyTest`.
+ * @param modelDefaults - optional per-model default-effort state backing `modelDefaults`/`setModelDefault`.
  */
-export function registerAuthRpc(ctx, controller, speed, proxy = undefined) {
+export function registerAuthRpc(ctx, controller, speed, proxy = undefined, modelDefaults = undefined) {
     // `connection` is not in this plugin's inject list (headless compositions
     // lack it), so its startup order is unconstrained: defer registration until
     // the service exists instead of probing once at apply time.
@@ -245,7 +310,7 @@ export function registerAuthRpc(ctx, controller, speed, proxy = undefined) {
         const connection = ctx.get('connection');
         ctx.effect(() => connection.rpc.handle(SUBSCRIPTIONS_AUTH_CHANNEL, async (endpoint, payload, signal) => {
             try {
-                return await dispatch(controller, speed, proxy, endpoint, payload, signal);
+                return await dispatch(controller, speed, proxy, modelDefaults, endpoint, payload, signal);
             }
             catch (error) {
                 return failure(error);