magicrew-auth 0.3.28 → 0.3.30

package/AGENTS.md

@@ -54,7 +54,7 @@ curl -s "https://usemagpie.ai/api/latest?channel=stable" | grep -o '"version":"[
 | 1 | 改好了国内站，国际站用户报同样的错 | **两站是同一个 Go 服务、逐字符同构**，改一处就要两站都验；`SITES.cn` / `SITES.intl` 只是 host 不同 | internals 一 |
 | 2 | 国际站 `/v1/chat/completions` 回 `HTTP 500` + 22 字节裸文本（不是 JSON） | 国际站网关**强制**要 `organization-code` 头，缺了就是这个 500 | internals 一 / 五 |
 | 3 | 换了 key 之后老 key 立刻失效、用户被要求重登 | **「签新 key 会吊销旧 key」已被实测推翻（2026-10-28）** —— 见下方「最容易误信的旧说法」。仍然只留一把、只走 `src/keys.mjs` 的唯一出口，理由是**本地别分叉**，不是互相吊销 | internals 十四 |
-| 4 | 刷新 token 之后两处 refresh_token 不一致、用户莫名掉登录 | 只允许**一个**出口持有 refresh_token；`src/hooks/refresh.mjs` 绕过出口就会分叉 | internals 二 / 十四 |
+| 4 | 刷新 token 之后两处 refresh_token 不一致、用户莫名掉登录 | 只允许**一个**出口持有 refresh_token；`src/hooks/refresh.mjs` 必须走 `keys.mjs` 的 `renewViaStore()`（0.3.29 起已收敛，与 `ensureKey` 共用 `renewOnce` 锁和同一个 key-store）。若改回自调 `refreshGatewayKey` 就会分叉 | internals 二 / 十四 |
 | 5 | agent 说「上下文放不下」，而实际模型能吃更长 | 上下文窗口**必须查 magpie 的模型库**，不能填保守值（早前一刀切 256K，实际 1M） | internals 十六 |
 | 6 | 流式回复拿到了，但 `usage` 永远是空、额度不扣 | 流式请求必须补 `stream_options.include_usage`，否则上游不回 usage | internals 十二 |
 | 7 | 模型被标成免费、Free first 一直派到它 | `free` 只认厂商声明（`input_points === 0`），**不能从 `rate === 0` 反推**；价格缺失 = 不列，不猜 | internals 十六 · HOOKS 十一之二 |
@@ -72,6 +72,9 @@ curl -s "https://usemagpie.ai/api/latest?channel=stable" | grep -o '"version":"[
 | 19 | 单轮回 `400 ... tools.N.function.parameters/properties/functions/items: invalid JSON Schema`，但请求里**没有**空 `items` | 上游对 **`items` 子树内部**比根节点严：`anyOf`/`oneOf`/`allOf`/`not`/`const`/`if`+`then`+`else`/`{}` 全 400，**tuple 形式的 `items`（数组）国际站拒**，而同样形态放在顶层 parameters 里 200。命中来源是 **MCP 工具 schema**（REA MCP 7 个工具的 `functions` 数组）。判据：同一请求只把 `items` 子树里的 `anyOf` 摊平 → 200；改完**必须复查没留下空 `{}`**（删 `not`/`const` 会删空）。⚠ **上游 2026-10-29 00:25 起放宽了这层校验（raw 也 200），同一夜里还出现过波动** —— 判要不要改写请看 `_probe/items-subtree-stability.mjs` 的多轮统计，别信单次探针。改写已做（`loosenItemsSchema`，**只动 `items` 子树**、顶层 union 不动） | internals 十七 · `tests/body-rewrite.mjs` · `_probe/items-subtree-upstream.mjs` |
 | 20 | 邮箱验证码登录报「phone 字段是必须的」或「captcha 字段是必须的」 | 邮箱和手机是**两套端点**：发信 `/v4/user/send-email` vs `/send-sms`，换登录态 `/v4/user/login-email` vs `/login`；邮箱那条验证码字段叫 **`captcha`**（不是 `code`）。判据：往 `/v4/user/login` 发任何 type 都回「phone 字段是必须的」 | `src/captcha.mjs` 头 · CHANGELOG 0.3.28 |
 | 21 | 无头登录「旋转验证连试 4 张图都没过」，而这号本来就是自己的 | 先分清两件事：① **已注册的号服务端根本不出图**（`/captcha/generate` 对已注册账号直接回 `business_token`）—— 所以必须**先取图、再判识图模型**，一上来就 `if (!vision) throw` 会把这条免费通道堵死；② 识图模型 `max_tokens` 太小会把推理答案饿死（`workbuddy/deepseek-v4.1-flash` 给 400 → `content:null`，判官抓空串） | CHANGELOG 0.3.28 · `src/vision.mjs` |
+| 22 | 同一账号有的请求 200、有的 403 `token无效`（`retryable=false`），换个时间又好了 | key 有两条签发路径时 store 与 magpie 各存一把，**静态挑一把必有一半踩空**。0.3.29 起 `keyCandidates()` 把 store 两槽 + `auth.access` 逐把打 chat，命中的写回 store；全被拒才交 402 让 magpie 换号。判据：`GET /v1/models` 对死 key **放行**，逐把探活必须用 `/v1/chat/completions` | CHANGELOG 0.3.29 · `tests/key-failover.mjs` |
+| 23 | 插件列表里别人有「已自动更新」徽章，magicrew 没有 | magpie 只自动更新包名以 `@magpie-community/` 开头的包（`internal/plugin/updates.go` 的 `Official()` 硬编码前缀）；第三方 npm / git 源永远只提示。本插件用 `src/auto-maintenance.mjs` 复刻：读 `plugin-updates.json` 的 `waiting` → 调 `magpie plugin update` → 成功后补 `updated[]`（徽章读它）。判据：`plugin-updates.json` 的 waiting 有 `package:"Magicrew", git:true`；`findMagpieExe()` 能解析到 magpie 可执行文件。⚠ 更新后要重启 magpie 才加载新代码 | CHANGELOG 0.3.30 · `tests/auto-maintenance.mjs` |
+| 24 | 新装插件后没有任何签到记录，`plugin-checkin.json` 里没有 magicrew | magpie 的 `PluginCheckinOn()`：`pluginCheckins` 没有显式值时默认 **false**（只有 WorkBuddy / Trae / MiniMax / Qoder 有内置开关）。插件只能在加载时把 `settings.json` 的 `pluginCheckins[provider]` 补成 true —— **只在键不存在时补**，用户显式 false 不覆盖。判据：`settings.json` 的 `pluginCheckins` 有 `magicrew` / `magicrew-intl` 键 | CHANGELOG 0.3.30 · `src/auto-maintenance.mjs` |
 
 **坑 14 的两个附带判据**（都实测过）：
 

package/CHANGELOG.md

@@ -1,5 +1,157 @@
 # 更新记录
 
