重构多 flow 邮件轮询并接入 Grok SSO

项目完整链路说明.md

@@ -10,10 +10,11 @@
 
 ## 1. 项目目标
 
-这是一个 Chrome 扩展，用于承载多套注册与认证自动化 flow。当前已注册两条主 flow：
+这是一个 Chrome 扩展，用于承载多套注册与认证自动化 flow。当前已注册三条主 flow：
 
 - `openai`：OpenAI / ChatGPT OAuth 注册、登录、平台绑定与 Plus 扩展链路
 - `kiro`：AWS Builder ID 注册页 + 桌面授权 + `kiro.rs` 凭据上传链路
+- `grok`：Grok / xAI 注册页自动化 + `webchat2api` SSO Cookie 本地导出链路
 
 它的核心价值不是“打开一个页面点几个按钮”，而是把下面这些环节串成一条完整可恢复的自动化链路：
 
@@ -28,7 +29,7 @@
 - 自动确认 OAuth 同意页
 - 把 localhost 回调提交到 CPA、SUB2API 或 Codex2API
 
-同时，这套扩展现在不再把“来源、步骤、侧边栏显隐、运行态字段”硬编码在单一 OpenAI 链路里，而是统一挂到 `flow registry + source registry + settings schema + step definitions` 这一层。Kiro 这类新 flow 可以复用共享邮箱服务与 IP 代理服务，但不会复用 OpenAI 的接码、Plus、平台绑定和贡献模式逻辑。
+同时，这套扩展现在不再把“来源、步骤、侧边栏显隐、运行态字段”硬编码在单一 OpenAI 链路里，而是统一挂到 `flow registry + source registry + settings schema + step definitions` 这一层。Kiro / Grok 这类新 flow 可以复用共享邮箱服务与 IP 代理服务，但不会复用 OpenAI 的接码、Plus、平台绑定和贡献模式逻辑。
 
 ## 2. 核心运行参与者
 
@@ -43,8 +44,8 @@
 - 向后台发送命令
 - 接收后台广播并更新 UI
 - 动态渲染步骤列表
-- 维护 `activeFlowId + targetId` 的双层选择；`openai` flow 继续把 `panelMode` 归一为 legacy integration target，`kiro` flow 则使用独立的 `flows.kiro.targetId`
-- 按当前 flow capability 决定显隐分组；Kiro flow 只显示来源下拉、`kiro.rs URL / API Key`、共享邮箱服务、共享 IP 代理与 Kiro 运行状态，不显示 OpenAI 接码 / Plus / 平台绑定配置
+- 维护 `activeFlowId + targetId` 的双层选择；`openai` flow 继续把 `panelMode` 归一为 legacy integration target，`kiro` / `grok` flow 使用各自的 `flows.<flowId>.targetId`
+- 按当前 flow capability 决定显隐分组；Kiro flow 只显示来源下拉、`kiro.rs URL / API Key`、共享邮箱服务、共享 IP 代理与 Kiro 运行状态；Grok flow 只显示 `webchat2api` SSO 导出状态、共享账号密码、共享邮箱服务和共享 IP 代理；二者都不显示 OpenAI 接码 / Plus / 平台绑定配置
 - 管理顶部“贡献”按钮与贡献模式主面板；贡献模式本身是 sidepanel 的运行态 UI 模式，不是新的 `panelMode` 来源
 - 在贡献模式下复用同一套主自动流程启动，并在面板内展示贡献链路的 `OAUTH / 回调 / 总状态` 三块实时状态
 - 在顶部“贡献/使用”按钮下方展示一个非强制的内容更新轻提示；提示来源于 `flowpilot.qlhazycoder.top` 的公开公告 / 教程摘要，用户关闭后仅对当前 `promptVersion` 静默，下次内容版本变化后会重新出现
@@ -150,13 +151,13 @@
 - `runtimeState`：当前运行中的 node、nodeStatuses、activeRunId 等核心执行态
 - `sharedState`：automation window、tab registry、最近来源 URL 这类跨 flow 共享运行态
 - `serviceState`：代理、邮箱等共享服务运行态
