magicrew-auth 0.3.15 → 0.3.16

package/AGENTS.md

@@ -0,0 +1,116 @@
+# AGENTS.md —— 给 AI 执行者的入口
+
+> 人类请看 [README](./README.md)。这份只回答两件事：**你现在该读哪一份**、
+> **忘了哪一条会静默出错**。
+>
+> 结构照搬 [magpie-plugin-scaffold](../magpie-plugin-scaffold/AGENTS.md) 的入口式写法；
+> 下面第二节是本仓库自己的坑，不是通用套话。
+
+---
+
+## 一、先定位你在哪一步
+
+| 你在做什么 | 必读（按顺序） | 做完的判据 |
+|---|---|---|
+| **改协议 / 接口调用** | [docs/internals.md](./docs/internals.md) 的「三、接口清单」「十二、流式」「十六、上下文窗口」 | 改动在两站（`magicrew` 与 `magicrew-intl`）都验过 |
+| **改登录链路** | internals 的「二、三层凭证」「十一、浏览器登录怎么做到全自动」 | 三条登录路径（本机浏览器 / 浏览器登录 / 手填 JWT）都还能登 |
+| **改 key / 续期** | internals 的「十三、签新 key 会吊销旧 key」「十四、三层凭据的有效期与保活」 | 没引入第二份 refresh_token（会和 `src/keys.mjs` 分叉） |
+| **改模型目录** | internals 的「十六、上下文窗口必须查库」+ HOOKS 十一之二（`free`） | 上下文来自查库；`free` 来自厂商声明，不从 `rate` 反推 |
+| **改签到 / 首任务** | internals 的 checkin 小节（一次性闸门、五种状态） | 不漏发、不重发、失败方向是「宁可晚一轮」 |
+| **代码写完，准备交付** | [CHECKLIST.md](./CHECKLIST.md) 的 **A 表** | A 表全勾 + `node scripts/check.mjs` 退出 0 |
+| **要发版本** | **[UPDATING.md](https://github.com/MYCF711/magpie-plugin-scaffold/blob/main/UPDATING.md)**（脚手架的，七步） | CHECKLIST B 表全勾 + 四条验证 |
+| **用户说「更新了没变化」** | 本文件坑 12（git 源只提示、要手动点更新） | `magpie plugin list` 里的 commit 真的变了 |
+
+**最容易漏的是「要发版本」这一行。** `git push` 只是七步里的第 4 步 ——
+本仓库真踩过：0.3.14 只 push，结果 GitHub 右侧「暂无发布版本」、npm 停在 0.3.8。
+
+---
+
+## 二、本仓库的坑
+
+| # | 症状（出问题时你看到什么） | 判据 | 出处 |
+|---|---|---|---|
+| 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 十三 |
+| 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 十二 |
+| 7 | 模型被标成免费、Free first 一直派到它 | `free` 只认厂商声明（`input_points === 0`），**不能从 `rate === 0` 反推**；价格缺失 = 不列，不猜 | internals 十六 · HOOKS 十一之二 |
+| 8 | 新号邀请奖励不到账 | 国际站判据是**有没有话题**，不是有没有项目 —— 项目打开工作台就会自动建 | internals checkin 小节 |
+| 9 | 一个号天天烧一次模型积分 | 首任务是**每账号一辈子一次**（`isAutoChatSettled`），别改回按日期；失败才重试，最多 3 次 | internals checkin 小节 |
+| 10 | 话题接口抖一下，就白花一次积分去补消息 | 查不到判据时**这次不发**、不落标记、不计数 —— 消息发出去花钱且不可撤 | `src/tasks.mjs` 的 `autoFirstChat` |
+| 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 |
+
+补充一条最容易误信的旧说法：
+
+| 症状 | 判据 | 出处 |
+|---|---|---|
+| 以为 checkin 会「顺带续 key」 | **从来没有**。`src/hooks/checkin.mjs` → `src/tasks.mjs` 全链路没 import 过 `ensureKey`；保活由 magpie 按 `refreshLead` 主动调 `auth.refresh` | internals 十四 · CHANGELOG 0.x |
+
+---
+
+## 三、命令
+
+```bash
+# 合规检查（脚手架里的脚本，直接指到本仓库）
+node ../magpie-plugin-scaffold/scripts/check.mjs .
+
+# 两站都要能跑：真实登录态在 ~/.cache/magpie/magicrew-session-<siteId>.json
+#   siteId = magicrew（国内） / magicrew-intl（国际）
+# 探针脚本必须放进仓库目录用 magpie 自带的 bun 跑（node 连不上国际站域名）：
+~/.cache/magpie/bun/1.4.4/magpie-bun.exe ./_probe/xxx.mjs
+
+# 打包面预演
+npm pack --dry-run
+
+# 发布（包内 name 是 Magicrew，npm 包名是 magicrew-auth）
+npm run publish:npm
+
+# Release：本仓库没有 .github/workflows，必须手工建
+git tag v0.3.16 && git push origin v0.3.16
+#   然后 POST /repos/MYCF711/magpie-magicrew-auth/releases
+```
+
+---
+
+## 四、两个交付门
+
+**门 1 · 代码交付**
+
+```
+□ node ../magpie-plugin-scaffold/scripts/check.mjs . 退出码 = 0
+□ CHECKLIST.md 的 A 表全勾
+□ 改动涉及的站点都跑过（国内 / 国际，别只验一个）
+```
+
+**门 2 · 发布**
+
+```
+□ CHECKLIST.md 的 B 表全勾（七步）
+□ 四条验证：npm view magicrew-auth version / tarball 内容 / magpie plugin list / Release 在
+```
+
+⚠ 没过门 2 不许说「已发布」。
+
+---
+
+## 五、文档地图
+
+| 文件 | 管什么 | 什么时候读 |
+|---|---|---|
+| [README](./README.md) | 用户看的门面：功能、模型、安装 | 改用户可见行为时 |
+| [docs/internals.md](./docs/internals.md) | 16 章实测：两站同构、三层凭证、接口清单、协议要点 | 改代码前按章查 |
+| [CHANGELOG.md](./CHANGELOG.md) | 每版一节 | 写新版本时 |
+| [CHECKLIST.md](./CHECKLIST.md) | 两张勾选表 | 两个交付门 |
+| 脚手架 [AGENTS.md](../magpie-plugin-scaffold/AGENTS.md) | 通用坑（九项清单、三条铁律、check 能查什么） | 第一次接触这个插件族时 |
+
+---
+
+## 六、这份文件的维护规矩
+
+1. 任何一次「不报错、要几小时才找到」的坑，收工前在第二节加一行（症状 → 判据 → 出处）。
+2. 第二节只放一句话判据，论证留在 `docs/internals.md`。
+3. 判据要能当场验证（命令、字段、界面现象），写不成判据的是感想。

package/CHANGELOG.md

@@ -1,5 +1,21 @@
 # 更新记录
 
+## 0.3.16
+
+**加了给 AI 执行者的入口 —— 因为「发布」这一步真的被漏过一次**
+
+不是功能改动。这个仓库 0.3.14 发布时只 `git push`，没发 npm、没打 tag、没建 Release，
+结果 GitHub 右侧一直挂着「暂无发布版本」、npm 停在 0.3.8。根因不是不知道有发布流程，
+是它没进阅读路径。
+
+- **新增 `AGENTS.md`** —— 按「你在哪一步」给阅读顺序（改协议 / 改登录 / 改 key /
+  改模型 / 改签到 / 交付 / 发版），外加**本仓库 13 条会静默出错的坑**，
+  每条带「症状 → 判据 → 出处章节」。坑都来自 `docs/internals.md` 的实测记录
+- **新增 `CHECKLIST.md`** —— A 表代码交付前 14 项（含「两站都验过」「上下文来自查库」
+  「流式带 include_usage」「话题查不到就不发」），B 表发版前七步带命令与判据
+- [README](./README.md) —— 顶部加三行指路：改代码 / 发版前先看这两份；发布是七步，
+  `git push` 只是第 4 步
+
 ## 0.3.15
 
 **修掉「网页已经登好、magpie 里一直转圈等」—— 弹窗永远拉不起来**

package/CHECKLIST.md

@@ -0,0 +1,110 @@
+# CHECKLIST —— 两张表，两个交付门
+
+> 给 `magpie-magicrew-auth`。`scripts/check.mjs`（在脚手架仓库里）只查**能自动查的那部分**；
+> 下面这些查不到，但漏了照样出事，而且通常**不报错**。
+>
+> 逐条勾，勾不上就是还没好。表格里的「判据」都能当场验。
+
+---
+
+## A 表 · 代码交付前
+
+```
+□ 1. config.models 有内容
+      判据：插件装上后模型列表不是空的（未登录时也要有静态表）
+      出处：README
+
+□ 2. authorize() 立刻返回
+      判据：登录时没有长时间转圈
+      出处：docs/internals.md 二
+
+□ 3. 两站都验过
+      判据：国内（magicrew）与国际（magicrew-intl）各跑一次目标路径，都通
+      出处：internals 一 —— 同一个 Go 服务，一边过不代表另一边过
+
+□ 4. 国际站请求带 organization-code
+      判据：/v1/chat/completions 不是 HTTP 500 + 22 字节裸文本
+      出处：internals 一 / 五
+
+□ 5. 上下文窗口来自查库，不是保守常数
+      判据：模型条目的 limit.context 与实际能吃的长度对得上（早前一刀切 256K 是错的）
+      出处：internals 十六
+
+□ 6. 流式请求带 stream_options.include_usage
+      判据：流式回复里有 usage，额度真的扣了
+      出处：internals 十二
+
+□ 7. 模型 free 来自厂商声明，不是从 rate 反推
+      判据：input_points === 0 才 free；缺失就不列，不猜
+      出处：internals 十六 · HOOKS 十一之二
+
+□ 8. 只有一处持有 refresh_token
+      判据：`src/hooks/refresh.mjs` 没有绕过 `src/keys.mjs`；没有第二次签发 key 的调用
+      出处：internals 十三 / 十四
+
+□ 9. 首任务仍是一次性闸门
+      判据：isAutoChatSettled 还在用；失败最多 3 次；不落日期格式
+      出处：internals checkin 小节
+
+□ 10. 话题查不到时「这次不发」
+      判据：fetchProjectTopics 抛错时不写标记、不计数、不发送
+      出处：src/tasks.mjs 的 autoFirstChat
+
+□ 11. 登录三条路径都还能登
+      判据：本机浏览器接上 / 浏览器登录 / 手填 JWT，各走一次
+      出处：internals 十一
+
+□ 12. 浏览器可执行文件是逐个试候选，不是写死一个名字
+      判据：Windows 上点登录能起浏览器（文件名随浏览器版本变）
+      出处：internals 十一
+
+□ 13. 没有写 magpie 的市场缓存
+      判据：src 里搜不到 plugin-market.json
+      出处：CHANGELOG 0.1.9 那段事故
+
+□ 14. node ../magpie-plugin-scaffold/scripts/check.mjs . 退出码 = 0
+      判据：末尾「失败 0」
+```
+
+---
+
+## B 表 · 发版前（七步，一步不能少）
+
+> ⚠ **`git push` 只是第 4 步。** 本仓库真踩过：0.3.14 只 push，
+> 结果 GitHub 右侧一直写着「暂无发布版本」、npm 停在 0.3.8。
+
+```
+□ 第 0 步 · 写 CHANGELOG
+      判据：顶部是这个版本的一节，一条一行，说用户能感知的变化
+
+□ 第 1 步 · bump version
+      命令：npm version patch --no-git-tag-version
+      判据：package.json 的 version 变了（同版本重打会命中 bun 缓存）
+
+□ 第 2 步 · 打包面预演
+      命令：npm pack --dry-run
+      判据：清单里有 README.md / CHANGELOG.md / docs / AGENTS.md / CHECKLIST.md
+
+□ 第 3 步 · 提交
+
+□ 第 4 步 · 推到默认分支
+      命令：git push origin main
+      判据：git 源装的人靠这里检测 —— 推别的分支不算
+
+□ 第 5 步 · npm publish
+      命令：npm run publish:npm          ← 包内 name 是 Magicrew，npm 包名是 magicrew-auth
+      判据：返回 + magicrew-auth@<版本>，且 package.json 的 name 已还原成 Magicrew
+
+□ 第 6 步 · tag + Release
+      命令：git tag v<version> && git push origin v<version>
+      本仓库**没有** .github/workflows ⇒ Release 必须手工建：
+        POST /repos/MYCF711/magpie-magicrew-auth/releases
+        { tag_name, target_commitish:"main", name, body:<CHANGELOG 该版本段>, draft:false }
+      判据：tag 与 version 一致；Release 不是 draft
+
+□ 第 7 步 · 四条验证
+      ① npm view magicrew-auth version       → 新版本（登记可能延迟 1-2 分钟）
+      ② 下载 dist.tarball 解包看内容          → 要看到新代码，不只看版本号
+      ③ magpie plugin list                   → commit 变了（git 源看 commit 不看 version）
+      ④ GET /releases/tags/v<version>        → 200 且 draft=false
+```

package/README.md

@@ -14,6 +14,11 @@
 
 > 上面那排是 2026-10-27 从两站 `GET /api/v1/flows/models` 拉下来核对的。清单会随订阅档位和平台上下架变 —— 所以插件里**没有一张写死的模型清单**，账户能选什么就显示什么。
 
+> **改代码 / 发版本之前**：先看 [AGENTS.md](./AGENTS.md) —— 按「你在哪一步」给阅读顺序，
+> 外加本仓库 13 条**会静默出错**的坑（症状 → 判据 → 出处）。交付与发版逐条走
+> [CHECKLIST.md](./CHECKLIST.md) 的两张表。
+> 发布是**七步**，`git push` 只是第 4 步。
+
 ---
 
 ## 功能

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "magicrew-auth",
-  "version": "0.3.15",
+  "version": "0.3.16",
   "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",
@@ -12,6 +12,8 @@
     "index.mjs",
     "src",
     "README.md",
+    "AGENTS.md",
+    "CHECKLIST.md",
     "CHANGELOG.md",
     "NOTICE.md",
     "docs"