magicrew-auth 0.3.26 → 0.3.28

package/docs/internals.md

@@ -1169,6 +1169,128 @@ HTTP 400
 `raw → 400 tools.40.../items`；过 `rewriteRequestBody` 后 `→ 200`。
 国内站、国际站都验过。
 
+### 三、`items` **子树内部**的 union / 空 schema → `400 invalid JSON Schema`
+
+**症状**（2026-10-28，DSH 经 magpie 网关调 DeepSeek-V4.1-Flash）：
+
+```
+本轮运行失败 400: {"code":null,"message":"超级麦吉: HTTP 400 请求错误:
+{\"error\":{\"code\":\"InvalidParameter\",\"message\":\"tools.40.function.parameters/
+ properties/functions/items: invalid JSON Schema; check the schema keywords
+ and references Request id: ...\",\"param\":\"\",\"type\":\"BadRequest\"}}",
+ "param":null,"type":"invalid_request_error"}
+```
+
+**报错路径与上面第二节一模一样，但请求里根本没有空的 `items`** —— 这是本节存在的理由。
+0.3.24 的 `loosenEmptyItems()` 只删 `items` **自己**的空对象，管不到 `items` **内部**。
+
+#### 根因：上游对数组元素的 schema 比对根节点更严
+
+**实测**（2026-10-28~29，直打上游、同一把 key、同一份请求、只改这一个字段；
+复跑脚本 `_probe/items-subtree-upstream.mjs`，稳定性统计 `_probe/items-subtree-stability.mjs`）：
+
+| 位置 | 形态 | 结果 |
+|---|---|---|
+| `items` 内部 | `anyOf` / `oneOf` / `allOf` | **400** |
+| `items` 内部 | `not` / `const` | **400** |
+| `items` 内部 | `if` + `then`（`else` 同理） | **400** |
+| `items` 内部 | `{}`（空 schema） | **400** |
+| `items` 内部 | `items` 本身是**数组**（draft-04 tuple 形式） | 国内站 200 / **国际站 400**（两站不一致） |
+| `items` 内部 | `type` / `enum` / `pattern` / `minLength` / `minItems` / `format` / `$ref` / 数值边界 | 200 |
+| `items` 内部 | `type:["object","string","number","boolean","array","null"]` | 200（**「任意值」的合法写法**） |
+| **顶层 parameters** | `anyOf` / `const` / `not` / `{}` | **200** |
+
+⇒ **同样形态放在顶层上游收，放进 `items` 子树就炸**。这条边界是本节的关键：
+改写必须精确落在 `items` 之下，全局摊平 union 会白白丢掉顶层那些上游**认**的约束。
+
+⇒ 还有一条纪律：**「任意值」不能写成 `{type:"object"}`** —— 那会把「任意」收紧成
+「只能是对象」。`{}` 与 `true` 在这层都被拒，只能落成显式的六类型 `type` 数组。
+
+#### 命中来源：MCP 工具的 schema
+
+不是客户端手写，而是 **MCP 服务器**声明的工具 schema。REA MCP 的
+`mcp__rea__build_call_path`、`mcp__rea__compare_application_versions` 等
+**7 个工具**的 `functions` 数组参数，元素 schema 用了：
+
+- `anyOf: [{…}, {type:"null"}]` —— 可选参数的标准写法；
+- `oneOf` —— 同类互斥分支；
+- `{}` —— 空 schema（如 `normalized_result`、`raw_result` 的分支）。
+
+一份 65 工具的请求里 7 个工具中招 ⇒ **整轮 400**（上游一次只报第一个坏位置，
+所以报错里的 `tools.N` 序号会随工具表顺序变 —— 别拿序号定位问题）。
+
+#### 修法：`loosenItemsSchema()`
+
+只作用于 `items` 子树：
+
+```
+anyOf / oneOf / allOf  → 取一个分支内联（分支本身先递归修）
+                          ⚠ 优先取**非纯 null** 的分支 —— `anyOf:[{…},{type:"null"}]`
+                            取第一个正好；顺序反过来时照抄第一个会把「可选」压成
+                            「只能 null」，那是收紧
+not / const            → 删除
+if / then / else       → 删除
+{}                     → {type:["object","string","number","boolean","array","null"]}
+items 是数组（tuple）   → {type:[同上]}   ← 国际站对数组形式回 400
+```
+
+全部是**降级放宽**，方向安全（宁可约束松一点，也不要整轮失败）：
+
+- union 取一个分支：`anyOf:[{…},{type:"null"}]` 的分支正是「非空」那个；
+- `const` 删除 ⇒ 「只能是这一个值」变「任意值」，放宽；
+- `not` / `if+then+else` 无等价物，删掉同样是放宽；
+- `{}` → 六类型 `type` 数组：**与空 schema 严格等价**（六种 JSON 类型全覆盖 = 任意值），
+  不是「等价于 `{type:"object"}`」—— 那会收紧。
+
+⚠ **删除会删空节点**：`{const:"x"}`、`{not:{…}}`、`{if:…,then:…}` 删完就成 `{}`，
+而空 schema 在 `items` 子树里**仍然 400**。所以删完必须在同一个函数里再查一次空对象并补成
+「任意值」—— 漏了这一步，改写看起来生效、实际仍然整轮 400（PR #10 初版就漏在这里，
+`not` / `const` 两例改写后实测仍 400）。
+
+递归同样遵守 schema 位置纪律（`walkSchema` 那套 `SCHEMA_MAPS` / `SCHEMA_LIST` /
+`SCHEMA_ONE`）：只进 `properties` 的**值**、union 的**分支**、`items` 的**值**……
+不碰 `enum` / `default` / `examples` 里的字面值。
+
+#### 端到端验证（2026-10-29）
+
+真实报障形态的 65 工具请求体（58 个填充 + 7 个中招的 REA 工具，脚本里现成构造）：
+
+| 站点 | 原样 | 过 `rewriteRequestBody` |
+|---|---|---|
+| 国内站 `i-magic-service.letsmagic.cn`（deepseek-v4.1-flash） | `400 … invalid JSON Schema` | **200** |
+| 国际站 `magic-service.magicrew.ai`（deepseek-v4.1-flash） | `400 … tools.58…/items` | **200** |
+
+单点矩阵（21 个形态 × raw / 改写后，两站各跑一遍）：**所有 `items` 子树非法形态
+400 → 200**，顶层对照形态保持 200 不动，合法关键字（`enum` / `pattern` / `$ref`）原样保留。
+
+复跑方式：
+
+```bash
+# 国内站（node 直连即可）
+node ./_probe/items-subtree-upstream.mjs
+# 国际站（node 连不上该域名，用 magpie 自带的 bun）
+~/.cache/magpie/bun/1.4.4/magpie-bun.exe ./_probe/items-subtree-upstream.mjs intl
+# 稳定性统计（同一形态连发 N 轮，判「恒 400」还是「偶发」）
+node ./_probe/items-subtree-stability.mjs 3 cn
+```
+
+⚠ **上游的校验会变，别把单次探针当定论**。2026-10-29 这一夜实测到的完整时间线：
+
+| 本地时间（UTC+8） | 站点 | `items` 子树非法形态（A 组 7 个） | tuple 形式 / `if+then` |
+|---|---|---|---|
+| 00:19 | 国内 | **稳定 400**（7/7） | 200 / 400 |
+| 00:24 | 国际 | **稳定 400**（7/7） | 200 / 400 |
+| 00:29（3 轮 ×21 形态统计） | 国内 | 已全变 **200** | 200 |
+| 00:35 | 国内 | 仍全 **200**（含真实报障形态的 raw） | 200 |
+
+⇒ 上游在 00:25~00:29 之间放宽了这层校验（灰度或发布，未确认）。
+**这不改变本节的结论**：改写现在是「保险」而不是「必需」——上游随时可能收回去
+（同一夜里已经出现过波动），而改写的代价只是一次遍历。
+
+所以判「某个形态要不要改写」要看多轮统计，别信单次探针：
+`_probe/items-subtree-stability.mjs` 就是为这件事写的（`N 轮 × 每形态 raw/改写各一次`，
+输出 `400 次数 / 轮数`）。
+
 ### 为什么算插件的事，不算客户端的事
 
 按规范 `{}` 与 `true` 等价，客户端没写错；**上游的兼容性不足**。

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "magicrew-auth",
-  "version": "0.3.26",
+  "version": "0.3.28",
   "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/captcha.mjs