-- `flowState`：OpenAI / Kiro 各自的 flow 私有运行态
+- `flowState`：OpenAI / Kiro / Grok 各自的 flow 私有运行态
 
 这两个模块的作用，是把“当前该跑哪些节点”“当前 state 应该怎么看”“前后台恢复时如何合并 patch”从 `background.js` 主入口里抽离出来，避免再次退回到旧的平铺 step 状态机。
 
 ### 3.4 步骤注册
 
-[data/step-definitions.js](./data/step-definitions.js) 提供共享步骤元数据，并按当前 `activeFlowId` 输出 flow-specific workflow。`openai` flow 会继续按 `plusPaymentMethod / signupMethod / plusAccountAccessStrategy` 动态解析步骤标题与节点集合：当 Plus 模式为邮箱注册且来源支持时，原本的 OAuth 尾链可以被替换成 `sub2api-session-import` 或 `cpa-session-import`；`kiro` flow 则输出固定的 9 节点注册/桌面授权/上传 workflow。
+[data/step-definitions.js](./data/step-definitions.js) 提供共享步骤元数据，并按当前 `activeFlowId` 输出 flow-specific workflow。`openai` flow 会继续按 `plusPaymentMethod / signupMethod / plusAccountAccessStrategy` 动态解析步骤标题与节点集合：当 Plus 模式为邮箱注册且来源支持时，原本的 OAuth 尾链可以被替换成 `sub2api-session-import` 或 `cpa-session-import`；`kiro` flow 输出固定的 9 节点注册/桌面授权/上传 workflow；`grok` flow 输出固定的 5 节点注册与 SSO Cookie 提取 workflow。
 [core/flow-kernel/step-registry.js](./core/flow-kernel/step-registry.js) 负责把“workflow node 元数据”映射到“步骤执行器”，同时保留 `flowId / nodeId / displayOrder / executeKey` 等稳定节点元数据。
 
 这意味着：
@@ -168,7 +169,7 @@
 
 ### 3.4.1 验证码规则注册
 
-[background/mail-rule-registry.js](./background/mail-rule-registry.js) 负责按当前 `activeFlowId` 选择验证码规则构造器。[flows/openai/mail-rules.js](./flows/openai/mail-rules.js) 则提供 OpenAI flow 当前使用的注册验证码 / 登录验证码规则。
+[background/mail-rule-registry.js](./background/mail-rule-registry.js) 负责按当前 `activeFlowId` 选择验证码规则构造器。[flows/openai/mail-rules.js](./flows/openai/mail-rules.js) 提供 OpenAI flow 当前使用的注册验证码 / 登录验证码规则，[flows/kiro/mail-rules.js](./flows/kiro/mail-rules.js) 提供 Kiro / AWS Builder ID 注册验证码与桌面授权验证码规则，[flows/grok/mail-rules.js](./flows/grok/mail-rules.js) 提供 xAI / Grok 注册验证码规则。
 
 这层统一产出：
 
@@ -180,7 +181,8 @@
 它的职责边界是：
 
 - `background/verification-flow.js` 只消费统一规则 payload，不再在每个 provider 或内容脚本里各自硬写一套 OpenAI 验证码过滤条件。
-- “邮件从哪里读”由 provider 决定，“哪封邮件算命中验证码”优先由规则注册层决定。
+- `background/flow-mail-polling.js` 负责共享的 provider 分派、iCloud / 2925 会话准备、网页邮箱标签页打开与内容脚本轮询；flow runner 只提供 `flowId / nodeId / step / filterAfterTimestamp` 这类业务上下文。
+- “邮件从哪里读”由公共轮询调度层和 provider 决定，“哪封邮件算命中验证码”优先由规则注册层决定。
 - 新 flow 如需接入邮箱验证码，应优先新增自己的 mail rules builder，而不是继续改写 OpenAI 规则。
 
 ### 3.5 日志步骤号链路
