Add Gmail+Email Worker hybrid mail path and private runtime config

Prefer Cloudflare Worker KV for verification codes with optional short IMAP
fallback disabled for private deploy; track config.json/.env for private repo.
Also add worker project, protocol mint backoff, and fail-fast Turnstile/mail
timeouts from batch runs.

README.md

@@ -108,6 +108,90 @@ uv run python grok_register_ttk.py
 
 ---
 
+
+## Gmail + Cloudflare Email Worker（秒级取码）
+
+推荐混合链路（**不需要公网 IP / 内网穿透**）：
+
+```
+xAI 发信
+  → Cloudflare Email Routing（域名 catch-all）
+  → Email Worker：解析验证码 → 写入 KV
+  → （可选）forward 到 Gmail，保留 IMAP 兜底
+  → 注册机：GET https://<worker>/code?to=alias@domain&key=...
+  → 未命中再回退 Gmail IMAP
+```
+
+### 1. 部署 Worker
+
+```bash
+cd cf-email-worker
+# 详见 cf-email-worker/README.md
+npx wrangler login
+npx wrangler kv namespace create GROK_MAIL_CODES   # id 写入 wrangler.toml
+npx wrangler secret put CODE_API_KEY
+# 可选：保留 Gmail 兜底
+# printf 'you@gmail.com' | npx wrangler secret put GMAIL_FORWARD_TO
+npx wrangler deploy
+```
+
+或用助手脚本：
+
+```bash
+export GMAIL_FORWARD_TO='you@gmail.com'   # 可选
+bash scripts/setup_gmail_worker.sh
+```
+
+### 2. Email Routing
+
+Dashboard → **Email Routing** → Catch-all → **Send to a Worker** → 选 `grok-xai-mail-codes`。
+
+> 若以前 catch-all 只转发 Gmail：改成进 Worker，由 Worker 内 `GMAIL_FORWARD_TO` 再转到 Gmail。
+
+### 3. 注册机配置
+
+`config.json`（`email_provider` 仍为 `gmail`）：
+
+```json
+{
+  "email_provider": "gmail",
+  "defaultDomains": "your-domain.com",
+  "gmail_imap_user": "you@gmail.com",
+  "gmail_imap_password": "app-password",
+  "gmail_worker_enabled": true,
+  "gmail_worker_url": "https://grok-xai-mail-codes.<subdomain>.workers.dev",
+  "gmail_worker_api_key": "与 CODE_API_KEY 相同",
+  "gmail_worker_timeout_sec": 25,
+  "gmail_worker_poll_interval": 0.4,
+  "gmail_imap_fallback": true
+}
+```
+
+### 4. 自测
+
+```bash
+# 模拟入库 + 取码
+python scripts/test_gmail_worker.py --to test@your-domain.com --ingest-demo
+
+# 真实邮件：给 random@your-domain.com 发信后轮询
+python scripts/test_gmail_worker.py --to random@your-domain.com --timeout 60
+```
+
+日志里成功时会看到：
+
+```text
+[*] Gmail 取码：优先 Email Worker（timeout=25s），超时回退 IMAP
+[*] Gmail Worker 取到验证码: ABC-DEF (elapsed=2.1s ...)
+```
+
+未命中 Worker 时：
+
+```text
+[*] Gmail Worker 未命中，回退 IMAP（剩余 timeout=...s）
+[*] Gmail IMAP 从邮件中提取到验证码: ...
+```
+
+
 ## 配置
 
 1. 复制模板并编辑（模板内 `"//…"` 键是注释，加载时忽略）：