@@ -1,17 +1,32 @@
-// 无头登录的底层：旋转验证码 + 手机验证码换取登录态
+// 无头登录的底层：旋转验证码 + 手机/邮箱验证码换取登录态
 //
 // 全部是**纯 HTTP**，不开浏览器、不读 localStorage。协议是从网页版
-// `SMSVerificationCodeForm` chunk 里逆出来的，每一步都实测过
+// `SMSVerificationCodeForm` / `LoginCoreForm` chunk 里逆出来的，每一步都实测过
 // （见 docs/internals.md「无头登录」一节）：
 //
-//   ① POST /captcha/generate   { account_type, mobile, state_code }
+//   ① POST /captcha/generate   { account_type, mobile, state_code }      手机
+//                              { account_type, email }                   邮箱
 //        → { token, image(data:image/webp;base64,…), expire_time }
 //   ② 算角度 → angle = enc(deg, n)
 //   ③ POST /captcha/verify     { token, angle, account_type, mobile, state_code }
+//                              { token, angle, account_type, email }
 //        → { verified: true, business_token: "biz_…" }
-//   ④ POST /v4/user/send-sms   { type, phone, state_code }
-//        + header `X-Captcha-Token: <business_token>`
-//   ⑤ POST /v4/user/login      { type: "phone_captcha", phone, state_code, code, device }
+//   ④ 发验证码（两条路**是两个端点**，别混）：
+//        手机 POST /v4/user/send-sms     { type, phone, state_code }
+//        邮箱 POST /v4/user/send-email   { email, type }
+//        + header `X-Captcha-Token: <business_token>`，type 都是 "account_login"
+//   ⑤ 换登录态（同样是两个端点）：
+//        手机 POST /v4/user/login        { type:"phone_captcha", phone, state_code, code, device }
+//        邮箱 POST /v4/user/login-email  { email, captcha, device }
+//
+// ⚠ 邮箱那条为什么走 `/v4/user/login-email` 而不是 `/v4/user/login`：
+//   实测（2026-10-28，两站）——往 `/v4/user/login` 发任何 type（email / email_captcha
+//   / email_code）都回 2000「phone 字段是必须的」，服务端根本不认邮箱。
+//   前端 `UserApi` 里也是两条独立方法：`loginByEmail()` → `/v4/user/login-email`，
+//   并且它显式 `delete("organization-code")`。
+//
+// ⚠ 邮箱那条的**验证码字段名是 `captcha`，不是 `code`** —— 实测发 `code` 回
+//   2000「captcha 字段是必须的」；发 `captcha` 回 2168「验证码错误」。
 //
 // ⚠ 三个域名各管一段，别混：
 //     www.<站点>            → 前端页面（只用来取 Origin，别的没用）