+## 0.3.30 — 2026-10-29
+
+**默认开启自动签到 · 插件自身自动更新**
+
+### 一、默认开启自动签到
+
+magpie 的插件签到开关 `pluginCheckins` 默认是**关**的：`PluginCheckinOn()`
+在没有显式值时只跟随厂商内置开关（WorkBuddy / Trae / MiniMax / Qoder），
+magicrew 没有内置开关，于是新装插件不会自动签到。
+
+插件加载时读 `~/.config/magpie/settings.json`：**只有这个 provider 从未被
+用户设置过**，才补一个 `pluginCheckins[provider] = true`。用户显式关掉的
+（false）绝不覆盖；settings.json 读不出来也不覆盖。config 钩子先补一次，
+usage 钩子再兜一次（防止 magpie 启动时把内存里的旧 settings 写回）。
+
+### 二、插件自身自动更新
+
+magpie 的自动更新只认 `@magpie-community/*`（源码 `internal/plugin/updates.go`
+的 `Official()` 硬编码这个前缀）—— 第三方插件无论 npm 源还是 git 源，都只会
+在插件列表里提示「有新提交」，等用户点更新。这就是为什么社区包（Qoder、
+CodeArts、商汤小浣熊、OpenCode Zen Free）有「已自动更新」徽章，而本插件没有。
+
+插件没法改 magpie 的判断，只能在插件侧复刻同一套机制：
+
+1. `config` 加载 15 秒后、以及每次签到成功后，读 magpie 写好的
+   `~/.config/magpie/plugin-updates.json`，看 `waiting` 里有没有
+   `package === "Magicrew" && git === true` 的自己；
+2. 有就调本机 magpie 的 CLI：`magpie plugin update`（进程树里找 magpie，
+   也可以用环境变量 `MAGPIE_EXE` 明示；找不到就记 `no-magpie-exe` 并放弃，
+   不伪造徽章）；
+3. CLI 成功退出（code 0）后，在 `plugin-updates.json` 的 `updated[]` 里补一条
+   `{package:"Magicrew", from, to, at}` —— magpie 的「已自动更新」徽章
+   （`plugin.LastUpdated()`）读的就是这个记录。
+
+节流：同一版本 6 小时内最多试一次；成功后按 `to` 版本记住不再重复。所有失败
+都只写状态文件，不影响签到/额度/登录。
+
+### 边界（必须知道）
+
+- `magpie plugin update` 是 CLI 进程内的 `plugin.Update()`，会重装**所有**
+  非路径插件；它不会重启正在运行的 magpie —— 更新文件后，下次启动 magpie
+  才会加载新代码。插件列表的「已自动更新」徽章会立即出现（读的是文件记录）。
+- 找不到 magpie 可执行文件时不会自动更新，也不会显示徽章；设 `MAGPIE_EXE`
+  可指定。
+- 这一步是插件对 magpie 的两个配置文件（settings.json / plugin-updates.json）
+  的读写 —— magpie 没有给插件提供这两个能力的 API（GUI API 只服务于它自己的
+  WebView，不是 TCP 端口）。写 settings 只在「该键不存在」时发生，且先备份为
+  `settings.json.bak-magicrew-auto`。
+
+### 验证
+
+- `tests/auto-maintenance.mjs` 20 条断言 0 失败：默认签到只补缺失、显式 false
+  不覆盖、坏 JSON 不覆盖；`pickSelfUpdate` 只认自己且只认 git；`noteUpdated`
+  去重/截断；`kick` 的 no-update / no-exe / throttled / done / dryRun / 成功
+- 本机真实 `plugin-updates.json` 的 dryRun：命中 `Magicrew 272b812 → 050b0f4`，
+  解析到 `E:\Downloads\magpie-windows-amd64.exe`；`ensureCheckinDefault` 对
+  `magicrew` / `magicrew-intl` 均返回 explicit:true（已是用户开着的，不改）
+- `magpie plugin list` CLI 正常（只读）
+
+## 0.3.29 — 2026-10-29
+
+**同一账号多把 key 逐把试 · 全部被拒改 402 · 续期收敛到 key-store**
+
+（核心改动来自 PR #12，作者 @baijiu666；合入时补了五处，见文末「合入时补的五处」。）
+
+### 症状
+
+ZCode 经 magpie 网关调 `magicrew-intl/deepseek-v4.1-flash` 整轮失败：
+
+```
+provider_code=403  reason=auth_failed  status=403  retryable=false
+界面显示：token无效
+```
+
+`retryable=false` ⇒ magpie 不换号，错误直接抛给客户端。同一 provider 下其他账号明明还有余额。
+
+### 根因：key 有两条签发路径，本地各存一把、静态挑一把
+
+- `src/hooks/refresh.mjs` —— magpie 的续期，签发后只交给 magpie，**不写** key-store
+- `src/keys.mjs` 的 `ensureKey` —— 请求路径自己续期，写 key-store
+
+两边各存一把；api_key 只活 2 小时，两条路各自什么时候续、续到哪把，本地并不一致。
+静态挑其中一把，踩空就是 403「token无效」。
+
+PR 提交者 2026-10-29 逐把打 `/v1/chat/completions` 实测（5 个国际站账号）：
+
+| 账号 | `auth.access` | store 当前槽 |
+|---|---|---|
+| magicrew-intl | ✅ | ❌ |
+| magicrew-intl#z983c8 | ✅ | ❌ |
+| magicrew-intl#3oqx5z | ❌ | ✅ |
+| magicrew-intl#h2mcxi | ❌ | ✅ |
+| magicrew-intl#8amjca | ❌ | ❌ |
+
+**5 个里 3 个两路状态不一致，方向还各不相同** —— 静态顺序（先 store 或先 auth）都救不了。
+
+⚠ 不要把这条读成「服务端同一账号只认最新签发的那把」—— 2026-10-28 的受控实验
+已经推翻过这个说法：同账号相隔 67 秒签的两把同时有效；12 把逐把探活，403 **全部**
+对应 `expiresAt` 已过。真正的失效原因是**手里那把过期了**，而两条路径让本地不知道
+自己手里的是哪把。逐把试解决的是这个「不知道」。
+
+补一条取证经验：对这种死 key，`GET /v1/models` 是**放行**的，只有 chat 才 403。逐把探活必须用 chat。
+
+### 修法（三处）
+
+1. **`src/keys.mjs` 新增 `keyCandidates()`** —— 同一账号的所有候选 key（store 当前槽 / 另一槽 / `auth.access`），去重后按 `expiresAt` 倒序。到期越晚 = 签发越晚 = 越可能是活着的那把。配套 `adoptKey()` 把命中的那把写回 store。
+
+2. **`src/hooks/loader.mjs` 逐把试 + 全挂改 402** —— `isKeyRejected()` 认两种形态：`HTTP 403`，以及 **`HTTP 200` + `{"code":403,"message":"token无效"}`**（绝大多数是这种，只看状态码会漏）。全部被拒时返回 **402** 而不是 403 —— 402 在 magpie 里是 `failCredit`，会把这个账号 rest 30 分钟、去问下一个账号 / 组的下一个成员，与 0.3.26「积分不足改写 402」同一条通路。SSE 一律不碰。
+
+3. **`src/hooks/refresh.mjs` 收敛到 key-store** —— 改调 `renewViaStore()`，由 store 统一持有 `refresh_token` 并写回新 key，magpie 拿到的是同一把；且与 `ensureKey` 共用 `renewOnce` 锁（按 siteId+account 去重），避免两条路径同时续期、后到的那次用废 token 被误判成「登录已失效」。
+
+### 验证（PR 提交者实测，2026-10-29）
+
+`makeLoader().fetch` 直接喂真实账号（不经过 magpie）：
+
+```
+① store 那把已死 / auth 活的（z983c8） → HTTP 200 ✅
+② 两把都死（8amjca）                  → HTTP 402 + 可读原因（交给 magpie 换号）
+③ auth 已死 / store 活的（h2mcxi）     → HTTP 200 ✅
+```
+
+全账号跑一遍：国际站 5/5 → 200；国内站 `magicrew` / `lky0b4` / `0ok4oa` → 200；`4rm3fp`（积分 -28）→ 402「可用积分已不足」（0.3.26 的改写，正确）。
+
+经网关三条链路 `magicrew/…`、`magicrew-intl/…`、`group/never-stuck` 全部 200。
+
+### 验证（合入后复核，2026-10-29 02:15）
+
+两站各取真实账号（国际 `magicrew-intl#m2orth` / 国内 `magicrew#3wbzad`），隔离 HOME、
+复制真实 key 构造四场景，用 magpie 自带的 bun 直打上游：
+
+| 场景 | 国际站 | 国内站 |
+|---|---|---|
+| A 基线（store 活 + auth 活） | 200 | 200 |
+| B store 死 / auth 活 | 200，且写回 store 另一槽 | 200，且写回 |
+| C store 活 / auth 死 | 200（命中 store 那把，不重写） | 200 |
+| D 三把全死 | 402 + 可读原因 | 402 + 可读原因 |
+
+`tests/key-failover.mjs` 25 条断言把以上全部离线钉死（`node tests/key-failover.mjs` 退出 0）。
+
+### 边界
+
+- 不跨账号借身份：只用**本账号**的 key；本账号全挂就交 402 让 magpie 决定换谁，与 0.3.23 `accountFor()` 的保守立场一致
+- 只有第一把被拒时才会多发请求；命中那把只走 1 次
+
+### 合入时补的五处
+
+1. **`renewViaStore` 会试两处 refresh_token** —— 升级上来的第一次续期，store 那份可能早被旧的 `refresh.mjs` 轮换废了；只认 store 会让用户莫名被要求重新登录。现在 store → `auth.refresh` 依次试，谁活谁写回。
+2. **`adoptKey` 空 store 时保留 `auth.refresh`** —— 首次接管、续期失败但 `auth.access` 还能用时，PR 初版写回 store 会丢掉 refresh_token，2 小时后没人能续。
+3. **`isKeyRejected` 只认业务错误码** —— PR 初版用文本正则，正常回复正文里恰好出现 `unauthorized` / `token无效` 就会被当成 key 拒绝，白白重发（可能重复计费）。现在先 `JSON.parse`，只看 `code` / `message` 字段；有 `choices` 的正常响应绝不判。
+4. **被拒响应的 body 显式取消** —— 逐把试时，每条死连接的响应体不会一直挂着等 GC。
+5. **`refresh.mjs` 不再要求 `auth.refresh` 存在** —— refresh_token 只躺在 key-store 里时（`ensureKey` 续过、magpie 那份已轮换），PR 初版直接 `return undefined`，key 到期就掉登录。
+
 ## 0.3.28 — 2026-10-29
 
 **邮箱验证码登录（内置）· 已有账号不再过旋转图 · 识图模型被 `max_tokens` 饿死的修复**