@@ -214,6 +216,7 @@
   - `contributionLastPollAt`
 - OAuth 链接
 - Kiro 运行态：使用 `kiroRuntime.session / register / webAuth / desktopAuth / upload` 命名空间，保存 Kiro 官方登录入口、Builder ID 注册页状态、Kiro Web 登录态摘要、桌面授权 PKCE 凭据、上传状态和当前 Kiro 会话进度
+- Grok 运行态：权威状态位于 `runtimeState.flowState.grok`，包含 `session / register / sso`；顶层 `grokRegisterTabId / grokPageState / grokEmail / grokPassword / grokSsoCookie / grokSsoCookies` 只作为兼容投影，不应当再形成第二套状态机
 - 当前轮冻结后的注册方式 `resolvedSignupMethod`
 - 当前统一账号标识 `accountIdentifierType / accountIdentifier`
 - 当前邮箱 / 密码
@@ -762,9 +765,32 @@ Kiro flow 的目标不是复用 OpenAI 注册链，而是独立完成“Kiro 官
 - Kiro 只复用共享账户密码、共享邮箱服务和共享 IP 代理服务，不复用 OpenAI 接码 / Plus / 平台绑定 / 贡献模式链路
 - Kiro 自动运行走通用 linear node runner，但执行器、运行态、页面驱动和上传器全部独立在 `background/kiro/*` 与 `content/kiro/*`
 - Kiro 运行态统一落在 `kiroRuntime` 命名空间，不再散落为多个平铺字段
+- Kiro 注册验证码与桌面授权验证码只在 runner 内计算业务时间窗，具体 AWS 邮件匹配规则由 `flows/kiro/mail-rules.js` 提供，provider 分派统一走 `background/flow-mail-polling.js`
 - `kiro.rs` 上传固定发送 BuilderId profileArn `arn:aws:codewhisperer:us-east-1:638616132270:profile/AAAACCCCXXXX`，machineId 固定按 `sha256("KotlinNativeAPI/" + refreshToken)` 生成
 - Kiro 注册页覆盖 `app.kiro.dev` 与 AWS Builder ID 页面；桌面授权页只绑定 AWS authorize 页面，二者由后台按 source 动态注入，避免同域 AWS 页面被错误归到另一条 Kiro 子链路
 
+## 6.3 Grok Flow 链路
+
+Grok flow 的目标是完成 Grok / xAI 注册页自动化，并把 `sso` Cookie 作为 `webchat2api` 可用的本地导出产物。它不是 OpenAI 目标来源，也不是公开贡献 / 发布 flow。
+
+链路如下：
+
+1. sidepanel 把当前 flow 切到 `grok`，target 固定为 `webchat2api`
+2. 步骤 1 打开 Grok / xAI 注册入口，并清理本轮注册页运行态
+3. 步骤 2 通过共享邮箱服务生成或复用注册邮箱，并提交到 xAI 登录/注册页
+4. 步骤 3 调用 `background/flow-mail-polling.js`，由 `flows/grok/mail-rules.js` 构造 xAI / Grok 验证码规则并轮询邮箱验证码，再交给 Grok 内容脚本提交
+5. 步骤 4 填写资料和密码，推进注册完成页状态
+6. 步骤 5 先通过 `chrome.cookies.get` 从 `x.ai / grok.com / accounts.x.ai` 查找 `sso` Cookie，必要时 fallback 到 Grok 内容脚本读取 `document.cookie`；提取到的值保存到 `runtimeState.flowState.grok.sso` 并投影到 `grokSsoCookie / grokSsoCookies`
+7. sidepanel 只展示掩码后的 SSO 值，复制和导出才使用完整值；清空动作必须发 `CLEAR_GROK_SSO_COOKIES` 给后台，由 `flows/grok/background/state.js` 构造 patch，不能在 sidepanel 直接写 `chrome.storage`
+
+这条链路的关键边界是：
+
+- Grok 只复用共享账户密码、共享邮箱服务和共享 IP 代理服务，不复用 OpenAI 接码 / Plus / 平台绑定 / 贡献模式链路
+- Grok 自动运行走通用 linear node runner，执行器、运行态、页面驱动和邮件规则全部放在 `flows/grok/*`
+- Grok 内容脚本不能全局 patch 浏览器原型；点击事件需要的坐标只能在局部事件参数里补齐
+- Grok SSO Cookie 是本地导出产物，`flows/grok/index.js` 的 `publicationTargets` 保持为空，`supportsAccountContribution` 保持为 `false`
+- `shared/contribution-registry.js` 的默认发布贡献校验只覆盖声明了发布目标或支持贡献的 flow；Grok 不应被自动纳入贡献 adapter 缺失检查。如果未来要把 Grok 改成正式发布 flow，必须先新增明确的 publication target 与 contribution adapter，再打开对应能力
+
 ## 7. 邮箱与 provider 链路
 
 ### 7.1 共享邮箱生成补充