@@ -23,6 +38,34 @@
 //      · 「验证不存在或已过期」 expire_time 给 10 分钟
 //      · 「验证提交过于频繁」  连续批量提交会被拦
 //   ⇒ 不能枚举角度，一次要算准；失败就换图重来。
+//
+// ═══════════════════════════════════════════════════════════════════════
+// 那张旋转图到底能不能绕开（2026-10-29 逐条实测，别再来一遍）
+// ═══════════════════════════════════════════════════════════════════════
+//
+// 结论：**只有「这个号已注册」这一条免费通道**，其余一律必须看懂图。
+//
+// ① 已注册的号 —— 服务端**不出图**：`/captcha/generate` 直接回 `business_token`。
+//      实测：已注册邮箱 → business_token；没注册过的邮箱 → token + image。
+//      ⇒ 「把我已有的账号加进 magpie」根本不需要识图模型（见 headless.mjs 里
+//        startCodeLogin 的「先取图、再判模型」顺序）。
+//
+// ② 新号的答案**不在前端**，也不在图里：
+//      · 前端提交的 `angle` 就是**用户拖动的角度**（`verify(r)` → 这个文件里的
+//        encodeAngle），前端不知道正确答案 —— 知道的话就不会让你拖了；
+//      · 图里没有任何元数据：解剖 webp 只有 `VP8X` / `ALPH` / `VP8` 三个 chunk，
+//        没有 EXIF / XMP / ICC / 自定义块，字符串扫描也是空的；
+//      · 服务端强制：`verify` 不传 angle → 「angle 字段是必须的」；乱填 →
+//        「验证失败，请重试」；发码不带 `X-Captcha-Token`（哪怕带上账号自己的 JWT
+//        和 organization-code）→ 「需要验证码验证」。
+//      ⇒ 答案 = 服务端生成图时随机定的角度，存在它自己的会话里（10 分钟过期）。
+//        要过它只有两条路：识图模型，或人眼看。
+//
+// ③ 不经过验证码的登录入口只有两条，都不是邮箱验证码的替代品：
+//      · 手机号 + 密码 → `POST /api/v1/sessions {type:"phone_password"}`
+//      · 本机浏览器里已登录 → 读它的 localStorage（见 local-browser.mjs）
+//      邮箱 + 密码（`type:"email_password"`）端点认这个 type，但要账号**事先设过
+//      密码** —— 实测对一个已注册邮箱回 `33002 账号不存在`，不能当通用路。
 
 /** 服务端只认这一套 Unicode；错误码直接用数字，日志里好 grep */
 export const CAPTCHA_CODE = {
@@ -44,6 +87,33 @@ export function keewoodOf(site) {
   return site.id === "magicrew" ? "https://i-keewood-service.teamshare.cn" : "https://keewood-service.magicrew.ai"
 }
 
+/**
+ * 「这条链路在给谁发验证码」→ 服务端要的那几个字段。
+ *
+ * 手机和邮箱走的是**同一套 captcha 协议**，只有三处不同，全收敛在这里：
+ *   ① 标识字段：`mobile` + `state_code` vs `email`
+ *   ② `account_type`：`"mobile"` vs `"email"`
+ *   ③ 端点：`/v4/user/send-sms` + `/v4/user/login` vs
+ *      `/v4/user/send-email` + `/v4/user/login-email`
+ *
+ * ⚠ 邮箱**不带 `state_code`** —— 前端邮箱表单的初始值里就没有这个字段
+ *   （实测抓到的请求体逐字符是 `{"account_type":"email","email":"…"}`）。
+ *
+ * @param {{mobile?:string, stateCode?:string, email?:string}} ident
+ * @returns {{account_type:"mobile"|"email", mobile?:string, state_code?:string, email?:string}}
+ */
+export function identFields(ident = {}) {
+  const email = String(ident?.email ?? "").trim()
+  if (email) return { account_type: "email", email }
+  const mobile = String(ident?.mobile ?? "").replace(/[\s-]/g, "")
+  return { account_type: "mobile", mobile, state_code: ident?.stateCode || "+86" }
+}
+
+/** 这条链路是手机还是邮箱 —— 决定走哪两个端点 */
+export function identKind(ident = {}) {
+  return String(ident?.email ?? "").trim() ? "email" : "mobile"
+}
+
 /**
  * 拖动角度 → 服务端要的 angle 字符串。
  *
@@ -109,14 +179,12 @@ async function postJSON(url, body, { headers = {}, timeoutMs = 20_000 } = {}) {
   return { status: res.status, text, json }
 }
 
-/** ① 取图。返回 null 表示服务端认为这个号**已经注册**，直接给了 business_token（跳过验证） */
-export async function generateCaptcha(site, { mobile, stateCode = "+86" } = {}) {
+/** ① 取图。服务端认为这个号**已经注册**时直接给 business_token（跳过验证） */
+export async function generateCaptcha(site, ident = {}) {
   const host = keewoodOf(site)
-  const { json } = await postJSON(`${host}/captcha/generate`, {
-    account_type: "mobile",
-    mobile,
-    state_code: stateCode,
-  }, { headers: { origin: site.web } })
+  const { json } = await postJSON(`${host}/captcha/generate`, identFields(ident), {
+    headers: { origin: site.web },
+  })
 
   const data = json?.data ?? {}
   if (data.business_token) return { registered: true, businessToken: data.business_token }
@@ -131,16 +199,14 @@ export async function generateCaptcha(site, { mobile, stateCode = "+86" } = {})
   }
 }
 
-/** ③ 提交角度 */
-export async function verifyCaptcha(site, { token, deg, mobile, stateCode = "+86" }) {
+/** ③ 提交角度（手机 / 邮箱同一套，标识字段由 identFields 决定） */
+export async function verifyCaptcha(site, { token, deg, ...ident }) {
   const host = keewoodOf(site)
   const n = randomN()
   const { json } = await postJSON(`${host}/captcha/verify`, {
-    account_type: "mobile",
     token,
     angle: encodeAngle(deg, n),
-    mobile,
-    state_code: stateCode,
+    ...identFields(ident),
   }, { headers: { origin: site.web } })
 
   const data = json?.data ?? {}
@@ -149,28 +215,42 @@ export async function verifyCaptcha(site, { token, deg, mobile, stateCode = "+86
 }
 
 /**
- * ④ 发短信。businessToken 缺了/假的都会被打回来，所以它必须是真的。
+ * ④ 发验证码。businessToken 缺了/假的都会被打回来，所以它必须是真的。
  *
  * ⚠ `type` 是 **`"account_login"`**，不是 `"login"`、也不是登录枚举里的 `phone_captcha`。
  *   填错的表现是「服务异常，请联系管理员」(9999) —— 后端内部炸了，不是参数校验失败，
  *   所以从错误信息上完全看不出是 type 的问题。这个值是从浏览器真实请求里抓到的：
- *     {"type":"account_login","phone":"199…","state_code":"+86"}
- *   ⇒ 别再按直觉改它。
+ *     手机 {"type":"account_login","phone":"199…","state_code":"+86"}
+ *     邮箱 {"email":"…","type":"account_login"}
+ *   ⇒ 别再按直觉改它。两站实测：邮箱发 `type:"login"` 同样回 2000「服务异常」。
+ *
+ * ⚠ 邮箱和手机是**两个端点**：`/v4/user/send-email` vs `/v4/user/send-sms`。
+ *   把邮箱发去 send-sms 会 404（`/v4/user/send-sms` 只认 phone）。
  */
-export async function sendSms(site, { phone, stateCode = "+86", businessToken, type = "account_login" }) {
+export async function sendCode(site, ident = {}, { businessToken, type = "account_login" } = {}) {
   const host = keewoodOf(site)
-  const { json } = await postJSON(`${host}/v4/user/send-sms`, {
-    type,
-    phone,
-    state_code: stateCode,
-  }, { headers: { origin: site.web, "X-Captcha-Token": businessToken || "" } })
+  const f = identFields(ident)
+  const isEmail = f.account_type === "email"
+  const path = isEmail ? "/v4/user/send-email" : "/v4/user/send-sms"
+  const body = isEmail
+    ? { email: f.email, type }
+    : { type, phone: f.mobile, state_code: f.state_code }
+
+  const { json } = await postJSON(`${host}${path}`, body, {
+    headers: { origin: site.web, "X-Captcha-Token": businessToken || "" },
+  })
 
   if (json?.code === CAPTCHA_CODE.OK) return { ok: true }
-  return { ok: false, message: json?.message ?? "发送短信失败" }
+  return { ok: false, message: json?.message ?? "发送验证码失败" }
+}
+
+/** 旧签名兼容：手机号发短信 */
+export async function sendSms(site, { phone, stateCode = "+86", businessToken, type = "account_login" }) {
+  return sendCode(site, { mobile: phone, stateCode }, { businessToken, type })
 }
 
 /**
- * ⑤ 验证码换登录态。
+ * ⑤ 验证码换登录态（手机 / 邮箱两个端点）。
  *
  * ⚠ `device` 是必须的，而且结构是一层层试出来的：
  *     缺 device        → 「系统异常」(9999)
@@ -179,7 +259,7 @@ export async function sendSms(site, { phone, stateCode = "+86", businessToken, t
  *     { id, name }     → 放行，返回 2168「验证码错误」
  *   ⇒ { id: 64 位 hex, name: "web" } 就够。
  *
- * ⚠ `auto_register` / `redirect` 一个都不能省（这是网页表单的初始值，抠出来的）：
+ * ⚠ 手机那条的 `auto_register` / `redirect` 一个都不能省（这是网页表单的初始值，抠出来的）：
  *
  *     { phone, state_code, code, auto_register: true,
  *       type: "phone_captcha", redirect: window.location.href }
@@ -188,29 +268,52 @@ export async function sendSms(site, { phone, stateCode = "+86", businessToken, t
  *   · `redirect` 是**当前页面的 URL**，服务端从它上面取 `?invitation=<码>`。
  *     ⇒ **邀请码是靠 redirect 传的，不是独立字段**。这就是为什么浏览器登录的
  *       URL 必须带 `?invitation=`：不带，新注册的号就没有邀请关系。
+ *
+ * ⚠ 邮箱那条**验证码字段叫 `captcha`，不叫 `code`**（实测：发 code 回
+ *   2000「captcha 字段是必须的」；发 captcha 回 2168「验证码错误」）。
+ *   端点也不同：`/v4/user/login-email`，前端调它时会先 `delete("organization-code")`。
+ *   `auto_register` / `redirect` 前端没传，但我们**照传** —— 实测多这两个字段
+ *   服务端不报错（仍回 2168），而新号注册和邀请码都指着它们。
  */
-export async function loginBySmsCode(
+export async function loginByCode(
   site,
-  { phone, stateCode = "+86", code, device, autoRegister = true, redirect },
+  { code, device, autoRegister = true, redirect, ...ident },
 ) {
   const host = keewoodOf(site)
-  const body = {
-    type: "phone_captcha",
-    phone,
-    state_code: stateCode,
-    code,
-    auto_register: autoRegister,
-    device: device ?? { id: makeDeviceId(), name: "web" },
-  }
+  const f = identFields(ident)
+  const isEmail = f.account_type === "email"
+
+  const body = isEmail
+    ? {
+        email: f.email,
+        captcha: code,
+        auto_register: autoRegister,
+        device: device ?? { id: makeDeviceId(), name: "web" },
+      }
+    : {
+        type: "phone_captcha",
+        phone: f.mobile,
+        state_code: f.state_code,
+        code,
+        auto_register: autoRegister,
+        device: device ?? { id: makeDeviceId(), name: "web" },
+      }
   if (redirect) body.redirect = redirect
 
-  const { json, status, text } = await postJSON(`${host}/v4/user/login`, body, {
-    headers: { origin: site.web },
-  })
+  const { json, status, text } = await postJSON(
+    `${host}${isEmail ? "/v4/user/login-email" : "/v4/user/login"}`,
+    body,
+    { headers: { origin: site.web } },
+  )
 
   return { json, status, text }
 }
 
+/** 旧签名兼容：手机号验证码换登录态 */
+export async function loginBySmsCode(site, { phone, stateCode = "+86", ...rest }) {
+  return loginByCode(site, { mobile: phone, stateCode, ...rest })
+}
+
 /** 64 位 hex，形状与网页版 cus.device_id 一致 */
 export function makeDeviceId() {
   const bytes = new Uint8Array(32)

package/src/headless.mjs

@@ -1,8 +1,12 @@
 // 无头登录的编排：一条纯 HTTP 的链路，不开浏览器
 //
-//   取图 → 识图判角度 → 过验证 → 发短信 → （用户填码）→ 换登录态 → 拿组织码
+//   取图 → 识图判角度 → 过验证 → 发验证码 → （用户填码）→ 换登录态 → 拿组织码
 //
-// 每一步都实测过（见 docs/internals.md「无头登录」）：
+// **手机号和邮箱走同一条编排** —— 协议、风控、识图全一样，只有「标识字段」
+// 和「发码 / 登录两个端点」不同，那些差异全在 captcha.mjs 里按 identFields 分派。
+//
+// 每一步都实测过（协议逐字段记在 src/captcha.mjs 头部；两站实测记录见
+// CHANGELOG 0.3.17「手机号验证码」与 0.3.28「邮箱验证码 + 已有账号免图」）：
 //   · 取图/过验证在 keewood 用户中心，纯 JSON，不需要 cookie 或指纹
 //   · 角度必须「一次算准」：同一 token 试错次数有限，且高频会被拦
 //   · 识图模型是用户在 magpie 里选的那个（settings.json 的 vision）
@@ -14,8 +18,9 @@
 import {
   extractCreds,
   generateCaptcha,
-  loginBySmsCode,
-  sendSms,
+  identKind,
+  loginByCode,
+  sendCode,
   verifyCaptcha,
 } from "./captcha.mjs"
 import { decideDegFromImage, readVisionModel } from "./vision.mjs"
@@ -30,14 +35,20 @@ const sleep = (ms) => new Promise((r) => setTimeout(r, ms))
 /**
  * 过掉旋转验证，拿到 business_token。
  *
+ * 手机和邮箱共用：只有传给服务端的「标识字段」不同（`{mobile, stateCode}` / `{email}`）。
+ *
+ * @param {object} site  站点对象（要有 id / web）
+ * @param {{mobile?:string, stateCode?:string, email?:string}} ident
+ * @param {object|null} firstCap 已经取到的那张图（调用方为了让「已注册免图」
+ *   这条短路先跑，会自己先调一次 generateCaptcha）—— 传进来就省一次取图
  * @returns {Promise<{businessToken:string, rounds:number, log:string[]}>}
  */
-export async function passCaptcha(site, { mobile, stateCode = "+86" } = {}) {
+export async function passCaptcha(site, ident = {}, firstCap = null) {
   const log = []
   let lastReason = ""
 
   for (let round = 1; round <= MAX_CAPTCHA_ROUNDS; round++) {
-    const cap = await generateCaptcha(site, { mobile, stateCode })
+    const cap = round === 1 && firstCap ? firstCap : await generateCaptcha(site, ident)
     // 已注册的号，服务端直接给 business_token，连图都不用看
     if (cap.registered) {
       log.push(`第 ${round} 轮：服务端直接放行（该号已注册）`)
@@ -53,7 +64,7 @@ export async function passCaptcha(site, { mobile, stateCode = "+86" } = {}) {
       continue
     }
 
-    const res = await verifyCaptcha(site, { token: cap.token, deg: decided.deg, mobile, stateCode })
+    const res = await verifyCaptcha(site, { token: cap.token, deg: decided.deg, ...ident })
     if (res.ok) {
       log.push(`第 ${round} 轮：deg=${decided.deg}（钟点 ${decided.clock?.toFixed?.(2) ?? "?"}，分歧 ${decided.spread?.toFixed?.(1) ?? 0}）→ 通过`)
       return { businessToken: res.businessToken, rounds: round, log }
@@ -71,45 +82,79 @@ export async function passCaptcha(site, { mobile, stateCode = "+86" } = {}) {
 }
 
 /**
- * 第 1 步：发短信。成功即代表「验证已经过了」——服务端把 business_token 当门票。
+ * 第 1 步：发验证码（短信 / 邮件）。成功即代表「验证已经过了」——服务端把 business_token 当门票。
+ *
+ * ⚠ **顺序很重要：先取图，再决定要不要识图模型。**
+ *
+ *   服务端对**已注册**的号根本不要求过旋转验证 —— `POST /captcha/generate` 直接回
+ *   `business_token`，连图都不给（实测：2026-10-29，已注册邮箱 `…@qq.com` → 免图；
+ *   同一个接口换一个没注册过的邮箱 → 给了 token+image）。
+ *
+ *   所以「加一个我自己已有的账号」这条最常见的路，**根本不需要识图模型**。
+ *   早先把 `readVisionModel()` 的判断放在取图**之前**，等于让没配识图模型的人
+ *   连自己已有的账号都加不进来 —— 那是白拦。现在只有确实要给新号过图时才要求它。
+ *
+ * @throws 需要过图但没配识图模型时，抛带 `code: "no-vision-model"` 的错误，
+ *         让调用方去回退浏览器（而不是在这里瞎猜角度）
  */
-export async function startSmsLogin(site, { mobile, stateCode = "+86" } = {}) {
-  if (!readVisionModel()) {
-    // 调用方应该先判断这个；走到这里说明判断被绕过了 —— 明确报出来，别静默瞎猜
-    throw Object.assign(new Error("没有配置识图模型，不能无头过旋转验证"), { code: "no-vision-model" })
+export async function startCodeLogin(site, ident = {}) {
+  const kind = identKind(ident)
+  const what = kind === "email" ? "邮件" : "短信"
+
+  // ① 先探一次。这一步是纯 JSON、不需要模型，也**不会真的发码**。
+  const first = await generateCaptcha(site, ident)
+
+  let businessToken
+  let rounds
+  let log
+
+  if (first.registered) {
+    // ⚡ 已注册 → 免图直接发码。识图模型在这条路上完全用不到。
+    businessToken = first.businessToken
+    rounds = 0
+    log = ["服务端认为该号已注册 → 免旋转验证"]
+  } else {
+    // ② 新号必须过图：这时才需要识图模型
+    if (!readVisionModel()) {
+      throw Object.assign(new Error("这个号还没注册，注册要过旋转验证，而你没配识图模型"), {
+        code: "no-vision-model",
+      })
+    }
+    const r = await passCaptcha(site, ident, first)
+    businessToken = r.businessToken
+    rounds = r.rounds
+    log = r.log
   }
 
-  const { businessToken, rounds, log } = await passCaptcha(site, { mobile, stateCode })
-  const sms = await sendSms(site, { phone: mobile, stateCode, businessToken })
-  if (!sms.ok) {
-    throw Object.assign(new Error(`发短信失败：${sms.message}`), { captchaLog: log })
+  const sent = await sendCode(site, ident, { businessToken })
+  if (!sent.ok) {
+    throw Object.assign(new Error(`发${what}失败：${sent.message}`), { captchaLog: log })
   }
-  return { businessToken, rounds, log }
+  return { businessToken, rounds, log, skippedCaptcha: Boolean(first.registered) }
+}
+
+/** 旧签名兼容：手机号发短信 */
+export async function startSmsLogin(site, { mobile, stateCode = "+86" } = {}) {
+  return startCodeLogin(site, { mobile, stateCode })
 }
 
 /**
  * 第 2 步：验证码换登录态，并补齐组织码。
  *
- * ⚠ 登录响应里 jwt / 组织码的**确切形状没实测过**（手上没有能收短信的号，
- *   只能验到 2168「验证码错误」）。所以：
+ * ⚠ 登录响应里 jwt / 组织码的**确切形状没实测过**（手上没有能收短信/收信的号，
+ *   只能验到 2168「验证码错误」——手机和邮箱都一样）。所以：
  *     · jwt 用 extractCreds 从响应里按特征找（以 eyJ 开头的三段式）
  *     · 组织码找不着就调 `/api/v1/aggregation/login-data`（带 authorization 头，
  *       服务端会回这个账号所在的组织列表）—— 这条路径是文档里查得到的
  */
-export async function finishSmsLogin(site, { mobile, stateCode = "+86", code, device, redirect }) {
-  const { json, status, text } = await loginBySmsCode(site, {
-    phone: mobile,
-    stateCode,
-    code,
-    device,
-    autoRegister: true,
-    redirect,
-  })
+export async function finishCodeLogin(site, { code, device, redirect, ...ident } = {}) {
+  const { json, status, text } = await loginByCode(site, { code, device, redirect, ...ident })
   if (!json) {
     throw new Error(`登录接口回了非 JSON（HTTP ${status}）：${String(text).slice(0, 200)}`)
   }
   if (json.code !== 1000) {
-    // 2168 是验证码错；其余原样透出，别把它吞成「登录失败」
+    // 2168（手机 / 邮箱都是它）= 验证码错；2167 = 短信验证码无效或已过期；
+    // 其余原样透出，别把它吞成「登录失败」
     throw Object.assign(new Error(`登录失败：${json.message ?? json.code}`), {
       code: json.code,
       raw: json,
@@ -140,6 +185,11 @@ export async function finishSmsLogin(site, { mobile, stateCode = "+86", code, de
   return { jwt, org: orgs[0], orgs, raw: json }
 }
 
+/** 旧签名兼容：手机号验证码换登录态 */
+export async function finishSmsLogin(site, { mobile, stateCode = "+86", ...rest } = {}) {
+  return finishCodeLogin(site, { mobile, stateCode, ...rest })
+}
+
 /**
  * 把一段 JSON 的形状描述出来：**只有键名和类型，没有任何值**。
  *