magicrew-auth 0.3.16 → 0.3.23

package/AGENTS.md

@@ -8,6 +8,27 @@
 
 ---
 
+## 零、magpie 升级时：只看稳定版
+
+**判断「要不要跟着 magpie 改这个插件」看稳定渠道，不看每版本渠道。**
+magpie 设置里有「更新渠道：每个版本 / 稳定版」，用户默认跑后者，插件要跟的也是后者。
+
+```bash
+curl -s "https://usemagpie.ai/api/latest?channel=stable" | grep -o '"version":"[^"]*"'
+```
+
+实测（2026-10-28）：两档差 **400 多个版本**（每版本 0.1.1763 / 稳定版 0.1.1327），
+但把两边内嵌契约都提取出来逐字段比对后 —— **插件相关的字段一条不差**。
+多出来的段是 GUI 历史，不是插件契约。⇒ 追每版本几乎全是白跑。
+
+**稳定版版本号变了**，才需要重提取契约（脚手架的 `extract-contract.py`）→
+跑 `contract-diff.mjs` → 看差集里有没有「不写会关掉某个能力」的字段。
+完整判据见脚手架的
+[HOOKS.md](https://github.com/MYCF711/magpie-plugin-scaffold/blob/main/HOOKS.md) 顶部
+与 [UPDATING.md](https://github.com/MYCF711/magpie-plugin-scaffold/blob/main/UPDATING.md) 第七节。
+
+---
+
 ## 一、先定位你在哪一步
 
 | 你在做什么 | 必读（按顺序） | 做完的判据 |
@@ -32,7 +53,7 @@
 |---|---|---|---|
 | 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**，别在热路径上调签发；续期走 `src/keys.mjs` 的唯一出口 | internals 十三 |
+| 3 | 换了 key 之后老 key 立刻失效、用户被要求重登 | **「签新 key 会吊销旧 key」已被实测推翻（2026-10-28）** —— 见下方「最容易误信的旧说法」。仍然只留一把、只走 `src/keys.mjs` 的唯一出口，理由是**本地别分叉**，不是互相吊销 | internals 十四 |
 | 4 | 刷新 token 之后两处 refresh_token 不一致、用户莫名掉登录 | 只允许**一个**出口持有 refresh_token；`src/hooks/refresh.mjs` 绕过出口就会分叉 | internals 二 / 十四 |
 | 5 | agent 说「上下文放不下」，而实际模型能吃更长 | 上下文窗口**必须查 magpie 的模型库**，不能填保守值（早前一刀切 256K，实际 1M） | internals 十六 |
 | 6 | 流式回复拿到了，但 `usage` 永远是空、额度不扣 | 流式请求必须补 `stream_options.include_usage`，否则上游不回 usage | internals 十二 |
@@ -43,12 +64,23 @@
 | 11 | Windows 上点登录，浏览器窗口拉不起来 | 浏览器可执行文件名**随版本变**（`msedge.exe` / Chrome 各版本目录不同），要逐个试候选，别写死一个名字 | internals 十一 |
 | 12 | 用户点「检查更新」显示有新提交，点了更新却没变化 | 本仓库是 **git 源**：magpie 比默认分支 HEAD 的 commit，只提示不自动更新，要用户点那一行的「更新」；更新后 `magpie plugin list` 的 commit 应变化 | 脚手架 UPDATING 一 |
 | 13 | 想让卡片标题 / 「源码」按钮对，去改了 magpie 的缓存 | 插件对 magpie 目录**只有读的份**；唯一载体是 `registry-entry.json`（提交给 `registry.json`） | internals 二 · README |
+| 14 | **卡片上额度正常，路由页里这个号却是「剩余额度未知」** | 窗口**不能标 `aside`**：magpie 的 `allowanceOf()` 把 `Aside`/`Text` 的窗口整条跳过，一条不剩 ⇒ 该号 `Known=false`（官网文档 issue #3650 明写）。判据：`curl -s http://127.0.0.1:3425/v1/magpie/trace`，看这个 provider 的 `known` 是 `true` 还是**字段缺失** | HOOKS 三 · `src/hooks/usage.mjs` 头 |
+| 15 | 接 ZCode / Claude Code 系客户端，带工具的请求回 `400 {"error":{"message":"模型响应失败","code":4017}}` | **上游的 `additionalProperties` 只认布尔值，任何对象形态都拒** —— 不只是 `{}`，`{type:"string"}` 这种有约束的 schema 一样 400（两个模型逐行一致）。判据：同一请求只把该字段换成 `true` → 200。改写已在 `rewriteRequestBody` 里做（非布尔一律换 true；**这是降级放宽、会丢约束**，取舍见 internals 十七） | internals 十七 · `tests/body-rewrite.mjs` |
+| 16 | 网关路径（agent 从 magpie 的 `/v1` 进来）报 `502 did not stream: token无效`，而 provider 显示已登录 | auth 里没带 org → `accountOf()` 落 `"default"` → 读不到真实账号的 key 槽 → 只能用 `auth.access`，它过了 2 小时就 403。`accountFor()` 已在**恰好一个真实账号**时兜到它；**多账号不猜**（猜错就是拿别人的 key 扣别人的积分） | internals 十四 · 十五 · `tests/account-fallback.mjs` |
+
+**坑 14 的两个附带判据**（都实测过）：
+
+- **改了 `src/hooks/usage.mjs` 要重启 magpie 才生效** —— 插件跑在 `magpie-bun` 子进程里，
+  模块缓存不随文件变化失效。改完先 `Stop-Process` 再 `Start-Process` 同一个 exe，
+  然后 `curl /v1/magpie/quotas` 看窗口里的 `spans`：`[{}]` = 没标 aside，`[{"aside":true}]` = 还标着。
+- **额度读取有 1 分钟缓存**，改完立刻看可能还是旧值。
 
 补充一条最容易误信的旧说法：
 
 | 症状 | 判据 | 出处 |
 |---|---|---|
 | 以为 checkin 会「顺带续 key」 | **从来没有**。`src/hooks/checkin.mjs` → `src/tasks.mjs` 全链路没 import 过 `ensureKey`；保活由 magpie 按 `refreshLead` 主动调 `auth.refresh` | internals 十四 · CHANGELOG 0.x |
+| 以为「签一把顶一把」、`key-store` 里的 key 会「时间没到就被顶掉」 | **已实测推翻（2026-10-28）**：同账号两把相隔 67 秒签的 key 同时有效；12 把 key 逐把探活，403 **全部**对应 `expiresAt` 已过（剩 -173～-541 分），没有一个「时间没到就失效」的样本。仍只留一把、只走唯一出口的理由是「本地别分叉」，不是「互相吊销」。据此加「跨账号挑活 key」的兜底 = 把别人的 key 交出去 | internals 十四 · 十五 |
 
 ---
 
@@ -102,7 +134,7 @@ git tag v0.3.16 && git push origin v0.3.16
 | 文件 | 管什么 | 什么时候读 |
 |---|---|---|
 | [README](./README.md) | 用户看的门面：功能、模型、安装 | 改用户可见行为时 |
-| [docs/internals.md](./docs/internals.md) | 16 章实测：两站同构、三层凭证、接口清单、协议要点 | 改代码前按章查 |
+| [docs/internals.md](./docs/internals.md) | 17 章实测：两站同构、三层凭证、接口清单、协议要点、工具 schema 兼容 | 改代码前按章查 |
 | [CHANGELOG.md](./CHANGELOG.md) | 每版一节 | 写新版本时 |
 | [CHECKLIST.md](./CHECKLIST.md) | 两张勾选表 | 两个交付门 |
 | 脚手架 [AGENTS.md](../magpie-plugin-scaffold/AGENTS.md) | 通用坑（九项清单、三条铁律、check 能查什么） | 第一次接触这个插件族时 |

package/CHANGELOG.md

@@ -1,5 +1,285 @@
 # 更新记录
 
+## 0.3.23 — 2026-10-28
+
+**修工具 schema 兼容 + 网关路径拿错 key，顺手把「签一把顶一把」测清楚了**
+
+### 一、上游不认 `additionalProperties: {}`
+
+接 ZCode / Claude Code 系客户端时，一次带 54 个工具定义的请求必回
+`400 {"error":{"message":"模型响应失败","code":4017}}`。根因是这些客户端把
+"允许任意属性"写成空对象，而上游适配层只认布尔值。
+
+同一把 key、同一份请求、只改这一个字段（2026-10-28 实测，glm-5.3-flash 与
+deepseek-v4.1-flash **逐行一致**）：
+
+```
+additionalProperties: 缺省             → 200
+additionalProperties: false            → 200
+additionalProperties: true             → 200
+additionalProperties: {}               → 400 code 4017
+additionalProperties: {type:"string"}  → 400 code 4017
+```
+
+**上游不是「只认布尔」，是根本不支持 schema 形态** —— 只处理空对象不够。这一点是拿
+改动端到端跑一遍才发现的：对照组 400 → 只改空对象**仍然 400** → 非布尔全换 true 才 200。
+
+`rewriteRequestBody` 里加递归规范化，把**所有非布尔值**换成 `true`。
+`{}` → `true` 是严格等价；`{type:"string"}` → `true` 是**降级放宽**、丢了约束，
+但上游无法表达它，留原值就是整个请求失败。方向安全（放宽不是收紧）。
+
+请求体三处改写（max_tokens / stream_options / additionalProperties）合并成**一次**
+`JSON.parse`，没改到时返回原始字符串（54 个工具的请求体可达上百 KB）。
+
+> 这处改动来自社区 PR #8（@baijiu666），按其最小复现验证后采纳。
+
+### 二、网关路径下拿不到正确账号的 key
+
+agent 从 magpie 的 `/v1/chat/completions` 进来时，`getAuth()` 返回的 auth
+**可能不带 org**，`accountOf()` 于是落到 `"default"` —— 读不到真实账号的 key 槽，
+`ensureKey` 只能退回 `auth.access`；它过了 2 小时就 403，表现成
+`502 {"message":"超级麦吉 did not stream: token无效"}`。
+
+新增 `accountFor()`：拿不到标识时，**只有该站点恰好一个真实账号**才退到它。
+0 个沿用原来的「首次接管」；**≥2 个不猜** —— 用错账号的 key 是拿别人的积分、
+别人的组织出话，本地看不出来，不是报错是错账。
+
+⚠ 多账号 + 网关路径这个组合仍然无解：需要 magpie 把 provider 实例 id 传给插件
+（`plugin-auth.json` 里已经有 `magicrew#p4nwa7` 这种 key），插件侧拿不到。
+在那之前只能保守 —— 宁可这次请求失败，也不借身份。
+
+### 三、「签一把顶一把」实测推翻（不涉及代码，只更正文档）
+
+`docs/internals.md` 第十四节一直挂着「要判定需要一次受控实验」。做完了：
+本机 12 把 key 逐把打 `GET /v1/models`（只读、不签发、不吊销），结果是
+
+- 同账号两把相隔 **67 秒**签发的 key **同时有效**
+- 所有 403 都对应 `expiresAt` 已过（剩 -173～-541 分），**没有**「时间没到就失效」的样本
+
+⇒ 后签的**不吊销**先签的；唯一失效条件是 2 小时到期。`AGENTS.md` 坑 3 与
+internals 十三节据此更正。「只留一把、只走唯一出口」的设计保留，理由改为
+「本地别分叉」而不是「互相吊销」。
+
+### 测试
+
+- `tests/body-rewrite.mjs` —— 20 个断言：只换空对象、非空 schema 不动、
+  其余字段一字不动、没改就不重新序列化
+- `tests/account-fallback.mjs` —— 10 个断言：单账号才兜、多账号不猜、空壳文件不算账号
+
+---
+
+## 0.3.22 — 2026-10-28
+
+**余额窗口保留「今日 / 限时 / 永久」拆分展示**
+
+0.3.21 只发一条总余额，路由对了，但看不出每日 23:59 到期的额度。现在在
+`积分余额` 余额窗口之后追加三条只展示的 `aside` 文本行：
+
+- `今日积分`：`185 / 200 积分 · 今日 23:59 到期`
+- `限时积分`：剩余限时批次 + 最早到期日
+- `永久积分`：不过期部分
+
+它们不带 `used` / `limit` / `balance`，宿主把它们当 `aside` 文本，不参与
+`Allowance.Left`，路由仍只按 `积分余额` 排序；总余额不会被拆分窗口压低。
+
+## 0.3.21 — 2026-10-28
+
+**积分改为 magpie 的「余额型窗口」：不再编造百分比**
+
+magpie 0.1.1790（issue #3950）起支持 `usage.windows[].balance`：只报余额和单位，
+不写 `used` / `limit` / `aside`。本版把原来「今日 / 限时 / 永久」三条假百分比窗口
+合并成一条 `积分余额`：
+
+- `balance = total_points`、`unit = "积分"`；
+- `runsOutAt` / `runsOut` 取最早过期的一批，让 smart 路由知道谁先失效；
+- 余额 0 也报 `balance: 0`，由宿主判定为用完，不再合成 `used: 100`。
+
+宿主现在按同 provider、同单位的余额从多到少排；不再显示「总量 = 余额」的
+100% 假进度条。旧版三窗口写法是宿主支持余额前的过渡，已删除。
+
+## 0.3.20 — 2026-10-28
+
+**积分按「什么时候失效」拆成三块：今日 / 限时 / 永久**
+
+0.3.19 把整池积分压成一条窗口，百分比是「总量 = 余额」的恒等式，没有信息量。
+现在拆成三块（数据都来自 `/api/v1/quota/points/total`）：
+
+| 窗口 | 是什么 | 百分比 | 参与路由 |
+|---|---|---|---|
+| **今日积分** | 今天 23:59:59 到期的批次（每日登录赠送，国内 200 / 国际 50） | **真的**（分母是每日额度） | 是 |
+| **限时积分** | 其余会过期批次的剩余之和 | 无（服务端不给原始额度） | 是（带 `runsOutAt`） |
+| **永久积分** | `total - Σ限时`，不过期 | — | 否（`aside` 只展示） |
+
+三块加起来正好等于 `total_points`，实测四个号都对得上。
+
+**为什么「限时积分」条目不标 `aside`**：标了会被 `allowanceOf()` 整条跳过，
+`runsOutAt` 就进不了路由 —— 这个号又会变回「未知」。所以它给 `used: 0` +
+`limit = 当前余量`，让 magpie 收下它并读到 `runsOutAt`。百分比（恒 100%）无意义，
+但路由能按「谁的积分先过期」排。
+
+**关于「7 个依次递减的到期时间」**：`runsOutAt` 是单值字段（`*time.Time`），
+语义就是「最早失效的那一批」，所以 7 个批次也只会出现一条提醒，不会堆成 7 条。
+magpie 自己的 WorkBuddy 插件就是这么用的。magicrew 的每日登录积分是
+「当天 23:59:59 到期」（`expire_type: 1`，不累积），更不存在滚动多批。
+
+**为什么还是要给 magpie 提 issue**：magpie 的契约把「有进度条」和「参与路由」
+焊在同一个窗口上 —— 要进度条就得给 `used`+`limit`，钱包没有分母就只能编；
+不编就判成纯文本 + `aside`，路由又当未知。三条不可能同时满足。
+真正的解是宿主支持「余额型窗口」：有读数、能参与路由，但不参与百分比。
+
+## 0.3.19 — 2026-10-28
+
+**路由页不再说「剩余额度未知」：窗口不能标 `aside`**
+
+0.3.18 把积分窗口改成 `aside: true` + 只给 `display` —— 卡片好了，
+**路由页还是「剩余额度未知」**。
+
+根因在 magpie 宿主侧，读源码可证：
+
+```
+provider/routing.go   allowanceOf()     if (w.Aside || w.Text) { continue }    ← 整条跳过
+provider/routing.go   routedAllowance() if len(a) == 0 { return nil, false }   ← 一条不剩 ⇒ 不 ok
+gateway/trace.go      weighed()         if l, ok := wg.lefts[key]; ok { w.Known = true }
+routing/client.js     w.known 为假且 kind == "account" ⇒ 「剩余额度未知」
+```
+
+官方文档也逐字写着（`docs/subsystems/provider-plugins.md`，issue #3650）：
+
+> An account whose windows all tell no share has no allowance, so routing counts
+> it not known ... as one never read. A window that says `used: 0` is a reading
+> at 0, as before.
+
+⇒ **`aside` 的代价不是「不参与排序」，是这个号在路由里整个消失**
+（unknown 一律排在已知的之后）。
+
+现在改成钱包的恒等式：`limit = 余额`、`amount = 0`、`used = 0`，**不加 `aside`**。
+`used` 仍然是「已用 0」而不是缺省 —— 缺省会被 magpie 判成「没有份额的文本行」，
+又回到未知。
+
+判据（2026-10-28 实测，两站四个号）：
+
+| | 修复前 | 修复后 |
+|---|---|---|
+| `/v1/magpie/trace` 的 `known` | **字段缺失** | `true`，`limit` = 余额 |
+| 路由页那一行 | 剩余额度未知 | `1,363 / 1,363 积分 · 剩余 100%` |
+
+A/B 都跑过：把 `aside: true` 加回去、重启 magpie，`known` 立刻变回缺失；
+换回来就恢复 `true`。
+
+⚠ 代价说清楚：这样算出来的百分比**没有信息量**（分母就是分子）——
+magpie 的额度契约是为「周期配额」设计的，钱包型额度它没有专门表达。
+真正该修的是宿主侧，插件侧只能给出最接近的形态。
+
+## 0.3.18 — 2026-10-28
+
+- **AGENTS 新增「零、magpie 升级时：只看稳定版」** —— magpie 有「更新渠道：每个版本 / 稳定版」，用户默认跑稳定版。两渠道实测差 **400 多个版本**（每版本 0.1.1763 / 稳定版 0.1.1327），但插件相关的契约字段**一条不差** ⇒ 追每版本几乎全是白跑。判断依据只有一条：**稳定版版本号变了**才需要重新同步
+
+## 0.3.17
+
+**不用开浏览器也能登录了 —— 手机号 + 短信验证码，纯 HTTP 走完**
+
+那个卡了很久的「拖动滑块使图片角度为正」现在能自动过：用 magpie 设置里你自己选的
+识图模型（`settings.json` 的 `vision`）判断旋转角度，然后纯 HTTP 把整条链走完。
+
+### 之前为什么做不了，以及真相
+
+旧文档（internals 第九节）写着「magicrew 没有这条路」。**那是错的，原因是找错了域名。**
+登录用的用户中心不在 `i-magic-service.letsmagic.cn`，而在另一套 keewood 服务上：
+
+| 站点 | 用户中心 |
+|---|---|
+| 国内 letsmagic.cn | `https://i-keewood-service.teamshare.cn` |
+| 国际 magicrew.ai | `https://keewood-service.magicrew.ai`（**没有 `i-` 前缀**） |
+
+换成这个域名，整条链一个 404 都没有。
+
+### 五步链路（全部实测）
+
+```
+POST /captcha/generate    {account_type:"mobile", mobile, state_code}
+     → {token, image(data:image/webp;base64,…), expire_time}      ← 纯 JSON，无 cookie、无指纹
+POST /captcha/verify      {token, angle, account_type, mobile, state_code}
+     → {verified:true, business_token:"biz_…"}
+POST /v4/user/send-sms    {type:"account_login", phone, state_code}
+     + header X-Captcha-Token: <business_token>                  ← 这个 type 填错会炸
+POST /v4/user/login       {type:"phone_captcha", phone, state_code, code, device:{id,name}}
+     → jwt + 组织
+```
+
+**`angle` 不是一个裸角度，是加密过的整数**，前端那么算：
+
+```
+l = deg,  u = n (n = Date.now()%90000+10000)
+d = 52249517 × (l + u) + 5976906165
+angle = String(d & 0xFFFFFFFF) + String(n)
+```
+
+`deg` 就是「图片要顺时针转多少度」，**1 px = 1.6°，满行程 225 px = 360°**。
+验证方式：抓浏览器真实提交的 4 组 angle，对每组正向穷举 0…359 **都唯一命中**，
+命中值与拖动像素严格成 1.6 倍；另用图像互相关独立验算，拖 100px 前后帧相差 160°±0.25°。
+
+### 识图判角度：问钟点，不问角度
+
+**不要问模型「这图歪了多少度」** —— 实测填空 6 次错 5 次。改问
+「主体自己的『上方向』指向钟面的几点」（12=正上、3=正右），再 `deg = (12 - clock) × 30`。
+
+而且**必须问两遍比分歧**：实测的失败样本是两个判官给出 1.7 和 7.5 钟点（相差 174°），
+其中一个把方向看反了 —— 这种情况取平均毫无意义，只能换图重来。
+分歧阈值 1.5 钟点（45°）。
+
+服务端**容差实测 ≥ ±10°**（正确答案 120°，故意提交 130° 仍然通过），所以钟点法的
+精度是够的：24 格 15° 网格的那点误差根本不影响。
+
+⚠ `Bun.Image.rotate()` **只支持 90° 的倍数**（`rotate: only multiples of 90 are supported`），
+`bytes()`/`buffer()` 给的是编码后的 PNG、拿不到原始像素 —— 所以「旋转 24 格网格」
+这条路在插件里走不通，才改用钟点法。
+
+### 新增
+
+- `src/captcha.mjs` —— 取图 / 角度加密 / 验证 / 发短信 / 验证码换登录态 / 三站域名映射
+- `src/vision.mjs` —— 读 `settings.json` 的 `vision`、找 magpie 自己的网关
+  （默认 `127.0.0.1:3425`，`MAGPIE_GATEWAY_PORT` 可覆盖）、webp→png、钟点双问与分歧判定
+- `src/headless.mjs` —— 编排：最多换 4 张图、每张只提交一次（风控不允许反复试同一 token）、
+  失败把每轮原因带出来
+- 登录方法「手机号验证码」—— `prompts` 问手机号，`authorize` 里过验证并发短信，
+  然后 `method: "code"` 等用户填 6 位验证码，`callback(code)` 换登录态并建号
+
+### 两个坑，都是实测撞出来的
+
+1. **`send-sms` 的 `type` 必须是 `"account_login"`**。填 `"login"` / `"phone_captcha"`
+   / `"sms_login"` 全部返回 `9999 服务异常，请联系管理员` —— 后端内部炸了，不是参数校验，
+   所以从错误信息上完全看不出是 type 的问题。这个值是从浏览器真实请求里抓出来的。
+2. **`device` 是必填且结构要试**：缺 → 9999；给字符串 → 9999；
+   `{device_id}` → 「id 字段是必须的」；`{id, name}` → 放行。
+   ⇒ `{id: 64 位 hex, name: "web"}`。
+
+### 另外两个更贵的修正（第一版发出去就踩了）
+
+1. **`opened` 必须是 `true`。** 这条链路全在后台走完，不需要任何浏览器；写成 `false`
+   会让 magpie 拿 `url` 去开**系统默认浏览器** —— 而那个浏览器里往往本来就登着这个站，
+   用户看到的是已登录界面，进不了「添加新号」，还以为插件把他登进了旧账号。
+   这正是浏览器登录那条路修过的坑，这次在新方法里又踩了一遍。
+2. **新号注册要带 `auto_register: true` 和 `redirect`，而邀请码是靠 `redirect` 传的。**
+   网页表单的初始值就是
+   `{ phone, state_code, code, auto_register: true, type: "phone_captcha", redirect: window.location.href }` —
+   服务端从 `redirect` 上取 `?invitation=<码>`，`invite_code` 不是独立字段。
+   ⇒ 无头这条路没有「打开带邀请码的页面」这一步，所以必须自己拼出带邀请码的
+   `redirect: ${web}/login?invitation=<码>`。少了它，新注册的号就没有邀请关系。
+
+
+### 没配识图模型时
+
+**不瞎猜。** 容差 ±10° 意味着瞎猜命中率只有约 5.6%（20/360），平均要试十几次，
+先撞上的会是「验证提交过于频繁」。这种情况直接报错并指路：去 magpie 设置里配一个
+识图模型，或者改用「浏览器登录」。
+
+### ⚠ 未实测的一步
+
+`/v4/user/login` 成功之后**响应里 jwt / 组织码的确切结构没验到** —— 手上没有能收短信的
+号码，只能验到 `2168 验证码错误`（这已经证明参数结构对了）。所以那一步写成：
+按 `eyJ` 三段式特征找 JWT、组织码找不着就用拿到的 JWT 调
+`/api/v1/aggregation/login-data` 补；两条都拿不到时把原始响应带进错误信息。
+
 ## 0.3.16
 
 **加了给 AI 执行者的入口 —— 因为「发布」这一步真的被漏过一次**

package/docs/internals.md

@@ -340,6 +340,29 @@ cat "<安装目录>/resources/app-update.yml"
 
 ## 九、为什么做不到「点一下全自动」
 
+> ### ⚠ 更正（2026-10-28）：这一节原来的结论是**错的**
+>
+> 原文断言「magicrew 没有这条路」，理由是「登录类型全是拿凭据换 token，没有设备码、
+> 没有一次性 ticket」。**真正的错因是找错了域名** —— 登录用的用户中心不在
+> `i-magic-service.letsmagic.cn`，而在 keewood：
+>
+> | 站点 | 用户中心 |
+> |---|---|
+> | 国内 | `https://i-keewood-service.teamshare.cn` |
+> | 国际 | `https://keewood-service.magicrew.ai`（**没有 `i-` 前缀**） |
+>
+> 换成这个域名，整条链一个 404 都没有：`/captcha/generate` → `/captcha/verify` →
+> `/v4/user/send-sms` → `/v4/user/login`，**全程纯 HTTP、不开浏览器**。
+> 那个「拖动滑块使图片角度为正」的答案就是提交参数里的 `angle`（加密过的整数），
+> 用 magpie 设置里的识图模型判「主体上方向指向钟面几点」就能算出来。
+>
+> 实现见 `src/captcha.mjs` / `src/vision.mjs` / `src/headless.mjs`，
+> 以及登录方法「手机号验证码」。下面保留原文，只为了说明**当时为什么判断错了**。
+
+下面的分析**在换对域名之前**成立，其中「① 13 种登录类型」和「③ 试过的三个端点」
+仍然是事实，只是它们不能推出「没有这条路」——真正缺的那个域名当时没找到。
+
+
 对比 OfficeAce：它能做到「浏览器登录完，magpie 窗口自动继续」，因为华为云 OAuth 的
 `redirect_uri` 指向一个**可控的服务**（`${CLAW_BASE}/v1/claw/auth/callback`），
 插件轮询那个服务取结果。magicrew 没有这条通道：
@@ -737,15 +760,62 @@ mgw_8f9a…（18:14 又一次续期换的）       → 网关请求 HTTP 200 正
 
 两把都活着。所以「一签就吊销」不成立。
 
-那第十三节那次 `mgw_63d4…` 为什么 403？现在只能说**不确定**，可能的原因三种，没分辨开：
+那第十三节那次 `mgw_63d4…` 为什么 403？当时只能说**不确定**，三种可能没分辨开：
 
 1. 它真的过期了（2 小时），而本地 `expires` 字段显示还没到 —— 说明 `expires` 不可信
 2. `PUT`（用 refresh_token 续期）会轮换/吊销旧的 `api_key`，而 `POST`（签发）不会
 3. 别的吊销条件（重新登录、并发续期）
 
-**要判定需要一次受控实验**：同一账号 POST 签两把、隔着时间各测一次，再把 PUT 也测一遍。
-在那之前，插件按「可能有吊销」来设计（只留一把、只走一个出口）是安全的，
-但**不要把它当成已知事实往下传**。
+### ✅ 结论（2026-10-28 晚，受控实验做完了）
+
+上面说「要判定需要一次受控实验」。实验做了，**答案落在第 1 条：只有「真的超过 2 小时」会 403，
+「签一把顶一把」不成立，`expires` 也只是个理论值**。
+
+做法：把本机**所有** key（magpie 的 `plugin-auth.json` 的 access + key-store 每个账号每个槽）
+逐把打 `GET /v1/models`——只读、不签发、不吊销、不花钱。探针留在仓库外，
+结论是这一张表（`剩余` = `expiresAt - now`，单位分钟）：
+
+```
+来源      站点            账号             槽       剩余(分)   判定
+magpie  magicrew-intl  67u4oe6fbenj   access   116        HTTP 200 MODELS=65
+magpie  magicrew       7fli52t2tc2b   access   115        HTTP 200 MODELS=44
+magpie  magicrew       66p0q56qo47j   access   115        HTTP 200 MODELS=44
+magpie  magicrew       h97gkbu8bruj   access   115        HTTP 200 MODELS=44
+store   magicrew-intl  67u4oe6fbenj   a*       116        HTTP 200 MODELS=65
+store   magicrew-intl  67u4oe6fbenj   b        -181       code=403 "token无效"
+store   magicrew       66p0q56qo47j   a*       -227       code=403 "token无效"
+store   magicrew       66p0q56qo47j   b        -541       code=403 "token无效"
+store   magicrew       7fli52t2tc2b   a*       -173       code=403 "token无效"
+store   magicrew       7fli52t2tc2b   b        -286       code=403 "token无效"
+store   magicrew       h97gkbu8bruj   a*       117        HTTP 200 MODELS=44
+store   magicrew       h97gkbu8bruj   b        -228       code=403 "token无效"
+```
+
+两条判据：
+
+**① 403 与「剩余分钟数」完全一致** —— 每一个 403 的剩余都是负数（-173 到 -541），
+每一个 200 的剩余都是正数。**没有一个「时间没到却不认」的样本。**
+所以「本地时间没到但服务端已经吊销」这个状态，本次实测里根本不存在。
+
+**② 同一账号同时有两把活 key，签发时刻相差 67 秒：**
+
+```
+magpie access  expires 2026-10-28T14:39:56.898Z   → 200
+store  槽 a    expires 2026-10-28T14:41:03.000Z   → 200
+```
+
+两把都是 2 小时有效期，也就是一把签于 12:39:56、另一把签于 12:41:03 —— **后签的没有顶掉先签的**。
+
+⇒ **一条账号一把活 key 这个说法彻底作废**。`POST` 与 `PUT` 都不吊销已签出的 key，
+唯一的失效条件是 2 小时到期。
+
+### 那这条为什么必须写下来
+
+2026-10-28 的 PR #8 就是被「时间没到但已被顶掉」这个前提带偏的：它据此把
+`ensureKey` 改成「优先用 `auth.access`」，并加了一个跨账号挑活 key 的兜底。
+前提不成立 ⇒ 改动没有依据；而那个兜底会**把别的账号的 key 交出去**
+（实测：auth 无 org 时 PR 分支返回了 `h97gkbu8bruj` 账号的 key，
+而 main 返回调用方自己的）。教训不是「多加一层兜底」，是**先把前提测了再改代码**。
 
 ### 保活的正确说法
 
@@ -982,3 +1052,84 @@ GET /v1/models            → id / object / created_at / owner_by
 
 magicrew 既不返回 `maxInputTokens`（`flows/models` 的 `configs` 只有 temperature），
 `/v1/models` 也只有 `id / object / created_at / owner_by` —— 所以走模型库这条路。
+
+---
+
+## 十七、上游不认 `additionalProperties: {}` —— 工具 schema 要在请求里兜住
+
+**症状**：接 ZCode / Claude Code 系客户端时，一次带 54 个工具定义的请求必定失败：
+
+```
+POST /v1/chat/completions
+→ HTTP 400 {"error":{"message":"模型响应失败","code":4017","request_id":"..."}}
+```
+
+换成简单请求（一两个工具）就正常 —— 所以看起来像"某些模型不行"或"工具太多"。
+
+### 根因
+
+这些客户端生成工具 schema 时，会把"允许任意额外属性"写成**空对象**：
+
+```json
+"parameters": { "type": "object", "properties": {...}, "additionalProperties": {} }
+```
+
+按 JSON Schema（draft-07）这是合法的 —— `additionalProperties` 的值是 schema 时，
+`{}` 表示"任意，不加约束"，与 `true` 语义等价。但**上游的适配层只认布尔值**，
+收到一个对象就整个请求拒掉，还只回一句"模型响应失败"，不说是哪个字段。
+
+### 最小复现（2026-10-28，同一把 key、同一份请求、只改这一个字段）
+
+| `additionalProperties` | glm-5.3-flash | deepseek-v4.1-flash |
+|---|---|---|
+| 缺省 | 200 | 200 |
+| `false` | 200 | 200 |
+| `true` | 200 | 200 |
+| `{}` | **400 code 4017** | **400 code 4017** |
+| `{type:"string"}` | **400 code 4017** | **400 code 4017** |
+| `{type:"string",description:"x"}` | **400 code 4017** | **400 code 4017** |
+
+**两个模型逐行一致。结论比「上游只认布尔」更狠：它根本不支持 schema 形态** ——
+不只是空对象，连 `{type:"string"}` 这种有约束的 schema 也一律拒。这一点很关键：
+只处理空对象的改写在真实请求里仍会 400（实测过，见下方「修法」）。
+
+### 修法：请求改写里做等价替换
+
+`src/hooks/loader.mjs` 的 `rewriteRequestBody` 里，`loosenAdditionalProperties()`
+递归扫 `tools[].function.parameters`，把**所有非布尔值**换成 `true`：
+
+```js
+"additionalProperties": 缺省         →  不动       // 等价于 true
+"additionalProperties": true         →  不动       // 上游认
+"additionalProperties": false        →  不动       // 「不许额外属性」，换掉就是反向放开
+"additionalProperties": {}           →  true       // 等价改写
+"additionalProperties": {type:"x"}   →  true       // ⚠ 降级放宽，丢了约束
+```
+
+**为什么接受那个不等价**：`{}` → `true` 是严格等价（都表示「任意，不加约束」）；
+`{type:"string"}` → `true` 丢掉了「额外属性必须是 string」这条约束。但上游无法表达它，
+保留原值就是整个请求失败。两害相权，让工具调用能跑（可能多出未声明的字段）
+比让 agent 完全不可用要好；方向也安全 —— 是放宽不是收紧，不会让原本合法的调用被拒。
+
+它与 `max_tokens`、`stream_options` 三处改写共用**一次** `JSON.parse`；
+没改到时返回原始字符串（省一次序列化 —— 54 工具的请求体可达上百 KB）。
+
+边界由 `tests/body-rewrite.mjs` 钉住（20 个断言）：非布尔一律换、布尔一律不动、
+其余字段一字不动、没改到就不重新序列化。
+
+### 为什么算插件的事，不算客户端的事
+
+按规范 `{}` 与 `true` 等价，客户端没写错；**上游的兼容性不足**。
+但插件是唯一能改请求体的地方（见 `src/hooks/loader.mjs` 顶部），
+在这里兜住比让每个用户去改 ZCode 的源码现实。
+
+### 同一处的第三个改写，以及它的教训
+
+同一次排查里还确认了两件事，都值得记住：
+
+1. **上游对"token 无效"回的是 HTTP 200**，body `{"code":403,"message":"token无效"}`，
+   且 `error` 字段是空数组（falsy）。**只看 HTTP 状态码会把失败当成功** ——
+   判断得用 `j.code !== 200`。排查时在这上面绕了很久。
+2. **插件宿主是运行时从 `~/.cache/magpie/bun/install-cache/` 加载的**，
+   不在 `plugin-host/host-*.js` 里；magpie 更新插件后会换目录（目录名带 commit hash），
+   要改当前实际加载的那个。

package/docs/upstream-issue-3950.md

@@ -0,0 +1,90 @@
+## TL;DR
+
+A provider that sells **prepaid credit** — a wallet — cannot be described by the current usage contract:
+
+- **With windows**, `used` must be a share of a periodic allowance. A wallet has no such denominator, so any `used` we send is fabricated.
+- **Without windows**, `routedAllowance` returns not-ok, `weighed()` leaves `Known` unset, and the Routing page says 「剩余额度未知」 — the account ranks after every known one (#3650).
+- **`aside: true` does not help**: `allowanceOf()` skips those windows whole, with the same result.
+
+What is missing is a **balance-shaped reading**: "this much is left", in a unit, with no percentage. Two fields would carry it — `QuotaWindow.Balance` and `routes.Seat.Left`.
+
+## The provider (real numbers, 2026-10-28)
+
+SuperMagic (超级麦吉 / MagiCrew), community plugin `magpie-magicrew-auth`.
+
+`GET /api/v1/quota/points/total` answers:
+
+```json
+{"total_points": 6291,
+ "expiring_quota_details": [
+   {"remaining_points": 185, "expires_at": "2026-10-28 23:59:59"},
+   {"remaining_points": 100, "expires_at": "2026-11-26 16:45:13"},
+   {"remaining_points": 956, "expires_at": "2027-11-03 19:11:01"}],
+ "organization_limit_points": null,
+ "user_limit_points": null,
+ "next_cycle_grant": null}
+```
+
+- No total, no consumed: `*_limit_points` are `null` on personal accounts.
+- The ledger endpoint `POST /api/v1/quota/points/records/queries` answers **HTTP 500** on both sites (five body shapes tried), so "how much was spent" is not readable either.
+- The only fixed number is the daily login gift — **200 points/day (CN), 50 (intl)** — which expires at 23:59:59 the same day.
+
+## What the plugin tried, and what magpie did
+
+| plugin sends | magpie | result |
+|---|---|---|
+| `aside: true, used: 0, display: "6,291 积分"` | `allowanceOf()` skips Aside/Text whole; none left → `routedAllowance` not ok → `weighed()` leaves `Known` unset | Routing page 「剩余额度未知」; the account ranks after every known one |
+| `used: 0, display: "6,291 积分"` (no `limit`) | known, but routing's `quota()` shows the count only when `limit > 0` | row reads `0% used`, no figure |
+| `used: 0, amount: 0, limit: 6291` | known, figure shown | percentage is `0 / 6291` — a tautology (denominator = remainder); the "fake share" of #3353 |
+
+## What it costs the router
+
+`routes.Seat` carries `Used float64` (a 0–100 share), `Soon []time.Time`, `Lapse`, `Pace`, … — **nothing that says how much is left**.
+
+- **`pace`**: `(100 - used) / hours until resetsAt`. A wallet has no `resetsAt` and its `used` is always 0, so every account of this provider gets **the same pace**. 6,291 points and 750 points are indistinguishable.
+- **`smart`**: the fine tier is ordered by `Soon` (`Allowance.Renewal`, which does fold `runsOutAt` in), then `Lapse` — it can say *whose points expire first*, never *who has more left*.
+
+Measured on 4 accounts: 1,363 / 1,693 / 6,291 / 750 points; earliest expiries 178 / 29 / 29 / 372 days out. Under `smart` all four tie on `Soon` whenever the expiry days match; under `pace` they are **exactly** identical.
+
+## Suggested shape
+
+**`QuotaWindow`**
+
+```go
+// Balance is how much of this allowance is left, in Unit — a reading of a
+// prepaid balance, with no share to tell (Used stays nil for it).
+Balance *float64 `json:"balance,omitempty"`
+```
+
+`allowanceOf` keeps such a window (`l.Balance = *w.Balance`), so `Known` is true, without inventing a `Used`.
+
+**`routes.Seat`**
+
+```go
+// Left is the absolute remainder in the provider's own unit: comparable
+// within one provider, 0 when the vendor doesn't say.
+Left float64
+```
+
+Filled from the windows' `Balance` (or the fullest window's `Amount`/`Of` when the vendor does count).
+
+**Ordering**: `smart` / `pace` fall back to `Left` (most first) when shares are unknown or equal. A prepaid provider then becomes rankable by both dimensions that matter: *who runs out first* (`runsOutAt`) and *who has the most left* (`balance`).
+
+## Today's plugin-side workaround (for reference)
+
+Three windows, so the account is at least known and carries `runsOutAt`:
+
+1. **今日积分** — today's batch, **real percentage** (denominator = the 200/50 daily gift), `resetsAt` = next midnight.
+2. **限时积分** — the rest of the expiring batches, `used: 0`, `limit` = current remainder, `runsOutAt` = earliest.
+3. **永久积分** — `total − Σexpiring`, `aside`, display only.
+
+That is the best the current contract allows — and it still cannot express "how much".
+
+## Related
+
+- #3428 — the seat knows *when* but not *how much* is lost (`w.RunsOut` dropped in `allowanceOf`). This issue is the same gap one layer up: the seat also cannot see *how much is left at all*.
+- #3352 — a `Windows: []` reading with a balance is dropped entirely, so the account is unknown.
+- #3353 — a window that never moves reads as `used: 0` and distorts smart ordering.
+- #3650 — a window without `used` becomes text + aside, no share.
+
+Happy to send a PR for the two fields if the shape looks right — I can test it against this provider directly.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "magicrew-auth",
-  "version": "0.3.16",
+  "version": "0.3.23",
   "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",