magicrew-auth 0.0.0-stage → 0.3.6

package/CHANGELOG.md

@@ -0,0 +1,176 @@
+# 更新记录
+
+## 0.3.6
+
+**修：添加第二个账号时网页闪一下就关，magpie 里没多出账号**
+
+- 症状：点「添加账号」→ 浏览器正常弹出 → 一两秒内自己关掉；用户确实也登录成功了，但账号列表里没有新账号
+- 根因：登录浏览器**复用**同一个 profile（`~/.cache/magpie/magicrew-login-profile`）。第二个窗口一打开，
+  localStorage 里就是上一个账号的 `MAGIC:user:authorization` / `organizationCode`，`waitForCreds`
+  第一轮（1.5 秒）读到它 → 判定登录完成 → 关窗；magpie 拿到的 `accountId` / `uid` 与已有账号完全相同，
+  按契约「同 accountId + 同 uid → 替换旧账号」→ 不新增
+- 修法：每次登录一个**一次性** profile（`magicrew-login-<pid>-<ts>-<rand>`），`closeSession()` 关窗后删；
+  `launchLoginBrowser()` 开头先 `sweepProfiles()` 清掉历史复用目录与超过 2 小时的一次性目录
+  （只认本插件造的名字，且只动目录 —— 同前缀的 `.log` 不碰）
+- 第二道防线：`waitForCreds(..., { baseline })` —— 窗口打开时就存在的凭据不算登录成功
+- 代价：每次都要在窗口里重新登录一次（独立 profile 本来也没有日常 cookie），换来「读到的凭据一定是本次的」
+- 判据：`node tools/_verify_profile_scope.mjs`（窗口打开 4 秒后 `READ_CREDS` 必须是空串、关窗后目录必须不存在）
+  + `node tests/login-profile.mjs`
+
+## 0.3.5
+
+**卡片上多一个「承载」徽章：`magpie.carries`**
+
+- 症状：Qoder 插件的卡片有「承载 Qoder 国际版 (qoder.com)、Qoder CN」，Magicrew 没有
+- 成因：那个徽章的数据源是 `provider.MovedOnto`，只认 **magpie 内置订阅被迁移到插件上**。
+  Magicrew 从来不是内置订阅（`internal/provider/migrate.go` 的 `movers` 表），所以永远是空
+- 修法：magpie 加 `magpie.carries` —— 插件在 `package.json` 里自己声明它承载哪些供应商，
+  后端读进 `pluginEntryJSON.Carries`（JSON 字段 `carries`），前端照样画同一个 `pm-chip moved`
+- 本插件声明：`["超级麦吉 (letsmagic.cn)", "MagiCrew (magicrew.ai)"]`
+- 兼容性：**旧 magpie 不认这个字段，直接忽略**；只有带 `carries` 能力的 magpie 才画这个徽章
+
+**上下文窗口的三档优先级，兜底从 256K 提到 1M**
+
+```
+① 用户在 magpie GUI 里手选的「上下文窗口」   ← 最优先，magpie 直接用
+② 模型库（~/.cache/magpie/models.json）查到的真实值
+③ 兜底 1M
+```
+
+- 兜底从 `256_000` 改成 `1_048_576`：给 1M 而实际只有 128K，上游会在超限时报错、用户看得见；
+  给 256K 而实际有 1M，agent 会主动拒绝一段本可以处理的对话 —— 那是静默的能力损失，
+  比报错更难查（`pi-ai detected context overflow` 就是这么来的）
+- 对照官方社区插件：Qoder 纯硬编码（`context: 1_000_000`）；WorkBuddy 硬编码一张表，
+  再从自家 `/v3/config` 的 `maxInputTokens` 覆盖。magicrew 不提供后者，所以查模型库更省事
+
+**发布到 npm：包名 `magicrew-auth`**
+
+- `magpie plugin add magicrew-auth` 从此可用；npm 源的更新按 `version` 检测，有新版本会提示
+- git 源标题仍是 `Magicrew`：npm 拒绝含大写字母的新包名，所以发布走 `npm run publish:npm`
+  —— `publish-npm.mjs` 临时把 `name` 换成 `magicrew-auth`、跑完无论成败都还原（已实测逐字节一致）
+- **README 模型段改版** —— 按 [magpie-plugin-scaffold 0.1.7](https://github.com/MYCF711/magpie-plugin-scaffold/blob/main/README-TEMPLATE.md)：
+  开头写发行商（GLM / DeepSeek / Qwen / Kimi…），不写「支持 N 个模型」；表格只列各家最新 / 热门
+
+## 0.3.4
+
+**上下文窗口向 magpie 的模型库查，不再一律填 256K**
+
+- 症状：`pi-ai detected context overflow for model "magicrew/deepseek-v4.1-flash"` —— 会话明明还能继续
+- 成因：magicrew 的两个模型接口（`/api/v1/flows/models`、`/v1/models`）**都不返回上下文窗口**，
+  早前一律填 `256_000` 当保守值。而 `deepseek-v4.1-flash` 实际是 **1,048,576**，
+  等于把可用容量砍掉四分之三 —— agent 拿 256K 判断"放不下"就拒绝了
+- 修法：`src/model-context.mjs` 向 magpie 自己的 `~/.cache/magpie/models.json` 查
+  （按 `limit.context`，支持全名 / 尾段 / 多厂商前缀取最大），查不到才退回 256K
+- 实测：deepseek-v4.1-flash 1,048,576 · qwen3.5-flash 1,000,000 · glm-5.3-flash 262,144 ·
+  kimi-k3.1-pro 1,048,576 · 查不到的 256,000
+
+## 0.3.3
+
+**key 按账号隔离 + A/B 双槽，保证每个账号至少一把活的**
+
+- **按账号一份文件**：`magicrew-key-<站点>__<org>.json`
+  - 同一站点登两个账号时，第二个登录**不会**覆盖第一个的 key
+  - 账号标识用 `org`（组织码，登录后不变），拿不到才退回 `accountId`
+- **双槽轮换**：续期签到「另一个槽」再切过去，旧的留在原槽当回退 —— 中途出错能切回来
+- **403 自动切槽**：当前这把被上游拒了就换另一槽重试一次（`body` 是字符串时才重发）
+- **实测**：`mgw_55ac` 失效后自动续出 `mgw_0671`（槽 a→b），回退槽保留，新 key 立即可用
+- **实测**：同一把 key 并发 6 个请求全部成功 —— `mgw_` 是账号级凭据，不是会话级，不存在"被占用"
+
+## 0.3.2
+
+**key 收敛到唯一出口 + 三层凭据各有各的保活**
+
+三层有效期，一层比一层长：
+
+| 凭据 | 活多久 | 说明 |
+|---|---|---|
+| 网页 JWT | 30 天 | 登录时签发 |
+| `mgw_` api_key | **2 小时** | 签一把顶一把，旧的当场吊销 |
+| refresh_token | **7 天** | 用一次轮换一次 |
+
+- **所有签发/续期只走 `src/keys.mjs`**，落到 `~/.cache/magpie/magicrew-key-<站点>.json`，**只保留最新一把**
+  - 动机：magpie 的 `auth.refresh` 和 loader 若各有一次签发机会，两份本地凭据会分叉，
+    谁都不确定手里那把是不是服务端认的
+  - ⚠ 早前版本这里写的是「签一把顶一把、旧的当场吊销」—— **那条没验证充分**。
+    实测两把不同时间签发的 `mgw_` key 可以同时有效；到底哪种操作会让旧 key 失效
+    （PUT 续期？只在 refresh_token 轮换时？）还没分清，见 internals 第十四节的更正
+- **首次运行自动接管**：key-store 空时从 magpie 存的凭据接一次，之后全部自管
+- **到期前 10 分钟自动续**（`ensureKey` 在每次请求前检查）
+- **checkin 每天顺手续一次**（24 小时提前量）：一天没请求时也不会让 refresh_token 闲置到 7 天失效
+- **续期串行化**：同一站点同时只跑一个 `renewOnce`，避免并发签多把互相吊销
+- **`writeKey` 校验 key 形状**：只接受 `mgw_` + 20 位以上，测试/占位值不许落盘
+  （曾经因为假 key `mgw_test_key` 被接管落盘，把国际站那把真 key 顶掉）
+- 实测「过夜 key 过期」：把落盘那把的 `expiresAt` 改到 3 小时前 → 来一发请求 →
+  HTTP 200 正常回复，落盘自动换成新 key（耗时 1885ms，含续期）
+
+
+## 0.3.1
+
+- **流式请求补 `stream_options: { include_usage: true }`**（防御性）
+  - magicrew 在 `stream: true` 下默认不返回 usage；补上之后 `[DONE]` 前会多一条
+    `{"choices":[],"usage":{...}}` 的收尾 chunk，流更完整，下游判定"结束了"更有把握
+  - 实测：补之前 `usage=无`，补之后 `finish_reason=stop · usage=有 · 收尾chunk=true · [DONE]=true`
+
+> ⚠ `Stream ended without finish_reason` 的真正根因**不是流式**，而是下面这条
+> 「签新 key 会吊销旧 key」—— 见 docs/internals.md 第十三节。这一项留着是因为
+> 它让流更完整，不是因为它是那个报错的解药。
+
+## 0.3.0
+
+**结构重构：一个针脚一个模块。行为不变，形状变了。**
+
+magpie 是主板 —— 九个针脚，能力全在它那边；插件只填自己那一份。
+原来 `makePlugin` 返回一个大对象把九样东西焊在一起，现在拆成：
+
+```
+index.mjs                 框：把选中的小插头拼起来，不实现任何东西
+src/context.mjs           站点上下文（siteCtx(SITES.cn) → 一个供应商）
+src/store.mjs             三份落盘：模型快照 / 邀请码 / 登录态
+src/clipboard.mjs         剪贴板降级通道
+src/browser-login.mjs     自己拉浏览器 + CDP 读凭据（可选能力，按需加载）
+src/hooks/config.mjs      ① config(cfg)
+src/hooks/methods.mjs     ② auth.methods[]
+src/hooks/refresh.mjs     ③ auth.refresh
+src/hooks/loader.mjs      ④ auth.loader
+src/hooks/usage.mjs       ⑤ auth.usage
+src/hooks/checkin.mjs     ⑥ auth.checkin
+src/hooks/models.mjs      ⑦ provider.models
+src/hooks/headers.mjs     ⑧ chat.headers
+```
+
+- **一个模块坏了不影响别的**：`browser-login` 和 `tasks` 都是运行时按需加载，
+  它们挂了这个插件照常登录（走登录态那条路）、拉模型、报额度
+- **只做一半功能也能用**：不要签到就把那行从 `index.mjs` 的 return 里删掉，别处不用改
+- 每个 hook 文件头写清「magpie 什么时候调它、拿到什么、要返回什么、**不要**做什么」
+
+## 0.2.1
+
+- **删掉「密码登录」** —— 两站都删，只剩浏览器登录与「登录态（JWT + 组织码）」两条。网页登录拿到的 token 一样能签 `mgw_` key，让用户再输一次手机号密码是多余的一步
+- **卡片显示手机号** —— `orgcode12345` 换成 `138****8000`。优先级 手机号 → 邮箱 → 昵称 → 真名（昵称是用户自己填的，新号可以不填也可以乱填）
+- **包名改为 `Magicrew`**，卡片标题就是它，不再显示 `magpie-magicrew-auth`。已装用户需按 HOOKS.md「改名的完整步骤」同步三处键名，或 `plugin rm` 后重装
+- **浏览器登录的 URL 也带 `?invitation=`** —— 原来只有密码登录的 body 带，用户在网页里注册就丢了邀请码
+- **修浏览器起不来**：`magicrew-login-profile` 里残留的 `SingletonLock` / `lockfile` 会让新进程把 URL 转交给一个已退出的实例后自己退出，`DevToolsActivePort` 永远不出现，于是白等 20 秒再降级。现在启动前清掉这些标记，超时收到 8 秒，`closeSession` 用 `taskkill /T /F` 连子进程一起杀
+- **更正一条错误结论**：网页版 354 字符 token（`device_id` 空）**完全可用**，`invitations/info` / `flows/models` / `gateway-tokens` / `quota` 四条全通。之前「不被网关接受一律 2155」是拿过期 token 测出来的
+- **`opened: true` 的语义**：那是「我自己已经开过页面了，你别再开」，传错会点了登录却不弹页面
+
+## 0.2.0
+
+- **一个包两个供应商**：国内「超级麦吉」（`magicrew`）与国际「MagiCrew」（`magicrew-intl`）各占一行，不聚合
+- **支持国际站**：`magicrew.ai` / 网关 `magic-service.magicrew.ai`，49 个可选模型（国内 27 个）
+- **模型不再写死**：按账号实时拉 `/api/v1/flows/models`，账户能选什么就显示什么；登录过的快照只作未登录时的兜底
+- **两套图标**：国内用超级麦吉的卡通角色，国际用 MagiCrew 的黑底六边形，供应商列表里一眼分得开
+- **点一下，全自动**：插件自己拉起浏览器（独立 profile + 调试端口）停在官方登录页，用户在里面登录，插件通过 CDP 读走它自己的 localStorage 拿到 JWT + 组织码 —— 零手动操作；本机没 Chrome/Edge 时降级为「系统浏览器 + 剪贴板」
+- **登录方式只剩两条**：浏览器登录（默认）与手填 JWT + 组织码。手机号+密码那条已删除 —— 网页登录拿到的 token 一样能签 `mgw_` key
+- **卡片显示手机号，不再显示组织码**：`orgcode12345` 换成 `138****8000`。优先级手机号 → 邮箱 → 昵称 → 真名：昵称是用户自己填的（新号可以不填、也可以乱填），手机号是登录凭据本身
+- **包名改为 `Magicrew`**，卡片标题就是它（原来显示 `magpie-magicrew-auth`）；已装的用户需要重装一次
+- 修正：`opened: true` 的语义是「我已自己开过页面」，传错会点了登录却不弹页面
+- 修正：网页版登录态（354 字符，`device_id` 空）**完全可用**，之前「不被网关接受」的结论是拿过期 token 测出来的
+- **邀请码自动滚**：第一次带作者的码，之后每次登录都记住上一个登录账号的码，拿到新的覆盖旧的，存在 `~/.cache/magpie/magicrew-invite-<站点>.json`
+- 国际站 `/v1/chat/completions` 强制 `organization-code`，按站点自动带
+- `max_tokens` 低于 512 时抬到 512（推理模型会把短额度吃光，`content` 返回空串）
+
+## 0.1.0
+
+- 首个版本：国内站「超级麦吉」（`letsmagic.cn`）接入 magpie / OpenCode
+- 手机号+密码登录，网页 JWT 换 `mgw_` api_key，两小时自续
+- 账号当前可选的 27 个语言模型、积分余额、新手奖励自动领取

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 YOUR NAME
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/NOTICE.md

@@ -0,0 +1,33 @@
+# 版权与归属声明
+
+本插件（`magpie-magicrew-auth`）由 MYCF711 编写，以 MIT 许可发布。
+正文见 [`LICENSE`](./LICENSE)。
+
+## 上游服务
+
+- **超级麦吉 / MagiCrew** —— 广东灯塔引擎科技有限公司的产品，其开源部分见
+  [dtyq/magic](https://github.com/dtyq/magic)（Magic Open Source License：Apache 2.0 + 附加限制）。
+  本插件**不复制**该仓库的任何代码，只调用两套云对外公开的 HTTP 接口，
+  接口契约的取证来源见 README 的「参考源」一节与 [`docs/internals.md`](./docs/internals.md)。
+
+## 第三方写法参考
+
+- **[@magpie-community/opencode-workbuddy-auth](https://github.com/magpie-community/plugins/tree/main/packages/workbuddy)**（MIT）
+  —— 「一个包导出多个 `XxxAuthPlugin`，每个站点一个供应商」的组织方式取自这里。
+  本插件按同一模式实现，未复制其代码。
+- **[@magpie-community/opencode-qoder-auth](https://github.com/magpie-community/plugins/tree/main/packages/qoder)**（MIT）
+  —— 同一模式的多站点（四导出）对照例。
+- **[magpie-plugin-template](https://github.com/MYCF711/magpie-plugin-template)**（MIT）
+  —— README / CHANGELOG / NOTICE 的骨架与硬规则。
+
+## 品牌资源
+
+插件内嵌的两张图标来自各站点自己的公开图标文件（抓取日期 2026-10-27）：
+
+| 站点 | 来源 | 用途 |
+|---|---|---|
+| 国内 · 超级麦吉 | `https://www.letsmagic.cn/web/favicon.png` | 供应商图标（512×512 → 128×128） |
+| 国际 · MagiCrew | `www.magicrew.ai` 的 `<link rel="icon">`，托管于其 OSS | 供应商图标（200×200 → 128×128） |
+
+两张图仅用于在 magpie 界面里标识对应供应商，版权归各自权利人所有。
+本项目与广东灯塔引擎科技有限公司无隶属关系，未获其背书。

package/README.md

@@ -1,3 +1,200 @@
-# Temporary Holding Version
-
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+# 超级麦吉 / MagiCrew for magpie
+
+**一个包，两个供应商：国内的 GLM / DeepSeek / Qwen / Kimi，国际再加 Claude / GPT / Gemini —— 原样走它的 OpenAI 兼容网关。**
+
+超级麦吉（`letsmagic.cn`）和 MagiCrew（`magicrew.ai`）是同一产品的两套云。这个插件把它们各接成一个独立供应商 —— 在 magpie 的供应商列表、用量概览、模型目录里各占一行，不聚合、不互相覆盖登录态。
+
+```
+国内   超级麦吉   www.letsmagic.cn     GLM / DeepSeek / Qwen / Kimi / MiniMax / MiMo / 豆包
+国际   MagiCrew   www.magicrew.ai      上面全部，再加 Claude / GPT / Gemini
+协议   OpenAI Chat Completions —— 原生，不是翻译出来的
+计费   积分（预充值，不是月度配额）
+凭证   登录一次 30 天全自动：api_key 两小时自续，refresh_token 自滚
+```
+
+> 上面那排是 2026-10-27 从两站 `GET /api/v1/flows/models` 拉下来核对的。清单会随订阅档位和平台上下架变 —— 所以插件里**没有一张写死的模型清单**，账户能选什么就显示什么。
+
+---
+
+## 功能
+
+- **两个供应商分得开** —— 国内、国际各一行，图标、名字、模型、积分、登录态全部独立
+- **模型跟着账号走** —— 每次登录后按 `/api/v1/flows/models` 实时拉，账户当前能选什么就展示什么，生图和 embedding 不会混进来
+- **积分算得准** —— 余额读的是 `/api/v1/quota/points/total`；空号就显示空，不会被优先派活
+- **登录一次管 30 天** —— 网页 JWT 顶 30 天，`mgw_` api_key 每 2 小时自续，refresh_token 每次续期时自滚
+- **点一下，全自动** —— 插件自己拉起浏览器停在官方登录页，你在里面登（手机号 / 密码 / Google / 邮箱验证码 / 飞书 / 钉钉都行），登录完成那一刻它自己把凭据读走，不用回来点任何东西
+- **登录方式还有两条备选** —— 手机号+密码走 API；或者直接粘 JWT + 组织码
+- **新手奖励自动领** —— 国内站 8 项里 7 项 PUT 即到账，每天跑一次幂等
+- **邀请码自动滚** —— 第一次注册带作者的码，之后每次登录都记住「上一个登录账号」的码，拿到新的就覆盖旧的
+
+---
+
+## 模型
+
+**国内的 GLM、DeepSeek、Qwen、Kimi、MiniMax、MiMo、豆包；国际站再加 Claude、GPT、Gemini 三家。**
+
+登录后按账号实时拉 `/api/v1/flows/models`，账户能选什么就显示什么 —— 下表只列各家**最新**和**热门**的那几款：
+
+| 发行商 | 最新 / 热门 | 上下文 | 国内 | 国际 |
+|---|---|---|---|---|
+| GLM（智谱） | `glm-5.3` · `glm-5.3-flash` | 1M · 256K | ✓ | ✓ |
+| DeepSeek | `deepseek-v4.1-flash` | 1M | ✓ | ✓ |
+| DeepSeek | `deepseek-v4-pro` | 128K | — | ✓ |
+| Qwen（阿里） | `qwen3.8-max` · `qwen3.7-plus` | 1M | ✓ | ✓ |
+| Kimi（月之暗面） | `kimi-k3.1-pro` | 1M | ✓ | ✓ |
+| MiniMax | `minimax-m3` · `minimax-m3.1-flash` | 1M | ✓ | ✓ |
+| MiMo（小米） | `mimo-v2.6-pro` · `mimo-v2.6-flash` | 1M | ✓ | ✓ |
+| 豆包 Seed（字节） | `doubao-seed-2.0-pro` · `doubao-seed-2.0-code` | 256K | ✓ | ✓ |
+| Claude（Anthropic） | `claude-haiku-5.5` | 1M | — | ✓ |
+| GPT（OpenAI） | `gpt-6-luna` · `gpt-5.4-mini` | 1.05M · 400K | — | ✓ |
+| Gemini（Google） | `gemini-3.7-flash` | 1M | — | ✓ |
+
+全量（含生图、向量、各家历史版本）不进 README —— 装好以后模型选择器里看到的才是账号真实的全部。
+
+用的是 `/api/v1/flows/models`（网页模型选择器里眼睛能点到的那些），不是 `/v1/models` —— 后者混着 VIP 锁定、生图、embedding，塞进来用户会选到根本调不动的模型。
+
+上下文按三档取：magpie GUI 里手选 > 模型库（`~/.cache/magpie/models.json`）> 兜底 1M。这两个接口都不返回 `context_length`；早先一律填 256K，把 `deepseek-v4.1-flash` 真实 1M 的窗口砍成四分之一，agent 反而更早拒绝 —— 根因与取舍见 `docs/internals.md` 第十六节。
+
+推理模型会吃 `max_tokens`：`glm-5.3-flash` 给 64 个 token 时 `reasoning_content` 就吃满、`content` 是空串。插件把低于 512 的 `max_tokens` 抬到 512。
+
+两站不是简单叠加：国际站多出 Claude / GPT / Gemini 三家，另有豆包 Seed 1.8 / 2.0-mini / seed-code、Kimi K2.6 / K2.7-code / K3、GLM 5.2、Qwen3.7-max 这些国内没有的档位。
+
+---
+
+## 新手奖励
+
+国内站 8 项任务合计 500 积分，7 项 PUT 一次就完成（实测 1240 → 1540，+300，六项当场入账）。只有「完成第一次 AI 工作」那项服务端认死必须真的跑过一次，PUT 回 `9303`。
+
+国际站 `/api/v1/onboarding/tasks` 现在返回空列表 —— 接口在，这个账号没东西可领。
+
+每天跑一次，幂等。
+
+---
+
+## 邀请码
+
+只一条规则，不需要你选任何东西：
+
+```
+① 固定位置有记录 → 用记录里那个
+② 没有记录     → 用作者的码
+③ 登录成功后   → 查这个账号自己的码 → 覆盖写回
+```
+
+效果：第一次注册带作者的码，之后每次都用「上一个登录成功的账号」的码，一路滚下去。
+
+固定位置：
+
+```
+~/.cache/magpie/magicrew-invite-<站点 id>.json      {"code":"...","at":"..."}
+```
+
+> ③ 不是每次都能成。`/api/v1/invitations/info` 只认带 `device_id` 的 JWT —— 同一个账号同一时刻签的两把，差别就在这一个字段：桌面客户端 438 字符（`device_id` = 64 位 hex）能拿到码，网页版 350 字符（`device_id` 空）回 `2155 用户不存在`。
+> 密码登录走 API、带 device 指纹，滚得动；浏览器登录拿到的是网页那把，滚不动 —— 那就保留旧值，不报错、不挡登录。
+
+奖励口径（上游前端常量，2026-10-27）：
+
+| | 每次注册 | 每次订阅 | 邀请注册封顶 | 总额封顶 |
+|---|---|---|---|---|
+| 国内 | 1,000 | 3,000 | 60,000 | 300,000 |
+| 国际 | 200 | 500 | 10,000 | 30,000 |
+
+---
+
+## 安装
+
+在 magpie 的 **插件 → 发现** 搜 `magicrew`，点**安装**（npm 上的包名是 `magicrew-auth`）。
+
+装完选站点，然后**点第一个「浏览器登录」** —— 没有任何输入框，插件自己把浏览器拉起来：
+
+1. 浏览器窗口弹出，停在官方登录页
+2. 用你平时的方式登进去（手机号 / 密码 / Google / 邮箱验证码 / 飞书 / 钉钉都行）
+3. **登录完成那一刻它自己就接上了** —— 不用回来点任何按钮，不用开 DevTools
+
+原理：插件不是调用系统浏览器，而是自己起一个 Edge / Chrome（独立 profile +
+`--remote-debugging-port`），所以登录成功后能用 CDP 在页面上下文里把它自己的
+localStorage 读走，拿到 JWT 和组织码，签完密钥就关窗。
+
+**每次登录都是一个新的 profile，用完就删。** 这是必须的：共用一个 profile 的话，
+添加第二个账号时窗口一打开，页面里已经躺着上一个账号的凭据 —— 插件会以为登录完成、
+立刻关窗，而 magpie 拿到的还是旧账号（同账号 → 替换，不新增）。
+
+> **为什么必须自己拉浏览器？** 因为 magicrew 没有 OAuth 回调通道 —— 它的登录类型只有 13 种、全是「拿凭据换 token」，没有设备码、没有插件授权、没有一次性 ticket；也没有 WorkBuddy 那种 `/v2/plugin/auth/state` + `/v2/plugin/auth/token` 协议。网页登录成功后 token 只在 `www.magicrew.ai` 的 localStorage 里，而 magpie 打开的是你系统默认那个浏览器，插件够不到它的存储。自己起一个，就够得到了。
+>
+> 本机没装 Chrome / Edge 时自动降级：改用系统浏览器打开，登录完把凭证送进剪贴板，插件从剪贴板读。
+
+不想碰 Console 的话，另外两条：
+
+- **密码登录** —— 手机号 + 密码 + 区号，走 API，全程在 magpie 里
+- **登录态（JWT + 组织码）** —— 手填两个字段：
+
+```
+DevTools → Application → Local Storage → https://www.magicrew.ai
+  MAGIC:user:authorization     → JSON，取 value     = JWT
+  MAGIC:user:organizationCode  → JSON，取 value     = 组织码（12 位小写字母数字）
+```
+
+> 组织码**不能从 JWT 推**。JWT 里只有 `cus.tenant_id`（18 位数字），组织码是另一套短串。缺了它 `/api/v1/*` 回 `2182 用户所在组织不存在`，给错了回 `3035 登录失败`。
+
+### 命令行
+
+```bash
+# npm（推荐：magpie 按 version 检测更新，有新版本会提示）
+magpie plugin add magicrew-auth
+
+# 从仓库源码（拿最新提交，不走 npm；更新按 commit，要手动 update）
+magpie plugin add github:MYCF711/magpie-magicrew-auth
+```
+
+> **两条路的卡片标题不一样**：npm 装 → 卡片标题就是包名 `magicrew-auth`；git 装 → 取 `package.json` 的 `name`，也就是 **`Magicrew`**。功能一样，只是标题。
+> 从旧包名 `magpie-magicrew-auth` 过来的，先 `magpie plugin rm magpie-magicrew-auth` 再装。
+
+装完确认：
+
+```bash
+magpie plugin list
+# magicrew-auth  on
+#   magicrew (超级麦吉, 27 models)  signed in as ...
+#   magicrew-intl (MagiCrew, 49 models)  signed in as ...
+```
+
+两个供应商各一行 —— 这就是「不聚合」的样子。
+
+---
+
+## 常见问题
+
+**两个站要装两次吗？** 不用。一个包导出两个插件，装一次两个供应商都在，各自登录。
+
+**添加第二个账号时，网页闪一下就关了、magpie 里也没多出账号？** 0.3.5 及更早会这样：登录浏览器复用同一个 profile，第二个窗口一打开就读到上一个账号的凭据，于是立刻「登录成功」并关窗 —— 加到的是已有账号。0.3.6 起每次登录用一个一次性 profile（关窗即删），不会再串号。
+
+**npm 上叫 `magicrew-auth`，为什么卡片显示 `Magicrew`？** 卡片标题取包内 `package.json` 的 `name`（`Magicrew`），而 npm 拒绝含大写字母的新包名。发布时用 `publish-npm.mjs` 临时换成 `magicrew-auth`、发完还原 —— 所以 npm 页面是小写包名，git 源装出来是 `Magicrew`。功能完全一样。
+
+**为什么模型列表会变？** 因为清单是从 `/api/v1/flows/models` 实时拉的。订阅档位变了、平台方上下架变了，清单就跟着变 —— 插件里没有需要维护的模型表。
+
+**国际站 `/v1/chat/completions` 报 500，22 字节的纯文本？** 那是缺 `organization-code` 请求头。国内站不需要，国际站强制。插件按站点自动带。
+
+**`glm-5.3-flash` 回复是空的？** 推理 token 吃满了 `max_tokens`。插件已经把低于 512 的抬到 512；还是空就把 `max_tokens` 再调大。
+
+**Android / macOS 也支持吗？** 插件只调 HTTP 接口，跟客户端无关。设备上能登录，这里就能用。
+
+---
+
+## 参考源
+
+| 来源 | 用在哪 |
+|---|---|
+| [dtyq/magic](https://github.com/dtyq/magic)（Apache 2.0 + 附加限制） | 接口契约：`types/login.ts` 的 `invite_code`、`LoginService.ts` 关于「邀请码在创建组织时消费」的注释、`constants/api.ts` 的错误码 |
+| [@magpie-community/opencode-workbuddy-auth](https://github.com/magpie-community/plugins/tree/main/packages/workbuddy)（MIT） | 「一个包导出多个 `XxxAuthPlugin`」的写法：每个站点一个具名导出，各成一个供应商 |
+| [@magpie-community/opencode-qoder-auth](https://github.com/magpie-community/plugins/tree/main/packages/qoder)（MIT） | 同上，四站点四导出的对照例 |
+| [magpie-plugin-template](https://github.com/MYCF711/magpie-plugin-template)（MIT） | README / CHANGELOG / NOTICE 的骨架与硬规则 |
+
+本插件不复制上游代码，只调它的公开 HTTP 接口。完整版权声明见 [`NOTICE.md`](./NOTICE.md)。
+
+---
+
+> 更新记录：[`CHANGELOG.md`](./CHANGELOG.md)
+
+## 许可
+
+MIT。