package/README.md

@@ -31,6 +31,8 @@
 - **积分耗尽自动换号** —— 上游用 HTTP 400 报「可用积分已不足」时，插件把它改写为语义正确的 **402 Payment Required**，magpie 会 rest 这个账号并继续问同 provider 的下一个账号 / 路由组的下一个成员
 - **登录一次管 30 天** —— 网页 JWT 顶 30 天，`mgw_` api_key 每 2 小时自续，refresh_token 每次续期时自滚
 - **新手奖励 8 项全自动** —— 国内站 8 项 500 积分全部拿得到；第 8 项（完成第一次 AI 工作）由插件替你发一条消息，花掉约 2 积分
+- **默认开启自动签到** —— 安装后自动把本 provider 的插件签到设为开（`pluginCheckins` 缺省时补 true；你手动关掉的不会被改回）
+- **自动更新** —— 复用 magpie 的插件更新机制：发现自己的新版本后调 `magpie plugin update`，并在成功后写「已自动更新」记录；更新完要重启一次 magpie 才会加载新代码
 - **邀请码自动滚** —— 第一次注册带作者的码，之后每次登录都记住「上一个登录账号」的码，拿到新的就覆盖旧的
 
 ---

package/docs/internals.md

@@ -822,7 +822,7 @@ store  槽 a    expires 2026-10-28T14:41:03.000Z   → 200
 不管吊销机制是什么，**只留一把、只有一个出口**这个设计依然成立 ——
 理由从「否则互相吊销」改成「否则本地会分叉，说不清手里那把是不是服务端认的」。
 
-### 保活链路（2026-10-27 逐版本核对后的实况）
+### 保活链路（0.3.29 起；2026-10-29 逐版本核对）
 
 ```
 每次请求前   ensureKey(c, getAuth)          ← src/hooks/loader.mjs
@@ -831,13 +831,40 @@ store  槽 a    expires 2026-10-28T14:41:03.000Z   → 200
                             ├─ 有 refresh_token → PUT 换新的 → 覆盖落盘
                             └─ 没有 / 失败     → 退回 magpie 存的那把
 
+             keyCandidates(c, auth)        ← 同一账号的 store 两槽 + auth.access
+               └─ 逐把打 /v1/chat/completions；被拒换下一把，命中写回 store（adoptKey）
+
 到期前 10 分钟 auth.refresh(auth)           ← magpie 按 refreshLead 主动调度
-               └─ src/hooks/refresh.mjs 直接调 api.refreshGatewayKey(auth.refresh)
-                  ⚠ 不经过 keys.mjs，也不读 key-store
+               └─ src/hooks/refresh.mjs → keys.mjs 的 renewViaStore()
+                  与 ensureKey 共用 renewOnce 锁和同一个 key-store；
+                  refresh_token 先试 store 那份、再试 magpie 那份（升级兼容）
 
 每天一次     checkin → runCheckin()         ← 领积分 / 补首任务 / 新手福利，**不碰 key**
 ```
 