@@ -840,8 +866,11 @@ Kiro flow 的目标不是复用 OpenAI 注册链，而是独立完成“Kiro 官
 - `background/registration-email-state.js`
   统一维护当前注册邮箱、上一份比较基线邮箱、来源与更新时间，并提供 Duck 生成前解析比较基线、Step 8 清空当前邮箱但保留历史基线，以及 Step 8 `add-email` 写入邮箱时保留手机号身份的共享工具。
 
-- `background/mail-rule-registry.js` + `flows/openai/mail-rules.js`
-  统一构造 Step 4 / Step 8 的验证码规则 payload，区分注册验证码与登录/绑定验证码，并把 `senderFilters / subjectFilters / codePatterns / targetEmailHints / mail2925MatchTargetEmail` 收敛到同一层。
+- `background/mail-rule-registry.js` + `flows/*/mail-rules.js`
+  统一构造各 flow 的验证码规则 payload，区分 OpenAI 注册/登录验证码、Kiro 注册/桌面授权验证码与 Grok 注册验证码，并把 `senderFilters / subjectFilters / codePatterns / targetEmailHints / mail2925MatchTargetEmail` 收敛到 flow mail rules 层。
+
+- `background/flow-mail-polling.js`
+  统一执行 flow 邮箱验证码轮询调度：读取当前邮箱配置，调用 `mailRuleRegistry.buildVerificationPollPayloadForNode`，分派 Hotmail / LuckMail / Cloudflare Temp Email / Cloud Mail / YYDS Mail 这类 API provider，并为 iCloud、2925 和普通网页邮箱准备会话与内容脚本轮询。Kiro 与后续新 flow 不应在各自 runner 内复制 provider 分派逻辑。
 
 - `background/generated-email-helpers.js`
   在原有 Duck / Cloudflare / iCloud / Cloudflare Temp Email 生成链路之外，新增 Gmail / 2925 的共享生成接入；Duck 生成前会按“侧栏当前可见邮箱 -> `registrationEmailState.current` -> `registrationEmailState.previous`”的顺序解析比较基线。
@@ -1131,6 +1160,7 @@ Hide My Email 获取与管理链路：
    - 如果当前 `Mail = 自定义邮箱` 且配置了 `customMailProviderPool`，会先按当前目标轮次把号池中的对应邮箱写回运行态
    - 如果当前生成方式是 `custom-pool`，会先按当前目标轮次把邮箱池中的对应邮箱写回运行态
    - fresh-attempt reset 会保留 `stepExecutionRangeByFlow`，避免重置运行态时丢失用户设置的执行窗口
+   - Grok fresh-attempt reset 会清理注册页 runtime，但保留已提取的 `grokSsoCookies`，避免用户导出前被下一轮准备动作清空
 5. 执行 `runAutoSequenceFromStep`
    - 如果当前 `activeFlowId !== openai`，后台会切到通用 linear node runner，按当前 flow 的 workflow node 顺序执行，并复用统一的完成状态与 idle watchdog
    - 如果 `stepExecutionRangeByFlow` 已启用，自动运行只会遍历允许范围内的 workflow node；范围外节点会被跳过，`getFirstUnfinishedNodeId` 与保存进度判断也只统计允许节点