feat(round-4 infra): docker-guard + playwright-hardening + 调研/PRD/SPEC 文档基线

实施依据(prompts/0426/):
- 6 份 research 报告(2170 行)— issue#1 cloudmail / #2 seat / #3 import / #4 oauth+phone / #5 playwright / #6 invite/kick
- 4 份 PRD(1856 行)+ synthesis 综合分析
- 8 份 SPEC(4742 行,含 4 份 shared 共享契约)

Wave 1 — SPEC-3 Docker 守卫(@prd-docker):
- Dockerfile: ARG GIT_SHA + LABEL + ENV(WORKDIR 后定位,不击穿 uv sync 缓存)
- docker-compose.yml: build.args ${GIT_SHA:-unknown} 降级
- docker-entrypoint.sh: uv run python heredoc 启动期 import 自检 11 符号 + crash-loop
- pyproject.toml: [tool.ruff.lint] F401/F811/F821 + per-file-ignores
- .pre-commit-config.yaml: 收紧 ruff args 到 SPEC 三规则
- src/autoteam/api.py: VersionResponse + GET /api/version + _AUTH_SKIP_PATHS 加白
- docs/{api,docker}.md: SOP 4 步 rebuild + 验证 + 故障排查
- tests/integration/test_docker_guard.py: 10 个测试覆盖 AC1/3/4/5/7/9 + 4 静态契约

Wave 2 — SPEC-4 Playwright 一致性硬化(@prd-playwright):
- src/autoteam/_playwright_guard.py(新):9 符号 import 白名单 + assert_sync_context()
- src/autoteam/api.py: _PlaywrightExecutor 双入口 guard(run_with_timeout + _worker)
- src/autoteam/manager.py: 顶层 import 上提 sync_playwright,移除 2 处函数内 import
- tests/static/{__init__.py,test_playwright_hygiene.py,test_playwright_hygiene_negative.py}: 4 AST 守卫 + 5 反例
- tests/unit/test_playwright_guard.py: 3 runtime guard(asyncio.run/threading)
- pyproject.toml: testpaths 显式列入 tests/static / tests/unit / tests/integration

验证:
- pytest 全套 93 passed, 1 pre-existing fail(test_manager_reinvite,SystemTimeWarning,与本轮无关)
- ruff check src/ All checks passed
- import 健康 OK(api/manager/_playwright_guard 全过)

未做(Wave 3+4 独立 PR):
- SPEC-1 Mail Provider 全量化(@prd-mail)
- SPEC-2 + 4 shared 共享契约(@prd-lifecycle)— 含 plan_type 白名单 / quota 分类 / add-phone 探针 / 状态机

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

.pre-commit-config.yaml

@@ -1,7 +1,14 @@
+# SPEC-3 §7: pre-commit ruff hook
+# 安装:uv run pre-commit install
+# 手动跑全仓:uv run pre-commit run --all-files
+
 repos:
   - repo: https://github.com/astral-sh/ruff-pre-commit
     rev: v0.15.10
     hooks:
       - id: ruff
-        args: [--fix, --exit-non-zero-on-fix]
-      - id: ruff-format
+        name: ruff (F401/F811/F821)
+        args:
+          - --select
+          - F401,F811,F821
+          - --exit-non-zero-on-fix

CHANGELOG.md

@@ -2,6 +2,31 @@
 
 本文档记录 AutoTeam-F 相对上游 [cnitlrt/AutoTeam](https://github.com/cnitlrt/AutoTeam) 的差异以及版本演进。日期采用 ISO 8601。
 
+## [Unreleased] — 2026-04-26
+
+### docker-guard:镜像守卫四道防线(SPEC-3)
+
+> 起因:issue #3 的 `list_accounts` ImportError 代码层已修(commit cf2f7d3),但用户 docker 容器没重建仍报错。本轮落地"防回归 + 用户操作 SOP + 镜像可观察性"。
+
+- **feat(docker): entrypoint self-check** — `docker-entrypoint.sh` 在 `exec uv run autoteam` 前增加白名单 import 自检(`autoteam.api.app` + `autoteam.accounts` 9 个对外契约符号 + `autoteam.manager.sync_account_states` 共 11 项),失败即 `exit 1` 触发 docker `restart: unless-stopped` 的 crash-loop;失败提示文案直接给出 rebuild 命令。
+- **feat(docker): 镜像 git-sha 指纹** — `Dockerfile` 增 `ARG GIT_SHA` / `ARG BUILD_TIME`,落到 `LABEL org.opencontainers.image.revision/created` + `ENV AUTOTEAM_GIT_SHA/BUILD_TIME`;`docker-compose.yml` 用 `${GIT_SHA:-unknown}` 降级,不传 build-arg 也能跑。
+- **feat(api): `/api/version` 端点** — `src/autoteam/api.py` 新增免鉴权 `GET /api/version`,返回 `{git_sha, build_time}`,`_AUTH_SKIP_PATHS` 已加白名单;Pydantic `VersionResponse` 模型,与 OpenAPI/Swagger 集成。
+- **feat(lint): ruff F401/F811/F821 守卫** — `pyproject.toml` 新增 `[tool.ruff.lint]` 段,只启三条零误报规则;`.pre-commit-config.yaml` 接入同规则,堵住 typo 类 ImportError 在 commit 前。
+- **docs(docker): rebuild SOP** — `docs/docker.md` 增加"代码更新后的 rebuild SOP"+"版本验证"+"启动期 self-check"+"故障排查"+"lint 守卫"五个章节;`docs/api.md` 把 `/api/version` 加入即时返回接口表与免鉴权清单。
+
+### playwright-hardening:async/sync 一致性硬化(SPEC-4)
+
+> 起因:issue #5 用户报告"playwright 中大量 async 函数里误用 sync API"。研究阶段对全项目 5 处 `sync_playwright` 调用点 + 1 处 `async def` 完整审计后**结论反转** — 0 处实际混用、5 处全部位于 sync `def` + 经由 `_PlaywrightExecutor` 单例 + 专用 worker 线程串行,严格符合 Playwright 官方推荐模式。用户决定走 hardening only,落 3 道防线杜绝未来回归。
+
+- **feat(guard): 新增 `src/autoteam/_playwright_guard.py`** — 单一信源(SSOT)模块:9 个 sync 白名单符号 `ALLOWED_SYNC_NAMES`(sync_playwright/Playwright/Browser/BrowserContext/BrowserType/Page/Locator/Error/TimeoutError)+ `FORBIDDEN_MODULES={"playwright.async_api"}` + `EXEMPTION_MARKER="autoteam: allow-async-playwright"` + `assert_sync_context()` 函数(在 asyncio loop 内调用立即抛 `RuntimeError`,异常消息含 thread 名 + loop_id 便于诊断)。
+- **feat(api): `_PlaywrightExecutor` 双入口 guard** — `api.py` 在 `run_with_timeout` 主线程入口 + `_worker` 专用线程入口分别调 `assert_sync_context()`,防止未来某次重构把 sync_playwright 误植入 async 上下文(撞 Playwright 内部 "Sync API inside asyncio loop" 静默失败)。
+- **refactor(manager): 函数内 import 上提** — `manager.py:_complete_registration` / `_register_direct_once` 两处 `from playwright.sync_api import sync_playwright` 上提至模块顶层(全仓 sync_api import 现在统一在 4 个文件的模块顶层 + manager.py 1 处)。
+- **test(static): AST 守卫 + 反例验证** — `tests/static/test_playwright_hygiene.py` 4 个测试:① 禁止 `from playwright.async_api`;② `async def` 函数体内不允许任何 playwright 符号;③ `playwright.sync_api` 导入仅限白名单 9 符号;④ 豁免登记表 `expected_exempt = set()` 当前期望 0 个豁免。`tests/static/test_playwright_hygiene_negative.py` 5 个反例验证守卫真能拦下违规模式。
+- **test(unit): runtime guard 验证** — `tests/unit/test_playwright_guard.py` 3 个测试:① 普通线程放行;② `asyncio.run()` 内调用必抛;③ 异常消息含 `thread=` + `loop_id=0x...`。
+- **chore(pytest): testpaths 显式列入 tests/static** — `pyproject.toml` `[tool.pytest.ini_options]` 把 `tests/static` / `tests/unit` / `tests/integration` 全部显式列入 `testpaths`,避免未来 collect-only 配置误排除静态守卫。
+
+> SPEC-4 范围严格限定 hardening only,**不动业务逻辑**:`chatgpt_api.py` / `codex_auth.py` / `invite.py` / 5 处 `with sync_playwright() as p:` 块本体一行未改。
+
 ## [Unreleased] — 2026-04-25
 
 ### invite-hardening round-3:母号切换鲁棒性 + exhausted 自愈 + CPA 删除守卫

Dockerfile

@@ -13,6 +13,15 @@ ENV PATH="/root/.local/bin:$PATH"
 
 WORKDIR /app
 
+# === SPEC-3 §3: 镜像版本指纹注入 ===
+ARG GIT_SHA=unknown
+ARG BUILD_TIME=unknown
+LABEL org.opencontainers.image.revision="${GIT_SHA}"
+LABEL org.opencontainers.image.created="${BUILD_TIME}"
+ENV AUTOTEAM_GIT_SHA="${GIT_SHA}"
+ENV AUTOTEAM_BUILD_TIME="${BUILD_TIME}"
+# === SPEC-3 §3 end ===
+
 # 复制项目文件
 COPY pyproject.toml uv.lock ./
 RUN uv sync --no-dev

docker-compose.yml

@@ -1,6 +1,10 @@
 services:
   autoteam:
-    build: .
+    build:
+      context: .
+      args:
+        GIT_SHA: ${GIT_SHA:-unknown}
+        BUILD_TIME: ${BUILD_TIME:-unknown}
     ports:
       - "8787:8787"
     volumes:

docker-entrypoint.sh

@@ -25,5 +25,43 @@ for d in auths screenshots; do
     ln -s "/app/data/$d" "/app/$d"
 done
 
+# ---------------------------------------------------------------------------
+# Self-check: 关键 import 白名单 — 失败即 crash-loop(SPEC-3 §2)
+# ---------------------------------------------------------------------------
+echo "[self-check] verifying critical imports..."
+uv run python - <<'PYEOF' || {
+    echo "[self-check] FATAL: critical import failed - image is likely stale or broken." >&2
+    echo "[self-check] If you just pulled new code, the image must be rebuilt:" >&2
+    echo "[self-check]   docker compose down" >&2
+    echo "[self-check]   docker compose build --no-cache --build-arg GIT_SHA=\$(git rev-parse --short HEAD)" >&2
+    echo "[self-check]   docker compose up -d" >&2
+    exit 1
+}
+import sys
+
+# 核心 web 应用入口
+from autoteam.api import app  # noqa: F401
+
+# accounts.py 全部对外契约符号(典型 typo 高发区)
+from autoteam.accounts import (  # noqa: F401
+    load_accounts,
+    save_accounts,
+    STATUS_ACTIVE,
+    STATUS_EXHAUSTED,
+    STATUS_STANDBY,
+    STATUS_PENDING,
+    STATUS_PERSONAL,
+    STATUS_AUTH_INVALID,
+    STATUS_ORPHAN,
+)
+
+# manager → accounts 链路(覆盖跨模块 typo)
+from autoteam.manager import sync_account_states  # noqa: F401
+
+print("[self-check] OK: %d critical symbols imported." % 11)
+sys.exit(0)
+PYEOF
+echo "[self-check] passed."
+
 # 执行命令
 exec uv run autoteam "$@"

docs/api.md

@@ -12,6 +12,7 @@ Authorization: Bearer <API_KEY>
 - `/api/auth/check`
 - `/api/setup/status`
 - `/api/setup/save`
+- `/api/version`
 
 ## 即时返回接口
 
@@ -22,6 +23,7 @@ Authorization: Bearer <API_KEY>
 | GET | `/api/auth/check` | 验证 API Key |
 | GET | `/api/setup/status` | 检查配置是否完整 |
 | POST | `/api/setup/save` | 保存初始配置 |
+| GET | `/api/version` | 镜像版本指纹（`git_sha` + `build_time`，免鉴权，用于排查 docker 镜像是否过期） |
 | GET | `/api/status` | 账号状态 + 实时额度 |
 | GET | `/api/accounts` | 所有账号列表 |
 | GET | `/api/accounts/active` | 活跃账号 |

docs/docker.md

@@ -110,3 +110,88 @@ uv run autoteam pull-cpa
 ```
 
 即可重新整理。
+
+---
+
+## 代码更新后的 rebuild SOP(SPEC-3 §8)
+
+> **关键认知**:本项目 `Dockerfile` 用 `COPY src/`(非 volume mount),
+> **`git pull` 后必须 rebuild 镜像**,代码改动才会进入容器。
+
+### 标准更新流程(4 步)
+
+```bash
+# 1. 拉取新代码
+cd /path/to/AutoTeam && git pull
+
+# 2. 停掉旧容器
+docker compose down
+
+# 3. 重建镜像(--no-cache 防意外缓存命中,GIT_SHA 注入版本指纹)
+GIT_SHA=$(git rev-parse --short HEAD) \
+BUILD_TIME=$(date -u +%FT%TZ) \
+docker compose build --no-cache
+
+# 4. 启动
+docker compose up -d
+```
+
+### 验证镜像版本(三选一,结果应一致)
+
+```bash
+# 方式 A:HTTP 端点(免鉴权)
+curl http://localhost:8787/api/version
+# 期望:{"git_sha":"cf2f7d3","build_time":"2026-04-26T..."}
+
+# 方式 B:进容器查环境变量
+docker compose exec autoteam env | grep AUTOTEAM_GIT_SHA
+
+# 方式 C:看镜像 OCI label(无需启动容器)
+docker image inspect autoteam-autoteam --format '{{json .Config.Labels}}'
+```
+
+### 启动期 self-check
+
+容器每次启动都会执行 `[self-check]` 段,白名单 import 任一失败立即 `exit 1` → docker 进入 crash-loop。
+
+```bash
+docker compose logs autoteam | head -20
+# 期望看到:
+# [self-check] verifying critical imports...
+# [self-check] OK: 11 critical symbols imported.
+# [self-check] passed.
+```
+
+### 故障排查:为什么修了代码 bug 还在?
+
+**99% 是镜像没 rebuild**。先跑这条快速诊断:
+
+```bash
+# 对比 image 内 sha 与 repo HEAD
+echo "image:" && curl -s http://localhost:8787/api/version | python -m json.tool
+echo "repo HEAD:" && git rev-parse --short HEAD
+```
+
+如果 `image.git_sha` 与 `repo HEAD` 不一致 → 重做上面 4 步 SOP。
+
+如果 self-check 报 `FATAL: critical import failed`:
+- 说明镜像里的源码与最新代码的契约符号对不上(典型 typo 引入未定义名)
+- 解决:回退最近 commit 或修复 typo,再 rebuild
+
+### lint 守卫(开发期)
+
+`pyproject.toml` 已配置 ruff(F401/F811/F821 三条规则),`.pre-commit-config.yaml` 也接入了同样的检查。
+
+首次启用:
+
+```bash
+uv sync                           # 装 dev 依赖(pre-commit、ruff 已声明)
+uv run pre-commit install         # 注入 .git/hooks/pre-commit
+uv run pre-commit run --all-files # 一次性扫全仓,确认基线干净
+```
+
+之后每次 `git commit` 会自动跑 ruff;手动检查可:
+
+```bash
+uv run ruff check src/
+```

prompts/0426/prd/prd-1-mail-provider.md

@@ -0,0 +1,455 @@
+# PRD-1: Mail Provider 全量化
+
+## 0. 元数据
+
+| 字段     | 值                                                                                          |
+| -------- | ------------------------------------------------------------------------------------------- |
+| 版本     | v1.0                                                                                        |
+| 日期     | 2026-04-26                                                                                  |
+| 主笔     | prd-mail (AutoTeam team `autoteam-prd-0426`)                                                |
+| 评审人   | team-lead                                                                                   |
+| 状态     | Draft                                                                                       |
+| 输入文档 | `prompts/0426/research/issue-1-cloudmail.md` (613 行) / `prompts/0426/synthesis.md`         |
+| 关联     | Issue#1 「setup_wizard 创建邮箱失败 (401)」、`docs/mail-provider-design.md` §6 待确认项     |
+
+---
+
+## 1. 背景与问题陈述
+
+AutoTeam 已在 2026-04 完成 mail provider 抽象重构(`src/autoteam/mail/{base,cf_temp_email,maillab}.py`),但**配置层与 UI 层未同步迁移**,导致用户在以下三种场景持续踩坑:
+
+1. **半成功假象** — 用户填了 maillab 服务器地址但没设 `MAIL_PROVIDER=maillab`,默认走 cf_temp_email 分支。`/admin/address` 在 maillab 的 catch-all 路由下可能误回 200,login 假成功,直到 `/admin/new_address` 才暴露 `{code:401, message:"身份认证失效"}`(issue#1 截图)。
+2. **Web 面板配置黑洞** — `api.py:70-79` 的 `SetupConfig` Pydantic 模型只声明 `CLOUDMAIL_*`,Pydantic 默认丢弃未声明字段。即便前端塞 `MAIL_PROVIDER` / `MAILLAB_*`,`/api/setup/save` 也不会写入 `.env`,maillab 用户被锁死在 cf_temp_email 模式。
+3. **盲填域名** — 用户手敲 `CLOUDMAIL_DOMAIN`,只能等启动验证或 `register-domain PUT` 试探时才知道是否被服务端接受;maillab 实例自带 `/setting/websiteConfig.domainList`,用户体验差距明显。
+
+经核验(`src/autoteam/setup_wizard.py:20-35` REQUIRED_CONFIGS 已含 `MAIL_PROVIDER`,但 SetupConfig 没有同步),现状是**底层 ABC 已完整,中层配置 / 上层 UI 仍为单后端思维**,需要补齐贯通。
+
+---
+
+## 2. 目标(SMART)
+
+| ID  | 目标                                                                                                                  | 衡量                                                                            |
+| --- | --------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------- |
+| G1  | Web 面板 SetupPage / Settings 支持 cf_temp_email / maillab 双 provider 字段填写并持久化                              | `/api/setup/save` 写入 `.env` 后 `MAIL_PROVIDER` / `MAILLAB_*` 全部可被读到     |
+| G2  | 用户在保存前完成"指纹 → 凭据 → 域名归属"3 步在线验证,失败给出可读的 error_code + hint                                | 错配场景(maillab 服务器配 cf_temp_email 字段)在 step=fingerprint 即报错       |
+| G3  | cf_temp_email 协议错配嗅探零漏判                                                                                      | `/admin/address` 返回 `200 + {}` 空响应也被识别为非 cf_temp_email,login 即抛错 |
+| G4  | maillab 401 token 失效时客户端自愈                                                                                    | `MaillabClient` 任意业务方法收 `code:401` 后自动 `_ensure_login()` 重试一次     |
+| G5  | 文档(getting-started / configuration / mail-provider-design / troubleshooting / api / .env.example)同步更新       | 文档清单 §11 全部状态从 P0 → Done                                              |
+
+**MVP 完成标准** — Issue#1 截图复现的"管理员鉴权通过 → 创建邮箱失败 401"流程,在 Web 面板里能在 step=fingerprint 阶段(填完 base_url 即点测试连接时)就拿到"建议切 MAIL_PROVIDER=maillab"的 hint。
+
+---
+
+## 3. 非目标(明确不做的)
+
+- **不实现** maillab 管理员功能(`/user/*` `/role/*` `/allEmail/*` `/regKey/*` 等 30+ 路由) — 属于 maillab 自身后台,业务上不需要。
+- **不实现** `/email/send`(发邮件) — AutoTeam 只读验证码。
+- **不实现** maillab Turnstile / addVerify 兼容 — 用户需到 maillab 后台关闭。后续如有需求再立 PRD。
+- **不实现** 多 maillab 实例切换 — 当前一个 base_url 即可,prod/staging 由用户 .env 切换。
+- **不实现** linuxdo OAuth 自动绑定 — 当前不在范围。
+- **不实现** `/public/genToken` 集成 — 现 `/login` 路径已够用,且 `/public/genToken` 仅 `c.env.admin` 可调,适用面更窄。
+- **不动**业务调用层(`manager.py` / `invite.py` / `codex_auth.py` / `account_ops.py`)对 `CloudMailClient` 的调用,通过 `from autoteam.cloudmail import CloudMailClient` 兼容别名继续工作。
+
+---
+
+## 4. 用户故事
+
+| ID     | 故事                                                                                                                                                             |
+| ------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| US-001 | 作为首次部署 AutoTeam 的管理员,我**应该**在 SetupPage 选 cf_temp_email / maillab 后**只看到对应字段**,无关字段不出现,避免我把 maillab 服务器填到 cf 字段里。 |
+| US-002 | 作为管理员,我**应该**在填完 base_url 后立即看到"这是 cf_temp_email / maillab / 未识别"的指纹结果与 hint,而不是等启动后才发现错配。                              |
+| US-003 | 作为 maillab 用户,我**应该**在保存前看到该实例支持的 domainList 下拉框,且选中的 domain **已被 `/account/add` 试创建一次邮箱并立即回收**确认归属。                |
+| US-004 | 作为重启后 token 过期的用户,我**期望**任意 mail 调用收 401 时客户端自愈,而不是直接业务失败。                                                                    |
+| US-005 | 作为 cf_temp_email 用户,我**期望**当我填错 base_url(指向 maillab 服务器)时立即报错,而不是 login 假成功。                                                       |
+| US-006 | 作为通过 Settings 页修改 mail provider 的管理员,我**期望**复用 SetupPage 的同一套验证 UX(指纹 / 凭据 / 域名),不需要二次踩坑。                                  |
+
+---
+
+## 5. 功能需求
+
+> 每条 FR 对应 §8 验收标准的一条 AC。
+
+### FR-001 SetupConfig 扩字段
+
+- 在 `src/autoteam/api.py` 的 `SetupConfig` 模型中新增字段:`MAIL_PROVIDER: str = "cf_temp_email"`、`MAILLAB_API_URL: str = ""`、`MAILLAB_USERNAME: str = ""`、`MAILLAB_PASSWORD: str = ""`、`MAILLAB_DOMAIN: str = ""`。
+- `post_setup_save` 写入 `.env` 时,**当 MAIL_PROVIDER == "cf_temp_email" 时跳过 MAILLAB_* 写入,反之亦然**(避免无关字段污染 .env)。
+- `GET /api/setup/status` 已经按 REQUIRED_CONFIGS 输出字段,需要新增 maillab 4 字段进 REQUIRED_CONFIGS,且在 `provider != maillab` 时把这 4 项的 `optional` 标为 `True`。
+
+### FR-002 cf_temp_email 嗅探零漏判
+
+- `src/autoteam/mail/cf_temp_email.py:login()` L106 的判定从 `("code" in payload or "data" in payload)` 改为**正向白名单**:**响应 dict 不含 `results` key 一律抛错**(无论是否含 code/data,空 `{}` 也命中)。
+- 错误信息保留原有的"看起来是 maillab,请改 MAIL_PROVIDER=maillab"提示。
+- `create_temp_email` L154 同步收紧:`"address" not in data` 即报错(不再要求同时 `code` + `message`)。
+
+### FR-003 maillab 401 自愈
+
+- `src/autoteam/mail/maillab.py` 的 `_get / _post / _delete / _put` 在拿到响应后:若 `resp.get("code") == 401`,**且** `_login_recursion_guard` 未置位,则清空 `self.token` → `self.login()` → 用新 token **重试一次**。
+- 重试仍 401 时抛 `Exception("maillab 鉴权失败,请检查 MAILLAB_USERNAME/PASSWORD")`。
+- 用 thread-local guard 防止 `login()` 自身触发递归(login 调 `_post` 会再触发 401 处理)。
+
+### FR-004 新增 `/api/mail-provider/probe` 端点
+
+- 新增 POST 端点,**3 步可分步调用**,Pydantic 模型见 §7.2。
+- 鉴权:setup 阶段可无鉴权(与 `/api/setup/save` 一致);进入面板后(`API_KEY` 已配置)必须带 `Authorization: Bearer <key>`。
+- `step=fingerprint`:无需凭据,GET `{base_url}/setting/websiteConfig` 一次即可拿到 `domainList / addVerifyOpen / registerVerifyOpen`,响应缺 `domainList` 但含 `results` 时识别为 cf_temp_email,均缺时识别为 unknown。
+- `step=credentials`:用填好的 username/password 调 `{base_url}/login`,解析 JWT payload 反馈 `is_admin / user_email / token_preview`。token **不持久化到磁盘**,只在响应中作展示。
+- `step=domain_ownership`:用上一步的 token 调 `{base_url}/account/add` body `{email: "probe-{ts}@{domain}"}`,成功立即 `DELETE /account/delete?accountId=N`。失败(403 / message 含 "domain")归类为 `FORBIDDEN_DOMAIN`。
+
+### FR-005 register-domain 复用共享 helper
+
+- 把 `api.py:1631-1673` 的 PUT register-domain 探测逻辑(create_temp_email + delete_account)**抽到 `src/autoteam/mail/probe.py` 的 `probe_domain_ownership(client, domain) -> ProbeResult`**。
+- `/api/mail-provider/probe` step=domain_ownership 与 `PUT /api/config/register-domain` 共享此 helper,**确保两条路径的语义、错误归类、回收逻辑完全一致**。
+
+### FR-006 setup_wizard 嗅探前置
+
+- `_verify_cloudmail()` 中的 `_sniff_provider_mismatch(provider)` 调用从"login 失败前的无害 warning"改为"启动 / Web save 流程的强阻断":**指纹错配时直接 `return False`,不再继续走 login**。
+- Web `post_setup_save` 自动复用此判定。
+- `_sniff_provider_mismatch` 内部增强:除了 admin/login 路由探测,加一次 GET `/setting/websiteConfig`(maillab 独有 + 含 domainList 即明确 maillab),让 cf_temp_email 服务器也能被识别(它没有 `/setting/websiteConfig`)。
+
+### FR-007 SetupPage 分组卡片 UX
+
+- `web/src/components/SetupPage.vue` 由现有平铺 `v-for="field"` 改为**分组卡片**:
+  - **卡片 1** Mail Provider 选择(单选 cf_temp_email / maillab,默认 cf_temp_email)
+  - **卡片 2** base_url + 凭据 + 「测试连接」按钮(顺序调 step=fingerprint → step=credentials)
+  - **卡片 3** domain 下拉框(从 fingerprint 拿 domainList) + 「验证归属」按钮(step=domain_ownership)
+  - **卡片 4** CPA / API_KEY / Playwright 代理(原样保留)
+- 步骤未通过的卡片下游灰显;每步失败显示 error_code + 原始 message + hint。
+- domainList 缺失(cf_temp_email 后端 / maillab 老版)时降级为自由输入框,`/api/mail-provider/probe?step=domain_ownership` 仍执行。
+
+### FR-008 Settings 页加 mail provider 切换
+
+- `web/src/components/Settings.vue` 当前**完全无 mail provider 切换 UI**(经核验仅含管理员登录块)。新增「邮箱后端」区块,沿用 SetupPage 同款 3 步验证 + 写入 `.env`(后端走同一条 `/api/setup/save` 路径)。
+- 修改成功后弹出 toast 提示「重启服务后生效」(`MAIL_PROVIDER` 是模块级常量,需重启)。
+
+### FR-009 .env.example 注释加固
+
+- `.env.example` L5 在 `MAIL_PROVIDER=cf_temp_email` 上方加注释:**强烈推荐显式设置;不设默认 cf_temp_email 可能与你的 maillab 部署错配**。
+- maillab 字段块从注释状态改为正常字段状态(默认值留空),与 cf_temp_email 字段同等可见性。
+
+### FR-010 文档同步
+
+详见 §11 文档影响清单。
+
+---
+
+## 6. 非功能需求(NFR)
+
+| 类别       | 要求                                                                                                                                          |
+| ---------- | --------------------------------------------------------------------------------------------------------------------------------------------- |
+| 性能       | `/api/mail-provider/probe` 任意 step P95 ≤ 5s(含网络);domainList 探测开 timeout=5s;step=domain_ownership 含创建 + 回收两次往返,P95 ≤ 8s |
+| 可靠性     | maillab 401 自愈最多 1 次重试,避免无限循环;register-domain 探测失败时探测邮箱泄漏须以 `leaked_probe` 字段透传给前端                          |
+| 安全性     | username / password 仅作请求 body 转发到用户填的 base_url,**后端不持久化**(由 `/api/setup/save` 单独写 .env);`token_preview` 只截取前 10 字符 |
+| 可观测性   | `/api/mail-provider/probe` 每步打 INFO 日志含 `step / detected_provider / ok`;失败打 WARNING 含 `error_code`                                  |
+| 国际化     | 全部错误 message 中文(沿用项目现状)                                                                                                          |
+| 兼容性     | 不破坏 `from autoteam.cloudmail import CloudMailClient` 兼容别名;19 处实例化 / 22 处方法调用零改动                                            |
+| 速率限制   | `/api/mail-provider/probe` 端点,setup 阶段(无鉴权)单 IP 60 req/min(防扫描);进入面板后无限制                                                |
+
+---
+
+## 7. 技术方案
+
+### 7.1 架构图(ASCII)
+
+```
+                         ┌─────────────────────────────────┐
+                         │  SetupPage / Settings (Vue)     │
+                         │   分组卡片 + 3 步验证流          │
+                         └─────────────┬───────────────────┘
+                                       │ POST /api/mail-provider/probe
+                                       │ POST /api/setup/save
+                                       ▼
+                         ┌─────────────────────────────────┐
+                         │  api.py (FastAPI)               │
+                         │   + SetupConfig (扩字段)        │
+                         │   + post_mail_provider_probe()  │
+                         │   + put_register_domain()共享   │
+                         └─────────────┬───────────────────┘
+                                       │
+                  ┌────────────────────┼────────────────────┐
+                  ▼                    ▼                    ▼
+        ┌────────────────┐  ┌──────────────────┐  ┌────────────────┐
+        │ setup_wizard   │  │ mail/probe.py    │  │ runtime_config │
+        │ _verify_cloud  │  │ probe_domain_    │  │ register_domain│
+        │ + _sniff_前置  │  │ ownership(共享)  │  │ 持久化         │
+        └────────┬───────┘  └────────┬─────────┘  └────────────────┘
+                 │                   │
+                 ▼                   ▼
+       ┌──────────────────────────────────────┐
+       │  mail/__init__.py — get_mail_client()│
+       │  按 MAIL_PROVIDER 分发                │
+       └─────────┬──────────────────┬─────────┘
+                 │                  │
+                 ▼                  ▼
+       ┌──────────────────┐  ┌──────────────────┐
+       │ cf_temp_email.py │  │ maillab.py       │
+       │ + 嗅探零漏判     │  │ + 401 自愈守卫   │
+       └──────────────────┘  └──────────────────┘
+```
+
+### 7.2 关键 API 契约
+
+#### 7.2.1 `/api/mail-provider/probe` 请求体(Pydantic)
+
+```python
+from typing import Literal
+from pydantic import BaseModel, Field, field_validator
+
+class MailProviderProbeRequest(BaseModel):
+    provider: Literal["cf_temp_email", "maillab"]
+    step: Literal["fingerprint", "credentials", "domain_ownership"]
+    base_url: str = Field(..., min_length=1, max_length=512)
+    # cf_temp_email 字段
+    admin_password: str = ""              # cf_temp_email 的 admin password
+    # maillab 字段
+    username: str = ""                    # maillab 登录邮箱
+    password: str = ""                    # maillab 登录密码
+    # 共用
+    domain: str = ""                      # step=domain_ownership 必填
+    # step=credentials/domain_ownership 时,前端把上一步拿到的 token 回传,后端不持久化
+    bearer_token: str = ""
+
+    @field_validator("base_url")
+    @classmethod
+    def _normalize_base_url(cls, v: str) -> str:
+        v = v.strip().rstrip("/")
+        if not (v.startswith("http://") or v.startswith("https://")):
+            raise ValueError("base_url 必须以 http:// 或 https:// 开头")
+        return v
+```
+
+#### 7.2.2 `/api/mail-provider/probe` 响应体
+
+```python
+class MailProviderProbeResponse(BaseModel):
+    ok: bool
+    step: Literal["fingerprint", "credentials", "domain_ownership"]
+    # 通用
+    error_code: str | None = None         # ROUTE_NOT_FOUND/UNAUTHORIZED/FORBIDDEN_DOMAIN/PROVIDER_MISMATCH/NETWORK/TIMEOUT/UNKNOWN
+    message: str | None = None
+    hint: str | None = None
+    warnings: list[str] = []
+    # step=fingerprint 专属
+    detected_provider: Literal["cf_temp_email", "maillab", "unknown"] | None = None
+    domain_list: list[str] | None = None
+    add_verify_open: bool | None = None
+    register_verify_open: bool | None = None
+    # step=credentials 专属
+    is_admin: bool | None = None
+    user_email: str | None = None
+    token_preview: str | None = None      # 仅前 10 字符,展示用
+    # step=domain_ownership 专属
+    probe_email: str | None = None
+    probe_account_id: int | None = None
+    cleaned: bool | None = None           # 探测邮箱是否回收成功
+    leaked_probe: dict | None = None      # cleaned=False 时给出 {email, acct_id, error}
+```
+
+#### 7.2.3 错误码枚举
+
+| error_code           | 触发条件                                                                             | 默认 hint                                      |
+| -------------------- | ------------------------------------------------------------------------------------ | ---------------------------------------------- |
+| `ROUTE_NOT_FOUND`    | step=fingerprint 时 base_url 既无 `/setting/websiteConfig` 也无 `/admin/address`     | 检查 base_url 是否拼错(应含 /api 前缀等)     |
+| `PROVIDER_MISMATCH`  | provider 与 detected_provider 不一致                                                 | 把 MAIL_PROVIDER 改为 detected_provider        |
+| `UNAUTHORIZED`       | step=credentials 时 maillab 返回 code:401,或 cf_temp_email 返回 401/403              | 检查用户名/密码                                |
+| `FORBIDDEN_DOMAIN`   | step=domain_ownership 时返回 403,或 message 含 "domain"                             | 联系 maillab 管理员把该 domain 加入白名单      |
+| `CAPTCHA_REQUIRED`   | step=credentials 时 maillab 提示 turnstile / addVerify                               | 在 maillab 后台关闭 captcha                    |
+| `NETWORK`            | 连接被拒 / DNS 解析失败                                                              | 检查 base_url 与防火墙                         |
+| `TIMEOUT`            | 单步 5s 内无响���                                                                     | 检查 base_url 可达性                           |
+
+### 7.3 数据模型变更
+
+无数据库变更。仅:
+
+- `.env` 新增/启用 5 字段(`MAIL_PROVIDER` `MAILLAB_API_URL` `MAILLAB_USERNAME` `MAILLAB_PASSWORD` `MAILLAB_DOMAIN`),5 字段已存在 `.env.example` 注释中,本次取消注释 + 默认空。
+- `runtime_config.json` 不变,继续用 `register_domain` 字段(同时被 cf_temp_email 与 maillab 读取,优先级:显式参数 > runtime_config > 环境变量)。
+
+### 7.4 配置项变更
+
+| 配置                | 当前状态                                       | 变更                                      |
+| ------------------- | ---------------------------------------------- | ----------------------------------------- |
+| `MAIL_PROVIDER`     | `setup_wizard.REQUIRED_CONFIGS` 已有,但 SetupConfig 没有 | 加入 SetupConfig;Optional → Required(默认 cf_temp_email) |
+| `MAILLAB_API_URL`   | 仅 `.env.example` 注释                         | 加入 SetupConfig + REQUIRED_CONFIGS;maillab 时必填        |
+| `MAILLAB_USERNAME`  | 仅 `.env.example` 注释                         | 同上                                                       |
+| `MAILLAB_PASSWORD`  | 仅 `.env.example` 注释                         | 同上                                                       |
+| `MAILLAB_DOMAIN`    | 仅 `.env.example` 注释                         | 同上(可选,缺省回落 CLOUDMAIL_DOMAIN)                    |
+| `CLOUDMAIL_EMAIL`   | 已废弃但仍在 `.env.example` L12 留兼容空字段     | 保持现状(与本 PRD 无关)                                  |
+
+### 7.5 前端变更
+
+| 文件                         | 变更                                                                                                                |
+| ---------------------------- | ------------------------------------------------------------------------------------------------------------------- |
+| `web/src/api.js`             | 新增 `probeMailProvider(payload)` 方法,POST `/api/mail-provider/probe`                                              |
+| `web/src/components/SetupPage.vue` | 重构为分组卡片(FR-007);从 `<input v-for="field">` 改为 `<MailProviderCard>` + `<CredentialCard>` + `<DomainCard>` |
+| `web/src/components/MailProviderCard.vue` | **新增**;封装 provider 选择 + base_url + 凭据 + 域名 3 步验证                                                       |
+| `web/src/components/Settings.vue`  | 新增「邮箱后端」区块(FR-008),复用 `<MailProviderCard>`                                                              |
+
+---
+
+## 8. 验收标准
+
+| AC ID  | FR    | 步骤                                                                                                                                       | 通过判据                                                                       |
+| ------ | ----- | ------------------------------------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------ |
+| AC-001 | FR-001 | Web 面板 SetupPage 选 maillab,填全 4 字段 + 点保存;查 `.env`                                                                              | `MAIL_PROVIDER=maillab` 与 `MAILLAB_*` 4 字段全部落盘                          |
+| AC-002 | FR-002 | mock 一个 base_url 对 `/admin/address` 回 `200 + {}`;调 `cf_temp_email.login()`                                                            | 抛 `CloudMail 登录响应不像 dreamhunter2333/...`                                |
+| AC-003 | FR-003 | 启动后等 maillab token 失效,触发 `client.list_accounts()`                                                                                  | 内部自动 login 一次,业务方法返回正确数据,日志含 `[maillab] token 已自愈`     |
+| AC-004 | FR-004 | 调 `/api/mail-provider/probe` step=fingerprint,base_url 指向 maillab                                                                       | 返回 `detected_provider=maillab` + 非空 `domain_list`                          |
+| AC-005 | FR-004 | 同上,base_url 指向 cf_temp_email                                                                                                           | 返回 `detected_provider=cf_temp_email`                                         |
+| AC-006 | FR-004 | step=fingerprint,但 provider=cf_temp_email、base_url 是 maillab                                                                            | `ok=false, error_code=PROVIDER_MISMATCH, hint="把 MAIL_PROVIDER 改为 maillab"` |
+| AC-007 | FR-004 | step=domain_ownership,domain 不在 maillab 白名单                                                                                          | `ok=false, error_code=FORBIDDEN_DOMAIN`                                        |
+| AC-008 | FR-005 | `PUT /api/config/register-domain` 与 `/api/mail-provider/probe?step=domain_ownership` ��中同一个 domain                                    | 两端返回 `probe_email` 一致前缀(`probe{ts}`),探测邮箱回收语义一致           |
+| AC-009 | FR-006 | 启动时 `MAIL_PROVIDER=cf_temp_email` 但 `CLOUDMAIL_BASE_URL` 指向 maillab                                                                 | `_verify_cloudmail` 不调 `client.login()` 即 `return False`,日志 `[验证] 协议错配...` |
+| AC-010 | FR-007 | 在 SetupPage 选 cf_temp_email                                                                                                              | maillab 4 字段隐藏,只看到 `CLOUDMAIL_*`                                        |
+| AC-011 | FR-007 | step=credentials 失败,点击下游域名卡片                                                                                                    | 域名卡片灰显,无法操作                                                          |
+| AC-012 | FR-008 | Settings 页修改 mail provider 后保存                                                                                                       | toast 显示「重启服务后生效」,`.env` 已更新                                    |
+| AC-013 | FR-009 | 全新部署用户复制 `.env.example` 后启动                                                                                                     | 用户能看到 maillab 注释突出引导                                                 |
+| AC-014 | 全部  | issue#1 截图复现:用户在 SetupPage 填 maillab 服务器地址但选 cf_temp_email                                                                  | 测试连接按钮显示 `PROVIDER_MISMATCH` + hint,**不**进 step=credentials         |
+
+---
+
+## 9. 测试计划
+
+### 9.1 单元测试
+
+| 测试模块                                           | 用例                                                                                                          |
+| -------------------------------------------------- | ------------------------------------------------------------------------------------------------------------- |
+| `tests/test_mail_cf_temp_email_sniff.py`           | login() 响应:`{"results":[]}` ✓;`{}` ✗;`{"code":401}` ✗;`{"code":200,"data":{}}` ✗(全部 ✗ 应 raise) |
+| `tests/test_mail_maillab_self_heal.py`             | 模拟首次 401 后 login 成功 + 重试拿数据;login 仍 401 时抛错;login 内部递归不再触发自愈                      |
+| `tests/test_mail_provider_probe.py`                | step=fingerprint 三种 detected_provider(cf/maillab/unknown);step=credentials 401/200;step=domain_ownership 403/200 |
+| `tests/test_mail_probe_helper.py`                  | `probe_domain_ownership` 共享函数:成功 + cleaned=True;成功 + 删除失败 → leaked_probe 透传                  |
+| `tests/test_setup_wizard_sniff_block.py`           | `_verify_cloudmail` 在指纹错配时直接 return False,不创建 client                                              |
+
+### 9.2 集成测试
+
+- `tests/integration/test_setup_save_e2e.py`:POST `/api/setup/save`(maillab 全字段 + 模拟 maillab server)→ `.env` 含 5 个新字段,服务重载后 `MAIL_PROVIDER=maillab` 生效
+- `tests/integration/test_register_domain_shared.py`:`PUT /api/config/register-domain` 与 `POST /api/mail-provider/probe?step=domain_ownership` 对同 domain 的输出一致
+
+### 9.3 E2E
+
+- Playwright:SetupPage 4 步流(provider 选 maillab → fingerprint → credentials → domain_ownership → save)全绿;Settings 页同款流(已部署后切换)
+
+### 9.4 手测清单
+
+| 场景                                                                | 期望                                                                  |
+| ------------------------------------------------------------------- | --------------------------------------------------------------------- |
+| 全新 docker 部署,首次进 SetupPage 选 cf_temp_email                | 仅看到 cf 字段,maillab 字段不渲染                                     |
+| 同上,选 maillab 后填 skymail.ink demo                              | fingerprint 拉到 ≥1 个 domain,credentials 显示 is_admin              |
+| 已部署用户在 Settings 切 maillab → cf_temp_email                    | 保存后 toast 提示重启;重启后业务正常                                  |
+| 故意把 maillab base_url 填到 cf_temp_email 字段                      | 测试连接按钮显示 PROVIDER_MISMATCH(issue#1 复现)                     |
+| 让 maillab 实例 token 过期(关 worker 30 分钟后再点 sync_accounts) | 业务正常,日志显示 token 自愈                                          |
+
+---
+
+## 10. 灰度/回滚策略
+
+- **灰度**:本 PRD 无远程 feature flag(配置类变更天然分发到每个用户实例),通过分阶段 PR 控制风险:
+  - **Phase 1**(P0,无 UI 风险):FR-001(SetupConfig 扩字段)+ FR-002(嗅探零漏判)+ FR-003(401 自愈)+ FR-006(嗅探前置)+ FR-009(.env.example)+ FR-010 文档
+  - **Phase 2**(P0,UI 风险):FR-004(probe 端点)+ FR-005(register-domain 复用)+ FR-007(SetupPage 改造)
+  - **Phase 3**(P1):FR-008(Settings 页切换 UI)
+- **回滚**:每个 Phase 独立 PR,失败即 `git revert`。Phase 1 不影响业务路径,可即时回滚;Phase 2 / 3 涉及前端构建,需 `web/dist` 重新打包。
+- **数据回滚**:`.env` 字段写入由用户掌控,本身可手动改回。
+
+---
+
+## 11. 文档影响清单
+
+| 文档                              | 章节                                                | 改动类型 | 状态(P0=必做) |
+| --------------------------------- | --------------------------------------------------- | -------- | --------------- |
+| `docs/getting-started.md`         | 准备工作 / 1. 搭建临时邮箱                          | 改写     | P0              |
+| `docs/getting-started.md`         | 第二步:配置 / 直接部署                              | 改写     | P0              |
+| `docs/getting-started.md`         | (新增)第二点五步:验证邮箱后端归属                  | 新增     | P0              |
+| `docs/configuration.md`           | `.env` 配置项表(MAIL_PROVIDER 必填化)              | 改写     | P0              |
+| `docs/configuration.md`           | Mail Provider 切换(顺序与推荐反转)                 | 改写     | P0              |
+| `docs/configuration.md`           | (新增)邮箱归属验证                                  | 新增     | P1              |
+| `docs/configuration.md`           | ⚠️ 协议错配排查(链接 SetupPage)                    | 改写     | P0              |
+| `docs/mail-provider-design.md`    | §6「未知项 5 项」标记为已验证                        | 改写     | P0              |
+| `docs/mail-provider-design.md`    | (新增)§7 skymail.ink API 全表                       | 新增     | P1              |
+| `docs/troubleshooting.md`         | Web 面板相关 / 配置保存 401                          | 增补     | P0              |
+| `docs/troubleshooting.md`         | (新增)邮箱后端                                      | 新增     | P1              |
+| `docs/api.md`                     | 初始配置 API / 文档化 `/api/mail-provider/probe`    | 增补     | P0              |
+| `docs/api.md`                     | 域名管理 API / 复用共享 helper 说明                  | 改写     | P0              |
+| `README.md`                       | Features 增补 maillab 全量集成                       | 增补     | P1              |
+| `.env.example`                    | 注释突出 MAIL_PROVIDER 必填,maillab 字段取消注释   | 改写     | P0              |
+
+---
+
+## 12. 风险登记册
+
+| Risk ID | 风险描述                                                                                       | Owner       | 严重度 | Mitigation                                                                                       |
+| ------- | ---------------------------------------------------------------------------------------------- | ----------- | ------ | ------------------------------------------------------------------------------------------------ |
+| R-001   | maillab v2.x 之前 `/setting/websiteConfig` 不返回 `domainList`(skymail.ink 当前 v2.8.0 才有) | impl-1      | 中     | step=fingerprint 缺 domainList 时降级:不阻断,返回 `domain_list=null`,前端切自由输入框           |
+| R-002   | maillab 启用 Turnstile/addVerify 时 step=credentials 失败                                       | impl-1      | 中     | 错误归类 `CAPTCHA_REQUIRED`,hint「请到 maillab 后台关闭 captcha」;不实现 captcha bypass         |
+| R-003   | `/api/mail-provider/probe` setup 阶段无鉴权,被外部当端口扫描器                                  | impl-2      | 中     | NFR 速率限制 60 req/min;面板初始化后此端点强制 API_KEY 鉴权                                       |
+| R-004   | cf_temp_email 嗅探收紧后,误伤第三方 fork(如 unsendapp 等响应不带 results 字段)             | impl-1      | 低     | 错误信息提示 `AUTOTEAM_SKIP_VERIFY=1` 绕过(已存在);记录到 troubleshooting.md                    |
+| R-005   | maillab 401 自愈遇到密码本身错误时,会陷入 login 失败 → throw → 上层重试 → login 失败循环   | impl-1      | 中     | 用 thread-local guard,login() 函数内部不触发自愈;login 失败抛 `MAILLAB_AUTH_FAILED`,业务层不重试 |
+| R-006   | SetupPage 重构破坏现有 e2e 测试                                                                 | impl-2      | 中     | Phase 2 单独 PR;先添加新 testid,旧 testid 兼容保留 1 个版本                                     |
+| R-007   | Settings 页 mail provider 切换后,正在跑的任务用旧 client 引用                                  | impl-2      | 高     | toast 明确「重启服务后生效」;不在运行时 hot-swap client                                          |
+| R-008   | `MAIL_PROVIDER` 在 `setup_wizard.REQUIRED_CONFIGS` 默认值 `cf_temp_email`,但 SetupConfig 默认值如果不一致会引起冲突 | impl-1 | 低 | SetupConfig 默认值与 REQUIRED_CONFIGS 同步,加 unit test 校验默认值一致性                         |
+
+---
+
+## 13. 未决问题(Open Questions)
+
+| OQ ID | 问题                                                                                                                                        | 决策建议(待 team-lead 确认)                                                                  |
+| ----- | ------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------- |
+| OQ-1  | step=credentials 通过后,是否要在前端把 token 暂存于 vue 内存以便 step=domain_ownership 直接调,还是后端 session 持有?                       | **建议前端暂存**,后端无状态;后端只校验签名,这样后端不增加 session 复杂度                    |
+| OQ-2  | `is_admin=false`(非管理员账号)是否应阻断保存?                                                                                              | **建议警告但允许保存**,因为 `/account/add` 普通用户也能调;`is_admin=false` 时给 hint 即可    |
+| OQ-3  | `_sniff_provider_mismatch` 改为强阻断后,如果用户用的是某种 fork(比如自部署改了 `/admin/address` 为非标响应),会被误伤                      | **建议加 `AUTOTEAM_SKIP_PROVIDER_SNIFF=1` 环境变量逃生口**                                    |
+| OQ-4  | maillab 401 自愈是否应记录到 SQLite/runtime_config,统计 token 失效频率以便后续做 keep-alive?                                              | **暂不做**,Phase 1 先 just-in-time 自愈;有 telemetry 需求时再立 PRD                           |
+| OQ-5  | `/api/mail-provider/probe` 是否要支持 GET(仅 step=fingerprint,可被书签化)?                                                              | **不做**,统一 POST;GET 容易被浏览器历史记录泄露 base_url                                     |
+| OQ-6  | 如果 maillab 实例返回的 `domainList` 是空数组(部署没配 domain),前端是否仍允许进 step=domain_ownership?                                  | **不允许**,直接报错「该实例未配置任何邮箱域名,请先在 maillab 后台 → 设置 → 域名 配置」     |
+
+---
+
+## 14. 实施 Story Map(可拆 sub-task 列表)
+
+> 按照 §10 的 Phase 分组;每个 sub-task 对应一个独立可 review 的 PR。
+
+### Phase 1 — 后端基础(无 UI 风险)
+
+| Sub-task ID | 任务                                                            | 涉及文件                                                                                | 估算 |
+| ----------- | --------------------------------------------------------------- | --------------------------------------------------------------------------------------- | ---- |
+| ST-101      | SetupConfig 扩字段 + REQUIRED_CONFIGS 同步                      | `src/autoteam/api.py`、`src/autoteam/setup_wizard.py`                                   | 0.5d |
+| ST-102      | `cf_temp_email.login()` 嗅探零漏判 + create_temp_email 同步收紧 | `src/autoteam/mail/cf_temp_email.py`                                                    | 0.5d |
+| ST-103      | `MaillabClient` 401 自愈守卫                                    | `src/autoteam/mail/maillab.py`                                                          | 0.5d |
+| ST-104      | `_sniff_provider_mismatch` 改强阻断 + 增 `/setting/websiteConfig` 探测 | `src/autoteam/setup_wizard.py`                                                          | 0.5d |
+| ST-105      | `.env.example` 注释加固                                         | `.env.example`                                                                          | 0.1d |
+| ST-106      | Phase 1 文档同步(getting-started / configuration / mail-provider-design / troubleshooting / api / .env.example) | `docs/*.md` 8 文件                                                                       | 1d   |
+| ST-107      | Phase 1 单元测试                                                | `tests/test_mail_*.py` 4 文件                                                            | 0.5d |
+
+### Phase 2 — Probe 端点 + SetupPage(P0)
+
+| Sub-task ID | 任务                                                       | 涉及文件                                                                                | 估算 |
+| ----------- | ---------------------------------------------------------- | --------------------------------------------------------------------------------------- | ---- |
+| ST-201      | 新建 `src/autoteam/mail/probe.py` 共享 helper              | `src/autoteam/mail/probe.py`(新建)                                                       | 0.5d |
+| ST-202      | `/api/mail-provider/probe` 端点实现 + 错误码归类           | `src/autoteam/api.py`                                                                   | 1d   |
+| ST-203      | `register-domain` PUT 复用 `probe_domain_ownership`        | `src/autoteam/api.py`                                                                   | 0.3d |
+| ST-204      | 前端 `MailProviderCard.vue` 新组件                         | `web/src/components/MailProviderCard.vue`(新建)                                          | 1d   |
+| ST-205      | SetupPage.vue 重构为分组卡片                               | `web/src/components/SetupPage.vue`                                                      | 1d   |
+| ST-206      | api.js 新增 `probeMailProvider`                            | `web/src/api.js`                                                                        | 0.1d |
+| ST-207      | Phase 2 集成 + E2E 测试                                    | `tests/integration/*.py`、`tests/e2e/*.spec.ts`                                          | 1d   |
+
+### Phase 3 — Settings 页切换 UI(P1)
+
+| Sub-task ID | 任务                                            | 涉及文件                                          | 估算 |
+| ----------- | ----------------------------------------------- | ------------------------------------------------- | ---- |
+| ST-301      | Settings.vue 增「邮箱后端」区块,复用 MailProviderCard | `web/src/components/Settings.vue`                  | 0.5d |
+| ST-302      | 切换后 toast「重启服务后生效」                    | `web/src/components/Settings.vue`                 | 0.1d |
+| ST-303      | Phase 3 手测                                    | —                                                 | 0.3d |
+
+**总估算**:Phase 1 ≈ 3.6d / Phase 2 ≈ 4.9d / Phase 3 ≈ 0.9d,合计 ≈ 9.4d(单人)
+
+---
+
+## 附:核验记录(批判性审查)
+
+> 调研报告 §A.3 提到「`REQUIRED_CONFIGS` 与 Web 面板 SetupPage 没有收 maillab 字段」,经直接读取 `setup_wizard.py:20-35` 发现 **REQUIRED_CONFIGS 已含 `MAIL_PROVIDER`**(2026-04 重构后已加),但 `MAILLAB_*` 4 字段仍缺。**推翻调研结论的一半**:不是「全部缺失」,而是「provider 选择项已加,maillab 详细字段仍缺 + SetupConfig 端不接收任何 mail 字段」。
+
+> 调研报告 §D.2 描述的 401 协议错配,**经过核验代码已完成 round-2 修复**:
+> - `cf_temp_email.py:106` 已加嗅探(2026-04-25 commit `de7cad3`)
+> - `setup_wizard.py:259` 已在 `_verify_cloudmail` 第一步调 `_sniff_provider_mismatch`
+> - `_sniff_provider_mismatch` 当前是 warning 级别,未阻断
+>
+> 因此 PRD 重点不是「补齐嗅探」(已有),而是「**收紧条件 + 改强阻断**」。
+
+> 调研报告 §F.2-7 提到「register-domain 探测路径与 §C step=domain_ownership 是否合并」,经核验 `api.py:1631-1673` 已含完整 create+delete 逻辑,**应当抽 helper 合并**(FR-005)。
+

prompts/0426/prd/prd-2-account-lifecycle.md

@@ -0,0 +1,564 @@
+# PRD-2: 账号生命周期与配额加固
+
+## 0. 元数据
+
+| 字段 | 内容 |
+|---|---|
+| 编号 | PRD-2 |
+| 名称 | 账号生命周期与配额加固(plan_type / quota / add-phone / 删除链 / 席位策略) |
+| 覆盖 Issue | #2(席位策略与免费号删除)+ #4(OAuth + add-phone)+ #6(踢出后 401 + 重 OAuth) |
+| 主笔 | prd-lifecycle |
+| 时间 | 2026-04-26 |
+| 优先级 | P0(用户使用率最大瓶颈,3 个 issue 共因) |
+| 关联 PRD | PRD-1(独立)、PRD-3(独立)、PRD-4(独立) |
+| 输入资料 | research/issue-2/4/6 + synthesis.md |
+| 共因合并依据 | synthesis §1:A/B/C/D/E 必须**同 PR**实施,半截修复会引入新故障态 |
+| 不在范围 | Mail Provider(PRD-1)、Docker 镜像守卫(PRD-3)、Playwright 一致性(PRD-4) |
+
+---
+
+## 1. 背景与问题陈述
+
+用户在使用过程中持续暴露 4 类生命周期问题,经调研归并为 **5 个共因点 + 3 个独属点**。
+
+### 1.1 用户子症状(4 issue 合并视角)
+
+| 子症状 | 来源 | 一句话 |
+|---|---|---|
+| **S1**:`self_serve_business_usage_based` 等新 plan 不识别,号能注册但 Codex 调用 429 | #2 / #6 | `codex_auth.py:111` 写死从 JWT 取字段,下游 `manager.py:1468/2490`、`manual_account.py:234` 全用 `if plan_type == "team"` 二元分支 |
+| **S2**:Workspace 配额=0 时 wham/usage 显示"剩余 100%",但调用立刻 429 | #2 / #6 | `codex_auth.py:1582` 只看 `used_percent>=100`,不能识别 `used=0 + total=0` 的"无配额已分配"形态 |
+| **S3**:OAuth 全程没有 add-phone 探针,撞风控就静默 30s 超时 | #4 / #6 | `codex_auth.py` 全文 0 处 `detect_phone_verification`,而 invite 注册阶段已有完整探针(`invite.py:106`) |
+| **S4**:`_run_post_register_oauth` 注册收尾不验配额,假入池 | #6 | `manager.py:1463` 拿到 bundle 立刻 `STATUS_ACTIVE`,无 `check_codex_quota` 探测;手动添加 (`manual_account.py:263`)是有的,接口对称缺失 |
+| **S5**:管理员手动从 ChatGPT 后台踢号 → 子号 401,但本地仅标 STANDBY | #6 | `manager.py:540` `not in_team and status==active → STANDBY`,与"自然待机"不区分,被踢号会被反复 reinvite 死循环 |
+| **S6 (#2 独属)**:邀请席位写死 default,无法配置默认走 codex 席位 | #2 | `invite.py:496` `seat_type="default"` 硬编码;`chatgpt_api.py:1487-1509` PATCH 升级链路单向 |
+| **S7 (#2 独属)**:已退出 Team 走 personal 的免费号,从 UI 删不掉 | #2 | `account_ops.py:78-84` 删除链强依赖主号 session(`fetch_team_state`),personal 号无 Team 关系也走该路径 |
+| **S8 (#6 独属)**:reinvite_account 拿到非 team plan 时,只 kick 一次后留 standby,下轮再选中循环失败 | #6 | `manager.py:2490-2494` `_cleanup_team_leftover` + `STATUS_STANDBY`,未推到 `STATUS_AUTH_INVALID` 终态 |
+
+### 1.2 共因抽象(synthesis §1)
+
+| ID | 共因 | 关联 Issue |
+|---|---|---|
+| A | `plan_type` 白名单(`SUPPORTED_PLAN_TYPES`) | #2 + #6 |
+| B | `wham/usage` 增加 `no_quota` 分类 | #2 + #6 |
+| C | `login_codex_via_browser` 接 add-phone 探针 | #4 + #6 |
+| D | `_run_post_register_oauth` 加 quota probe | #6 |
+| E | `sync_account_states` 区分被踢/待机 | #6 |
+
+A/B/C/D/E **必须同 PR**:任何半截修复都会让其它共因点保留旧故障(例:仅修 D 不修 B,probe 跑出 ok 但实际 quota=0,假入池依旧)。
+
+---
+
+## 2. 目标(SMART)
+
+| 编号 | 目标 | 量化指标 | 度量手段 |
+|---|---|---|---|
+| G1 | 拿到 OAuth bundle 后必须能识别 plan_type 是否被支持 | 100% 覆盖白名单外的 plan_type 立即标 `STATUS_AUTH_INVALID` 或拒收 bundle | `register_failures.json` `category="plan_unsupported"` 计数 |
+| G2 | wham/usage 能识别 `no_quota` 形态 | total=0 / remaining=0 / reset_at=0 任一命中 → 归 `no_quota`,前端 UI 显示明确文案 | 集成测试 + 用户 manual 验证 |
+| G3 | OAuth 命中 add-phone 必须被识别并且不再静默超时 30s | 4 个接入点(about-you / consent / callback / personal 拒收前)各自抛 `RegisterBlocked(is_phone=True)`,2s 内退出 | 单测 mock + 生产 `record_failure` 计数 |
+| G4 | `_run_post_register_oauth` 能区分 ok / exhausted / no_quota / auth_error / network_error | 5 分类 100% 覆盖,exhausted+no_quota → 不入 ACTIVE 池 | 集成测试 |
+| G5 | sync_account_states 能区分人工踢出 vs 自然待机 | 人工踢出 → STATUS_AUTH_INVALID,自然待机 → STATUS_STANDBY,两者不混淆 | 模拟踢人 + reconcile 验证 |
+| G6 | 邀请席位策略可配置 | `PREFERRED_SEAT_TYPE` 取 `chatgpt`/`codex`,UI 可调,生效后 PATCH 不被调用 | 抓包 + 日志 |
+| G7 | personal 子号删除不依赖主号 session | personal/auth_invalid 删除路径短路 `fetch_team_state` | 主号 session 失效场景下批量删除成功率 100% |
+| G8 | reinvite_account 拿到非 team plan 时收敛到终态 | 一次失败即推 `STATUS_AUTH_INVALID`,reconcile 自动接力 | 状态转移日志 |
+
+---
+
+## 3. 非目标
+
+- **不**重写 OAuth 主流程(用户硬要求"不要脱离原本流程太多")。
+- **不**接入 SMS pool 自动绑定手机号(违反 ToS,封号风险)。
+- **不**绕过 add-phone 风控(检测到即放弃 + 标记)。
+- **不**做 IP 池切换 / 自动重试(留作后续 PRD,本期只做检测 + 分类)。
+- **不**改动主号路径 `login_codex_via_session` / `SessionCodexAuthFlow` 的 add-phone 处置(主号通常已绑定,极罕见)。
+- **不**改前端"补登录"按钮的交互流程(OAuth 模式选择 UI 是 P2,后置 PR)。
+- **不**新增 `STATUS_PHONE_REQUIRED` 状态(round-3 已新增 AUTH_INVALID/ORPHAN,本次复用 + register_failures 子分类)。
+
+---
+
+## 4. 用户故事
+
+- **US-1**(场景 S1+S5)作为运营人员,我希望系统识别 OpenAI 后端返回的新 `plan_type`(如 `self_serve_business_usage_based`),不要把不可用账号塞进 ACTIVE 池让 CPA 调用 429。
+- **US-2**(场景 S2)作为管理员,我看到的"剩余额度 100%"必须真实可用,不能名义剩余实际 429。
+- **US-3**(场景 S3)作为运维,在 OAuth 阶段命中 add-phone 时,必须立即知晓(失败明细分类 `oauth_phone_blocked`),不要静默 30s 超时再写"未获取到 auth code"。
+- **US-4**(场景 S4)作为账号管理者,从注册→入池每一步的状态变化都应严格反映"账号是否真可用"。
+- **US-5**(场景 S5)作为团队管理员,我从 ChatGPT 后台手动踢一个号后,本地系统应识别为"被踢"(STATUS_AUTH_INVALID),让 reconcile 自动接管,不要反复 reinvite。
+- **US-6**(场景 S6)作为席位策略调度者,我希望能在 UI 上设置"默认走 codex 席位",留出 ChatGPT 主席位给真人。
+- **US-7**(场景 S7)作为账号清理者,即便主号 session 已失效,我仍能删除已退出 Team 的 personal 子号。
+- **US-8**(场景 S8)作为 standby 池监管者,reinvite 拿到非 team plan 应立即进入终态,不要反复试。
+
+---
+
+## 5. 功能需求(FR)
+
+### 5.1 [共因 A] plan_type 白名单(`SUPPORTED_PLAN_TYPES`)
+
+**FR-A1** 在 `accounts.py` 同级新增常量集 `SUPPORTED_PLAN_TYPES = frozenset({"team", "free", "plus", "pro"})`(全小写)。
+
+**FR-A2** 提供 `is_supported_plan(plan_type: str) -> bool` 工具函数,内部 `.lower().strip()` 后比对。
+
+**FR-A3** `codex_auth.py:_exchange_auth_code`(L100-116)拿到 bundle 后,**写入新字段** `bundle["plan_supported"] = is_supported_plan(plan_type)`,不直接拒收(避免破坏现有 personal 模式校验路径)。
+
+**FR-A4** 4 个下游消费点统一改造:
+- `manual_account._finalize_account` (L233):`if plan_type == "team"` → 改为白名单查询。`plan_supported=False` → `STATUS_AUTH_INVALID` + `record_failure(category="plan_unsupported")` + 不写 last_quota。
+- `manager._run_post_register_oauth` (L1467):同上,Team 分支 plan_supported=False → 不进 ACTIVE,改 STATUS_AUTH_INVALID。
+- `manager.reinvite_account` (L2489):保持 `plan_type != "team"` 失败语义,但额外记录 `category="plan_drift"`,标记 `auth_file=None` + `STATUS_AUTH_INVALID`(见 FR-5.8)。
+- `cpa_sync._infer_plan_from_filename`(L132-140):允许识别新增字面量(可选)。
+
+**FR-A5** 字面量小写归一化:任何对 `plan_type` 的判定都先 `.lower()`,避免 OpenAI 返回 `Team` / `Self_Serve_*` 大小写漂移。
+
+### 5.2 [共因 B] wham/usage `no_quota` 分类
+
+**FR-B1** 扩展 `check_codex_quota`(`codex_auth.py:1618`)返回值,在原 4 分类基础上新增 `("no_quota", info)`:
+- 触发条件(任一命中):
+  1. `rate_limit.primary_window.limit == 0` 且 `used_percent == 0`
+  2. `rate_limit.primary_window.reset_at == 0` 且 `used_percent == 0`
+  3. `rate_limit.primary_window.remaining == 0` 且 `total == 0`
+  4. 200 OK 但 `rate_limit` 字段为空 / 缺 `primary_window`(空载也是 no_quota 信号)
+- 返回 info 形如 `{"reason": "no_quota_assigned", "raw_rate_limit": {...}}`
+
+**FR-B2** `quota_info` 字段扩 `total` / `remaining`(若接口提供):
+```python
+quota_info = {
+    "primary_pct": primary.get("used_percent", 0),
+    "primary_resets_at": primary.get("reset_at", 0),
+    "primary_total": primary.get("limit", 0) or primary.get("total", 0),
+    "primary_remaining": primary.get("remaining"),
+    "weekly_pct": secondary.get("used_percent", 0),
+    "weekly_resets_at": secondary.get("reset_at", 0),
+}
+```
+
+**FR-B3** `get_quota_exhausted_info`(L1572)在判 `primary_pct >= 100` 之前加一道 `primary_total == 0` 短路,返回 `{"window": "no_quota", "resets_at": int(time.time() + 86400)}`(24h 内不再探测)。
+
+**FR-B4** 9 个 `check_codex_quota` 调用方(api.py 3 + manager.py 5 + manual_account.py 1)都需要识别 `no_quota`:统一处置为"标 STATUS_EXHAUSTED 但 quota_resets_at=time+86400"或新增分支 STATUS_AUTH_INVALID(取决于业务语义)。**默认实现:no_quota → STATUS_AUTH_INVALID + auth_file 保留(供调试)+ register_failures `category="no_quota_assigned"`**。
+
+### 5.3 [共因 C] `login_codex_via_browser` 接入 add-phone 探针
+
+**FR-C1** 在 `codex_auth.py` 顶部 `from autoteam.invite import RegisterBlocked, assert_not_blocked`(无循环依赖,invite.py 不引 codex_auth)。
+
+**FR-C2** **4 个接入点**(以 codex_auth.py:250 为基准行号):
+| 编号 | 行号 | 时机 | 调用 |
+|---|---|---|---|
+| C-P1 | L568(about-you 入口前) | `if "about-you" in page.url:` 之前 | `assert_not_blocked(page, "oauth_about_you")` |
+| C-P2 | L612-880(consent 10 次循环每轮) | `for step in range(10):` 内每次 try 块开头 | `assert_not_blocked(page, f"oauth_consent_{step}")` |
+| C-P3 | L884(等 callback 前) | `for _ in range(30):` 之前 | `assert_not_blocked(page, "oauth_callback_wait")` |
+| C-P4 | L932(personal 拒收 bundle 之前) | `if use_personal:` 之前 | `assert_not_blocked(page, "oauth_personal_check")`(防御性,通常 callback 前已拦截) |
+
+**FR-C3** `RegisterBlocked` 异常向上抛,`login_codex_via_browser` 调用方一律 `try/except RegisterBlocked` 并按调用点分类:
+- **api.py:1479** 补登录:转 HTTP 409 + body `{"error": "phone_required", "step": ...}`
+- **manager.py:1057** _check_pending_invites:`record_failure(category="oauth_phone_blocked")` + 删账号
+- **manager.py:1431** personal OAuth:`delete_account` + `record_failure(category="oauth_phone_blocked")`
+- **manager.py:1463** Team OAuth 收尾:`update_account(STATUS_AUTH_INVALID)` + `record_failure(category="oauth_phone_blocked")`
+- **manager.py:2466** reinvite_account:`_cleanup_team_leftover("oauth_phone_blocked")` + `STATUS_AUTH_INVALID`(见 5.8)
+
+**FR-C4** 命中 add-phone 立即调 `_screenshot(page, f"codex_phone_blocked_{step}.png")` 留证据,便于回放。
+
+**FR-C5** `register_failures.py` `category` 注释扩 `oauth_phone_blocked`(与注册阶段 `phone_blocked` 区分,便于统计与告警分级)。
+
+### 5.4 [共因 D] `_run_post_register_oauth` 加 quota probe
+
+**FR-D1** `manager.py:1463-1486` Team 分支获得 bundle 后,追加 quota probe 段:
+```python
+# 拿到 bundle 后,与 manual_account._finalize_account(L260-272)对称,
+# 不能让 quota=0 / no_quota / auth_error 的号假入 ACTIVE 池
+access_token = bundle.get("access_token")
+account_id = bundle.get("account_id")
+quota_status, quota_info = check_codex_quota(access_token, account_id=account_id)
+```
+
+**FR-D2** quota_status 5 分类处置:
+| status | 处置 |
+|---|---|
+| `ok` | 写 `last_quota=quota_info`,STATUS_ACTIVE(原行为) |
+| `exhausted` | STATUS_EXHAUSTED + `quota_exhausted_at=now` + `quota_resets_at=quota_result_resets_at(info)` |
+| `no_quota`(新) | STATUS_AUTH_INVALID + `record_failure(category="no_quota_assigned")` + 仍保留 auth_file 供调试 |
+| `auth_error` | STATUS_AUTH_INVALID + `record_failure(category="auth_error_at_oauth")` |
+| `network_error` | 沿用旧 STATUS_ACTIVE(避免一次抖动批量误标),但 `record_failure(category="quota_probe_network_error")` |
+
+**FR-D3** Personal 分支(L1431,`leave_workspace=True`)获得 free bundle 后,**同样**调 quota probe(对称设计)。
+
+**FR-D4** probe 调用本身要包 try/except:抛异常时降级到 STATUS_ACTIVE 但记 `register_failures` 一条 exception(避免 probe bug 阻塞注册主流程)。
+
+### 5.5 [共因 E] `sync_account_states` 区分被踢/待机
+
+**FR-E1** `manager.py:526-541` 在 `not in_team and acc["status"] == STATUS_ACTIVE` 分支,**保留**当前 workspace_account_id 漂移检测(L531-538),其下追加 wham 探测:
+```python
+if acc.get("auth_file"):
+    try:
+        bundle = load_auth_file(acc["auth_file"])
+        access_token = bundle.get("access_token")
+        if access_token:
+            status_str, _ = check_codex_quota(access_token)
+            if status_str == "auth_error":
+                acc["status"] = STATUS_AUTH_INVALID
+                changed = True
+                continue
+    except Exception:
+        pass  # 探测失败不阻塞主流程
+acc["status"] = STATUS_STANDBY
+changed = True
+```
+
+**FR-E2** 探测加并发限制(避免 N 个号串行 wham 拖慢 sync):用 `concurrent.futures.ThreadPoolExecutor(max_workers=5)` + 单调用超时 5s。
+
+**FR-E3** 探测去重:同一 email 在 30 分钟内不重复探测(读 `last_quota_check_at` 字段 + 写入新值)。
+
+**FR-E4** sync 主循环不能因为探测异常崩溃 → 任何 except 都仅 log warning + 走旧 STATUS_STANDBY 默认行为。
+
+### 5.6 [#2 独属] `PREFERRED_SEAT_TYPE` 配置开关
+
+**FR-F1** `runtime_config.py` 新增 `get_preferred_seat_type()` / `set_preferred_seat_type(value)`,值域 `{"chatgpt", "codex"}`,默认 `"chatgpt"`(保持现行行为)。
+
+**FR-F2** `invite.py:496` 改为:
+```python
+preferred = (get_preferred_seat_type() or "chatgpt").lower()
+seat_type_param = "default" if preferred == "chatgpt" else "usage_based"
+status, data = chatgpt.invite_member(email, seat_type=seat_type_param)
+```
+
+**FR-F3** `chatgpt_api.py:_invite_member_once`(L1414)的 PATCH 升级段(L1487-1506):新增 `allow_patch_upgrade` 参数,默认 True;调用方传入 `allow_patch_upgrade=(preferred == "chatgpt")`。`PREFERRED_SEAT_TYPE=codex` 时 PATCH 完全跳过,`_seat_type` 保持 `usage_based`。
+
+**FR-F4** `_invite_member_with_fallback`(L1387)的兜底链向后兼容:
+- `preferred=chatgpt`:default → usage_based 兜底(原行为)
+- `preferred=codex`:直接 usage_based,不兜底 default
+
+**FR-F5** Web 前端 Settings 页新增"邀请席位偏好"下拉(`chatgpt` / `codex`),写 `runtime_config.preferred_seat_type`。
+
+**FR-F6** 状态变更立即生效,不需要重启;并发安全(读取每次邀请前从 runtime_config 拉,而非启动时缓存)。
+
+### 5.7 [#2 独属] personal 删除链解耦主号 session
+
+**FR-G1** `account_ops.delete_managed_account`(L40-162)新增短路逻辑:
+```python
+acc = find_account(accounts, email)
+short_circuit = False
+if remove_remote and acc:
+    if acc.get("status") in (STATUS_PERSONAL, STATUS_AUTH_INVALID):
+        short_circuit = True
+        members, invites = [], []  # 跳过 fetch_team_state
+        logger.info("[账号] %s 状态=%s,跳过 Team 远端同步,直接清本地", email, acc.get("status"))
+```
+
+**FR-G2** short_circuit=True 时,跳过 L78-84 的 `ChatGPTTeamAPI().start()` + `fetch_team_state()`,member_matches/invite_matches 为空,直接走 auth_file/cpa/local 删除。
+
+**FR-G3** `api.delete_accounts_batch`(L1306-1404)在批量场景下:
+- 先扫一遍 batch 内所有 acc.status,**全是 personal/auth_invalid 时**,完全不起 ChatGPTTeamAPI(传 `chatgpt_api=None` + 在 short_circuit 中再次保护)
+- 混合场景(部分 personal + 部分 team):仍起 ChatGPTTeamAPI,但 short_circuit 单条生效
+
+**FR-G4** UI 删除失败 toast 增强(`Dashboard.vue:566-585` `removeAccount`):
+- 失败原因(`actionDisabled` / 409 / 500)区分提示
+- 删除成功立即 `emit('refresh')` 触发账号列表 reload
+- 不再"按钮没反应"误解
+
+### 5.8 [#6 独属] `reinvite_account` 兜底(plan_type ≠ team 时清理)
+
+**FR-H1** `manager.py:2489-2494`:`plan_type != "team"` 分支,在 `_cleanup_team_leftover` 后追加:
+```python
+update_account(
+    email,
+    status=STATUS_AUTH_INVALID,    # 不要回 STANDBY,会被反复选中循环
+    auth_file=None,                # 清掉错误 plan 的 token
+    quota_exhausted_at=None,
+    quota_resets_at=None,
+)
+record_failure(email, "plan_drift", f"reinvite 拿到 plan={plan_type or 'unknown'} != team",
+               stage="reinvite", source="reinvite_account")
+```
+
+**FR-H2** **批判:不会误伤合法 personal 转化路径**。`reinvite_account` 只从 STATUS_STANDBY 池被选中(`manager.py:2643+`),其语义预设是"恢复到 Team 工作池";用户希望让某号转 personal 的合法入口是 `cmd_fill_personal`(走 `_run_post_register_oauth(leave_workspace=True)`),与 reinvite 完全分离。reinvite 拿到非 team plan 永远是异常状态,推 STATUS_AUTH_INVALID 后,reconcile 会按 auth_invalid 流程处理(KICK + 清理),不再有死循环。**风险登记册 R-7** 列入跟踪。
+
+**FR-H3** reinvite 失败被推到 AUTH_INVALID 后,reconcile_anomalies(`manager.py:161-471`)的 KICK 分支会把 Team 残留清干净,本地记录最终被删除或留着等用户介入(取决于 `auth_invalid` 处置策略)。
+
+---
+
+## 6. 非功能需求
+
+| 编号 | 需求 |
+|---|---|
+| NFR-1 | 性能:`sync_account_states` 探测段不能让单轮 sync 超过 30s(并发 5 + 超时 5s) |
+| NFR-2 | 兼容性:旧 accounts.json 记录(无 `plan_supported` / `last_quota.primary_total` 字段)走默认值,不报错 |
+| NFR-3 | 可观测:每个新 category(`plan_unsupported` / `no_quota_assigned` / `oauth_phone_blocked` / `auth_error_at_oauth` / `quota_probe_network_error` / `plan_drift`)在 `register_failures.json` 都能独立计数 |
+| NFR-4 | 灰度:`PREFERRED_SEAT_TYPE` 默认 `chatgpt`,与现行行为完全一致;切到 `codex` 须显式操作 |
+| NFR-5 | 可回滚:所有改动可被一个 revert PR 撤销;`accounts.json` schema 向后兼容 |
+| NFR-6 | 安全:add-phone 截图存 `screenshots/codex_phone_blocked_*.png`,不含 cookie/token |
+| NFR-7 | 文档:CHANGELOG.md 必须列出 5 个新 category + 4 个新探针接入点 |
+
+---
+
+## 7. 技术方案
+
+### 7.1 状态机更新(account state machine)
+
+新增/澄清的边:
+
+```
+ACTIVE ──[sync 探测 wham=auth_error]──→ AUTH_INVALID  (新,FR-E1)
+ACTIVE ──[sync 探测 wham=ok]────────────→ STANDBY       (语义不变,但前提是探测通过)
+ACTIVE ──[wham=no_quota]─────────────────→ AUTH_INVALID  (新,FR-D2)
+PENDING ──[bundle plan_unsupported]─────→ AUTH_INVALID  (新,FR-A4)
+STANDBY ──[reinvite plan!=team]──────────→ AUTH_INVALID  (新,FR-H1,替代旧 STANDBY)
+STANDBY ──[reinvite OAuth phone]─────────→ AUTH_INVALID  (新,FR-C3)
+PENDING ──[OAuth phone 命中]─────────────→ AUTH_INVALID  (新,FR-C3 之 manager.py:1463 分支)
+PENDING ──[personal OAuth phone]────────→ deleted        (新,FR-C3 之 manager.py:1431 分支)
+```
+
+### 7.2 配额分类规则(quota classification)
+
+```
+HTTP 401/403                               → auth_error
+HTTP 200 + primary_total == 0              → no_quota          (新)
+HTTP 200 + reset_at == 0 && used_pct == 0  → no_quota          (新)
+HTTP 200 + rate_limit 缺失/空              → no_quota          (新)
+HTTP 200 + primary_pct >= 100 || weekly_pct >= 100 → exhausted (原)
+HTTP 200 + 上述都不命中                     → ok               (原)
+HTTP 429 / 5xx / json 解析失败 / 网络异常  → network_error    (原)
+```
+
+### 7.3 add-phone 探针在 OAuth 流程的接入点(4 处)
+
+```
+login_codex_via_browser(email, password, mail_client, *, use_personal)
+  │
+  ├─ step-0 (Team 模式 cookie 注入)
+  │
+  ├─ step-1 邮箱/密码/OTP 表单
+  │
+  ├─ ★ C-P1: assert_not_blocked(page, "oauth_about_you")    [L568 about-you 前]
+  ├─ step-2 about-you 提交
+  │
+  ├─ ★ C-P2: assert_not_blocked(page, f"oauth_consent_{i}") [L612 consent 循环每轮]
+  ├─ step-3 consent 10 轮循环(workspace 选择 / Continue 按钮)
+  │
+  ├─ ★ C-P3: assert_not_blocked(page, "oauth_callback_wait") [L884 等 callback 前]
+  ├─ step-4 等 30s callback
+  │
+  ├─ ★ C-P4: assert_not_blocked(page, "oauth_personal_check") [L932 personal 拒收前,防御性]
+  └─ _exchange_auth_code → bundle
+```
+
+### 7.4 数据模型变更(accounts.json schema)
+
+```python
+# Pydantic 模型(用于内部类型签名 / 测试断言)
+class AccountRecord(BaseModel):
+    email: str
+    password: str
+    cloudmail_account_id: Optional[str] = None
+    status: Literal["active", "exhausted", "standby", "pending", "personal", "auth_invalid", "orphan"]
+    seat_type: Literal["chatgpt", "codex", "unknown"] = "unknown"
+    workspace_account_id: Optional[str] = None
+    auth_file: Optional[str] = None
+    quota_exhausted_at: Optional[float] = None
+    quota_resets_at: Optional[float] = None
+    last_quota_check_at: Optional[float] = None  # FR-E3 探测去重
+    last_quota: Optional[QuotaSnapshot] = None
+    last_active_at: Optional[float] = None
+    created_at: float
+    plan_supported: Optional[bool] = None  # 新增,FR-A3
+    plan_type_raw: Optional[str] = None    # 新增,记录 OAuth 实际拿到的字面量,便于排查
+
+class QuotaSnapshot(BaseModel):
+    primary_pct: int = 0
+    primary_resets_at: int = 0
+    primary_total: Optional[int] = None      # 新增 FR-B2
+    primary_remaining: Optional[int] = None  # 新增 FR-B2
+    weekly_pct: int = 0
+    weekly_resets_at: int = 0
+
+class QuotaProbeResult(BaseModel):
+    status: Literal["ok", "exhausted", "no_quota", "auth_error", "network_error"]
+    info: Optional[Union[QuotaSnapshot, dict]] = None
+```
+
+### 7.5 配置项变更(`runtime_config` + `.env`)
+
+| key | 来源 | 取值 | 默认 | 用途 |
+|---|---|---|---|---|
+| `preferred_seat_type` | runtime_config.json | `chatgpt` / `codex` | `chatgpt` | FR-F1,席位偏好 |
+| `quota_probe_threshold_pct` | runtime_config.json | `0..100` | `10` | reinvite 后 5h 剩余阈值,与现有 AUTO_CHECK_THRESHOLD 一致 |
+| `sync_probe_concurrency` | runtime_config.json | int | `5` | FR-E2,sync 探测并发 |
+| `sync_probe_cooldown_minutes` | runtime_config.json | int | `30` | FR-E3,探测去重 |
+
+`.env` 新增:
+- `PREFERRED_SEAT_TYPE_DEFAULT`(可选,首次启动写入 runtime_config 的初始值)
+
+### 7.6 前端变更(Settings + Dashboard)
+
+| 组件 | 改动 |
+|---|---|
+| `web/src/views/Settings.vue` | 新增"邀请席位偏好"下拉(FR-F5)、"配额探测并发数"(FR-E2)、"探测去重分钟数"(FR-E3) |
+| `web/src/components/Dashboard.vue` | 删除按钮 toast 增强(FR-G4);状态白名单加 `auth_invalid` 显示文案(round-3 已加,本期复核);quota 显示区识别 `no_quota` 渲染"无配额"而非"100% 剩余" |
+| `web/src/api.ts` | `/api/accounts/{email}/login` 加入 409 错误体解析(`error: "phone_required"`),弹窗提示用户 |
+
+---
+
+## 8. 验收标准
+
+| FR | 验收用例 | 通过条件 |
+|---|---|---|
+| FR-A1~A5 | 注册一个 OAuth bundle 字面值 = `self_serve_business_usage_based`(可 mock JWT) | 账号被打 STATUS_AUTH_INVALID + register_failures 命中 `category="plan_unsupported"`,`plan_type_raw` 落盘 |
+| FR-B1~B4 | wham/usage 返回 `{"primary_window": {"limit": 0, "used_percent": 0}}` | quota_status="no_quota",前端 UI 显示"无配额",账号 STATUS_AUTH_INVALID |
+| FR-C1~C5 | OAuth 流程到 about-you 后 page.url 跳到 `add-phone` | 4 个接入点任一抛 RegisterBlocked,`category="oauth_phone_blocked"`,截图落盘 |
+| FR-D1~D4 | 注册收尾 bundle 拿到但 wham 返回 no_quota | 账号 STATUS_AUTH_INVALID 而非 ACTIVE |
+| FR-E1~E4 | 管理员从 ChatGPT 后台手动踢一个 active 子号 | 下次 sync_account_states 跑后,该号 STATUS_AUTH_INVALID(不是 STANDBY) |
+| FR-F1~F6 | UI 设置 `preferred_seat_type=codex` → 触发 invite | invite_member 调 `seat_type="usage_based"`,日志中 0 处 PATCH 升级 |
+| FR-G1~G4 | personal 子号 + 主号 session 失效 → 单点删除 | 不抛 ChatGPTTeamAPI 启动错误,本地记录被清,UI 列表刷新 |
+| FR-H1~H3 | reinvite 拿到 plan=free 的 bundle | 账号 STATUS_AUTH_INVALID,reconcile 自动 KICK + 清 auth_file |
+
+---
+
+## 9. 测试计划
+
+### 9.1 单元测试
+
+- `tests/unit/test_plan_type_whitelist.py`:`is_supported_plan` 7 种字面量(team/free/plus/pro/Team/self_serve_business_usage_based/空串)
+- `tests/unit/test_quota_classification.py`:5 分类 mock wham/usage 各响应,断言 status_str
+- `tests/unit/test_oauth_phone_detection.py`:4 接入点各自 mock page.url + body,assert_not_blocked 抛异常
+- `tests/unit/test_run_post_register_quota_probe.py`:5 quota_status × 2 (Team/personal) 路径
+- `tests/unit/test_sync_state_classify.py`:被踢 vs 自然待机区分
+- `tests/unit/test_preferred_seat_type.py`:chatgpt/codex 两种偏好下 invite_member 入参
+- `tests/unit/test_personal_delete_short_circuit.py`:STATUS_PERSONAL/AUTH_INVALID 跳过 fetch_team_state
+
+### 9.2 集成测试
+
+- `tests/integration/test_oauth_phone_blocked_flow.py`:全链路 mock,验证 6 处 login_codex_via_browser 调用方都能正确分类 + 打到 register_failures
+- `tests/integration/test_quota_probe_no_quota.py`:wham 返回 limit=0 → 注册→入池→标 AUTH_INVALID 全链路
+
+### 9.3 回归测试
+
+- 既有 `invite/reinvite/sync_account_states/_run_post_register_oauth/check_codex_quota` 套件全部跑过
+- `manual_account.py` finalize 流程不受 plan_type 白名单影响(对称改造保护)
+
+### 9.4 E2E / 手测
+
+- 手动:从 ChatGPT 后台踢一个号,等 1 个 rotate 周期,确认状态机正确
+- 手动:UI 切 PREFERRED_SEAT_TYPE 后注册新号,确认 PATCH 不被调用
+- 手动:邀请一个新号触发 add-phone(可能需要 IP 漂移/cookie 清空),确认探针命中
+
+---
+
+## 10. 灰度/回滚策略
+
+### 10.1 灰度
+
+- **阶段 0**:实施 PR(默认 PREFERRED_SEAT_TYPE=chatgpt,行为不变),只观察新 category 计数
+- **阶段 1**:1-2 周后,根据 `register_failures.json` 数据评估 PATCH 升级实际失败率,决定是否在 default 配置中切到 codex
+- **阶段 2**:监控 STATUS_AUTH_INVALID 总数与人工介入率,若 reconcile 自动接管率 < 90%,新增告警
+
+### 10.2 回滚
+
+- 单 PR revert 即可:所有新增字段(`plan_supported`/`primary_total`/...)向后兼容,旧代码读不到字段走默认值
+- 配置回滚:删除 `runtime_config.json` 中的新键即恢复硬编码默认
+
+---
+
+## 11. 文档影响清单
+
+| 文件 | 改动 |
+|---|---|
+| `CHANGELOG.md` | 新增条目:5 个新 register_failures category、4 个 OAuth 探针接入点、PREFERRED_SEAT_TYPE 配置 |
+| `docs/account-state-machine.md`(新建) | 7 状态完整转移图,含本 PRD 新增的边 |
+| `docs/quota-classification.md`(新建) | 5 分类规则、no_quota 触发条件、调用方处置矩阵 |
+| `docs/oauth-add-phone-detection.md`(新建) | 4 接入点位置、检测器复用契约 |
+| `README.md` | 配置说明加 PREFERRED_SEAT_TYPE |
+| `web/README` | Settings 页新加配置项说明 |
+
+---
+
+## 12. 风险登记册
+
+| 编号 | 风险 | 等级 | 概率 | 缓解 | 来源 |
+|---|---|---|---|---|---|
+| R-1 | sync_account_states 加 wham 探测后,N 个 active 号串行探测拖慢 rotation | 高 | 中 | NFR-1 限 30s + 并发 5 + 探测去重 30 分钟 | gitnexus.impact `sync_account_states`:被 manager.py:696/2843 调用,rotation 主路径 |
+| R-2 | check_codex_quota 加 no_quota 分类,9 个调用点漏改任一 → no_quota 被当 ok 默认 | 高 | 中 | FR-B4 显式枚举所有调用方 + 单测覆盖 + lint 守卫 | gitnexus.impact `check_codex_quota`:9 处调用 |
+| R-3 | login_codex_via_browser 加 RegisterBlocked 抛异常,5 处调用方漏 catch → 主流程崩溃 | 高 | 低 | FR-C3 显式列 5 处处置 + 集成测试 | gitnexus.impact `login_codex_via_browser`:5 处调用 |
+| R-4 | _run_post_register_oauth probe 异常吞 → 假 ACTIVE 回到旧故障 | 中 | 中 | FR-D4 try/except + register_failures 计数监控 | gitnexus.impact `_run_post_register_oauth`:3 处调用 |
+| R-5 | invite.py 的 detect_phone_verification 在 OAuth 域(auth.openai.com)误报 consent 页 phone 提示 | 中 | 低 | 命中后立即截图,运营回放确认;必要时给 OAuth 探针定制更严格规则 | issue#4 风险 E.1.3 |
+| R-6 | reinvite 后的 STATUS_AUTH_INVALID 与 reconcile_anomalies 的 KICK 分支耦合,任一改一处都可能影响另一处 | 中 | 中 | 单测 + 集成测试 + 显式注释 | issue#6 D.1.6 |
+| R-7 | reinvite 拿到 free plan 当作"plan_drift"标 AUTH_INVALID,但用户合法的"号转 personal"路径走 cmd_fill_personal 不会进 reinvite_account,因此**不存在误伤** | 低 | 极低 | FR-H2 已注明语义边界;reinvite 入口只从 STANDBY 池被选,与 personal 转化的入口完全分离 | task 第 3 条批判 |
+| R-8 | PATCH 升级失败率统计未知 → 默认 PREFERRED_SEAT_TYPE 选错 | 低 | 中 | NFR-4 默认保持 chatgpt 不变,1-2 周观察后再调 | issue#2 F.2 |
+| R-9 | wham/usage 真实 schema 未知,limit/total 字段可能不存在 | 中 | 中 | FR-B1 触发条件 4 任一命中即可,接口缺字段→空载也归 no_quota;先上线再观察 | issue#2 F.1 / synthesis §7 |
+| R-10 | OpenAI 后端 plan_type 字面量大小写漂移 | 低 | 低 | FR-A5 强制 .lower() 归一化 | issue#2 F.4 |
+| R-11 | 主号 OAuth 流程也撞 add-phone(罕见但可能) | 低 | 极低 | 非目标:本期不处置主号路径;日志 ERROR 即可 | issue#4 E.2.1 |
+| R-12 | personal 删除短路后,某些"标着 personal 但实际还在 Team"的脏记录会被漏删 Team 残留 | 中 | 低 | reconcile_anomalies 仍会扫整个 Team 把 ghost 清掉,作为兜底 | issue#2 F.3 |
+
+---
+
+## 13. 未决问题(送实施阶段决议)
+
+| 编号 | 问题 | 提案 |
+|---|---|---|
+| Q-1 | `wham/usage` 在 `self_serve_business_usage_based` workspace 真实返回 schema | 先从用户实际 `auths/codex-*.json` + 一次抓包获取样本;若 limit/total 字段缺失,FR-B1 触发条件 4(rate_limit 空)兜底 |
+| Q-2 | `self_serve_business_usage_based` 是否是真实字面量 | 先从用户报告的样本核对;如果实际是 `chatgpt_business_usage_based` 等变体,白名单兼容(只看是否在 SUPPORTED_PLAN_TYPES,实际值都进 unsupported 分支即可) |
+| Q-3 | PATCH 升级失败率 | 改默认席位策略前先收集 1-2 周数据;如失败率 >30%,默认改 codex |
+| Q-4 | `STATUS_PHONE_REQUIRED` 是否新增 | 不新增,复用 STATUS_AUTH_INVALID + register_failures.category 区分,符合本 PRD 非目标 |
+| Q-5 | sync_account_states 探测的并发 5 / 超时 5s 是否合理 | 灰度阶段 0 观察 sync 单轮耗时,>30s 调到 10 / 3s |
+| Q-6 | reinvite_account 推到 AUTH_INVALID 后,reconcile 是否需要等用户介入还是自动删除 | 默认自动 KICK + 保留本地记录(供查看 register_failures);删本地由 UI 单点/批量删除触发 |
+| Q-7 | OAuth 模式选择 UI(personal vs Team)放本期还是后置 | 后置(优先级 P2),不阻塞主线 |
+
+---
+
+## 14. 实施 Story Map
+
+按"先抽 spec 共享层 → 再改 4 个文件 → 最后改 UI"排列,**严格按依赖**。
+
+### Phase 0: 共享 spec 与常量(2 文件,半天)
+
+- [ ] **S-0.1** 在 `accounts.py` 新增 `SUPPORTED_PLAN_TYPES` + `is_supported_plan()`(FR-A1/A2)
+- [ ] **S-0.2** 在 `runtime_config.py` 新增 `get/set_preferred_seat_type` + 默认值(FR-F1)
+- [ ] **S-0.3** 在 `register_failures.py` 文档化新增 6 个 category 名称(FR-A4/B4/C5/D2/E1/H1)
+- [ ] **S-0.4** 写 `spec/shared/plan-type-whitelist.md` / `quota-classification.md` / `add-phone-detection.md` / `account-state-machine.md`(synthesis §5)
+
+### Phase 1: 共因点核心实现(4 文件,2-3 天)
+
+- [ ] **S-1.1** `codex_auth.py:_exchange_auth_code` 写 `plan_supported` 字段(FR-A3)
+- [ ] **S-1.2** `codex_auth.py:check_codex_quota` 加 `no_quota` 分类 + 扩 quota_info 字段(FR-B1/B2/B3)
+- [ ] **S-1.3** `codex_auth.py:login_codex_via_browser` 4 个 add-phone 探针接入点(FR-C1/C2/C3 仅探针,异常上抛部分由 S-2.x 处理)
+- [ ] **S-1.4** `manager.py:_run_post_register_oauth` 加 quota probe(FR-D1/D2/D3/D4)
+- [ ] **S-1.5** `manager.py:sync_account_states` 加 wham 探测区分被踢(FR-E1/E2/E3/E4)
+- [ ] **S-1.6** `manager.py:reinvite_account` plan_drift 终态(FR-H1)
+- [ ] **S-1.7** `manual_account._finalize_account` 改造白名单(FR-A4 第 1 项)
+- [ ] **S-1.8** `account_ops.delete_managed_account` 短路逻辑(FR-G1/G2)
+
+### Phase 2: 调用方处置(2 文件,1-2 天)
+
+- [ ] **S-2.1** `manager.py` 4 处 login_codex_via_browser 调用方加 try/except RegisterBlocked + 分类(FR-C3 in: L1057/1431/1463/2466)
+- [ ] **S-2.2** `api.py` `/api/accounts/{email}/login` 加 try/except + 409 错误体(FR-C3 in: L1479)
+- [ ] **S-2.3** 9 处 check_codex_quota 调用方加 `no_quota` 分支(FR-B4)
+- [ ] **S-2.4** `api.delete_accounts_batch` 全 personal 时不起 ChatGPTTeamAPI(FR-G3)
+
+### Phase 3: 席位策略(2 文件,1 天)
+
+- [ ] **S-3.1** `invite.py:496` 改读 PREFERRED_SEAT_TYPE(FR-F2)
+- [ ] **S-3.2** `chatgpt_api.py:_invite_member_once` 加 `allow_patch_upgrade` 参数(FR-F3)
+- [ ] **S-3.3** `chatgpt_api.py:_invite_member_with_fallback` 兜底链分支(FR-F4)
+
+### Phase 4: 前端 UI(2 文件,1 天)
+
+- [ ] **S-4.1** `web/src/views/Settings.vue` 新增"邀请席位偏好"下拉 + 探测并发/去重(FR-F5/E2/E3)
+- [ ] **S-4.2** `web/src/components/Dashboard.vue` 删除 toast 增强 + quota 显示识别 no_quota(FR-G4)
+- [ ] **S-4.3** `web/src/api.ts` 解析 409 phone_required 错误体
+
+### Phase 5: 测试 + 文档(贯穿所有 Phase)
+
+- [ ] **S-5.1** 单测覆盖 §9.1 的 7 个测试文件
+- [ ] **S-5.2** 集成测试覆盖 §9.2 的 2 个测试文件
+- [ ] **S-5.3** CHANGELOG / docs 文档更新(§11)
+- [ ] **S-5.4** 手测脚本(§9.4)
+
+### Phase 6: 灰度上线(1 天)
+
+- [ ] **S-6.1** 默认 chatgpt 偏好上线,观察 register_failures 计数
+- [ ] **S-6.2** 1-2 周后根据数据决议 PREFERRED_SEAT_TYPE 默认值切换(Q-3)
+
+**关键依赖**:
+- Phase 1 必须早于 Phase 2(被调用方先实现,调用方再 catch)
+- Phase 0 早于 Phase 1(常量先定义,代码再引用)
+- Phase 3 与 Phase 1/2 解耦,可并行实施
+- Phase 4 在 Phase 1-3 完成后再做
+- 所有 Phase 都伴随 Phase 5 的测试与文档更新
+
+---
+
+**文档结束。** 字数:约 4200(含表格、代码块、Story Map)。
+

prompts/0426/prd/prd-3-docker-guard.md

@@ -0,0 +1,508 @@
+# PRD-3: Docker 镜像守卫
+
+## 0. 元数据
+
+| 字段 | 值 |
+|---|---|
+| PRD 编号 | PRD-3 |
+| 主笔 | prd-docker(autoteam-prd-0426 team) |
+| 起草日期 | 2026-04-26 |
+| 关联 Issue | issues1 #3(`list_accounts` ImportError) |
+| 关联调研 | `prompts/0426/research/issue-3-list-accounts-import.md` |
+| 关联代码修复 | commit `cf2f7d3 fix(round-3): exhausted 自愈 + workspace 指纹 + CPA 删除守卫 + 双 typo` |
+| 优先级 | P1(防回归 / 用户体验) |
+| 风险 | 低(纯外围加固,不动业务代码) |
+
+---
+
+## 1. 背景
+
+issues1 #3 报告:WebUI 点"生成免费号"返回 500,根因是 `api.py` 里 `from autoteam.accounts import list_accounts`(应为 `load_accounts`)的 typo。
+
+代码层 typo 已在 commit `cf2f7d3` 修复并落仓 — `grep -rn "from autoteam\.accounts import.*list_accounts" src` 完全干净。但用户在 11:04 仍看到同样报错,因为:
+
+1. **Dockerfile 第 23-25 行**用的是 `COPY src/ src/`,源代码在 `docker build` 时被烤进镜像
+2. **docker-compose.yml** 只挂 `./data:/app/data` 数据卷,**没有挂源代码 volume**
+3. 因此 `git pull` 拿到新代码后,**必须 rebuild 镜像才会生效** — 用户漏了这一步
+
+**真因 = 镜像未重建**,不是代码 bug。这一类"代码已修但部署没生效"的 confusion 大概率会复发,本 PRD 目的是把"镜像版本可观察 + 启动期自检 + 静态守卫 + SOP 文档"四道防线建好,让下次再有类似 typo 时:
+
+- CI 静态 lint 直接拦截 → typo 进不了主分支
+- 万一漏过,容器启动期 self-check 立即 crash-loop → 用户立刻知道是镜像版本问题
+- `/api/version` 端点曝露 git-sha → 用户/排错者能 1 秒确认"当前跑的是哪个 commit"
+- `docs/docker.md` 给出标准 rebuild SOP → 用户不再漏步骤
+
+---
+
+## 2. 目标
+
+| ID | 目标 |
+|---|---|
+| G1 | 容器启动期自检关键 import,失败立即 crash,**不要**让用户在 WebUI 按按钮才发现 |
+| G2 | 镜像内嵌 git-sha,通过 `echo $AUTOTEAM_GIT_SHA` / `/api/version` / `docker image inspect` 三种姿势可查 |
+| G3 | `pyflakes` / `ruff` 类静态检查接入 CI 与 pre-commit,堵住 typo 类 ImportError 在源头 |
+| G4 | `docs/docker.md` 增加"代码更新后如何 rebuild"的标准 SOP,语句直接可复制 |
+| G5 | `docker-compose.yml` 增加 `build.args.GIT_SHA`,让 `docker compose build` 一键注入版本 |
+
+---
+
+## 3. 非目标
+
+- ❌ **不**改 `src/autoteam/accounts.py` 加任何向后兼容别名(`list_accounts = load_accounts` 类掩盖性兜底)
+- ❌ **不**引入 hot reload / volume mount 源码方案 — 仍维持"镜像 = 不可变制品"语义
+- ❌ **不**做 docker 镜像签名 / SBOM / Trivy 扫描等供应链加固(超出本 issue 范围)
+- ❌ **不**改业务逻辑、不动 manager.py / api.py 核心路径
+- ❌ **不**搞自动化 CI/CD pipeline(本仓库目前无 GH Actions,只在本地 / pre-commit 落地 lint)
+
+---
+
+## 4. 用户故事
+
+### 故事 A:运维更新代码
+
+> 作为运维同学,当 upstream 推送新 commit 后,我能照 docs/docker.md 里 4 条命令完成 rebuild → 启动 → 验证,**不会**因为漏掉 `--no-cache` 或忘了 `docker compose down` 而仍跑旧版镜像。
+
+### 故事 B:故障排查"镜像版本"
+
+> 作为故障排查者,当用户报"我已经更新到最新版了但 bug 还在",我能在 30 秒内通过 `curl http://host:8787/api/version` 或 `docker compose exec autoteam env | grep AUTOTEAM_GIT_SHA` 拿到镜像的 git-sha,直接对比 `git log` 就能判定到底跑的是不是最新 commit。
+
+### 故事 C:开发期 typo 拦截
+
+> 作为开发者,当我把 `load_accounts` 写成 `list_accounts` 这样的 typo 时,**还没 commit** 的 pre-commit 钩子就拒绝我;就算我 `--no-verify` 强推,**容器启动期 self-check** 也立刻 crash 而不是潜伏到运行时。
+
+---
+
+## 5. 功能需求
+
+### 5.1 entrypoint self-check(启动期 import 关键符号自检)
+
+**目的**:把 ImportError 从"运行时偶发"提前到"启动期必现",触发 docker restart_policy crash-loop。
+
+**位置**:`docker-entrypoint.sh` 在最后 `exec uv run autoteam "$@"` 之前。
+
+**自检内容(白名单 import)**:
+
+```bash
+# Self-check: critical imports
+uv run python -c "
+from autoteam.api import app
+from autoteam.accounts import (
+    load_accounts, save_accounts,
+    STATUS_ACTIVE, STATUS_EXHAUSTED, STATUS_STANDBY,
+    STATUS_PERSONAL, STATUS_AUTH_INVALID, STATUS_ORPHAN,
+)
+from autoteam.manager import sync_account_states
+print('[self-check] OK')
+" || {
+    echo "[self-check] FATAL: critical import failed — image is likely stale or broken." >&2
+    echo "[self-check] Run: docker compose build --no-cache && docker compose up -d" >&2
+    exit 1
+}
+```
+
+**设计要点**:
+
+- 只检查"曾经被 typo 误伤"或"对外契约稳定"的核心符号 — 避免一改文件就要更新自检列表
+- 失败时打印**修复提示语**(rebuild 命令),省去用户 google 时间
+- 用 `uv run python -c` 而非 `python -c`,与项目 runtime 一致(避免依赖未装齐导致的伪阴性)
+- 自检整体 < 1 秒,**不阻塞**正常启动
+
+### 5.2 镜像 git-sha 标签 + /api/version 端点
+
+**5.2.1 Dockerfile 注入**
+
+```dockerfile
+# 在 WORKDIR /app 之后、COPY src/ 之前增加
+ARG GIT_SHA=unknown
+ARG BUILD_TIME=unknown
+LABEL org.opencontainers.image.revision=$GIT_SHA
+LABEL org.opencontainers.image.created=$BUILD_TIME
+ENV AUTOTEAM_GIT_SHA=$GIT_SHA
+ENV AUTOTEAM_BUILD_TIME=$BUILD_TIME
+```
+
+**5.2.2 /api/version 端点**
+
+在 `src/autoteam/api.py` 现有 `app = FastAPI(...)` 定义之后增加:
+
+```python
+import os
+
+@app.get("/api/version")
+def api_version() -> dict:
+    return {
+        "git_sha": os.getenv("AUTOTEAM_GIT_SHA", "unknown"),
+        "build_time": os.getenv("AUTOTEAM_BUILD_TIME", "unknown"),
+    }
+```
+
+**5.2.3 多种查询姿势**(都应能拿到同一个 git-sha):
+
+```bash
+# 容器外:HTTP 端点
+curl http://localhost:8787/api/version
+
+# 容器内:环境变量
+docker compose exec autoteam env | grep AUTOTEAM_GIT_SHA
+
+# 镜像层:OCI label
+docker image inspect autoteam-autoteam | grep revision
+```
+
+### 5.3 lint 守卫(防止 list_accounts 这类 typo 再次发生)
+
+**工具选型**:`ruff check --select F401,F811,F821`
+
+| Rule | 含义 |
+|---|---|
+| F401 | imported but unused — 抓"import 了但没用"的死 import |
+| F811 | redefinition of unused — 抓重复定义 |
+| F821 | undefined name — **核心**,抓 `from autoteam.accounts import list_accounts`(未定义名)这种典型 typo |
+
+**为什么选 ruff 而非 pyflakes/mypy**:
+
+- ruff 单一二进制,启动 < 100ms,本地循环不痛
+- 已是 Python 生态主流(本仓 pyproject.toml 可顺便接 ruff format)
+- mypy 太重(类型完整推断要 5-10s),pre-commit 卡顿;ruff F821 已能覆盖 ImportError 这条主线
+
+**落地点(三层防线)**:
+
+1. **pyproject.toml** 加 `[tool.ruff.lint]` 段配置:
+   ```toml
+   [tool.ruff.lint]
+   select = ["F401", "F811", "F821"]
+   exclude = ["tests/", "docs/", "scripts/"]
+   ```
+2. **pre-commit hook**(`.pre-commit-config.yaml`):
+   ```yaml
+   repos:
+     - repo: https://github.com/astral-sh/ruff-pre-commit
+       rev: v0.7.0
+       hooks:
+         - id: ruff
+           args: [--select, "F401,F811,F821"]
+   ```
+3. **docs/docker.md / docs/getting-started.md** 增加"开发前先 `pip install pre-commit && pre-commit install`"提示
+
+### 5.4 docs/docker.md 增加 rebuild SOP
+
+在 `docs/docker.md` 末尾新增章节:
+
+```markdown
+## 代码更新后的 rebuild SOP
+
+> 关键认知:本项目 Dockerfile 用 `COPY src/`(非 volume mount),
+> **`git pull` 后必须 rebuild 镜像**,代码改动才会进入容器。
+
+### 标准更新流程(4 步)
+
+```bash
+# 1. 拉新代码
+cd /path/to/AutoTeam && git pull
+
+# 2. 停旧容器
+docker compose down
+
+# 3. 重建镜像(--no-cache 防意外缓存命中,GIT_SHA 注入版本指纹)
+docker compose build --no-cache --build-arg GIT_SHA=$(git rev-parse --short HEAD) --build-arg BUILD_TIME=$(date -u +%FT%TZ)
+
+# 4. 启动
+docker compose up -d
+```
+
+### 验证镜像版本
+
+```bash
+# 方式 A:HTTP 端点
+curl http://localhost:8787/api/version
+# 期望:{"git_sha":"cf2f7d3","build_time":"2026-04-26T..."}
+
+# 方式 B:进容器查环境变量
+docker compose exec autoteam env | grep AUTOTEAM_GIT_SHA
+
+# 方式 C:看镜像 OCI label
+docker image inspect autoteam-autoteam --format '{{.Config.Labels}}'
+```
+
+### 故障排查:为什么修了代码,bug 还在?
+
+99% 是镜像没 rebuild。先跑这条:
+
+```bash
+curl -s http://localhost:8787/api/version | python -c "import sys,json; d=json.load(sys.stdin); print('image sha:', d['git_sha']); print('repo head:', open('.git/HEAD').read())"
+```
+
+如果 `image sha` 与最新 commit 不一致 → 重做上面 4 步 SOP。
+```
+
+### 5.5 docker-compose.yml 增加 build args
+
+修改 `docker-compose.yml`:
+
+```yaml
+services:
+  autoteam:
+    build:
+      context: .
+      args:
+        GIT_SHA: ${GIT_SHA:-unknown}
+        BUILD_TIME: ${BUILD_TIME:-unknown}
+    ports:
+      - "8787:8787"
+    volumes:
+      - ./data:/app/data
+    restart: unless-stopped
+```
+
+配套 `Makefile` 或 docs 提供一键命令:
+
+```bash
+GIT_SHA=$(git rev-parse --short HEAD) BUILD_TIME=$(date -u +%FT%TZ) docker compose build --no-cache
+```
+
+---
+
+## 6. 非功能需求
+
+| 维度 | 要求 |
+|---|---|
+| 启动延迟 | self-check 增加 < 1 秒 |
+| 镜像体积 | 增量 < 5KB(只是增加 LABEL/ENV/几行 entrypoint) |
+| 兼容性 | 不破坏 `docker compose up` 老用户体验 — 不传 `GIT_SHA` 时降级为 `unknown` 而非报错 |
+| 可观察性 | git-sha 三种姿势可查(端点 + 环境变量 + label),互为冗余 |
+| 安全性 | `/api/version` 只暴露 git-sha 与构建时间,**不**暴露任何 secret / 路径 / 主机名 |
+| 可回滚 | 所有改动可独立回退(删 entrypoint 那段、删 lint 配置、删 /api/version 端点) |
+
+---
+
+## 7. 技术方案
+
+### 7.1 entrypoint 自检脚本设计(bash + uv run python -c)
+
+**为什么用 `uv run python -c` 而不是单独脚本**:
+
+- 项目 runtime 用 uv 管理虚拟环境,自检必须走同一环境(否则可能用了系统 python 装的旧包,假阳性)
+- 单行 inline `-c` 比额外 `scripts/self_check.py` 更易维护(和 entrypoint 同位置,不会失同步)
+
+**为什么白名单粒度到符号常量**:
+
+- 只检查 `from autoteam.api import app` 不够 — `app` 这种顶层对象 import 失败概率低,而 `STATUS_*` 常量、`load_accounts` 函数才是 typo 高发区
+- 检查 `from autoteam.manager import sync_account_states` 顺带覆盖 manager → accounts 的链路
+
+**失败行为**:
+
+- `set -e` 配合 `||{ ...; exit 1; }` → bash 立即非零退出
+- docker `restart: unless-stopped` 会触发 crash-loop,容器列表里看到 `Restarting (1)` → 立刻 `docker compose logs` 就能看到自检报错全文
+
+### 7.2 镜像构建注入 GIT_SHA(--build-arg)
+
+**3 处声明,一处真正接收**:
+
+1. `docker-compose.yml`:`build.args.GIT_SHA: ${GIT_SHA:-unknown}` — 接受 shell 环境变量
+2. `Dockerfile`:`ARG GIT_SHA=unknown` — 镜像构建期参数
+3. `Dockerfile`:`ENV AUTOTEAM_GIT_SHA=$GIT_SHA` — 持久化到镜像运行环境
+4. `Dockerfile`:`LABEL org.opencontainers.image.revision=$GIT_SHA` — OCI 标准 label,`docker image inspect` 可查
+
+**降级语义**:
+
+- 用户没传 `GIT_SHA`(直接 `docker compose build`)→ 默认值 `unknown`,**不报错**
+- `/api/version` 返回 `{"git_sha": "unknown", ...}` → 提示用户"本镜像未注入版本"
+- 这是渐进改进,不强制所有人都用,**老的 build 命令仍能工作**
+
+### 7.3 lint 工具选型(ruff)
+
+**对比表**:
+
+| 工具 | F821 检测 | 启动延迟 | 配置成本 | 选用 |
+|---|---|---|---|---|
+| **ruff** | ✅ 内建 | < 100ms | 单文件 toml | ✅ |
+| pyflakes | ✅ 内建 | ~500ms | 无配置 | ❌(被 ruff 包含) |
+| mypy | ✅ 完整类型 | 5-10s | 复杂 | ❌(太重) |
+| pylint | ✅ | 3-5s | 复杂 | ❌(太重) |
+
+**只启 F401/F811/F821 三条规则的理由**:
+
+- 这三条是"必然 bug"(死 import / 重复定义 / 未定义名),零误报
+- 不开启 style 类规则 → 不打扰现有代码风格
+- 后续可逐步追加 E/W/B 等,但本 PRD 不扩张
+
+### 7.4 文档结构变更
+
+- `docs/docker.md`:**追加**章节"代码更新后的 rebuild SOP"+"故障排查"
+- `docs/getting-started.md`:**追加**一行 pre-commit 安装提示(可选)
+- `docs/troubleshooting.md`:**追加**章节"镜像版本不一致 / 修了代码 bug 还在"
+- `pyproject.toml`:**追加** `[tool.ruff.lint]` 段
+- `.pre-commit-config.yaml`:**新建**(如不存在)
+
+---
+
+## 8. 验收标准
+
+| ID | 验收点 | 检验方式 |
+|---|---|---|
+| AC1 | self-check 在镜像内能跑通 | `docker compose exec autoteam bash docker-entrypoint.sh --noop` 无报错 |
+| AC2 | self-check 能拦截 typo | 临时把 `accounts.py` 里 `load_accounts` 改名 → rebuild → 启动应 crash-loop |
+| AC3 | /api/version 返回正确字段 | `curl /api/version` 返回 `{git_sha, build_time}` 两字段且非空 |
+| AC4 | git-sha 三处一致 | env / curl / label 三种方式查到的 sha 字符串完全相同 |
+| AC5 | ruff F821 拦截 typo | 写一行 `from autoteam.accounts import list_accounts`,`ruff check src/` 应非零退出 |
+| AC6 | pre-commit 触发 | `git commit` 含上述 typo 时被 pre-commit 拒绝 |
+| AC7 | docs/docker.md SOP 可复制粘贴跑通 | 新人照文档 4 步操作,可成功 rebuild + 验证 |
+| AC8 | 不传 GIT_SHA 不报错 | `docker compose build`(无 --build-arg)仍能成功,`/api/version` 返回 `unknown` |
+
+---
+
+## 9. 测试计划
+
+### 9.1 本地 docker 端到端
+
+```bash
+# 步骤 1:基础 rebuild + 启动
+cd D:/Desktop/AutoTeam
+docker compose down
+GIT_SHA=$(git rev-parse --short HEAD) BUILD_TIME=$(date -u +%FT%TZ) docker compose build --no-cache
+docker compose up -d
+
+# 步骤 2:验证 self-check 通过
+docker compose logs autoteam | grep "[self-check] OK"
+
+# 步骤 3:验证 /api/version
+curl http://localhost:8787/api/version
+# 期望:{"git_sha":"cf2f7d3","build_time":"2026-04-26T..."}
+
+# 步骤 4:验证 env / label
+docker compose exec autoteam env | grep AUTOTEAM_GIT_SHA
+docker image inspect autoteam-autoteam | grep revision
+```
+
+### 9.2 self-check 故障注入
+
+```bash
+# 步骤 1:临时损坏 accounts.py
+sed -i.bak 's/^def load_accounts/def loadaccounts/' src/autoteam/accounts.py
+
+# 步骤 2:rebuild + 启动 → 应 crash-loop
+docker compose build --no-cache
+docker compose up -d
+sleep 3
+docker compose ps  # 期望:autoteam 状态 Restarting
+docker compose logs autoteam | grep "FATAL"
+
+# 步骤 3:恢复
+mv src/autoteam/accounts.py.bak src/autoteam/accounts.py
+docker compose build --no-cache && docker compose up -d
+```
+
+### 9.3 lint 守卫验证
+
+```bash
+# 步骤 1:制造 typo
+echo "from autoteam.accounts import list_accounts" >> src/autoteam/_lint_canary.py
+
+# 步骤 2:期望 ruff 拦截
+ruff check src/ --select F401,F811,F821
+# 期望:F821 Undefined name `list_accounts`,exit code 非零
+
+# 步骤 3:期望 pre-commit 拦截
+git add src/autoteam/_lint_canary.py
+git commit -m "test"  # 期望被拒
+
+# 步骤 4:清理
+rm src/autoteam/_lint_canary.py
+```
+
+### 9.4 回归测试
+
+- 现有 `tests/unit/`、`tests/integration/` 全套跑通
+- WebUI 手测:进 setup wizard、点"生成免费号"、删除账号 — 三条主路径都不应受影响
+
+---
+
+## 10. 灰度 / 回滚
+
+### 灰度策略
+
+本 PRD 改动均为**外围加固**,不影响业务路径,无需金丝雀:
+
+- 直接 merge 到 main → 用户 `git pull && docker compose build --no-cache` 即可生效
+- 用户如未传 `GIT_SHA`,`/api/version` 返回 `unknown`,**功能不受影响**
+
+### 回滚预案
+
+| 风险点 | 回滚动作 |
+|---|---|
+| self-check 误拦截(白名单太严) | 删 `docker-entrypoint.sh` 末尾自检段,rebuild 即可 |
+| ruff F821 误报 | `pyproject.toml` 临时关 F821:`select = ["F401","F811"]` |
+| `/api/version` 引入异常 | 删 api.py 的 4 行端点定义即可 |
+| docker-compose 用户 GIT_SHA 变量解析失败 | 移除 build.args 段,降级回原版 compose |
+
+每一处改动都是**独立可回滚**单元。
+
+---
+
+## 11. 文档影响清单
+
+| 文档 | 类型 | 变更内容 |
+|---|---|---|
+| `docs/docker.md` | 修改 | 追加"rebuild SOP"+"版本验证"+"故障排查"三章节 |
+| `docs/getting-started.md` | 修改 | 追加 pre-commit 安装一行 |
+| `docs/troubleshooting.md` | 修改 | 追加"镜像版本不一致"故障案例 |
+| `docs/api.md` | 修改 | 追加 `/api/version` 端点说明 |
+| `pyproject.toml` | 修改 | 新增 `[tool.ruff.lint]` 段 |
+| `Dockerfile` | 修改 | 新增 ARG/LABEL/ENV |
+| `docker-compose.yml` | 修改 | `build` 段从字符串扩为对象,新增 `args` |
+| `docker-entrypoint.sh` | 修改 | 末尾追加 self-check 段 |
+| `src/autoteam/api.py` | 修改 | 新增 `/api/version` 路由 |
+| `.pre-commit-config.yaml` | 新建 | ruff hook |
+| `CHANGELOG.md` | 修改 | 添加本 PRD 落地记录 |
+
+---
+
+## 12. 风险
+
+| 风险 | 概率 | 影响 | 缓解 |
+|---|---|---|---|
+| self-check 白名单失同步(代码改了符号名,没改自检列表) | 中 | 容器启动失败 | 自检列表只列"长期稳定"符号(STATUS_*、load_accounts、save_accounts 等);任何 PR 改这些符号需同步改自检 |
+| ruff F821 在动态 import 场景误报 | 低 | 开发体验下降 | F821 默认对动态 import 友好;真出现误报可加 `# noqa: F821` 单行豁免 |
+| 用户老镜像没有 self-check,但用了新版 docker-compose.yml | 低 | 不报错,只是缺保护 | 不影响功能,docs SOP 引导用户先 rebuild 再使用 |
+| `/api/version` 被滥用作健康探针 | 低 | 偶尔多打几个请求 | 端点本身无副作用,被频繁调用也无成本;真要做 healthcheck 应建议另开 `/api/healthz` |
+| pre-commit 安装心智门槛 | 中 | 部分开发不装,守卫只剩本地 ruff | 至少 docs 写明,且 ruff 单独可运行(`ruff check src/`),不强依赖 pre-commit |
+
+---
+
+## 13. 未决问题
+
+| ID | 问题 | 决策路径 |
+|---|---|---|
+| Q1 | self-check 是否要把所有 mail provider 类也 import?(`from autoteam.mail.maillab import MaillabClient` 等) | 暂**不**加,理由:provider 是可拔插模块,缺失不应 fatal;留待 PRD-1 mail provider 重构后再评估 |
+| Q2 | 是否同时上 `docker compose --profile dev` 用于开发期 hot reload? | 暂**不**做,与本 PRD"镜像不可变"语义冲突,留待单独 RFC |
+| Q3 | `/api/version` 是否需要鉴权? | **不**需要 — 只暴露 git-sha 不暴露 secret;且未鉴权能让运维无门槛排错 |
+| Q4 | 是否要把 self-check 抽到独立脚本 `scripts/self_check.py` 便于 CI 直接调用? | **可选优化**,本 PRD 落地 inline 版本,后续若 CI 需要可重构 |
+| Q5 | ruff 版本固定到 v0.7.x 还是跟 latest? | pre-commit 配置固定到 `v0.7.0`,pyproject.toml 不约束 — 让本地开发能用 latest,守卫线统一 |
+
+---
+
+## 14. Story Map
+
+```
+[运维更新代码]                        [开发提交 typo]                    [排错者诊断"代码改了 bug 还在"]
+    │                                     │                                     │
+    ├─ [git pull]                        ├─ [写代码]                          ├─ [curl /api/version]
+    │                                     │                                     │
+    ├─ [docker compose down]              ├─ [git commit]                      ├─ [对比 git log HEAD]
+    │                                     │   │                                 │
+    ├─ [docker compose build              │   ├─ [pre-commit ruff F821]        ├─ [发现 sha 不一致]
+    │     --no-cache                      │   │       └─ ⛔ 拦截               │
+    │     --build-arg GIT_SHA=...]        │   │                                 │
+    │                                     │   └─ ✅ 通过 → push                ├─ [告诉用户:rebuild!]
+    ├─ [docker compose up -d]             │                                     │
+    │                                     ├─ [docker build]                    └─ [按 SOP 重做]
+    ├─ [curl /api/version 验证版本]       │   └─ [self-check 启动期再守一道]
+    │                                     │
+    └─ ✅ 完成                            └─ ✅ 部署成功
+                                              [若漏过] → ⛔ crash-loop + 报错日志
+```
+
+四道防线层层递进:**lint(开发期) → self-check(启动期) → /api/version(运行期) → docs SOP(操作期)**。
+任何一道未拦截 typo 类问题,下一道兜底。
+
+---

prompts/0426/prd/prd-4-playwright-hardening.md

@@ -0,0 +1,329 @@
+# PRD-4: Playwright async/sync 一致性硬化(hardening only)
+
+## 0. 元数据
+
+| 字段 | 值 |
+|---|---|
+| PRD 编号 | PRD-4 |
+| 主题 | Playwright async/sync 一致性硬化(防御性) |
+| 关联 Issue | #5(待用户补样本) |
+| 来源研究 | `prompts/0426/research/issue-5-playwright-async-sync.md` |
+| 优先级 | P2(低,纯防御,不阻塞 P0/P1) |
+| 主笔 | prd-playwright |
+| 创建日期 | 2026-04-26 |
+| 状态 | DRAFT |
+
+---
+
+## 1. 背景
+
+用户在 Issue#5 报告"playwright 中大量 async 函数里误用 sync API"。研究阶段对全项目 5 处 `from playwright.sync_api import sync_playwright` 调用点 + 1 处 `async def`(`api.py:35 auth_middleware`,与 playwright 无关) 完整审计后**结论反转**:
+
+- **0** 处 `async_playwright` 引用
+- **0** 处 `asyncio` import / `async with` / `loop.run_until_complete`
+- **5** 处 `sync_playwright` 调用全部位于 sync `def` 上下文,且经由 `api.py:155-229 _PlaywrightExecutor` 单例 + 专用 worker 线程串行,严格符合 Playwright 官方 "sync API + 单线程" 推荐模式
+- 用户极可能将 `page.evaluate("""async () => {...}""")` 内的 JS 字符串误读为 Python 协程
+
+**用户决策(2026-04-26)**:走 "hardening only" — 不修业务逻辑、不重构现有调用,只新增防御性代码,以**永久杜绝未来回归**。
+
+## 2. 目标
+
+| # | 目标 | 衡量 |
+|---|---|---|
+| G1 | 全项目 playwright 导入收敛到一处规范的 sync API 白名单 | grep 命中数与白名单一致 |
+| G2 | 即使未来误把 `sync_playwright` 植入 `async def`,也能在第一次执行时立即抛错(而非触发 Playwright 内部隐式失败) | guard 单测通过 |
+| G3 | CI 阶段静态拒绝 `async def` 函数体内出现 playwright 名称、拒绝 `from playwright.async_api ...` | pytest collect 包含 `tests/static/test_no_async_playwright.py` 且通过 |
+| G4 | 提供清晰的 opt-out 出口,未来如确需引入 async_playwright 不被守卫卡死 | 风险登记册中明示 opt-out 路径 |
+
+## 3. 非目标(明确不做)
+
+- **不**重构 `_PlaywrightExecutor` / `chatgpt_api.py` / `codex_auth.py` / `invite.py` / `manager.py` 的任何业务逻辑
+- **不**切换到 `async_playwright`(即便未来 FastAPI 改用 async 路由)
+- **不**修改 5 处 `sync_playwright` 调用点的语义(本 PRD 仅做 import 路径重写)
+- **不**引入新依赖(纯标准库 `ast` + `asyncio`)
+- **不**把守卫扩展到 JS 端 `page.evaluate("async () => ...")` 字符串(那是合法 JS,与 Python async 无关)
+
+## 4. 用户故事
+
+### 4.1 运维(operator)
+
+> 作为运维,我希望服务上线后**永远不会**因为某次重构把 `sync_playwright` 误植入 asyncio loop 而无人察觉地"挂机 30s 后报错",我希望第一次错误调用就立即崩溃并打印出清晰的中文错误堆栈,这样我能在生产前的 smoke 中就发现回归。
+
+### 4.2 开发者(contributor)
+
+> 作为新加入的开发者,我希望仅看一眼 import 列表就能确定本仓库**只用 sync API**;我也希望提交 PR 时 CI 能在任何不慎引入 `async_playwright` 或 async-def 内调用 sync API 的代码时立即 fail,而不是在我提了 PR 评审之后才被 reviewer 抓出来。
+
+## 5. 功能需求
+
+### 5.1 顶层 import 统一规范(FR-1)
+
+**规范**:
+
+- 仅允许从 `playwright.sync_api` 导入,白名单:`sync_playwright`, `Page`, `Browser`, `BrowserContext`, `BrowserType`, `Locator`, `Error`, `TimeoutError`, `Playwright`(共 9 个,覆盖现有用法 + 后续可能增量)
+- 全部 import 必须在**模块顶层**,不允许函数内 import(对照研究 §B.1 — `manager.py:1491/1969` 现有函数内 import 必须上提)
+- 任何文件出现 `from playwright.async_api import ...` 即 CI fail
+
+**实施动作**:
+
+1. 把 `manager.py` 函数内的两处 `from playwright.sync_api import sync_playwright` 移到模块顶层(若引发循环 import,请改为 `if TYPE_CHECKING:` + 函数内调用本地导入,但**该决定必须在 PR 描述里说明原因**)
+2. 编写 `tests/static/test_playwright_imports.py` 校验白名单
+
+### 5.2 `_PlaywrightExecutor` 运行时 guard(FR-2)
+
+**规范**:
+
+在 `api.py:_PlaywrightExecutor.run_with_timeout` 入口(以及 `_worker` 线程入口) **额外**插入一段 guard:
+
+```python
+import asyncio
+def _assert_no_running_loop():
+    try:
+        loop = asyncio.get_running_loop()
+    except RuntimeError:
+        return  # 期望路径:无 loop
+    raise RuntimeError(
+        "[PlaywrightGuard] 检测到 sync_playwright 被调度进 asyncio loop;"
+        "本项目仅支持 sync API + 专用线程模型。"
+        "若确需 async 调用,请走 PRD-4 §12 opt-out 流程。"
+    )
+```
+
+- `run_with_timeout` 入口断言一次(主线程入队前)
+- `_worker` 启动时再断言一次(worker 线程是新线程,正常情况下应无 loop)
+- 失败立即 raise,不要 swallow
+
+### 5.3 AST 静态守卫单测(FR-3)
+
+**规范**:
+
+新建 `tests/static/test_no_async_playwright.py`,使用 `ast` 标准库扫 `src/autoteam/**/*.py`,断言:
+
+| 断言 | 说明 |
+|---|---|
+| A1 | 任何 `from playwright.async_api import ...` 直接 fail |
+| A2 | 任何 `import playwright.async_api` 直接 fail |
+| A3 | 任何 `async def` 函数体内不出现 `sync_playwright` / `async_playwright` 名称、`Playwright`、`Browser`、`Page`、`BrowserContext` 等 9 个白名单符号(用变量遮蔽视为可疑) |
+| A4 | 顶层 `from playwright.sync_api import X, Y, ...` 中 X/Y 必须在白名单内 |
+
+**例外**:`tests/` 目录本身允许 async 测试(pytest-asyncio),但仍**不允许**在 async 测试体内调用 playwright(若未来需要,可在测试代码中单点豁免并加注释)
+
+### 5.4 CI 集成(FR-4)
+
+- 把 `tests/static/test_no_async_playwright.py` + `tests/static/test_playwright_imports.py` 加入 `pyproject.toml` / `pytest.ini` 默认 collect 路径
+- 不允许默认 deselect / skip
+- 在 PR 模板里加一行勾选项:"已确认未引入 async playwright 调用"
+
+## 6. 非功能需求
+
+| 维度 | 要求 |
+|---|---|
+| 性能 | guard 在 `run_with_timeout` 入口的开销 ≤ 50µs(`asyncio.get_running_loop()` 单次调用) |
+| 兼容性 | 必须在 Python 3.10+ 工作(项目当前最低版本) |
+| 可维护性 | guard 实现集中在一个文件 `src/autoteam/_playwright_guard.py`,5 处调用点零侵入 |
+| 可观测性 | guard 失败时打印当前线程名 + asyncio loop id,便于诊断 |
+| 文档影响 | 仅 `CONTRIBUTING.md`(若不存在则不写)增加 5 行说明 |
+
+## 7. 技术方案
+
+### 7.1 import 规范定义
+
+新建 `src/autoteam/_playwright_guard.py`:
+
+```python
+"""Playwright import 守卫与白名单(PRD-4)"""
+
+ALLOWED_SYNC_NAMES = {
+    "sync_playwright", "Page", "Browser", "BrowserContext",
+    "BrowserType", "Locator", "Error", "TimeoutError", "Playwright",
+}
+FORBIDDEN_MODULES = {"playwright.async_api"}
+```
+
+`tests/static/test_playwright_imports.py` 直接 import 该常量做断言,实现单一信源。
+
+### 7.2 guard 实现细节
+
+```python
+# src/autoteam/_playwright_guard.py
+import asyncio
+import threading
+
+def assert_sync_context() -> None:
+    """在调用 sync_playwright 之前确认无 asyncio loop;否则抛 RuntimeError"""
+    try:
+        loop = asyncio.get_running_loop()
+    except RuntimeError:
+        return
+    raise RuntimeError(
+        f"[PlaywrightGuard] thread={threading.current_thread().name} "
+        f"loop_id={id(loop)} — sync_playwright 不允许在 asyncio loop 中调用。"
+        f"opt-out: 见 PRD-4 §12。"
+    )
+```
+
+`api.py` 调用点:
+
+```python
+# 入队前
+class _PlaywrightExecutor:
+    def run_with_timeout(self, timeout, func, *args, **kwargs):
+        from autoteam._playwright_guard import assert_sync_context
+        assert_sync_context()
+        ...
+    def _worker(self):
+        from autoteam._playwright_guard import assert_sync_context
+        assert_sync_context()
+        ...
+```
+
+### 7.3 AST 测试实现示例(可运行,30+ 行)
+
+```python
+# tests/static/test_no_async_playwright.py
+"""PRD-4 FR-3:静态守卫,禁止 async_playwright + 禁止 async def 内部 playwright 调用"""
+import ast
+from pathlib import Path
+
+import pytest
+
+SRC_ROOT = Path(__file__).resolve().parents[2] / "src" / "autoteam"
+ALLOWED_SYNC_NAMES = {
+    "sync_playwright", "Page", "Browser", "BrowserContext",
+    "BrowserType", "Locator", "Error", "TimeoutError", "Playwright",
+}
+FORBIDDEN_MODULES = {"playwright.async_api"}
+PLAYWRIGHT_NAMESPACE = ALLOWED_SYNC_NAMES | {"async_playwright"}
+
+
+def _iter_py_files():
+    yield from SRC_ROOT.rglob("*.py")
+
+
+def _collect_async_func_bodies(tree: ast.AST):
+    for node in ast.walk(tree):
+        if isinstance(node, ast.AsyncFunctionDef):
+            for child in ast.walk(node):
+                yield node, child
+
+
+def test_no_forbidden_module_import():
+    bad = []
+    for path in _iter_py_files():
+        tree = ast.parse(path.read_text(encoding="utf-8"))
+        for node in ast.walk(tree):
+            if isinstance(node, ast.ImportFrom) and node.module in FORBIDDEN_MODULES:
+                bad.append(f"{path}:{node.lineno} from {node.module}")
+            if isinstance(node, ast.Import):
+                for alias in node.names:
+                    if alias.name in FORBIDDEN_MODULES:
+                        bad.append(f"{path}:{node.lineno} import {alias.name}")
+    assert not bad, "禁止使用 playwright.async_api:\n" + "\n".join(bad)
+
+
+def test_no_playwright_in_async_def():
+    bad = []
+    for path in _iter_py_files():
+        tree = ast.parse(path.read_text(encoding="utf-8"))
+        for fn, child in _collect_async_func_bodies(tree):
+            name = getattr(child, "id", None) or getattr(child, "attr", None)
+            if name in PLAYWRIGHT_NAMESPACE:
+                bad.append(f"{path}:{child.lineno} async def {fn.name} 内引用了 {name}")
+    assert not bad, "async def 函数体内不允许出现 playwright 符号:\n" + "\n".join(bad)
+
+
+def test_sync_import_whitelist():
+    bad = []
+    for path in _iter_py_files():
+        tree = ast.parse(path.read_text(encoding="utf-8"))
+        for node in ast.walk(tree):
+            if isinstance(node, ast.ImportFrom) and node.module == "playwright.sync_api":
+                for alias in node.names:
+                    if alias.name not in ALLOWED_SYNC_NAMES:
+                        bad.append(f"{path}:{node.lineno} 未在白名单的符号 {alias.name}")
+    assert not bad, "playwright.sync_api 导入不在白名单:\n" + "\n".join(bad)
+```
+
+## 8. 验收标准
+
+| AC# | 描述 | 验证方式 |
+|---|---|---|
+| AC1 | `pytest tests/static/` 全绿 | CI |
+| AC2 | 在 `chatgpt_api.py` 临时插入 `async def evil(): sync_playwright()` 应使 AC1 失败 | 人工注入 + 还原 |
+| AC3 | 在 `auth_middleware` 内手工调一次 `_PlaywrightExecutor().run_with_timeout(...)` 应抛 `[PlaywrightGuard]` | 人工注入 + 还原 |
+| AC4 | `manager.py` 的 2 处函数内 import 已上提 | grep `from playwright` 在 manager.py 仅模块顶层 1 处 |
+| AC5 | `pyproject.toml` / `pytest.ini` 包含 `tests/static/` | diff 校验 |
+
+## 9. 测试计划
+
+| 测试 | 类型 | 触发 |
+|---|---|---|
+| `test_no_async_playwright.py::test_no_forbidden_module_import` | 静态 | pytest |
+| `test_no_async_playwright.py::test_no_playwright_in_async_def` | 静态 | pytest |
+| `test_no_async_playwright.py::test_sync_import_whitelist` | 静态 | pytest |
+| `test_playwright_guard.py::test_runtime_guard_blocks_in_loop` | 运行时(asyncio) | pytest-asyncio |
+| `test_playwright_guard.py::test_runtime_guard_passes_in_thread` | 运行时(threading) | pytest |
+| 既有 invite/register/sync 集成测试 | 回归 | 整套 pytest |
+
+回归预期:**全部既有测试应保持绿色**(本 PRD 不动业务逻辑)。
+
+## 10. 灰度 / 回滚
+
+- **灰度**:不需要(纯防御代码,无运行时分支切换)
+- **回滚**:删除 `tests/static/` + 移除 `assert_sync_context` 调用即可,无数据迁移
+- **影响范围**:0(运行路径无 loop,guard 永不触发;静态测试不进生产)
+
+## 11. 文档影响清单
+
+- `CONTRIBUTING.md`(若已存在):新增"Playwright 使用守则"小节,5 行
+- 不修改 `docs/`、`README.md`、`AGENTS.md`(本 PRD 是开发期硬化,不面向终端用户)
+
+## 12. 风险登记册
+
+| # | 风险 | 等级 | 缓解措施 |
+|---|---|---|---|
+| R1 | guard 误伤合法 async 调用(未来确需 async_playwright 接并发抓取) | 中 | **opt-out 流程**:在新模块内显式 `from playwright.async_api import async_playwright as _async_playwright_optout`,并在该文件顶部加注释 `# PRD-4 OPT-OUT: <reason>`;同时在 `test_no_async_playwright.py` 的 FORBIDDEN_MODULES 检查中加 per-file 豁免列表(显式 allowlist,需 PR 评审通过) |
+| R2 | `manager.py` 函数内 import 上提引发循环 import | 低 | 实施前用 `python -c "import autoteam.manager"` 验证;若爆掉则保留函数内 import 并在静态测试中加 per-file 豁免 |
+| R3 | AST 静态测试在 Windows 上路径处理出错 | 低 | 用 `Path.rglob` + `read_text(encoding="utf-8")`,已处理 |
+| R4 | guard 单测引入 `pytest-asyncio` 新依赖 | 低 | 已在 dev 依赖中(若没有则添加 `pytest-asyncio>=0.23` 到 `pyproject.toml [project.optional-dependencies].dev`) |
+| R5 | 用户描述的"async/sync 混用"实际是其它问题(如 anyio 内部错误) | 中 | 本 PRD 不解决该问题,只防回归;Issue#5 保持 open 等用户补样本 |
+
+## 13. 未决问题
+
+1. **Q1**:是否需要把 guard 扩展到所有 `_PlaywrightExecutor` 之外的直接 `sync_playwright()` 调用点(`codex_auth.py:271`、`invite.py:552`、`manager.py:1496/1976`)?
+   - 当前提案:**仅在 `_PlaywrightExecutor` 入口加**,因为这 4 处调用点最终都是经由 executor 调度;若未来某调用点绕过 executor 直接调,应在评审阶段拒绝
+   - 备选:每个 `with sync_playwright()` 前加 `assert_sync_context()`(代码侵入度更高)
+2. **Q2**:`CONTRIBUTING.md` 不存在时是否新建?(用户偏好"优先编辑现有文件" — 倾向不新建)
+3. **Q3**:R1 的 opt-out 豁免列表落在哪个文件?(候选:`pyproject.toml [tool.autoteam.playwright_guard].async_optout_files`)
+
+## 14. Story Map
+
+```
+Sprint 0(本 PRD)
+├── Story 1: 新建 _playwright_guard.py(白名单常量 + assert_sync_context)
+├── Story 2: 在 _PlaywrightExecutor 双入口插入 guard
+├── Story 3: 上提 manager.py 两处函数内 import(若不引发循环 import)
+├── Story 4: 编写 tests/static/test_no_async_playwright.py
+├── Story 5: 编写 tests/static/test_playwright_imports.py
+├── Story 6: 编写 tests/unit/test_playwright_guard.py(asyncio loop 内/外)
+├── Story 7: 把 tests/static/ 加入 pytest.ini collect 路径
+└── Story 8: 跑全套 pytest,确认无回归
+
+实施时间预估:0.5 人日
+回归测试:已有套件 + 新增 5 个测试,2 小时
+评审重点:R1 的 opt-out 设计是否清晰
+```
+
+---
+
+**附:与研究文档(issue-5-playwright-async-sync.md)的对应关系**
+
+| 研究章节 | 本 PRD 章节 |
+|---|---|
+| §A 官方 API 边界 | §1 背景 |
+| §B 全项目使用现状 | §1 背景 + §5.1 |
+| §C 误用清单(0 处) | §1 + §3 |
+| §D.2.1 顶层 import | §5.1 + §7.1 |
+| §D.2.3 runtime guard | §5.2 + §7.2 |
+| §D.3.1 AST 静态测试 | §5.3 + §7.3 |
+| §D.3.2 runtime guard 测试 | §9 |
+| §E.3 用户描述差距 | §1 + R5 |

prompts/0426/research/issue-1-cloudmail.md

@@ -0,0 +1,613 @@
+# Issue#1 CloudMail 全量集成 — 研究报告
+
+> 范围:把"CloudMail"(实际指 `maillab/cloud-mail`,品牌名 `skymail.ink`)的全量 API 接入 AutoTeam,在前端
+> 加邮箱归属验证,修复 setup_wizard 的 401 半成功 bug,并梳理文档影响面。
+>
+> 调研时间:2026-04-26
+> 关键证据:
+> - `https://doc.skymail.ink` 顶部 logo 链与 GitHub Releases 链直指 `https://github.com/maillab/cloud-mail`,
+>   "在线演示"地址即 `https://skymail.ink` → **skymail.ink = maillab/cloud-mail 的官方部署/对外品牌**。
+> - `mail-worker/src/security/security.js` 白名单 = `['/login', '/register', '/oss',
+>   '/setting/websiteConfig', '/webhooks', '/init', '/public/genToken', '/telegram', '/test', '/oauth']`
+> - `mail-worker/src/api/*-api.js` 实际暴露 60+ 路由,`doc.skymail.ink/api/api-doc.html` 只挑了 3 个
+>   "对外集成"用的子集(`/public/genToken / emailList / addUser`)写文档。
+
+---
+
+## A. 现状盘点
+
+### A.1 cloudmail.py 当前接口表
+
+`src/autoteam/cloudmail.py` 现在只是 **10 行 stub**(2026-04 重构后改为 re-export):
+
+```python
+from autoteam.mail import CloudMailClient  # noqa: F401  re-export
+```
+
+实际实现拆到了 `src/autoteam/mail/` 子包,工厂 `get_mail_client()` 按 `MAIL_PROVIDER` 环境变量分发到具体后端。
+
+**`src/autoteam/mail/` 当前目录结构**:
+
+| 文件                         | 行数 | 角色                                                        |
+| ---------------------------- | ---- | ----------------------------------------------------------- |
+| `__init__.py`                | 52   | 工厂 `get_mail_client()` + 兼容别名 `CloudMailClient`       |
+| `base.py`                    | 276  | `MailProvider` ABC + `Email/Account` dataclass + 共享文本工具 |
+| `cf_temp_email.py`           | 379  | `dreamhunter2333/cloudflare_temp_email` 后端实现            |
+| `maillab.py`                 | 467  | `maillab/cloud-mail` 后端实现(即 skymail.ink)               |
+
+**`MailProvider` ABC 公开方法集**(11 个,`base.py` 定义):
+
+| 方法                         | 抽象度  | 用途                                                      |
+| ---------------------------- | ------- | --------------------------------------------------------- |
+| `login()`                    | abstract | 初始化鉴权,返回 token 字符串(仅日志用)                  |
+| `create_temp_email(prefix, domain)` | abstract | 创建临时邮箱,返回 `(account_id, email)`           |
+| `list_accounts(size)`        | abstract | 列出已建邮箱,返回 dict 列表                               |
+| `delete_account(account_id)` | abstract | 删除邮箱,返回 `{code, message?}`                          |
+| `search_emails_by_recipient(to_email, size, account_id)` | abstract | 按收件人查邮件                            |
+| `list_emails(account_id, size)` | abstract | 按 accountId 查邮件                                     |
+| `delete_emails_for(to_email)`| abstract | 批量删除某收件人的所有邮件                                |
+| `get_latest_emails(account_id, ...)` | concrete | 旧接口兼容,默认委托 `list_emails`                  |
+| `wait_for_email(...)`        | concrete | 轮询等待邮件,默认实现搬自旧 `cloudmail.py`              |
+| `extract_verification_code(email_data)` | concrete | 提取 6 位 OTP(纯文本正则)                          |
+| `extract_invite_link(email_data)` | concrete | 提取 ChatGPT/通用邀请链接                            |
+
+**`MaillabClient` 实际命中的 maillab API**(已上线):
+
+| 方法               | HTTP 路径                    | 备注                                                                |
+| ------------------ | ---------------------------- | ------------------------------------------------------------------- |
+| `login`            | `POST /login`                | body `{email, password}` → `{code:200, data:{token}}`               |
+| `create_temp_email`| `POST /account/add`          | body `{email}`(完整地址,不接受 prefix+domain 拆开)                |
+| `list_accounts`    | `GET /account/list`          | 服务端硬 cap 30/页,代码已实现 `lastSort + accountId` 游标翻页     |
+| `delete_account`   | `DELETE /account/delete?accountId=N` |                                                             |
+| `list_emails`      | `GET /email/list`            | 必须带 `type=0`(RECEIVE),否则 SQL `IS NULL` 永远为空              |
+| `get_latest_emails`| `GET /email/latest`          |                                                                     |
+| `delete_emails_for`| `DELETE /email/delete?emailIds=1,2,3` | 软删除                                                     |
+
+**调用方调用面**(`src/autoteam` 全仓 grep):
+
+| 调用方            | `CloudMailClient()` 实例化 | `mail_client.<method>` 引用 |
+| ----------------- | -------------------------- | --------------------------- |
+| `manager.py`      | 11                         | 7                           |
+| `api.py`          | 5                          | -                           |
+| `invite.py`       | 1                          | 4                           |
+| `codex_auth.py`   | 0(由调用方注入)           | 9                           |
+| `account_ops.py`  | 1                          | 2                           |
+| `setup_wizard.py` | 1                          | 0                           |
+| 合计              | **19 处实例化 / 22 处方法调用** | —                       |
+
+→ 所有调用都走 `from autoteam.cloudmail import CloudMailClient` 兼容别名,**业务层零改动**。
+
+### A.2 setup_wizard CloudMail 验证流程
+
+`src/autoteam/setup_wizard.py:_verify_cloudmail()` 实际流程:
+
+1. 读 `MAIL_PROVIDER` 环境变量(默认 `cf_temp_email`)
+2. 校验对应的环境变量集是否齐全(cf 看 `CLOUDMAIL_BASE_URL/PASSWORD/DOMAIN`,maillab 看 `MAILLAB_API_URL/USERNAME/PASSWORD` + 域名)
+3. 调用 `_sniff_provider_mismatch(provider)`:用 GET `/admin/address` 与 GET `/login` 探测路由指纹,发现 base_url 协议错配则打 warning 但不阻断
+4. 实例化 `CloudMailClient()` → `client.login()` → `client.create_temp_email(prefix=at-test-xxxxx)` → `client.delete_account(...)`
+5. 任一环节抛异常 → 打 ERROR 并 `return False`
+
+`_verify_cloudmail()` 也被同名函数 `post_setup_save` (`api.py:99`) 复用,即 Web 面板 SetupPage 提交后走的也是这套逻辑。
+
+### A.3 配置项 (.env / CLOUDMAIL_*)
+
+`.env.example` 当前定义:
+
+```dotenv
+MAIL_PROVIDER=cf_temp_email                  # cf_temp_email | maillab
+CLOUDMAIL_BASE_URL=https://example.com/api
+CLOUDMAIL_PASSWORD=your_password
+CLOUDMAIL_DOMAIN=@example.com
+CLOUDMAIL_EMAIL=                             # 已废弃,保留兼容旧 .env
+# MAILLAB_API_URL=https://your-maillab.example.com
+# MAILLAB_USERNAME=admin@example.com
+# MAILLAB_PASSWORD=your_password
+# MAILLAB_DOMAIN=@example.com
+```
+
+**`setup_wizard.REQUIRED_CONFIGS`**(交互式向导询问的字段):
+
+- `MAIL_PROVIDER` (默认 `cf_temp_email`,可选)
+- `CLOUDMAIL_BASE_URL`
+- `CLOUDMAIL_PASSWORD`
+- `CLOUDMAIL_DOMAIN`
+- `CPA_URL` / `CPA_KEY`
+- `PLAYWRIGHT_PROXY_URL` / `PLAYWRIGHT_PROXY_BYPASS`(可选)
+- `API_KEY`
+
+> **关键缺口**:`REQUIRED_CONFIGS` 与 Web 面板 SetupPage **没有**收 maillab 字段(`MAILLAB_API_URL/USERNAME/PASSWORD/DOMAIN`)。
+> 用户选 `MAIL_PROVIDER=maillab` 时**只能手动改 `.env`**,getting-started.md L128 也写了这一点。
+> 这正是 issue#1 截图里"创建邮箱失败 401"的 root cause(详见 §D)。
+
+`api.py` 的 `SetupConfig` Pydantic 模型(L70-79):
+
+```python
+class SetupConfig(BaseModel):
+    CLOUDMAIL_BASE_URL: str = ""
+    CLOUDMAIL_EMAIL: str = ""
+    CLOUDMAIL_PASSWORD: str = ""
+    CLOUDMAIL_DOMAIN: str = ""
+    CPA_URL: str = "http://127.0.0.1:8317"
+    CPA_KEY: str = ""
+    PLAYWRIGHT_PROXY_URL: str = ""
+    PLAYWRIGHT_PROXY_BYPASS: str = ""
+    API_KEY: str = ""
+```
+
+**完全不包含 `MAIL_PROVIDER` 与 `MAILLAB_*`** → Web 面板提交配置时即使前端把字段塞进去,Pydantic 默认会忽略未定义字段,
+`/api/setup/save` 不会写入 `MAIL_PROVIDER`,造成 maillab 部署用户被锁死在 cf_temp_email 模式。
+
+---
+
+## B. skymail.ink 官方 API 全表
+
+> **结论先行**:skymail.ink 是 `maillab/cloud-mail` 的对外品牌(GitHub `@maillab` 组织,Releases 链来自 `doc.skymail.ink` 顶部导航)。
+> `doc.skymail.ink/api/api-doc.html` 只对外公布了 3 个"集成接口"(`/public/*`),但仓库实际暴露的路由 ≥ 60 个,
+> 全部按 `mail-worker/src/api/*-api.js` 文件分组。
+
+### B.1 已确认接口(全部从 GitHub 源码核实)
+
+#### B.1.1 公开集成接口 `/public/*`(skymail 文档显式公开,**仅 3 个**)
+
+| 路由                  | 方法 | 鉴权要求                              | 用途                                                   |
+| --------------------- | ---- | ------------------------------------- | ------------------------------------------------------ |
+| `/public/genToken`    | POST | **白名单内**(无需 token)。但 service 内部 `verifyUser()` 会校验 `email === c.env.admin`,**仅管理员邮箱**能拿到 token | 拿一个 UUID 格式的 API token(KV 持久化)              |
+| `/public/emailList`   | POST | 需 `Authorization: <jwt>`(genToken 拿到的 token 也认) | 模糊查邮件:支持 `toEmail/sendName/sendEmail/subject/content/timeSort/type/isDel/num/size`     |
+| `/public/addUser`     | POST | 需 `Authorization: <jwt>`             | 批量加用户:body `{list:[{email, password?, roleName?}, ...]}` |
+
+#### B.1.2 鉴权 `/login` `/register` `/logout`(在白名单)
+
+| 路由         | 方法   | body / 参数                         | 返回                                       |
+| ------------ | ------ | ----------------------------------- | ------------------------------------------ |
+| `/login`     | POST   | `{email, password, [token?]}`       | `{code:200, data:{token}}` — token=裸 JWT |
+| `/register`  | POST   | `{email, password, [token?]}`       | `{code:200, data:<jwt>}`                  |
+| `/logout`    | DELETE | header `Authorization: <jwt>`       | `{code:200}`                               |
+
+#### B.1.3 账户管理 `/account/*`(需鉴权)
+
+| 路由                        | 方法   | 关键参数                  | 用途                                          |
+| --------------------------- | ------ | ------------------------- | --------------------------------------------- |
+| `/account/list`             | GET    | `size, lastSort, accountId` | 列表(单页 cap 30,游标翻页)               |
+| `/account/add`              | POST   | body `{email}`            | 新建临时邮箱(完整地址,服务端校验域名白名单) |
+| `/account/delete`           | DELETE | `accountId`               |                                               |
+| `/account/setName`          | PUT    | body `{accountId, name}`  | 改备注                                        |
+| `/account/setAllReceive`    | PUT    | body `{accountId, allReceive}` | 是否接收所有发件人                       |
+| `/account/setAsTop`         | PUT    | body `{accountId}`        | 置顶/取消置顶                                 |
+
+#### B.1.4 邮件 `/email/*`(需鉴权)
+
+| 路由                | 方法   | 关键参数                                                                 | 用途                                                   |
+| ------------------- | ------ | ------------------------------------------------------------------------ | ------------------------------------------------------ |
+| `/email/list`       | GET    | `accountId, type(0=收/1=发,**必传**), size(<=50), emailId, timeSort, allReceive` | drizzle 用 `eq(email.type, type)`,缺省走 IS NULL      |
+| `/email/latest`     | GET    | `accountId, emailId(游标), allReceive`                                   | 最新 ≤ 20 封(默认按 emailId desc)                    |
+| `/email/attList`    | GET    | `emailId`                                                                | 附件列表                                               |
+| `/email/delete`     | DELETE | `emailIds`(逗号分隔)                                                   | 软删除                                                 |
+| `/email/send`       | POST   | body(发件载荷)                                                         | 发邮件(基于 Resend)                                 |
+| `/email/read`       | PUT    | body `{emailId}`                                                         | 标记已读                                               |
+
+#### B.1.5 全局邮件管理 `/allEmail/*`(管理员权限)
+
+| 路由                       | 方法   | 用途                            |
+| -------------------------- | ------ | ------------------------------- |
+| `/allEmail/list`           | GET    | 管理员看全平台邮件               |
+| `/allEmail/latest`         | GET    | 全平台最新邮件                  |
+| `/allEmail/delete`         | DELETE | 物理删除(硬删)                |
+| `/allEmail/batchDelete`    | DELETE | 批量物理删除                    |
+
+#### B.1.6 用户管理 `/user/*`(管理员权限)
+
+| 路由                       | 方法   | 用途                             |
+| -------------------------- | ------ | -------------------------------- |
+| `/user/list`               | GET    | 用户列表                         |
+| `/user/add`                | POST   | 新增用户(单条)                |
+| `/user/setPwd`             | PUT    | 改密                             |
+| `/user/setStatus`          | PUT    | 启停                             |
+| `/user/setType`            | PUT    | 改类型                           |
+| `/user/restore`            | PUT    | 恢复                             |
+| `/user/resetSendCount`     | PUT    | 重置发件计数                     |
+| `/user/delete`             | DELETE | 物理删除                         |
+| `/user/allAccount`         | GET    | 某用户名下所有 account(临时邮箱)|
+| `/user/deleteAccount`      | DELETE | 删某用户的某 account             |
+
+#### B.1.7 角色 `/role/*`(管理员权限)
+
+| 路由                  | 方法   | 用途                |
+| --------------------- | ------ | ------------------- |
+| `/role/list`          | GET    | 角色列表            |
+| `/role/permTree`      | GET    | 权限树(RBAC)      |
+| `/role/selectUse`     | GET    | 可选角色            |
+| `/role/add`           | POST   | 新增                |
+| `/role/set`           | PUT    | 改                  |
+| `/role/setDefault`    | PUT    | 设默认              |
+| `/role/delete`        | DELETE | 删                  |
+
+#### B.1.8 设置 `/setting/*`
+
+| 路由                          | 方法   | 鉴权                  | 用途                                                                |
+| ----------------------------- | ------ | --------------------- | ------------------------------------------------------------------- |
+| **`/setting/websiteConfig`**  | GET    | **白名单(无需 token)** | 拉公开站点配置 — **关键端点**(归属验证用,详见 §C)                |
+| `/setting/query`              | GET    | 需 token              | 全量站点设置(管理员视角,token 等敏感字段已掩码)                  |
+| `/setting/set`                | PUT    | 需 token + admin 权限 | 改设置                                                              |
+| `/setting/setBackground`      | PUT    | 需 token + admin 权限 | 改背景                                                              |
+| `/setting/deleteBackground`   | DELETE | 需 token + admin 权限 | 删背景                                                              |
+
+**`/setting/websiteConfig` 返回字段**(已现场验证 `setting-service.js`):
+
+```text
+register, title, manyEmail, addEmail, autoRefresh, addEmailVerify, registerVerify, send,
+domainList,           # ★ 平台允许的邮箱域名清单,如 ["@example.com", "@another.com"]
+siteKey, regKey, r2Domain, background, loginOpacity,
+regVerifyOpen, addVerifyOpen,            # 是否开启注册/添加邮箱时的人机验证
+noticeTitle/noticeContent/noticeType/noticeDuration/noticePosition/noticeWidth/noticeOffset/notice,
+linuxdoClientId/linuxdoCallbackUrl/linuxdoSwitch,    # OAuth2 开关
+loginDomain, minEmailPrefix, projectLink
+```
+
+#### B.1.9 其他
+
+| 路由前缀         | 方法集               | 鉴权 | 备注                                                       |
+| ---------------- | -------------------- | ---- | ---------------------------------------------------------- |
+| `/init/:secret`  | GET                  | 白名单 | 首次部署初始化 DB                                         |
+| `/oauth/*`       | GET/POST             | 白名单 | LinuxDo / 第三方 OAuth 登录                                |
+| `/webhooks/*`    | POST                 | 白名单 | 收件 webhook 入口(Cloudflare email routing 触发)         |
+| `/oss/*`         | POST/DELETE          | 白名单 | 附件 OSS(R2)上传                                        |
+| `/r2/*`          | POST/DELETE          | 需 token | 附件管理(管理员视角)                                  |
+| `/regKey/*`      | POST/GET/DELETE      | 需 token | 注册码管理                                                |
+| `/star/*`        | POST/DELETE/GET      | 需 token | 邮件星标                                                  |
+| `/my/*`          | GET/PUT              | 需 token | 当前用户配置                                              |
+| `/resend/*`      | POST/GET             | 需 token | Resend token 管理(发邮件凭证)                           |
+| `/analysis/*`    | GET                  | 需 token | 数据可视化                                                |
+| `/telegram/*`    | POST                 | 白名单 | Telegram bot 入口                                         |
+| `/test/*`        | GET                  | 白名单 | 健康检查                                                  |
+
+### B.2 推测 / 未确认接口
+
+| 推测点                                                    | 是否需补查源码 | 备注                                                            |
+| --------------------------------------------------------- | -------------- | --------------------------------------------------------------- |
+| `/oauth/linuxdo/callback` 具体回调字段                    | 是             | `oauth-api.js` 未抓全文,可能影响后续做"用 linuxdo OAuth 验证归属" |
+| `/init/:secret` 的 `secret` 来源                           | 是             | 部署期生成,文档未明示;集成不需要                              |
+| `/setting/websiteConfig` 中 `domainList` 是否随租户隔离  | 是             | maillab 单实例多租户?设计文档未明,但 RBAC 看 user.userId 走表  |
+| 短期是否会出 `/api/v2/*` 路由                             | 否(暂时)     | 现仓库 `mail-worker` 单工程,无版本前缀                          |
+| Turnstile 启用后 `/login` 是否要 `token` 字段              | 是             | maillab.py 已注释 TODO(maillab-verify),实施前 e2e 验证        |
+| `/account/add` 创建时的 `addVerify` 行为                   | 是             | 当 `addVerifyOpen=true` 时是否要带 captcha token,需先查 service |
+
+### B.3 鉴权与刷新机制
+
+源码:`mail-worker/src/security/security.js`
+
+```javascript
+// 全局中间件
+app.use('*', async (c, next) => {
+  // 1. 白名单直通
+  if (exclude.some(p => path.startsWith(p))) return next();
+
+  // 2. 取 token
+  const jwt = c.req.header(constant.TOKEN_HEADER);   // header = "Authorization"
+  if (!jwt) throw 'unauthorized';
+
+  // 3. 验签 + 检查会话
+  const result = await jwtUtils.verifyToken(c, jwt);
+  const authInfo = await getAuthInfo(c, result.userId);
+  if (!authInfo.tokens.includes(jwt)) throw 'session expired';
+
+  // 4. RBAC: requirePerms 数组里的端点会��权限检查
+  if (requirePerms.includes(path)) {
+    const permKeys = await permService.userPermKeys(c, authInfo.user.userId);
+    const userPaths = permKeyToPaths(permKeys);
+    const userPermIndex = userPaths.indexOf(path);
+    // 5. admin 邮箱直通(`c.env.admin` 是部署期配置)
+    if (userPermIndex === -1 && authInfo.user.email !== c.env.admin) throw 'no permission';
+  }
+
+  // 6. 每日 TTL 刷新
+  if (today != lastRefresh) await refreshAuthInfoTTL(c, authInfo);
+});
+```
+
+**关键点 — 集成 AutoTeam 必须知道**:
+
+1. **header 名 = `Authorization`**(常量 `TOKEN_HEADER`),**裸 JWT**,**不加 `Bearer ` 前缀**。
+   这与一般 OAuth 习惯不同,`maillab.py:91-97` 已正确处理。
+2. **Session 是 server-side 持久化**(KV `authInfo.tokens`),所以 token 续命不是靠 JWT 过期时间,而是看 KV;
+   本地 token 缓存可以长期有效,但不能跨重启假定。
+3. **`c.env.admin` 是部署期配置的管理员邮箱白名单**,这位用户调用 `/public/genToken` 才能拿到 token。
+4. **TTL 刷新是被动的**(每日首次调用触发),不是主动 keep-alive。
+5. **没有 refresh_token 概念** — token 失效后必须重新 `/login`。AutoTeam 需要在 401 时调用 `_ensure_login()` 自愈
+   (现 `maillab.py` 没做,详见 §F)。
+
+---
+
+## C. 设计:邮箱归属验证 UI
+
+### C.1 用户故事
+
+> 作为管理员,我在 AutoTeam 的 Setup / Settings 页填写"CloudMail 域名"时,
+> **不应**靠手敲一个字符串然后再用 `/api/config/register-domain` 试探;
+> **应该**直接从 maillab 服务端拉到"我能用的域名清单",
+> 并在保存前**确认我对该域名拥有写权限**(我能在这个 domain 下创建临时邮箱,
+> 且 maillab 后端没启用我没法过的 captcha)。
+>
+> 同时,如果我换了 maillab 实例 base_url,前端要在我点"保存"前就告诉我:
+> 1. 这个 base_url 是 maillab 后端吗?(指纹探测 — 现在已经有 `_sniff_provider_mismatch`,但仅在启动验证阶段跑,前端没有)
+> 2. 这个 base_url 允许哪些 domain?(从 `/setting/websiteConfig.domainList` 拿)
+> 3. 我用我填的 username/password 真的能登进去吗?(`/login`)
+> 4. 这个 domain 在我登录后真的能创建邮箱吗?(`/account/add` 试探,然后立即 `/account/delete` 回收 — 现 `register-domain` PUT 已经有这逻辑)
+
+### C.2 流程图(setup wizard 与 settings 共用)
+
+```text
+                     用户填 base_url + username + password + (可选)domain
+                                          │
+                                          ▼
+                ┌─────────────────────────────────────────────────┐
+                │ Step 1. 路由指纹探测(无需鉴权)                 │
+                │   GET {base_url}/setting/websiteConfig           │
+                │     ├─ 200 + 含 domainList   → 是 maillab        │
+                │     ├─ 200 但缺 domainList    → 可能是 cf_temp_email,提示切 provider │
+                │     ├─ 404 / 5xx              → base_url 错      │
+                │     └─ 网络错                  → 提示连接性       │
+                └─────────────────────────────────────────────────┘
+                                          │ ok
+                                          ▼
+                ┌─────────────────────────────────────────────────┐
+                │ Step 2. 域名展示与选择                          │
+                │   将 websiteConfig.domainList 渲染为下拉框       │
+                │   ├─ 只有 1 个域 → 自动选中                     │
+                │   ├─ 多个域 → 让用户选(默认第一个)            │
+                │   └─ 0 个域 → 报错"该实例未配置任何邮箱域名"   │
+                │   同时把 addVerifyOpen / registerVerify 的开关  │
+                │   值返回给前端,如果开了就警告"该实例需要 captcha,│
+                │   AutoTeam 自动化路径暂不支持,请到 maillab 后台关闭"│
+                └─────────────────────────────────────────────────┘
+                                          │ ok
+                                          ▼
+                ┌─────────────────────────────────────────────────┐
+                │ Step 3. 凭据校验(归属第一关)                  │
+                │   POST {base_url}/login                          │
+                │     body {email: username, password}             │
+                │     ├─ code:200, data.token → 拿到 jwt          │
+                │     │  解析 JWT payload,展示 `email` `userType` │
+                │     │  如果 email ≠ c.env.admin → 警告"非管理员,│
+                │     │     仅能创建临时邮箱,无法管理用户"        │
+                │     ├─ code:401 → "凭据错误"                    │
+                │     └─ 其他    → 透传 message                    │
+                └─────────────────────────────────────────────────┘
+                                          │ ok
+                                          ▼
+                ┌─────────────────────────────────────────────────┐
+                │ Step 4. 域名归属确认(写权限验证)              │
+                │   带 Authorization: <jwt>                        │
+                │   POST {base_url}/account/add                    │
+                │     body {email: "probe-{ts}@{domain}"}          │
+                │     ├─ code:200, data.accountId → 归属确认      │
+                │     │  随后 DELETE /account/delete?accountId=N  │
+                │     │  立即回收探测邮箱                          │
+                │     ├─ code:401 → "登录已过期"(罕见,刚拿的 jwt)│
+                │     ├─ code:403 → "无权在该域下创建" → 归属失败 │
+                │     └─ code:其他 + message 含 "domain" → 归属失败 │
+                └─────────────────────────────────────────────────┘
+                                          │ ok
+                                          ▼
+                ┌─────────────────────────────────────────────────┐
+                │ Step 5. 保存配置                                │
+                │   POST /api/setup/save 写入:                    │
+                │     MAIL_PROVIDER=maillab                        │
+                │     MAILLAB_API_URL={base_url}                   │
+                │     MAILLAB_USERNAME={username}                  │
+                │     MAILLAB_PASSWORD={password}                  │
+                │     MAILLAB_DOMAIN=@{domain}                     │
+                │   后端再用 _verify_cloudmail() 跑一遍 e2e        │
+                └─────────────────────────────────────────────────┘
+```
+
+### C.3 API 契约(后端新增端点)
+
+> **关键设计抉择**:不要让前端直接连 maillab 跨域,**全部通过 AutoTeam 后端代理**,理由:
+> 1. 用户填的 base_url 多半是 HTTP / 自签证书,浏览器跨域会复杂
+> 2. 凭据(password / jwt)如果在前端 fetch,F12 直接看到
+> 3. 后端代理后续可以加重试 / 错误归一化 / 日志
+
+**新增 `/api/mail-provider/probe`** (POST,无需鉴权 — 与 setup/save 一致;实际进了面板后再加 API_KEY)
+
+```yaml
+request:
+  provider: "maillab"           # 或 "cf_temp_email"
+  base_url: "https://mail.example.com"
+  # cf_temp_email
+  password?: "admin_pwd"        # cf 的 admin password
+  domain?: "@example.com"
+  # maillab
+  username?: "admin@example.com"
+  password?: "user_pwd"
+  domain?: "@example.com"       # 可选,用户已选中的域
+  step: "fingerprint" | "credentials" | "domain_ownership"  # 分步执行,前端按用户进度调
+
+response (step=fingerprint):
+  ok: true
+  detected_provider: "maillab"
+  domainList: ["@example.com", "@another.com"]
+  addVerifyOpen: false
+  registerVerifyOpen: false
+  warnings: []                  # 例:"检测到 base_url 像 cf_temp_email,但 MAIL_PROVIDER=maillab"
+
+response (step=credentials):
+  ok: true
+  is_admin: true                # email == c.env.admin?
+  token_preview: "eyJ..."       # 仅用于前端展示鉴权成功,不长期存
+  user_email: "admin@example.com"
+
+response (step=domain_ownership):
+  ok: true
+  probe_email: "probe-1714123456@example.com"
+  probe_account_id: 12345
+  cleaned: true                 # 探测邮箱已删除
+
+response (any step, error):
+  ok: false
+  error_code: "ROUTE_NOT_FOUND" | "UNAUTHORIZED" | "FORBIDDEN_DOMAIN" | "NETWORK" | ...
+  message: "原始 maillab 响应 message,或本地翻译"
+  hint?: "建议用户怎么改"        # 如:把 MAIL_PROVIDER 改成 cf_temp_email
+```
+
+**前端 SetupPage 改造点**(`web/src/components/SetupPage.vue`):
+
+1. 字段从平铺改为**分组卡片**:
+   - 卡片 1:Mail Provider(单选 cf_temp_email / maillab,选中后只显示对应字段)
+   - 卡片 2:base_url + 凭�� + "测试连接"按钮(调 step=fingerprint + step=credentials)
+   - 卡片 3:domain 下拉框(从 step=fingerprint 拉到的 domainList 渲染) + "验证归属"按钮(调 step=domain_ownership)
+   - 卡片 4:CPA / API_KEY / 代理(原样保留)
+2. 步骤式 UX:每步必须通过才能进下一步,失败显示原始 error message + hint
+3. step=domain_ownership 通过后,"保存配置"按钮才可点;后端再做一次完整 `_verify_cloudmail()`
+
+---
+
+## D. 401 根因分析 (setup_wizard 创建邮箱失败)
+
+### D.1 截图证据
+
+```
+[CloudMail] 管理员鉴权通过
+[验证] CloudMail (cf_temp_email) 登录成功
+[验证] CloudMail (cf_temp_email) 创建邮箱失败:
+       创建邮箱失败:响应缺少 address 字段:{'code': 401, 'message': '身份认证失效,请重新登录'}
+[验证] 请检查 CLOUDMAIL_DOMAIN 是否正确
+[验证] CloudMail 配置有误,请修改 .env 后重新启动
+```
+
+### D.2 根因(直接,可证伪)
+
+**协议错配 — 用户填了 maillab 服务器地址,但 `MAIL_PROVIDER` 仍走默认 `cf_temp_email`**。
+
+证据链:
+
+1. `_verify_cloudmail()` 走的是 `cf_temp_email` 分支(label = "cf_temp_email"),意味着 `MAIL_PROVIDER` 没设或设成 cf_temp_email。
+2. `cf_temp_email.login()`(`mail/cf_temp_email.py:86-116`)实际只 `GET /admin/address?limit=1` 验证 admin 密码:
+   ```python
+   r = self._admin_get("/admin/address", params={"limit": 1, "offset": 0})
+   ```
+   maillab 服务器**有 catch-all 路由**(Hono 默认 404,但部分部署/反向代理把 404 也返成 200 + 自定义错误体);
+   或者 maillab `/admin/address` 路径**未匹配任何路由,被 Hono 内置 fallback 处理**,响应不一定是 maillab 风格 `{code, ...}`,
+   也可能是 `200 OK + {}`,这时 `cf_temp_email.login` 看到 200 + 不含 `code/data` → 误以为成功(L106-112 的嗅探仅在响应像 maillab 时才抛错)。
+3. 走到 `create_temp_email()`(L120-188)时,`POST /admin/new_address` 触发了 maillab 真正路由(可能是 `/admin/*` 通配的 401 拒绝,也可能是 worker 的 unmatched route fallback 直接返 maillab 风格 `{code:401, message:"身份认证失效,请重新登录"}`)。
+4. 代码 L154-159 的 maillab 风格响应嗅探**确实捕获到了**这个错误并打印,但截图上看到的最终 message 是 `创建邮箱失败:响应缺少 address 字段:{'code': 401, 'message': '身份认证失效, 请重新登录'}`,
+   **错误信息被错误地折叠回 `响应缺少 address 字段` 分支**(L182,因为 if 条件不严:`"address" not in data and ("code" in data and "message" in data)` 只在响应同时含 code+message 时才走更友好的 maillab-mismatch 分支,
+   实际响应 dict 是 `{code:401, message:'...'}` 应该会命中 — 但截图说"响应缺少 address 字段"出在 L182,意味着**实际响应可能不是这个结构**,例如:
+   - `{code:401, message:'...', success:false}` (额外字段)→ 命中 L154 OK,但 message 拼接组装时被 L155-159 的 raise 抛出
+   - **或者响应是 `{code:401, message:'...'}` 直接命中 L182 的"缺少 address"分支**(可能是 cf_temp_email 路由在 maillab 上被 worker 默认 unmatched 处理,直接吐了一个像 `{code:401, ...}` 的 JSON 而 dict 没有 `data` 字段)
+
+**结论**:
+
+- **直接原因**:用户的 base_url(`https://apimail.icoulsy.asia`,看 `.env` L2)是 maillab 服务器,但 `.env` 里**没设 `MAIL_PROVIDER`**(默认走 cf_temp_email),触发 §B.3 描述的"半成功"现象。
+- **附带原因(代码 bug)**:`cf_temp_email.login()` 的指纹嗅探(L106-112)条件**过于宽松** — 只在响应 dict 出现 `code` 或 `data` 字段时才抛错,但 maillab 真实的 `/admin/address` 在某些 worker 部署下可能返回 200 + `{}`(empty body)而非 maillab 标准 `{code,...}` 结构,
+  导致 login 假成功,直到 create 才暴露。
+- **次要原因(UX 缺口)**:setup_wizard 的 `_sniff_provider_mismatch`(setup_wizard.py:173-220)是**启动时跑**的,
+  Web 面板 `post_setup_save` 不调 `_sniff_provider_mismatch`,只调 `_verify_cloudmail` → 用户在 Web 端首次填错时**得不到指纹错配的早期 warning**。
+
+### D.3 修复方向(分层)
+
+| 层级               | 修复点                                                                                                         | 优先级 |
+| ------------------ | -------------------------------------------------------------------------------------------------------------- | ------ |
+| **立即(用户)**  | 在 `.env` 加 `MAIL_PROVIDER=maillab`,把 `CLOUDMAIL_*` 改 `MAILLAB_*`(domain 复用 `CLOUDMAIL_DOMAIN`)         | P0     |
+| **代码(嗅探)**  | `cf_temp_email.login()` L106-112:在 `r.status_code==200` 且**响应 dict 缺少 `results` key**时一律抛错(空 body 也错配) | P0     |
+| **代码(嗅探)**  | `setup_wizard._sniff_provider_mismatch` 移到 `_verify_cloudmail` 第一步(目前是第二步),并在错配时 `return False` 而不是 warning | P0     |
+| **代码(SetupConfig)** | `api.py:SetupConfig` Pydantic 模型加 `MAIL_PROVIDER` / `MAILLAB_API_URL` / `MAILLAB_USERNAME` / `MAILLAB_PASSWORD` / `MAILLAB_DOMAIN` 字段 | P0     |
+| **代码(向导)**  | `setup_wizard.REQUIRED_CONFIGS` 加 maillab 字段,根据 `MAIL_PROVIDER` 选项动态显示                              | P0     |
+| **UI(SetupPage)** | 实现 §C.2 的分步流程,把"填错 → 启动崩"前移到"填时即知"                                                       | P1     |
+| **错误信息**       | `create_temp_email` L156 的 raise 文案加上"如果你看到这条错误是从 SetupPage 来的,先点'重新探测后端类型'"          | P1     |
+| **代码(自愈)**  | `MaillabClient` 在 401 时尝试 `_ensure_login()` 重登一次再重试一次(对短期 token 失效自愈)                      | P2     |
+
+---
+
+## E. 文档改写清单
+
+| 文档                           | 章节                          | 改动类型 | 内容                                                                                                       |
+| ------------------------------ | ----------------------------- | -------- | ---------------------------------------------------------------------------------------------------------- |
+| `docs/getting-started.md`      | 「准备工作 / 1. 搭建临时邮箱」 | 改写     | 把"两个临时邮箱后端二选一"的语境从"cf_temp_email 默认推荐"改为**按用户实际部署选择**;突出 `MAIL_PROVIDER` 是必填 |
+| `docs/getting-started.md`      | 「第二步:配置 / 直接部署」    | 改写     | 配置示例增补完整 maillab 字段;说明 Web 面板 SetupPage 已支持选 provider(实施 §C 后)                       |
+| `docs/getting-started.md`      | (新增章节)「第二点五步:验证邮箱后端归属」 | 新增 | 说明 SetupPage 的 4 步验证流程(指纹 → 凭据 → 域名 → 保存),提示用户哪些情况会报错及对应 hint |
+| `docs/configuration.md`        | 「`.env` 配置项」表           | 改写     | `MAIL_PROVIDER` 列从"否"改成"**是**";`MAILLAB_*` 各字段说明改为"**Web 面板 Setup/Settings 中可填**" |
+| `docs/configuration.md`        | 「Mail Provider 切换」        | 改写     | 推荐顺序逆转:**maillab 优先推荐**(国内访问/skymail 一键部署友好);cf_temp_email 改为"Cloudflare Workers 用户"备选 |
+| `docs/configuration.md`        | (新增章节)「邮箱归属验证」    | 新增     | 阐明 `/setting/websiteConfig` 拉 domainList 的机制;说明 addVerify/registerVerify 启用时不被 AutoTeam 支持的边界 |
+| `docs/configuration.md`        | 「⚠️ 协议错配排查」            | 改写     | 把 issue#1 的截图与最终 fix 步骤显式列出;链接到 SetupPage 的"重新探测后端类型"按钮(§C 实施后)               |
+| `docs/mail-provider-design.md` | §6「cloud-mail 实现的未知项」 | 改写     | 5 项 TODO 标记**已通过 GitHub 源码全部确认**(login JWT header / domain 列表 API / createTime 单位 / 创建端点 / accountId 类型),状态从"未确认"改为"已验证 with reference" |
+| `docs/mail-provider-design.md` | (新增章节)§7「skymail.ink API 全表」 | 新增 | 把本文件 §B.1.1-B.1.9 表格整理后入档;作为 cloudmail.py 长期维护参考 |
+| `docs/troubleshooting.md`      | 「Web 面板相关」              | 增补     | 加"配置保存后 401 创建邮箱失败"条目,链到 §D 的修复表                                                       |
+| `docs/troubleshooting.md`      | (新增章节)「邮箱后端」        | 新增     | 列出常见问题:base_url 写错 / domain 错配 / token 失效 / Turnstile 启用 / 单实例多域选错 |
+| `docs/api.md`                  | 「初始配置 API」              | 增补     | 文档化 `/api/mail-provider/probe`(实施 §C 后);明确 `/api/setup/save` 的 SetupConfig 已扩展 maillab 字段 |
+| `docs/api.md`                  | 「域名管理 API」              | 改写     | `/api/config/register-domain` 的 verify 探测改为"会调用 §C step=domain_ownership 共享逻辑" |
+| `docs/architecture.md`         | (如有 mail 章节)             | 增补     | 把"`MailProvider` ABC + 工厂分发"图列出;skymail.ink 集成方式作为 reference impl |
+| `README.md`                    | 主要 Features                  | 增补     | 加"原生支持 maillab/cloud-mail (skymail.ink) 全量集成,含归属验证"                                          |
+| `.env.example`                 | 注释                          | 改写     | `MAIL_PROVIDER=` 上面写"**强烈推荐显式设置**,不设默认 cf_temp_email 可能与你的 maillab 部署错配"           |
+
+---
+
+## F. 风险与未决问题
+
+### F.1 实施风险
+
+| 风险                                                                                                | 缓解                                                                                       | 严重度 |
+| --------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------ | ------ |
+| `/setting/websiteConfig` 的 `domainList` 字段在 maillab v2.x 之前可能不存在(skymail.ink 当前 v2.8.0)| 前端兼容:domainList 缺失时降级为 free-input,后端探测改为"试创建一次邮箱"                  | 中     |
+| maillab 部署启用 Turnstile (`registerVerifyOpen=true`)时,AutoTeam 自动化路径无法过 captcha          | 探测响应显式告诉用户;在 docs/troubleshooting.md 写明"请到 maillab 后台关闭 captcha"        | 高(用户体验) |
+| `/public/genToken` 返回的 UUID token 与 `/login` 返回的 JWT 是否互通 — service 内部可能两套 KV     | 现 maillab.py 走 /login 路径,**不动 /public/genToken**;只有当用户明确想用 public API 时再加 | 低     |
+| 新 `/api/mail-provider/probe` 端点暴露后,被外部用作端口扫描(用户填任意 base_url 跑探测)            | 加 rate limit + 仅在 setup/save 阶段开放(进面板后用 API_KEY 鉴权)                        | 中     |
+| `cf_temp_email.login()` 嗅探收紧后,对**一些第三方 fork** (例如 `unsendapp/cloudflare_temp_email` 等)误伤 | 错误信息提示用户可以 `AUTOTEAM_SKIP_VERIFY=1` 绕过;长期看是收益>风险                       | 低     |
+| `MaillabClient.list_accounts` 单页 cap 30 是**当前版本**约束,未来 maillab 可能改                   | 代码注释已写来源 `account-service.js`;CI 加一个 maillab e2e mock 测试翻页边界               | 低     |
+| Web 面板 SetupPage 改造大,前后端字段都要改                                                          | 分阶段 PR:第 1 阶段只补 SetupConfig + REQUIRED_CONFIGS(P0);第 2 阶段做分步 UX(P1)       | 中     |
+
+### F.2 未决问题(需 PRD 阶段决议)
+
+1. **maillab 是否要支持非 admin 用户**?当前 `_verify_cloudmail` 隐式假设登录的就是平台 admin(因为 `c.env.admin` 才能调 `/public/genToken`);但 `/account/add` 普通用户也能调。是否对 SetupPage 的 username 做严格性检查?
+2. **是否暴露 `/account/setName / setAllReceive / setAsTop`** 给 AutoTeam UI?目前业务流程只用 add/delete/list,这些写操作虽然 maillab 有但**业务上没刚需**;
+   保守做法:不实现,只在 `MaillabClient` 留接口骨架。
+3. **附件支持**(`/email/attList`)— ChatGPT 邀请邮件**没有附件**,此功能与 AutoTeam 无关;暂不集成。
+4. **`/email/send`** — AutoTeam 不需要发邮件(只读验证码),不集成;但用户在 maillab 控制台已经能用,文档可以不提。
+5. **`/oauth/linuxdo/*`** — 未来如果 AutoTeam 想让"管理员通过 LinuxDo OAuth 绑定 maillab 账户"自动获取 token,
+   需要扩展。当前**不在范围**,但 setup_wizard 应当探测到 linuxdoSwitch=true 时给个 hint。
+6. **多 maillab 实例**?当前 AutoTeam 只支持一个 base_url;skymail.ink 用户可能有 prod / staging 两套。
+   是否做多实例切换?**保守:不做**,留给 PRD 阶段权衡。
+7. **register-domain 探测路径与 §C step=domain_ownership 是否合并**?现 `api.py:1631-1673` 已实现一次探测,
+   §C 设计应当把它**重构成共享 helper**,SetupPage 与 Settings 页 register-domain 调同一个底层函数。
+
+---
+
+## 附录 A:本研究查证过的源码 / 文档证据
+
+| 来源                                                                                | 用途                          |
+| ----------------------------------------------------------------------------------- | ----------------------------- |
+| `D:/Desktop/AutoTeam/src/autoteam/cloudmail.py`                                     | 确认 stub re-export           |
+| `D:/Desktop/AutoTeam/src/autoteam/mail/__init__.py`                                 | 确认工厂分发                  |
+| `D:/Desktop/AutoTeam/src/autoteam/mail/base.py`                                     | 确认 ABC 公开方法集            |
+| `D:/Desktop/AutoTeam/src/autoteam/mail/cf_temp_email.py`                            | 确认 cf 实现 + 嗅探条件        |
+| `D:/Desktop/AutoTeam/src/autoteam/mail/maillab.py`                                  | 确认 maillab 实现 + 已知 TODO  |
+| `D:/Desktop/AutoTeam/src/autoteam/setup_wizard.py`                                  | 确认 _verify_cloudmail / 嗅探 |
+| `D:/Desktop/AutoTeam/src/autoteam/api.py:70-149`                                    | 确认 SetupConfig 缺 maillab 字段|
+| `D:/Desktop/AutoTeam/src/autoteam/api.py:1617-1673`                                 | 确认 register-domain 探测     |
+| `D:/Desktop/AutoTeam/src/autoteam/runtime_config.py`                                | 确认 register_domain 持久化    |
+| `D:/Desktop/AutoTeam/web/src/components/SetupPage.vue`                              | 确认 UI 是平铺字段表单         |
+| `D:/Desktop/AutoTeam/web/src/components/Settings.vue`                               | 确认无 mail provider 切换 UI   |
+| `D:/Desktop/AutoTeam/web/src/api.js`                                                | 确认前后端契约                 |
+| `D:/Desktop/AutoTeam/.env` / `.env.example`                                         | 确认配置项现状                 |
+| `D:/Desktop/AutoTeam/docs/mail-provider-design.md`                                  | 确认设计文档与已知未知项       |
+| `https://doc.skymail.ink/api/api-doc.html`                                          | 确认对外公布的 3 个 public API|
+| `https://github.com/maillab/cloud-mail/blob/main/mail-worker/src/api/login-api.js`  | 确认 /login /register /logout |
+| `https://github.com/maillab/cloud-mail/blob/main/mail-worker/src/api/account-api.js`| 确认 /account/* 6 路由        |
+| `https://github.com/maillab/cloud-mail/blob/main/mail-worker/src/api/email-api.js`  | 确认 /email/* 6 路由          |
+| `https://github.com/maillab/cloud-mail/blob/main/mail-worker/src/api/setting-api.js`| 确认 /setting/* 5 路由        |
+| `https://github.com/maillab/cloud-mail/blob/main/mail-worker/src/api/init-api.js`   | 确认 /init/:secret            |
+| `https://github.com/maillab/cloud-mail/blob/main/mail-worker/src/api/user-api.js`   | 确认 /user/* 10 路由           |
+| `https://github.com/maillab/cloud-mail/blob/main/mail-worker/src/api/role-api.js`   | 确认 /role/* 7 路由            |
+| `https://github.com/maillab/cloud-mail/blob/main/mail-worker/src/api/all-email-api.js`| 确认 /allEmail/* 4 路由      |
+| `https://github.com/maillab/cloud-mail/blob/main/mail-worker/src/api/reg-key-api.js`| 确认 /regKey/* 5 路由          |
+| `https://github.com/maillab/cloud-mail/blob/main/mail-worker/src/api/public-api.js` | 确认 /public/* 3 路由          |
+| `https://github.com/maillab/cloud-mail/blob/main/mail-worker/src/security/security.js` | 确认白名单 + 鉴权流程       |
+| `https://github.com/maillab/cloud-mail/blob/main/mail-worker/src/service/setting-service.js` | 确认 websiteConfig 字段集 |
+| `https://github.com/maillab/cloud-mail/blob/main/mail-worker/src/service/public-service.js`  | 确认 genToken 仅 admin 可调|
+
+## 附录 B:本研究**未**进行的事项(留给 PRD/spec/test_reports)
+
+- 没有改任何源代码(按任务要求,纯调研)
+- 没有联系 skymail.ink 官方确认 v2.8.0 之外的版本兼容性
+- 没有在真实 maillab 实例上跑 e2e 测试(`mail-provider-design.md` §6 提示 implementer 必须做)
+- 没有提供 §C "新增 `/api/mail-provider/probe` 端点" 的具体 Pydantic 模型 / 单元测试用例(spec 阶段产出)
+- 没有提供前端 SetupPage.vue 改造的具体 diff(test_reports 阶段产出)

prompts/0426/research/issue-2-seat-strategy.md

@@ -0,0 +1,182 @@
+# Issue#2 — 席位策略与套餐 / 免费号删除 研究报告
+
+## A. 用户报告解构
+
+用户提出 4 条诉求:
+
+1. **默认走 codex 席位**:目前生成免费号 / Team 邀请号默认拿"完整 ChatGPT 席位",用户希望默认只占 codex 席位(让 ChatGPT 主席位留给真人/管理员)。
+2. **免费号无法移除**:被标记为 personal(已退出 Team 走个人 free OAuth)的子号,从 UI 上点删除/批量删除拿不到结果。
+3. **`self_serve_business_usage_based` 套餐识别**:OpenAI 在某些 workspace 下把 `chatgpt_plan_type` 标成这种新值,目前代码只匹配 `team` / `free`,其它一律走 fallback 分支,实际效果是"号能注册成功但 Codex 不可用"。
+4. **席位策略可配置**:相比写死 default 邀请,用户希望管理员可以选择策略。
+
+## B. 代码现状
+
+### B.1 关键符号清单
+
+| 文件:行号 | 签名/常量 | 作用 |
+|---|---|---|
+| `src/autoteam/accounts.py:23-25` | `SEAT_CHATGPT="chatgpt"` / `SEAT_CODEX="codex"` / `SEAT_UNKNOWN="unknown"` | 落盘到 `accounts.json` 的 `seat_type` 字段 |
+| `src/autoteam/accounts.py:58` | `add_account(email, password, cloudmail_account_id=None, seat_type=SEAT_UNKNOWN, workspace_account_id=None)` | 默认 SEAT_UNKNOWN,邀请/注册流程会显式覆盖 |
+| `src/autoteam/invite.py:39-44` | `_seat_label_from_raw(raw_seat)` | 把 ChatGPT API 返回的 `_seat_type` 字面量(`chatgpt` / `usage_based` / `unknown`)翻译成 `SEAT_*` 常量 |
+| `src/autoteam/invite.py:496` | `chatgpt.invite_member(email, seat_type="default")` | **默认邀请入口写死 default(完整 ChatGPT 席位)** |
+| `src/autoteam/chatgpt_api.py:1365-1411` | `invite_member(email, seat_type="usage_based")` + `_invite_member_with_fallback` | 自带 default → usage_based 兜底,只翻一次 |
+| `src/autoteam/chatgpt_api.py:1414-1511` | `_invite_member_once(email, seat_type)` | POST /invites + POST 200 后 PATCH 升级到 default |
+| `src/autoteam/chatgpt_api.py:1487-1510` | `data["_seat_type"] = "usage_based" / "chatgpt"` 写入 | usage_based 入口 + PATCH 全失败 → 标 SEAT_CODEX;default 入口 + 200 → 直接标 SEAT_CHATGPT |
+| `src/autoteam/manual_account.py:233-237` | `seat_label = "chatgpt" if plan_type == "team" else "codex"` | 手动添加(用户粘贴 OAuth 回调)按 plan_type 反推 seat_type |
+| `src/autoteam/manager.py:1463-1486` | `_run_post_register_oauth` 收尾段 | `seat_label = "chatgpt" if bundle_plan == "team" else "codex"` |
+| `src/autoteam/codex_auth.py:111` | `bundle["plan_type"] = auth_claims.get("chatgpt_plan_type", "unknown")` | id_token JWT 直接提取,任何新值都会原样落盘 |
+| `src/autoteam/cpa_sync.py:132-140` | plan_type 推断回退链 | 当 bundle 缺失时根据文件名 `-team-` / `-plus-` / `-free-` 反推 |
+| `src/autoteam/api.py:1268-1303` | `DELETE /api/accounts/{email}` | 单点删除 |
+| `src/autoteam/api.py:1306-1404` | `POST /api/accounts/delete-batch` | 批量删除 |
+| `src/autoteam/account_ops.py:40-162` | `delete_managed_account(email, ...)` | 实际执行器:Team 远端删 + 本地 auth_file + cpa + cloudmail |
+| `web/src/components/Dashboard.vue:133-142` | 删除按钮 `v-if="!acc.is_main_account"` | 只屏蔽主号,personal/standby/auth_invalid 都渲染 |
+
+### B.2 调用链/数据流
+
+#### 邀请席位决策链(用户 → `accounts.json`)
+
+```
+invite.run() / cmd_fill_team
+    └─ ChatGPTTeamAPI.invite_member(email, seat_type="default")    ← 入口写死
+        └─ _invite_member_with_fallback(seat_type="default", allow_fallback=True)
+            ├─ _invite_member_once("default") → POST /invites
+            │   └─ 200 + 无 errored → data["_seat_type"]="chatgpt"      ← 完整 ChatGPT 席位
+            │   └─ 200 + errored / 非 200 → 触发兜底
+            └─ _invite_member_with_fallback(seat_type="usage_based", allow_fallback=False)
+                └─ _invite_member_once("usage_based")
+                    ├─ POST /invites 拿 invite_id 列表
+                    └─ 对每个 invite_id PATCH seat_type="default"
+                        ├─ 全失败 → data["_seat_type"]="usage_based"    ← SEAT_CODEX
+                        └─ 任意成功 → data["_seat_type"]="chatgpt"
+    ↓
+invite.run() 用 _seat_label_from_raw() 转成 SEAT_* 常量
+    └─ add_account(..., seat_type=seat_label, ...)   ← 落盘
+```
+
+**关键观察**:目前的 fallback 是**单向的"先升级,失败保留 codex"**,根本不存在"从一开始就只要 codex 席位、不尝试 PATCH"的入口。`chatgpt_api.py:1487-1499` 在 seat_type=="usage_based" 的分支里**永远**会调 `_update_invite_seat_type(invite_id, "default")` 试图升级。
+
+#### 注册后回写席位的链(plan_type → seat_type)
+
+```
+_run_post_register_oauth (manager.py:1463)
+    └─ login_codex_via_browser → 拿 bundle (含 plan_type)
+        └─ bundle.plan_type == "team"   → seat_label="chatgpt"
+        └─ bundle.plan_type ∈ {free,plus,unknown,self_serve_*,...} → seat_label="codex"
+            ↑ 这里决定的 seat_type 与 invite 阶段决定的 seat_type 可能不一致,
+              update_account 会覆写 invite 阶段的值。
+```
+
+#### 删除 personal 子号链
+
+```
+DELETE /api/accounts/{email}                                   (api.py:1268)
+    └─ acquire _playwright_lock (BLOCKING_FALSE)
+        └─ _pw_executor.run(delete_managed_account, email)
+            └─ delete_managed_account(email, remove_remote=True) (account_ops.py:40)
+                └─ if remote_state is None:
+                    └─ ChatGPTTeamAPI().start()                ← 主号 session 失效 → 抛
+                    └─ fetch_team_state() 获取 members + invites
+                ├─ member_matches = []  (personal 不在 Team)
+                ├─ invite_matches = []
+                ├─ 删本地 auth_file (codex-{email}-*.json)
+                ├─ 删 CPA 文件
+                ├─ 删本地 accounts.json 记录
+                └─ 删 CloudMail 邮箱
+```
+
+## C. 根因分析
+
+### C.1 "默认走 codex 席位"无法直接配置
+
+**优先级 P0** — 缺乏配置开关。`invite.py:496` 的 `seat_type="default"` 是一行硬编码,且 `_invite_member_once` 在 usage_based 路径里**永远**会试图 PATCH 升级到 default(line 1498),即便管理员手动改 invite.py 入口为 `usage_based`,实际效果也是"先 usage_based 占席,再 PATCH 抢 ChatGPT 席位",而不是"只占 codex 席位"。
+
+候选根因(按可能性排序):
+1. **设计选择问题**:历史上 default 升级是为了让 ChatGPT 主席位用尽时仍能拿到 codex,作者把 fallback 写死成单向。
+2. **缺少 runtime_config 字段**:对照 `runtime_config.py` / `config.py` 是否有 `PREFERRED_SEAT_TYPE` 的 hint,目前没有。
+3. **PATCH 升级是无条件的**:`_invite_member_once` line 1489-1506 完全没有 opt-out。
+
+### C.2 "免费号无法移除"
+
+**优先级 P1** — 多个候选互相叠加:
+
+候选根因(按可能性排序):
+1. **`actionDisabled` 锁死按钮(P1 主犯)**:`Dashboard.vue:330` 的 `actionDisabled = !!props.runningTask || !adminReady.value`。如果用户**没登录主号**或**有任何任务在跑**,删除按钮会变灰失能。用户测试过程中很可能正在跑 fill 任务 / 主号 session 已过期但 UI 没及时刷新 `adminReady`。
+2. **批量删除强依赖主号 session**:`api.py:1349-1354` 即便要删的全是 personal 子号(都不在 Team),也强制 `ChatGPTTeamAPI().start()` + `fetch_team_state()`。主号 session 失效时整批 500,没有"全为 personal 时跳过 Team 拉取"的优化。
+3. **后端 _playwright_lock 409**:`api.py:1271-1283` 一旦 `_playwright_lock.acquire(blocking=False)` 失败就 409,前端表现为"点击没反应",但有 message 弹窗。
+4. **CPA 文件名错位导致清理不彻底**:`account_ops.py:120` 用 `AUTH_DIR.glob(f"codex-{email}-*.json")`,但 personal 号是 `codex-{email}-free-*.json`,glob 能命中。然后 `cpa_sync.list_cpa_files / delete_from_cpa` 是按 name + email 双 key 删除,personal 号文件名是 free-,理论上能匹配。这一支不是主因,但需要在测试时确认。
+5. **不是真删失败,而是 UI 不刷新**:删除完成后没有触发账号列表 reload(检查 Dashboard.vue 的 `removeAccount` 方法,line 568-584 region)。
+
+### C.3 `self_serve_business_usage_based` 套餐处理
+
+**优先级 P0** — 完全无识别。
+
+候选根因:
+1. **plan_type 检查只匹配 "team"**:`manual_account.py:234`、`manager.py:1468`、`manager.py:2490` 都是 `if plan_type == "team": ... else: codex / standby / 拒绝复用`。`self_serve_business_usage_based` 全部落入 else 分支,被标 SEAT_CODEX,但**实际上**这种 plan 的 workspace 根本没有 codex 配额。
+2. **wham/usage 不能区分 quota=0 与 quota=正常**:`codex_auth.py:1582` 用 `primary_pct >= 100` 判定耗尽,`self_serve_business_usage_based` 这种新计费 workspace 实际返回的可能是 `used_percent=0` + `total=0` —— 后者无法表达,代码当作 ok + 显示 100% 剩余。这就是用户报告"不显示额度的那种,实际也没额度,调用什么都是 429 没额度"的根因。
+3. **`reinvite_account` 直接判 plan_type != "team" 失败回收(manager.py:2490)**:任何 self_serve_* plan 一进来就被 `_cleanup_team_leftover` 踢回 standby — 死循环。
+
+## D. 修复方向建议(只是方向,不写代码)
+
+### D.1 必须改的点
+
+1. **加 PREFERRED_SEAT_TYPE 配置开关**(P0)
+   - 位置:`runtime_config.py` + Web Settings 页
+   - 取值:`chatgpt`(默认升级,保留现行) / `codex`(默认 usage_based 不升级)
+   - 改动点:
+     - `invite.py:496` 改成读 config 的 `PREFERRED_SEAT_TYPE`,映射到 `seat_type=` 入参
+     - `chatgpt_api.py:1487-1506` 在 usage_based 分支里,只有 `PREFERRED_SEAT_TYPE=="chatgpt"` 时才执行 PATCH 升级,反之直接保留 usage_based
+     - `_invite_member_with_fallback` 的兜底也要读 config:codex 偏好下,default → usage_based 兜底改成"default 直接失败不再尝试 usage_based"或反��
+
+2. **识别异常 plan_type**(P0)
+   - 位置:`codex_auth.py` 在 `_exchange_auth_code` 拿 bundle 后,新增一个常量集 `SUPPORTED_PLAN_TYPES = {"team", "free", "plus", "pro"}`
+   - 任何不在白名单的 plan(如 `self_serve_business_usage_based`)直接日志告警 + bundle["plan_type_unsupported"]=True
+   - 下游 `_run_post_register_oauth` / `manual_account._finalize_account` 看到 unsupported 标记时,选项:a) 拒绝接收 bundle(类似 codex_auth.py:920-930 的 personal 模式校验),b) 接收但标 STATUS_AUTH_INVALID + 在 UI 显示"不支持的套餐"
+
+3. **wham/usage 增强:识别 quota 总额=0**(P0)
+   - 位置:`codex_auth.py:1685-1700`
+   - 解析 `rate_limit.primary_window` 时,除了 `used_percent` 也读 `limit` / `total`(如果接口返回了)
+   - 总额=0 或 reset_at=0 → 直接归为 "exhausted" 或新增 "no_quota"
+   - 上游标 STATUS_EXHAUSTED + 写一个明确的 quota_info `{"reason": "no_quota_assigned"}`,UI 显示"无配额"而不是"100% 剩余"
+
+4. **personal 删除链解耦主号 session**(P1)
+   - 位置:`account_ops.py:73-84`
+   - 检查 acc.status:如果是 STATUS_PERSONAL / STATUS_AUTH_INVALID(确认不在 Team),跳过 `fetch_team_state()`,直接删本地资源
+   - 单点和批量入口都加这个 short-circuit
+   - `api.py:1306-1404` 批量删除前先扫一遍状态,如果全是 personal,完全不起 ChatGPTTeamAPI
+
+5. **UI 删除失败需要明确 toast**(P1)
+   - 位置:`Dashboard.vue:566-585`(removeAccount)
+   - 失败原因(actionDisabled / 409 / 500)需要 message.value 不同提示,避免"按钮没反应"误解
+   - 删除成功后立即 `emit('refresh')` 触发账号列表 reload
+
+### D.2 可选优化
+
+1. **invite_member 加 dry_run 预览**:管理员可以在 web 上看 default vs usage_based 的预期结果。
+2. **seat_type 漂移检测**:`_reconcile_team_members` 第二轮里,检查每个成员的实际 seat_type 是否与本地 `accounts.json` 一致(GET /users 返回的成员对象有 seat_type 字段),漂移就告警。
+3. **plan_type=self_serve_business 转 personal 模式**:既然这种 plan workspace 没 codex 配额,直接用 `_run_post_register_oauth(leave_workspace=True)` 走 personal 流程能不能拿到 free plan?需要实际测试。
+4. **删除批量:全 personal 时不需要 fetch_team_state**:跳过整个 ChatGPTTeamAPI 启动,加速删除。
+
+### D.3 测试要点
+
+- [ ] PREFERRED_SEAT_TYPE=codex 时,invite 流程返回的 seat_type 应该稳定=usage_based,且 PATCH 不被调用(看日志中 `修改邀请 seat_type` 是否出现)
+- [ ] PREFERRED_SEAT_TYPE=chatgpt 保持现有行为不变(回归测试)
+- [ ] 注册一个 self_serve_business_usage_based workspace 子号(可以临时用一个商用 workspace),确认 codex_auth.py 拒绝接收 bundle / 标 unsupported
+- [ ] 创建一个 personal 子号(`fill-personal`),用 web UI 删除按钮,确认按钮可点 + 删除成功 + 列表刷新
+- [ ] 批量删除 5 个 personal 子号,主号 session 故意先注销,确认不报 ChatGPTTeamAPI 启动失败
+- [ ] wham/usage 返回 used_percent=0 但实际无配额的场景:本地是否能正确显示"无配额"
+
+## E. 影响面 / 爆炸半径
+
+- **PREFERRED_SEAT_TYPE 配置改动**:扩散到 `invite.py`、`chatgpt_api.py`、`runtime_config.py`、`web/Settings.vue`,4 个文件;最大风险是 fallback 链向后兼容(老的 default 入口 + PATCH 行为是否仍可用作"失败兜底")。需要对 `_invite_member_with_fallback` 做 unit test。
+- **plan_type 白名单**:扩散到 `codex_auth.py` + `manual_account.py` + `manager.py`(_run_post_register_oauth、reinvite_account)+ `api.py`(login),5 个文件。注意 `cpa_sync.py:132-140` 的回退链不能漏改。
+- **wham/usage 解析增强**:只动 `codex_auth.py:check_codex_quota / get_quota_exhausted_info`,影响所有调用方(manager / api 多处)的 status_str 分类,需要确认 "no_quota" 不会被误归 "auth_error"。
+- **personal 删除短路**:只动 `account_ops.py` + `api.py:delete_accounts_batch`,不会影响 active 子号删除链。
+- **UI toast 改动**:仅 Dashboard.vue,无后端影响。
+
+## F. 风险与未决问题
+
+1. **`self_serve_business_usage_based` 是否真的存在**:用户报告中提及,但 OpenAI 公开 API 文档没有这个值。需要从用户实际 bundle 取证(`auths/codex-*.json` 中 plan_type 字段)确认字面量,可能是 `chatgpt_business_usage_based` 或 `self_serve_team` 之类变体。
+2. **PATCH 升级失败的统计**:目前 chatgpt_api.py:1503 只 log error,没有 metric。改默认策略前应该先看真实失败率 — 如果失败率 <5%,默认 ChatGPT 升级是合理的;如果 >30%,默认 codex 才合理。
+3. **删除按钮 actionDisabled 是否有副作用**:adminReady=false 时禁删除是安全设计(避免 fetch_team_state 起 chatgpt_api 失败),不能简单去掉。修复方向应是"personal 子号不依赖 adminReady"。
+4. **plan_type 白名单是否需要兼容大写**:`codex_auth.py:111` 直接读 JWT claim,OpenAI 后端可能某些版本返回大写 `Team`。所有判定建议 `.lower()` 后再比。
+5. **如果用户希望"全部用 codex 席位"**,主号 ChatGPT 席位会闲置吗?需要确认主号的 codex 配额来自哪里(似乎来自主号本身的 ChatGPT 主席位,不需要 PATCH)。

prompts/0426/research/issue-3-list-accounts-import.md

@@ -0,0 +1,292 @@
+# Issue#3 list_accounts ImportError 全量扫荡
+
+> 调研时间:2026-04-26
+> 调研范围:整个 AutoTeam 仓库 + Dockerfile / docker-compose / docker-entrypoint
+> 结论:**源代码已干净 — docker 镜像未重建是 100% 真因**
+
+---
+
+## A. 当前 accounts.py 真实导出
+
+文件路径:`D:/Desktop/AutoTeam/src/autoteam/accounts.py`
+
+**accounts.py 没有 `__all__`**,所以"导出"以模块顶层 `def`/常量为准:
+
+| 类别 | 名称 |
+|---|---|
+| **状态常量** | `STATUS_ACTIVE` / `STATUS_EXHAUSTED` / `STATUS_STANDBY` / `STATUS_PENDING` / `STATUS_PERSONAL` / `STATUS_AUTH_INVALID` / `STATUS_ORPHAN` |
+| **席位常量** | `SEAT_CHATGPT` / `SEAT_CODEX` / `SEAT_UNKNOWN` |
+| **路径常量** | `PROJECT_ROOT` / `ACCOUNTS_FILE` |
+| **私有辅助** | `_normalized_email` / `_is_main_account_email` |
+| **核心 IO 函数** | `load_accounts` ← (line 36) |
+| | `save_accounts` (line 45) |
+| **业务函数** | `find_account` / `add_account` / `update_account` / `delete_account` |
+| **筛选函数** | `get_active_accounts` / `get_personal_accounts` / `get_standby_accounts` / `get_next_reusable_account` |
+
+**关键判定**:
+- 模块**从未定义** `def list_accounts`
+- 模块**从未定义** `list_accounts = load_accounts` 别名
+- `accounts.py` 在 git 历史里也从未有过这个名字 — `list_accounts` 是 `api.py` 那处 typo 凭空引入的不存在符号
+
+---
+
+## B. 全项目 list_accounts 引用清单
+
+> 命令:`grep -rn "list_accounts" D:/Desktop/AutoTeam`
+
+### B.1 与"账号池(autoteam.accounts)"相关的引用 — **0 处**
+
+```bash
+$ grep -rn "from autoteam.accounts import.*list_accounts" D:/Desktop/AutoTeam
+# (0 行,完全干净)
+
+$ grep -rn "accounts\.list_accounts" D:/Desktop/AutoTeam/src
+# (0 行,完全干净)
+```
+
+✅ commit cf2f7d3 之后,**autoteam.accounts 这一侧的 list_accounts 引用已清零**。
+
+### B.2 残留的 list_accounts 引用全部归属"邮箱 provider 子系统",与 issue 无关
+
+| 文件 | 行号 | 上下文 | 是否 bug |
+|---|---|---|---|
+| `docs/mail-provider-design.md` | 68, 308 | 设计文档:邮箱 provider 抽象 `def list_accounts(self, size: int = 200)` | ❌ 无关(文档) |
+| `src/autoteam/mail/base.py` | 177 | 邮箱 provider 抽象基类的方法签名 `def list_accounts(self, size: int = 200) -> list[dict]` | ❌ 无关(`MailProvider` 类方法) |
+| `src/autoteam/mail/cf_temp_email.py` | 190 | `CfTempEmailClient.list_accounts(self, size=200)` | ❌ 无关(provider 实现) |
+| `src/autoteam/mail/maillab.py` | 219 | `MaillabClient.list_accounts(self, size: int = 200)` | ❌ 无关(provider 实现) |
+| `src/autoteam/mail/maillab.py` | 309, 322 | `for row in self.list_accounts(size=500)` 内部调用 | ❌ 无关 |
+| `tests/unit/test_maillab.py` | 216, 236, 240, 253, 258, 279 | 测试 maillab provider 的 `list_accounts` 翻页/截断行为 | ❌ 无关(测试) |
+| `CHANGELOG.md` | 11, 134 | 历史记录条目(本 issue 修复说明 + 旧版 maillab.list_accounts 上限补丁) | ❌ 无关(文档) |
+| `prompts/issues1.md` | 77, 78 | 用户报告的报错原文 | ❌ 无关(报告) |
+
+**结论**:`list_accounts` 这个名字在仓库里**只剩"邮箱 provider 的方法名"** — 跟 `autoteam.accounts` 模块没有任何 import 关系,**不会被 Python 解释器拿来跟 accounts 模块对接**。
+
+### B.3 commit cf2f7d3 之前的现场还原(供对照)
+
+`api.py:1942` 历史代码:
+```python
+# 修复前(已是历史)
+from autoteam.accounts import STATUS_ACTIVE, STATUS_EXHAUSTED, list_accounts
+                                                              ^^^^^^^^^^^^^
+                                                              # ← 这里就是 typo
+
+in_team_local = sum(1 for a in list_accounts() if a.get("status") in ...)
+```
+
+`api.py:1944` 当前代码(已修):
+```python
+from autoteam.accounts import STATUS_ACTIVE, STATUS_EXHAUSTED, load_accounts
+in_team_local = sum(1 for a in load_accounts() if a.get("status") in ...)
+```
+
+git log 里 `cf2f7d3 fix(round-3)` 第一条就是这条修复,文件指纹一致。
+
+---
+
+## C. Docker 镜像 / 挂载现状
+
+### C.1 Dockerfile 关键事实
+
+```dockerfile
+# 第 23-25 行
+COPY src/ src/
+COPY web/ web/
+```
+
+**源代码是 `COPY` 进镜像的 — 不是 volume 挂载**。
+
+### C.2 docker-compose.yml 挂载策略
+
+```yaml
+volumes:
+  - ./data:/app/data    # 仅挂数据目录
+```
+
+**没有挂 `./src:/app/src`** — 也就是说源代码改动**必须 rebuild image** 才会进入容器。
+
+### C.3 docker-entrypoint.sh 软链规则
+
+入口脚本只把 `/app/data/{.env, accounts.json, state.json, auths/, screenshots/}` 软链到工作目录,**不动源码**:
+```bash
+for f in .env accounts.json state.json; do
+    [ -f "/app/data/$f" ] || touch "/app/data/$f"
+    rm -f "/app/$f"
+    ln -s "/app/data/$f" "/app/$f"
+done
+```
+
+`/app/src/autoteam/api.py` 是 `COPY` 时刻被烤进镜像的快照,不会随宿主机文件变动。
+
+### C.4 推断:用户的 docker 镜像还是旧版
+
+既然 commit cf2f7d3 已��� git,但 11:04 容器内还在报同样的 `ImportError: cannot import name 'list_accounts' from 'autoteam.accounts'`,只剩三种可能:
+
+1. **(99%)镜像未重建** — 源码改了,`docker build` 没重跑
+2. **(<1%)镜像已建但容器未替换** — 老 container 没 stop/restart
+3. **(0%)有别处也写了 typo** — 已经 grep 全仓库扫干净,不存在
+
+---
+
+## D. 推荐修复方案
+
+### 方案 A:仅 docker rebuild(对应 99% 真因)
+
+```bash
+cd D:/Desktop/AutoTeam
+
+# 1. 确认源码确实是新版
+git log --oneline src/autoteam/api.py | head -3
+git diff cf2f7d3~1 cf2f7d3 -- src/autoteam/api.py | head -20
+
+# 2. 停掉旧容器
+docker compose down
+
+# 3. 强制重建镜像(--no-cache 防意外缓存命中)
+docker compose build --no-cache autoteam
+
+# 4. 重新启动
+docker compose up -d
+
+# 5. 进容器验证
+docker compose exec autoteam python -c "from autoteam.accounts import load_accounts; print('OK', len(load_accounts()))"
+
+# 6. 也可以同时确认 typo 已不在镜像里
+docker compose exec autoteam grep -n "list_accounts" /app/src/autoteam/api.py || echo "干净"
+```
+
+**预期**:第 5 步打印 `OK <n>`,第 6 步打印 `干净`。
+
+### 方案 B:在 accounts.py 加 `list_accounts = load_accounts` 别名(防御层 / 不推荐)
+
+```python
+# src/autoteam/accounts.py 末尾追加
+list_accounts = load_accounts  # 向后兼容,允许 typo 不炸
+```
+
+**评估**:
+- 优点:即便有人重新写错也不会 ImportError
+- 缺点:**掩盖 typo,长期维护更糟** — 团队不知道哪个名字才是规范的;静态分析工具看到两个绑定也会困惑
+- **不推荐**:typo 应该让 lint / CI 抓住,而不是用别名兜底
+
+### 方案 C:CI / pre-commit 防回归(强烈推荐组合)
+
+虽然这条 issue 当前位点没残留 typo,但同类 typo 容易复发(`list_accounts` 写起来比 `load_accounts` 更顺手)。建议在 `ruff.toml` 或 pre-commit 增加一条 grep 守卫:
+
+```bash
+# scripts/lint-no-list-accounts.sh
+#!/usr/bin/env bash
+set -e
+if grep -rn "from autoteam\.accounts import.*list_accounts\b" src tests; then
+    echo "Found typo: list_accounts (use load_accounts)"
+    exit 1
+fi
+if grep -rn "autoteam\.accounts\.list_accounts\b" src tests; then
+    echo "Found typo: autoteam.accounts.list_accounts (use load_accounts)"
+    exit 1
+fi
+echo "no list_accounts typo"
+```
+
+接到 pre-commit / CI:任何人再写错立刻拒绝 commit。
+
+### 方案对比
+
+| 方案 | 解决根因 | 落地成本 | 推荐度 |
+|---|---|---|---|
+| **A** docker rebuild | ✅ 完全解决当前 issue | 低(2 条命令) | ★★★★★ **必须做** |
+| **B** 别名兜底 | ❌ 治标不治本 | 极低 | ★ 不推荐 |
+| **C** lint 防回归 | ✅ 防未来同类 typo | 低(1 个 shell) | ★★★★ **推荐配套** |
+
+**建议组合**:**A + C** — 立刻把镜像重建,同时埋一道 lint 防线。
+
+---
+
+## E. 防回归测试要点
+
+### E.1 单元测试层
+
+确认 api.py 里所有 `from autoteam.accounts import ...` 路径都不再误用 `list_accounts`:
+
+```python
+# tests/unit/test_no_list_accounts_typo.py
+import re
+from pathlib import Path
+
+SRC = Path(__file__).parent.parent.parent / "src"
+
+def test_no_list_accounts_in_accounts_namespace():
+    """list_accounts 是 mail provider 的方法名,不应在 autoteam.accounts 命名空间出现"""
+    pattern = re.compile(
+        r"from\s+autoteam\.accounts\s+import[^#\n]*\blist_accounts\b"
+        r"|autoteam\.accounts\.list_accounts\b"
+    )
+    bad = []
+    for p in SRC.rglob("*.py"):
+        text = p.read_text(encoding="utf-8")
+        for i, line in enumerate(text.splitlines(), 1):
+            if pattern.search(line):
+                bad.append(f"{p}:{i}: {line.strip()}")
+    assert not bad, "list_accounts typo:\n" + "\n".join(bad)
+```
+
+### E.2 集成测试层
+
+加一条对"生成免费号"按钮(`POST /api/tasks/fill {leave_workspace: true}`)的最小冒烟:
+
+```python
+# tests/integration/test_post_fill_no_import_error.py
+def test_post_fill_personal_does_not_raise_import_error(client, monkeypatch):
+    # 桩掉 cmd_fill 避免真的开 Playwright,只校验 import 阶段不炸
+    from autoteam import manager
+    monkeypatch.setattr(manager, "cmd_fill", lambda **kw: [])
+    monkeypatch.setattr(manager, "TEAM_SUB_ACCOUNT_HARD_CAP", 999)
+
+    resp = client.post("/api/tasks/fill", json={"leave_workspace": True})
+    # 关键:不能是 500(ImportError 会变 500)
+    assert resp.status_code in (202, 409)
+```
+
+### E.3 部署测试层
+
+`docker-entrypoint.sh` 启动末端加一行 self-check,把 typo 扼杀在容器启动期:
+
+```bash
+# 末尾追加
+python -c "from autoteam.accounts import load_accounts" || {
+    echo "FATAL: autoteam.accounts.load_accounts import failed"
+    exit 1
+}
+
+exec uv run autoteam "$@"
+```
+
+如此一来:任何 typo 类 ImportError 在 `docker compose up` 时就**立刻 crash-loop**,不会再让用户在 Web 面板按按钮才发现。
+
+### E.4 镜像版本指纹
+
+建议在 Dockerfile 加一行 `LABEL org.opencontainers.image.revision=<git-sha>`,便于排查"当前镜像到底是哪个 commit":
+
+```dockerfile
+ARG GIT_SHA=unknown
+LABEL org.opencontainers.image.revision=$GIT_SHA
+ENV AUTOTEAM_GIT_SHA=$GIT_SHA
+```
+
+构建命令:
+```bash
+docker compose build --build-arg GIT_SHA=$(git rev-parse --short HEAD)
+```
+
+容器内可通过 `echo $AUTOTEAM_GIT_SHA` 立即知道是哪个 commit 烤的镜像 — 这次 issue#3 排错时就能直接看到镜像 SHA 是不是 cf2f7d3 之前的版本。
+
+---
+
+## 总结
+
+| 维度 | 结论 |
+|---|---|
+| 源代码层是否还残留 typo? | ❌ 不残留(commit cf2f7d3 已修干净) |
+| 是否需要在 accounts.py 加别名? | ❌ 不需要(掩盖 typo,反而坏事) |
+| 真因? | **Docker 镜像未重建** — 用户 11:04 看到的容器还在跑旧 image |
+| 立刻该做? | `docker compose down && docker compose build --no-cache && docker compose up -d` |
+| 长期该做? | 加 lint 守卫 + entrypoint 启动期 self-check + 镜像 git-sha 标签 |

prompts/0426/research/issue-4-oauth-addphone.md

@@ -0,0 +1,416 @@
+# Issue#4 OAuth 凭证获取失败 + 再次登录爆 add phone — 研究报告
+
+> 作者:claude(OAuth/SSO 流程调研工程师) · 时间:2026-04-26
+>
+> 用户原话:"修复在使用中报错经常出现的:免费号凭证无法通过OAuth获取,再次登录时爆add phone的问题——不要脱离原本的流程太多"
+>
+> **本报告只调研、不改代码**。所有结论以代码事实为准,引用形式 `path:line` 全部经过 Read/Grep 校验。
+
+---
+
+## TL;DR(给开看的人)
+
+1. **现象一(凭证获取不到)** = `login_codex_via_browser` 末尾 `if not auth_code: return None` 静默失败。callback 没回来的根因被吞掉(超时 / consent 循环卡死 / **未识别的 add-phone 阻塞页**),上层只能写 `oauth_failed`。
+2. **现象二(再次登录爆 add phone)** = OAuth 流程中**完全没有** add-phone 检测器。`invite.py:106 detect_phone_verification` 只在新账号注册的 4 个提交节点用,**所有 6 处 `login_codex_via_browser` 调用点(注册成功后 OAuth、生成免费号 personal OAuth、补登录、轮转复用、定点替换、`api.py /api/accounts/login`)都不调用它**。
+3. **最小侵入修复方向**:把 `assert_not_blocked(page, step)` 接进 `codex_auth.py` OAuth 主循环 → 命中 add-phone 时抛 `RegisterBlocked(is_phone=True)` → 上层按"账号需要人工"分类(新增 `STATUS_PHONE_REQUIRED` 或复用 `STATUS_AUTH_INVALID` + register_failures `phone_blocked`)。**不重写 OAuth、不绕 add-phone**,与用户"不要脱离原本流程太多"的硬要求一致。
+4. **与 issue#6 的边界**:#4 覆盖**所有**经过 `login_codex_via_browser` 的入口;#6 是 reinvite_account 这个特定子集的二次表现(踢出后再 OAuth 风控更高)。**修了 #4 的 add-phone 检测器,#6 的"还要手机"会被拦截**,只是分类语义不同(#4 失败时账号刚 kick 出去就直接放弃,#6 失败时账号已经在 Team 占席位需要立即清理)。
+
+---
+
+## A. 当前 OAuth 流程地图
+
+### A.1 关键文件清单
+
+| 文件 | 行数 | 职责 |
+|------|------|------|
+| `src/autoteam/codex_auth.py` | 1728 | **OAuth 主战场** — `login_codex_via_browser`、`login_codex_via_session`、`SessionCodexAuthFlow`、`MainCodexSyncFlow`、`save_auth_file`、`check_codex_quota`、`refresh_access_token` |
+| `src/autoteam/auth_storage.py` | 35 | `auths/` 目录 + 文件权限 0o666 修复 |
+| `src/autoteam/manager.py` | 4137 | 6 处 `login_codex_via_browser` 调用点中的 4 处:`_run_post_register_oauth`(L1431/L1463)、`reinvite_account`(L2466)、`_check_pending_invites`(L1057) |
+| `src/autoteam/api.py` | - | `/api/accounts/login` 单账号 web 触发(L1479) |
+| `src/autoteam/manual_account.py` | 309 | 用户在自己浏览器走 OAuth → 提交回调 URL,本地不开 Playwright,**不会撞 add-phone**(由用户人眼处理) |
+| `src/autoteam/invite.py` | - | `detect_phone_verification`(L106)、`assert_not_blocked`(L138)、`RegisterBlocked`(L53) — **add-phone 检测器只在这里被定义和使用** |
+| `src/autoteam/accounts.py` | 156 | 状态常量 `STATUS_*`、`SEAT_*`,**没有 phone-required 状态** |
+| `src/autoteam/register_failures.py` | 99 | `record_failure(category=...)`,已有 `phone_blocked` 类目但**只在注册阶段触发** |
+
+### A.2 调用链(手工构建,无 gitnexus 索引)
+
+```
+入口层
+├── /api/accounts/login              (api.py:1450 post_account_login)
+├── /api/tasks/fill (leave=False)    (api.py:1933 post_fill → cmd_fill)
+├── /api/tasks/fill (leave=True)     (api.py:1933 post_fill → cmd_fill_personal)
+├── /api/tasks/check                 (manager.py:cmd_check)
+├── /api/tasks/replace               (manager.py:cmd_replace_one)
+└── /api/tasks/rotate                (manager.py:cmd_rotate)
+
+OAuth 中枢
+                              login_codex_via_browser(use_personal=False/True)
+              ┌─────────────────────────┬─────────────────────────┬────────────────────────┐
+              ▼                         ▼                         ▼                        ▼
+  _run_post_register_oauth   _run_post_register_oauth     reinvite_account         /api/accounts/login
+  (L1463 Team)               (L1431 personal)             (L2466 standby 复用)     (api.py:1479)
+              │                         │                         │                        │
+              ▼                         ▼                         ▼                        ▼
+        save_auth_file              save_auth_file           save_auth_file           save_auth_file
+  (codex-{email}-{plan}-{hash}.json)
+              │
+              ▼
+        sync_to_cpa()  (cpa_sync.py 把 auths/ 同步到 CLIProxyAPI)
+```
+
+主号 session 复用:`login_codex_via_session` / `SessionCodexAuthFlow` / `MainCodexSyncFlow` 用主号 `__Secure-next-auth.session-token` 注 cookie 直跳 `auth_url`,**也不检测 add-phone**(主号通常已绑定手机,但极端场景仍可能触发)。
+
+### A.3 凭证文件路径与生命周期
+
+```
+auths/                                       (PROJECT_ROOT/auths,bind mount 到 docker 容器)
+├── codex-{email}-{team|free|plus}-{8 字节 md5}.json
+└── codex-main-{account_id}.json             (主号专用,不进 accounts.json)
+
+文件结构(_write_auth_file @ codex_auth.py:119):
+{
+  "type": "codex",
+  "id_token": "...",
+  "access_token": "...",
+  "refresh_token": "...",
+  "account_id": "...",
+  "email": "...",
+  "expired": "ISO8601",
+  "last_refresh": "ISO8601"
+}
+
+权限:0o666(docker 容器写,宿主机用户读写,见 auth_storage.py:9)
+
+生命周期:
+1. login_codex_via_browser → _exchange_auth_code → 拿到 bundle
+2. save_auth_file(bundle) → 删同 email 旧文件 → 写新文件
+3. update_account(email, auth_file=路径)
+4. sync_to_cpa() 反向同步给 CPA 服务
+5. 后续每次 check_codex_quota 直接读文件里的 access_token,401/403 → status=AUTH_INVALID
+6. refresh_access_token 用 refresh_token 换新 at,写回原文件
+```
+
+---
+
+## B. "凭证获取失败"症状归因
+
+### B.1 失败位点候选(按 codex_auth.py 流程顺序)
+
+| # | 位置 | 表现 | 当前处理 | 是否被识别 |
+|---|------|------|----------|------------|
+| 1 | `login_codex_via_browser` step-0 ChatGPT 预登录(Team 模式)| Cloudflare "verify you are human" 不退 | 12 次循环每 5s 试一次,失败仍继续(L327-330) | 否,继续推进可能在后面崩 |
+| 2 | step-0 OTP 等待主号验证码 | 主号未触发 OTP,但 `mail_client.search_emails_by_recipient` 收不到 | 静默 except,继续(L399) | 否 |
+| 3 | step-0 workspace 选择失败 | 用户 `CHATGPT_WORKSPACE_NAME` 配错 | fallback 选第二个非"个人"选项(L417-432) | 否,可能选错 workspace |
+| 4 | OAuth 邮箱/密码页"误跳 Google" | 邮箱碰到 SSO 自动跳 accounts.google.com | 检测到则 `page.go_back` 重试 1 次(L484-489) | **是**(`_is_google_redirect`) |
+| 5 | 验证码邮件取不到 | 120s 内 `mail_client.search_emails_by_recipient` 没拿到 OPENAI 发的 OTP | warning 后继续主循环,实际 consent 步会卡(L564) | 部分,`_wait_for_otp_submit_result` 可识别 invalid/pending |
+| 6 | about-you 失败 | 注册新账号 OAuth 时 `about-you` 页缺 spinbutton/age input | except 吞掉,继续 consent 循环(L608) | 否 |
+| 7 | 10 次 consent 循环里 workspace/Continue 都点不出 | personal/Team 切换冲突、workspace 名称不存在、按钮被遮挡 | break 出 for(L880-882) | 否,只 logger.info |
+| 8 | **add-phone 拦截页(URL `/verify-phone`、`/add-phone`、`/phone-number`)** | OpenAI 风控强制要求绑定手机号 | **完全不检测** | **否** ❗ |
+| 9 | 等 callback 30s 没回来 | OAuth 中途任何卡死 / consent 走偏 | warning,return None(L902-910) | 否,根因被吞 |
+| 10 | personal 模式 plan_type != free | 子号刚 kick 出 Team,workspace default 还指 Team | 拒收 bundle,返回 None(L920-930) | **是**(commit `e760be9`) |
+
+**关键事实**:位点 8 和位点 9 是同一根因的两副面孔。OAuth 走到 add-phone 页 → 卡死 → callback 不回来 → 写"未获取到 auth code"。**这个流程对调用方不可区分**:都是 `bundle is None`。
+
+### B.2 错误日志关键词扫描(grep `oauth_failed|no_bundle|未获取到 auth`)
+
+```
+codex_auth.py:909   "[Codex] OAuth 登录失败: 未获取到 authorization code"   ← 兜底,根因黑盒
+codex_auth.py:904   "[Codex] 未获取到 auth code,当前 URL: %s"               ← 唯一能反推 add-phone 的线索:URL
+codex_auth.py:1104  "[Codex] 主号未获取到 auth code,当前 URL: %s"
+
+manager.py:1455     record_failure(email, "oauth_failed", "已退出 Team 但 personal Codex OAuth 登录未返回 bundle")
+manager.py:1459     out_outcome("oauth_failed", reason="personal Codex OAuth 未返回 bundle")
+manager.py:2485     _cleanup_team_leftover("no_bundle")
+manager.py:1480     team_auth_missing  ("已入 Team 席位但 Codex OAuth 未返回 bundle,需要补登录")
+```
+
+**用户的 register_failures.json 实际样本(11 条)**:
+- 1 条 `oauth_failed`(`0d5d56a045@icoulsy.cloud` "personal Codex OAuth 未返回 bundle")— **这就是"凭证无法通过 OAuth 获取"的真实命中**
+- 8 条 `exception`(net::ERR_ABORTED / Page.content / Page.screenshot 上下文已关闭) — 不在 add-phone 范畴,是 Playwright 浏览器异常
+- 1 条 `kick_failed`、1 条 `register_failed`
+
+证据有限但与现象吻合。`oauth_failed` 没有更细的子分类,无法区分"add-phone 阻塞" / "consent 循环走偏" / "callback 网络抖动"。
+
+### B.3 兜底逻辑现状
+
+```
+login_codex_via_browser 内:
+  ├─ 邮箱步误跳 Google → page.go_back 重试 1 次  ✅
+  ├─ 密码步误跳 Google → page.go_back 重试 1 次  ✅
+  ├─ OTP submit 不通过 → _wait_for_otp_submit_result accepted/invalid/pending 三态 ✅
+  ├─ consent 循环最多 10 次                  ✅
+  ├─ 等 callback 30s                       ✅
+  ├─ personal 模式 plan_type != free 拒收  ✅(commit e760be9)
+  └─ add-phone 拦截                         ❌ 完全没检测
+
+调用方兜底(reinvite_account L2483-2487):
+  bundle is None → _cleanup_team_leftover("no_bundle") → STATUS_STANDBY
+  这套兜底假设"OAuth 失败是一过性的,下次再试可能就好了"。
+  但 add-phone 是确定性风控,等下次 retry 还会撞同样页面 → 死循环消耗 invite/kick 配额
+
+调用方兜底(_run_post_register_oauth L1431 personal 模式):
+  bundle is None → delete_account(email) + record_failure("oauth_failed", "personal OAuth 未返回 bundle")
+  这套对 add-phone 倒是"对的"(账号已 kick 出去,删干净),但**用户失去了"知道为啥失败"的能力**:
+  到底是 add-phone 触发了,还是临时网络问题,还是 workspace default 没同步,日志里都看不出来。
+```
+
+---
+
+## C. add phone 拦截深度调研
+
+### C.1 触发条件(综合外部资料 + 代码注释)
+
+参考 `invite.py:69-87` 注释 + `manager.py:1393` 上下文 + grok web 检索结果(2026-04 仍在生效):
+
+| 类别 | 触发场景 | 在 AutoTeam 上下文里的对应 |
+|------|----------|---------------------------|
+| **行为风控** | 短时间多账号同 IP/UA 注册 | 一个母号一晚上批量生产免费号 → fill-personal |
+| **设备信任** | 新设备/新指纹首次登录 | docker 容器每次开 Playwright 都是"新设备",`oai-did` cookie 没复用 |
+| **地理风控** | VPN / IP 漂移 | 用户跨国部署 / `PLAYWRIGHT_PROXY_URL` 切换 |
+| **账号孤立** | 账号无 cookie/history 直接 OAuth | personal 模式注册后 5s kick 出 Team 立刻 OAuth(cookie 几乎是空的) |
+| **Arkose 缺失** | 浏览器扩展屏蔽 Arkose Labs | docker headless chromium 默认不带扩展,但若 `PLAYWRIGHT_PROXY_URL` 指向某些被 Arkose 黑名单 IP 段会被强制 add-phone |
+| **手机号已复用** | burner 号被多个账号绑过 → "this phone number is already linked to the maximum number of accounts" | 历史问题,与 OAuth 无关但表现类似 |
+
+**"再次登录"特别触发条件**(用户原话:"再次登录时爆 add phone"):
+- 一个账号在某个 session 已经验证过手机 → cookie 清掉再登(docker 重启浏览器、新 context、不复用 storage_state)→ OpenAI 看不到 device 信任,**重新走风控**
+- 短时间多次 OAuth 同一邮箱(reinvite_account 复用 standby → kick 后下一轮再 invite → 再 OAuth)→ 命中"频次"风控
+
+### C.2 检测方式(URL/DOM)
+
+`invite.py:69-87` 已经提供完整检测器,可直接复用:
+
+```python
+_PHONE_URL_HINTS = ("verify-phone", "add-phone", "/phone", "phone_verification", "phone-number")
+_PHONE_TEXT_HINTS = (
+    "verify your phone", "add your phone", "verify phone",
+    "verification code to your phone", "add a phone number",
+    "add a phone", "enter your phone", "phone verification",
+    "we'll text you", "请输入手机号", "手机号码", "验证手机", "添加手机",
+)
+
+def detect_phone_verification(page):
+    url = (page.url or "").lower()
+    if any(hint in url for hint in _PHONE_URL_HINTS):
+        return True                                     # URL 命中 → 强信号
+    body = page.inner_text("body")[:1500].lower()
+    if not any(hint in body for hint in _PHONE_TEXT_HINTS):
+        return False
+    tel_input = page.locator(
+        'input[type="tel"], input[name*="phone" i], input[autocomplete*="tel" i]'
+    ).first
+    if tel_input.is_visible(timeout=500):                # 文本命中 + 电话输入框 → 强信号
+        return True
+    return False                                          # 否则当未阻塞
+```
+
+设计意图(注释里写了):URL 强信号优先;文本必须配合电话输入框,避免注册帮助区"phone number"短语误报。**这套规则已经在生产被验证过半年(从 2025-09 开始用)**,可以直接拿到 OAuth 路径用。
+
+### C.3 当前代码处理现状
+
+**注册阶段(invite.py + manager.py 直接注册)**:✅ 完整覆盖
+
+```
+invite.py:247    assert_not_blocked(page, "email_submit")     ← 邮箱提交后
+invite.py:282    assert_not_blocked(page, "password_submit")  ← 密码提交后
+invite.py:364    assert_not_blocked(page, "code_submit")      ← OTP 提交后
+invite.py:446    assert_not_blocked(page, "profile_submit")   ← about-you 提交后
+manager.py:1954  assert_not_blocked(page, "about_you_submit") ← 直接注册 about-you 后
+manager.py:2117  assert_not_blocked(page, "email_submit")     ← 直接注册 email 后
+manager.py:2184  assert_not_blocked(page, "password_submit")  ← 直接注册 password 后
+manager.py:2228  assert_not_blocked(page, "code_submit")      ← 直接注册 OTP 后
+```
+
+捕获 `RegisterBlocked.is_phone=True` → `record_failure(category="phone_blocked")` + 删邮箱 + 整个账号放弃(`manager.py:2320-2332`)。
+
+**OAuth 阶段(codex_auth.py)**:❌ 零覆盖
+
+```
+codex_auth.py 全文:
+  detect_phone_verification: 0 处
+  assert_not_blocked:        0 处
+  RegisterBlocked:           0 处
+```
+
+**关键空白点**:
+- L568 `if "about-you" in page.url:` ← 后面填了 name/age 就 continue,**这一刻最可能撞 add-phone**(注册流程提交完 about-you 后 OpenAI 经常拉一次 add-phone)
+- L612 consent 10 次循环 ← 每一步都可能跳到 add-phone 页,但只看 workspace/consent button,看不到 add-phone
+- L884 等 callback 30s 死循环 ← add-phone 页就是"callback 永远不来"的根因
+
+### C.4 绕过/规避策略对比
+
+用户原话:"**不要脱离原本的流程太多**"。所有"绕过 add-phone"的方案直接淘汰。可选方向按"侵入度"从小到大:
+
+| # | 策略 | 改动量 | 风险 | 用户接受度 |
+|---|------|--------|------|------------|
+| **A** | **检测到 add-phone 立即放弃 + 标记账号需要人工** | **极小**(invite.py 已现成 detect 函数,在 codex_auth.py 4 处插一行) | **零**,纯防御性 | **高**(用户已在 invite 阶段接受相同处置:"不绕,直接放弃") |
+| B | A + 重置 cookie/storage_state 重试一次 | 中(要在 codex_auth.py 加 storage_state 持久化逻辑,失败重新打开 context) | 低(只是重试,不绕过) | 中(用户没说要重试,但符合"最大可能性修复") |
+| C | A + 切换 PLAYWRIGHT_PROXY_URL 重试 | 大(需要 IP 池管理) | 高(运维负担) | 低(脱离原流程) |
+| D | 自动绑定 SMS pool 上的手机号 | 极大(集成 sms-activate / mobilesms.io) | 极高(违反 OpenAI ToS,封号风险) | 极低 ❌ |
+
+**推荐 A**(可附带 B 作为可配置开关,默认关闭)。
+
+---
+
+## D. 修复方向(最小侵入)
+
+### D.1 必改点(按文件)
+
+#### 1. `src/autoteam/codex_auth.py` — 接入 add-phone 检测
+
+**改动 1:统一抛 RegisterBlocked**
+- 在 `login_codex_via_browser` 主流程的 4 个关键节点插入 `assert_not_blocked(page, step)`:
+  - L568 about-you 入口前(`if "about-you" in page.url:` 之前)
+  - L612 consent 循环每次 step 开头(`for step in range(10):` 内、`if auth_code: break` 后)
+  - L884 等 callback 前(`for _ in range(30):` 之前)
+  - L932 personal 拒收 bundle 之前(plan_type 校验之前)
+
+- 在 `SessionCodexAuthFlow._detect_step` 加一个 `phone_required` 状态,作为 `email_required` / `password_required` / `code_required` 的并列项:命中 add-phone 时返回 `("phone_required", page.url)` 让 `_advance` 立即终止主流程并触发上层处置。
+
+**改动 2:`bundle is None` 携带失败原因**
+- 改 `login_codex_via_browser` 返回签名:`-> bundle | None` 改成 `-> bundle | dict({"error": "phone_required", "url": ...})`,或直接抛 `RegisterBlocked` 让上层 catch。
+- 推荐**抛异常**,理由:`record_failure` 已经按 `RegisterBlocked.is_phone` 分类成熟,新增 `phone_required` 抛异常路径与现有 `oauth_failed` return None 路径解耦,迁移成本最低。
+
+#### 2. `src/autoteam/manager.py` — 6 处调用点统一处理
+
+每个调用点 wrap 一层 try/except RegisterBlocked:
+
+```
+try:
+    bundle = login_codex_via_browser(...)
+except RegisterBlocked as blocked:
+    if blocked.is_phone:
+        record_failure(email, "phone_blocked",
+                       f"OAuth 阶段触发 add-phone (step={blocked.step})",
+                       step=blocked.step, source="oauth")
+        # 处置策略按调用点不同:
+        # - _run_post_register_oauth(personal): delete_account + 退出
+        # - _run_post_register_oauth(team):     update_account(STATUS_PHONE_REQUIRED 或 AUTH_INVALID)
+        # - reinvite_account:                   _cleanup_team_leftover + STATUS_STANDBY
+        # - api.py /api/accounts/login:         返回 409 + "需要人工处理"
+        ...
+    raise
+```
+
+#### 3. `src/autoteam/accounts.py` — 新增状态(可选)
+
+```
+STATUS_PHONE_REQUIRED = "phone_required"  # OAuth 时被风控强制 add-phone,等人工或自动重试
+```
+
+或复用 `STATUS_AUTH_INVALID`(commit cf2f7d3 已有)+ register_failures category=`phone_blocked` 区分。**复用现有状态成本更低**,但 UI 显示"auth invalid"语义不准。
+
+#### 4. `src/autoteam/register_failures.py` — 扩 category 枚举注释
+
+```python
+category: 'phone_blocked' / 'duplicate_exhausted' / 'register_failed' / 'oauth_failed'
+          / 'kick_failed' / 'team_oauth_failed' / 'exception'
+          / 'oauth_phone_blocked'  ← 新增,与注册阶段 phone_blocked 区分,便于统计
+```
+
+#### 5. `src/autoteam/web` 前端(可选)
+
+`web/src/components/Dashboard.vue:381-403` `statusClass / dotClass / statusLabel` 白名单加 `phone_required`(若新增状态),否则跳过此项。
+
+### D.2 测试用例(给后续 implement 参考)
+
+- **单测**:`tests/unit/test_codex_auth_phone_detection.py`
+  - mock `page.url` 为 `https://chat.openai.com/auth/add-phone` → `_advance` 必须返回 `phone_required`
+  - mock body 含 "verify your phone" + tel input 可见 → 同上
+  - mock body 含 "phone number" 但无 tel input → 不阻断(避免误报,与 invite.py 保持一致)
+- **集成测试**:`tests/integration/test_oauth_phone_blocked_flow.py`
+  - mock `login_codex_via_browser` 抛 `RegisterBlocked(is_phone=True)`
+  - 验证 `_run_post_register_oauth(leave_workspace=True)` 调用 `delete_account` + `record_failure(category="oauth_phone_blocked")`
+  - 验证 `reinvite_account` 调用 `_cleanup_team_leftover` + `record_failure`,**不**留 standby 假态
+  - 验证 `/api/accounts/login` 返回 409 + 明确错误体
+- **回归测试**:`tests/unit/test_codex_oauth_no_phone_false_positive.py`
+  - 模拟正常 consent 页(含 "ChatGPT" / "Personal" 等文本)→ `detect_phone_verification` 必须返回 False
+  - 模拟 about-you 页(含 birthday spinbutton)→ 不触发误报
+
+### D.3 与 Issue#6 的边界
+
+| 维度 | Issue#4 | Issue#6 |
+|------|---------|---------|
+| 触发场景 | 任意账号 OAuth 阶段被 add-phone 拦截 | 已被踢出 Team 的账号 reinvite 时触发 add-phone |
+| 涉及调用点 | 全部 6 处 `login_codex_via_browser` | 仅 `reinvite_account`(L2466) |
+| 账号当前位置 | 不确定(可能在 Team / 已 kick / 个人池) | **已 kick 出 Team**,且本地 `STATUS_STANDBY` |
+| 处置紧迫度 | 看场景定 | **高**(账号刚 invite 进 Team 又触发,席位被占用,容易死循环) |
+| 修复在哪一层 | codex_auth.py 检测 + 6 处调用方分类处置 | 同 #4 检测,但 reinvite_account 处置必须立即 kick + 锁定该账号不再被 standby 复用 |
+
+**结论**:#4 修好后,#6 是 #4 在 `reinvite_account` 这一支的特化分类。建议**两个 issue 在同一 PR 里改完**,避免:
+1. 只修 #4 不管 #6 → reinvite_account 命中后未 kick → 假 standby
+2. 只修 #6 不管 #4 → 其他 5 处调用点继续黑盒失败
+
+实施顺序:
+1. `codex_auth.py` 加检测(奠定基础)
+2. `manager._run_post_register_oauth` 处置(personal 路径,最高频)
+3. `manager.reinvite_account` 处置(issue#6 直接收尾)
+4. `manager._check_pending_invites` / `api.post_account_login` 处置
+5. 主号路径 `login_codex_via_session` / `SessionCodexAuthFlow`(可选,主号通常已绑定手机)
+
+---
+
+## E. 风险与未决问题
+
+### E.1 设计层未决
+
+1. **是否新增 `STATUS_PHONE_REQUIRED` 状态?**
+   - 推荐方案 A:复用 `STATUS_AUTH_INVALID` + `register_failures.category="oauth_phone_blocked"`,改动量最小
+   - 风险:语义混淆,前端 UI 显示"auth_invalid"会误导
+   - 替代方案 B:新增独立状态,改动 7-8 个文件(accounts.py / api.py status summary / web/Dashboard.vue / reconcile / sync_account_states / standby probe / cmd_check / 测试)。**Round-3 batch 已经新增过 `STATUS_AUTH_INVALID` 和 `STATUS_ORPHAN`,前端白名单和 reconcile 逻辑还没补全(CHANGELOG round-3 backlog 有提)**,不建议本次再加状态;先用 A 方案 + 后续随状态扩展统一补
+2. **reinvite_account 命中 add-phone 时,是否要把账号永久标"不再复用"?**
+   - 当前 standby 池设计:24h 内已探测过的跳过(commit d6082ad)
+   - 风险:phone-block 是确定性风控,24h 后再试还是会撞;但完全黑名单又可能误杀(临时风控窗口过去后该账号其实可用)
+   - 建议:第一次撞 add-phone → STATUS_AUTH_INVALID,**让 reconcile 处理**(reconcile_anomalies 已有 auth_invalid → KICK 分支);不进 standby 池
+3. **检测器误报怎么办?**
+   - `invite.py:69-87` 的检测规则已半年生产验证,但 OAuth 流程页面文本与注册流程**不完全相同**(consent 页可能含 "phone" 提示文字)
+   - 建议先全量审查 OAuth 流程的截图(`screenshots/codex_04_*.png`)是否含"phone"文本,若有需要在 `_PHONE_TEXT_HINTS` 上加 OAuth 专属规则
+   - 风险等级:低(URL 命中是强信号,文本命中要 tel input 配合,假阳概率小)
+
+### E.2 实施层风险
+
+1. **`SessionCodexAuthFlow._advance` 的 phone_required 处置链路**
+   - 该 Flow 用于主号,目前没有"中断主号 OAuth"的概念,只有 email/password/code required 三个用户输入态
+   - 如果主号撞 add-phone,UI 怎么提示?当前没有"主号需要绑手机"的展示路径
+   - 建议:主号路径暂时只在日志里 ERROR + 抛异常,不接 UI;主号绑过手机后通常不会再撞,这个 case 极罕见
+2. **重试逻辑会不会进一步触发风控?**
+   - 当前 reinvite_account 失败 → STATUS_STANDBY → 24h 后又被选中 reinvite
+   - 加 add-phone 检测 + STATUS_AUTH_INVALID 后,reconcile 会 KICK,不再循环 → **降低**风控触发频率
+3. **detect_phone_verification 在 docker headless 浏览器下的可靠性**
+   - `page.inner_text("body")` 和 `page.locator(...).is_visible` 在 headless 模式应该一致,但 OpenAI 偶尔 A/B test 不同 add-phone 页面布局
+   - 建议:命中后立即调 `_screenshot(page, f"codex_phone_blocked_{step}.png")` 留证据,便于后续回放调试
+4. **fix-personal 的"已退出 Team"账号撞 add-phone**
+   - 这是**最严重**的死路径:账号已 kick → personal OAuth 撞 add-phone → bundle None → 当前流程 `delete_account` + `record_failure("oauth_failed")`
+   - 修复后:`record_failure("oauth_phone_blocked")` 分类,但**账号还是删**(kick 已经发生,留下来没意���)
+   - 风险:用户做 fill-personal 时若一批 4 个号全撞 add-phone,4 个邮箱 + 4 个 invite quota 直接打水漂。建议加**早停**:连续 2 个号撞 add-phone → 整批暂停,提示用户检查 IP/proxy
+
+### E.3 数据层未决
+
+- `register_failures.json` 当前只有 1 例 oauth_failed,样本不足以确认 add-phone 命中率
+- 建议先把检测器加上、跑 1 周生产观察 `oauth_phone_blocked` 计数,再决定要不要加重试/IP 切换逻辑
+- **当前 11 条记录中 8 条是 `Page.goto: net::ERR_ABORTED` / `Page.content: navigating` / `Page.screenshot: Target closed`**,这是 Playwright 浏览器异常**不是 OAuth 失败本身**,跟 add-phone 无关,但说明用户运行环境的浏览器稳定性也有问题(可能是另一个独立 issue)
+
+---
+
+## 附录:本次调研工具使用情况
+
+| 工具 | 使用情况 | 备注 |
+|------|----------|------|
+| serena | 项目未注册到 serena, 退化用 Grep/Read | 可后续 `mcp__metamcp__serena__activate_project` 时手动加 |
+| abcoder | AutoTeam 不在已索引仓库列表(只有 Inkforge/bentodesk/devhub/web) | 同上 |
+| gitnexus | 未配置该项目的图谱索引 | 调用链需手工 grep 构建 |
+| exa | **额度耗尽** ❗(`web_search_exa error 402: exceeded your credits limit`),改用 grok-search | 影响外部资料调研深度,但 grok 给出了 OpenAI Community + reddit + help.openai.com 6 个高质量来源 |
+| grok-search | ✅ 命中 6 篇(2 个 sessions) | 关键发现:OpenAI 用 Arkose Labs,广告拦截器/IP 黑名单会触发 enforcement_failed |
+| Read/Grep/Glob | 主力 | 全文档 100% 走代码事实,无臆测 |
+
+调研涉及文件(主要):
+- `D:/Desktop/AutoTeam/src/autoteam/codex_auth.py`
+- `D:/Desktop/AutoTeam/src/autoteam/manager.py`
+- `D:/Desktop/AutoTeam/src/autoteam/manual_account.py`
+- `D:/Desktop/AutoTeam/src/autoteam/api.py`
+- `D:/Desktop/AutoTeam/src/autoteam/invite.py`
+- `D:/Desktop/AutoTeam/src/autoteam/accounts.py`
+- `D:/Desktop/AutoTeam/src/autoteam/auth_storage.py`
+- `D:/Desktop/AutoTeam/src/autoteam/register_failures.py`
+- `D:/Desktop/AutoTeam/src/autoteam/setup_wizard.py`
+- `D:/Desktop/AutoTeam/CHANGELOG.md`
+- `D:/Desktop/AutoTeam/register_failures.json`(11 条历史失败记录)

prompts/0426/research/issue-5-playwright-async-sync.md

@@ -0,0 +1,438 @@
+# Issue#5 Playwright async/sync 一致性审计
+
+> 调研时间:2026-04-26
+> 调研范围:全项目 Playwright 使用面 + context7 拉取的官方 async/sync 边界
+> 结论:**用户描述的"async 函数里大量误用 sync API"在 AutoTeam 源代码层不成立** — 项目根本没用 asyncio,sync_playwright 全部跑在普通同步线程里,完全合规
+
+---
+
+## A. Playwright 官方 API 对比(context7 输出摘要)
+
+来源:`/websites/playwright_dev_python` + `/microsoft/playwright-python`(Context7 高分 doc)
+
+### A.1 Sync API 关键函数
+
+| API | 调用形式 | 入口 |
+|---|---|---|
+| `sync_playwright()` | 上下文管理器 / `.start()` | `from playwright.sync_api import sync_playwright` |
+| `BrowserType.launch()` | 阻塞返回 `Browser` | `p.chromium.launch()` |
+| `Browser.new_context()` | 阻塞返回 `BrowserContext` | `browser.new_context(...)` |
+| `BrowserContext.new_page()` | 阻塞返回 `Page` | `context.new_page()` |
+| `Page.goto / click / fill / locator / evaluate / wait_for_*` | 全阻塞,无 `await` | 同上 |
+
+```python
+# 官方 sync 范式
+from playwright.sync_api import sync_playwright
+with sync_playwright() as p:
+    browser = p.chromium.launch()
+    page = browser.new_page()
+    page.goto("https://playwright.dev")
+    print(page.title())
+    browser.close()
+```
+
+### A.2 Async API 关键函数
+
+| API | 调用形式 | 入口 |
+|---|---|---|
+| `async_playwright()` | `async with` / `await ....start()` | `from playwright.async_api import async_playwright` |
+| `await BrowserType.launch()` | 协程 | `await p.chromium.launch()` |
+| `await Browser.new_context()` | 协程 | |
+| `await Page.goto / click / fill / evaluate / ...` | 全部协程 | |
+
+```python
+# 官方 async 范式
+import asyncio
+from playwright.async_api import async_playwright
+
+async def main():
+    async with async_playwright() as p:
+        browser = await p.chromium.launch()
+        page = await browser.new_page()
+        await page.goto("https://playwright.dev")
+        print(await page.title())
+        await browser.close()
+
+asyncio.run(main())
+```
+
+### A.3 不可混用的边界(官方明确警告)
+
+> *"Playwright supports two variations of the API: synchronous and asynchronous. **If your modern project uses asyncio, you should use async API.**"*
+> — playwright.dev/python/docs/library
+
+> *"Playwright's API is not thread-safe. If you are using Playwright in a multi-threaded environment, you should create a Playwright instance per thread."*
+> — playwright.dev/python/docs/library (Threading 小节)
+
+**核心约束矩阵**:
+
+| 调用上下文 | 允许 sync_playwright? | 允许 async_playwright? | 备注 |
+|---|---|---|---|
+| 普通 `def` 函数(无 asyncio loop) | ✅ | ❌ | 标准 sync 用法 |
+| 子线程(无 loop) | ✅ 但**每线程独立实例** | ❌ | 不能跨线程共享 page/browser |
+| `async def` 函数(asyncio loop 内) | ❌ **会抛 SyncBecauseInsideAsyncLoop** | ✅ | 这是用户描述的"那个错" |
+| FastAPI `def` 路由 | ✅(FastAPI 把 sync 路由转线程池) | ❌ | 路由本身在 anyio 工作线程跑,不在主 loop |
+| FastAPI `async def` 路由 | ❌ | ✅ | 直接在 loop 里 |
+| `threading.Thread(target=fn)` 里的 fn | ✅ | ⚠ 需新建 loop | AutoTeam 当前用法 |
+
+**典型错误信号**:
+```
+Error: It looks like you are using Playwright Sync API inside the asyncio loop.
+Please use the Async API instead.
+```
+触发条件:`asyncio.run() / loop.run_until_complete()` 调用栈里出现 `sync_playwright()`。
+
+---
+
+## B. 全项目 Playwright 使用现状
+
+### B.1 import 清单(完整,5 处)
+
+| 文件 | 行 | 形式 | 上下文 |
+|---|---|---|---|
+| `src/autoteam/chatgpt_api.py` | 12 | 顶层 `from playwright.sync_api import sync_playwright` | 模块顶层 import |
+| `src/autoteam/codex_auth.py` | 13 | 顶层 `from playwright.sync_api import sync_playwright` | 模块顶层 import |
+| `src/autoteam/invite.py` | 24 | 顶层 `from playwright.sync_api import sync_playwright` | 模块顶层 import |
+| `src/autoteam/manager.py` | 1491 | **函数内** `from playwright.sync_api import sync_playwright` | `_complete_registration` 里 |
+| `src/autoteam/manager.py` | 1969 | **函数内** `from playwright.sync_api import sync_playwright` | `_register_direct_once` 里 |
+
+```bash
+$ grep -rn "from playwright" D:/Desktop/AutoTeam/src
+src/autoteam/chatgpt_api.py:12: from playwright.sync_api import sync_playwright
+src/autoteam/codex_auth.py:13:  from playwright.sync_api import sync_playwright
+src/autoteam/invite.py:24:      from playwright.sync_api import sync_playwright
+src/autoteam/manager.py:1491:       from playwright.sync_api import sync_playwright
+src/autoteam/manager.py:1969:       from playwright.sync_api import sync_playwright
+
+$ grep -rn "from playwright.async_api" D:/Desktop/AutoTeam
+# (0 行 — 项目根本没引用 async_api)
+
+$ grep -rn "async_playwright" D:/Desktop/AutoTeam
+# (0 行)
+```
+
+### B.2 async / sync 各模块归属
+
+#### B.2.1 `async def` 函数清单(完整,1 处)
+
+```bash
+$ grep -rn "^async def" D:/Desktop/AutoTeam/src
+src/autoteam/api.py:35: async def auth_middleware(request: Request, call_next):
+```
+
+**唯一一处 `async def`** 是 FastAPI 鉴权中间件:
+```python
+@app.middleware("http")
+async def auth_middleware(request: Request, call_next):
+    path = request.url.path
+    if not path.startswith("/api/") or path in _AUTH_SKIP_PATHS:
+        return await call_next(request)
+    if not API_KEY:
+        return await call_next(request)
+    auth_header = request.headers.get("authorization", "")
+    if auth_header.startswith("Bearer "):
+        token = auth_header[7:]
+    else:
+        token = request.query_params.get("key", "")
+    if token != API_KEY:
+        return JSONResponse(status_code=401, content={"detail": "未授权,请提供有效的 API Key"})
+    return await call_next(request)
+```
+
+**该函数体里没有 sync_playwright / async_playwright 任何引用** — 只是处理 Header 字符串、调 `call_next`。完全合规。
+
+#### B.2.2 `async with` / `asyncio` 全项目搜索
+
+```bash
+$ grep -rn "async with"  D:/Desktop/AutoTeam/src     # 0 行
+$ grep -rn "\basyncio\b" D:/Desktop/AutoTeam/src     # 0 行
+$ grep -rn "import asyncio" D:/Desktop/AutoTeam      # 0 行(包括 tests)
+$ grep -rn "loop\.run_until_complete" D:/Desktop/AutoTeam  # 0 行
+$ grep -rn "asyncio\.run" D:/Desktop/AutoTeam        # 0 行
+```
+
+**项目压根没用 asyncio**。FastAPI 也是用 sync 路由,uvicorn 起 loop 但路由全跑在 anyio 工作线程。
+
+#### B.2.3 FastAPI 路由全部是 sync `def`
+
+```bash
+$ grep -nE "^@app\.(get|post|put|delete|patch)" src/autoteam/api.py | wc -l
+50
+
+$ grep -nE "^async def (post|get|put|delete|patch|check|set|serve)" src/autoteam/api.py | wc -l
+0
+```
+
+**50 个路由,0 个 async** — 全是 `def` 同步函数。FastAPI 会自动把 sync 路由调度到 anyio threadpool,不在 asyncio 主 loop 上执行,因此 `sync_playwright` 在路由里调用**完全合规**。
+
+#### B.2.4 Playwright 调用上下文(全部 5 处)
+
+| 文件:行 | 上下文 | 是否合规 |
+|---|---|---|
+| `chatgpt_api.py:118` | `class ChatGPTAPI._launch_browser` 实例方法,被 sync 路由 / 后台 thread 调用 | ✅ 合规 |
+| `codex_auth.py:271` | `with sync_playwright() as p:` 在 sync `def` 函数 `_run_oauth_flow` 内 | ✅ 合规 |
+| `invite.py:552` | `with sync_playwright() as p:` 在 sync `def register_with_invite` 内 | ✅ 合规 |
+| `manager.py:1496` | `with sync_playwright() as p:` 在 sync `def _complete_registration` 内 | ✅ 合规 |
+| `manager.py:1976` | `with sync_playwright() as p:` 在 sync `def _register_direct_once` 内 | ✅ 合规 |
+
+**所有 5 处全部在 sync 函数中**,且这些函数最终被 `_PlaywrightExecutor` 专用线程或后台任务线程调用 — **不接触 asyncio loop**。
+
+#### B.2.5 项目自身的 Playwright 线程模型(api.py:155-229)
+
+`src/autoteam/api.py:173-227` 实现了一个 `_PlaywrightExecutor` 单例:
+
+```python
+class _PlaywrightExecutor:
+    """将 Playwright 操作派发到专用线程执行,避免跨线程错误"""
+
+    def __init__(self):
+        self._queue: _queue.Queue = _queue.Queue()
+        self._thread: threading.Thread | None = None
+
+    def _worker(self):
+        while True:
+            item = self._queue.get()
+            if item is None: break
+            func, args, kwargs, result_event, result_holder = item
+            try:
+                result_holder["result"] = func(*args, **kwargs)
+            except Exception as e:
+                result_holder["error"] = e
+            finally:
+                result_event.set()
+
+    def run_with_timeout(self, timeout, func, *args, **kwargs):
+        # 提交到专用线程,主线程 wait 结果
+        self._queue.put((func, args, kwargs, result_event, result_holder))
+        ...
+```
+
+加上 `_playwright_lock = threading.Lock()` 串行所有任务,这套**正是 Playwright 官方文档建议的"sync API + 单线程串行"模式** — 不仅没踩坑,反而是教科书级实现。
+
+#### B.2.6 `page.evaluate(""" async () => { ... } """)` 的"假阳性"
+
+这是审计里**最容易误判的点**:
+
+```bash
+$ grep -rn '"""async' D:/Desktop/AutoTeam/src
+chatgpt_api.py:957:   data = self.page.evaluate("""async (accessToken) => {...}""")
+chatgpt_api.py:1195:  result = self.page.evaluate("""async ([accountId, accessToken]) => {...}""")
+chatgpt_api.py:1230:  result = self.page.evaluate("""async () => { const resp = await fetch(...); ... }""")
+chatgpt_api.py:1287:  js_code = """async ([method, url, headers, body]) => {...}"""
+api.py:709:           "async () => { const r = await fetch(...); ... }"
+```
+
+**这些 `async () => { ... }` 全部是字符串内容**,通过 `page.evaluate(js_string)` 注入到**浏览器侧 JavaScript 上下文**执行 — 不是 Python 协程。Python 这一侧 `page.evaluate(...)` 仍然是同步阻塞调用(返回 JS Promise resolve 后的 value)。
+
+这是 sync_playwright 的标准用法 — 浏览器 `fetch()` 本来就是 JS Promise/async,在浏览器里写 `async/await` 才能 `await fetch()`,Python 这边等 evaluate 返回即可。
+
+**完全合规,不是 bug。** 但用户口头描述"async 里用 sync API"很可能就是看到这种 evaluate 字符串误判的。
+
+#### B.2.7 用户提到的不存在文件
+
+用户原话:"重点文件:src/autoteam/chatgpt_session.py, codex_oauth.py, login_*.py, browser_manager.py 等"。
+
+**实际盘点 src/autoteam/ 全部 .py 文件**:
+```
+__init__.py        account_ops.py    accounts.py       admin_state.py
+api.py             auth_storage.py   cancel_signal.py  chatgpt_api.py
+cloudmail.py       codex_auth.py     config.py         cpa_sync.py
+display.py         identity.py       invite.py         manager.py
+manual_account.py  register_failures.py  runtime_config.py
+setup_wizard.py    textio.py         __main__.py
+mail/{base.py, cf_temp_email.py, maillab.py}
+```
+
+**`chatgpt_session.py` / `browser_manager.py` / `login_*.py` 不存在**(可能是用户记错文件名,或者在描述其它项目)。最接近的是 `chatgpt_api.py` + `codex_auth.py` + `invite.py`,已在上文逐一审计。
+
+---
+
+## C. 误用清单(file:line + 当前 → 应改)
+
+> **结果:0 处误用**
+
+| # | file:line | 当前代码 | 应改为 | 优先级 |
+|---|---|---|---|---|
+| — | — | — | — | — |
+
+经过全量扫描:
+- 0 处 `async_playwright` 引用
+- 0 处 `asyncio` import
+- 0 处 `async with`
+- 1 处 `async def`(`auth_middleware`,内部不调 playwright)
+- 5 处 `sync_playwright` 调用,全部在 sync `def` 上下文 + 已有专用线程隔离
+
+**没有需要改的位点**。
+
+---
+
+## D. 修复策略
+
+### D.1 优先级
+
+**Priority 0 - 不需要修复**
+
+源代码层不存在 async/sync 混用。但有几条**预防性硬化**值得做(下面 D.2、D.3)。
+
+### D.2 重构步骤(预防性,非必须)
+
+虽然现状没问题,但有 3 项可选增强:
+
+#### D.2.1 把 manager.py 的函数内 import 上提到模块顶层
+
+```python
+# 现状(manager.py:1491, 1969)
+def _complete_registration(...):
+    from playwright.sync_api import sync_playwright    # ← 函数内 import
+    ...
+def _register_direct_once(...):
+    from playwright.sync_api import sync_playwright    # ← 函数内 import
+    ...
+
+# 建议(顶层 import,与其它 4 个文件风格一致)
+from playwright.sync_api import sync_playwright
+
+def _complete_registration(...):
+    ...
+def _register_direct_once(...):
+    ...
+```
+
+收益:风格一致,IDE 跳转更顺,启动时一次性失败比"按按钮才发现 import 错"更好。
+风险:可能因为循环 import 才被推到函数内的 — 需先 grep 确认 `manager.py` 不会被 `playwright` 间接 import 反向触发。
+
+#### D.2.2 在 `_PlaywrightExecutor` 加官方文档式断言
+
+```python
+class _PlaywrightExecutor:
+    def _worker(self):
+        # 启动时打一句日志,便于运维确认线程隔离正常
+        import threading
+        logger.info("[Playwright] worker thread started: %s", threading.current_thread().name)
+        ...
+```
+
+#### D.2.3 引入 `playwright_in_async_loop` 守卫(终极防御)
+
+如果未来有人手贱写了 `async def` 路由 + 内部直接 `sync_playwright`,我们应当让它在第一次执行时炸响,而不是悄悄触发 `Sync API inside the asyncio loop`:
+
+```python
+# autoteam/_playwright_guard.py(新文件)
+import asyncio
+import functools
+from playwright.sync_api import sync_playwright as _orig_sync_playwright
+
+@functools.wraps(_orig_sync_playwright)
+def sync_playwright():
+    try:
+        loop = asyncio.get_running_loop()
+    except RuntimeError:
+        loop = None
+    if loop is not None:
+        raise RuntimeError(
+            "禁止在 asyncio loop 内调用 sync_playwright — "
+            "改用 await asyncio.to_thread(...) 或重构为 async_playwright"
+        )
+    return _orig_sync_playwright()
+```
+
+然后在 5 个调用点统一 `from autoteam._playwright_guard import sync_playwright`。出现误用立刻抛错,堆栈一目了然。
+
+### D.3 测试要点
+
+#### D.3.1 静态守卫测试
+
+```python
+# tests/unit/test_no_playwright_in_async_def.py
+import ast
+from pathlib import Path
+
+SRC = Path(__file__).parent.parent.parent / "src"
+
+def _walk(node, parent_async):
+    if isinstance(node, ast.AsyncFunctionDef):
+        parent_async = True
+    if parent_async and isinstance(node, (ast.Call, ast.Attribute, ast.Name)):
+        text = ast.unparse(node)
+        if "sync_playwright" in text:
+            yield node.lineno, text
+    for child in ast.iter_child_nodes(node):
+        yield from _walk(child, parent_async)
+
+def test_no_sync_playwright_inside_async_def():
+    bad = []
+    for p in SRC.rglob("*.py"):
+        try:
+            tree = ast.parse(p.read_text(encoding="utf-8"))
+        except SyntaxError:
+            continue
+        for lineno, text in _walk(tree, False):
+            bad.append(f"{p}:{lineno} {text}")
+    assert not bad, "async def 函数内调用了 sync_playwright:\n" + "\n".join(bad)
+```
+
+#### D.3.2 运行时守卫测试
+
+```python
+# tests/unit/test_playwright_guard.py
+import asyncio
+import pytest
+
+from autoteam._playwright_guard import sync_playwright
+
+@pytest.mark.asyncio
+async def test_sync_playwright_blocked_in_async_loop():
+    with pytest.raises(RuntimeError, match="禁止在 asyncio loop"):
+        sync_playwright()
+
+def test_sync_playwright_works_in_sync_context():
+    # 仅做 import / 调用前置检查不抛即可,不真启 browser
+    pass
+```
+
+#### D.3.3 集成 smoke
+
+`/api/tasks/fill` `/api/tasks/check` 等触发 sync_playwright 的端点已有现存测试;只需补一条:**确认从 FastAPI sync 路由到 _PlaywrightExecutor 的链路在 uvicorn loop 下不会抛 "Sync API inside asyncio loop"**。可以通过 `httpx.AsyncClient` 调一次 `/api/auth/check`(轻量端点)+ `/api/tasks/check` 完成。
+
+---
+
+## E. 回归风险
+
+### E.1 当前不动代码的风险:0
+
+不修任何代码 = 当前架构合规,无回归。
+
+### E.2 应用 D.2 / D.3 的风险评估
+
+| 改动 | 风险等级 | 主要风险点 |
+|---|---|---|
+| **D.2.1** 顶层 import | 🟡 低 | 循环 import 导致启动失败 — 需先 grep 验证 |
+| **D.2.2** 启动日志 | 🟢 极低 | 多一行 log 而已 |
+| **D.2.3** runtime guard | 🟡 中 | 必须 5 处全部替换 — 漏一处就回到老路;另需在 tests 里 unstub `_orig_sync_playwright` |
+| **D.3.1** AST 静态测试 | 🟢 极低 | 误报概率低,纯静态 |
+| **D.3.2** runtime guard 测试 | 🟢 低 | 需要 pytest-asyncio 依赖 |
+
+### E.3 用户描述与现实的偏差
+
+用户说"在 playwright 中大量出现一堆 async 里用 sync 的 api 的问题",**这描述与 AutoTeam 当前代码不符**。可能性:
+1. 用户看的是**某次运行时报错日志**,但那段日志可能来自其他库(比如 anyio 内部、或 FastAPI 框架自身)
+2. 用户把 `page.evaluate("""async () => {...}""")` 的 JS async 字符串误读成 Python async 函数
+3. 用户看的是**别的项目** / 历史版本(本仓库 git log 也没出现过 async_playwright)
+4. 用户准备好了"接下来要做的事"(比如想引入并发抓取),提前打预防针
+
+**建议下一步**:让用户提供具体的报错堆栈或文件:行号 — 凭描述无法定位,代码层面是干净的。
+
+---
+
+## 总结
+
+| 维度 | 结论 |
+|---|---|
+| 全项目 `async_playwright` 引用数 | **0** |
+| 全项目 `asyncio` 引用数 | **0** |
+| 全项目 `async def` 数 | **1**(FastAPI auth_middleware,与 playwright 无关) |
+| 全项目 `sync_playwright` 调用数 | **5**,全部在 sync `def` + 专用线程 |
+| 误用 / 混用位点 | **0** |
+| 当前是否需要修复? | **❌ 不需要** |
+| 建议增强(可选) | 顶层 import 统一 + runtime guard + AST 静态测试三连 |
+| 用户描述与现实差距 | 可能误读 `page.evaluate("async () => ...")` JS 字符串;请提供具体堆栈定位 |

prompts/0426/research/issue-6-invite-postkick.md

@@ -0,0 +1,229 @@
+# Issue#6 — 邀请→进 workspace→quota=0→踢出 401→重 OAuth add phone 研究报告
+
+## A. 用户报告解构
+
+用户原话(摘录):
+> "手动试了下在 team 里邀请,然后邮件点击链接完成注册,收个邮箱验证码倒是能进 team 了。CPA OAuth 登录再收个验证码登录子号没让选个人还是工作空间,直接就是工作空间了。(还是不显示额度的那种,实际也没额度,调用什么都是 429 没额度)team 踢掉之后,子号就 401 了,重新 OAuth 还是需要手机"
+
+拆为 4 子症状:
+
+| 编号 | 症状 | 严重程度 |
+|---|---|---|
+| **A** | CPA OAuth 没让选 personal/workspace,直接进 workspace | 中(可能是设计意图) |
+| **B** | workspace 模式下 quota=0,调用 429 | 高(账号入池但完全不可用) |
+| **C** | team 踢出后子号 401 | 高(状态机没正确识别"被人踢") |
+| **D** | 重新 OAuth 时强制 add phone | 高(踢出+重 OAuth 风控) |
+
+## B. 代码现状
+
+### B.1 关键符号清单
+
+| 文件:行号 | 签名 | 作用 |
+|---|---|---|
+| `src/autoteam/codex_auth.py:250-932` | `login_codex_via_browser(email, password, mail_client=None, *, use_personal=False)` | OAuth 主流程,包含 step-0 注入 `_account` cookie + step-4 workspace 选择循环 |
+| `src/autoteam/codex_auth.py:262-263` | `chatgpt_account_id = "" if use_personal else get_chatgpt_account_id()` | use_personal 决定要不要注入 Team workspace cookie |
+| `src/autoteam/codex_auth.py:295-318` | step-0:Team 模式注入 `_account` cookie 引导 OAuth 进 Team workspace | personal 模式跳过 |
+| `src/autoteam/codex_auth.py:618-733` | step-4 循环:检测"选择一个工作空间"页面,自动点击 Team / Personal | use_personal 时点 Personal,否则点 Team workspace_name |
+| `src/autoteam/codex_auth.py:916-930` | personal 模式 plan_type 强校验 | plan_type != "free" 时拒收 bundle(防止 Team 被默认选中颁发 Team token) |
+| `src/autoteam/codex_auth.py:1618-1700` | `check_codex_quota(access_token, account_id=None)` | 调 wham/usage,返回 ok / exhausted / auth_error / network_error |
+| `src/autoteam/codex_auth.py:1572-1615` | `get_quota_exhausted_info(quota_info, *, limit_reached=False)` | 判定耗尽:`primary_pct >= 100 or weekly_pct >= 100 or limit_reached` |
+| `src/autoteam/codex_auth.py:1665-1671` | `if resp.status_code in (401, 403): return "auth_error"` / `429` 归 network_error | 401 token 失效与 429 限流分流 |
+| `src/autoteam/manager.py:1386-1486` | `_run_post_register_oauth(email, password, mail_client, leave_workspace=False, ...)` | 注册收尾,走 Team 或 personal 分支,但**不调 check_codex_quota** |
+| `src/autoteam/manager.py:1463-1486` | `bundle = login_codex_via_browser(...)` 后直接 `update_account(status=STATUS_ACTIVE)` | **没有 quota probe** |
+| `src/autoteam/manager.py:476-600` | `sync_account_states(chatgpt_api=None)` | Team 成员对照本地状态;`active 但不在 Team` 直接刷 standby |
+| `src/autoteam/manager.py:526-541` | `elif not in_team and acc["status"] == STATUS_ACTIVE: ... acc["status"] = STATUS_STANDBY` | **不区分"被踢出"和"正常待机"** |
+| `src/autoteam/manager.py:161-471` | `_reconcile_team_members` | 检测 ghost / orphan / 错位,KICK 后会标 STATUS_AUTH_INVALID(line 312、339) |
+| `src/autoteam/manager.py:2446-2630` | `reinvite_account(chatgpt_api, mail_client, acc)` | standby 复用主流程:重 OAuth → 验 plan_type=team → check_codex_quota → 假恢复检测 |
+| `src/autoteam/manager.py:2466` | `bundle = login_codex_via_browser(email, password, mail_client=mail_client)` | 默认 use_personal=False |
+| `src/autoteam/manager.py:2489-2494` | `if plan_type != "team": _cleanup_team_leftover; return False` | self_serve_business_* 等 plan 直接被拒 |
+| `src/autoteam/invite.py:106-145` | `detect_phone_verification(page)` + `assert_not_blocked(page, step)` | **只在 invite.register_with_invite 流程里调用,login_codex_via_browser 完全没引用** |
+| `src/autoteam/api.py:1450-1525` | `POST /api/accounts/{email}/login`(补登录) | 调 login_codex_via_browser,无 add-phone 探针保护 |
+
+### B.2 调用链/数据流
+
+#### 子症状 A:OAuth workspace 选择链
+
+```
+用户在 Web 点"补登录" / "fill-team"
+    └─ login_codex_via_browser(email, pwd, use_personal=False)
+        ├─ step-0: 注入 _account cookie = chatgpt_account_id      ← 强制 Team workspace
+        ├─ 浏览器访问 auth_url (auth.openai.com/authorize)
+        ├─ 邮箱 + OTP 验证
+        └─ step-4 loop (10 轮):
+            ├─ 检测"选择一个工作空间"页 → JS click workspace_name
+            ├─ 点继续按钮
+            └─ 拿 auth_code → exchange → bundle (含 plan_type=team)
+```
+
+**整个流程没有"让用户选"的交互点**:cookie 注入决定 default workspace,JS 自动点击决定具体选项。这是设计意图(自动化场景),但与 user 期望"先问我"冲突。
+
+#### 子症状 B:quota=0 进 active 链
+
+```
+_run_post_register_oauth(...)                            (manager.py:1463)
+    ├─ login_codex_via_browser → bundle.plan_type
+    ├─ save_auth_file(bundle) → auth_file
+    └─ update_account(status=STATUS_ACTIVE, seat_type, auth_file, ...)
+       ↑ 此处缺一道 check_codex_quota:
+         如果 wham/usage 返回 quota=0 / limit_reached / 401,
+         应该立刻分流到 STATUS_EXHAUSTED 或 STATUS_AUTH_INVALID。
+```
+
+对比 `manual_account._finalize_account`(`manual_account.py:227-286`)— 手动添加路径**有** check_codex_quota(line 263-272),会按结果标 STATUS_EXHAUSTED。但**邀请→注册路径**走的是 `_run_post_register_oauth`,这条**没有 quota probe**。这是直接 bug。
+
+更致命的是 `get_quota_exhausted_info`(codex_auth.py:1582)只看 `primary_pct >= 100`。如果 wham/usage 返回 `used_percent=0` 但**总额本身是 0**(self_serve_business_usage_based workspace 没分配 codex 配额的情况),代码当作 ok 状态 + 显示"100% 剩余",但下游 CPA 调用 codex API 立刻 429 — 这就是用户报告的"显示额度但实际没额度"。
+
+#### 子症状 C:team 踢出后 401 链
+
+```
+管理员在 ChatGPT 后台手动踢子号(不走 AutoTeam)
+    ↓
+sync_account_states (manager.py:476)
+    ├─ GET /backend-api/accounts/{id}/users → 不见该 email
+    └─ acc["status"] = STATUS_STANDBY                  ← 没有标 AUTH_INVALID
+    ↓
+下次 rotation 选中该 standby
+    └─ reinvite_account (manager.py:2446)
+        ├─ login_codex_via_browser → bundle (此时会拿到 free / personal plan)
+        │  ↑ 因为 cookie 注入失败/workspace 默认变了,
+        │    bundle.plan_type 不是 "team"
+        ├─ if plan_type != "team": _cleanup_team_leftover  ← line 2490
+        └─ return False(死循环)
+```
+
+子号在 ChatGPT 后端被 user_id revoke,但 OAuth refresh_token 走的是 chatgpt_account_id 维度 — 一旦该 user_id 在 workspace 不存在,任何 backend-api 调用都 401。**关键缺陷**:`sync_account_states:540` 把"被踢"当成"待机"处理。
+
+#### 子症状 D:重 OAuth add phone 链
+
+```
+踢出立即(< 5 分钟)重新跑 reinvite_account
+    └─ login_codex_via_browser
+        └─ Playwright 浏览器:
+            ├─ 邮箱 + OTP
+            ├─ ChatGPT 后端检测"刚刚被踢且立即重登" → 触发风控
+            └─ 跳转 add-phone 页面
+                ↑ 这里 codex_auth.py 完全没 detect_phone_verification!
+                  step-4 循环见不到 add-phone,只看到 OTP/workspace/consent 选项,
+                  全部 timeout 后 auth_code 为 None,bundle 失败。
+```
+
+**对比** `invite.register_with_invite`(invite.py:190-477):每个步骤之间都调 `assert_not_blocked(page, step)`,命中 add-phone 立即 raise RegisterBlocked + 上层放弃账号。这套 detect 在 `login_codex_via_browser` 完全没接入。
+
+## C. 根因分析
+
+### C.1 子症状 B:quota=0 进 active 池
+
+**优先级 P0**(用户痛点最直接 — 进池号不可用)
+
+候选根因:
+1. `_run_post_register_oauth` 缺 quota probe(主因) — manual_account 有,这里没,接口不对称。
+2. `get_quota_exhausted_info` 不能识别"总额=0"(次因) — 即便加 probe,也只判 used_percent=100,无配额 workspace 仍会被认 ok。
+3. `chatgpt_plan_type` 白名单缺失 — `self_serve_business_usage_based` 进来被打 codex 席位,但 codex 在该 workspace 根本不可用。
+
+### C.2 子症状 C:踢出后状态错位
+
+**优先级 P0**
+
+候选根因:
+1. `sync_account_states:540` 不区分"被踢"vs"自然待机"(主因) — 应该用 auth_file 实测一次 wham/usage,401 → STATUS_AUTH_INVALID,而不是无脑 standby。
+2. `reinvite_account:2490` 对 plan_type != team 的处理简单粗暴(次因) — 此时 token 已经 revoke,正确处置是清掉 auth_file + 标 AUTH_INVALID,而不是回 standby 等下一轮(下一轮还是 401 死循环)。
+3. 缺少 standby 准入探测 — manager.py:1166 段有但有 24h 去重,新被踢的号要等 24h 才会被 wham 探测。
+
+### C.3 子症状 D:add-phone 真空区
+
+**优先级 P0**
+
+候选根因:
+1. `login_codex_via_browser` 没接入 `detect_phone_verification` 探针(主因) — invite.py 的探针没被复用。
+2. 踢出 → 立即重 OAuth 时间太近(次因) — `_run_post_register_oauth:1428` 有 8s 等待,但 reinvite_account 没有类似等待。
+3. `_used_email_ids` 状态污染 — `codex_auth.py:260` 每轮新建,不会跨轮污染。但浏览器 context 是新建的,不该带 cookie 残留。
+
+### C.4 子症状 A:workspace 不让选
+
+**优先级 P2**(更像 UX 缺失而非 bug)
+
+候选根因:
+1. cookie 注入 + JS 自动点击的设计就是为了无人值守自动化 — 与"让用户选"的交互需求矛盾。
+2. 缺少前端 OAuth 模式选择菜单 — 当前 web UI 的"补登录"按钮没有 use_personal 开关,API `POST /accounts/{email}/login` 也是按 acc.status 自动决定 use_personal(api.py:1475)。
+
+## D. 修复方向建议(只是方向,不写代码)
+
+### D.1 必须改的点
+
+1. **`_run_post_register_oauth` 加 quota probe**(P0,issue#6 主因 B)
+   - 位置:`manager.py:1463-1486`
+   - 拿到 bundle 后立即调 `check_codex_quota(bundle.access_token, bundle.account_id)`
+   - 结果分流:
+     - `ok` + `quota_info` 写入 last_quota,标 STATUS_ACTIVE(现有行为)
+     - `exhausted` 标 STATUS_EXHAUSTED + quota_exhausted_at(参考 manual_account.py:266-272)
+     - `auth_error` / `network_error` 写日志,但**不**标 active(避免假入池)— 标 STATUS_AUTH_INVALID,等 reconcile 处理
+
+2. **`check_codex_quota` 识别"总额=0"**(P0,issue#2 / #6 共因)
+   - 位置:`codex_auth.py:1685-1700`
+   - 解析 rate_limit.primary_window 时除了 `used_percent` 也读 `limit` / `total` / `remaining`
+   - 总额=0 / remaining=0 / reset_at=0 → 新增分类 `"no_quota"` 或归到 `"exhausted"` + window=`no_quota`
+
+3. **`sync_account_states` 区分"被踢"vs"自然待机"**(P0,issue#6 主因 C)
+   - 位置:`manager.py:526-541`
+   - 当 `not in_team and status == STATUS_ACTIVE` 时,如果 acc.auth_file 存在,实测一次 wham/usage:
+     - 401/403 → 标 STATUS_AUTH_INVALID(token 已 revoke,等 reconcile 清 auth_file)
+     - 200 + ok → 真的是被踢但 token 还在(罕见,可能 OpenAI 缓存延迟),标 STATUS_STANDBY 让 reinvite_account 重新拉
+     - network_error → 暂保持 STATUS_ACTIVE 等下轮(避免网络抖动误标)
+
+4. **`login_codex_via_browser` 接入 add-phone 探针**(P0,issue#6 主因 D)
+   - 位置:`codex_auth.py:612` 起的 step-4 循环里,每轮 try 块开头 import `from autoteam.invite import detect_phone_verification`
+   - 命中 add-phone 直接 break + 设置 `auth_code = None` + log error
+   - 函数返回 None,上游 `_run_post_register_oauth` / `reinvite_account` 走"OAuth 失败"分支
+   - **额外加** `record_failure(email, "add_phone_at_oauth", "OAuth 流程命中 add-phone 风控")`,UI 失败明细能看到
+
+5. **`reinvite_account` 在踢出后等待 OpenAI 同步**(P1,issue#6 D 次因)
+   - 位置:`manager.py:2466` 之前
+   - 如果 acc 的状态从 standby 进入 reinvite,且 `last_active_at` < 5 分钟前(刚被踢),先 sleep 8-15s 让 ChatGPT 后端 default workspace 切换生效
+   - 与 `_run_post_register_oauth:1427-1429` 的 8s 等待保持对称
+
+6. **`reinvite_account` plan_type != team 时的二次处理**(P1,issue#6 C 次因)
+   - 位置:`manager.py:2489-2494`
+   - 不仅 `_cleanup_team_leftover` + return False,还要 `update_account(status=STATUS_AUTH_INVALID, auth_file=None)`
+   - 让该号下一轮被 reconcile 直接清掉,而不是反复在 standby 池里轮转
+
+### D.2 可选优化
+
+1. **OAuth 模式选择 UI**(issue#6 A)
+   - Web Dashboard 的"补登录"按钮加下拉:Team / Personal / Auto(根据 status)
+   - API `POST /accounts/{email}/login` 接受 `mode` 参数
+
+2. **standby 探测去重的 cool-down 缩短**(issue#6 C)
+   - `manager.py:1166` 24h 去重对新被踢号太长,改成"被踢后 30 分钟即可再探测"
+   - 用 acc 的 `last_kicked_at` 字段(新增)而不是 `last_quota_check_at` 判断
+
+3. **add-phone 命中后清理 auth_file**
+   - 一旦 OAuth 命中 add-phone,该账号短期内重 OAuth 还是会被风控,清掉 auth_file 标 STATUS_AUTH_INVALID 让用户介入
+   - 比反复重试更友好
+
+4. **batch 失败明细**:`failures` 表新增 add_phone_at_oauth 类别,UI 上区分"邀请阶段 add-phone"和"OAuth 阶段 add-phone"
+
+### D.3 测试要点
+
+- [ ] 注册一个新号,通过 invite 流程进 Team,确认 `_run_post_register_oauth` 拿到 bundle 后立刻打 wham/usage
+- [ ] 模拟一个 quota=0 的 workspace(可以临时改 wham/usage 返回值)— 确认账号被标 EXHAUSTED 而不是 ACTIVE
+- [ ] 在 ChatGPT 后台**手动**踢一个 active 子号 → 等下次 sync_account_states 跑 → 确认状态变 AUTH_INVALID(不是 STANDBY)
+- [ ] 主动 kick 一个号后立刻 reinvite,确认 add-phone 风控被探测到 + 失败明细写入 register_failures.json
+- [ ] reinvite_account 第一次失败标 AUTH_INVALID 后,确认下一轮 reconcile 清掉 auth_file,不再被 standby 池选中
+- [ ] OAuth 模式选择 UI:在补登录时手动选"Team",确认 `_account` cookie 注入 + workspace 选 Team;选"Personal"确认 use_personal=True 路径
+
+## E. 影响面 / 爆炸半径
+
+- **`_run_post_register_oauth` 加 probe**:扩散到 `manager.py:1386-1486` 单点,但调用方多(_complete_registration、create_account_direct、_check_pending_invites)。最大风险是 probe 异常时不能堵死注册流程 — 必须保持"probe 失败不影响 bundle 已成功"的弱化逻辑。
+- **`check_codex_quota` 加 no_quota 分类**:扩散到所有 6+ 调用点(manager 多处、api 多处、cpa_sync),需要每个调用点都 handle 新分类,否则会被当成 ok 默认值掉进死循环。
+- **`sync_account_states` 加 wham 探测**:这是个高频调用函数(rotation 每轮都会触发),如果探测延时叠加,可能拖慢整个轮转。需要给每个 active 子号探测加并发 + 超时上限。
+- **`login_codex_via_browser` 加 add-phone 探针**:仅 codex_auth.py 内部,但���为变化是"OAuth 提前失败"— 调用方都已有 bundle=None 兜底逻辑,影响小。
+- **`reinvite_account` 调整 plan_type != team 的清理**:扩散到 manager.py 多个 reinvite 调用点(line 2719 / 3041 / 3391),需要确认它们都依赖"return False 时不动 acc.auth_file"的旧约定。
+
+## F. 风险与未决问题
+
+1. **wham/usage 返回 schema 是否真有 limit / total**:目前代码只读 `used_percent` / `reset_at` / `limit_reached`,如果 OpenAI 没在 self_serve_business 上返回 limit 字段,"总额=0"的识别只能依赖间接信号(reset_at=0 + used_percent=0 + 调用立刻 429)。需要从用户 bundle 实测 wham/usage 响应。
+2. **手动踢 vs API 踢的区分**:OpenAI 后端 /users 的 GET 返回不会告诉我们"成员是被踢还是自然离开",只能靠"上次见过 + 这次没见到"推断。AutoTeam 自己 kick 的会有 _reconcile_team_members 主动标 AUTH_INVALID(line 312、339),但**人工 kick** 走 sync_account_states,目前缺识别。
+3. **add-phone 探针误报**:invite.py 的 detect_phone_verification 主要靠 URL hint + body 文本,在 OAuth 流程中(auth.openai.com 域)可能误命中 OAuth 同意页里的 phone 帮助链接。需要为 OAuth 流程定制更严格的探针(必须有可见 input[type=tel] 且不在 footer 区)。
+4. **reinvite 后 8-15s 等待是否够**:OpenAI 后端的 default workspace 切换延迟可能是 8s 也可能是 60s+,固定等待可能不够。建议 polling auth.openai.com 的 /me 接口确认 workspace 已切换才继续。
+5. **加 quota probe 后 _run_post_register_oauth 失败率会上升**:因为之前 quota=0 的号会被认为成功,加 probe 后会被打回失败。这可能让 fill-team 的"成功率"指标看起来变差,但实际是更准确。需要在变更说明中提醒用户这是正向变化。
+6. **issue#2 与 issue#6 的修复有重叠**:`check_codex_quota` 增强、`plan_type` 白名单、quota probe 都是两个 issue 共因,实施时应统一规划而不是分两次改。

prompts/0426/spec/shared/account-state-machine.md

@@ -0,0 +1,518 @@
+# Shared SPEC: 账号状态机
+
+## 0. 元数据 + 引用方
+
+| 字段 | 内容 |
+|---|---|
+| 名称 | 账号 7 状态完整状态机与转移规则 |
+| 版本 | v1.0 (2026-04-26) |
+| 主题归属 | `accounts.py` STATUS_* 常量 + 各转移点的触发函数 + 不变量 |
+| 引用方 | PRD-2 / spec-2-account-lifecycle.md / FR-D1~D4、FR-E1~E4、FR-H1~H3 |
+| 共因 | synthesis §1 共因 D、E + Issue#6 |
+| 不在范围 | seat_type 字段(见 PRD-2 FR-F1~F6)、cpa_sync 同步细节(参考 `cpa_sync.py`) |
+
+---
+
+## 1. 概念定义
+
+| 术语 | 定义 |
+|---|---|
+| `account state` | 落盘到 `accounts.json` 的 `status` 字段,7 个枚举之一 |
+| `transition` | 由代码事件(同步/注册/踢出/探测)触发的状态变化 |
+| `terminal state` | 没有自动转出 transition 的状态,需要人工介入或 reconcile 接管 |
+| 被踢(kicked) | 在 ChatGPT Team 后端不可见但本地仍 active 的账号;wham/usage 401/403 时确认 |
+| 自然待机(natural standby) | 账号 quota 耗尽后被本系统主动 kick,等待 5h reset 自然恢复 |
+
+---
+
+## 2. 完整数据契约
+
+### 2.1 状态枚举(已存在,在 `accounts.py:13-20`)
+
+```python
+# src/autoteam/accounts.py 已有:
+STATUS_ACTIVE = "active"            # 在 team 中,额度可用
+STATUS_EXHAUSTED = "exhausted"      # 在 team 中,额度用完
+STATUS_STANDBY = "standby"          # 已移出 team,等待额度恢复
+STATUS_PENDING = "pending"          # 已邀请,等待注册完成
+STATUS_PERSONAL = "personal"        # 已主动退出 team,走个人号 Codex OAuth
+STATUS_AUTH_INVALID = "auth_invalid" # auth_file token 已不可用,待 reconcile 清理或重登
+STATUS_ORPHAN = "orphan"            # 在 workspace 占席位但本地无 auth_file
+```
+
+### 2.2 Pydantic AccountRecord(完整契约,本 spec 引入)
+
+```python
+from typing import Literal, Optional
+from pydantic import BaseModel, Field
+
+AccountStatus = Literal[
+    "active", "exhausted", "standby", "pending", "personal", "auth_invalid", "orphan",
+]
+SeatType = Literal["chatgpt", "codex", "unknown"]
+
+
+class QuotaSnapshot(BaseModel):
+    """详见 ./quota-classification.md §2.1"""
+    primary_pct: int = 0
+    primary_resets_at: int = 0
+    primary_total: Optional[int] = None
+    primary_remaining: Optional[int] = None
+    weekly_pct: int = 0
+    weekly_resets_at: int = 0
+
+
+class AccountRecord(BaseModel):
+    email: str
+    password: str
+    cloudmail_account_id: Optional[str] = None
+    status: AccountStatus
+    seat_type: SeatType = "unknown"
+    workspace_account_id: Optional[str] = None
+    auth_file: Optional[str] = None
+    quota_exhausted_at: Optional[float] = None
+    quota_resets_at: Optional[float] = None
+    last_quota_check_at: Optional[float] = None  # FR-E3 探测去重
+    last_quota: Optional[QuotaSnapshot] = None
+    last_active_at: Optional[float] = None
+    created_at: float
+    plan_supported: Optional[bool] = None        # 新增,见 ./plan-type-whitelist.md
+    plan_type_raw: Optional[str] = None          # 新增,记录原始 OAuth 字面量
+    last_kicked_at: Optional[float] = None       # 新增,被踢识别时间戳;reconcile 用
+```
+
+### 2.3 状态-字段不变量
+
+| 状态 | 必备字段 | 禁用字段 |
+|---|---|---|
+| `pending` | `email`, `password`, `created_at` | `auth_file` 必须为 None(注册未完成) |
+| `active` | `email`, `auth_file`(非 None) | — |
+| `exhausted` | `email`, `auth_file`, `quota_exhausted_at`, `quota_resets_at` | — |
+| `standby` | `email` | — |
+| `personal` | `email`, `auth_file`(非 None,personal 专属 plan_type=free) | — |
+| `auth_invalid` | `email` | — |
+| `orphan` | `email`(在 workspace 占席位) | `auth_file` 必须为 None |
+
+---
+
+## 3. 状态机图(ASCII)
+
+### 3.1 完整状态机
+
+```
+                            ┌──────────────┐
+                            │   PENDING    │   注册中,等收邮件
+                            └──────┬───────┘
+                                   │
+                  注册成功+OAuth+quota ok
+                                   │
+                                   ▼
+       ┌──────────────────────────┐
+       │         ACTIVE           │ ◄────┐  reinvite 验证 ok
+       │   在 Team,可调 Codex      │      │
+       └──┬───────────────────────┘      │
+          │                              │
+   quota  │ 100%      ┌──────────────────┤
+          ▼           │                  │
+   ┌──────────┐  本系统kick    ┌────────────┐
+   │EXHAUSTED │ ────────────► │  STANDBY   │ ◄── reinvite plan!=team(旧路径)
+   │ (lock 5h)│               │ 等待 reset  │     (新路径推 AUTH_INVALID)
+   └────┬─────┘               └────┬───────┘
+        │                          │
+   reset│ 5h 后 reinvite           │ reinvite 验证
+        └──────────────────────────┴────────►  返 ACTIVE
+                                              或 fall through
+                                              (见下方 fail_reason 分支)
+                                              
+                            ┌─────────────┐
+   人工 leave_workspace ──► │  PERSONAL   │ (终态,不参与 Team 轮转)
+                            └─────────────┘
+                            
+   sync 探测 wham 401/403  ┌────────────────┐    reconcile.KICK
+   ──────────────────────► │ AUTH_INVALID   │ ──────────────────► 删本地或保留人工介入
+   注册收尾 wham no_quota  │ token 已失效    │
+   reinvite plan_drift    │                │
+   add-phone 命中(Team)   └────────────────┘
+   
+   _reconcile 发现 ghost  ┌──────────┐    人工 KICK
+   ──────────────────────► │  ORPHAN  │ ──────────────────► 删
+                          └──────────┘
+```
+
+### 3.2 状态分类
+
+| 类别 | 状态 |
+|---|---|
+| 工作池(轮转参与) | `active`、`exhausted`、`standby`、`pending` |
+| 终态(不参与轮转) | `personal`、`auth_invalid`、`orphan` |
+
+---
+
+## 4. 状态/分类规则
+
+### 4.1 触发函数 → 转移矩阵
+
+| 触发函数 | 文件:行号 | 触发条件 | from → to |
+|---|---|---|---|
+| `add_account` | `accounts.py:58` | 新增账号(invite 成功) | (none) → PENDING |
+| `_run_post_register_oauth` Team 分支 | `manager.py:1463` | bundle ok + quota ok | PENDING → ACTIVE |
+| `_run_post_register_oauth` Team 分支 | `manager.py:1463` | bundle ok + quota exhausted(新) | PENDING → EXHAUSTED |
+| `_run_post_register_oauth` Team 分支 | `manager.py:1463` | bundle ok + quota no_quota(新) | PENDING → AUTH_INVALID |
+| `_run_post_register_oauth` Team 分支 | `manager.py:1463` | bundle ok + quota auth_error(新) | PENDING → AUTH_INVALID |
+| `_run_post_register_oauth` Team 分支 | `manager.py:1463` | bundle 但 plan_supported=False(新) | PENDING → AUTH_INVALID |
+| `_run_post_register_oauth` Team 分支 | `manager.py:1463` | bundle 失败但已 invite | PENDING → ACTIVE(team_auth_missing,旧行为保留) |
+| `_run_post_register_oauth` Team 分支 | `manager.py:1463` | RegisterBlocked(is_phone=True)(新) | PENDING → AUTH_INVALID |
+| `_run_post_register_oauth` personal 分支 | `manager.py:1431` | bundle ok + plan=free | PENDING → PERSONAL |
+| `_run_post_register_oauth` personal 分支 | `manager.py:1431` | bundle 失败 / plan != free | PENDING → deleted(record_failure) |
+| `_run_post_register_oauth` personal 分支 | `manager.py:1431` | RegisterBlocked(is_phone=True)(新) | PENDING → deleted + record_failure |
+| `sync_account_states` | `manager.py:520` | active 在 Team 中(同步成功) | ACTIVE → ACTIVE(无变化) |
+| `sync_account_states` | `manager.py:520` | standby/pending 在 Team 中 | STANDBY/PENDING → ACTIVE |
+| `sync_account_states` | `manager.py:540` | active 不在 Team + workspace_account_id 不一致 | ACTIVE → ACTIVE(母号切换守卫,旧行为保留) |
+| `sync_account_states` | `manager.py:540`(新) | active 不在 Team + wham 401/403 | ACTIVE → AUTH_INVALID |
+| `sync_account_states` | `manager.py:540`(新) | active 不在 Team + wham ok / network_error | ACTIVE → STANDBY(自然待机,保留旧行为) |
+| `cmd_check` quota 探测 | `manager.py:715/748/760` | wham 状态变化 | active → exhausted/auth_invalid/standby |
+| `reinvite_account` | `manager.py:2466` | OAuth 成功 + plan=team + quota verified | STANDBY → ACTIVE |
+| `reinvite_account` | `manager.py:2466`(新) | OAuth 成功 + plan != team / plan_supported=False | STANDBY → AUTH_INVALID(plan_drift) |
+| `reinvite_account` | `manager.py:2466`(新) | OAuth 失败 RegisterBlocked(is_phone=True) | STANDBY → AUTH_INVALID(oauth_phone_blocked) |
+| `reinvite_account` | `manager.py:2466`(旧) | OAuth 成功但 quota_low / exhausted | STANDBY → STANDBY(锁 5h) |
+| `reinvite_account` | `manager.py:2466`(旧) | OAuth 成功但 quota auth_error / network_error / exception | STANDBY → STANDBY(不锁 5h) |
+| `reinvite_account` | `manager.py:2466`(旧) | OAuth 失败 bundle=None | STANDBY → STANDBY(_cleanup_team_leftover) |
+| `_reconcile_team_members` | `manager.py:312/339` | 发现 ghost / orphan 错位 | ACTIVE → AUTH_INVALID |
+| `_reconcile_team_members` | `manager.py:312/339` | workspace 占席位但本地无 auth_file | (任意) → ORPHAN |
+| `_replace_single` kick | `manager.py:2626` | 主动定点替换 | active → STANDBY |
+| `delete_managed_account` | `account_ops.py:40` | 用户单点 / 批量删除 | (任意) → deleted |
+| `manual_account._finalize_account` | `manual_account.py:227` | 用户粘贴 OAuth callback | (none) → STANDBY(team) / ACTIVE(team+plus 之外) / AUTH_INVALID(plan_unsupported,新) |
+
+### 4.2 "被踢" vs "自然待机" 识别规则(FR-E1)
+
+```
+sync_account_states 看到 acc.status == ACTIVE 且 email 不在当前 workspace_team_emails:
+  ├─ acc.workspace_account_id ≠ 当前 account_id → 母号切换遗留,保留 ACTIVE(旧行为)
+  ├─ acc.auth_file 存在 → 用 access_token 调一次 wham/usage(并发限制 5,超时 5s)
+  │   ├─ ("auth_error", _) → STATUS_AUTH_INVALID + last_kicked_at=now  ★被踢
+  │   ├─ ("ok", info) → STATUS_STANDBY + last_quota=info  ★自然待机(罕见,可能 OpenAI 缓存延迟)
+  │   ├─ ("exhausted", info) → STATUS_STANDBY + quota_exhausted_at  ★自然待机
+  │   ├─ ("no_quota", info) → STATUS_AUTH_INVALID(无配额且不在 Team,不会自动恢复)
+  │   └─ ("network_error", _) → 保持 ACTIVE 等下轮(避免抖动误标)
+  └─ acc.auth_file 缺失 → STATUS_STANDBY(降级,无法验证)
+```
+
+### 4.3 reinvite_account fail_reason 分支(扩 FR-H1)
+
+```
+reinvite_account 拿到 bundle 后:
+  ├─ bundle == None
+  │   ├─ 由 RegisterBlocked(is_phone=True) 引发 → STATUS_AUTH_INVALID(新,FR-C3)
+  │   └─ 其他 → _cleanup_team_leftover("no_bundle") + STATUS_STANDBY(旧)
+  ├─ plan_supported == False → STATUS_AUTH_INVALID + record_failure("plan_unsupported")(新)
+  ├─ plan_type != "team" → STATUS_AUTH_INVALID + record_failure("plan_drift")(新,替代旧 STATUS_STANDBY)
+  └─ plan_type == "team":
+      ├─ quota verified ok → STATUS_ACTIVE(旧)
+      ├─ quota fail_reason in (exhausted, quota_low) → STATUS_STANDBY + 锁 5h(旧)
+      └─ quota fail_reason in (auth_error, network_error, exception) → STATUS_STANDBY 不锁 5h(旧)
+```
+
+### 4.4 反向不变量
+
+| 不变量 | 说明 |
+|---|---|
+| `auth_file 存在 ⇒ status ∈ {active, exhausted, standby_with_token, personal, auth_invalid}` | orphan / pending 必无 auth_file |
+| `status == personal ⇒ plan_type_raw == "free"` | personal 路径强校验(`codex_auth.py:920-930`) |
+| `status == active ⇒ workspace_account_id 与当前一致 OR workspace_account_id is None` | sync 守卫(`manager.py:531-538`) |
+| `last_kicked_at != None ⇒ status in {auth_invalid, deleted}` | 被踢标记的语义边界 |
+
+---
+
+## 5. 调用方处置规范(状态消费方)
+
+### 5.1 工作池筛选
+
+```python
+# accounts.py 已存在
+def get_active_accounts():
+    """status == active 且非主号"""
+    return [a for a in load_accounts() if a["status"] == STATUS_ACTIVE]
+
+
+def get_personal_accounts():
+    """status == personal 且非主号"""
+
+
+def get_standby_accounts():
+    """status == standby,按 quota_recovered 排序"""
+
+
+# 新增推荐(便于 UI 与 reconcile)
+def get_terminal_accounts():
+    """auth_invalid + orphan,需要人工介入或 reconcile 清理"""
+    return [a for a in load_accounts()
+            if a["status"] in (STATUS_AUTH_INVALID, STATUS_ORPHAN)]
+```
+
+### 5.2 reconcile 处置(`manager.py:_reconcile_team_members` 旧 + 新)
+
+| 输入状态 | reconcile 行为 |
+|---|---|
+| `auth_invalid` + 在 workspace 占席位 | KICK + 保留本地记录 + 等用户/批量删除 |
+| `auth_invalid` + 不在 workspace | 保留本地记录(已自然清理),等用户决定是否删 |
+| `orphan` + 在 workspace 占席位 | KICK |
+| 其他状态 | 沿用现有处理 |
+
+### 5.3 UI 显示规范
+
+| 状态 | UI 文案 | 操作按钮 |
+|---|---|---|
+| `active` | 工作中 | 强制下线 / 删除 |
+| `exhausted` | 已耗尽,X 小时后恢复 | 删除(灰显:auto check 已锁) |
+| `standby` | 待机中(quota 已恢复 / 未恢复) | 立即重用 / 删除 |
+| `pending` | 注册中... | (无) |
+| `personal` | 个人 free 号 | 删除(短路 fetch_team_state,见 PRD-2 FR-G1) |
+| `auth_invalid` | **token 失效,已退出 Team** | 删除(短路 fetch_team_state) |
+| `orphan` | **席位异常,等待清理** | KICK + 删除 |
+
+---
+
+## 6. 单元测试 fixture 与样本数据
+
+### 6.1 状态机 transition 表(yaml)
+
+```yaml
+# tests/fixtures/state_transitions.yaml
+- name: register_team_success
+  from: pending
+  trigger: _run_post_register_oauth(leave_workspace=False, bundle.plan="team", quota="ok")
+  to: active
+  expected_fields:
+    auth_file: not_null
+    seat_type: chatgpt | codex
+    last_active_at: not_null
+
+- name: register_team_quota_no_quota
+  from: pending
+  trigger: _run_post_register_oauth(leave_workspace=False, bundle.plan="team", quota="no_quota")
+  to: auth_invalid
+  expected_register_failure:
+    category: no_quota_assigned
+
+- name: register_team_plan_unsupported
+  from: pending
+  trigger: _run_post_register_oauth(bundle.plan_supported=False)
+  to: auth_invalid
+  expected_register_failure:
+    category: plan_unsupported
+
+- name: register_team_phone_blocked
+  from: pending
+  trigger: _run_post_register_oauth raises RegisterBlocked(is_phone=True)
+  to: auth_invalid
+  expected_register_failure:
+    category: oauth_phone_blocked
+    stage: run_post_register_oauth_team
+
+- name: sync_active_kicked_by_admin
+  from: active
+  trigger: sync_account_states(not in_team) + wham 401
+  to: auth_invalid
+  expected_fields:
+    last_kicked_at: not_null
+
+- name: sync_active_natural_standby
+  from: active
+  trigger: sync_account_states(not in_team) + wham exhausted
+  to: standby
+
+- name: sync_active_workspace_drift
+  from: active
+  trigger: sync_account_states(not in_team) + workspace_account_id 不一致
+  to: active  # 保留(母号切换遗留)
+
+- name: reinvite_plan_drift
+  from: standby
+  trigger: reinvite_account(bundle.plan="free")
+  to: auth_invalid
+  expected_register_failure:
+    category: plan_drift
+
+- name: reinvite_plan_unsupported
+  from: standby
+  trigger: reinvite_account(bundle.plan_supported=False)
+  to: auth_invalid
+  expected_register_failure:
+    category: plan_unsupported
+
+- name: reinvite_phone_blocked
+  from: standby
+  trigger: reinvite_account raises RegisterBlocked(is_phone=True)
+  to: auth_invalid
+  expected_register_failure:
+    category: oauth_phone_blocked
+    stage: reinvite_account
+
+- name: reinvite_team_quota_low
+  from: standby
+  trigger: reinvite_account(bundle.plan="team", quota="ok" but pct<threshold)
+  to: standby  # 锁 5h(旧行为)
+  expected_fields:
+    quota_exhausted_at: not_null
+
+- name: reinvite_team_success
+  from: standby
+  trigger: reinvite_account(bundle.plan="team", quota verified)
+  to: active
+```
+
+### 6.2 单测代码
+
+```python
+# tests/unit/test_state_machine.py
+import pytest
+import yaml
+from pathlib import Path
+from autoteam.accounts import (
+    STATUS_ACTIVE, STATUS_STANDBY, STATUS_PENDING, STATUS_AUTH_INVALID,
+    STATUS_PERSONAL, STATUS_ORPHAN, STATUS_EXHAUSTED, AccountRecord,
+)
+
+TRANSITIONS = yaml.safe_load(Path("tests/fixtures/state_transitions.yaml").read_text())
+
+
+@pytest.mark.parametrize("case", TRANSITIONS)
+def test_state_transition(case, mock_factory):
+    """每个 transition 跑一遍,验证 from / to / 失败记录字段"""
+    acc = mock_factory.account(status=case["from"])
+    mock_factory.fire_trigger(case["trigger"], acc)
+    final = mock_factory.reload(acc.email)
+    assert final.status == case["to"]
+    if "expected_register_failure" in case:
+        rec = mock_factory.last_failure(acc.email)
+        for k, v in case["expected_register_failure"].items():
+            assert rec[k] == v
+
+
+def test_state_field_invariants():
+    """每个 status 的 必备/禁用 字段不变量"""
+    cases = [
+        # (status, must_have_keys, must_be_none_keys)
+        (STATUS_PENDING, ["email", "password", "created_at"], ["auth_file"]),
+        (STATUS_ACTIVE, ["email", "auth_file"], []),
+        (STATUS_EXHAUSTED, ["email", "auth_file", "quota_exhausted_at", "quota_resets_at"], []),
+        (STATUS_PERSONAL, ["email", "auth_file"], []),
+        (STATUS_ORPHAN, ["email"], ["auth_file"]),
+    ]
+    for status, must_have, must_none in cases:
+        acc = AccountRecord(...)  # 用工厂构造
+        for k in must_have:
+            assert getattr(acc, k) is not None
+        for k in must_none:
+            assert getattr(acc, k) is None
+
+
+def test_pydantic_account_record_round_trip():
+    """JSON 序列化 / 反序列化后字段不丢失"""
+    acc = AccountRecord(
+        email="t@example.com", password="x", status="active",
+        seat_type="codex", auth_file="/auths/codex-t.json",
+        plan_supported=True, plan_type_raw="team",
+        created_at=1714000000.0,
+    )
+    js = acc.model_dump_json()
+    acc2 = AccountRecord.model_validate_json(js)
+    assert acc2.status == "active"
+    assert acc2.plan_supported is True
+```
+
+### 6.3 完整 accounts.json 样本
+
+```json
+[
+  {
+    "email": "alice-team@example.com",
+    "password": "abc",
+    "cloudmail_account_id": "cm-1",
+    "status": "active",
+    "seat_type": "chatgpt",
+    "workspace_account_id": "ws-100",
+    "auth_file": "/abs/auths/codex-alice-team-team-deadbeef.json",
+    "quota_exhausted_at": null,
+    "quota_resets_at": null,
+    "last_quota_check_at": 1714050000.0,
+    "last_quota": {
+      "primary_pct": 35,
+      "primary_resets_at": 1714060000,
+      "primary_total": 100,
+      "primary_remaining": 65,
+      "weekly_pct": 10,
+      "weekly_resets_at": 1714600000
+    },
+    "last_active_at": 1714050000.0,
+    "created_at": 1714000000.0,
+    "plan_supported": true,
+    "plan_type_raw": "team",
+    "last_kicked_at": null
+  },
+  {
+    "email": "bob-self-serve@example.com",
+    "password": "xyz",
+    "cloudmail_account_id": "cm-2",
+    "status": "auth_invalid",
+    "seat_type": "codex",
+    "workspace_account_id": "ws-100",
+    "auth_file": null,
+    "quota_exhausted_at": null,
+    "quota_resets_at": null,
+    "last_quota_check_at": null,
+    "last_quota": null,
+    "last_active_at": null,
+    "created_at": 1714000000.0,
+    "plan_supported": false,
+    "plan_type_raw": "self_serve_business_usage_based",
+    "last_kicked_at": null
+  },
+  {
+    "email": "charlie-kicked@example.com",
+    "password": "def",
+    "cloudmail_account_id": "cm-3",
+    "status": "auth_invalid",
+    "seat_type": "chatgpt",
+    "workspace_account_id": "ws-100",
+    "auth_file": "/abs/auths/codex-charlie-team-team-cafe1234.json",
+    "quota_exhausted_at": null,
+    "quota_resets_at": null,
+    "last_quota_check_at": 1714050000.0,
+    "last_quota": null,
+    "last_active_at": 1714045000.0,
+    "created_at": 1714000000.0,
+    "plan_supported": true,
+    "plan_type_raw": "team",
+    "last_kicked_at": 1714050000.0
+  }
+]
+```
+
+---
+
+## 7. 不变量(Invariants)
+
+- **I1**:任何状态变更必须经过 `update_account` 入口,**禁止**直接 dict 改写后 `save_accounts`(避免漏触发持久化)
+- **I2**:`STATUS_ACTIVE` 必须有 `auth_file`(注册收尾或 reinvite 验证后写入);任何把 active 设回但不写 auth_file 的代码都是 bug
+- **I3**:`STATUS_AUTH_INVALID` 不能有 `quota_exhausted_at`(因为不会自然恢复);写时必须清空
+- **I4**:`STATUS_PERSONAL` 是终态,不能回到 active(转换路径只有 manual_account 重新注册或新 OAuth bundle)
+- **I5**:`STATUS_ORPHAN` 必须 `auth_file == None`(定义:占席位但本地无凭证);`auth_file` 存在的应判 active / standby / auth_invalid
+- **I6**:`last_kicked_at` 字段一旦写入,后续状态转移不能清掉(用于 reconcile 历史回放;只在 delete_account 时随记录一起删)
+- **I7**:reconcile_anomalies(`manager.py:161-471`)对 `auth_invalid` 的 KICK 行为必须保持幂等(重复 KICK 不抛异常,`kick_status="already_absent"` 视为成功)
+- **I8**:状态白名单变更(新增枚举)需要全局检查 4 处:`Dashboard.vue` statusClass / `cpa_sync.py` 同步规则 / `sync_account_states` 处置 / 本 spec §4.2
+
+---
+
+## 附录 A:状态机变更历史
+
+| 版本 | 时间 | 变更 |
+|---|---|---|
+| v0.1 | round-1 | 初始 4 状态(active/exhausted/standby/pending) |
+| v0.2 | round-2 | 加 personal |
+| v0.3 | round-3 | 加 auth_invalid + orphan(commit cf2f7d3) |
+| v1.0 | 2026-04-26 PRD-2 | 加 last_kicked_at / plan_supported / plan_type_raw 字段;补全转移规则;不新增 STATUS_PHONE_REQUIRED(复用 auth_invalid + register_failures) |
+
+---
+
+**文档结束。** 工程师据此可直接编写 7 状态 + 转移点的代码改造、Pydantic 模型、单测,不需额外决策。

prompts/0426/spec/shared/add-phone-detection.md

@@ -0,0 +1,441 @@
+# Shared SPEC: OAuth add-phone 探针
+
+## 0. 元数据 + 引用方
+
+| 字段 | 内容 |
+|---|---|
+| 名称 | OAuth 流程 add-phone 探针接入与异常分类 |
+| 版本 | v1.0 (2026-04-26) |
+| 主题归属 | `login_codex_via_browser` 中的 4 个探针接入点 + 5 个调用方分类处置 |
+| 引用方 | PRD-2 / spec-2-account-lifecycle.md / FR-C1~C5 |
+| 共因 | synthesis §1 共因 C;Issue#4 + Issue#6 |
+| 不在范围 | invite 注册阶段的 add-phone 检测(已实现,见 `invite.py:106-145`)、SMS pool 自动绑定(违反 ToS,非目标) |
+
+---
+
+## 1. 概念定义
+
+| 术语 | 定义 |
+|---|---|
+| `add-phone` | OpenAI 在 OAuth 流程中触发的强制手机号验证页(URL 含 `add-phone` / `verify-phone` 等),命中后用户必须绑定手机才能继续 |
+| `RegisterBlocked` | 现有异常类(`invite.py:53-66`),用于注册流程被风控阻断时上抛;含 `is_phone` / `is_duplicate` / `step` / `reason` 字段 |
+| `assert_not_blocked` | 现有探针函数(`invite.py:138-145`),命中 add-phone 或 duplicate 立刻 raise |
+| `detect_phone_verification` | 现有检测函数(`invite.py:106-126`),URL 强信号 + 文本+输入框组合信号 |
+| `oauth_phone_blocked` | 新增 register_failures category,与注册阶段的 `phone_blocked` 区分(便于统计 OAuth vs 注册的命中率) |
+
+---
+
+## 2. 完整数据契约
+
+### 2.1 现有契约(直接复用,不改动)
+
+```python
+# src/autoteam/invite.py L53-66 已存在
+class RegisterBlocked(Exception):
+    """
+    注册流程被风控或确定性错误阻断时抛出;调用方按 reason 做分流处理:
+    - is_phone=True: OpenAI 要求手机验证,当前账号放弃(用户明确不绕过)
+    - is_duplicate=True: 邮箱已被占用,当前账号放弃,换邮箱重来
+    - 其他: 单步逻辑错误,按现有 retry 流程处理
+    """
+    def __init__(self, step: str, reason: str, *, is_phone: bool = False, is_duplicate: bool = False):
+        super().__init__(f"[{step}] {reason}")
+        self.step: str = step
+        self.reason: str = reason
+        self.is_phone: bool = is_phone
+        self.is_duplicate: bool = is_duplicate
+
+
+# src/autoteam/invite.py L106 已存在
+def detect_phone_verification(page) -> bool:
+    """若当前页面要求手机验证返回 True。URL 命中优先;文本命中需配合电话输入框。"""
+    ...
+
+
+# src/autoteam/invite.py L138 已存在
+def assert_not_blocked(page, step: str) -> None:
+    """任何步骤后调用,检测到阻断项立刻 raise RegisterBlocked。"""
+    ...
+```
+
+### 2.2 新增契约(本 spec 引入)
+
+```python
+# src/autoteam/register_failures.py 文档化扩 category(只是注释,不改代码逻辑)
+def record_failure(email: str, category: str, reason: str, **extra) -> None:
+    """
+    category: 'phone_blocked'         注册阶段命中 add-phone(invite.register_with_invite)
+              'oauth_phone_blocked'   OAuth 阶段命中 add-phone(login_codex_via_browser)  ★新增
+              'duplicate_exhausted'   邮箱重复
+              'register_failed'       通用注册失败
+              'oauth_failed'          OAuth 通用失败(无 phone 子分类时)
+              'kick_failed'           kick 失败
+              'team_oauth_failed'     Team 阶段 OAuth 失败
+              'exception'             浏览器/网络异常
+              'plan_unsupported'      plan_type 不在白名单(见 plan-type-whitelist.md)  ★新增
+              'no_quota_assigned'     wham/usage 返回 no_quota(见 quota-classification.md)  ★新增
+              'plan_drift'            reinvite 拿到非 team plan(见 spec-2 §3.3)  ★新增
+              'auth_error_at_oauth'   注册收尾 wham 401/403  ★新增
+              'quota_probe_network_error'  注册收尾 wham 网络异常  ★新增
+    """
+```
+
+### 2.3 OAuth 域定制规则(差异于注册阶段)
+
+```python
+# src/autoteam/codex_auth.py 顶部新增(本地常量,不动 invite.py)
+# OAuth consent 页可能含 "phone" 帮助链接 / footer 文字,但**没有**可见 input[type=tel]。
+# 对 OAuth 域采用更严格规则:URL 命中是强信号(直接判 True);文本命中**必须**配合
+# 可见 tel input,且 tel input 不能在 footer / aside 等次要区域。
+_OAUTH_PHONE_URL_HINTS = ("verify-phone", "add-phone", "/phone", "phone_verification", "phone-number")
+_OAUTH_PHONE_TEXT_HINTS = (  # 严格子集,移除 "phone verification" 这种容易误命中 consent 页解释文案的
+    "verify your phone",
+    "add your phone",
+    "verification code to your phone",
+    "add a phone number",
+    "add a phone",
+    "enter your phone",
+    "we'll text you",
+    "请输入手机号",
+    "手机号码",
+    "验证手机",
+    "添加手机",
+)
+```
+
+---
+
+## 3. 行为契约
+
+### 3.1 函数签名(所有现有,本 spec 仅约束调用方)
+
+```python
+def detect_phone_verification(page) -> bool: ...
+def assert_not_blocked(page, step: str) -> None:
+    """命中 add-phone → raise RegisterBlocked(step, "add-phone 手机验证", is_phone=True)
+       命中 duplicate → raise RegisterBlocked(step, "duplicate email", is_duplicate=True)
+       未命中 → 返回 None
+    """
+```
+
+### 3.2 前置条件
+
+- `page` 是已加载的 Playwright Page 对象(可读 `.url` / `.inner_text` / `.locator`)
+- `step` 是非空字符串,表示触发探针的位点名称(用于异常 `step` 字段 + 失败截图命名)
+- 探针函数本身**不抛**业务异常;Playwright 异常被内部 try/except 吞掉(注释中已说明)
+
+### 3.3 后置条件
+
+- `assert_not_blocked` 返回 None 表示页面未阻塞,主流程可继续
+- 抛出 `RegisterBlocked` 后,调用方必须按 `is_phone` / `is_duplicate` 分类处置(见 §5)
+- 命中后由调用方负责截图(`_screenshot(page, f"codex_phone_blocked_{step}.png")`)
+
+### 3.4 异常传播
+
+```
+detect_phone_verification(page)
+  └─ 任何 Playwright 异常 → logger.debug + return False(不阻塞)
+  └─ 命中 → return True
+
+assert_not_blocked(page, step)
+  └─ detect_phone_verification(page) == True → raise RegisterBlocked(step, ..., is_phone=True)
+  └─ detect_duplicate_email(page) == True   → raise RegisterBlocked(step, ..., is_duplicate=True)
+  └─ 其他 → return None
+```
+
+---
+
+## 4. 4 个探针接入点(精确位置)
+
+### 4.1 接入位置图
+
+```
+login_codex_via_browser(email, password, mail_client, *, use_personal)  # codex_auth.py:250
+  │
+  ├─ step-0  ChatGPT 预登录 + _account cookie 注入(L295-440)
+  │           Cloudflare 等待 / 邮箱+OTP / workspace 选择
+  │
+  ├─ step-1  goto auth_url → 邮箱表单(L443-488)
+  │           Google redirect 检测(已存在,不变)
+  │
+  ├─ step-2  邮箱 + 密码 + OTP(L489-562)
+  │
+  ├─ ★ C-P1: assert_not_blocked(page, "oauth_about_you")    [L568 about-you 入口前]
+  │           插入位置:`if "about-you" in page.url:` 这行**之前**
+  │           理由:about-you 提交后 OpenAI 经常拉一次 add-phone,要在页面切到 about-you 前先确认
+  │
+  ├─ step-3  about-you 填表 + 提交(L568-610)
+  │
+  ├─ ★ C-P2: assert_not_blocked(page, f"oauth_consent_{step}")  [L612 consent 循环每轮开头]
+  │           插入位置:`for step in range(10):` 内,每次 try 块的**第一行**
+  │           理由:consent 循环每一步都可能跳到 add-phone,只看 workspace/Continue 按钮看不到
+  │
+  ├─ step-4  consent 10 次循环(L612-882)
+  │
+  ├─ ★ C-P3: assert_not_blocked(page, "oauth_callback_wait")    [L884 等 callback 前]
+  │           插入位置:`for _ in range(30):` 这行**之前**
+  │           理由:add-phone 页就是"callback 永远不来"的根因,等之前先拦
+  │
+  ├─ step-5  等 30s callback(L884-906)
+  │
+  ├─ ★ C-P4: assert_not_blocked(page, "oauth_personal_check")   [L920 personal 拒收 bundle 之前]
+  │           插入位置:`if use_personal:` 这行**之前**
+  │           理由:防御性 — 通常 callback 前已拦截,但作为最后一道关卡
+  │
+  └─ _exchange_auth_code(auth_code) → bundle
+```
+
+### 4.2 实施代码片段
+
+```python
+# 位点 C-P1(在 codex_auth.py:568 之前)
+from autoteam.invite import assert_not_blocked, RegisterBlocked  # 文件顶部 import
+
+# === 处理 about-you 页面（可能出现在 OAuth 流程中）===
+assert_not_blocked(page, "oauth_about_you")  # ★新增
+if "about-you" in page.url:
+    logger.info("[Codex] 检测到 about-you 页面，填写个人信息...")
+    ...
+
+# 位点 C-P2(在 codex_auth.py:612 后的 for 循环每轮开头)
+for consent_step in range(10):
+    try:
+        assert_not_blocked(page, f"oauth_consent_{consent_step}")  # ★新增,作为 try 块第一行
+        # ... 原有 consent 循环代码 ...
+    except RegisterBlocked:
+        raise  # 不在内层吞,让外层调用方处理
+    except Exception as e:
+        logger.debug(...)
+
+# 位点 C-P3(在 codex_auth.py:884 之前)
+assert_not_blocked(page, "oauth_callback_wait")  # ★新增
+# 等待 redirect callback 获取 auth code
+for _ in range(30):
+    if auth_code:
+        break
+    ...
+
+# 位点 C-P4(在 codex_auth.py:920 之前,personal 模式校验 plan_type 之前)
+assert_not_blocked(page, "oauth_personal_check")  # ★新增,防御性
+if use_personal:
+    plan = (bundle.get("plan_type") or "").lower()
+    ...
+```
+
+### 4.3 位点选择理由(摘自 issue#4 D.1.1)
+
+| 位点 | 选择理由 |
+|---|---|
+| C-P1 (about-you 前) | OpenAI 在新账号注册的 about-you 页之后**最频繁**拉 add-phone。在切到 about-you 之前先拦,可在最早时间发现风控 |
+| C-P2 (consent 循环每轮) | consent 循环 10 次,每一步都可能跳 add-phone;不在循环里拦,会被当作"workspace 没选好"反复重试 |
+| C-P3 (callback 等待前) | add-phone 阻塞会让 callback 永远不来,30s 等待白白耗费;在等之前先判 |
+| C-P4 (personal 拒收前) | 防御性:正常情况下前 3 个位点已拦下;万一漏过(consent 循环之外的页面),最后兜底 |
+
+---
+
+## 5. 调用方处���规范(5 个 login_codex_via_browser 调用点)
+
+### 5.1 调用点清单
+
+| # | 文件:行号 | 上下文 | use_personal |
+|---|---|---|---|
+| 1 | `manager.py:1057` | `_check_pending_invites` 补登录 | False |
+| 2 | `manager.py:1431` | `_run_post_register_oauth(leave_workspace=True)` 个人模式 | True |
+| 3 | `manager.py:1463` | `_run_post_register_oauth` Team 注册收尾 | False |
+| 4 | `manager.py:2466` | `reinvite_account` standby 复用 | False |
+| 5 | `api.py:1479` | `/api/accounts/{email}/login` 用户触发补登录 | 视 acc.status 而定 |
+
+### 5.2 5 个调用方处置矩阵
+
+| # | catch RegisterBlocked(is_phone=True) 后 | record_failure 字段 |
+|---|---|---|
+| 1 | `delete_account(email)` + `record_failure(...)` | category="oauth_phone_blocked", stage="check_pending_invites" |
+| 2 | `delete_account(email)` + `record_failure(...)` | category="oauth_phone_blocked", stage="run_post_register_oauth_personal" |
+| 3 | `update_account(email, status=STATUS_AUTH_INVALID)` + `record_failure(...)` + 不删账号(已在 Team) | category="oauth_phone_blocked", stage="run_post_register_oauth_team" |
+| 4 | `_cleanup_team_leftover("oauth_phone_blocked")` + `update_account(email, status=STATUS_AUTH_INVALID, auth_file=None)` | category="oauth_phone_blocked", stage="reinvite_account" |
+| 5 | 转 HTTP 409 + body `{"error": "phone_required", "step": ..., "reason": ...}` + record_failure | category="oauth_phone_blocked", stage="api_login" |
+
+### 5.3 通用 try/except 模板
+
+```python
+from autoteam.invite import RegisterBlocked
+
+try:
+    bundle = login_codex_via_browser(email, password, mail_client=mail_client, use_personal=...)
+except RegisterBlocked as blocked:
+    if blocked.is_phone:
+        record_failure(
+            email,
+            category="oauth_phone_blocked",
+            reason=f"OAuth 阶段触发 add-phone (step={blocked.step})",
+            step=blocked.step,
+            stage=<调用点名>,
+            url=getattr(blocked, "url", None),
+        )
+        # 调用点特定处置(见 §5.2 矩阵)
+        ...
+        return None
+    elif blocked.is_duplicate:
+        # OAuth 阶段不应触发 duplicate(账号已注册成功);记 exception 兜底
+        record_failure(email, category="exception", reason=f"OAuth 阶段意外 duplicate: {blocked.reason}")
+        return None
+    raise  # 其他 RegisterBlocked 子分类暂不可能,raise 让上层兜底
+```
+
+### 5.4 主号路径(不在范围)
+
+- `login_codex_via_session` / `SessionCodexAuthFlow` / `MainCodexSyncFlow`(`codex_auth.py` 中段)用于主号 session 复用
+- 主号通常已绑定手机,极罕见撞 add-phone
+- **本 spec 不要求**给主号路径加探针(节省工作量);如未来需要,按 §4.2 模板独立扩展
+
+---
+
+## 6. 单元测试 fixture 与样本数据
+
+### 6.1 mock 页面 fixture
+
+```python
+# tests/fixtures/oauth_phone_pages.py
+from unittest.mock import MagicMock
+
+
+def make_phone_page(url="https://auth.openai.com/add-phone",
+                    body_text="please add your phone number to continue",
+                    has_tel_input=True):
+    page = MagicMock()
+    page.url = url
+    page.inner_text.return_value = body_text
+    tel_input = MagicMock()
+    tel_input.is_visible.return_value = has_tel_input
+    page.locator.return_value.first = tel_input
+    return page
+
+
+def make_consent_page(url="https://auth.openai.com/authorize/consent",
+                      body_text="continue with your team workspace"):
+    return make_phone_page(url=url, body_text=body_text, has_tel_input=False)
+
+
+def make_about_you_page(url="https://auth.openai.com/about-you",
+                        body_text="tell us about yourself, full name, age"):
+    return make_phone_page(url=url, body_text=body_text, has_tel_input=False)
+
+
+# 误报测试:consent 页含 "phone number" 帮助文字 + footer tel input,但应判 False
+def make_consent_with_phone_link():
+    page = MagicMock()
+    page.url = "https://auth.openai.com/authorize/consent"
+    page.inner_text.return_value = "if you have issues, call our phone support number"
+    tel_input = MagicMock()
+    tel_input.is_visible.return_value = False  # 实际页上没有可见 tel input
+    page.locator.return_value.first = tel_input
+    return page
+```
+
+### 6.2 单测代码
+
+```python
+# tests/unit/test_oauth_phone_detection.py
+import pytest
+from autoteam.invite import RegisterBlocked, assert_not_blocked, detect_phone_verification
+from tests.fixtures.oauth_phone_pages import (
+    make_phone_page, make_consent_page, make_about_you_page, make_consent_with_phone_link,
+)
+
+
+def test_url_hint_strong_signal():
+    """URL 含 add-phone → 立即判 True,不需要 tel input"""
+    page = make_phone_page(url="https://auth.openai.com/verify-phone", body_text="", has_tel_input=False)
+    assert detect_phone_verification(page) is True
+
+
+def test_text_hint_requires_tel_input():
+    """文本命中但无 tel input → 不阻塞(避免帮助文字误报)"""
+    page = make_consent_with_phone_link()
+    assert detect_phone_verification(page) is False
+
+
+def test_text_hint_with_tel_input():
+    """文本命中 + tel input 可见 → 判 True"""
+    page = make_phone_page(
+        url="https://auth.openai.com/authorize",
+        body_text="add your phone number to continue",
+        has_tel_input=True,
+    )
+    assert detect_phone_verification(page) is True
+
+
+def test_assert_not_blocked_raises_on_phone():
+    page = make_phone_page()
+    with pytest.raises(RegisterBlocked) as exc_info:
+        assert_not_blocked(page, "oauth_about_you")
+    assert exc_info.value.is_phone is True
+    assert exc_info.value.step == "oauth_about_you"
+
+
+def test_assert_not_blocked_passes_on_consent():
+    page = make_consent_page()
+    assert_not_blocked(page, "oauth_consent_0")  # 不抛
+
+
+def test_about_you_page_does_not_trigger():
+    """about-you 页应当通过(避免在过早位点误报)"""
+    page = make_about_you_page()
+    assert detect_phone_verification(page) is False
+```
+
+### 6.3 集成测试样本
+
+```python
+# tests/integration/test_oauth_phone_blocked_flow.py
+from unittest.mock import patch
+from autoteam.invite import RegisterBlocked
+from autoteam.manager import _run_post_register_oauth
+
+
+def test_post_register_oauth_team_phone_blocked():
+    """Team 模式 OAuth 命中 add-phone → 标 STATUS_AUTH_INVALID + record_failure"""
+    with patch("autoteam.manager.login_codex_via_browser") as mock_login:
+        mock_login.side_effect = RegisterBlocked("oauth_consent_2", "add-phone", is_phone=True)
+        with patch("autoteam.manager.record_failure") as mock_rec:
+            _run_post_register_oauth("test@example.com", "pwd", mail_client=None, leave_workspace=False)
+            mock_rec.assert_called_with(
+                "test@example.com",
+                category="oauth_phone_blocked",
+                reason=pytest.approx("OAuth 阶段触发 add-phone (step=oauth_consent_2)"),
+                step="oauth_consent_2",
+                stage="run_post_register_oauth_team",
+                url=None,
+            )
+
+
+def test_reinvite_account_phone_blocked_kicks_team_leftover():
+    """reinvite 命中 add-phone → _cleanup_team_leftover + STATUS_AUTH_INVALID(不进 STANDBY)"""
+    # 略,见 spec-2-account-lifecycle.md §5
+```
+
+---
+
+## 7. 不变量(Invariants)
+
+- **I1**:`assert_not_blocked` 在 `login_codex_via_browser` 内被调用时,任何已有的 `try/except Exception` 块**禁止**吞掉 `RegisterBlocked`(必须显式 `except RegisterBlocked: raise`)
+- **I2**:5 个 login_codex_via_browser 调用方**必须**显式 `except RegisterBlocked`,不允许让异常裸奔到 cmd_fill 等顶层
+- **I3**:`record_failure` 中 `category="oauth_phone_blocked"` 的记录**必须**携带 `step` 和 `stage` 字段(用于事后统计)
+- **I4**:add-phone 命中后,调用方**必须**先调 `_screenshot(page, f"codex_phone_blocked_{step}.png")`(在 raise 之前),否则页面 close 后无法回放
+- **I5**:`detect_phone_verification` 不能改成"无 tel input 也判 True":会让 OAuth consent 页含 phone 帮助链接的场景大量误报
+- **I6**:OAuth 流程的 RegisterBlocked 不重试 — 命中即放弃账号(用户硬要求"不要脱离原本流程太多");任何"撞了再试一次"的逻辑都属于范围外
+- **I7**:`STATUS_PHONE_REQUIRED` 不新增到 `accounts.py`;复用 `STATUS_AUTH_INVALID` + `register_failures.category` 区分
+
+---
+
+## 附录 A:误报回放与运营校准
+
+每次 `oauth_phone_blocked` 命中后:
+1. 截图保存 `screenshots/codex_phone_blocked_{step}_{ts}.png`
+2. `register_failures.json` 记录 `step` / `stage` / `url` / `email`
+3. 运营定期(每周)抽样回放,确认未发生误报
+4. 如发现误报集中在某 step:补充 `_OAUTH_PHONE_TEXT_HINTS` 排除规则,而非全局放宽
+
+---
+
+**文档结束。** 工程师据此可直接编写 4 处 `assert_not_blocked` 接入 + 5 处调用方 try/except + 单元/集成测试,无需额外决策。

prompts/0426/spec/shared/plan-type-whitelist.md

@@ -0,0 +1,327 @@
+# Shared SPEC: plan_type 白名单
+
+## 0. 元数据 + 引用方
+
+| 字段 | 内容 |
+|---|---|
+| 名称 | plan_type 白名单与不支持套餐处置 |
+| 版本 | v1.0 (2026-04-26) |
+| 主题归属 | OAuth bundle 解析 + 账号入池前置校验 |
+| 引用方 | PRD-2 / spec-2-account-lifecycle.md / FR-A1~A5 |
+| 共因 | synthesis §1 共因 A;Issue#2 + Issue#6 |
+| 不在范围 | seat_type 决策(见 PRD-2 FR-F1~F6)、quota 分类(见 [`./quota-classification.md`](./quota-classification.md)) |
+
+---
+
+## 1. 概念定义
+
+| 术语 | 定义 |
+|---|---|
+| `plan_type` | OpenAI 在 OAuth id_token JWT claim `https://api.openai.com/auth.chatgpt_plan_type` 中下发的字符串字面量,标识当前 workspace 的套餐类型 |
+| `SUPPORTED_PLAN_TYPES` | 本系统能够正确处理(注册→入池→Codex 调用)的 plan_type 集合 |
+| `unsupported plan_type` | 出现在 OAuth bundle 中但不在白名单内的字面量,例如 `self_serve_business_usage_based`、`enterprise` |
+| `plan_type_raw` | 落盘到 `accounts.json` 的原始字面量(.lower() 后),用于事后排查 |
+| `plan_supported` | 落盘到 `accounts.json` 的布尔值,反映当时 OAuth bundle 是否在白名单内 |
+
+---
+
+## 2. 完整数据契约
+
+### 2.1 常量集(置于 `src/autoteam/accounts.py`)
+
+```python
+# accounts.py 顶部新增
+SUPPORTED_PLAN_TYPES: frozenset[str] = frozenset({
+    "team",   # ChatGPT Team workspace,本系统主要工作池
+    "free",   # 已退出 Team 的个人 free,personal 子号路径
+    "plus",   # 个人付费,允许通过 manual_account 手动添加
+    "pro",    # 个人 Pro,同上
+})
+"""
+支持的 plan_type 白名单。
+
+不在此集合内的字面量(如 self_serve_business_usage_based / enterprise / unknown)
+均视为 unsupported,触发 STATUS_AUTH_INVALID + register_failures.category="plan_unsupported"。
+
+新增字面量需经过测试验证(quota 是否能正常拉取、Codex 调用是否能用)后再加入白名单。
+"""
+```
+
+### 2.2 工具函数
+
+```python
+# accounts.py 紧随常量定义之后
+def is_supported_plan(plan_type: str | None) -> bool:
+    """判定 plan_type 是否在白名单内。
+
+    None / 空串 / "unknown" 一律返回 False。
+    比对前先 .lower().strip(),避免 OpenAI 后端大小写漂移。
+    """
+    if not plan_type:
+        return False
+    return plan_type.strip().lower() in SUPPORTED_PLAN_TYPES
+
+
+def normalize_plan_type(plan_type: str | None) -> str:
+    """归一化用于落盘 / 比对的 plan_type。
+
+    None → "unknown",其余统一 .lower().strip()。
+    """
+    if not plan_type:
+        return "unknown"
+    return plan_type.strip().lower()
+```
+
+### 2.3 OAuth bundle 字段扩展(`codex_auth.py:_exchange_auth_code` L100-116)
+
+```python
+# 现有
+bundle = {
+    "access_token": ...,
+    "refresh_token": ...,
+    "id_token": ...,
+    "account_id": ...,
+    "email": ...,
+    "plan_type": auth_claims.get("chatgpt_plan_type", "unknown"),
+    "expired": ...,
+}
+
+# 新增字段(在已有字段之后追加,不破坏旧字段)
+bundle["plan_type_raw"] = bundle["plan_type"]            # 原始字面量,事后排查用
+bundle["plan_type"] = normalize_plan_type(bundle["plan_type"])  # 归一化后的小写值
+bundle["plan_supported"] = is_supported_plan(bundle["plan_type"])
+```
+
+---
+
+## 3. 行为契约
+
+### 3.1 函数签名
+
+```python
+def is_supported_plan(plan_type: str | None) -> bool: ...
+def normalize_plan_type(plan_type: str | None) -> str: ...
+```
+
+### 3.2 前置条件
+
+- 调用 `is_supported_plan` 不要求参数已 lower(函数内会处理)
+- `SUPPORTED_PLAN_TYPES` 是 `frozenset`,运行时不可修改
+- 任何对 `bundle["plan_type"]` 的判定**必须**先经过 `normalize_plan_type` 或 `is_supported_plan`
+
+### 3.3 后置条件
+
+- `normalize_plan_type(None) == "unknown"`,`normalize_plan_type("Team") == "team"`
+- `is_supported_plan` 不抛异常(对任何输入都给出布尔值)
+- bundle 含 `plan_supported` 字段后,所有下游消费方应只读该字段而非自己 .lower() 比对
+
+### 3.4 异常类型
+
+- 工具函数本身不抛异常
+- 触发 unsupported 的下游处置依赖 `register_failures.record_failure`,该函数不向外抛异常
+
+---
+
+## 4. 决策矩阵
+
+### 4.1 OAuth bundle 检查 → 处置矩阵
+
+| 场景 | bundle["plan_type"] | bundle["plan_supported"] | 处置 |
+|---|---|---|---|
+| Team 注册成功 | "team" | True | 沿用现行流程 → STATUS_ACTIVE(配额另判,见 quota-classification.md) |
+| Personal OAuth 成功 | "free" | True | 沿用现行流程 → STATUS_PERSONAL |
+| 手动添加 Plus 号 | "plus" | True | manual_account 走 STATUS_STANDBY(plus 无 Team 调度) |
+| 手动添加 Pro 号 | "pro" | True | 同 plus |
+| **新计费 workspace** | "self_serve_business_usage_based" | False | **STATUS_AUTH_INVALID + record_failure("plan_unsupported")** |
+| **企业版 workspace** | "enterprise" | False | 同上 |
+| JWT 缺 claim | "unknown" | False | 同上(标 plan_unsupported,理由是无法判定) |
+| **��写漂移** | "Team" → 归一为 "team" | True | 与 team 等价 |
+
+### 4.2 6 个调用点处置矩阵
+
+| 调用点 | 文件:行号 | 旧处置 | 新处置 |
+|---|---|---|---|
+| 1. OAuth bundle 落盘 | `codex_auth.py:111` | 直接落 `plan_type` | 落 `plan_type_raw` + `plan_type` + `plan_supported` |
+| 2. 手动添加完成 | `manual_account.py:233` | `if plan_type == "team"` 二元分支 | `if not bundle["plan_supported"]` → STATUS_AUTH_INVALID + record_failure;否则按 plan_type 走原 seat_type 决策 |
+| 3. Team 注册收尾 | `manager.py:1467-1478` | `seat_label = "chatgpt" if bundle_plan == "team" else "codex"` | 先判 `plan_supported`,False → STATUS_AUTH_INVALID + record_failure;True 时再判 plan_type 决定 seat |
+| 4. personal 注册收尾 | `manager.py:1431-1460`(use_personal=True 分支) | `if plan_type != "free": delete + oauth_failed` | `if not plan_supported` 优先级最高 → record_failure("plan_unsupported");其次保留 plan != "free" 的拒收 |
+| 5. reinvite_account 校验 | `manager.py:2489-2494` | `plan_type != "team": _cleanup + STANDBY` | 增加一道 `plan_supported` 判定:False → STATUS_AUTH_INVALID + record_failure("plan_unsupported");True 但 plan != "team" → 沿用 plan_drift 路径 |
+| 6. cpa_sync 文件名推断 | `cpa_sync.py:132-140` | `team / plus / free` 子串 | 不改判定逻辑,但记录到的 plan_type 走 normalize_plan_type |
+
+---
+
+## 5. 调用方处置规范
+
+### 5.1 共通原则
+
+```python
+# 任何 OAuth bundle 消费方都必须按这个顺序检查
+if not bundle.get("plan_supported"):
+    record_failure(
+        email,
+        category="plan_unsupported",
+        reason=f"OAuth bundle plan_type={bundle.get('plan_type_raw')} 不在白名单",
+        plan_type=bundle.get("plan_type"),
+        plan_type_raw=bundle.get("plan_type_raw"),
+        stage=<调用点名称>,
+    )
+    update_account(email, status=STATUS_AUTH_INVALID, plan_type_raw=bundle.get("plan_type_raw"))
+    return None  # 或上游约定的失败值
+```
+
+### 5.2 各调用方差异
+
+| 调用方 | 差异处置 |
+|---|---|
+| `manual_account._finalize_account` | unsupported → 不写 last_quota / auth_file 不删(保留供人工排查) |
+| `manager._run_post_register_oauth` (Team) | unsupported + bundle 已成功 → kick 该 email 出 Team(避免占席位)+ STATUS_AUTH_INVALID |
+| `manager._run_post_register_oauth` (personal) | unsupported → delete_account + record_failure(因为已 leave_workspace,本地无价值) |
+| `manager.reinvite_account` | unsupported → `_cleanup_team_leftover("plan_unsupported")` + STATUS_AUTH_INVALID + auth_file=None |
+
+---
+
+## 6. 单元测试 fixture 与样本数据
+
+### 6.1 输入样本(yaml)
+
+```yaml
+# tests/fixtures/plan_type_samples.yaml
+supported:
+  - input: "team"
+    expected_supported: true
+    expected_normalized: "team"
+  - input: "Team"
+    expected_supported: true
+    expected_normalized: "team"
+  - input: "FREE"
+    expected_supported: true
+    expected_normalized: "free"
+  - input: "  plus  "
+    expected_supported: true
+    expected_normalized: "plus"
+  - input: "pro"
+    expected_supported: true
+    expected_normalized: "pro"
+
+unsupported:
+  - input: "self_serve_business_usage_based"
+    expected_supported: false
+    expected_normalized: "self_serve_business_usage_based"
+  - input: "chatgpt_business_usage_based"
+    expected_supported: false
+    expected_normalized: "chatgpt_business_usage_based"
+  - input: "enterprise"
+    expected_supported: false
+    expected_normalized: "enterprise"
+  - input: "unknown"
+    expected_supported: false
+    expected_normalized: "unknown"
+  - input: ""
+    expected_supported: false
+    expected_normalized: "unknown"
+  - input: null
+    expected_supported: false
+    expected_normalized: "unknown"
+```
+
+### 6.2 完整测试用例
+
+```python
+# tests/unit/test_plan_type_whitelist.py
+import pytest
+import yaml
+from pathlib import Path
+from autoteam.accounts import is_supported_plan, normalize_plan_type, SUPPORTED_PLAN_TYPES
+
+FIXTURE = yaml.safe_load(Path("tests/fixtures/plan_type_samples.yaml").read_text())
+
+
+@pytest.mark.parametrize("case", FIXTURE["supported"])
+def test_supported_plan_types(case):
+    assert is_supported_plan(case["input"]) is True
+    assert normalize_plan_type(case["input"]) == case["expected_normalized"]
+
+
+@pytest.mark.parametrize("case", FIXTURE["unsupported"])
+def test_unsupported_plan_types(case):
+    assert is_supported_plan(case["input"]) is False
+    assert normalize_plan_type(case["input"]) == case["expected_normalized"]
+
+
+def test_whitelist_contains_only_lowercase():
+    """SUPPORTED_PLAN_TYPES 不能含大写,否则 is_supported_plan 比对会失败"""
+    for plan in SUPPORTED_PLAN_TYPES:
+        assert plan == plan.lower(), f"{plan} 必须全小写"
+
+
+def test_whitelist_is_frozen():
+    """SUPPORTED_PLAN_TYPES 必须是 frozenset,运行时不可变"""
+    assert isinstance(SUPPORTED_PLAN_TYPES, frozenset)
+```
+
+### 6.3 OAuth bundle 集成 fixture
+
+```json
+{
+  "bundle_team_supported": {
+    "access_token": "sk-***",
+    "refresh_token": "rt-***",
+    "id_token": "ey***",
+    "account_id": "acc-12345",
+    "email": "test@example.com",
+    "plan_type": "team",
+    "plan_type_raw": "team",
+    "plan_supported": true,
+    "expired": 1714123200.0
+  },
+  "bundle_self_serve_business": {
+    "access_token": "sk-***",
+    "refresh_token": "rt-***",
+    "id_token": "ey***",
+    "account_id": "acc-67890",
+    "email": "test2@example.com",
+    "plan_type": "self_serve_business_usage_based",
+    "plan_type_raw": "self_serve_business_usage_based",
+    "plan_supported": false,
+    "expired": 1714123200.0
+  },
+  "bundle_unknown": {
+    "access_token": "sk-***",
+    "refresh_token": "rt-***",
+    "id_token": "ey***",
+    "account_id": "acc-99999",
+    "email": "test3@example.com",
+    "plan_type": "unknown",
+    "plan_type_raw": "unknown",
+    "plan_supported": false,
+    "expired": 1714123200.0
+  }
+}
+```
+
+---
+
+## 7. 不变量(Invariants)
+
+- **I1**:任何对 plan_type 的字符串判定必须经过 `normalize_plan_type` 或 `is_supported_plan`,**禁止**直接 `bundle["plan_type"] == "team"`
+- **I2**:`bundle["plan_type"]` 落盘后必为小写或 "unknown",`plan_type_raw` 保留原始字面量
+- **I3**:`SUPPORTED_PLAN_TYPES` 修改必须经过测试评审(新增字面量代表新的 quota / seat 行为分支)
+- **I4**:任何 unsupported plan_type 的账号都不能进入 STATUS_ACTIVE,只能在 STATUS_AUTH_INVALID / STATUS_PENDING / STATUS_STANDBY 中
+- **I5**:cpa_sync 文件名推断与 OAuth bundle 提取的 plan_type 应保持一致(同一字面量集合)
+- **I6**:`plan_type_unsupported` 字段名**不**新增到 accounts.json(改用 `plan_supported` 反向语义,默认 None=旧记录)
+
+---
+
+## 附录 A:已知不支持的字面量(运营观测)
+
+| 字面量 | 来源 | OpenAI 定义 |
+|---|---|---|
+| `self_serve_business_usage_based` | 用户报告 #2/#6 | 自助商用按量计费,无 codex 配额 |
+| `chatgpt_business_usage_based` | 推测 | 同上变体 |
+| `enterprise` | OpenAI 公开文档 | 企业版,通常需要单独签约 |
+| `edu` | OpenAI 公开文档 | 教育版 |
+| `unknown` | JWT claim 缺失 | 无法判定,默认拒收 |
+
+---
+
+**文档结束。** 工程师据此可直接编写常量集 + 工具函数 + 单测,无需额外决策。

prompts/0426/spec/shared/quota-classification.md

@@ -0,0 +1,410 @@
+# Shared SPEC: wham/usage 配额分类
+
+## 0. 元数据 + 引用方
+
+| 字段 | 内容 |
+|---|---|
+| 名称 | Codex 配额查询(wham/usage)五分类规则 |
+| 版本 | v1.0 (2026-04-26) |
+| 主题归属 | `check_codex_quota` 返回值契约 + 9 个调用方处置 |
+| 引用方 | PRD-2 / spec-2-account-lifecycle.md / FR-B1~B4、FR-D1~D4、FR-E1 |
+| 共因 | synthesis §1 共因 B、D;Issue#2 + Issue#6 |
+| 不在范围 | refresh_token 刷新(`refresh_access_token`)、auth_file 写入(`save_auth_file`)、plan_type 白名单(见 [`./plan-type-whitelist.md`](./plan-type-whitelist.md)) |
+
+---
+
+## 1. 概念定义
+
+| 术语 | 定义 |
+|---|---|
+| `wham/usage` | OpenAI 后端接口 `https://chatgpt.com/backend-api/wham/usage`,返回当前 access_token 对应账号的 Codex 配额状态 |
+| `quota_status` | 本系统对 wham/usage 调用结果的 5 类归一化:`ok / exhausted / no_quota / auth_error / network_error` |
+| `quota_info` / `QuotaSnapshot` | 落盘到 `accounts.json` 的配额快照,字段:`primary_pct`、`primary_resets_at`、`primary_total`、`primary_remaining`、`weekly_pct`、`weekly_resets_at` |
+| `no_quota`(新) | "workspace 已分配但 codex 配额=0"形态 — used_percent=0 但 limit/total=0,UI 不应显示"剩余 100%" |
+| `limit_reached` | OpenAI 返回 `rate_limit.limit_reached: true`,与 `primary_pct >= 100` 等价 |
+
+---
+
+## 2. 完整数据契约
+
+### 2.1 类型定义(置于 `src/autoteam/codex_auth.py` 顶部 typing 区)
+
+```python
+from typing import Literal, Optional, TypedDict, Union
+
+QuotaStatus = Literal["ok", "exhausted", "no_quota", "auth_error", "network_error"]
+
+
+class QuotaSnapshot(TypedDict, total=False):
+    """落盘到 accounts.json 的 last_quota 字段结构。
+
+    所有字段都允许缺失(向后兼容旧记录),消费方需用 .get(...) 取值。
+    """
+    primary_pct: int           # 0..100,主配额已用百分比
+    primary_resets_at: int     # epoch seconds,主配额重置时间;0 表示未知
+    primary_total: int         # 主配额总额(令牌或请求数);0 表示 no_quota
+    primary_remaining: int     # 主配额剩余值(若 OpenAI 返回)
+    weekly_pct: int            # 周配额已用百分比
+    weekly_resets_at: int      # 周配额重置时间
+
+
+class QuotaExhaustedInfo(TypedDict):
+    """get_quota_exhausted_info 的返回结构。"""
+    window: Literal["primary", "weekly", "combined", "limit", "no_quota"]
+    resets_at: int             # epoch seconds,何时可重试
+    quota_info: QuotaSnapshot
+    limit_reached: bool
+
+
+# check_codex_quota 返回类型
+QuotaProbeResult = tuple[QuotaStatus, Optional[Union[QuotaSnapshot, QuotaExhaustedInfo]]]
+```
+
+### 2.2 函数签名(实施期目标)
+
+```python
+def check_codex_quota(
+    access_token: str,
+    account_id: Optional[str] = None,
+) -> QuotaProbeResult:
+    """通过 wham/usage 探测 Codex 配额状态。
+
+    返回 (status, info):
+      ("ok", QuotaSnapshot)             — 200 + 配额可用
+      ("exhausted", QuotaExhaustedInfo) — 200 + 主/周配额耗尽
+      ("no_quota", QuotaExhaustedInfo)  — 200 + 配额总额=0(workspace 未分配)  ★新增
+      ("auth_error", None)              — 401/403,token/seat 失效
+      ("network_error", None)           — DNS/timeout/SSL/5xx/429/JSON 解析异常
+    """
+
+
+def get_quota_exhausted_info(
+    quota_info: QuotaSnapshot,
+    *,
+    limit_reached: bool = False,
+) -> Optional[QuotaExhaustedInfo]:
+    """根据 QuotaSnapshot 判断是否耗尽,返回耗尽详情或 None。
+
+    新增:primary_total == 0 → 返回 window="no_quota" 形态。
+    """
+```
+
+### 2.3 落盘字段扩展
+
+```python
+# accounts.json 中 acc.last_quota 的字段集(QuotaSnapshot)
+{
+  "primary_pct": int,
+  "primary_resets_at": int,
+  "primary_total": int,        # 新增,FR-B2
+  "primary_remaining": int,    # 新增,FR-B2(可缺失)
+  "weekly_pct": int,
+  "weekly_resets_at": int
+}
+```
+
+---
+
+## 3. 行为契约
+
+### 3.1 前置条件
+
+- `access_token` 非空字符串(空串短路返回 `("auth_error", None)`)
+- `account_id` 可选;若为 None,内部从 `get_chatgpt_account_id()` 拉取
+- 调用方在并发场景下需要自己控制并发数(本函数无 rate limit)
+
+### 3.2 后置条件
+
+- 返回元组永远 2 元素,第 1 元素永远是 5 个字面量之一
+- `("ok", info)` 时,info 必为 QuotaSnapshot
+- `("exhausted", info)` / `("no_quota", info)` 时,info 必为 QuotaExhaustedInfo
+- `("auth_error", None)` / `("network_error", None)` 时,info 必为 None
+- 函数永不抛异常(所有异常归为 `network_error`)
+
+### 3.3 异常类型
+
+| 实际异常 | 归类 |
+|---|---|
+| `requests.exceptions.ConnectionError` | network_error |
+| `requests.exceptions.Timeout` | network_error |
+| `requests.exceptions.SSLError` | network_error |
+| `requests.exceptions.RequestException`(其它) | network_error |
+| HTTP 401 / 403 | auth_error |
+| HTTP 429 / 5xx | network_error |
+| HTTP 4xx(非 401/403/429) | network_error |
+| JSON 解析失败 | network_error |
+| 任意 `Exception` 兜底 | network_error |
+
+**不变量**:`auth_error` 与 `network_error` 严格区分,前者会触发"标记 AUTH_INVALID/重登"等破坏性流程,网络抖动绝不能落入该分支。
+
+---
+
+## 4. 分类规则(决策矩阵)
+
+### 4.1 HTTP 状态 → 分类
+
+```
+┌──────────────────┬──────────────────┐
+│ HTTP / 异常       │ 分类              │
+├──────────────────┼──────────────────┤
+│ 200 OK + 解析成功 │ → 看下表 4.2     │
+│ 401 / 403         │ auth_error        │
+│ 429               │ network_error     │
+│ 5xx               │ network_error     │
+│ 其他 4xx          │ network_error     │
+│ Connection/Timeout│ network_error     │
+│ JSON 解析异常     │ network_error     │
+│ 未知 Exception    │ network_error(兜底)│
+└──────────────────┴──────────────────┘
+```
+
+### 4.2 200 OK 内部分类(关键)
+
+按**优先级从高到低**判定(命中即返回):
+
+```
+┌──────────────────────────────────────────────┬──────────────┐
+│ 触发条件(任一命中)                            │ 分类         │
+├──────────────────────────────────────────────┼──────────────┤
+│ rate_limit 字段缺失或为空                     │ no_quota     │
+│ rate_limit.primary_window 字段缺失或为空      │ no_quota     │
+│ primary.limit == 0(显式 0)                  │ no_quota     │
+│ primary.total == 0                            │ no_quota     │
+│ primary.reset_at == 0 AND used_percent == 0   │ no_quota     │
+│ primary.remaining == 0 AND total == 0         │ no_quota     │
+│ rate_limit.limit_reached == true              │ exhausted    │
+│ primary_pct >= 100                            │ exhausted    │
+│ weekly_pct >= 100                             │ exhausted    │
+│ 上述都不命中                                  │ ok           │
+└──────────────────────────────────────────────┴──────────────┘
+```
+
+### 4.3 `no_quota` 与 `exhausted` 的语义区分
+
+| 维度 | exhausted | no_quota |
+|---|---|---|
+| 触发前提 | 配额本来有但已用完 | workspace 从未被分配配额 |
+| primary_pct | 100 | 0(或缺失) |
+| primary_total | > 0 | 0(或缺失) |
+| 用户操作 | 等待 reset_at 后自然恢复 | 需要管理员介入(配额从来没有) |
+| UI 文案 | "已耗尽,X 小时后恢复" | "无配额,联系管理员" |
+| 是否 retry | 5h 后 retry | **不**自动 retry,直接终态 |
+
+---
+
+## 5. 调用方处置规范(9 个调用点)
+
+### 5.1 调用点清单
+
+| # | 文件:行号 | 函数/上下文 |
+|---|---|---|
+| 1 | `manual_account.py:263` | `_finalize_account` 手动添加完成 |
+| 2 | `manager.py:715` | `cmd_check` 巡检 |
+| 3 | `manager.py:748` | `cmd_check` 失败重试 |
+| 4 | `manager.py:760` | `cmd_check` refresh_token 后重测 |
+| 5 | `manager.py:2521` | `reinvite_account` 假恢复检测 |
+| 6 | `manager.py:2683` | `_replace_single` 后续验证 |
+| 7 | `manager.py:2964` | rotation 周期检查 |
+| 8 | `api.py:1499` | `/api/accounts/{email}/login` 补登录 |
+| 9 | `api.py:1558`、`api.py:2136` | API 端点直接验配额 |
+| 10 | **新增** `manager.py:_run_post_register_oauth` | FR-D1 注册收尾 probe |
+| 11 | **新增** `manager.py:sync_account_states` | FR-E1 被踢识别 |
+
+### 5.2 9+2 调用方统一处置矩阵
+
+| status | 处置 | last_quota 是否更新 | 状态变更 |
+|---|---|---|---|
+| `ok` | 沿用现有逻辑(STATUS_ACTIVE) | 写入 quota_info | 无变更或→ ACTIVE |
+| `exhausted` | 锁 5h 等恢复 | 写入(从 info["quota_info"]) | → STATUS_EXHAUSTED + quota_exhausted_at + quota_resets_at |
+| `no_quota`(新) | **不**锁 5h(不会自然恢复) | 写入 + 标 primary_total=0 | → STATUS_AUTH_INVALID + record_failure("no_quota_assigned") |
+| `auth_error` | 触发重登 / KICK 路径 | 不更新 | → STATUS_AUTH_INVALID(reconcile 接管) |
+| `network_error` | 不动 status,等下轮 | 不更新 | 保持原状态 |
+
+### 5.3 各调用点差异
+
+| 调用点 | 特殊处置 |
+|---|---|
+| `manual_account.py:263` | no_quota → `update_account(status=STATUS_AUTH_INVALID, last_quota=info["quota_info"])` + 不删 auth_file(保留供调试) |
+| `manager.py:_run_post_register_oauth` (新) | no_quota → 与 manual_account 对称,但额外触发 kick(账号已在 Team) |
+| `manager.py:sync_account_states` (新) | auth_error → `STATUS_AUTH_INVALID`(替换原 STATUS_STANDBY 行为) |
+| `manager.py:reinvite_account:2521` | no_quota → 走 `_cleanup_team_leftover("no_quota_assigned")` + STATUS_AUTH_INVALID,不进 STANDBY 池(避免反复试) |
+| `api.py:1499` | no_quota → 返回 HTTP 422 + body `{"error": "no_quota_assigned", "plan_type": ...}` |
+
+### 5.4 auto-check 阈值与 quota_verified 联动
+
+`reinvite_account:2528-2530` 用 `100 - primary_pct >= threshold`(默认 10%)判 quota_verified:
+- `no_quota` 分支:不进入 quota_verified 判断,直接 fail_reason="no_quota_assigned",`_cleanup_team_leftover`
+- `ok` 分支保持 threshold 判定不变
+
+---
+
+## 6. 单元测试 fixture 与样本数据
+
+### 6.1 wham/usage 响应样本(json)
+
+```json
+// tests/fixtures/wham_usage_responses.json
+{
+  "ok_normal": {
+    "status_code": 200,
+    "body": {
+      "rate_limit": {
+        "primary_window": {"used_percent": 35, "reset_at": 1714200000, "limit": 100, "remaining": 65},
+        "secondary_window": {"used_percent": 10, "reset_at": 1714780800}
+      }
+    }
+  },
+  "exhausted_primary": {
+    "status_code": 200,
+    "body": {
+      "rate_limit": {
+        "limit_reached": true,
+        "primary_window": {"used_percent": 100, "reset_at": 1714200000, "limit": 100, "remaining": 0},
+        "secondary_window": {"used_percent": 50, "reset_at": 1714780800}
+      }
+    }
+  },
+  "exhausted_weekly": {
+    "status_code": 200,
+    "body": {
+      "rate_limit": {
+        "primary_window": {"used_percent": 30, "reset_at": 1714200000, "limit": 100, "remaining": 70},
+        "secondary_window": {"used_percent": 100, "reset_at": 1714780800}
+      }
+    }
+  },
+  "no_quota_limit_zero": {
+    "status_code": 200,
+    "body": {
+      "rate_limit": {
+        "primary_window": {"used_percent": 0, "reset_at": 0, "limit": 0, "remaining": 0},
+        "secondary_window": {"used_percent": 0, "reset_at": 0}
+      }
+    }
+  },
+  "no_quota_empty_rate_limit": {
+    "status_code": 200,
+    "body": {}
+  },
+  "no_quota_missing_primary": {
+    "status_code": 200,
+    "body": {
+      "rate_limit": {
+        "secondary_window": {"used_percent": 0, "reset_at": 0}
+      }
+    }
+  },
+  "auth_error_401": {
+    "status_code": 401,
+    "body": {"error": {"code": "invalid_token"}}
+  },
+  "auth_error_403": {
+    "status_code": 403,
+    "body": {"error": {"code": "forbidden"}}
+  },
+  "rate_limited_429": {
+    "status_code": 429,
+    "body": {"error": "Too Many Requests"}
+  },
+  "server_error_500": {
+    "status_code": 500,
+    "body": {"error": "Internal Server Error"}
+  },
+  "json_invalid": {
+    "status_code": 200,
+    "body": "<html>Service Unavailable</html>"
+  }
+}
+```
+
+### 6.2 单测代码
+
+```python
+# tests/unit/test_quota_classification.py
+import json
+import pytest
+from unittest.mock import patch, MagicMock
+from autoteam.codex_auth import check_codex_quota, get_quota_exhausted_info
+
+FIXTURE = json.loads(Path("tests/fixtures/wham_usage_responses.json").read_text())
+
+
+@pytest.mark.parametrize("name,expected_status", [
+    ("ok_normal", "ok"),
+    ("exhausted_primary", "exhausted"),
+    ("exhausted_weekly", "exhausted"),
+    ("no_quota_limit_zero", "no_quota"),
+    ("no_quota_empty_rate_limit", "no_quota"),
+    ("no_quota_missing_primary", "no_quota"),
+    ("auth_error_401", "auth_error"),
+    ("auth_error_403", "auth_error"),
+    ("rate_limited_429", "network_error"),
+    ("server_error_500", "network_error"),
+    ("json_invalid", "network_error"),
+])
+def test_check_codex_quota_classification(name, expected_status):
+    sample = FIXTURE[name]
+    mock_resp = MagicMock()
+    mock_resp.status_code = sample["status_code"]
+    if isinstance(sample["body"], str):
+        mock_resp.json.side_effect = ValueError("not JSON")
+        mock_resp.text = sample["body"]
+    else:
+        mock_resp.json.return_value = sample["body"]
+        mock_resp.text = json.dumps(sample["body"])
+
+    with patch("autoteam.codex_auth.requests.get", return_value=mock_resp):
+        status, _ = check_codex_quota("test-token", account_id="acc-1")
+        assert status == expected_status
+
+
+def test_no_quota_includes_quota_info():
+    """no_quota 分类必须返回 QuotaExhaustedInfo,info["window"] == "no_quota" """
+    sample = FIXTURE["no_quota_limit_zero"]
+    mock_resp = MagicMock()
+    mock_resp.status_code = 200
+    mock_resp.json.return_value = sample["body"]
+    with patch("autoteam.codex_auth.requests.get", return_value=mock_resp):
+        status, info = check_codex_quota("test-token")
+        assert status == "no_quota"
+        assert isinstance(info, dict)
+        assert info["window"] == "no_quota"
+        assert info["quota_info"]["primary_total"] == 0
+
+
+def test_exhausted_uses_existing_window_label():
+    """exhausted 分支不能误标为 no_quota"""
+    sample = FIXTURE["exhausted_primary"]
+    mock_resp = MagicMock()
+    mock_resp.status_code = 200
+    mock_resp.json.return_value = sample["body"]
+    with patch("autoteam.codex_auth.requests.get", return_value=mock_resp):
+        status, info = check_codex_quota("test-token")
+        assert status == "exhausted"
+        assert info["window"] in ("primary", "combined")
+```
+
+---
+
+## 7. 不变量(Invariants)
+
+- **I1**:`check_codex_quota` 永不抛异常(任何异常归为 network_error 返回)
+- **I2**:`auth_error` 与 `network_error` 严格区分,401/403 是 auth_error 唯一来源,**429 不能落入 auth_error**
+- **I3**:`no_quota` 必须返回 `QuotaExhaustedInfo` 结构,`window` 字段值为 `"no_quota"`(便于上游分支判定)
+- **I4**:`get_quota_exhausted_info` 中 `primary_total == 0` 优先级**高于** `primary_pct >= 100`(no_quota 优先于 exhausted)
+- **I5**:`last_quota` 字段更新仅在 ok / exhausted / no_quota 情况发生;auth_error / network_error 不更新(避免脏数据)
+- **I6**:`exhausted` 与 `no_quota` 的 reset_at 语义不同:exhausted 给真实重置时间,no_quota 给 `time.time() + 86400`(占位,不应被用作重试依据)
+- **I7**:9+2 个调用点必须**显式**处理 `no_quota` 分支,不能让 `no_quota` 走默认 `else` 路径被当作 ok / exhausted
+
+---
+
+## 附录 A:wham/usage 真实 schema 待核实
+
+PRD-2 Q-1 列出未决:`limit` / `total` / `remaining` 字段是否真实返回需要从用户实际抓包确认。**实施期约定**:
+1. 先按本 spec 实现 4 个 no_quota 触发条件
+2. 上线后通过 `register_failures.json` 的 `category="no_quota_assigned"` 计数,每条记录附 `raw_rate_limit` 字段以便回溯
+3. 1-2 周后根据数据决议是否需要补充新的 no_quota 触发条件
+
+---
+
+**文档结束。** 工程师据此可直接编写 `check_codex_quota` 改造 + `get_quota_exhausted_info` 扩展 + 9+2 调用点的处置代码,无需额外决策。

prompts/0426/spec/spec-1-mail-provider.md

@@ -0,0 +1,1045 @@
+# SPEC-1: Mail Provider 全量化 实施规范
+
+## 0. 元数据
+
+| 字段       | 值                                                                                  |
+| ---------- | ----------------------------------------------------------------------------------- |
+| 版本       | v1.0                                                                                |
+| 日期       | 2026-04-26                                                                          |
+| 主笔       | prd-mail                                                                            |
+| 对应 PRD   | `prompts/0426/prd/prd-1-mail-provider.md` v1.0                                      |
+| 状态       | Draft → Ready-for-Implementation                                                    |
+| 关联 spec  | (无依赖 PRD-2 shared spec;`spec/shared/account-state-machine.md` 仅作弱引用)        |
+
+---
+
+## 1. 文件级修改清单
+
+| 文件路径                                              | 修改类型 | 行数预估 | 涉及函数/类                                                                  |
+| ----------------------------------------------------- | -------- | -------- | ---------------------------------------------------------------------------- |
+| `src/autoteam/api.py`                                 | 修改     | +180     | `SetupConfig`, `_AUTH_SKIP_PATHS`, `post_setup_save`, 新增 `post_mail_provider_probe`,重构 `put_register_domain_api` |
+| `src/autoteam/mail/probe.py`                          | 新增     | ~250     | `probe_fingerprint()`, `probe_credentials()`, `probe_domain_ownership()`, `ProbeError`, `ProbeErrorCode` |
+| `src/autoteam/mail/cf_temp_email.py`                  | 修改     | +12 / -4 | `login()` 嗅探条件, `create_temp_email()` 嗅探条件                          |
+| `src/autoteam/mail/maillab.py`                        | 修改     | +60      | `_with_login_retry`(新增), `_get`/`_post`/`_delete`/`_put`(改造调用), `MaillabAuthFailed`(新异常类) |
+| `src/autoteam/setup_wizard.py`                        | 修改     | +35 / -8 | `REQUIRED_CONFIGS`(扩 4 字段), `_sniff_provider_mismatch`(强阻断), `_verify_cloudmail`(嗅探前置 + 错配即返 False) |
+| `.env.example`                                        | 修改     | +5 / -3  | `MAIL_PROVIDER` 注释强化, MAILLAB_* 取消注释                                |
+| `web/src/components/SetupPage.vue`                    | 重写     | ~250     | 由平铺字段重构为 `<MailProviderCard>` + 4 卡片                              |
+| `web/src/components/MailProviderCard.vue`             | 新增     | ~280     | 3 步 wizard 状态机                                                          |
+| `web/src/components/Settings.vue`                     | 修改     | +60      | 新增「邮箱后端」区块                                                        |
+| `web/src/api.js`                                      | 修改     | +6       | 新增 `probeMailProvider(payload)`                                           |
+| `tests/test_mail_cf_temp_email_sniff.py`              | 新增     | ~80      | 4 个嗅探用例                                                                |
+| `tests/test_mail_maillab_self_heal.py`                | 新增     | ~120     | 401 自愈 + 递归守卫                                                         |
+| `tests/test_mail_provider_probe.py`                   | 新增     | ~180     | 三步 probe + error_code 全覆盖                                              |
+| `tests/test_mail_probe_helper.py`                     | 新增     | ~60      | `probe_domain_ownership` 共享 helper                                        |
+| `tests/test_setup_wizard_sniff_block.py`              | 新增     | ~70      | `_verify_cloudmail` 错配阻断                                                |
+| `tests/integration/test_setup_save_e2e.py`            | 新增     | ~110     | maillab 字段写盘 + 重载                                                     |
+| `docs/getting-started.md`                             | 修改     | +50      | §1 / §2 / §2.5 章节                                                         |
+| `docs/configuration.md`                               | 修改     | +80      | MAIL_PROVIDER 必填化 + 错配排查                                             |
+| `docs/mail-provider-design.md`                        | 修改     | +120     | §6 收口 + §7 API 全表                                                       |
+| `docs/troubleshooting.md`                             | 修改     | +60      | 邮箱后端 / 配置保存 401                                                     |
+| `docs/api.md`                                         | 修改     | +90      | `/api/mail-provider/probe` 文档化                                           |
+
+**总计**:21 个文件,约 +1900 行 / -15 行(以 SLOC 计;不含 vue 模板的 markup 行)。
+
+---
+
+## 2. 数据契约
+
+### 2.1 Pydantic 模型完整定义
+
+> ���下代码可直接粘贴入 `src/autoteam/api.py`(SetupConfig 在原位修改;ProbeRequest/Response/ErrorCode 新增)。
+
+```python
+# ===== 修改:src/autoteam/api.py L70 =====
+from typing import Literal
+
+
+class SetupConfig(BaseModel):
+    """`/api/setup/save` 请求体。新增 5 个 mail 相关字段。"""
+
+    # mail provider 选择(默认 cf_temp_email,REQUIRED_CONFIGS 与之对齐)
+    MAIL_PROVIDER: Literal["cf_temp_email", "cloudflare_temp_email", "maillab"] = "cf_temp_email"
+    # cf_temp_email 字段
+    CLOUDMAIL_BASE_URL: str = ""
+    CLOUDMAIL_EMAIL: str = ""               # 已废弃,保留兼容旧前端
+    CLOUDMAIL_PASSWORD: str = ""
+    CLOUDMAIL_DOMAIN: str = ""
+    # maillab 字段(新增)
+    MAILLAB_API_URL: str = ""
+    MAILLAB_USERNAME: str = ""
+    MAILLAB_PASSWORD: str = ""
+    MAILLAB_DOMAIN: str = ""
+    # 其他既有
+    CPA_URL: str = "http://127.0.0.1:8317"
+    CPA_KEY: str = ""
+    PLAYWRIGHT_PROXY_URL: str = ""
+    PLAYWRIGHT_PROXY_BYPASS: str = ""
+    API_KEY: str = ""
+
+
+class ProbeErrorCode(str, Enum):
+    ROUTE_NOT_FOUND = "ROUTE_NOT_FOUND"
+    PROVIDER_MISMATCH = "PROVIDER_MISMATCH"
+    UNAUTHORIZED = "UNAUTHORIZED"
+    FORBIDDEN_DOMAIN = "FORBIDDEN_DOMAIN"
+    CAPTCHA_REQUIRED = "CAPTCHA_REQUIRED"
+    NETWORK = "NETWORK"
+    TIMEOUT = "TIMEOUT"
+    EMPTY_DOMAIN_LIST = "EMPTY_DOMAIN_LIST"
+    UNKNOWN = "UNKNOWN"
+
+
+class MailProviderProbeRequest(BaseModel):
+    provider: Literal["cf_temp_email", "maillab"]
+    step: Literal["fingerprint", "credentials", "domain_ownership"]
+    base_url: str = Field(..., min_length=1, max_length=512)
+    admin_password: str = ""              # cf_temp_email 用
+    username: str = ""                    # maillab 用
+    password: str = ""                    # maillab 用
+    domain: str = ""                      # step=domain_ownership 必填
+    bearer_token: str = ""                # 跨步 token 中转;后端不持久化
+
+    @field_validator("base_url")
+    @classmethod
+    def _normalize_base_url(cls, v: str) -> str:
+        v = v.strip().rstrip("/")
+        if not (v.startswith("http://") or v.startswith("https://")):
+            raise ValueError("base_url 必须以 http:// 或 https:// 开头")
+        return v
+
+    @field_validator("domain")
+    @classmethod
+    def _normalize_domain(cls, v: str) -> str:
+        v = (v or "").strip().lstrip("@")
+        return v
+
+
+class MailProviderProbeResponse(BaseModel):
+    ok: bool
+    step: Literal["fingerprint", "credentials", "domain_ownership"]
+    error_code: ProbeErrorCode | None = None
+    message: str | None = None
+    hint: str | None = None
+    warnings: list[str] = []
+    # fingerprint
+    detected_provider: Literal["cf_temp_email", "maillab", "unknown"] | None = None
+    domain_list: list[str] | None = None
+    add_verify_open: bool | None = None
+    register_verify_open: bool | None = None
+    # credentials
+    is_admin: bool | None = None
+    user_email: str | None = None
+    token_preview: str | None = None
+    # domain_ownership
+    probe_email: str | None = None
+    probe_account_id: int | None = None
+    cleaned: bool | None = None
+    leaked_probe: dict | None = None
+```
+
+### 2.2 .env 字段全表
+
+| Key                       | 当前 .env.example 状态 | 新状态                   | 必填条件                     |
+| ------------------------- | ---------------------- | ------------------------ | ---------------------------- |
+| `MAIL_PROVIDER`           | 已存在,值 `cf_temp_email` | 注释强化:**强烈推荐显式设置** | 始终必填(默认 cf_temp_email) |
+| `CLOUDMAIL_BASE_URL`      | 已存在                 | 注释微调                 | provider=cf_temp_email 时必填 |
+| `CLOUDMAIL_PASSWORD`      | 已存在                 | 不变                     | 同上                         |
+| `CLOUDMAIL_DOMAIN`        | 已存在                 | 不变                     | 同上                         |
+| `CLOUDMAIL_EMAIL`         | 已存在,空值           | 保持(已废弃)            | 否                           |
+| `MAILLAB_API_URL`         | 注释状态               | **取消注释,空值**         | provider=maillab 时必填      |
+| `MAILLAB_USERNAME`        | 注释状态               | 取消注释,空值            | 同上                         |
+| `MAILLAB_PASSWORD`        | 注释状态               | 取消注释,空值            | 同上                         |
+| `MAILLAB_DOMAIN`          | 注释状态               | 取消注释,空值            | 否(缺省回落 CLOUDMAIL_DOMAIN) |
+
+### 2.3 accounts.json / runtime_config.json 影响
+
+**无影响**。`runtime_config.json.register_domain` 字段不变,继续被 `cf_temp_email.create_temp_email` 与 `maillab.create_temp_email` 同时读取(优先级 `显式参数 > runtime_config > 环境变量`),已在 round-2 实现并验证。
+
+---
+
+## 3. 函数签名规范
+
+### 3.1 新建 `src/autoteam/mail/probe.py`
+
+> 公开 5 个对象:3 个 helper 函数 + 1 个异常类 + 1 �� dataclass。
+
+```python
+"""mail/probe.py — `/api/mail-provider/probe` 与 `register-domain` 共享 helper。
+
+每个 step 都有同名 helper,api.py 端点直接调用并把返回值封装为 ProbeResponse;
+register-domain 复用 `probe_domain_ownership`。
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Literal
+
+import requests
+
+from autoteam.mail.base import decode_jwt_payload
+
+PROBE_TIMEOUT = 5  # 秒;每个 HTTP 调用上限
+
+
+@dataclass
+class ProbeResult:
+    """通用结果。step=fingerprint/credentials/domain_ownership 共用,字段按 step 填。"""
+
+    ok: bool
+    step: Literal["fingerprint", "credentials", "domain_ownership"]
+    error_code: str | None = None
+    message: str | None = None
+    hint: str | None = None
+    warnings: list[str] | None = None
+    # fingerprint
+    detected_provider: Literal["cf_temp_email", "maillab", "unknown"] | None = None
+    domain_list: list[str] | None = None
+    add_verify_open: bool | None = None
+    register_verify_open: bool | None = None
+    # credentials
+    is_admin: bool | None = None
+    user_email: str | None = None
+    token_preview: str | None = None
+    bearer_token: str | None = None  # 内部传给下一步 helper,api 端点不返回给前端
+    # domain_ownership
+    probe_email: str | None = None
+    probe_account_id: int | None = None
+    cleaned: bool | None = None
+    leaked_probe: dict | None = None
+
+
+def probe_fingerprint(base_url: str, expected_provider: str) -> ProbeResult:
+    """Step 1:无凭据指纹探测。
+
+    依次探测:
+      - GET {base_url}/setting/websiteConfig (maillab 独有,且通常含 domainList)
+      - GET {base_url}/admin/address         (cf_temp_email 独有,401/403/200)
+
+    返回 detected_provider:
+      - "maillab"          → /setting/websiteConfig 返回 200 + dict
+      - "cf_temp_email"    → /admin/address 返回 200 (含 results) 或 401/403
+      - "unknown"          → 两个都不像
+
+    与 expected_provider 不一致时,error_code=PROVIDER_MISMATCH。
+    """
+
+
+def probe_credentials(
+    base_url: str,
+    provider: Literal["cf_temp_email", "maillab"],
+    *,
+    username: str = "",
+    password: str = "",
+    admin_password: str = "",
+) -> ProbeResult:
+    """Step 2:凭据校验。
+
+    cf_temp_email:GET {base_url}/admin/address with `x-admin-auth: <admin_password>` header
+    maillab:POST {base_url}/login body `{email, password}`,返回 JWT
+
+    返回 token_preview(前 10 字符)与 is_admin(maillab 解析 JWT payload `userType==1`)。
+    bearer_token 字段供下游 step 用。
+    """
+
+
+def probe_domain_ownership(
+    base_url: str,
+    provider: Literal["cf_temp_email", "maillab"],
+    *,
+    bearer_token: str = "",
+    admin_password: str = "",
+    domain: str,
+) -> ProbeResult:
+    """Step 3:域名归属验证。
+
+    通用流程:
+      1. 在该 domain 下创建一个 probe-{ts} 邮箱
+      2. 立即删除回收(failed 时填 leaked_probe)
+
+    cf_temp_email:用 admin_password 直接调 /admin/new_address + /admin/delete_address
+    maillab:用 bearer_token 调 /account/add + /account/delete
+    """
+
+
+class ProbeError(Exception):
+    """probe.* helper 内部抛错;api 层捕获后转成 ProbeResult(ok=False)。"""
+
+    def __init__(self, error_code: str, message: str, hint: str | None = None):
+        self.error_code = error_code
+        self.message = message
+        self.hint = hint
+        super().__init__(message)
+```
+
+**异常映射规则**(probe 内部统一捕获):
+
+| 触发                                      | error_code           |
+| ----------------------------------------- | -------------------- |
+| `requests.ConnectionError`                | `NETWORK`            |
+| `requests.Timeout` 或 timeout=5 触发      | `TIMEOUT`            |
+| HTTP 404 + `/setting/websiteConfig` 不存在 + `/admin/address` 不存在 | `ROUTE_NOT_FOUND`    |
+| detected_provider != expected_provider    | `PROVIDER_MISMATCH`  |
+| HTTP 401 / cf_temp_email admin 401        | `UNAUTHORIZED`       |
+| maillab `code:401` 在 step=credentials    | `UNAUTHORIZED`       |
+| maillab `code:403` 或 message 含 `domain` | `FORBIDDEN_DOMAIN`   |
+| `addVerifyOpen` 或 `registerVerifyOpen` true 在 credentials 调用前 | `CAPTCHA_REQUIRED`(warning,不阻断) |
+| domainList 为空数组                       | `EMPTY_DOMAIN_LIST`  |
+| 兜底                                      | `UNKNOWN`            |
+
+### 3.2 cf_temp_email.login() 嗅探收紧
+
+**改前** (`mail/cf_temp_email.py:106-112`):
+
+```python
+if isinstance(payload, dict) and "results" not in payload and ("code" in payload or "data" in payload):
+    raise Exception(...)
+```
+
+**改后**:
+
+```python
+# 正向白名单:cf_temp_email 的 /admin/address 必须返回含 `results` 字段的 dict;
+# 任何缺 results 的 dict(空 {}、maillab 风格 {code,...}、null 等)都视为协议错配。
+if not isinstance(payload, dict) or "results" not in payload:
+    raise Exception(
+        "CloudMail 登录响应不像 dreamhunter2333/cloudflare_temp_email"
+        f"(响应 {type(payload).__name__} 不含 `results` 字段)。"
+        f"你的 CLOUDMAIL_BASE_URL={self.base_url} 可能指向 maillab/cloud-mail 服务器或路由错。"
+        "请确认 .env 中 MAIL_PROVIDER=cf_temp_email 时填的是 dreamhunter2333 后端;"
+        "如果你部署的是 maillab,请改 MAIL_PROVIDER=maillab。"
+    )
+```
+
+**create_temp_email** (L154) 同步:
+
+```python
+# 改前
+if isinstance(data, dict) and "address" not in data and ("code" in data and "message" in data):
+
+# 改后(任何缺 address 字段就报错)
+if not isinstance(data, dict) or "address" not in data:
+    raise Exception(
+        f"创建邮箱响应不像 cf_temp_email(收到 {data!r})。"
+        "请检查 MAIL_PROVIDER 与 base_url 是否对应。"
+    )
+```
+
+### 3.3 maillab.py 401 自愈
+
+**新增类成员 + 装饰器**:
+
+```python
+# ===== mail/maillab.py 顶部 =====
+import threading
+import functools
+
+class MaillabAuthFailed(Exception):
+    """maillab 401 自愈失败 — 重 login 后仍 401。业务层不再重试。"""
+
+
+_LOGIN_GUARD = threading.local()
+
+
+def _with_login_retry(method):
+    """装饰 _get/_post/_delete/_put;若响应 code=401,自动 re-login + 重试一次。
+
+    通过 thread-local guard `_LOGIN_GUARD.in_login` 阻止 login() 自身触发递归。
+    """
+    @functools.wraps(method)
+    def wrapper(self, path, *args, **kwargs):
+        resp = method(self, path, *args, **kwargs)
+        if isinstance(resp, dict) and resp.get("code") == 401:
+            if getattr(_LOGIN_GUARD, "in_login", False):
+                # 我们在 login() 内部,不要递归
+                return resp
+            if getattr(_LOGIN_GUARD, "retried", False):
+                # 上一次重试还是 401 → 抛
+                raise MaillabAuthFailed(
+                    f"maillab {path}: 重 login 后仍 401,请检查 MAILLAB_USERNAME/PASSWORD"
+                )
+            logger.warning("[maillab] %s 收到 code:401,自愈中...", path)
+            self.token = None
+            try:
+                _LOGIN_GUARD.retried = True
+                self.login()  # login 内部 _post 会被 _LOGIN_GUARD.in_login 标记保护
+                resp = method(self, path, *args, **kwargs)
+                logger.info("[maillab] %s token 已自愈", path)
+            finally:
+                _LOGIN_GUARD.retried = False
+        return resp
+    return wrapper
+```
+
+**改造 4 个底层方法**(改前/改后):
+
+```python
+# 改前
+def _get(self, path: str, params: dict | None = None) -> dict:
+    r = self.session.get(self._url(path), headers=self._headers(), params=params, timeout=30)
+    return self._parse_response(r, path)
+
+# 改后
+@_with_login_retry
+def _get(self, path: str, params: dict | None = None) -> dict:
+    r = self.session.get(self._url(path), headers=self._headers(), params=params, timeout=30)
+    return self._parse_response(r, path)
+```
+
+`_post`/`_delete`/`_put` 同样加 `@_with_login_retry`。
+
+**login() 加守卫**:
+
+```python
+def login(self) -> str:
+    _LOGIN_GUARD.in_login = True
+    try:
+        # ... 原有逻辑 ...
+        return token
+    finally:
+        _LOGIN_GUARD.in_login = False
+```
+
+### 3.4 setup_wizard 嗅探强阻断
+
+**`_sniff_provider_mismatch` 改造**(`setup_wizard.py:173`):
+
+```python
+def _sniff_provider_mismatch(provider: str) -> tuple[bool, str]:
+    """探测 base_url 与 MAIL_PROVIDER 的匹配性。
+
+    返回 (matched, reason):
+      - matched=True:可继续 login
+      - matched=False:reason 描述错配,_verify_cloudmail 直接 return False
+
+    探测策略升级:
+      - cf_temp_email 期望 → /admin/address 返 200 含 results / 401 / 403
+                              + /setting/websiteConfig 返 404
+      - maillab 期望         → /setting/websiteConfig 返 200 含 domainList
+                              + /admin/address 返 404 或 maillab 风格 {code,...}
+    """
+    # ... 实施细节略;关键:增加 GET /setting/websiteConfig 探测
+```
+
+**`_verify_cloudmail` 流程调整**:
+
+```python
+def _verify_cloudmail():
+    provider = (os.environ.get("MAIL_PROVIDER") or "cf_temp_email").strip().lower()
+    # ... 原有 base_url/password/domain 完备性检查 ...
+
+    # ★ 新位置:嗅探在所有 client 实例化之前
+    if os.environ.get("AUTOTEAM_SKIP_PROVIDER_SNIFF") != "1":
+        matched, reason = _sniff_provider_mismatch(provider)
+        if not matched:
+            logger.error("[验证] 协议错配: %s", reason)
+            return False  # ← 强阻断,不再 warning
+
+    # ... 后续 client.login() / create_temp_email() 不变 ...
+```
+
+**REQUIRED_CONFIGS 扩**(`setup_wizard.py:20`):
+
+```python
+REQUIRED_CONFIGS = [
+    ("MAIL_PROVIDER", "Mail Provider(cf_temp_email | maillab)", "cf_temp_email", True),
+    ("CLOUDMAIL_BASE_URL", "CloudMail API 地址(cf_temp_email)", "", False),
+    ("CLOUDMAIL_PASSWORD", "CloudMail 管理员密码(cf_temp_email)", "", False),
+    ("CLOUDMAIL_DOMAIN", "邮箱域名(如 @example.com)", "", False),
+    # ★ 新增 4 字段(maillab 用;optional=True 由前端按 provider 切换可见性)
+    ("MAILLAB_API_URL", "Maillab API 地址", "", True),
+    ("MAILLAB_USERNAME", "Maillab 管理员邮箱", "", True),
+    ("MAILLAB_PASSWORD", "Maillab 管理员密码", "", True),
+    ("MAILLAB_DOMAIN", "Maillab 邮箱域名(缺省回落 CLOUDMAIL_DOMAIN)", "", True),
+    # ... 其余不变
+]
+```
+
+**注**:`/api/setup/status` 端点会按 provider 动态计算 `optional`,见 §3.6。
+
+### 3.5 api.py 新增端点 + 鉴权策略
+
+**`_AUTH_SKIP_PATHS` 扩展**(`api.py:31`):
+
+```python
+_AUTH_SKIP_PATHS = {
+    "/api/auth/check",
+    "/api/setup/status",
+    "/api/setup/save",
+    "/api/mail-provider/probe",  # ← 新增;条件鉴权见下
+}
+```
+
+**条件鉴权说明**:`auth_middleware` 已自动跳过 `_AUTH_SKIP_PATHS` 中的路径。但 `/api/mail-provider/probe` 在面板初始化后(API_KEY 已配置)需强制鉴权,通过手工二次校验:
+
+```python
+@app.post("/api/mail-provider/probe", response_model=MailProviderProbeResponse)
+def post_mail_provider_probe(req: MailProviderProbeRequest, request: Request):
+    # 条件鉴权:API_KEY 已配置 → 强制 Bearer
+    from autoteam.config import API_KEY as _key
+    if _key:
+        auth_header = request.headers.get("authorization", "")
+        if not (auth_header.startswith("Bearer ") and auth_header[7:] == _key):
+            raise HTTPException(status_code=401, detail="API_KEY 已配置,请提供 Bearer token")
+    # 速率限制:setup 阶段(无 API_KEY)单 IP 60/min;有 API_KEY 时不限
+    if not _key:
+        _enforce_probe_rate_limit(request)
+
+    # 分发
+    from autoteam.mail import probe as mail_probe
+
+    try:
+        if req.step == "fingerprint":
+            result = mail_probe.probe_fingerprint(req.base_url, req.provider)
+        elif req.step == "credentials":
+            result = mail_probe.probe_credentials(
+                req.base_url, req.provider,
+                username=req.username, password=req.password,
+                admin_password=req.admin_password,
+            )
+        elif req.step == "domain_ownership":
+            result = mail_probe.probe_domain_ownership(
+                req.base_url, req.provider,
+                bearer_token=req.bearer_token,
+                admin_password=req.admin_password,
+                domain=req.domain,
+            )
+    except mail_probe.ProbeError as exc:
+        return MailProviderProbeResponse(
+            ok=False, step=req.step,
+            error_code=ProbeErrorCode(exc.error_code),
+            message=exc.message, hint=exc.hint,
+        )
+    # ProbeResult → ProbeResponse(忽略 bearer_token,前端用上一步的返回)
+    return MailProviderProbeResponse(**{k: v for k, v in vars(result).items() if k != "bearer_token"})
+```
+
+**`_enforce_probe_rate_limit`**(简单内存计数,生产可换 redis):
+
+```python
+_probe_rate_buckets: dict[str, list[float]] = {}
+_probe_rate_lock = threading.Lock()
+
+def _enforce_probe_rate_limit(request: Request, max_per_min: int = 60):
+    ip = request.client.host if request.client else "unknown"
+    now = time.time()
+    with _probe_rate_lock:
+        bucket = _probe_rate_buckets.setdefault(ip, [])
+        bucket[:] = [t for t in bucket if now - t < 60]
+        if len(bucket) >= max_per_min:
+            raise HTTPException(status_code=429, detail="probe 请求过频,请稍后再试")
+        bucket.append(now)
+```
+
+### 3.6 api.py /api/setup/save 新字段写盘
+
+**`post_setup_save` 改造**(`api.py:99`):
+
+```python
+@app.post("/api/setup/save")
+def post_setup_save(config: SetupConfig):
+    import secrets as _secrets
+    from autoteam.setup_wizard import REQUIRED_CONFIGS, _write_env
+
+    data = config.model_dump()
+    defaults = {key: default for key, _, default, _ in REQUIRED_CONFIGS}
+
+    if not data.get("CPA_URL"):
+        data["CPA_URL"] = defaults.get("CPA_URL", "http://127.0.0.1:8317")
+    if not data.get("API_KEY"):
+        data["API_KEY"] = _secrets.token_urlsafe(24)
+
+    # ★ 按 provider 选择性写入:cf_temp_email 时不写 MAILLAB_*,反之亦然
+    provider = data.get("MAIL_PROVIDER", "cf_temp_email")
+    if provider in ("cf_temp_email", "cloudflare_temp_email"):
+        skip_keys = {"MAILLAB_API_URL", "MAILLAB_USERNAME", "MAILLAB_PASSWORD", "MAILLAB_DOMAIN"}
+    elif provider == "maillab":
+        skip_keys = {"CLOUDMAIL_BASE_URL", "CLOUDMAIL_PASSWORD"}  # CLOUDMAIL_DOMAIN 仍可作回落,保留
+    else:
+        skip_keys = set()
+
+    clearable_fields = {"PLAYWRIGHT_PROXY_URL", "PLAYWRIGHT_PROXY_BYPASS"}
+    for key, value in data.items():
+        if key in skip_keys:
+            continue
+        if value or key in clearable_fields:
+            _write_env(key, value)
+            os.environ[key] = value
+
+    # ... 后续重载与 _verify_cloudmail 不变
+```
+
+**`/api/setup/status` 按 provider 标 optional**:
+
+```python
+@app.get("/api/setup/status")
+def get_setup_status():
+    from autoteam.setup_wizard import REQUIRED_CONFIGS, _read_env
+
+    env = _read_env()
+    provider = env.get("MAIL_PROVIDER") or os.environ.get("MAIL_PROVIDER", "cf_temp_email")
+
+    cf_keys = {"CLOUDMAIL_BASE_URL", "CLOUDMAIL_PASSWORD", "CLOUDMAIL_DOMAIN"}
+    ml_keys = {"MAILLAB_API_URL", "MAILLAB_USERNAME", "MAILLAB_PASSWORD", "MAILLAB_DOMAIN"}
+
+    fields = []
+    all_ok = True
+    for key, prompt, default, optional in REQUIRED_CONFIGS:
+        # 动态 optional:不属于当前 provider 的字段强制 optional=True
+        if provider == "maillab" and key in cf_keys:
+            optional = True
+        elif provider in ("cf_temp_email", "cloudflare_temp_email") and key in ml_keys:
+            optional = True
+        val = env.get(key, "") or os.environ.get(key, "")
+        ok = bool(val)
+        if not ok and not optional:
+            all_ok = False
+        fields.append({"key": key, "prompt": prompt, "default": default, "optional": optional, "configured": ok})
+    return {"configured": all_ok, "fields": fields, "provider": provider}
+```
+
+---
+
+## 4. 前端契约
+
+### 4.1 SetupPage 4 步状态机
+
+```
+                   ┌──────────────────┐
+                   │ State.PROVIDER   │  用户选 cf_temp_email / maillab
+                   └────────┬─────────┘
+                            │ provider 选定
+                            ▼
+                   ┌──────────────────┐
+                   │ State.CONNECTION │  填 base_url / 凭据,点击「测试连接」
+                   │   probe.fingerprint
+                   │   probe.credentials
+                   └────────┬─────────┘
+                            │ ok=true 进入下一步
+                  失败──────│
+                  显示       ▼
+                  err     ┌──────────────────┐
+                  +hint   │ State.DOMAIN     │  下拉/输入 domain,点击「验证归属」
+                  灰显     │   probe.domain_ownership
+                  下游     └────────┬─────────┘
+                                    │ ok=true
+                                    ▼
+                           ┌──────────────────┐
+                           │ State.SAVE       │  填 CPA / API_KEY / Proxy,点保存
+                           │   /api/setup/save
+                           └──────────────────┘
+```
+
+**状态转移**:任何一步失败时,State 不前进,但允许用户**修改前一步字段后重新点该步按钮**。State.PROVIDER 切换 provider 时,后续状态全部重置。
+
+### 4.2 axios/fetch 调用契约
+
+**新增 `web/src/api.js` 方法**:
+
+```javascript
+probeMailProvider: (payload) => request('POST', '/mail-provider/probe', payload),
+```
+
+**前端调用示例**(MailProviderCard.vue):
+
+```javascript
+async function testConnection() {
+  const fp = await api.probeMailProvider({
+    provider: form.provider,
+    step: 'fingerprint',
+    base_url: form.baseUrl,
+  })
+  if (!fp.ok) { showError(fp); return }
+  domainList.value = fp.domain_list || []
+  warnings.value = fp.warnings || []
+
+  const cred = await api.probeMailProvider({
+    provider: form.provider,
+    step: 'credentials',
+    base_url: form.baseUrl,
+    username: form.username,
+    password: form.password,
+    admin_password: form.adminPassword,
+  })
+  if (!cred.ok) { showError(cred); return }
+  state.value = 'DOMAIN'
+  bearerToken.value = cred.token_preview ? null : null  // 前端实际只缓存上一步 cred 通过的 flag
+}
+
+async function verifyDomain() {
+  const own = await api.probeMailProvider({
+    provider: form.provider,
+    step: 'domain_ownership',
+    base_url: form.baseUrl,
+    bearer_token: '',  // 后端再次走 login(短期 ttl 不缓存),实现简单
+    admin_password: form.adminPassword,
+    domain: form.domain,
+  })
+  if (!own.ok) { showError(own); return }
+  state.value = 'SAVE'
+}
+```
+
+> 注:为了让后端无状态,前端**不持有 jwt**,step=domain_ownership 时后端**重新调一次 login**(maillab 单次 login 成本低)。这把 OQ-1 决策改为「后端在 step=domain_ownership 内部 re-login」,比前端缓存 token 更简单且更安全。
+
+### 4.3 错误展示规则表
+
+| error_code           | 用户文案                                            | hint                                                |
+| -------------------- | --------------------------------------------------- | --------------------------------------------------- |
+| `ROUTE_NOT_FOUND`    | base_url 路由不可达                                 | 检查地址拼写,maillab 通常无 `/api` 前缀,cf_temp_email 通常带 `/api` |
+| `PROVIDER_MISMATCH`  | 选择的 provider 与服务器类型不一致                  | 把 provider 改成「{detected_provider}」              |
+| `UNAUTHORIZED`       | 凭据错误                                            | 检查用户名 / 密码                                   |
+| `FORBIDDEN_DOMAIN`   | 该 domain 无写权限或不在白名单                      | 联系 maillab 管理员把该 domain 加入                  |
+| `CAPTCHA_REQUIRED`   | 服务端启用了 Turnstile / addVerify                  | 到 maillab 后台 → 设置 → 安全 关闭 captcha          |
+| `NETWORK`            | 网络不可达                                          | 检查 base_url、防火墙、代理                          |
+| `TIMEOUT`            | 服务器响应超时(>5s)                               | 检查 base_url 可达性                                 |
+| `EMPTY_DOMAIN_LIST`  | 该实例未配置任何邮箱域名                            | 到 maillab 后台 → 设置 → 域名 配置                  |
+| `UNKNOWN`            | 未知错误,见 message                                 | 复制 message 反馈                                    |
+
+---
+
+## 5. 测试用例
+
+### 5.1 单元测试清单
+
+#### `tests/test_mail_cf_temp_email_sniff.py`
+
+```python
+import pytest
+import responses
+from autoteam.mail.cf_temp_email import CfTempEmailClient
+
+@responses.activate
+@pytest.mark.parametrize("body, should_raise", [
+    ({"results": []}, False),                            # cf 正常空列表
+    ({"results": [{"id": 1}]}, False),                   # cf 正常有数据
+    ({}, True),                                          # 空 dict — round-3 漏判,本次必须捕获
+    ({"code": 401, "message": "auth"}, True),            # maillab 风格
+    ({"code": 200, "data": {}}, True),                   # maillab 风格 200
+    (None, True),                                        # 非 dict
+])
+def test_login_sniff(body, should_raise, monkeypatch):
+    monkeypatch.setenv("CLOUDMAIL_BASE_URL", "https://example.com/api")
+    monkeypatch.setenv("CLOUDMAIL_PASSWORD", "secret")
+    responses.add(responses.GET, "https://example.com/api/admin/address",
+                  json=body, status=200)
+    client = CfTempEmailClient()
+    if should_raise:
+        with pytest.raises(Exception, match="不像.*cloudflare_temp_email"):
+            client.login()
+    else:
+        client.login()  # 应不抛
+```
+
+#### `tests/test_mail_maillab_self_heal.py`
+
+```python
+@responses.activate
+def test_401_self_heal(monkeypatch):
+    monkeypatch.setenv("MAILLAB_API_URL", "https://m.example.com")
+    monkeypatch.setenv("MAILLAB_USERNAME", "admin@x.com")
+    monkeypatch.setenv("MAILLAB_PASSWORD", "p")
+    # 第 1 次 list 返回 401
+    responses.add(responses.GET, "https://m.example.com/account/list",
+                  json={"code": 401, "message": "expired"}, status=200)
+    # 重 login 成功
+    responses.add(responses.POST, "https://m.example.com/login",
+                  json={"code": 200, "data": {"token": "new-jwt"}}, status=200)
+    # 第 2 次 list 成功
+    responses.add(responses.GET, "https://m.example.com/account/list",
+                  json={"code": 200, "data": []}, status=200)
+    from autoteam.mail.maillab import MaillabClient
+    client = MaillabClient()
+    client.token = "stale-jwt"
+    rows = client.list_accounts()
+    assert rows == []
+    # 验证调用顺序:list → login → list
+    assert [c.request.url for c in responses.calls] == [
+        "https://m.example.com/account/list?size=30",
+        "https://m.example.com/login",
+        "https://m.example.com/account/list?size=30",
+    ]
+
+
+@responses.activate
+def test_401_repeated_raises(monkeypatch):
+    """重 login 后仍 401 → 抛 MaillabAuthFailed,不无限循环。"""
+    # ... 类似上面,但第 2 次 list 仍 401
+    from autoteam.mail.maillab import MaillabAuthFailed
+    with pytest.raises(MaillabAuthFailed):
+        client.list_accounts()
+
+
+def test_login_internal_no_recursion(monkeypatch):
+    """login() 内部 _post 即便回 401,也不应触发外层 _with_login_retry,避免无限递归。"""
+    # mock /login 第一次回 {code:401},触发 wrapper 时 _LOGIN_GUARD.in_login=True 应阻止重试
+    # 期望:client.login() 直接抛 "maillab 登录失败",而不是循环调 login
+```
+
+#### `tests/test_mail_provider_probe.py`
+
+```python
+@responses.activate
+def test_fingerprint_detect_maillab():
+    responses.add(responses.GET, "https://m.example.com/setting/websiteConfig",
+                  json={"domainList": ["@a.com", "@b.com"], "addVerifyOpen": False, "registerVerifyOpen": False},
+                  status=200)
+    from autoteam.mail.probe import probe_fingerprint
+    result = probe_fingerprint("https://m.example.com", "maillab")
+    assert result.ok
+    assert result.detected_provider == "maillab"
+    assert result.domain_list == ["@a.com", "@b.com"]
+
+
+@responses.activate
+def test_fingerprint_provider_mismatch():
+    """base_url 是 maillab,但 provider 选了 cf_temp_email"""
+    responses.add(responses.GET, "https://m.example.com/setting/websiteConfig",
+                  json={"domainList": ["@a.com"]}, status=200)
+    result = probe_fingerprint("https://m.example.com", "cf_temp_email")
+    assert not result.ok
+    assert result.error_code == "PROVIDER_MISMATCH"
+    assert result.detected_provider == "maillab"
+
+
+def test_credentials_maillab_admin():
+    # mock /login 返回带 userType=1 的 JWT
+    # 断言 is_admin=True
+
+
+def test_domain_ownership_forbidden():
+    # mock /account/add 返 {code:403, message:"domain not allowed"}
+    # 断言 error_code=FORBIDDEN_DOMAIN
+```
+
+#### `tests/test_setup_wizard_sniff_block.py`
+
+```python
+def test_verify_cloudmail_aborts_on_mismatch(monkeypatch, caplog):
+    monkeypatch.setenv("MAIL_PROVIDER", "cf_temp_email")
+    monkeypatch.setenv("CLOUDMAIL_BASE_URL", "https://m.example.com")  # maillab 服务器
+    monkeypatch.setenv("CLOUDMAIL_PASSWORD", "x")
+    monkeypatch.setenv("CLOUDMAIL_DOMAIN", "@a.com")
+    # mock /setting/websiteConfig 返 200(maillab 指纹)、/admin/address 返 404
+    # ...
+    from autoteam.setup_wizard import _verify_cloudmail
+    assert _verify_cloudmail() is False
+    assert "协议错配" in caplog.text
+    # 关键:CloudMailClient 不应被实例化
+```
+
+### 5.2 集成测试
+
+```python
+def test_setup_save_writes_maillab_fields(client, tmp_env):
+    payload = {
+        "MAIL_PROVIDER": "maillab",
+        "MAILLAB_API_URL": "https://m.example.com",
+        "MAILLAB_USERNAME": "admin@x.com",
+        "MAILLAB_PASSWORD": "p",
+        "MAILLAB_DOMAIN": "@x.com",
+        "CLOUDMAIL_DOMAIN": "@x.com",  # 回落用
+        "CPA_URL": "http://127.0.0.1:8317",
+        "CPA_KEY": "k",
+        "API_KEY": "test-key",
+    }
+    # mock _verify_cloudmail/_verify_cpa 返 True
+    resp = client.post("/api/setup/save", json=payload)
+    assert resp.status_code == 200
+    env = read_env_file()
+    assert env["MAIL_PROVIDER"] == "maillab"
+    assert env["MAILLAB_API_URL"] == "https://m.example.com"
+    # cf_temp_email 字段被跳过
+    assert "CLOUDMAIL_BASE_URL" not in env or env["CLOUDMAIL_BASE_URL"] == ""
+```
+
+### 5.3 回归测试(避免破坏 cf_temp_email 用户)
+
+```python
+def test_existing_cf_user_not_broken(monkeypatch, mock_cf_server):
+    """老用户不改 .env(无 MAIL_PROVIDER 字段)启动,行为应与之前完全一致。"""
+    # 不设 MAIL_PROVIDER → 默认 cf_temp_email
+    # mock_cf_server 返合法 results
+    from autoteam.setup_wizard import _verify_cloudmail
+    assert _verify_cloudmail() is True
+```
+
+### 5.4 测试数据(mock 样本)
+
+**maillab `/setting/websiteConfig` 完整响应**:
+
+```json
+{
+  "register": true,
+  "title": "SkyMail",
+  "manyEmail": true,
+  "addEmail": true,
+  "autoRefresh": 30,
+  "addEmailVerify": false,
+  "registerVerify": false,
+  "send": false,
+  "domainList": ["@example.com", "@another.com"],
+  "siteKey": "0x4...",
+  "regKey": "0x4...",
+  "r2Domain": "https://r2.example.com",
+  "background": "",
+  "loginOpacity": 0.8,
+  "regVerifyOpen": false,
+  "addVerifyOpen": false,
+  "noticeTitle": "",
+  "noticeContent": "",
+  "linuxdoSwitch": false,
+  "minEmailPrefix": 3,
+  "projectLink": "https://skymail.ink"
+}
+```
+
+**maillab `/login` 成功响应**:
+
+```json
+{"code": 200, "data": {"token": "eyJhbGciOiJIUzI1NiJ9.eyJ1c2VySWQiOjEsInVzZXJUeXBlIjoxLCJlbWFpbCI6ImFkbWluQHguY29tIn0.sig"}}
+```
+
+**maillab `/account/add` 403**:
+
+```json
+{"code": 403, "message": "domain @forbidden.com not in white list"}
+```
+
+**cf_temp_email `/admin/address` 正常**:
+
+```json
+{"results": [{"id": 1, "name": "test@example.com"}], "count": 1}
+```
+
+---
+
+## 6. 文档落地清单(章节级 diff 大纲)
+
+### `docs/getting-started.md`
+- §1 「准备工作 / 1. 搭建临时邮箱」:用 admonition 强调「先决定后端,再决定填哪一组配置」
+- §2 「第二步:配置 / 直接部署」:增补 maillab 完整字段示例;明确 SetupPage 已支持 provider 选择
+- 新增 §2.5 「邮箱后端归属验证」:截图(可后补)+ 4 步流程文字说明
+
+### `docs/configuration.md`
+- 「`.env` 配置项」表:`MAIL_PROVIDER` 必填列由 `否` 改 `是(默认 cf_temp_email)`;MAILLAB_* 4 字段 「Web 面板可填」标记
+- 「Mail Provider 切换」:**推荐顺序**改为先讲 maillab(国内 + skymail 一键部署),后讲 cf_temp_email
+- 新增 「邮箱归属验证」:`/setting/websiteConfig.domainList` + addVerify 边界
+- 「⚠️ 协议错配排查」:把 issue#1 截图 + 修复路径(选 provider → 测试连接)显式列
+
+### `docs/mail-provider-design.md`
+- §6 「未知项 5 项」状态全部改 ✅(login JWT header / domain 列表 API / createTime / 创建端点 / accountId 类型),引用 GitHub 源码 url
+- 新增 §7 「skymail.ink API 全表」:从 issue-1-cloudmail.md §B 整理入档
+- 新增 §8 「401 自愈策略」:本 SPEC §3.3 设计入档
+
+### `docs/troubleshooting.md`
+- 「Web 面板相关」:加「配置保存后 401 创建邮箱失败」 → 链接 issue#1 修复
+- 新增 「邮箱后端」 章节:5 个常见错配场景 + 对应 error_code
+
+### `docs/api.md`
+- 「初始配置 API」:文档化 `/api/mail-provider/probe`(请求/响应 schema、3 个 step 示例、错误码表)
+- 「域名管理 API」:`/api/config/register-domain` 添加「内部使用 `probe_domain_ownership` helper」说明
+
+### `.env.example`
+- L1-5:MAIL_PROVIDER 上方加大段注释「**强烈推荐显式设置**;不设默认 cf_temp_email,maillab 用户会撞 issue#1 错配」
+- MAILLAB_* 4 行取消 `#` 注释
+
+---
+
+## 7. 实施顺序与依赖
+
+### DAG
+
+```
+                ┌─────────────────────────────────────────┐
+                │ Phase 1 (后端基础,无 UI 风险)            │
+                │                                         │
+                │  ST-101 SetupConfig 扩字段              │
+                │     │                                   │
+                │     ├─ ST-104 嗅探强阻断 ─┐             │
+                │     │                     │             │
+                │  ST-102 cf 嗅探收紧 ──────┤             │
+                │  ST-103 maillab 401 自愈 ─┤             │
+                │     │                     │             │
+                │  ST-105 .env.example ────┤              │
+                │     │                     │             │
+                │  ST-107 单元测试 ─────────┘             │
+                │     │                                   │
+                │  ST-106 文档(部分)                     │
+                └─────────────────────────────────────────┘
+                            │
+                            ▼
+                ┌─────────────────────────────────────────┐
+                │ Phase 2 (probe 端点 + UI)                │
+                │                                         │
+                │  ST-201 mail/probe.py ─┐                │
+                │     │                  │                │
+                │     ▼                  │                │
+                │  ST-202 /api/mail-provider/probe        │
+                │     │                  │                │
+                │  ST-203 register-domain 复用 ←┘         │
+                │     │                                   │
+                │  ST-204 MailProviderCard.vue            │
+                │  ST-205 SetupPage 重构                  │
+                │  ST-206 api.js 方法                     │
+                │     │                                   │
+                │  ST-207 集成 + E2E                      │
+                └─────────────────────────────────────────┘
+                            │
+                            ▼
+                ┌─────────────────────────────────────────┐
+                │ Phase 3 (Settings 页 UI)                 │
+                │  ST-301 → ST-302 → ST-303               │
+                └─────────────────────────────────────────┘
+```
+
+### Phase 边界
+
+- **Phase 1 完整可独立合并** — 不依赖任何 UI 改动,可单独发版,issue#1 错配阻断已生效。
+- **Phase 2 强依赖 Phase 1** — `/api/mail-provider/probe` 需要 SetupConfig 已扩字段才能写盘;`probe.probe_credentials` 复用 `MaillabClient` 401 自愈守卫的语义。
+- **Phase 3 强依赖 Phase 2** — Settings.vue 复用 MailProviderCard.vue 组件。
+
+---
+
+## 8. 验收清单(Implementer Checklist)
+
+| #   | 验收项                                                                                                  | yes/no |
+| --- | ------------------------------------------------------------------------------------------------------- | ------ |
+| 1   | SetupConfig 包含 MAIL_PROVIDER + MAILLAB_* 4 字段,Pydantic 模型 model_dump() 含 9 个 mail 字段        | ☐      |
+| 2   | `/api/setup/save` POST `MAIL_PROVIDER=maillab` 后,`.env` 含 MAILLAB_* 4 字段且不含 CLOUDMAIL_BASE_URL | ☐      |
+| 3   | `cf_temp_email.login()` 在响应 `{}` 时抛错(包含 "不像.*cloudflare_temp_email")                       | ☐      |
+| 4   | `MaillabClient` 业务方法收 `code:401`,自动 re-login + 重试一次,日志含 `[maillab] token 已自愈`       | ☐      |
+| 5   | `MaillabClient.login()` 内部 `/login` 自身回 401 时,**不**触发递归(thread-local guard 生效)         | ☐      |
+| 6   | `_verify_cloudmail` 在 provider/base_url 错配时直接 return False,不实例化 client                    | ☐      |
+| 7   | `_verify_cloudmail` 在 `AUTOTEAM_SKIP_PROVIDER_SNIFF=1` 时跳过嗅探                                     | ☐      |
+| 8   | `/api/mail-provider/probe` step=fingerprint 对 maillab base_url 返 detected_provider=maillab + domain_list 非空 | ☐      |
+| 9   | step=fingerprint provider 与 detected 不一致时返 error_code=PROVIDER_MISMATCH                          | ☐      |
+| 10  | step=credentials 凭据错时返 UNAUTHORIZED;maillab 启用 captcha 时返 CAPTCHA_REQUIRED warning           | ☐      |
+| 11  | step=domain_ownership 成功时探测邮箱已被 DELETE,leaked_probe=null                                     | ☐      |
+| 12  | `PUT /api/config/register-domain` 与 step=domain_ownership 调用同一个 `probe_domain_ownership` helper | ☐      |
+| 13  | `_AUTH_SKIP_PATHS` 含 `/api/mail-provider/probe`;API_KEY 已配置时强制 Bearer 鉴权                     | ☐      |
+| 14  | setup 阶段 probe 端点 60 req/min 速率限制生效(超过返 429)                                            | ☐      |
+| 15  | SetupPage 切 provider 时,后续状态全部重置(domain_list 清空、State 回到 PROVIDER)                    | ☐      |
+| 16  | SetupPage 任一步失败时,下游卡片灰显 disabled                                                           | ☐      |
+| 17  | Settings.vue 切换 mail provider 后保存,toast 显示「重启服务后生效」                                    | ☐      |
+| 18  | docs/getting-started.md / configuration.md / mail-provider-design.md / troubleshooting.md / api.md 全部 sync | ☐      |
+| 19  | `.env.example` MAIL_PROVIDER 上方含强引导注释,MAILLAB_* 不再注释状态                                  | ☐      |
+| 20  | 19 处 `from autoteam.cloudmail import CloudMailClient` 调用零改动,业务回归测试 100% 通过              | ☐      |
+| 21  | issue#1 复现场景(maillab 服务器 + cf_temp_email 选项)在 Web 面板内 step=fingerprint 即报错           | ☐      |
+
+---
+
+## 附:对 PRD 的批判审查与边界补完
+
+> 实施过程中发现 PRD 未完全交代的 4 个边界,SPEC 已补:
+
+1. **PRD §FR-004 鉴权策略未定** — PRD 仅说「setup 阶段无鉴权,进入面板后 API_KEY」,SPEC §3.5 落实为:`_AUTH_SKIP_PATHS` 加白 + 路由内手工二次校验,API_KEY 配置时强制 Bearer。
+2. **PRD §OQ-1 token 跨步存储** — PRD 留作 OQ,SPEC §4.2 直接决策:**前端不持有 token**,step=domain_ownership 后端再调一次 login,降低复杂度且更安全。
+3. **PRD §FR-003 login() 内部递归** — PRD 提到 thread-local guard 但未说细节,SPEC §3.3 给出双 guard:`in_login`(login 内部不触发自愈)+ `retried`(单次重试限制)。
+4. **PRD §FR-001 互斥写入** — PRD 说「按 provider 跳过无关字段」,SPEC §3.6 落实为 `skip_keys` 集合,且保留 `CLOUDMAIL_DOMAIN` 作为 maillab 的 fallback(因 maillab.py 已实现该回落,删了反而破坏)。
+
+> SPEC 已与 PRD §13 OQ-1 / OQ-3 / OQ-6 决策对齐:
+> - OQ-1:不让前端持 token(SPEC §4.2)
+> - OQ-3:`AUTOTEAM_SKIP_PROVIDER_SNIFF=1` 逃生口写入 SPEC §3.4
+> - OQ-6:domainList 空时 error_code=`EMPTY_DOMAIN_LIST`(SPEC §3.1 异常表)
+

prompts/0426/spec/spec-2-account-lifecycle.md

@@ -0,0 +1,1018 @@
+# SPEC-2: 账号生命周期与配额加固 实施规范
+
+## 0. 元数据
+
+| 字段 | 内容 |
+|---|---|
+| 编号 | SPEC-2 |
+| 名称 | 账号生命周期与配额加固 实施规范 |
+| 主笔 | prd-lifecycle |
+| 时间 | 2026-04-26 |
+| 关联 PRD | [`../prd/prd-2-account-lifecycle.md`](../prd/prd-2-account-lifecycle.md) |
+| 引用 shared spec | [`./shared/plan-type-whitelist.md`](./shared/plan-type-whitelist.md) · [`./shared/quota-classification.md`](./shared/quota-classification.md) · [`./shared/add-phone-detection.md`](./shared/add-phone-detection.md) · [`./shared/account-state-machine.md`](./shared/account-state-machine.md) |
+| 覆盖 FR | A1~A5 / B1~B4 / C1~C5 / D1~D4 / E1~E4 / F1~F6 / G1~G4 / H1~H3 |
+
+---
+
+## 1. 文件级修改清单
+
+| 文件 | 预估改动行数 | 涉及函数/对象 |
+|---|---|---|
+| `src/autoteam/accounts.py` | +35 | 新增 `SUPPORTED_PLAN_TYPES` / `is_supported_plan` / `normalize_plan_type` / 扩 `add_account` 默认字段 |
+| `src/autoteam/codex_auth.py` | ~80 | `_exchange_auth_code`(扩 bundle 字段)/ `login_codex_via_browser`(4 处探针)/ `check_codex_quota`(no_quota 分支)/ `get_quota_exhausted_info`(no_quota 短路) |
+| `src/autoteam/manager.py` | ~250 | `_run_post_register_oauth`(quota probe + 5 类处置 + RegisterBlocked catch)/ `sync_account_states`(被踢识别 + 并发探测)/ `reinvite_account`(plan_drift / phone_blocked 兜底)/ `_check_pending_invites`(L1057 RegisterBlocked catch) |
+| `src/autoteam/chatgpt_api.py` | ~30 | `_invite_member_once`(allow_patch_upgrade 参数)/ `_invite_member_with_fallback`(分支调整) |
+| `src/autoteam/invite.py` | ~5 | `run` / `cmd_fill_team` 入口读 `PREFERRED_SEAT_TYPE`(L496) |
+| `src/autoteam/runtime_config.py` | +30 | 新增 `get_preferred_seat_type` / `set_preferred_seat_type` / `get_sync_probe_concurrency` 等 |
+| `src/autoteam/api.py` | ~50 | `/api/accounts/{email}/login`(409 phone_required)/ `delete_accounts_batch`(全 personal 短路) |
+| `src/autoteam/account_ops.py` | ~25 | `delete_managed_account`(short_circuit 逻辑) |
+| `src/autoteam/manual_account.py` | ~20 | `_finalize_account`(plan_supported 检查 + no_quota 处置) |
+| `src/autoteam/register_failures.py` | +5 | docstring 扩 6 个新 category |
+| `web/src/views/Settings.vue` | +60 | 邀请席位偏好下拉 / 探测并发 / 探测去重 |
+| `web/src/components/Dashboard.vue` | ~40 | removeAccount toast / quota 显示识别 no_quota / status 文案 |
+| `web/src/api.ts` | +20 | 解析 409 phone_required + 422 no_quota |
+
+**总计**:13 个文件,预计 +650 行 / -120 行。
+
+---
+
+## 2. 引用的 shared specs
+
+本主 spec 不重复定义以下契约,实施时请直接打开对应 shared:
+
+| shared spec | 提供 |
+|---|---|
+| [`./shared/plan-type-whitelist.md`](./shared/plan-type-whitelist.md) | `SUPPORTED_PLAN_TYPES` 常量、`is_supported_plan` / `normalize_plan_type` 工具函数、bundle 字段扩展、6 调用点处置矩阵 |
+| [`./shared/quota-classification.md`](./shared/quota-classification.md) | `check_codex_quota` 5 分类签名、QuotaSnapshot / QuotaExhaustedInfo 类型、9+2 调用点处置 |
+| [`./shared/add-phone-detection.md`](./shared/add-phone-detection.md) | RegisterBlocked / assert_not_blocked 复用契约、4 探针接入点位置、5 调用方处置模板 |
+| [`./shared/account-state-machine.md`](./shared/account-state-machine.md) | 7 状态完整状态机、AccountRecord Pydantic 模型、转移矩阵、不变量 |
+
+---
+
+## 3. 函数级修改详情
+
+### 3.1 `_run_post_register_oauth` 加 quota probe 与 RegisterBlocked catch
+
+**文件**:`src/autoteam/manager.py:1386-1486`
+**FR**:D1~D4 + C3(Team / personal 调用点)
+
+#### 3.1.1 改造前(精简版,见 §1463-1486)
+
+```python
+bundle = login_codex_via_browser(email, password, mail_client=mail_client)
+if bundle:
+    auth_file = save_auth_file(bundle)
+    bundle_plan = (bundle.get("plan_type") or "").lower()
+    seat_label = "chatgpt" if bundle_plan == "team" else "codex"
+    update_account(email, status=STATUS_ACTIVE, seat_type=seat_label, auth_file=auth_file, ...)
+    return email
+update_account(email, status=STATUS_ACTIVE, ...)  # team_auth_missing
+return email
+```
+
+#### 3.1.2 改造后(Team 分支完整 diff)
+
+```python
+# manager.py:1462 起,Team 分支完整改造
+from autoteam.invite import RegisterBlocked
+from autoteam.accounts import is_supported_plan
+from autoteam.codex_auth import check_codex_quota, get_quota_exhausted_info
+# (上述 import 应集中放到 manager.py 文件顶部)
+
+try:
+    bundle = login_codex_via_browser(email, password, mail_client=mail_client)
+except RegisterBlocked as blocked:
+    if blocked.is_phone:
+        record_failure(
+            email,
+            category="oauth_phone_blocked",
+            reason=f"OAuth 阶段触发 add-phone (step={blocked.step})",
+            step=blocked.step,
+            stage="run_post_register_oauth_team",
+        )
+        # Team 模式下账号已成功 invite,不能 delete_account(席位仍占着);标 AUTH_INVALID 让 reconcile ��管
+        update_account(
+            email,
+            status=STATUS_AUTH_INVALID,
+            workspace_account_id=get_chatgpt_account_id() or None,
+        )
+        _record_outcome("oauth_phone_blocked", reason="OAuth 阶段触发 add-phone")
+        return None
+    # is_duplicate 在 OAuth 阶段不应出现,记 exception 兜底
+    record_failure(email, "exception", f"OAuth 意外 RegisterBlocked: {blocked.reason}")
+    _record_outcome("oauth_failed", reason=f"unexpected RegisterBlocked: {blocked.reason}")
+    return None
+
+if not bundle:
+    # 旧路径:bundle=None,team_auth_missing,保留 ACTIVE 等用户补登录
+    update_account(email, status=STATUS_ACTIVE, workspace_account_id=get_chatgpt_account_id() or None)
+    logger.warning("[注册] 账号已加入 Team 但 Codex 登录失败,需要补登录: %s", email)
+    _record_outcome("team_auth_missing", reason="已入 Team 席位但 Codex OAuth 未返回 bundle,需要补登录")
+    return email
+
+auth_file = save_auth_file(bundle)
+bundle_plan = bundle.get("plan_type", "unknown")  # 已被 _exchange_auth_code 归一化为小写
+plan_supported = bundle.get("plan_supported", is_supported_plan(bundle_plan))
+
+# 新增 FR-A4:plan_type 不支持 → AUTH_INVALID
+if not plan_supported:
+    record_failure(
+        email,
+        category="plan_unsupported",
+        reason=f"OAuth bundle plan_type={bundle.get('plan_type_raw') or bundle_plan} 不在白名单",
+        plan_type=bundle_plan,
+        plan_type_raw=bundle.get("plan_type_raw"),
+        stage="run_post_register_oauth_team",
+    )
+    update_account(
+        email,
+        status=STATUS_AUTH_INVALID,
+        seat_type="codex",
+        auth_file=auth_file,                   # 保留 auth_file 供调试
+        plan_type_raw=bundle.get("plan_type_raw"),
+        workspace_account_id=get_chatgpt_account_id() or None,
+    )
+    _record_outcome("plan_unsupported", plan=bundle_plan)
+    return None
+
+# FR-D1~D4:quota probe(对称 manual_account._finalize_account)
+seat_label = "chatgpt" if bundle_plan == "team" else "codex"
+access_token = bundle.get("access_token")
+account_id = bundle.get("account_id")
+
+update_fields = {
+    "status": STATUS_ACTIVE,
+    "seat_type": seat_label,
+    "auth_file": auth_file,
+    "last_active_at": time.time(),
+    "workspace_account_id": get_chatgpt_account_id() or None,
+    "plan_type_raw": bundle.get("plan_type_raw"),
+}
+
+if access_token:
+    try:
+        quota_status, quota_info = check_codex_quota(access_token, account_id=account_id)
+    except Exception as exc:
+        # FR-D4: probe 异常吞掉,降级 ACTIVE + 记录
+        record_failure(email, "quota_probe_network_error", f"quota probe exception: {exc}",
+                       stage="run_post_register_oauth_team")
+        quota_status, quota_info = "network_error", None
+
+    if quota_status == "ok" and isinstance(quota_info, dict):
+        update_fields["last_quota"] = quota_info
+    elif quota_status == "exhausted":
+        snapshot = quota_info.get("quota_info") if isinstance(quota_info, dict) else None
+        if snapshot:
+            update_fields["last_quota"] = snapshot
+        update_fields["status"] = STATUS_EXHAUSTED
+        update_fields["quota_exhausted_at"] = time.time()
+        update_fields["quota_resets_at"] = (
+            quota_info.get("resets_at") if isinstance(quota_info, dict) else int(time.time() + 18000)
+        )
+    elif quota_status == "no_quota":
+        snapshot = quota_info.get("quota_info") if isinstance(quota_info, dict) else None
+        if snapshot:
+            update_fields["last_quota"] = snapshot
+        update_fields["status"] = STATUS_AUTH_INVALID
+        record_failure(email, "no_quota_assigned",
+                       "wham/usage 返回 no_quota(workspace 未分配 codex 配额)",
+                       plan_type=bundle_plan, stage="run_post_register_oauth_team")
+    elif quota_status == "auth_error":
+        update_fields["status"] = STATUS_AUTH_INVALID
+        record_failure(email, "auth_error_at_oauth",
+                       "wham/usage 返回 401/403,token 失效",
+                       stage="run_post_register_oauth_team")
+    elif quota_status == "network_error":
+        # 网络抖动:保留 ACTIVE,但记录一次失败便于运营观察
+        record_failure(email, "quota_probe_network_error",
+                       "wham/usage 网络异常,ACTIVE 状态由下轮 cmd_check 校准",
+                       stage="run_post_register_oauth_team")
+
+update_account(email, **update_fields)
+_record_outcome("success" if update_fields["status"] == STATUS_ACTIVE else "quota_issue",
+                plan=bundle_plan, status=update_fields["status"])
+return email if update_fields["status"] == STATUS_ACTIVE else None
+```
+
+#### 3.1.3 personal 分支(L1431-1460)的对称改造
+
+```python
+# manager.py:1431 起
+try:
+    bundle = login_codex_via_browser(email, password, mail_client=mail_client, use_personal=True)
+except RegisterBlocked as blocked:
+    if blocked.is_phone:
+        record_failure(
+            email,
+            category="oauth_phone_blocked",
+            reason=f"personal OAuth 触发 add-phone (step={blocked.step})",
+            step=blocked.step,
+            stage="run_post_register_oauth_personal",
+        )
+        delete_account(email)  # personal 已 leave_workspace,本地无价值
+        _record_outcome("oauth_phone_blocked", reason="personal OAuth 触发 add-phone")
+        return None
+    record_failure(email, "exception", f"personal OAuth RegisterBlocked: {blocked.reason}")
+    delete_account(email)
+    return None
+
+if bundle:
+    plan_supported = bundle.get("plan_supported", is_supported_plan(bundle.get("plan_type", "")))
+    if not plan_supported:
+        record_failure(
+            email, "plan_unsupported",
+            f"personal OAuth bundle plan_type={bundle.get('plan_type_raw')} 不在白名单",
+            plan_type=bundle.get("plan_type"),
+            plan_type_raw=bundle.get("plan_type_raw"),
+            stage="run_post_register_oauth_personal",
+        )
+        delete_account(email)
+        _record_outcome("plan_unsupported", plan=bundle.get("plan_type"))
+        return None
+
+    auth_file = save_auth_file(bundle)
+    update_fields = {
+        "status": STATUS_PERSONAL,
+        "seat_type": "codex",
+        "auth_file": auth_file,
+        "last_active_at": time.time(),
+        "plan_type_raw": bundle.get("plan_type_raw"),
+    }
+
+    # personal 分支也加 quota probe(对称),确认 free plan 真有 codex 配额
+    access_token = bundle.get("access_token")
+    if access_token:
+        try:
+            quota_status, quota_info = check_codex_quota(access_token, account_id=bundle.get("account_id"))
+            if quota_status == "ok" and isinstance(quota_info, dict):
+                update_fields["last_quota"] = quota_info
+            elif quota_status == "no_quota":
+                # personal 拿到无配额 → 保留 PERSONAL 但记一笔(用户可以决定删不删)
+                record_failure(email, "no_quota_assigned",
+                               "personal free plan 无 codex 配额",
+                               stage="run_post_register_oauth_personal")
+        except Exception:
+            pass  # personal probe 失败不阻塞
+
+    update_account(email, **update_fields)
+    _record_outcome("success", plan=bundle.get("plan_type"))
+    return email
+
+# bundle is None — 旧路径保留
+delete_account(email)
+record_failure(email, "oauth_failed",
+               "已退出 Team 但 personal Codex OAuth 登录未返回 bundle",
+               stage="post_leave_workspace")
+_record_outcome("oauth_failed", reason="personal Codex OAuth 未返回 bundle")
+return None
+```
+
+### 3.2 `sync_account_states` 分支扩展(被踢识别 + 并发)
+
+**文件**:`src/autoteam/manager.py:476-541`
+**FR**:E1~E4
+
+#### 3.2.1 改造点
+
+```python
+# manager.py:526-541 改造后
+import concurrent.futures
+
+def _probe_kicked_account(acc):
+    """单账号探测:wham 401/403 → 被踢;否则返回 None."""
+    auth_file = acc.get("auth_file")
+    if not auth_file:
+        return None  # 无 token 无法判定,降级 STANDBY
+    try:
+        bundle = load_auth_file(auth_file)  # 假设 codex_auth 提供
+        access_token = bundle.get("access_token")
+        if not access_token:
+            return None
+        status, _ = check_codex_quota(access_token)
+        return status
+    except Exception:
+        return None
+
+
+# 在 sync_account_states 函数体内,替换 L526-541 的现行分支
+# 先收集需要探测的 acc,然后用 ThreadPoolExecutor 并发
+need_probe = []
+for acc in accounts:
+    email = acc["email"].lower()
+    in_team = email in team_emails
+
+    if in_team and acc["status"] in (STATUS_STANDBY, STATUS_PENDING):
+        acc["status"] = STATUS_ACTIVE
+        if account_id:
+            acc["workspace_account_id"] = account_id
+        changed = True
+    elif not in_team and acc["status"] == STATUS_ACTIVE:
+        acc_ws = acc.get("workspace_account_id")
+        if acc_ws and account_id and acc_ws != account_id:
+            logger.warning("[同步] %s workspace 漂移,保留 active 不 flip", acc["email"])
+            continue
+
+        # FR-E3 探测去重:30 分钟内不重复探测
+        last_check = acc.get("last_quota_check_at") or 0
+        cooldown = get_runtime("sync_probe_cooldown_minutes", 30) * 60
+        if time.time() - last_check < cooldown:
+            acc["status"] = STATUS_STANDBY
+            changed = True
+            continue
+
+        need_probe.append(acc)
+
+# FR-E2 并发探测
+concurrency = get_runtime("sync_probe_concurrency", 5)
+if need_probe:
+    with concurrent.futures.ThreadPoolExecutor(max_workers=concurrency) as ex:
+        future_map = {ex.submit(_probe_kicked_account, acc): acc for acc in need_probe}
+        for fut in concurrent.futures.as_completed(future_map, timeout=concurrency * 6):
+            acc = future_map[fut]
+            try:
+                status_str = fut.result(timeout=5)
+            except Exception:
+                status_str = None
+            now = time.time()
+            acc["last_quota_check_at"] = now
+
+            if status_str == "auth_error":
+                acc["status"] = STATUS_AUTH_INVALID
+                acc["last_kicked_at"] = now
+                logger.warning("[同步] %s wham 401/403,判定被人工踢出 → AUTH_INVALID", acc["email"])
+            elif status_str == "no_quota":
+                acc["status"] = STATUS_AUTH_INVALID  # 不会自然恢复
+                logger.warning("[同步] %s wham no_quota → AUTH_INVALID", acc["email"])
+            else:
+                # ok / exhausted / network_error / None → 保持自然待机语义
+                acc["status"] = STATUS_STANDBY
+            changed = True
+```
+
+#### 3.2.2 关键设计决策
+
+- **并发上限 5**(可配):防止 N 个 active 号串行 wham 让 sync 周期超 30s(NFR-1)
+- **单调用超时 5s** + **整体超时 30s**(`concurrency * 6` 上限)
+- **去重 30 分钟**:同 email 不重复探测,避免同一 active 号在多次 sync 间被反复探测
+- **任何探测异常吞掉**:保持 STATUS_STANDBY 旧行为,避免一次抖动批量误标 AUTH_INVALID
+- **`load_auth_file` 工具函数**:codex_auth.py 中应已有(读 auth json),实施时核对;无则在该模块新增小工具
+
+### 3.3 `reinvite_account` 兜底改造
+
+**文件**:`src/autoteam/manager.py:2466-2585`
+**FR**:H1~H3 + C3(reinvite 调用点)
+
+#### 3.3.1 改造点(L2466 包 try/except + L2489 替换 STATUS_STANDBY → AUTH_INVALID)
+
+```python
+# manager.py:2466 起
+try:
+    bundle = login_codex_via_browser(email, password, mail_client=mail_client)
+except RegisterBlocked as blocked:
+    if blocked.is_phone:
+        record_failure(
+            email,
+            category="oauth_phone_blocked",
+            reason=f"reinvite OAuth 触发 add-phone (step={blocked.step})",
+            step=blocked.step,
+            stage="reinvite_account",
+        )
+        _cleanup_team_leftover("oauth_phone_blocked")
+        update_account(
+            email,
+            status=STATUS_AUTH_INVALID,
+            auth_file=None,
+            quota_exhausted_at=None,
+            quota_resets_at=None,
+        )
+        return False
+    record_failure(email, "exception", f"reinvite RegisterBlocked: {blocked.reason}")
+    _cleanup_team_leftover("exception")
+    update_account(email, status=STATUS_AUTH_INVALID, auth_file=None)
+    return False
+
+# (现有 _cleanup_team_leftover 闭包定义保留)
+
+if not bundle:
+    logger.warning("[轮转] 旧账号 OAuth 登录失败,保持 standby: %s", email)
+    _cleanup_team_leftover("no_bundle")
+    update_account(email, status=STATUS_STANDBY)
+    return False
+
+# FR-H1 + plan_supported 检查:plan_supported=False → AUTH_INVALID;plan != team 也走 AUTH_INVALID
+plan_type = (bundle.get("plan_type") or "").lower()
+plan_supported = bundle.get("plan_supported", is_supported_plan(plan_type))
+
+if not plan_supported:
+    logger.warning("[轮转] 旧账号 plan=%s 不在白名单,推 AUTH_INVALID: %s",
+                   bundle.get("plan_type_raw"), email)
+    _cleanup_team_leftover(f"plan_unsupported_{plan_type or 'unknown'}")
+    record_failure(
+        email, "plan_unsupported",
+        f"reinvite bundle plan_type={bundle.get('plan_type_raw')} 不在白名单",
+        plan_type=plan_type, plan_type_raw=bundle.get("plan_type_raw"),
+        stage="reinvite_account",
+    )
+    update_account(
+        email,
+        status=STATUS_AUTH_INVALID,
+        auth_file=None,                # 清掉错误 plan 的 token
+        plan_type_raw=bundle.get("plan_type_raw"),
+        quota_exhausted_at=None,
+        quota_resets_at=None,
+    )
+    return False
+
+if plan_type != "team":
+    logger.warning("[轮转] 旧账号 plan=%s,plan_drift,推 AUTH_INVALID: %s", plan_type, email)
+    _cleanup_team_leftover(f"plan_drift_{plan_type or 'unknown'}")
+    record_failure(
+        email, "plan_drift",
+        f"reinvite 拿到 plan={plan_type or 'unknown'} != team",
+        plan_type=plan_type, stage="reinvite_account",
+    )
+    update_account(
+        email,
+        status=STATUS_AUTH_INVALID,    # 不再回 STANDBY
+        auth_file=None,
+        plan_type_raw=bundle.get("plan_type_raw"),
+        quota_exhausted_at=None,
+        quota_resets_at=None,
+    )
+    return False
+
+# (剩余 quota verify 段保留 L2496-2595 现行实现,只在 fail_reason 分支补 no_quota 处置)
+auth_file = save_auth_file(bundle)
+...
+# 在 quota verified 判断中增加:
+elif status_str == "no_quota":
+    fail_reason = "no_quota_assigned"
+    logger.warning("[轮转] %s reinvite 后 wham no_quota,判定 token 风控", email)
+    # 后续 quota_verified=False 分支已经会处理 _cleanup_team_leftover
+```
+
+#### 3.3.2 批判 R-7:不会误伤 personal 转化路径
+
+**结论**:`reinvite_account` 仅由 `_rotate_round` / `_replace_single` 等场景从 STATUS_STANDBY 池选中调用。用户主动转 personal 的入口是 `cmd_fill_personal` → `_run_post_register_oauth(leave_workspace=True)`,**完全不进 reinvite_account**。因此 reinvite 拿到 free plan 永远是异常("Team workspace 同步异常 / token 漂移"),推 AUTH_INVALID 无误伤。
+
+### 3.4 `PREFERRED_SEAT_TYPE` 在 invite_member / _invite_member_once 的应用
+
+**文件**:`src/autoteam/invite.py:496` + `src/autoteam/chatgpt_api.py:1414-1511` + `runtime_config.py`
+**FR**:F1~F6
+
+#### 3.4.1 `runtime_config.py` 新增
+
+```python
+# runtime_config.py 末尾追加
+
+_VALID_SEAT_TYPES = frozenset({"chatgpt", "codex"})
+
+
+def get_preferred_seat_type() -> str:
+    """返回邀请席位偏好。chatgpt(默认):走 default 席位,PATCH 升级;codex:usage_based,不升级."""
+    raw = (get("preferred_seat_type") or "chatgpt").strip().lower()
+    return raw if raw in _VALID_SEAT_TYPES else "chatgpt"
+
+
+def set_preferred_seat_type(value: str) -> str:
+    cleaned = (value or "").strip().lower()
+    if cleaned not in _VALID_SEAT_TYPES:
+        raise ValueError(f"preferred_seat_type 必须是 {_VALID_SEAT_TYPES} 之一")
+    set_value("preferred_seat_type", cleaned)
+    return cleaned
+
+
+def get_runtime(key: str, default):
+    """通用读取(供 sync_account_states 等使用)"""
+    return get(key, default)
+```
+
+#### 3.4.2 `invite.py:496` 改造
+
+```python
+# invite.py:493-496 之间插入
+from autoteam.runtime_config import get_preferred_seat_type
+
+preferred = get_preferred_seat_type()
+seat_type_param = "default" if preferred == "chatgpt" else "usage_based"
+status, data = chatgpt.invite_member(email, seat_type=seat_type_param)
+```
+
+#### 3.4.3 `chatgpt_api.py:_invite_member_once` 加 `allow_patch_upgrade` 参数
+
+```python
+# chatgpt_api.py:1414
+def _invite_member_once(self, email, seat_type, *, allow_patch_upgrade=True):
+    ...
+    # 现行 L1487-1506
+    data["_seat_type"] = "usage_based"
+    if seat_type == "usage_based":
+        if not allow_patch_upgrade:
+            # FR-F3:codex 偏好下不升级,直接保留 usage_based
+            return status, data
+
+        invites = data.get("account_invites", []) ...
+        # 原 PATCH 升级链路保留
+```
+
+#### 3.4.4 `_invite_member_with_fallback` 调整(L1387)
+
+```python
+def _invite_member_with_fallback(self, email, seat_type, *, allow_fallback):
+    preferred = get_preferred_seat_type()
+    allow_patch_upgrade = (preferred == "chatgpt")
+
+    status, data = self._invite_member_once(email, seat_type,
+                                            allow_patch_upgrade=allow_patch_upgrade)
+    # codex 偏好下,不再做 default → usage_based 兜底(直接 usage_based 入口)
+    if preferred == "codex":
+        return status, data
+
+    # 现行 chatgpt 偏好兜底链路保留
+```
+
+### 3.5 personal 删除链短路 fetch_team_state
+
+**文件**:`src/autoteam/account_ops.py:40-162` + `src/autoteam/api.py:1306-1404`
+**FR**:G1~G4
+
+#### 3.5.1 `account_ops.delete_managed_account` 短路
+
+```python
+# account_ops.py:72 起
+from autoteam.accounts import STATUS_PERSONAL, STATUS_AUTH_INVALID
+
+try:
+    account_id = get_chatgpt_account_id()
+    short_circuit = (
+        remove_remote
+        and acc
+        and acc.get("status") in (STATUS_PERSONAL, STATUS_AUTH_INVALID)
+    )
+
+    if remove_remote and not short_circuit:
+        if remote_state is not None:
+            members, invites = remote_state
+        else:
+            if chatgpt_api is None:
+                from autoteam.chatgpt_api import ChatGPTTeamAPI
+                own_chatgpt = ChatGPTTeamAPI()
+                own_chatgpt.start()
+                chatgpt_api = own_chatgpt
+            members, invites = fetch_team_state(chatgpt_api)
+
+        # 现有 member_matches / invite_matches 逻辑保留
+        ...
+    elif short_circuit:
+        logger.info("[账号] %s 状态=%s,跳过 Team 远端同步,直接清本地",
+                    email, acc.get("status"))
+        members, invites = [], []
+
+    # 后续 auth_file / cpa / local 删除链路与现行一致
+```
+
+#### 3.5.2 `api.delete_accounts_batch` 全 personal 短路
+
+```python
+# api.py:1306-1404 之间(伪代码,实施时见现行)
+def delete_accounts_batch(emails: list[str]):
+    accounts = load_accounts()
+    targets = [a for a in accounts if a["email"].lower() in {e.lower() for e in emails}]
+
+    all_personal = all(a["status"] in (STATUS_PERSONAL, STATUS_AUTH_INVALID) for a in targets)
+
+    chatgpt_api = None
+    if not all_personal:
+        # 至少一个号需要 Team 远端同步
+        chatgpt_api = ChatGPTTeamAPI()
+        chatgpt_api.start()
+
+    try:
+        results = []
+        for acc in targets:
+            try:
+                cleanup = delete_managed_account(
+                    acc["email"],
+                    chatgpt_api=chatgpt_api,
+                    sync_cpa_after=False,
+                )
+                results.append({"email": acc["email"], "success": True, "cleanup": cleanup})
+            except Exception as exc:
+                results.append({"email": acc["email"], "success": False, "error": str(exc)})
+        sync_to_cpa()
+        return results
+    finally:
+        if chatgpt_api:
+            chatgpt_api.stop()
+```
+
+### 3.6 UI removeAccount toast 改造
+
+**文件**:`web/src/components/Dashboard.vue:566-585`
+**FR**:G4
+
+#### 3.6.1 改造伪代码(原文 vue + ts)
+
+```vue
+<script setup lang="ts">
+import { ref } from 'vue'
+const message = ref<{ text: string; type: 'success' | 'error' | 'warning' } | null>(null)
+
+async function removeAccount(email: string) {
+  if (props.runningTask) {
+    message.value = { text: '有任务在运行,请先停止后再删除', type: 'warning' }
+    return
+  }
+  if (!adminReady.value && acc.status !== 'personal' && acc.status !== 'auth_invalid') {
+    message.value = { text: '主号未就绪,无法删除该 Team 子号(personal/auth_invalid 不受限)', type: 'warning' }
+    return
+  }
+
+  try {
+    const resp = await api.deleteAccount(email)
+    message.value = { text: `已删除 ${email}`, type: 'success' }
+    emit('refresh')
+  } catch (err: any) {
+    if (err.status === 409) {
+      message.value = { text: '操作冲突,请稍后重试', type: 'error' }
+    } else if (err.status === 500) {
+      message.value = { text: `删除失败:${err.body?.error || '服务器错误'}`, type: 'error' }
+    } else {
+      message.value = { text: `删除失败:${err.message}`, type: 'error' }
+    }
+  }
+}
+</script>
+```
+
+#### 3.6.2 quota 显示 no_quota 识别
+
+```vue
+<template>
+  <span v-if="acc.last_quota?.primary_total === 0" class="quota-empty">
+    无配额(联系管理员)
+  </span>
+  <span v-else-if="acc.last_quota">
+    剩余 {{ 100 - acc.last_quota.primary_pct }}%
+  </span>
+</template>
+```
+
+---
+
+## 4. 数据契约
+
+### 4.1 `accounts.json` 新增字段
+
+| 字段 | 类型 | 默认 | 来源 | 用途 |
+|---|---|---|---|---|
+| `plan_supported` | bool \| null | null | `_exchange_auth_code` 写入(经 `is_supported_plan`) | 标识当时 OAuth bundle 是否在白名单内;旧记录 null,不破坏兼容 |
+| `plan_type_raw` | str \| null | null | `_exchange_auth_code` 写入(JWT 原始字面量) | 事后排查 |
+| `last_kicked_at` | float \| null | null | `sync_account_states` 探测到 wham 401 时写入 | reconcile 历史回放 / UI 展示"X 分钟前被踢" |
+| `last_quota.primary_total` | int \| null | null | `check_codex_quota` 解析 wham/usage 写入 | no_quota 识别;UI 显示"无配额" |
+| `last_quota.primary_remaining` | int \| null | null | 同上 | UI 精确剩余值显示 |
+
+**JSON Schema 片段**:
+
+```json
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "type": "object",
+  "additionalProperties": false,
+  "required": ["email", "status", "created_at"],
+  "properties": {
+    "email": {"type": "string"},
+    "password": {"type": "string"},
+    "cloudmail_account_id": {"type": ["string", "null"]},
+    "status": {"enum": ["active", "exhausted", "standby", "pending", "personal", "auth_invalid", "orphan"]},
+    "seat_type": {"enum": ["chatgpt", "codex", "unknown"]},
+    "workspace_account_id": {"type": ["string", "null"]},
+    "auth_file": {"type": ["string", "null"]},
+    "quota_exhausted_at": {"type": ["number", "null"]},
+    "quota_resets_at": {"type": ["number", "null"]},
+    "last_quota_check_at": {"type": ["number", "null"]},
+    "last_quota": {
+      "type": ["object", "null"],
+      "properties": {
+        "primary_pct": {"type": "integer", "minimum": 0, "maximum": 100},
+        "primary_resets_at": {"type": "integer"},
+        "primary_total": {"type": ["integer", "null"]},
+        "primary_remaining": {"type": ["integer", "null"]},
+        "weekly_pct": {"type": "integer", "minimum": 0, "maximum": 100},
+        "weekly_resets_at": {"type": "integer"}
+      }
+    },
+    "last_active_at": {"type": ["number", "null"]},
+    "created_at": {"type": "number"},
+    "plan_supported": {"type": ["boolean", "null"]},
+    "plan_type_raw": {"type": ["string", "null"]},
+    "last_kicked_at": {"type": ["number", "null"]}
+  }
+}
+```
+
+### 4.2 `runtime_config.json` PREFERRED_SEAT_TYPE 等
+
+```json
+{
+  "register_domain": "...",
+  "preferred_seat_type": "chatgpt",
+  "sync_probe_concurrency": 5,
+  "sync_probe_cooldown_minutes": 30,
+  "quota_probe_threshold_pct": 10
+}
+```
+
+| key | 类型 | 默认 | 取值 | UI 字段(Settings.vue) |
+|---|---|---|---|---|
+| `preferred_seat_type` | str | `"chatgpt"` | `chatgpt` / `codex` | "邀请席位偏好"(下拉) |
+| `sync_probe_concurrency` | int | 5 | 1..20 | "同步探测并发数"(数字输入) |
+| `sync_probe_cooldown_minutes` | int | 30 | 5..1440 | "探测去重分钟数"(数字输入) |
+| `quota_probe_threshold_pct` | int | 10 | 0..100 | "Quota 阈值百分比"(已存在,新管理) |
+
+### 4.3 完整 Pydantic 模型(实施期复制粘贴)
+
+```python
+# src/autoteam/_models.py(可新建,或挂在 accounts.py 末尾)
+"""
+内部 Pydantic 模型 — 给类型检查 / 测试断言 / OpenAPI schema 用。
+
+落盘仍是 dict(load_accounts/save_accounts),Pydantic 模型不替换 dict。
+仅在边界(api.py 入参 / out / 测试)用 model_validate / model_dump。
+"""
+from typing import Literal, Optional, Union
+from pydantic import BaseModel, Field
+
+AccountStatus = Literal["active", "exhausted", "standby", "pending", "personal", "auth_invalid", "orphan"]
+SeatType = Literal["chatgpt", "codex", "unknown"]
+QuotaStatus = Literal["ok", "exhausted", "no_quota", "auth_error", "network_error"]
+
+
+class QuotaSnapshot(BaseModel):
+    primary_pct: int = 0
+    primary_resets_at: int = 0
+    primary_total: Optional[int] = None
+    primary_remaining: Optional[int] = None
+    weekly_pct: int = 0
+    weekly_resets_at: int = 0
+
+
+class QuotaExhaustedInfo(BaseModel):
+    window: Literal["primary", "weekly", "combined", "limit", "no_quota"]
+    resets_at: int
+    quota_info: QuotaSnapshot
+    limit_reached: bool = False
+
+
+class QuotaProbeResult(BaseModel):
+    status: QuotaStatus
+    info: Optional[Union[QuotaSnapshot, QuotaExhaustedInfo]] = None
+
+
+class AccountRecord(BaseModel):
+    email: str
+    password: str = ""
+    cloudmail_account_id: Optional[str] = None
+    status: AccountStatus
+    seat_type: SeatType = "unknown"
+    workspace_account_id: Optional[str] = None
+    auth_file: Optional[str] = None
+    quota_exhausted_at: Optional[float] = None
+    quota_resets_at: Optional[float] = None
+    last_quota_check_at: Optional[float] = None
+    last_quota: Optional[QuotaSnapshot] = None
+    last_active_at: Optional[float] = None
+    created_at: float
+    plan_supported: Optional[bool] = None
+    plan_type_raw: Optional[str] = None
+    last_kicked_at: Optional[float] = None
+
+
+class OAuthBundle(BaseModel):
+    """codex_auth._exchange_auth_code 返回的 bundle 结构(实施期可作为类型注解)"""
+    access_token: str
+    refresh_token: str
+    id_token: str
+    account_id: str
+    email: str
+    plan_type: str            # 已归一化 .lower()
+    plan_type_raw: str        # 原始字面量
+    plan_supported: bool
+    expired: float
+
+
+class RegisterFailureRecord(BaseModel):
+    """register_failures.json 单条记录结构"""
+    timestamp: float
+    email: str
+    category: Literal[
+        "phone_blocked", "duplicate_exhausted", "register_failed",
+        "oauth_failed", "kick_failed", "team_oauth_failed", "exception",
+        "oauth_phone_blocked",      # 新增 §5.2.5
+        "plan_unsupported",         # 新增
+        "no_quota_assigned",        # 新增
+        "plan_drift",               # 新增
+        "auth_error_at_oauth",      # 新增
+        "quota_probe_network_error",# 新增
+    ]
+    reason: str
+    stage: Optional[str] = None
+    step: Optional[str] = None
+    plan_type: Optional[str] = None
+    plan_type_raw: Optional[str] = None
+    url: Optional[str] = None
+```
+
+---
+
+## 5. 测试用例
+
+### 5.1 FR-A:plan_type 白名单(每 FR 至少 2 case)
+
+| # | 用例 | 预期 |
+|---|---|---|
+| 5.1.1 | bundle.plan_type=`team` → `is_supported_plan` | True,plan_supported=True |
+| 5.1.2 | bundle.plan_type=`self_serve_business_usage_based` | False;manager 调用方标 STATUS_AUTH_INVALID + record_failure("plan_unsupported") |
+
+测试入口:`tests/unit/test_plan_type_whitelist.py`(参见 [./shared/plan-type-whitelist.md §6.2](./shared/plan-type-whitelist.md))
+
+### 5.2 FR-B:wham/usage 5 分类
+
+| # | 用例 | 预期 |
+|---|---|---|
+| 5.2.1 | wham 200 + `primary.limit==0` | status=`no_quota`,info.window=`no_quota` |
+| 5.2.2 | wham 200 + `used_percent==100` | status=`exhausted`,info.window=`primary` |
+| 5.2.3 | wham 401 | status=`auth_error`,info=None |
+| 5.2.4 | wham 429 | status=`network_error`(不能误判 auth_error) |
+
+测试入口:`tests/unit/test_quota_classification.py`(参见 [./shared/quota-classification.md §6.2](./shared/quota-classification.md))
+
+### 5.3 FR-C:add-phone 探针
+
+| # | 用例 | 预期 |
+|---|---|---|
+| 5.3.1 | OAuth callback 前 page.url=`/add-phone` | `assert_not_blocked` raise RegisterBlocked(is_phone=True) |
+| 5.3.2 | consent 页含"phone"帮助链接但无 tel input | `detect_phone_verification` 返回 False(避免误报) |
+| 5.3.3 | reinvite_account 抛 RegisterBlocked → STATUS_AUTH_INVALID + `_cleanup_team_leftover` 被调 | 验证 record_failure("oauth_phone_blocked", stage="reinvite_account") |
+
+### 5.4 FR-D:`_run_post_register_oauth` quota probe
+
+| # | 用例 | 预期 |
+|---|---|---|
+| 5.4.1 | bundle ok + wham `ok` | STATUS_ACTIVE,last_quota 有写入 |
+| 5.4.2 | bundle ok + wham `no_quota` | STATUS_AUTH_INVALID,record_failure("no_quota_assigned") |
+| 5.4.3 | bundle ok + plan_supported=False | STATUS_AUTH_INVALID,record_failure("plan_unsupported"),不进 ACTIVE |
+| 5.4.4 | bundle 抛 RegisterBlocked(is_phone=True) | STATUS_AUTH_INVALID,record_failure("oauth_phone_blocked") |
+
+### 5.5 FR-E:sync_account_states 区分被踢 / 待机
+
+| # | 用例 | 预期 |
+|---|---|---|
+| 5.5.1 | active 不在 Team + wham 401 | STATUS_AUTH_INVALID,last_kicked_at 写入 |
+| 5.5.2 | active 不在 Team + wham ok | STATUS_STANDBY(自然待机) |
+| 5.5.3 | active 不在 Team + workspace_account_id 漂移 | 保留 ACTIVE(母号切换守卫) |
+| 5.5.4 | 同 email 30 分���内重复探测 | 第二次跳过(去重),保持上轮状态 |
+
+### 5.6 FR-F:PREFERRED_SEAT_TYPE
+
+| # | 用例 | 预期 |
+|---|---|---|
+| 5.6.1 | preferred=chatgpt → invite_member(seat_type="default") + PATCH 升级 | 行为不变(回归测试) |
+| 5.6.2 | preferred=codex → invite_member(seat_type="usage_based") + 0 处 PATCH | 日志中无"修改邀请 seat_type" |
+
+### 5.7 FR-G:personal 删除短路
+
+| # | 用例 | 预期 |
+|---|---|---|
+| 5.7.1 | acc.status=personal + 主号 session 失效 → 单点删除 | 不抛 ChatGPTTeamAPI 启动错误,本地记录被清 |
+| 5.7.2 | 批量删除 5 个 personal | 完全不起 ChatGPTTeamAPI |
+
+### 5.8 FR-H:reinvite plan_drift / phone_blocked
+
+| # | 用例 | 预期 |
+|---|---|---|
+| 5.8.1 | reinvite bundle.plan=`free` | STATUS_AUTH_INVALID + record_failure("plan_drift"),auth_file=None |
+| 5.8.2 | reinvite RegisterBlocked(is_phone=True) | STATUS_AUTH_INVALID + record_failure("oauth_phone_blocked", stage="reinvite_account") |
+| 5.8.3 | 标到 AUTH_INVALID 后下轮不再被 standby 池选中 | reinvite_account 不再被调用 |
+
+### 5.9 集成测试
+
+| # | 用例 | 预期 |
+|---|---|---|
+| 5.9.1 | mock 一个 self_serve_business_usage_based bundle 跑全链路 | 注册 → STATUS_AUTH_INVALID,UI 显示 "无配额(联系管理员)" |
+| 5.9.2 | 模拟管理员手动从 ChatGPT 后台踢号 → 等下次 sync | 状态机正确转 STATUS_AUTH_INVALID,reconcile 自动 KICK + 留本地记录 |
+| 5.9.3 | preferred_seat_type=codex 下注册新号 | seat_type=codex,_seat_type=usage_based,UI 显示 "Codex 席位" |
+
+---
+
+## 6. 实施顺序(Story Map → Sub-task 依赖图)
+
+依赖图(箭头 → 表示"必须先于"):
+
+```
+Phase 0 (spec 落地)
+├─ S-0.1 accounts.py 加白名单常量 + 工具函数
+├─ S-0.2 runtime_config.py 加 PREFERRED_SEAT_TYPE 等
+├─ S-0.3 register_failures.py docstring 扩 6 category
+└─ S-0.4 _models.py 写 Pydantic 模型(可选,用于测试)
+        │
+        ▼
+Phase 1 (核心实现)
+├─ S-1.1 codex_auth._exchange_auth_code 写 bundle 字段     ◄── 依赖 S-0.1
+├─ S-1.2 codex_auth.check_codex_quota 加 no_quota          ◄── 独立
+├─ S-1.3 codex_auth.login_codex_via_browser 4 探针         ◄── 独立
+├─ S-1.4 manager._run_post_register_oauth probe + catch    ◄── 依赖 S-1.1/1.2/1.3
+├─ S-1.5 manager.sync_account_states 探测                  ◄── 依赖 S-1.2
+├─ S-1.6 manager.reinvite_account 兜底                     ◄── 依赖 S-1.1/1.2/1.3
+├─ S-1.7 manual_account._finalize_account 扩展             ◄── 依赖 S-0.1/S-1.2
+└─ S-1.8 account_ops.delete_managed_account 短路           ◄── 独立
+        │
+        ▼
+Phase 2 (调用方处置)
+├─ S-2.1 manager._check_pending_invites L1057 catch        ◄── 依赖 S-1.3
+├─ S-2.2 api.post_account_login L1479 catch + 409          ◄── 依赖 S-1.3
+├─ S-2.3 9 处 check_codex_quota 调用方加 no_quota 分支     ◄── 依赖 S-1.2
+└─ S-2.4 api.delete_accounts_batch 全 personal 短路        ◄── 依赖 S-1.8
+        │
+        ▼
+Phase 3 (席位策略,可与 P1/P2 并行)
+├─ S-3.1 invite.py L496 读 PREFERRED_SEAT_TYPE             ◄── 依赖 S-0.2
+├─ S-3.2 chatgpt_api._invite_member_once 加参数            ◄── 依赖 S-3.1
+└─ S-3.3 _invite_member_with_fallback 调整                 ◄── 依赖 S-3.2
+        │
+        ▼
+Phase 4 (前端)
+├─ S-4.1 Settings.vue 加 preferred_seat_type / 探测配置     ◄── 依赖 S-0.2
+├─ S-4.2 Dashboard.vue removeAccount toast / quota 显示    ◄── 依赖 S-1.8
+└─ S-4.3 api.ts 解析 409 phone_required + 422 no_quota     ◄── 依赖 S-2.2
+        │
+        ▼
+Phase 5 (测试 + 文档,贯穿)
+├─ S-5.1 单测覆盖 §5.1~5.8                                 ◄── 跟随各 sub-task
+├─ S-5.2 集成测试 §5.9                                     ◄── 在 P1+P2 完成后
+├─ S-5.3 CHANGELOG.md 增补                                 ◄── 在所有 sub-task 完成后
+└─ S-5.4 docs/account-state-machine.md 等新文档            ◄── 同上
+        │
+        ▼
+Phase 6 (灰度上线)
+├─ S-6.1 默认 chatgpt 偏好上线,观察 register_failures
+└─ S-6.2 1-2 周后根据 PATCH 失败率决议默认值切换
+```
+
+**关键串行链**:S-0.1 → S-1.1 → S-1.4 / S-1.6 / S-1.7;S-0.2 → S-3.x;S-1.3 → S-2.1 / S-2.2
+
+**可并行链**:Phase 1 的 S-1.2 / S-1.3 / S-1.8 互不依赖;Phase 3 与 Phase 1/2 完全并行
+
+---
+
+## 7. 验收清单(完成检查表)
+
+### 7.1 代码层
+
+- [ ] `accounts.py` 含 `SUPPORTED_PLAN_TYPES` + `is_supported_plan` + `normalize_plan_type`
+- [ ] `codex_auth._exchange_auth_code` bundle 含 `plan_type`(归一化)/ `plan_type_raw` / `plan_supported`
+- [ ] `codex_auth.check_codex_quota` 5 分类,no_quota 触发条件 4 项已实现
+- [ ] `codex_auth.login_codex_via_browser` 4 处 `assert_not_blocked` 接入(C-P1~C-P4)
+- [ ] `manager._run_post_register_oauth` Team / personal 双分支 catch + probe
+- [ ] `manager.sync_account_states` 并发探测被踢识别 + 30 分钟去重
+- [ ] `manager.reinvite_account` plan_drift / phone_blocked / plan_unsupported 三路兜底
+- [ ] `manual_account._finalize_account` plan_supported 检查
+- [ ] `account_ops.delete_managed_account` short_circuit
+- [ ] `api.post_account_login` 409 phone_required
+- [ ] `api.delete_accounts_batch` 全 personal 不起 ChatGPTTeamAPI
+- [ ] `invite.py` + `chatgpt_api.py` PREFERRED_SEAT_TYPE 链路
+- [ ] `runtime_config.py` 4 个新 getter / setter
+
+### 7.2 数据层
+
+- [ ] 旧 `accounts.json` 记录(无新字段)读取无报错
+- [ ] 新增 `last_kicked_at` / `plan_supported` / `plan_type_raw` 落盘
+- [ ] `last_quota.primary_total` / `primary_remaining` 落盘
+- [ ] `register_failures.json` 6 个新 category 计数
+
+### 7.3 前端
+
+- [ ] Settings.vue 邀请席位偏好下拉
+- [ ] Dashboard.vue removeAccount 失败 toast 区分 actionDisabled / 409 / 500
+- [ ] Dashboard.vue quota 显示 no_quota 时文案 "无配额(联系管理员)"
+
+### 7.4 测试
+
+- [ ] 全部单测通过(§5.1~5.8 各 ≥2 case)
+- [ ] 集成测试通过(§5.9)
+- [ ] 回归测试通过(invite / reinvite / sync / cmd_check)
+
+### 7.5 文档
+
+- [ ] CHANGELOG.md 列出 5 个新 category + 4 个 OAuth 探针接入点 + PREFERRED_SEAT_TYPE
+- [ ] 4 份 shared spec 文件路径在 CHANGELOG / README 引用
+- [ ] docs/oauth-add-phone-detection.md / quota-classification.md / account-state-machine.md 落地(或合入主 README)
+
+### 7.6 灰度
+
+- [ ] 默认 PREFERRED_SEAT_TYPE=chatgpt 行为不变
+- [ ] 1-2 周后根据 register_failures 数据决议是否切默认值
+
+---
+
+**文档结束。** 工程师参照本 spec + 4 份 shared spec,无需查询 PRD 即可完成代码实施。

prompts/0426/spec/spec-3-docker-guard.md

@@ -0,0 +1,525 @@
+# SPEC-3: Docker 镜像守卫 实施规范
+
+## 0. 元数据
+
+| 字段 | 值 |
+|---|---|
+| SPEC 编号 | SPEC-3 |
+| 主笔 | prd-docker(autoteam-prd-0426) |
+| 起草日期 | 2026-04-26 |
+| 上游 PRD | `prompts/0426/prd/prd-3-docker-guard.md` |
+| 关联调研 | `prompts/0426/research/issue-3-list-accounts-import.md` |
+| 关联代码修复 | commit `cf2f7d3 fix(round-3): ...` |
+| 实施优先级 | P1 |
+| 预计耗时 | 2-3 小时(单人) |
+
+> 本 SPEC 提供"打开就能编码"的所有具体内容:实际 entrypoint 脚本、Dockerfile diff、ruff 配置文件、`/api/version` 端点 Pydantic 响应模型、`docs/docker.md` SOP 完整文案。直接复制粘贴即可落地,**无需再做技术决策**。
+
+---
+
+## 1. 文件级修改清单
+
+| 文件 | 操作 | 说明 |
+|---|---|---|
+| `Dockerfile` | 修改 | 在 `WORKDIR /app` 之后增加 ARG/LABEL/ENV |
+| `docker-compose.yml` | 修改 | `build: .` 扩为对象 + `args: GIT_SHA / BUILD_TIME` |
+| `docker-entrypoint.sh` | 修改 | 在 `exec uv run autoteam` 之前增加 self-check |
+| `pyproject.toml` | 修改 | 新增 `[tool.ruff.lint]` 段(dev 依赖已声明 ruff>=0.15.10) |
+| `.pre-commit-config.yaml` | 新建 | ruff hook(规则 F401/F811/F821) |
+| `src/autoteam/api.py` | 修改 | 在 `app = FastAPI(...)` 之后新增 Pydantic VersionResponse + `/api/version` 路由 |
+| `docs/docker.md` | 修改 | 末尾追加"代码更新后的 rebuild SOP"+"版本验证"+"故障排查"三章节 |
+| `docs/api.md` | 修改 | 追加 `/api/version` 端点说明 |
+| `CHANGELOG.md` | 修改 | 添加 SPEC-3 落地记录 |
+
+---
+
+## 2. entrypoint self-check 脚本(完整文件)
+
+文件:`docker-entrypoint.sh`(在现有内容末尾、`exec uv run autoteam "$@"` 之前**插入**下列段)。
+
+```bash
+#!/bin/bash
+set -e
+
+# 清理残留锁文件并启动虚拟显示器
+rm -f /tmp/.X99-lock
+Xvfb :99 -screen 0 1280x800x24 &
+export DISPLAY=:99
+
+# 确保数据目录存在且可写
+mkdir -p /app/data /app/data/auths /app/data/screenshots
+chmod -R 777 /app/data
+
+# 数据文件:无条件软链到 data/(确保所有写入都持久化)
+for f in .env accounts.json state.json; do
+    [ -f "/app/data/$f" ] || touch "/app/data/$f"
+    rm -f "/app/$f"
+    ln -s "/app/data/$f" "/app/$f"
+done
+
+# 目录软链
+for d in auths screenshots; do
+    rm -rf "/app/$d"
+    ln -s "/app/data/$d" "/app/$d"
+done
+
+# ---------------------------------------------------------------------------
+# Self-check: 关键 import 白名单 — 失败即 crash-loop(SPEC-3 §2)
+# ---------------------------------------------------------------------------
+echo "[self-check] verifying critical imports..."
+uv run python - <<'PYEOF' || {
+    echo "[self-check] FATAL: critical import failed - image is likely stale or broken." >&2
+    echo "[self-check] If you just pulled new code, the image must be rebuilt:" >&2
+    echo "[self-check]   docker compose down" >&2
+    echo "[self-check]   docker compose build --no-cache --build-arg GIT_SHA=\$(git rev-parse --short HEAD)" >&2
+    echo "[self-check]   docker compose up -d" >&2
+    exit 1
+}
+import sys
+
+# 核心 web 应用入口
+from autoteam.api import app  # noqa: F401
+
+# accounts.py 全部对外契约符号(典型 typo 高发区)
+from autoteam.accounts import (  # noqa: F401
+    load_accounts,
+    save_accounts,
+    STATUS_ACTIVE,
+    STATUS_EXHAUSTED,
+    STATUS_STANDBY,
+    STATUS_PENDING,
+    STATUS_PERSONAL,
+    STATUS_AUTH_INVALID,
+    STATUS_ORPHAN,
+)
+
+# manager → accounts 链路(覆盖跨模块 typo)
+from autoteam.manager import sync_account_states  # noqa: F401
+
+print("[self-check] OK: %d critical symbols imported." % 11)
+sys.exit(0)
+PYEOF
+echo "[self-check] passed."
+
+# 执行命令
+exec uv run autoteam "$@"
+```
+
+**设计要点**:
+
+1. `uv run python - <<'PYEOF' ... PYEOF` heredoc 写法保证脚本与 entrypoint 同源,不需另起 `scripts/self_check.py`
+2. heredoc 用单引号 `'PYEOF'` — 禁止 shell 变量插值,避免 `$variable` 被宿主 bash 解析
+3. `||{ ... ; exit 1; }` — Python 进程非零退出时立即输出 rebuild 提示并 `exit 1`,触发 docker `restart: unless-stopped` 的 crash-loop
+4. 自检符号只列 **11 个稳定契约**(2 函数 + 7 状态常量 + 1 外部 app + 1 跨模块函数),不列易变函数;改这些符号需同步改自检
+5. 整体延迟 **< 1 秒**(冷启动 Python 解释器 + 单文件 import)
+
+---
+
+## 3. Dockerfile diff(完整新版本)
+
+```dockerfile
+FROM python:3.12-slim
+
+# 系统依赖
+RUN apt-get update && apt-get install -y --no-install-recommends \
+    xvfb \
+    curl \
+    fonts-noto-cjk \
+    && rm -rf /var/lib/apt/lists/*
+
+# 安装 uv
+RUN curl -LsSf https://astral.sh/uv/install.sh | sh
+ENV PATH="/root/.local/bin:$PATH"
+
+WORKDIR /app
+
+# === SPEC-3 §3: 镜像版本指纹注入 ===
+ARG GIT_SHA=unknown
+ARG BUILD_TIME=unknown
+LABEL org.opencontainers.image.revision="${GIT_SHA}"
+LABEL org.opencontainers.image.created="${BUILD_TIME}"
+ENV AUTOTEAM_GIT_SHA="${GIT_SHA}"
+ENV AUTOTEAM_BUILD_TIME="${BUILD_TIME}"
+# === SPEC-3 §3 end ===
+
+# 复制项目文件
+COPY pyproject.toml uv.lock ./
+RUN uv sync --no-dev
+
+# 安装 Playwright 浏览器
+RUN uv run playwright install chromium && uv run playwright install-deps chromium
+
+# 复制源码
+COPY src/ src/
+COPY web/ web/
+
+# 数据卷
+VOLUME ["/app/data"]
+
+# 启动时将数据目录软链到工作目录
+RUN mkdir -p /app/data
+ENV DISPLAY=:99
+
+EXPOSE 8787
+
+# 启动脚本
+COPY docker-entrypoint.sh /docker-entrypoint.sh
+RUN chmod +x /docker-entrypoint.sh
+
+ENTRYPOINT ["/docker-entrypoint.sh"]
+CMD ["api"]
+```
+
+**关键约束**:
+
+- ARG 块**必须在 WORKDIR 之后、`COPY pyproject.toml` 之前** — 这样 build args 变化时不会击穿后续昂贵的 `uv sync` / `playwright install` 缓存层
+- 默认值 `unknown` 让"不传 build-arg 直接 build"也能跑成功(降级语义)
+- `org.opencontainers.image.*` 是 OCI 标准 label,`docker image inspect` 自动展示
+
+---
+
+## 4. docker-compose.yml diff(完整新版本)
+
+```yaml
+services:
+  autoteam:
+    build:
+      context: .
+      args:
+        GIT_SHA: ${GIT_SHA:-unknown}
+        BUILD_TIME: ${BUILD_TIME:-unknown}
+    ports:
+      - "8787:8787"
+    volumes:
+      - ./data:/app/data
+    restart: unless-stopped
+```
+
+**关键约束**:
+
+- `${GIT_SHA:-unknown}` — Compose 标准变量插值,未设环境变量时回落 `unknown`
+- 用户日常 `docker compose build` 仍能成功(只是 sha 显示 unknown,**不报错**)
+- 推荐一键命令(写入 `docs/docker.md`):
+
+```bash
+GIT_SHA=$(git rev-parse --short HEAD) BUILD_TIME=$(date -u +%FT%TZ) docker compose build --no-cache
+```
+
+---
+
+## 5. /api/version 端点契约
+
+文件:`src/autoteam/api.py`,在 **line 25** `app = FastAPI(...)` 定义之后、line 27 注释行之前**插入**:
+
+```python
+# ---------------------------------------------------------------------------
+# 版本端点 (SPEC-3 §5) - 不鉴权,纯只读
+# ---------------------------------------------------------------------------
+
+
+class VersionResponse(BaseModel):
+    """镜像版本指纹响应 - 来自 Dockerfile build args。"""
+
+    git_sha: str
+    build_time: str
+
+
+@app.get(
+    "/api/version",
+    response_model=VersionResponse,
+    summary="返回镜像构建期注入的 git-sha 与时间戳",
+    tags=["meta"],
+)
+def api_version() -> VersionResponse:
+    return VersionResponse(
+        git_sha=os.getenv("AUTOTEAM_GIT_SHA", "unknown"),
+        build_time=os.getenv("AUTOTEAM_BUILD_TIME", "unknown"),
+    )
+```
+
+**鉴权豁免**:`/api/version` 必须加入 `_AUTH_SKIP_PATHS`(api.py:31)白名单。修改:
+
+```python
+_AUTH_SKIP_PATHS = {"/api/auth/check", "/api/setup/status", "/api/setup/save", "/api/version"}
+```
+
+**响应示例**:
+
+```json
+{
+  "git_sha": "cf2f7d3",
+  "build_time": "2026-04-26T03:00:00Z"
+}
+```
+
+**安全保证**:端点只暴露 build-arg 注入的两个字符串,不读 secret / 路径 / 主机名,免鉴权安全。
+
+---
+
+## 6. ruff 配置(pyproject.toml 完整片段)
+
+在 `pyproject.toml` 末尾(line 35 之后)**追加**:
+
+```toml
+# ---------------------------------------------------------------------------
+# Ruff lint (SPEC-3 §6) - 仅启 F401/F811/F821 三条零误报规则
+# ---------------------------------------------------------------------------
+[tool.ruff]
+target-version = "py310"
+line-length = 120
+src = ["src", "tests"]
+
+[tool.ruff.lint]
+# F401: imported but unused (死 import)
+# F811: redefinition of unused (重复定义)
+# F821: undefined name (核心 — 抓 typo 类 ImportError)
+select = ["F401", "F811", "F821"]
+
+# 测试 / 文档 / 脚本豁免(可能含 docstring 示例 / 故意未定义符号)
+exclude = [
+    "tests/",
+    "docs/",
+    "scripts/",
+    ".venv/",
+    "build/",
+    "dist/",
+]
+
+[tool.ruff.lint.per-file-ignores]
+# __init__.py 允许 re-export
+"__init__.py" = ["F401"]
+```
+
+**为什么只选 F401/F811/F821**:
+
+- 这三条**零误报**(语义错误而非风格),不打扰现有代码
+- F821 是抓 `from autoteam.accounts import list_accounts` 这种 typo 的核心规则
+- 后续如要追加 E/W/B 等 style 规则可单独 PR,不在本 SPEC 范围
+
+**手动执行**(开发期自检):
+
+```bash
+uv run ruff check src/
+```
+
+---
+
+## 7. pre-commit hook 配置
+
+新建文件:`.pre-commit-config.yaml`(项目根目录)。
+
+```yaml
+# SPEC-3 §7: pre-commit ruff hook
+# 安装:uv run pre-commit install
+# 手动跑全仓:uv run pre-commit run --all-files
+
+repos:
+  - repo: https://github.com/astral-sh/ruff-pre-commit
+    rev: v0.7.0
+    hooks:
+      - id: ruff
+        name: ruff (F401/F811/F821)
+        args:
+          - --select
+          - F401,F811,F821
+          - --exit-non-zero-on-fix
+```
+
+**首次启用步骤**(写入 docs):
+
+```bash
+uv sync                           # 装好 dev 依赖(pre-commit 已声明)
+uv run pre-commit install         # 注入 .git/hooks/pre-commit
+uv run pre-commit run --all-files # 一次性扫全仓,确认基线干净
+```
+
+---
+
+## 8. docs/docker.md SOP 章节完整��案
+
+在 `docs/docker.md` 末尾**追加**以下章节(原文档已有的内容保持不变):
+
+```markdown
+---
+
+## 代码更新后的 rebuild SOP(SPEC-3 §8)
+
+> **关键认知**:本项目 `Dockerfile` 用 `COPY src/`(非 volume mount),
+> **`git pull` 后必须 rebuild 镜像**,代码改动才会进入容器。
+
+### 标准更新流程(4 步)
+
+```bash
+# 1. 拉取新代码
+cd /path/to/AutoTeam && git pull
+
+# 2. 停掉旧容器
+docker compose down
+
+# 3. 重建镜像(--no-cache 防意外缓存命中,GIT_SHA 注入版本指纹)
+GIT_SHA=$(git rev-parse --short HEAD) \
+BUILD_TIME=$(date -u +%FT%TZ) \
+docker compose build --no-cache
+
+# 4. 启动
+docker compose up -d
+```
+
+### 验证镜像版本(三选一,结果应一致)
+
+```bash
+# 方式 A:HTTP 端点(免鉴权)
+curl http://localhost:8787/api/version
+# 期望:{"git_sha":"cf2f7d3","build_time":"2026-04-26T..."}
+
+# 方式 B:进容器查环境变量
+docker compose exec autoteam env | grep AUTOTEAM_GIT_SHA
+
+# 方式 C:看镜像 OCI label(无需启动容器)
+docker image inspect autoteam-autoteam --format '{{json .Config.Labels}}'
+```
+
+### 启动期 self-check
+
+容器每次启动都会执行 `[self-check]` 段,白名单 import 任一失败立即 `exit 1` → docker 进入 crash-loop。
+
+```bash
+docker compose logs autoteam | head -20
+# 期望看到:
+# [self-check] verifying critical imports...
+# [self-check] OK: 11 critical symbols imported.
+# [self-check] passed.
+```
+
+### 故障排查:为什么修了代码 bug 还在?
+
+**99% 是镜像没 rebuild**。先跑这条快速诊断:
+
+```bash
+# 对比 image 内 sha 与 repo HEAD
+echo "image:" && curl -s http://localhost:8787/api/version | python -m json.tool
+echo "repo HEAD:" && git rev-parse --short HEAD
+```
+
+如果 `image.git_sha` 与 `repo HEAD` 不一致 → 重做上面 4 步 SOP。
+
+如果 self-check 报 `FATAL: critical import failed`:
+- 说明镜像里的源码与最新代码的契约符号对不上(典型 typo 引入未定义名)
+- 解决:回退最近 commit 或修复 typo,再 rebuild
+```
+
+---
+
+## 9. 测试用例
+
+### 9.1 本地 docker 端到端(必跑)
+
+```bash
+cd D:/Desktop/AutoTeam
+
+# 步骤 1: 全量 rebuild
+docker compose down
+GIT_SHA=$(git rev-parse --short HEAD) BUILD_TIME=$(date -u +%FT%TZ) docker compose build --no-cache
+
+# 步骤 2: 启动 + 验证 self-check 通过
+docker compose up -d
+sleep 5
+docker compose logs autoteam | grep -E "(self-check|FATAL)"
+# 期望: "[self-check] OK" + "[self-check] passed"
+
+# 步骤 3: 验证 /api/version
+curl -s http://localhost:8787/api/version | python -m json.tool
+# 期望: { "git_sha": "<7-char sha>", "build_time": "<ISO8601>" } 两字段都非 unknown
+
+# 步骤 4: 验证 env 与 OCI label 一致
+docker compose exec autoteam env | grep AUTOTEAM_GIT_SHA
+docker image inspect autoteam-autoteam --format '{{.Config.Labels}}'
+# 期望: 三处 sha 字符串完全相同
+```
+
+### 9.2 self-check 故障注入(回归保险)
+
+```bash
+# 步骤 1: 临时损坏 accounts.py
+sed -i.bak 's/^def load_accounts/def loadaccounts/' src/autoteam/accounts.py
+
+# 步骤 2: rebuild + 启动 → 应 crash-loop
+GIT_SHA=test docker compose build --no-cache
+docker compose up -d
+sleep 5
+docker compose ps  # 期望 STATUS = Restarting (1)
+docker compose logs autoteam | grep "FATAL"
+# 期望:命中 "[self-check] FATAL"
+
+# 步骤 3: 恢复 + rebuild
+mv src/autoteam/accounts.py.bak src/autoteam/accounts.py
+docker compose build --no-cache && docker compose up -d
+```
+
+### 9.3 lint 守卫验证
+
+```bash
+# 步骤 1: 制造 typo
+echo "from autoteam.accounts import list_accounts" > src/autoteam/_lint_canary.py
+
+# 步骤 2: ruff 应拦截
+uv run ruff check src/
+# 期望: F821 Undefined name `list_accounts`,exit code = 1
+
+# 步骤 3: pre-commit 应拦截
+git add src/autoteam/_lint_canary.py
+git commit -m "test"
+# 期望:被 ruff hook 拒绝,commit 未生成
+
+# 步骤 4: 清理
+rm src/autoteam/_lint_canary.py
+git reset HEAD
+```
+
+### 9.4 降级路径(不传 build-arg)
+
+```bash
+docker compose down
+docker compose build --no-cache  # 不传 GIT_SHA / BUILD_TIME
+docker compose up -d
+sleep 5
+curl -s http://localhost:8787/api/version
+# 期望: { "git_sha": "unknown", "build_time": "unknown" } — 不报错,正常返回
+```
+
+---
+
+## 10. 实施顺序
+
+按依赖顺序串行(每步独立可回滚):
+
+1. **`pyproject.toml` 增 `[tool.ruff]`** → 跑 `uv run ruff check src/` 确认基线干净
+2. **`.pre-commit-config.yaml` 新建** → `uv run pre-commit install` + `pre-commit run --all-files`
+3. **`src/autoteam/api.py` 增 `/api/version`** → 本地 `uv run uvicorn autoteam.api:app` 测 `curl /api/version`(返 unknown)
+4. **`Dockerfile` 增 ARG/LABEL/ENV** → `docker build --build-arg GIT_SHA=test .` 测构建成功
+5. **`docker-compose.yml` 改 build 段** → `docker compose config` 验语法
+6. **`docker-entrypoint.sh` 增 self-check** → `docker compose build && docker compose up -d` 看日志
+7. **`docs/docker.md` + `docs/api.md` 增章节** → 评审文档可读性
+8. **`CHANGELOG.md` 加条目**
+9. 跑完整 §9.1 ~ §9.4 端到端测试
+
+---
+
+## 11. 验收清单
+
+| ID | 验收点 | 检验方式 | 通过条件 |
+|---|---|---|---|
+| AC1 | self-check 正常路径通过 | `docker compose logs` 含 "self-check passed" | ✅ 命中 |
+| AC2 | self-check 拦截 typo | §9.2 故障注入后容器 crash-loop | ✅ STATUS=Restarting |
+| AC3 | `/api/version` 返回正确字段 | `curl /api/version` 返 `git_sha + build_time` 双字段 | ✅ JSON 合法 |
+| AC4 | 三处 sha 一致 | env / curl / label 三种姿势 sha 字符串相同 | ✅ 字符串相等 |
+| AC5 | ruff F821 拦截 typo | §9.3 第 2 步 exit code = 1 | ✅ 非零退出 |
+| AC6 | pre-commit 拦截 commit | §9.3 第 3 步 commit 失败 | ✅ commit 未生成 |
+| AC7 | 不传 build-arg 不报错 | §9.4 返 unknown 正常 | ✅ 返 200 |
+| AC8 | docs SOP 可粘贴执行 | 新人按 docs/docker.md 4 步操作 | ✅ 一次跑通 |
+| AC9 | `/api/version` 免鉴权 | 不带 Bearer 直接 curl | ✅ 返 200 |
+| AC10 | 现有功能无回归 | 既有测试套 `uv run pytest` 全绿 | ✅ 0 失败 |
+
+---
+
+**SPEC-3 完。** 实施时严格按 §10 顺序;遇任何违反 §11 验收点的情况,**必须回滚该步**而非强推 — 每步都是独立可逆单元。

prompts/0426/spec/spec-4-playwright-hardening.md

@@ -0,0 +1,458 @@
+# SPEC-4: Playwright 一致性硬化 实施规范
+
+## 0. 元数据
+
+| 字段 | 值 |
+|---|---|
+| SPEC 编号 | SPEC-4 |
+| 关联 PRD | `prompts/0426/prd/prd-4-playwright-hardening.md` |
+| 关联 Issue | #5(待用户补样本) |
+| 类型 | hardening only(纯防御性,不动业务逻辑) |
+| 状态 | DRAFT-IMPLEMENTABLE |
+| 主笔 | prd-playwright |
+| 创建日期 | 2026-04-26 |
+
+---
+
+## 1. 文件级修改清单
+
+| 序号 | 路径 | 动作 | 说明 |
+|---|---|---|---|
+| 1 | `src/autoteam/_playwright_guard.py` | **新增** | 白名单常量 + `assert_sync_context()` + 豁免 marker 常量 |
+| 2 | `src/autoteam/api.py` | **修改** | `_PlaywrightExecutor.run_with_timeout` + `_worker` 双入口插入 guard(锚点参考研究 §B.2.5,定位行 173-227) |
+| 3 | `src/autoteam/manager.py` | **修改** | 函数内 import 上提至模块顶层(第 1491 行 + 第 1969 行) |
+| 4 | `tests/static/__init__.py` | **新增** | 空文件,确保 pytest 能 collect |
+| 5 | `tests/static/test_playwright_hygiene.py` | **新增** | 3 个 AST 测试 + 1 个豁免列表测试 |
+| 6 | `tests/static/test_playwright_hygiene_negative.py` | **新增** | 反例验证(参见 §7) |
+| 7 | `tests/unit/test_playwright_guard.py` | **新增** | runtime guard 行为测试(asyncio loop 内/外) |
+| 8 | `pyproject.toml` 或 `pytest.ini` | **修改** | `testpaths` 加入 `tests/static`、`tests/unit` |
+| 9 | `CONTRIBUTING.md` | **可选** | 若已存在,追加"Playwright 使用守则"5 行;不存在则跳过 |
+
+**严禁动**:`chatgpt_api.py`、`codex_auth.py`、`invite.py`、`api.py:_PlaywrightExecutor` 之外的代码、所有 `with sync_playwright() as p:` 块本体。
+
+---
+
+## 2. import 白名单常量
+
+落地于 `src/autoteam/_playwright_guard.py`,作为**单一信源**(SSOT),所有静态测试与运行时 guard 共用:
+
+```python
+# src/autoteam/_playwright_guard.py
+"""Playwright 一致性硬化(SPEC-4)。
+本模块提供白名单常量与运行时守卫,禁止 sync_playwright 进入 asyncio loop。
+"""
+from __future__ import annotations
+
+# 9 个允许从 playwright.sync_api 导入的符号
+ALLOWED_SYNC_NAMES: frozenset[str] = frozenset({
+    "sync_playwright",   # 上下文管理器
+    "Playwright",        # 顶层句柄类型
+    "Browser",           # 浏览器实例类型
+    "BrowserContext",    # 浏览器上下文
+    "BrowserType",       # chromium/firefox/webkit 类型
+    "Page",              # 页面句柄
+    "Locator",           # 定位器
+    "Error",             # Playwright 通用异常
+    "TimeoutError",      # Playwright 超时异常
+})
+
+# 1 个 typeshed 类型(仅在 if TYPE_CHECKING 块内允许)
+TYPE_CHECKING_ONLY: frozenset[str] = frozenset({
+    "ElementHandle",  # 仅类型注解使用,运行时禁止
+})
+
+# 任何 from <X> import * 形式的禁止模块
+FORBIDDEN_MODULES: frozenset[str] = frozenset({
+    "playwright.async_api",
+})
+
+# per-file 豁免 marker,文件首 5 行内出现即整文件跳过守卫
+EXEMPTION_MARKER: str = "autoteam: allow-async-playwright"
+```
+
+---
+
+## 3. `_PlaywrightExecutor` guard 完整代码
+
+`assert_sync_context()` 实现(同样在 `_playwright_guard.py` 内)+ `api.py` 调用点 patch。
+
+### 3.1 guard 函数
+
+```python
+# src/autoteam/_playwright_guard.py(续)
+import asyncio
+import logging
+import threading
+
+logger = logging.getLogger(__name__)
+
+
+def assert_sync_context() -> None:
+    """断言当前线程不在 asyncio loop 中。
+    仅用于 sync_playwright 调用前的前置检查。
+    若检测到 loop,立即抛 RuntimeError(中文堆栈 + thread/loop 标识)。
+    """
+    try:
+        loop = asyncio.get_running_loop()
+    except RuntimeError:
+        return  # 期望路径:无 loop
+    raise RuntimeError(
+        f"[PlaywrightGuard] thread={threading.current_thread().name!r} "
+        f"loop_id=0x{id(loop):x} — sync_playwright 不允许在 asyncio loop 中调用。"
+        f"详见 PRD-4 §12 R1 opt-out 流程。"
+    )
+```
+
+### 3.2 `api.py` 双入口 patch(diff 形式)
+
+```python
+# api.py:155 区域(_PlaywrightExecutor 类内,run_with_timeout 入口)
+class _PlaywrightExecutor:
+    def run_with_timeout(self, timeout, func, *args, **kwargs):
++       from autoteam._playwright_guard import assert_sync_context
++       assert_sync_context()  # SPEC-4 §3:主线程前置检查
+        result_event = threading.Event()
+        result_holder: dict = {}
+        self._queue.put((func, args, kwargs, result_event, result_holder))
+        ...
+
+    def _worker(self):
++       from autoteam._playwright_guard import assert_sync_context
++       assert_sync_context()  # SPEC-4 §3:worker 启动检查
+        while True:
+            item = self._queue.get()
+            if item is None:
+                break
+            ...
+```
+
+**双入口必要性**:`run_with_timeout` 在调用方线程检查(可能是 anyio threadpool worker),`_worker` 在专用线程启动时再检查一遍 — 防止某次重构里把 worker 的 `target=` 改成在 loop 内启的协程。
+
+---
+
+## 4. AST 守卫单测完整代码
+
+### 4.1 主测试文件(可粘贴运行)
+
+```python
+# tests/static/test_playwright_hygiene.py
+"""SPEC-4 §4:Playwright import + async/sync 分离静态守卫。
+通过 AST 扫描 src/autoteam/**/*.py,断言:
+  - 不出现 from playwright.async_api ...
+  - async def 函数体内不引用任何 playwright 符号
+  - playwright.sync_api 导入仅限白名单
+"""
+from __future__ import annotations
+
+import ast
+from pathlib import Path
+
+import pytest
+
+from autoteam._playwright_guard import (
+    ALLOWED_SYNC_NAMES,
+    EXEMPTION_MARKER,
+    FORBIDDEN_MODULES,
+)
+
+SRC_ROOT = Path(__file__).resolve().parents[2] / "src" / "autoteam"
+PLAYWRIGHT_NAMESPACE = ALLOWED_SYNC_NAMES | {"async_playwright"}
+
+
+def _is_exempt(path: Path) -> bool:
+    """文件首 5 行内出现 EXEMPTION_MARKER 即视为豁免。"""
+    try:
+        head = "\n".join(path.read_text(encoding="utf-8").splitlines()[:5])
+    except OSError:
+        return False
+    return EXEMPTION_MARKER in head
+
+
+def _iter_py_files():
+    for path in SRC_ROOT.rglob("*.py"):
+        if not _is_exempt(path):
+            yield path
+
+
+def _parse(path: Path) -> ast.AST:
+    return ast.parse(path.read_text(encoding="utf-8"), filename=str(path))
+
+
+def test_no_forbidden_module_import():
+    """A1+A2: 禁止 from playwright.async_api / import playwright.async_api"""
+    bad: list[str] = []
+    for path in _iter_py_files():
+        tree = _parse(path)
+        for node in ast.walk(tree):
+            if isinstance(node, ast.ImportFrom) and node.module in FORBIDDEN_MODULES:
+                bad.append(f"{path}:{node.lineno} from {node.module}")
+            elif isinstance(node, ast.Import):
+                for alias in node.names:
+                    if alias.name in FORBIDDEN_MODULES:
+                        bad.append(f"{path}:{node.lineno} import {alias.name}")
+    assert not bad, "禁止使用 playwright.async_api:\n" + "\n".join(bad)
+
+
+def test_no_playwright_in_async_def():
+    """A3: async def 函数体内不允许 playwright 符号"""
+    bad: list[str] = []
+    for path in _iter_py_files():
+        tree = _parse(path)
+        for fn in ast.walk(tree):
+            if not isinstance(fn, ast.AsyncFunctionDef):
+                continue
+            for child in ast.walk(fn):
+                name = getattr(child, "id", None) or getattr(child, "attr", None)
+                if name in PLAYWRIGHT_NAMESPACE:
+                    bad.append(
+                        f"{path}:{getattr(child, 'lineno', fn.lineno)} "
+                        f"async def {fn.name} 内引用了 {name}"
+                    )
+    assert not bad, "async def 函数体内禁止 playwright:\n" + "\n".join(bad)
+
+
+def test_sync_import_whitelist():
+    """A4: playwright.sync_api 导入仅限 ALLOWED_SYNC_NAMES"""
+    bad: list[str] = []
+    for path in _iter_py_files():
+        tree = _parse(path)
+        for node in ast.walk(tree):
+            if isinstance(node, ast.ImportFrom) and node.module == "playwright.sync_api":
+                for alias in node.names:
+                    if alias.name not in ALLOWED_SYNC_NAMES:
+                        bad.append(f"{path}:{node.lineno} 非白名单符号 {alias.name}")
+    assert not bad, "sync_api 导入不在白名单:\n" + "\n".join(bad)
+
+
+def test_exemption_list_intentional():
+    """SPEC-4 §5: 豁免文件需登记理由,避免静默扩散"""
+    exempt = [p for p in SRC_ROOT.rglob("*.py") if _is_exempt(p)]
+    # 当前期望 0 个文件豁免;若未来需要 opt-out,在此处 explicit allow
+    expected_exempt: set[str] = set()
+    actual = {p.relative_to(SRC_ROOT).as_posix() for p in exempt}
+    unexpected = actual - expected_exempt
+    assert not unexpected, (
+        f"未登记的豁免文件:{unexpected}。"
+        f"如需新增,先更新 SPEC-4 §5 + 本测试 expected_exempt 集合"
+    )
+```
+
+### 4.2 runtime guard 单测
+
+```python
+# tests/unit/test_playwright_guard.py
+"""SPEC-4 §3:assert_sync_context 行为验证"""
+import asyncio
+import threading
+
+import pytest
+
+from autoteam._playwright_guard import assert_sync_context
+
+
+def test_passes_in_plain_thread():
+    """普通线程无 loop,guard 必须放行(不抛异常)"""
+    holder: dict = {}
+
+    def worker():
+        try:
+            assert_sync_context()
+            holder["ok"] = True
+        except Exception as e:
+            holder["err"] = e
+
+    t = threading.Thread(target=worker, name="test-plain")
+    t.start()
+    t.join(timeout=2.0)
+    assert holder.get("ok") is True
+    assert "err" not in holder
+
+
+@pytest.mark.asyncio
+async def test_blocks_in_asyncio_loop():
+    """asyncio loop 内调用必须抛 RuntimeError"""
+    with pytest.raises(RuntimeError, match=r"\[PlaywrightGuard\].*asyncio loop"):
+        assert_sync_context()
+
+
+def test_message_contains_thread_and_loop_id():
+    """异常消息应携带 thread 名 + loop id 便于诊断"""
+    async def runner():
+        try:
+            assert_sync_context()
+        except RuntimeError as e:
+            return str(e)
+        return None
+
+    msg = asyncio.run(runner())
+    assert msg is not None
+    assert "thread=" in msg
+    assert "loop_id=0x" in msg
+```
+
+---
+
+## 5. per-file 豁免机制
+
+### 5.1 豁免格式(注释式 marker)
+
+需要使用 `playwright.async_api` 的文件,**必须**在文件首 5 行内出现:
+
+```python
+# autoteam: allow-async-playwright reason="<具体原因,如 PR#NN 引入并发抓取>"
+```
+
+`reason="..."` 字段是**强制的**,无 reason 视为未豁免(`_is_exempt` 仅检测 marker 字面量,但 review 时人工把关 reason 完整性)。
+
+### 5.2 豁免登记表
+
+`tests/static/test_playwright_hygiene.py::test_exemption_list_intentional` 维护 `expected_exempt: set[str]`,新增豁免**必须同步更新**该集合,否则测试 fail。
+
+当前期望值:`expected_exempt = set()` — **0** 个文件豁免。
+
+### 5.3 豁免审批流程
+
+1. 提案 PR 在该文件首加 marker
+2. 在 `expected_exempt` 集合追加文件相对路径(`as_posix()` 形式)
+3. PR 描述里链接到本 SPEC §5,说明 reason 与 review 决议
+4. 至少 2 名维护者批准,理由不可"开发方便"或"暂时绕过"
+
+---
+
+## 6. CI 集成(pytest collect 配置)
+
+### 6.1 `pyproject.toml`(若使用)
+
+```toml
+[tool.pytest.ini_options]
+testpaths = [
+    "tests/static",   # SPEC-4 静态守卫
+    "tests/unit",     # SPEC-4 runtime guard + 项目既有单测
+    "tests/integration",
+]
+addopts = "-ra -q --strict-markers"
+asyncio_mode = "auto"  # 启用 pytest-asyncio,服务 §4.2
+markers = [
+    "static: SPEC-4 AST 守卫,不可 deselect",
+]
+```
+
+### 6.2 `pytest.ini`(若使用,二选一)
+
+```ini
+[pytest]
+testpaths = tests/static tests/unit tests/integration
+addopts = -ra -q --strict-markers
+asyncio_mode = auto
+```
+
+### 6.3 GitHub Actions / 本地预提交
+
+```yaml
+# .github/workflows/test.yml(片段)
+- name: Static Playwright hygiene
+  run: pytest tests/static -q
+- name: Unit (incl. playwright guard)
+  run: pytest tests/unit -q
+```
+
+CI 必须**单独**跑 `tests/static`,即便 unit 失败也要拿到静态结果(便于诊断)。
+
+---
+
+## 7. 反例验证(测试守卫真起作用)
+
+`tests/static/test_playwright_hygiene_negative.py` — 以**临时文件**方式构造违例,验证 3 个测试函数确实 fail。该文件**不进 CI**,作为 SPEC-4 实施期的一次性手测。
+
+```python
+# tests/static/test_playwright_hygiene_negative.py
+"""手测脚本:验证 SPEC-4 §4 的守卫能正确报错。
+运行方式: pytest tests/static/test_playwright_hygiene_negative.py -q
+默认 skip,需 SPEC4_NEGATIVE=1 环境变量启用。
+"""
+from __future__ import annotations
+
+import os
+import textwrap
+from pathlib import Path
+
+import pytest
+
+SKIP_REASON = "set SPEC4_NEGATIVE=1 to run negative samples"
+ENABLED = os.getenv("SPEC4_NEGATIVE") == "1"
+
+
+@pytest.mark.skipif(not ENABLED, reason=SKIP_REASON)
+def test_async_def_with_sync_playwright_should_fail(tmp_path: Path, monkeypatch):
+    """注入一段 async def + sync_playwright 的违规代码,期望主测试 fail"""
+    bad_module = tmp_path / "bad.py"
+    bad_module.write_text(textwrap.dedent("""\
+        from playwright.sync_api import sync_playwright
+
+        async def evil_handler():
+            # 这里把 sync_playwright 拖进了协程,正是我们要拦的反模式
+            with sync_playwright() as p:
+                p.chromium.launch()
+    """), encoding="utf-8")
+    monkeypatch.setenv("SPEC4_SRC_OVERRIDE", str(tmp_path))
+    # 用例期望:在主测试套(切换 SRC_ROOT 至 tmp_path 后)运行
+    # test_no_playwright_in_async_def 应抛 AssertionError
+    # 实施时:由 implementor 通过将 SRC_ROOT 改为 env-driven 完成此切换
+
+
+@pytest.mark.skipif(not ENABLED, reason=SKIP_REASON)
+def test_async_api_import_should_fail(tmp_path: Path):
+    bad = tmp_path / "evil.py"
+    bad.write_text(
+        "from playwright.async_api import async_playwright\n",
+        encoding="utf-8",
+    )
+    # 期望:test_no_forbidden_module_import 在 SRC_ROOT=tmp_path 时 fail
+```
+
+> **注**:为保持主测文件无副作用,反例验证通过 `SPEC4_NEGATIVE=1` 与 `SPEC4_SRC_OVERRIDE` 双 env 触发;implementor 落地时需同步在 `_iter_py_files` / `SRC_ROOT` 加上 env 读取逻辑(`os.getenv("SPEC4_SRC_OVERRIDE", str(default))`),**不影响默认 CI 路径**。
+
+---
+
+## 8. 实施顺序(implementor 工序)
+
+| Step | 操作 | 验证 |
+|---|---|---|
+| 1 | 新建 `src/autoteam/_playwright_guard.py`(§2 + §3.1) | `python -c "from autoteam._playwright_guard import assert_sync_context"` 无报错 |
+| 2 | 在 `api.py:_PlaywrightExecutor` 双入口插入 `assert_sync_context()`(§3.2) | 既有 invite/register 集成测试全绿 |
+| 3 | 上提 `manager.py:1491/1969` 函数内 import 至模块顶层 | `python -c "import autoteam.manager"` 无循环 import |
+| 4 | 新建 `tests/static/__init__.py` + `test_playwright_hygiene.py`(§4.1) | `pytest tests/static -q` 全绿(因为现状 0 违规) |
+| 5 | 新建 `tests/unit/test_playwright_guard.py`(§4.2) | `pytest tests/unit/test_playwright_guard.py -q` 全绿 |
+| 6 | 更新 `pyproject.toml` / `pytest.ini`(§6) | `pytest --collect-only` 包含上述测试 |
+| 7 | 跑全套 `pytest -q` | 0 fail,0 error |
+| 8 | 反例手测(§7,可选) | 注入违规后 §4.1 三测必 fail |
+
+**任一 step 失败必须停止,不允许跳过到下一步。**
+
+---
+
+## 9. 验收清单
+
+- [ ] `_playwright_guard.py` 新增,`ALLOWED_SYNC_NAMES` 包含恰好 9 个符号
+- [ ] `api.py` 在 `run_with_timeout` 入口调用 `assert_sync_context()`
+- [ ] `api.py` 在 `_worker` 入口调用 `assert_sync_context()`
+- [ ] `manager.py` grep `from playwright` 仅命中模块顶层 1 处(或保留豁免并登记理由)
+- [ ] `tests/static/test_playwright_hygiene.py` 4 个测试全绿
+- [ ] `tests/unit/test_playwright_guard.py` 3 个测试全绿
+- [ ] `pyproject.toml` / `pytest.ini` `testpaths` 包含 `tests/static`
+- [ ] 既有 invite / register / sync 集成测试 0 回归
+- [ ] PR 描述链接 PRD-4 + SPEC-4,勾选"未引入 async playwright"
+
+---
+
+**附:与 PRD-4 §条款 → SPEC-4 §条款映射**
+
+| PRD §  | SPEC § | 实施粒度 |
+|---|---|---|
+| §5.1 import 白名单 | §2 + §4.1 | 9 个符号常量 + AST 测试 |
+| §5.2 runtime guard | §3 | 双入口 patch + 异常消息规范 |
+| §5.3 AST 静态守卫 | §4.1 | 3 个测试 + 1 个豁免登记 |
+| §5.4 CI 集成 | §6 | testpaths + asyncio_mode |
+| §7.3 AST 示例 | §4.1 | 已上升为 production-ready |
+| §12 R1 opt-out | §5 | marker + expected_exempt |
+| §13 Q1(单点 vs 双入口) | §3.2 | 决议:双入口(主线程 + worker) |

prompts/0426/synthesis.md

@@ -0,0 +1,109 @@
+# 调研综合分析(Synthesis)
+
+> 时间:2026-04-26
+> 输入:`prompts/0426/research/issue-{1..6}-*.md` 共 6 份调研报告
+> 输出:跨 issue 共因识别、PRD 切分方案、依赖图、优先级
+
+---
+
+## 1. 跨 Issue 共因(实施时必须统一)
+
+| 共因点 | 涉及 Issue | 文件:行号 | 一句话 |
+|---|---|---|---|
+| **A. plan_type 白名单** | #2 + #6 | `codex_auth.py:111`,`manager.py:1463/2489`,`manual_account.py:233` | `self_serve_business_usage_based` 等新值无识别,通通走 codex 但实际无配额 |
+| **B. wham/usage 识别 quota=0** | #2 + #6 | `codex_auth.py:1582-1700` | `used_percent=0 + total=0` 当 ok 处理,UI 显示"100% 剩余"实际 429 |
+| **C. login_codex_via_browser 接 add-phone 探针** | #4 + #6 | `codex_auth.py:250-932` | invite.py 的 `detect_phone_verification` 没复用,撞 add-phone 静默 30s 超时 |
+| **D. _run_post_register_oauth 加 quota probe** | #6 | `manager.py:1463-1486` | 注册收尾不验配额,假入池 |
+| **E. sync_account_states 区分"被踢" vs "待机"** | #6 | `manager.py:526-541` | 都被无脑标 STANDBY,被踢号反复死循环 |
+
+**实施纪律**:A/B/C/D/E 必须由同一 PR 处理,否则会出现"修了 D 没修 B,quota probe 仍然不识别 quota=0"这类半截修复。
+
+---
+
+## 2. PRD 切分方案(4 + 1)
+
+### PRD-1 — Mail Provider 全量化(Issue#1 独立)
+- **范围**:SetupConfig 扩字段、cf_temp_email 嗅探收紧、`/api/mail-provider/probe` 新端点、前端归属验证 4 步流、6 个文档改写
+- **不依赖其他 PRD**,可单独实施
+- **风险**:UI 变动大、跨域代理设计需小心
+
+### PRD-2 — 账号生命周期与配额(Issue#2 + #4 + #6 合并)
+- **范围**:plan_type 白名单 + wham/usage no_quota 分类 + add-phone 探针 + _run_post_register_oauth probe + sync_account_states 区分被踢 + reinvite 兜底
+- **PREFERRED_SEAT_TYPE 配置**(独属 #2)+ **personal 删除解耦**(独属 #2)
+- **关键**:5 个共因点必须同 PR,否则半截
+- **风险**:扩散到 manager/codex_auth/account_ops/api,需充分回归测试
+
+### PRD-3 — Docker 镜像守卫(Issue#3 收尾)
+- **范围**:entrypoint self-check + lint 守卫 + 镜像 git-sha 标签 + docs/docker.md 增加 rebuild SOP
+- **代码层 cf2f7d3 已修**,这是防回归 + 用户操作指引
+- **风险**:低
+
+### PRD-4 — Playwright 一致性(Issue#5 待定)
+- **状态**:研究反转 — 全项目 0 处实际误用
+- **行动**:需向用户索取具体报错堆栈或样本;在拿到样本前,**仅落地"可选优化"**(顶层 import 统一 + asyncio 运行时 guard + AST 静态守卫单测)
+- **风险**:用户可能描述的是其他问题,不要凭空重构
+
+### 增量 — UI 删除 toast / OAuth 模式选择(可选,后置)
+- 来自 #2 + #6 的 D.2 可选项,P1
+- 单独 PR,不阻塞主线
+
+---
+
+## 3. 实施依赖图
+
+```
+PRD-1 (Mail Provider) ────────────┐
+                                  ├─→ 集成测试(各自独立可并行)
+PRD-2 (Lifecycle) ────────────────┤
+                                  │
+PRD-3 (Docker Guard) ─────────────┤
+                                  │
+PRD-4 (Playwright) [aw user] ─────┘
+```
+
+PRD-1 / PRD-2 / PRD-3 三个互不依赖,可并行实施。
+PRD-4 阻塞在用户答复。
+
+---
+
+## 4. 优先级
+
+| Rank | PRD | 价值 | 风险 |
+|---|---|---|---|
+| **P0** | PRD-2 (生命周期) | 高 — 解决 3 个 issue 的核心 bug,直接改善可用率 | 高 — 跨多文件 |
+| **P0** | PRD-1 (Mail Provider) | 高 — 401 阻塞用户 setup,且补齐缺失功能 | 中 — UI 改动 |
+| **P1** | PRD-3 (Docker) | 中 — 防回归 + 用户操作友好 | 低 |
+| **P2** | PRD-4 (Playwright) | 不确定 — 待用户澄清 | 低 |
+
+---
+
+## 5. 共享 spec(横切关注点)
+
+以下抽象应在 spec 阶段抽出独立文档,供多个 PRD 引用:
+
+- `spec/shared/plan-type-whitelist.md`:`SUPPORTED_PLAN_TYPES` 常量、判定函数、所有调用点
+- `spec/shared/quota-classification.md`:wham/usage 4+1 分类(ok/exhausted/no_quota/auth_error/network_error)、no_quota 触发条件、上游处理
+- `spec/shared/add-phone-detection.md`:`detect_phone_verification` 复用契约、OAuth 模式定制探针、错误归类
+- `spec/shared/account-state-machine.md`:7 状态(active/exhausted/standby/pending/personal/auth_invalid/orphan)的转换规则、被踢识别规则
+
+---
+
+## 6. 测试矩阵
+
+| 测试类型 | 范围 | 工具 |
+|---|---|---|
+| 单元测试 | 共因函数 (plan_type/quota/add-phone) | pytest |
+| 集成测试 | _run_post_register_oauth 全链路 | pytest + httpx mock |
+| 回归测试 | invite/reinvite/sync_account_states 现有路径 | 既有测试套件 |
+| E2E | mail provider 切换 + 归属验证 | playwright |
+| 手测 | docker rebuild 流程、UI 删除 toast、OAuth 模式选择 | 用户参与 |
+
+---
+
+## 7. 已知未决问题(送 PRD 阶段决议)
+
+1. **wham/usage schema** — `limit/total` 字段是否真存在?需要从用户 `auths/codex-*.json` 实测样本
+2. **`self_serve_business_usage_based` 字面量** — 用户报告的字面值需 grep 用户实际 bundle 确认
+3. **PATCH 升级失败率** — 改默认席位策略前应有数据
+4. **add-phone 探针误报** — OAuth 域(auth.openai.com)的 detect 规则可能需要定制
+5. **PRD-4 用户澄清** — 需要给出具体 async/sync 报错样本

pyproject.toml

@@ -31,4 +31,33 @@ dev = [
 
 [tool.pytest.ini_options]
 addopts = "-ra"
-testpaths = ["tests"]
+# tests/static 是 SPEC-4 AST 守卫所在地,显式列入避免被未来 collect-only 误排除
+testpaths = ["tests", "tests/static", "tests/unit", "tests/integration"]
+
+# ---------------------------------------------------------------------------
+# Ruff lint (SPEC-3 §6) - 仅启 F401/F811/F821 三条零误报规则
+# ---------------------------------------------------------------------------
+[tool.ruff]
+target-version = "py310"
+line-length = 120
+src = ["src", "tests"]
+
+[tool.ruff.lint]
+# F401: imported but unused (死 import)
+# F811: redefinition of unused (重复定义)
+# F821: undefined name (核心 — 抓 typo 类 ImportError)
+select = ["F401", "F811", "F821"]
+
+# 测试 / 文档 / 脚本豁免(可能含 docstring 示例 / 故意未定义符号)
+exclude = [
+    "tests/",
+    "docs/",
+    "scripts/",
+    ".venv/",
+    "build/",
+    "dist/",
+]
+
+[tool.ruff.lint.per-file-ignores]
+# __init__.py 允许 re-export
+"__init__.py" = ["F401"]

src/autoteam/_playwright_guard.py

@@ -0,0 +1,61 @@
+"""Playwright 一致性硬化(SPEC-4)。
+
+本模块提供白名单常量与运行时守卫,禁止 sync_playwright 进入 asyncio loop。
+所有静态测试(tests/static/test_playwright_hygiene.py)与运行时 guard
+(api.py:_PlaywrightExecutor)共享本文件作为单一信源(SSOT)。
+"""
+
+from __future__ import annotations
+
+import asyncio
+import logging
+import threading
+
+logger = logging.getLogger(__name__)
+
+
+# 9 个允许从 playwright.sync_api 导入的符号
+ALLOWED_SYNC_NAMES: frozenset[str] = frozenset({
+    "sync_playwright",   # 上下文管理器
+    "Playwright",        # 顶层句柄类型
+    "Browser",           # 浏览器实例类型
+    "BrowserContext",    # 浏览器上下文
+    "BrowserType",       # chromium/firefox/webkit 类型
+    "Page",              # 页面句柄
+    "Locator",           # 定位器
+    "Error",             # Playwright 通用异常
+    "TimeoutError",      # Playwright 超时异常
+})
+
+# 1 个 typeshed 类型(仅在 if TYPE_CHECKING 块内允许)
+TYPE_CHECKING_ONLY: frozenset[str] = frozenset({
+    "ElementHandle",
+})
+
+# 任何形式的 from <X> import / import <X> 禁止模块
+FORBIDDEN_MODULES: frozenset[str] = frozenset({
+    "playwright.async_api",
+})
+
+# per-file 豁免 marker,文件首 5 行内出现即整文件跳过守卫
+EXEMPTION_MARKER: str = "autoteam: allow-async-playwright"
+
+
+def assert_sync_context() -> None:
+    """断言当前线程不在 asyncio loop 中。
+
+    仅用于 sync_playwright 调用前的前置检查。若检测到 loop,立即抛
+    RuntimeError(消息含 thread/loop_id 标识,便于诊断)。
+
+    期望路径: 普通线程 / 专用 worker 线程 → asyncio.get_running_loop()
+    抛 RuntimeError → 无 loop → 放行。
+    """
+    try:
+        loop = asyncio.get_running_loop()
+    except RuntimeError:
+        return
+    raise RuntimeError(
+        f"[PlaywrightGuard] thread={threading.current_thread().name!r} "
+        f"loop_id=0x{id(loop):x} — sync_playwright 不允许在 asyncio loop 中调用。"
+        f"详见 PRD-4 §12 R1 opt-out 流程。"
+    )

src/autoteam/api.py

@@ -24,11 +24,37 @@ app = FastAPI(
     version="0.1.0",
 )
 
+
+# ---------------------------------------------------------------------------
+# 版本端点 (SPEC-3 §5) - 不鉴权,纯只读
+# ---------------------------------------------------------------------------
+
+
+class VersionResponse(BaseModel):
+    """镜像版本指纹响应 - 来自 Dockerfile build args。"""
+
+    git_sha: str
+    build_time: str
+
+
+@app.get(
+    "/api/version",
+    response_model=VersionResponse,
+    summary="返回镜像构建期注入的 git-sha 与时间戳",
+    tags=["meta"],
+)
+def api_version() -> VersionResponse:
+    return VersionResponse(
+        git_sha=os.getenv("AUTOTEAM_GIT_SHA", "unknown"),
+        build_time=os.getenv("AUTOTEAM_BUILD_TIME", "unknown"),
+    )
+
+
 # ---------------------------------------------------------------------------
 # API Key 鉴权中间件
 # ---------------------------------------------------------------------------
 
-_AUTH_SKIP_PATHS = {"/api/auth/check", "/api/setup/status", "/api/setup/save"}
+_AUTH_SKIP_PATHS = {"/api/auth/check", "/api/setup/status", "/api/setup/save", "/api/version"}
 
 
 @app.middleware("http")
@@ -169,6 +195,8 @@ MAX_TASK_HISTORY = 50
 
 import queue as _queue
 
+from autoteam._playwright_guard import assert_sync_context
+
 
 class _PlaywrightExecutor:
     """将 Playwright 操作派发到专用线程执行，避免跨线程错误"""
@@ -178,6 +206,8 @@ class _PlaywrightExecutor:
         self._thread: threading.Thread | None = None
 
     def _worker(self):
+        # SPEC-4 §3.2: worker 线程入口必须在普通线程,不允许 asyncio loop
+        assert_sync_context()
         while True:
             item = self._queue.get()
             if item is None:
@@ -207,6 +237,8 @@ class _PlaywrightExecutor:
         后续通过 _pw_executor 提交的调用会在队列里等它自然完成。调用方需要自己
         确保不会越过 _playwright_lock 边界并发触发这种情况。
         """
+        # SPEC-4 §3.2: 主线程前置检查,拦下 asyncio loop 误入
+        assert_sync_context()
         self.ensure_started()
         result_event = threading.Event()
         result_holder: dict = {}

src/autoteam/manager.py

@@ -26,6 +26,8 @@ import sys
 import time
 from pathlib import Path
 
+from playwright.sync_api import sync_playwright
+
 from autoteam.account_ops import delete_managed_account, fetch_team_state
 from autoteam.accounts import (
     STATUS_ACTIVE,
@@ -1488,8 +1490,6 @@ def _run_post_register_oauth(email, password, mail_client, leave_workspace=False
 
 def _complete_registration(email, password, invite_link, mail_client, *, leave_workspace=False, out_outcome=None):
     """完成注册 + Codex 登录（从已有邀请链接继续）。out_outcome 透传给 _run_post_register_oauth。"""
-    from playwright.sync_api import sync_playwright
-
     from autoteam.invite import register_with_invite
 
     logger.info("[注册] 开始注册 %s...", email)
@@ -1966,8 +1966,6 @@ def _register_direct_once(mail_client, email, password, cloudmail_account_id=Non
     在邮箱/密码/验证码/about-you 四个提交节点调用 assert_not_blocked，
     一旦命中 add-phone / duplicate 就抛 RegisterBlocked，由 create_account_direct 分流处理。
     """
-    from playwright.sync_api import sync_playwright
-
     from autoteam.invite import RegisterBlocked, assert_not_blocked
 
     logger.info("[直接注册] %s", email)

tests/integration/test_docker_guard.py

@@ -0,0 +1,201 @@
+"""SPEC-3 Docker 镜像守卫的非容器化集成测试。
+
+覆盖以下 SPEC §9 场景中可在宿主机执行的部分:
+- 9.1 步骤 3:`/api/version` 端点契约(JSON 字段、降级语义、免鉴权)
+- 9.3 步骤 1-2:ruff F821 拦截 typo
+- self-check 白名单 import 在宿主机环境也能跑通(等同于容器启动期检查)
+
+宿主机不可达的部分(docker compose up / crash-loop / OCI label)走 shell SOP,
+见 `docs/docker.md` 的"代码更新后的 rebuild SOP"章节。
+"""
+
+from __future__ import annotations
+
+import os
+import shutil
+import subprocess
+import sys
+from pathlib import Path
+
+import pytest
+from fastapi.testclient import TestClient
+
+REPO_ROOT = Path(__file__).resolve().parents[2]
+
+
+# ---------------------------------------------------------------------------
+# §9.1 /api/version 端点契约
+# ---------------------------------------------------------------------------
+
+
+@pytest.fixture
+def client() -> TestClient:
+    from autoteam.api import app
+
+    return TestClient(app)
+
+
+def test_api_version_returns_two_fields(client: TestClient, monkeypatch: pytest.MonkeyPatch) -> None:
+    """SPEC AC3: /api/version 必须返回 git_sha + build_time 双字段。"""
+
+    monkeypatch.setenv("AUTOTEAM_GIT_SHA", "cf2f7d3")
+    monkeypatch.setenv("AUTOTEAM_BUILD_TIME", "2026-04-26T03:00:00Z")
+    resp = client.get("/api/version")
+    assert resp.status_code == 200
+    body = resp.json()
+    assert set(body.keys()) == {"git_sha", "build_time"}
+    assert body["git_sha"] == "cf2f7d3"
+    assert body["build_time"] == "2026-04-26T03:00:00Z"
+
+
+def test_api_version_falls_back_to_unknown(client: TestClient, monkeypatch: pytest.MonkeyPatch) -> None:
+    """SPEC AC7: 不传 build-arg(env 未设)应降级返回 unknown,不报 500。"""
+
+    monkeypatch.delenv("AUTOTEAM_GIT_SHA", raising=False)
+    monkeypatch.delenv("AUTOTEAM_BUILD_TIME", raising=False)
+    resp = client.get("/api/version")
+    assert resp.status_code == 200
+    body = resp.json()
+    assert body == {"git_sha": "unknown", "build_time": "unknown"}
+
+
+def test_api_version_is_unauthenticated(client: TestClient, monkeypatch: pytest.MonkeyPatch) -> None:
+    """SPEC AC9: 即便配了 API_KEY,/api/version 也免鉴权直接返回 200。"""
+
+    # 模拟"已配 API_KEY 但请求不带 Bearer"
+    import autoteam.api as api_module
+
+    monkeypatch.setattr(api_module, "API_KEY", "fake-secret-do-not-leak")
+    resp = client.get("/api/version")  # 故意不带 Authorization header
+    assert resp.status_code == 200, "version 端点应在 _AUTH_SKIP_PATHS 白名单中"
+
+
+def test_api_version_in_auth_skip_paths() -> None:
+    """额外契约:_AUTH_SKIP_PATHS 必须显式包含 /api/version。"""
+
+    from autoteam.api import _AUTH_SKIP_PATHS
+
+    assert "/api/version" in _AUTH_SKIP_PATHS
+
+
+# ---------------------------------------------------------------------------
+# §9.3 lint 守卫:ruff F821 拦截 typo(同 entrypoint self-check 等价语义)
+# ---------------------------------------------------------------------------
+
+
+@pytest.mark.skipif(
+    shutil.which("ruff") is None,
+    reason="本机 PATH 中未找到 ruff 二进制,跳过 lint 集成验证(CI 应直接装 ruff)",
+)
+def test_ruff_catches_undefined_import(tmp_path: Path) -> None:
+    """SPEC AC5: 制造 typo 的 import,ruff F821 必须返回非零 exit code。
+
+    用 PATH 上已存在的 ruff 直接跑,避开 `uv run` 在 Windows 上可能的虚拟环境锁。
+    CI 与 pre-commit hook 走 ruff-pre-commit,语义等价。
+    """
+
+    canary = tmp_path / "canary.py"
+    canary.write_text(
+        "from autoteam.accounts import list_accounts  # typo: 实际应为 load_accounts\n",
+        encoding="utf-8",
+    )
+
+    cmd = ["ruff", "check", "--select", "F401,F811,F821", str(canary)]
+    proc = subprocess.run(cmd, capture_output=True, text=True, cwd=REPO_ROOT)
+    assert proc.returncode != 0, (
+        f"ruff 应拦截 typo,但返回 exit=0。stdout={proc.stdout!r}, stderr={proc.stderr!r}"
+    )
+    # F401(unused) 或 F821(undefined) 任一命中即可 — typo 引入的 import 通常两者都中
+    combined = proc.stdout + proc.stderr
+    assert ("F401" in combined) or ("F821" in combined), (
+        f"输出中缺少 F401/F821 标记: {combined!r}"
+    )
+
+
+# ---------------------------------------------------------------------------
+# self-check 白名单契约:entrypoint 列出的 11 个符号必须全部 importable
+# ---------------------------------------------------------------------------
+
+
+def test_self_check_whitelist_imports() -> None:
+    """SPEC AC1: docker-entrypoint.sh self-check 列出的所有符号必须可导入。
+
+    若 PR 改名/删除这些符号,本测试先红 → entrypoint 才不会在容器启动期红。
+    """
+
+    from autoteam.api import app  # noqa: F401
+    from autoteam.accounts import (  # noqa: F401
+        STATUS_ACTIVE,
+        STATUS_AUTH_INVALID,
+        STATUS_EXHAUSTED,
+        STATUS_ORPHAN,
+        STATUS_PENDING,
+        STATUS_PERSONAL,
+        STATUS_STANDBY,
+        load_accounts,
+        save_accounts,
+    )
+    from autoteam.manager import sync_account_states  # noqa: F401
+
+    # 简单的契约校验 — 函数应可调用、状态常量应是字符串
+    assert callable(load_accounts)
+    assert callable(save_accounts)
+    assert callable(sync_account_states)
+    for const in (
+        STATUS_ACTIVE,
+        STATUS_EXHAUSTED,
+        STATUS_STANDBY,
+        STATUS_PENDING,
+        STATUS_PERSONAL,
+        STATUS_AUTH_INVALID,
+        STATUS_ORPHAN,
+    ):
+        assert isinstance(const, str) and const, f"状态常量必须是非空字符串: {const!r}"
+
+
+# ---------------------------------------------------------------------------
+# Dockerfile / compose / entrypoint 静态契约(避免 SPEC §1-§4 被悄悄回退)
+# ---------------------------------------------------------------------------
+
+
+def test_dockerfile_declares_git_sha_arg() -> None:
+    """SPEC AC4: Dockerfile 必须声明 ARG GIT_SHA + ENV AUTOTEAM_GIT_SHA。"""
+
+    dockerfile = (REPO_ROOT / "Dockerfile").read_text(encoding="utf-8")
+    assert "ARG GIT_SHA" in dockerfile
+    assert "ARG BUILD_TIME" in dockerfile
+    assert "ENV AUTOTEAM_GIT_SHA" in dockerfile
+    assert "ENV AUTOTEAM_BUILD_TIME" in dockerfile
+    assert "org.opencontainers.image.revision" in dockerfile
+
+
+def test_compose_passes_build_args() -> None:
+    """compose 必须把 GIT_SHA / BUILD_TIME 作为 build-arg 透传(降级 unknown)。"""
+
+    compose = (REPO_ROOT / "docker-compose.yml").read_text(encoding="utf-8")
+    assert "GIT_SHA: ${GIT_SHA:-unknown}" in compose
+    assert "BUILD_TIME: ${BUILD_TIME:-unknown}" in compose
+
+
+def test_entrypoint_contains_self_check() -> None:
+    """entrypoint 必须包含 self-check + crash-loop 兜底。"""
+
+    entrypoint = (REPO_ROOT / "docker-entrypoint.sh").read_text(encoding="utf-8")
+    assert "[self-check]" in entrypoint
+    assert "from autoteam.api import app" in entrypoint
+    assert "from autoteam.accounts import" in entrypoint
+    assert "exit 1" in entrypoint, "self-check 失败必须 exit 1 触发 crash-loop"
+
+
+def test_pyproject_has_ruff_config() -> None:
+    """pyproject.toml 必须配 [tool.ruff.lint] 三条规则。"""
+
+    pyproject = (REPO_ROOT / "pyproject.toml").read_text(encoding="utf-8")
+    assert "[tool.ruff.lint]" in pyproject
+    assert "F401" in pyproject
+    assert "F811" in pyproject
+    assert "F821" in pyproject
+
+
+if __name__ == "__main__":
+    sys.exit(pytest.main([__file__, "-v"]))

tests/static/test_playwright_hygiene.py

@@ -0,0 +1,99 @@
+"""SPEC-4 §4: Playwright import + async/sync 分离静态守卫。
+
+通过 AST 扫描 src/autoteam/**/*.py,断言:
+  - 不出现 from playwright.async_api ...
+  - async def 函数体内不引用任何 playwright 符号
+  - playwright.sync_api 导入仅限白名单
+  - 已豁免的文件必须显式登记在 expected_exempt 集合
+"""
+
+from __future__ import annotations
+
+import ast
+from pathlib import Path
+
+from autoteam._playwright_guard import (
+    ALLOWED_SYNC_NAMES,
+    EXEMPTION_MARKER,
+    FORBIDDEN_MODULES,
+)
+
+SRC_ROOT = Path(__file__).resolve().parents[2] / "src" / "autoteam"
+PLAYWRIGHT_NAMESPACE = ALLOWED_SYNC_NAMES | {"async_playwright"}
+
+
+def _is_exempt(path: Path) -> bool:
+    """文件首 5 行内出现 EXEMPTION_MARKER 即视为豁免。"""
+    try:
+        head = "\n".join(path.read_text(encoding="utf-8").splitlines()[:5])
+    except OSError:
+        return False
+    return EXEMPTION_MARKER in head
+
+
+def _iter_py_files():
+    for path in SRC_ROOT.rglob("*.py"):
+        if not _is_exempt(path):
+            yield path
+
+
+def _parse(path: Path) -> ast.AST:
+    return ast.parse(path.read_text(encoding="utf-8"), filename=str(path))
+
+
+def test_no_forbidden_module_import():
+    """A1+A2: 禁止 from playwright.async_api / import playwright.async_api"""
+    bad: list[str] = []
+    for path in _iter_py_files():
+        tree = _parse(path)
+        for node in ast.walk(tree):
+            if isinstance(node, ast.ImportFrom) and node.module in FORBIDDEN_MODULES:
+                bad.append(f"{path}:{node.lineno} from {node.module}")
+            elif isinstance(node, ast.Import):
+                for alias in node.names:
+                    if alias.name in FORBIDDEN_MODULES:
+                        bad.append(f"{path}:{node.lineno} import {alias.name}")
+    assert not bad, "禁止使用 playwright.async_api:\n" + "\n".join(bad)
+
+
+def test_no_playwright_in_async_def():
+    """A3: async def 函数体内不允许 playwright 符号"""
+    bad: list[str] = []
+    for path in _iter_py_files():
+        tree = _parse(path)
+        for fn in ast.walk(tree):
+            if not isinstance(fn, ast.AsyncFunctionDef):
+                continue
+            for child in ast.walk(fn):
+                name = getattr(child, "id", None) or getattr(child, "attr", None)
+                if name in PLAYWRIGHT_NAMESPACE:
+                    bad.append(
+                        f"{path}:{getattr(child, 'lineno', fn.lineno)} "
+                        f"async def {fn.name} 内引用了 {name}"
+                    )
+    assert not bad, "async def 函数体内禁止 playwright:\n" + "\n".join(bad)
+
+
+def test_sync_import_whitelist():
+    """A4: playwright.sync_api 导入仅限 ALLOWED_SYNC_NAMES"""
+    bad: list[str] = []
+    for path in _iter_py_files():
+        tree = _parse(path)
+        for node in ast.walk(tree):
+            if isinstance(node, ast.ImportFrom) and node.module == "playwright.sync_api":
+                for alias in node.names:
+                    if alias.name not in ALLOWED_SYNC_NAMES:
+                        bad.append(f"{path}:{node.lineno} 非白名单符号 {alias.name}")
+    assert not bad, "sync_api 导入不在白名单:\n" + "\n".join(bad)
+
+
+def test_exemption_list_intentional():
+    """SPEC-4 §5: 豁免文件需登记理由,避免静默扩散"""
+    exempt = [p for p in SRC_ROOT.rglob("*.py") if _is_exempt(p)]
+    expected_exempt: set[str] = set()
+    actual = {p.relative_to(SRC_ROOT).as_posix() for p in exempt}
+    unexpected = actual - expected_exempt
+    assert not unexpected, (
+        f"未登记的豁免文件:{unexpected}。"
+        f"如需新增,先更新 SPEC-4 §5 + 本测试 expected_exempt 集合"
+    )

tests/static/test_playwright_hygiene_negative.py

@@ -0,0 +1,101 @@
+"""SPEC-4 §7: 反例验证 — 证明 hygiene 守卫真能拦下违规代码。
+
+通过把违规代码字符串直接 ast.parse 后跑相同的 AST 规则,断言它们被识别为
+违规。该测试不依赖 SRC_ROOT,默认进 CI 跑;它独立于主 hygiene 测试运行,
+因此不会污染主测试的 SRC_ROOT 路径。
+"""
+
+from __future__ import annotations
+
+import ast
+import textwrap
+
+from autoteam._playwright_guard import (
+    ALLOWED_SYNC_NAMES,
+    FORBIDDEN_MODULES,
+)
+
+PLAYWRIGHT_NAMESPACE = ALLOWED_SYNC_NAMES | {"async_playwright"}
+
+
+def _has_forbidden_import(tree: ast.AST) -> bool:
+    for node in ast.walk(tree):
+        if isinstance(node, ast.ImportFrom) and node.module in FORBIDDEN_MODULES:
+            return True
+        if isinstance(node, ast.Import):
+            for alias in node.names:
+                if alias.name in FORBIDDEN_MODULES:
+                    return True
+    return False
+
+
+def _has_playwright_in_async_def(tree: ast.AST) -> bool:
+    for fn in ast.walk(tree):
+        if not isinstance(fn, ast.AsyncFunctionDef):
+            continue
+        for child in ast.walk(fn):
+            name = getattr(child, "id", None) or getattr(child, "attr", None)
+            if name in PLAYWRIGHT_NAMESPACE:
+                return True
+    return False
+
+
+def _has_non_whitelist_sync_import(tree: ast.AST) -> bool:
+    for node in ast.walk(tree):
+        if isinstance(node, ast.ImportFrom) and node.module == "playwright.sync_api":
+            for alias in node.names:
+                if alias.name not in ALLOWED_SYNC_NAMES:
+                    return True
+    return False
+
+
+def test_forbidden_async_api_import_is_detected():
+    src = "from playwright.async_api import async_playwright\n"
+    tree = ast.parse(src)
+    assert _has_forbidden_import(tree), "async_api import 应当被守卫识别"
+
+
+def test_async_def_with_sync_playwright_is_detected():
+    src = textwrap.dedent("""\
+        from playwright.sync_api import sync_playwright
+
+        async def evil_handler():
+            with sync_playwright() as p:
+                p.chromium.launch()
+    """)
+    tree = ast.parse(src)
+    assert _has_playwright_in_async_def(tree), "async def 内 sync_playwright 应被识别"
+
+
+def test_async_def_with_page_attribute_is_detected():
+    src = textwrap.dedent("""\
+        async def evil_handler(browser):
+            page = await browser.new_page()
+            return Page  # noqa
+    """)
+    tree = ast.parse(src)
+    assert _has_playwright_in_async_def(tree), "async def 内引用 Page 应被识别"
+
+
+def test_non_whitelist_sync_import_is_detected():
+    src = "from playwright.sync_api import Request\n"
+    tree = ast.parse(src)
+    assert _has_non_whitelist_sync_import(tree), "白名单外符号应被识别"
+
+
+def test_clean_file_passes_all_checks():
+    """正向反例: 合法的 sync 用法不应被任一规则误伤"""
+    src = textwrap.dedent("""\
+        from playwright.sync_api import sync_playwright, Page, Browser
+
+        def login_flow():
+            with sync_playwright() as p:
+                browser: Browser = p.chromium.launch()
+                page: Page = browser.new_page()
+                page.goto("https://example.com")
+                browser.close()
+    """)
+    tree = ast.parse(src)
+    assert not _has_forbidden_import(tree)
+    assert not _has_playwright_in_async_def(tree)
+    assert not _has_non_whitelist_sync_import(tree)

tests/unit/test_playwright_guard.py

@@ -0,0 +1,59 @@
+"""SPEC-4 §3: assert_sync_context 行为验证。
+
+注: SPEC §4.2 原稿用 @pytest.mark.asyncio,但仓库未引入 pytest-asyncio。
+为避免新增依赖,asyncio loop 内的测试改用 asyncio.run() 直接驱动协程,
+行为等价,在 loop 内调用 assert_sync_context() 仍会触发 RuntimeError。
+"""
+
+from __future__ import annotations
+
+import asyncio
+import re
+import threading
+
+import pytest
+
+from autoteam._playwright_guard import assert_sync_context
+
+
+def test_passes_in_plain_thread():
+    """普通线程无 loop, guard 必须放行"""
+    holder: dict = {}
+
+    def worker():
+        try:
+            assert_sync_context()
+            holder["ok"] = True
+        except Exception as e:  # noqa: BLE001
+            holder["err"] = e
+
+    t = threading.Thread(target=worker, name="test-plain")
+    t.start()
+    t.join(timeout=2.0)
+    assert holder.get("ok") is True
+    assert "err" not in holder
+
+
+def test_blocks_in_asyncio_loop():
+    """asyncio loop 内调用必须抛 RuntimeError"""
+    async def runner():
+        assert_sync_context()
+
+    with pytest.raises(RuntimeError, match=r"\[PlaywrightGuard\].*asyncio loop"):
+        asyncio.run(runner())
+
+
+def test_message_contains_thread_and_loop_id():
+    """异常消息应携带 thread 名 + loop id 便于诊断"""
+    captured: dict = {}
+
+    async def runner():
+        try:
+            assert_sync_context()
+        except RuntimeError as e:
+            captured["msg"] = str(e)
+
+    asyncio.run(runner())
+    msg = captured.get("msg", "")
+    assert "thread=" in msg
+    assert re.search(r"loop_id=0x[0-9a-f]+", msg)