+⚠ 0.3.29 之前 refresh.mjs 自己调 `api.refreshGatewayKey(auth.refresh)`、不写 key-store：
+两条签发路径各存一把 key，而 key 只活 2 小时，两条路各自续到哪把、哪把已经过期，
+本地并不一致。2026-10-29 实测 5 个国际站账号里 3 个「静态挑一把」踩空，表现是
+403 `token无效` 且 `retryable=false`（magpie 不换号，整轮直接抛给客户端）。
+`keyCandidates()` 的逐把试与 `renewViaStore()` 的收敛就是为这两条路分别兜底。
+
+⚠ 别把这里读成「服务端同一账号只认最新签发的那把」—— 2026-10-28 的受控实验
+已经推翻过：同账号相隔 67 秒签的两把同时有效；12 把逐把探活，403 全部对应
+`expiresAt` 已过。真正失效的是**手里那把过期了**，不是后来签的把它顶掉了。
+
+### 自动维护（0.3.30 起）
+
+插件有两个 magpie 没替它做的事，都在 `src/auto-maintenance.mjs`：
+
+| 能力 | magpie 的现状 | 插件怎么补 |
+|---|---|---|
+| 默认开启签到 | `PluginCheckinOn()`：`pluginCheckins` 无显式值时默认 **false**（只有 WorkBuddy / Trae / MiniMax / Qoder 有内置开关） | 插件加载时读 `~/.config/magpie/settings.json`，只在键不存在时补 true；用户显式 false 不覆盖 |
+| 插件自身自动更新 | `Official()` 只认 `@magpie-community/*`；第三方 git / npm 源只提示、不自动装 | 读 `plugin-updates.json` 的 `waiting`；有自己就调 `magpie plugin update`；成功后补 `updated[]`（「已自动更新」徽章读它） |
+
+⚠ GUI 的 `/api/...` 不在 gateway 端口 3425 上（那里是 `/v1`，`/api/plugins/updates`
+会回 `/v1` 的 404 文案）；插件拿不到桌面 WebView 的 API，所以只能走文件 + CLI。
+⚠ `magpie plugin update` 不重启运行中的 magpie：更新文件后要下次启动才加载新代码。
+
 ### checkin 现在做四件事（0.3.11 起）
 
 ```

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "magicrew-auth",
-  "version": "0.3.28",
+  "version": "0.3.30",
   "description": "超级麦吉 / MagiCrew for magpie and OpenCode — one package, two providers: letsmagic.cn (国内) and magicrew.ai (international). Password or web-JWT sign-in, the account's own live model list, points balance, newcomer rewards, invite codes.",
   "type": "module",
   "main": "./index.mjs",

package/src/auto-maintenance.mjs

@@ -0,0 +1,253 @@
+// 自动维护 —— 「默认开启签到」与「插件自身自动更新」
+//
+// 这两个能力本质上都踩在 magpie 的边界上，先把边界说清楚：
+//
+// ① 签到：magpie 的 `pluginCheckins`（设置 → 插件签到）**默认是关的**
+//    （`PluginCheckinOn()`：没有显式值时跟随厂商内置开关，magicrew 没有内置
+//    开关，于是 false）。插件没有官方 API 能声明的默认值，只能在插件加载时
+//    读 `~/.config/magpie/settings.json`：**只有这个 provider 从未被用户设置过**
+//    才补一个 true。用户显式关掉的，绝不覆盖。
+//
+// ② 自动更新：magpie 只对 `@magpie-community/*` 的包自动更新
+//    （`plugin.Official()` 硬编码这个前缀），git 源的第三方插件永远只提示、
+//    等用户点「更新」。我们不在那个 scope 里，所以只能由插件自己复刻这套
+//    机制：读 magpie 写好的 `plugin-updates.json`，确认「有我自己」之后调用
+//    magpie 的 CLI（`magpie plugin update`）——它会把插件目录更新到最新；
+//    成功后在 `plugin-updates.json` 的 `updated[]` 里补一条，magpie 的
+//    「已自动更新」徽章读的就是这个记录（`plugin.LastUpdated()`）。
+//
+// ⚠ 边界（都是实测/源码结论，别想当然）：
+//   · 插件进程拿不到 GUI 的 HTTP 端口 —— `MAGPIE_ADDR` 指向 3425，那是
+//     **gateway**（`/api/plugins/updates` 在那里会回 `/v1` 的 404 文案），
+//     GUI API 走的是桌面窗口自己的 WebView，不是 TCP 端口。
+//   · `magpie plugin update` 是 CLI 进程内的 `plugin.Update()`，会更新
+//     **所有** 非路径插件并重装；它不会重启正在运行的 magpie，所以更新后
+//     要等 magpie 下次启动才加载新代码。这是这个兜底能做到的极限。
+//   · 找不到 magpie 可执行文件时只记录 `no-magpie-exe`，不伪造徽章、不硬编码
+//     本机路径。可以设环境变量 `MAGPIE_EXE` 明示。
+//
+// 两个动作都是**尽力而为**：失败不抛、不拖慢签到/额度/登录。
+
+import { readFileSync, writeFileSync, renameSync, mkdirSync, existsSync, copyFileSync } from "node:fs"
+import { homedir } from "node:os"
+import { join, dirname, basename } from "node:path"
+import { execFileSync, spawn } from "node:child_process"
+
+const PKG_NAME = "Magicrew"
+const AUTO_DIR = () => join(homedir(), ".config", "magpie")
+const CACHE_DIR = () => join(homedir(), ".cache", "magpie")
+const THROTTLE_MS = 6 * 3600_000 // 同一次更新失败后，6 小时内不再试
+
+function readJson(path, fallback) {
+  try {
+    return JSON.parse(readFileSync(path, "utf8"))
+  } catch {
+    return fallback
+  }
+}
+
+/** 原子写：先写同目录临时文件再 rename，避免把 magpie 的 JSON 写半截 */
+function writeJsonAtomic(path, value, { backup = false } = {}) {
+  mkdirSync(dirname(path), { recursive: true })
+  if (backup && existsSync(path)) {
+    try {
+      writeFileSync(path + ".bak-magicrew-auto", readFileSync(path))
+    } catch {}
+  }
+  const tmp = `${path}.tmp-${process.pid}-${Date.now()}`
+  writeFileSync(tmp, JSON.stringify(value, null, 2) + "\n")
+  renameSync(tmp, path)
+}
+
+/** 这个 provider 的签到是否从未被用户设置过；是就补 true（并返回 changed） */
+export function ensureCheckinDefault(provider, { dir = AUTO_DIR() } = {}) {
+  const file = join(dir, "settings.json")
+  let s
+  if (existsSync(file)) {
+    s = readJson(file, null)
+    // 文件在但读不出来：绝不覆盖用户的设置
+    if (!s || typeof s !== "object" || Array.isArray(s)) return { changed: false, reason: "settings-unreadable" }
+  } else {
+    s = {}
+  }
+  const table = s.pluginCheckins && typeof s.pluginCheckins === "object" && !Array.isArray(s.pluginCheckins)
+    ? s.pluginCheckins
+    : {}
+  if (Object.hasOwn(table, provider)) return { changed: false, reason: "explicit", on: table[provider] === true }
+  s.pluginCheckins = { ...table, [provider]: true }
+  writeJsonAtomic(file, s, { backup: true })
+  return { changed: true, on: true }
+}
+
+/** magpie 的 waiting 里有没有「我自己」的新版本（git 源只有 commit，没有 npm version） */
+export function pickSelfUpdate(waiting, { pkg = PKG_NAME } = {}) {
+  if (!Array.isArray(waiting)) return null
+  return waiting.find((w) => w && w.package === pkg && w.git === true) || null
+}
+
+/** 补一条「自动更新记录」—— magpie 的「已自动更新」徽章读 plugin-updates.json 的 updated[] */
+export function noteUpdated(pkg, from, to, { dir = AUTO_DIR(), now = new Date() } = {}) {
+  const file = join(dir, "plugin-updates.json")
+  const u = readJson(file, null)
+  if (!u || typeof u !== "object" || Array.isArray(u)) return false
+  u.updated = Array.isArray(u.updated) ? u.updated : []
+  const last = u.updated[u.updated.length - 1]
+  // 同一次更新重复写会让徽章的计时一直刷新；24 小时内同 from/to 只记一次
+  if (last && last.package === pkg && last.from === from && last.to === to) {
+    const at = Date.parse(last.at)
+    if (Number.isFinite(at) && now.getTime() - at < 24 * 3600_000) return true
+  }
+  u.updated.push({ package: pkg, from, to, at: now.toISOString() })
+  if (u.updated.length > 20) u.updated = u.updated.slice(-20)
+  writeJsonAtomic(file, u, { backup: true })
+  return true
+}
+
+/** 自动更新的节流状态（每个站点一份） */
+export function readAutoState(site, { cacheDir = CACHE_DIR() } = {}) {
+  return readJson(join(cacheDir, `magicrew-auto-${site}.json`), {}) || {}
+}
+
+function writeAutoState(site, state, { cacheDir = CACHE_DIR() } = {}) {
+  try {
+    writeJsonAtomic(join(cacheDir, `magicrew-auto-${site}.json`), state)
+  } catch {}
+}
+
+/**
+ * 找本机 magpie 可执行文件。顺序：
+ *   1. 环境变量 MAGPIE_EXE（最可靠，给测试和自定义安装用）
+ *   2. 祖父进程：插件跑在 magpie-bun.exe 里，它的父进程就是 magpie 主程序
+ *   3. PATH 里的 magpie / magpie.exe / magpie-windows-amd64.exe
+ * 找不到返回 ""
+ */
+export function findMagpieExe({ env = process.env, ppid = process.ppid, platform = process.platform } = {}) {
+  const resolve = (p) => {
+    if (!p || !existsSync(p)) return ""
+    // magpie 的 `magpie.cmd` 只是同目录 exe 的包装（Settings 的 Command line
+    // 会生成它）；spawn 一个 .cmd 在 Windows 上还要 shell，直接解析到 exe。
+    if (/\.(cmd|bat)$/i.test(p)) {
+      for (const n of ["magpie-windows-amd64.exe", "magpie.exe"]) {
+        const q = join(dirname(p), n)
+        if (existsSync(q)) return q
+      }
+    }
+    return p
+  }
+  if (env.MAGPIE_EXE) {
+    const p = resolve(env.MAGPIE_EXE)
+    if (p) return p
+  }
+  const exists = (p) => !!resolve(p)
+  const tryExec = (cmd, args, timeout = 2500) => {
+    try {
+      return execFileSync(cmd, args, {
+        encoding: "utf8",
+        timeout,
+        windowsHide: true,
+        stdio: ["ignore", "pipe", "ignore"],
+      }).trim()
+    } catch {
+      return ""
+    }
+  }
+  if (platform === "win32") {
+    const ps = [
+      "$p = Get-CimInstance Win32_Process -Filter \"ProcessId=" + Number(ppid) + "\"",
+      "if ($p) { $q = Get-CimInstance Win32_Process -Filter \"ProcessId=$($p.ParentProcessId)\"; if ($q) { $q.ExecutablePath } }",
+    ].join("; ")
+    const out = tryExec("powershell.exe", ["-NoProfile", "-Command", ps])
+    // 只认名字里带 magpie 的进程 —— 测试/宿主不在 magpie 下时，
+    // 父进程可能是 bash / node，不能把它们的路径当 magpie
+    if (exists(out) && /magpie/i.test(basename(out))) return resolve(out)
+  } else {
+    const out = tryExec("ps", ["-p", String(ppid), "-o", "ppid="])
+    const grand = out.split(/\s+/)[0]
+    if (grand) {
+      const path = tryExec("ps", ["-p", grand, "-o", "comm="])
+      if (exists(path) && /magpie/i.test(basename(path))) return resolve(path)
+    }
+  }
+  for (const name of ["magpie-windows-amd64.exe", "magpie.exe", "magpie"]) {
+    const lines = tryExec(platform === "win32" ? "where.exe" : "which", [name], 1500).split(/\r?\n/)
+    for (const line of lines) {
+      const p = line.trim()
+      if (exists(p) && /magpie/i.test(basename(p))) return resolve(p)
+    }
+  }
+  return ""
+}
+
+/**
+ * 检查并（尽力）自动更新。
+ * @param {{id:string}} c 站点上下文（用 c.id 存节流状态）
+ * @param {{dir?:string, cacheDir?:string, pkg?:string, exe?:string, dryRun?:boolean, spawnFn?:Function}} opts
+ * @returns {Promise<object>} 结果只用于日志/测试，不抛
+ */
+export async function kick(c, opts = {}) {
+  const dir = opts.dir || AUTO_DIR()
+  const cacheDir = opts.cacheDir || CACHE_DIR()
+  const pkg = opts.pkg || PKG_NAME
+  try {
+    const updates = readJson(join(dir, "plugin-updates.json"), null)
+    const waiting = pickSelfUpdate(updates?.waiting, { pkg })
+    if (!waiting) return { skipped: "no-update" }
+
+    const state = readAutoState(c.id, { cacheDir })
+    const now = Date.now()
+    if (state.done && state.done.to === waiting.latest) return { skipped: "done" }
+    if (state.lastAttempt && state.latest === waiting.latest && now - state.lastAttempt < THROTTLE_MS) {
+      return { skipped: "throttled" }
+    }
+
+    const exe = opts.exe !== undefined ? opts.exe : findMagpieExe(opts)
+    if (!exe) {
+      writeAutoState(c.id, { ...state, lastAttempt: now, latest: waiting.latest, reason: "no-magpie-exe" }, { cacheDir })
+      return { skipped: "no-magpie-exe", waiting }
+    }
+    if (opts.dryRun) return { wouldRun: exe, waiting }
+
+    let child
+    try {
+      child = (opts.spawnFn || spawn)(exe, ["plugin", "update"], {
+        detached: true,
+        stdio: "ignore",
+        windowsHide: true,
+        env: process.env,
+      })
+    } catch (e) {
+      writeAutoState(c.id, { ...state, lastAttempt: now, latest: waiting.latest, reason: String(e?.message ?? e) }, { cacheDir })
+      return { skipped: "spawn-failed", error: String(e?.message ?? e) }
+    }
+    child.on?.("exit", (code) => {
+      if (code === 0) {
+        noteUpdated(pkg, waiting.version, waiting.latest, { dir })
+        writeAutoState(c.id, {
+          ...state,
+          lastAttempt: now,
+          latest: waiting.latest,
+          done: { from: waiting.version, to: waiting.latest, at: new Date().toISOString() },
+        }, { cacheDir })
+      } else {
+        writeAutoState(c.id, { ...state, lastAttempt: now, latest: waiting.latest, reason: `exit-${code}` }, { cacheDir })
+      }
+    })
+    child.unref?.()
+    return { started: true, waiting }
+  } catch (e) {
+    return { skipped: "error", error: String(e?.message ?? e) }
+  }
+}
+
+/** 插件加载时的初始化：补默认签到 + 延迟检查更新（不阻塞 config） */
+export function initAutoMaintenance(c) {
+  try {
+    ensureCheckinDefault(c.PROVIDER)
+  } catch {}
+  try {
+    const t = setTimeout(() => {
+      kick(c).catch(() => {})
+    }, 15_000)
+    t.unref?.()
+  } catch {}
+}

package/src/hooks/checkin.mjs

@@ -8,6 +8,7 @@
 // 签到逻辑在独立模块里**按需加载**：它挂了，登录/模型/额度照常工作。
 
 import { rollInvite } from "../store.mjs"
+import { kick } from "../auto-maintenance.mjs"
 
 export function makeCheckin(c) {
   return async (getAuth) => {
@@ -20,7 +21,12 @@ export function makeCheckin(c) {
       // rollInvite 内部自带超时和 try/catch，失败不影响签到。
       await rollInvite(c.id, auth.jwt, auth.org, c.host)
       const { runCheckin } = await import("../tasks.mjs")
-      return await runCheckin({ ...auth, host: c.host })
+      const result = await runCheckin({ ...auth, host: c.host })
+      // 签到成功后再给自动更新一次机会（config 启动时已试过一次；
+      // 这里覆盖「magpie 长期不重启」的情况）。kick 自己有 6 小时节流，
+      // 且不阻塞签到结果。
+      kick(c).catch(() => {})
+      return result
     } catch (e) {
       return { outcome: "failed", message: String(e?.message ?? e) }
     }

package/src/hooks/config.mjs

@@ -5,13 +5,19 @@
 // ⚠ 三条不许改：
 //   · 用 ??= 不用 =，否则覆盖用户在 plugins.json 里手配的值
 //   · models 必须有内容 —— 未登录也要有，空表会让卡片显示 "0 models"
-//   · 不要在这里发网络请求：它是配置，不是钩子
+//   · 不要在这里发**业务**网络请求：它是配置，不是钩子（本地默认设置与
+//     延迟的自动维护见 src/auto-maintenance.mjs，失败不影响 config）
 
 import { SDK } from "../context.mjs"
 import { readSnapshot } from "../store.mjs"
+import { initAutoMaintenance } from "../auto-maintenance.mjs"
 
 export function makeConfig(c) {
   return async (cfg) => {
+    // 默认开启本 provider 的签到；并在后台检查插件自身更新。
+    // 两者都尽力而为，失败不影响 config（见 src/auto-maintenance.mjs 的边界说明）。
+    initAutoMaintenance(c)
+
     cfg.provider ??= {}
     cfg.provider[c.PROVIDER] ??= {
       name: c.SHORT,

package/src/hooks/loader.mjs

@@ -14,7 +14,45 @@
 // ⚠ 不要在这里读流、不要手拼 x-api-key ——
 //   流由 magpie 处理，头由 SDK 包自动加。见 README「最小交付面」。
 
-import { ensureKey, accountOf } from "../keys.mjs"
+import { ensureKey, accountOf, keyCandidates, adoptKey } from "../keys.mjs"
+
+/**
+ * 上游「这个账号不行」的两种形态（2026-10-29 实测）：
+ *
+ *   · HTTP 403
+ *   · **HTTP 200 + `{"code":403,"message":"token无效"}`**  ← 绝大多数是这种
+ *
+ * 所以光看状态码会漏。只解析 JSON（SSE 一律不碰，读流会破坏它）。
+ */
+async function isKeyRejected(res) {
+  if (!res) return false
+  if (res.status === 401 || res.status === 403) return true
+  const ct = res.headers.get("content-type") || ""
+  if (res.status !== 200 || !ct.includes("application/json")) return false
+  let text = ""
+  try {
+    text = await res.clone().text()
+  } catch {
+    return false
+  }
+  if (text.length > 8192) return false
+  let body
+  try {
+    body = JSON.parse(text)
+  } catch {
+    return false
+  }
+  // 只认**业务错误码**。正常 chat 完成的 JSON 是 {choices:[…]}，没有顶层 code；
+  // 用文本正则会把模型回复里恰好出现的 "unauthorized" 当成 key 拒绝 ——
+  // 那会白白重发请求（可能重复计费），甚至最后把正常响应丢掉换成 402。
+  const code = Number(body?.code ?? body?.error?.code)
+  if (code === 401 || code === 403) return true
+  const msg = String(body?.message ?? body?.error?.message ?? "")
+  if (!msg) return false
+  if (/token无效|token 无效|invalid token/i.test(msg)) return true
+  // 兜底：只有 message、没有 code 的少量形态；有 choices 的正常响应绝不判
+  return !Array.isArray(body?.choices) && /unauthorized/i.test(msg)
+}
 
 /**
  * 把 JSON Schema 里的 `additionalProperties` **非布尔值**原地换成 `true`。
@@ -447,6 +485,8 @@ export async function rewriteCreditRefusal(res) {
 }
 
 export function makeLoader(c) {
+  /** 已经写回 store 的 key —— 避免每个请求都去读一次 store */
+  const adopted = new Set()
   return async (getAuth) => {
     const auth = await getAuth()
     if (!auth) return {}
@@ -489,12 +529,60 @@ export function makeLoader(c) {
         // 四处请求体改写，全在 rewriteRequestBody 里（那里有实测出处）
         body = rewriteRequestBody(body)
 
-        return rewriteCreditRefusal(await fetch(url, {
-          method: init?.method ?? "POST",
-          headers,
-          body,
-          signal: init?.signal ?? req?.signal ?? AbortSignal.timeout(300_000),
-        }))
+        const signal = init?.signal ?? req?.signal ?? AbortSignal.timeout(300_000)
+        const sendWith = (apiKey) =>
+          fetch(url, {
+            method: init?.method ?? "POST",
+            headers: { ...headers, authorization: `Bearer ${apiKey}` },
+            body,
+            signal,
+          })
+
+        // 同一账号可能握着两把 key（magpie 的 refresh 一条、插件 store 一条），
+        // 哪把还有效本地无法预判 —— 静态挑必然有一半踩空，只能逐把试。
+        // 详见 src/keys.mjs 的 keyCandidates 注释（2026-10-29 五个账号的实测表）。
+        // 传 fresh 而不是 getAuth：候选与下面 adoptKey 必须落在同一个账号上，
+        // 不能让两次 getAuth() 返回不同结果。
+        const cands = await keyCandidates(c, fresh)
+        if (!cands.length) throw new Error(`${c.SHORT} 未登录（拿不到可用的 key）`)
+
+        for (const cand of cands) {
+          const res = await sendWith(cand.apiKey)
+          if (!(await isKeyRejected(res))) {
+            // 这把能用 —— 写回 store，让 ensureKey / 额度那几路也用同一把
+            if (!adopted.has(cand.apiKey)) {
+              adopted.add(cand.apiKey)
+              adoptKey(c, fresh, cand.apiKey, cand.expiresAt)
+            }
+            return rewriteCreditRefusal(res)
+          }
+          // 这把被拒：响应不再使用，显式取消 body —— 否则逐把试时
+          // 每条死连接的响应体都挂着，等 GC 才释放。
+          try {
+            await res.body?.cancel()
+          } catch {}
+        }
+
+        // 这个账号的 key 全被拒。上游给的是 403「token无效」，magpie 会判成
+        // 「不可重试」直接抛给客户端（ZCode 显示 auth_failed / token无效）。
+        // 改写成 402：magpie 的 failure(402) 是 failCredit → 把这个账号 rest 掉、
+        // 去问下一个账号 / 组的下一个成员。与 0.3.26 的「积分不足」同一条通路。
+        return new Response(
+          JSON.stringify({
+            error: {
+              message:
+                `${c.SHORT}：本账号的 ${cands.length} 把密钥均已被上游拒绝，已交给 magpie 换下一个账号。` +
+                `（常见于登录 / 续期分叉；请重新登录这个账号）`,
+              type: "account_unavailable",
+              code: 402,
+            },
+          }),
+          {
+            status: 402,
+            statusText: "Payment Required",
+            headers: { "content-type": "application/json" },
+          },
+        )
       },
     }
   }

package/src/hooks/refresh.mjs

@@ -3,24 +3,31 @@
 // magpie 在 api_key 到期前（refreshLead）调一次，**返回的字段合并进旧账号**，
 // 不是整体替换（client.auth.set 才是替换，两者不同）。
 //
-// ⚠ 一次性 refresh_token 必须串行 —— magpie 已按账号串行化，插件里别再并发；
+// ⚠ 一次性 refresh_token 必须串行 —— magpie 已按账号串行化；插件里
+//   renewViaStore 与 ensureKey 共用 renewOnce 的同一把锁，也不会并发。
 //   服务端每次换完会轮换，必须用返回的新值。
 
-import { refreshGatewayKey } from "../api.mjs"
+import { renewViaStore } from "../keys.mjs"
 
 export function makeRefresh(c) {
   return async (auth) => {
-    if (!auth?.refresh) return undefined
+    // 不要求 auth.refresh 存在：refresh_token 可能只躺在 key-store 里
+    //（0.3.29 之前 ensureKey 续过、magpie 那份已经轮换废了）。由 renewViaStore
+    // 两处都试，这里先别把它挡掉。
+    if (!auth) return undefined
     try {
-      const k = await refreshGatewayKey(auth.refresh, c.host)
+      // ⚠ 必须走 store —— 由它统一持有 refresh_token 并把新 key 写回。
+      //   自己再调一次 refreshGatewayKey 会让两条路径各存一把，
+      //   哪把还有效本地无法预判，请求侧就会 403「token无效」（2026-10-29 实测）。
+      const k = await renewViaStore(c, auth)
       return {
         access: k.apiKey,
-        // 服务端每次 PUT 都轮换 refresh_token，必须用新的
+        // 服务端每次换完都轮换 refresh_token，必须用返回的新值
         refresh: k.refreshToken ?? auth.refresh,
-        expires: Date.now() + 2 * 3600_000,
+        expires: k.expiresAt || Date.now() + 2 * 3600_000,
       }
     } catch (e) {
-      if (/invalid|expired|401|403/i.test(String(e?.message))) {
+      if (/invalid|expired|401|403|token/i.test(String(e?.message))) {
         throw Object.assign(new Error("登录已失效，请重新登录"), { signIn: "expired" })
       }
       throw e

package/src/hooks/usage.mjs

@@ -25,13 +25,23 @@
 // 宿主支持余额之前的临时协议，见 CHANGELOG 0.3.20。
 
 import { fetchPoints, SITES } from "../api.mjs"
+import { ensureCheckinDefault } from "../auto-maintenance.mjs"
 
 // 每日登录积分：国内 +200/天、国际 +50/天（实测，见 docs/internals.md）。
 // 今日批次的分母，只用于展示「今日还剩 / 今日额度」。
 const DAILY_LOGIN_GIFT = { cn: 200, intl: 50 }
 
 export function makeUsage(c) {
+  let ensuredCheckin = false
   return async (getAuth) => {
+    // config 已经补过默认签到；这里再兜一次 —— magpie 启动时可能先
+    // Save 了内存里的旧 settings，把 config 那次覆盖掉。只补「从未设置过」的。
+    if (!ensuredCheckin) {
+      ensuredCheckin = true
+      try {
+        ensureCheckinDefault(c.PROVIDER)
+      } catch {}
+    }
     const auth = await getAuth()
     if (!auth) return { error: "未登录", windows: [] }
     try {

package/src/keys.mjs

@@ -2,21 +2,16 @@
 //
 //   登录成功  → issueAndStore()  签一把放进「另一个槽」，切过去
 //   loader    → ensureKey()      快过期就把新的签到另一个槽，切过去；旧的留着当回退
-//   refresh   → ⚠ **不经过本模块**。src/hooks/refresh.mjs 自己调
-//               api.refreshGatewayKey(auth.refresh)，magpie 拿到的不是这一把。
+//   refresh   → renewViaStore()  续期、写回 store；magpie 拿到的就是 store 里这一把
 //
 // **每个账号一套槽，互不干扰** —— 同站点登两个账号时，第二个人登录不会碰第一个人的 key。
 // 账号标识用 `org`（组织码），拿不到才退回 accountId。
 //
-// ⚠ 上面那条 refresh 是「唯一出口」这个设计里**唯一没落地的口子**（2026-10-27 核对）：
-//   refresh_token 是一次性轮换的，两条路径各用各的那份会分叉 ——
-//   ensureKey 轮换后 store 里是新值，refresh.mjs 手里 magpie 的还是旧值，
-//   再调就是 401 → magpie 判定「登录已失效」→ 让用户重新登录。
-//
-//   目前不会触发，因为 **store 从来没被写过**（本机 magicrew-key-*.json 一个都没有，
-//   说明 ensureKey 从没执行过 —— 没发过模型请求）。但这意味着：
-//   **若将来要给 checkin 补 ensureKey，必须先把这个钩子也收敛进来**，
-//   否则就是亲手把「一条路」掰成两条，用「多写一句文档」换「用户莫名掉登录」。
+// ⚠ refresh 这条口子曾经是「唯一出口」设计里唯一没落地的地方（2026-10-27 核对）：
+//   refresh.mjs 自己调 api.refreshGatewayKey(auth.refresh)，拿到的 key 只交给 magpie，
+//   与 store 各存一份 —— refresh_token 一次性轮换，两条路径必然分叉。
+//   0.3.29（PR #12）起已收敛到 renewViaStore()：与 ensureKey 共用 renewOnce 锁和
+//   同一个 key-store，refresh_token 也只从这里轮换出去。
 
 import { issueGatewayKey, refreshGatewayKey } from "./api.mjs"
 import {
@@ -84,6 +79,150 @@ export function accountFor(c, auth) {
   return direct
 }
 
+/**
+ * 这个账号**所有**可能能用的 key，按到期时间从晚到早排。
+ *
+ * 为什么需要「多把」：key 有两条签发路径 —— magpie 的 `auth.refresh` 一条
+ * （src/hooks/refresh.mjs）、本模块的 `ensureKey` 一条，两边各写各的。
+ * api_key 只活 2 小时，两条路各自什么时候续、续到哪把，本地并不一致 ——
+ * 静态「只挑一把」必然有一半概率踩空。
+ *
+ * 2026-10-29 实测（5 个国际站账号，逐把打 /v1/chat/completions）：
+ *
+ *   magicrew-intl          auth.access ✅   store 槽 b ❌
+ *   magicrew-intl#z983c8   auth.access ✅   store 槽 b ❌
+ *   magicrew-intl#3oqx5z   auth.access ❌   store 槽 a ✅
+ *   magicrew-intl#h2mcxi   auth.access ❌   store 槽 b ✅
+ *   magicrew-intl#8amjca   auth.access ❌   store 槽 a ❌  ← 两把都死
+ *
+ * **5 个里 3 个两路状态不一致，方向还各不相同** —— 先 store 或先 auth 都救不了。
+ *
+ * ⚠ 不要读成「服务端同一账号只认最新签发的那把」。2026-10-28 的受控实验已经
+ * 推翻过这个说法：同账号相隔 67 秒签的两把同时有效；12 把逐把探活，403 全部
+ * 对应 `expiresAt` 已过。真正的原因是**手里那把过期了**，而两条路径让本地
+ * 不知道自己手里的是哪把。逐把试解决的就是这个「不知道」。
+ *
+ * 到期越晚 = 签发越晚 = 越可能是活着的那把，所以按 expiresAt 倒序试。
+ *
+ * @param {object} c               站点上下文
+ * @param {Function|object} getAuth magpie 的取账号函数，或直接给 auth 对象
+ */
+export async function keyCandidates(c, getAuth) {
+  let auth = null
+  try {
+    auth = typeof getAuth === "function" ? await getAuth() : getAuth
+  } catch {}
+  const account = accountFor(c, auth)
+  const st = readStore(c.id, account)
+
+  const out = []
+  const byKey = new Map()
+  const add = (k) => {
+    if (!k?.apiKey) return
+    const rec = { apiKey: k.apiKey, expiresAt: Number(k.expiresAt) || 0 }
+    const prev = byKey.get(rec.apiKey)
+    if (prev) {
+      // 同一把 key 从两路拿到时，保留更晚的到期时间 —— 否则可能被排到死 key 后面
+      if (rec.expiresAt > prev.expiresAt) prev.expiresAt = rec.expiresAt
+      return
+    }
+    byKey.set(rec.apiKey, rec)
+    out.push(rec)
+  }
+  add(currentKey(st))
+  add(st?.keys?.[otherSlot(st.current)])
+  if (auth?.access) add({ apiKey: auth.access, expiresAt: Number(auth.expires) || 0 })
+
+  return out.sort((a, b) => Number(b.expiresAt || 0) - Number(a.expiresAt || 0))
+}
+
+/** 把实测能用的那把写回 store —— 下次直接命中，不再逐把试错 */
+export function adoptKey(c, auth, apiKey, expiresAt) {
+  try {
+    const account = accountFor(c, auth)
+    const st = readStore(c.id, account)
+    if (currentKey(st)?.apiKey === apiKey) return
+    const slot = otherSlot(st.current)
+    writeStore(c.id, account, {
+      current: slot,
+      // 空 store 首次接管时 refresh_token 只在 magpie 手里 —— 这里必须接住，
+      // 否则 2 小时后没人能续，用户被要求重新登录。
+      refreshToken: st.refreshToken || auth?.refresh || "",
+      keys: { ...st.keys, [slot]: { apiKey, expiresAt: Number(expiresAt) || 0 } },
+      at: st.at,
+    })
+  } catch {}
+}
+
+/**
+ * 续期并**写回 store** —— 给 src/hooks/refresh.mjs 用。
+ *
+ * 收敛成一条路径的原因：refresh.mjs 原来自己调 `refreshGatewayKey`，
+ * 拿到的 key 只交给 magpie，插件 store 里还是旧的。两条路径各存一份，
+ * 哪把是新签的、哪把已经过期，本地说不清 —— 2026-10-29 实测 5 个账号里
+ * 3 个两路状态不一致，就是这么来的。
+ *
+ * ⚠ refresh_token 是一次性的：谁续谁负责写回，不能让两边各存各的。
+ */
+export async function renewViaStore(c, auth) {
+  const account = accountFor(c, auth)
+
+  // 与 ensureKey 共用同一把锁（renewOnce 按 siteId+account 去重）——
+  // refresh_token 一次性，两条路径同时续期会让后到的那次用废 token → 误判掉登录。
+  let err = null
+  const rec = await renewOnce(c.id, account, async () => {
+    try {
+      const st = readStore(c.id, account)
+
+      // refresh_token 也可能有两份：store 里的（ensureKey 续过）与 magpie 手里的
+      // （0.3.29 之前的 refresh.mjs 续过）。两把都是一次性，只有一把还活着 ——
+      // 升级上来的第一次尤其：store 那份可能早被轮换废了，auth.refresh 才是活的。
+      const tokens = []
+      const seen = new Set()
+      for (const t of [st.refreshToken, auth?.refresh]) {
+        if (!t || seen.has(t)) continue
+        seen.add(t)
+        tokens.push(t)
+      }
+      if (!tokens.length) throw new Error("没有 refresh_token")
+
+      let lastErr = null
+      for (const refreshToken of tokens) {
+        try {
+          const k = await refreshGatewayKey(refreshToken, c.host)
+          const next = { apiKey: k.apiKey, expiresAt: toEpochMs(k.apiKeyExpiresAt) }
+          const slot = otherSlot(st.current)
+          const nextRefresh = k.refreshToken || refreshToken
+          writeStore(c.id, account, {
+            current: slot,
+            refreshToken: nextRefresh,
+            keys: { ...st.keys, [slot]: next },
+            at: st.at,
+          })
+          return { ...next, refreshToken: nextRefresh }
+        } catch (e) {
+          lastErr = e
+        }
+      }
+      throw lastErr ?? new Error("续期失败")
+    } catch (e) {
+      err = e
+      throw e
+    }
+  })
+
+  if (!rec) throw err ?? new Error("续期失败")
+  // 并发时可能复用 ensureKey 的 rec（它只返回 apiKey/expiresAt）——
+  // 从 store 补上最新 refresh_token，免得 magpie 那份落后一轮。
+  if (!rec.refreshToken) {
+    try {
+      const st2 = readStore(c.id, account)
+      if (st2.refreshToken) rec.refreshToken = st2.refreshToken
+    } catch {}
+  }
+  return rec
+}
+
 /**
  * 拿到这个账号一把能用的 key。**永不抛** —— 续不上就交出手里那把（哪怕不新鲜），
  * 让请求自己去撞上游的错误，比在这里抛更能说明问题。