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

项目文件结构说明.md

@@ -21,7 +21,7 @@
 - `.gitignore`：定义仓库忽略规则，当前忽略 `docs/md/`、`.github/`、`_metadata/`、`.vscode/` 等目录。
 - `LICENSE`：项目许可证文件。
 - `README.md`：面向使用者的精简说明文档，主要介绍项目用途、功能范围、快速开始与文档入口；不再承载过多技术实现细节。
-- `background.js`：扩展后台 Service Worker 入口壳，负责模块装配、初始化、全局常量、少量保留的领域函数与运行入口；当前已按 `activeFlowId` 装配 flow-aware 的步骤定义、执行注册表、自动运行与状态同步，`openai` flow 继续承接 `oauthFlowTimeoutEnabled` 与 `stepExecutionRangeByFlow`，`kiro` flow 则走独立的“注册页 1-6 步 -> 桌面授权 7-8 步 -> `kiro.rs` 上传 9 步”链路。
+- `background.js`：扩展后台 Service Worker 入口壳，负责模块装配、初始化、全局常量、少量保留的领域函数与运行入口；当前已按 `activeFlowId` 装配 flow-aware 的步骤定义、执行注册表、自动运行与状态同步，`openai` flow 继续承接 `oauthFlowTimeoutEnabled` 与 `stepExecutionRangeByFlow`，`kiro` flow 走独立的“注册页 1-6 步 -> 桌面授权 7-8 步 -> `kiro.rs` 上传 9 步”链路，`grok` flow 走独立的“注册页 1-4 步 -> SSO Cookie 提取 5 步”链路。
 - `cloudmail-utils.js`：Cloud Mail / SkyMail 相关的纯工具函数，负责 API 地址、域名、鉴权头、邮件列表响应与邮件正文归一化。
 - `cloudflare-temp-email-utils.js`：Cloudflare Temp Email 相关的纯工具函数，负责 URL、域名、邮件内容与 MIME 数据归一化。
 - `gopay-utils.js`：GoPay / GPC Plus 支付相关纯工具函数，负责支付方式归一化、GoPay 手机号/OTP/PIN 归一化、GPC API 地址归一化、API Key 请求头、任务创建/查询/OTP/PIN/停止 URL 与余额响应解析。
@@ -59,11 +59,14 @@
 - `flows/kiro/background/desktop-client.js`：Kiro 桌面授权协议层，负责桌面 OIDC client 注册、PKCE 参数生成、授权地址组装、callback 参数校验和授权码换 token。
 - `flows/kiro/background/desktop-authorize-runner.js`：Kiro 桌面授权执行器，负责步骤 7~8 的标签页打开、授权页轮询、localhost callback 捕获，以及桌面授权完成后的凭据落库。
 - `flows/kiro/background/publisher-kiro-rs.js`：Kiro 发布器，负责 `kiro.rs` 地址归一化、连通性探测、BuilderId profileArn 固定映射、machineId 计算、上传 payload 构建与最终凭据上传。
+- `flows/grok/background/state.js`：Grok 独立运行态模型与状态工具，负责 `runtimeState.flowState.grok.session / register / sso` 的默认值、归一化、兼容字段投影、节点完成回写、下游重置和 fresh-attempt keep-state 构建。
+- `flows/grok/background/register-runner.js`：Grok 注册页执行器，负责步骤 1~5 的编排、Grok/xAI 注册标签页管理、邮箱提交、验证码轮询提交、资料/密码提交、SSO Cookie 提取、去重保存与账号记录收尾。
 - `background/ip-proxy-core.js`：IP 代理核心模块，负责代理条目解析、账号/接口代理池运行态、PAC 应用与清除、代理鉴权回填、出口探测、失败时的目标站点 fail-close 防漏规则，以及自动运行成功阈值后的代理切换支撑。
 - `background/ip-proxy-provider-711proxy.js`：711Proxy provider 规则模块，负责从账号串中识别和写回 `region / session / sessTime` 等参数，并在固定账号模式下把侧栏配置转换为最终生效的代理账号。
 - `background/logging-status.js`：后台日志、步骤状态、错误信息和若干状态判断的公共工具层；日志条目统一写入结构化 `step / stepKey`，sidepanel 只读取该元数据渲染步骤标签，不再从日志正文解析步骤号；当前额外承接 `add-phone / 手机号页` 这类认证 fatal 错误的共享判定，并会把 Step 2 的“手机号输入模式未切成功”与真正的 auth `add-phone` 页面区分开，避免自动运行误停机。
 - `background/mail-2925-session.js`：2925 会话模块，负责 2925 账号池持久化、当前账号切换、cookie 清理登出、自动登录、命中“子邮箱已达上限邮箱”后的 24 小时禁用与自动切号。
 - `background/mail-rule-registry.js`：flow-aware 邮件规则注册表，负责按 `activeFlowId` 选择验证码规则构造器，并统一输出注册/登录验证码轮询 payload。
+- `background/flow-mail-polling.js`：flow-aware 邮件轮询调度层，负责读取共享邮箱配置、调用当前 flow 的 mail rules、分派 Hotmail / LuckMail / Cloudflare Temp Email / Cloud Mail / YYDS Mail API provider、准备 iCloud / 2925 / 网页邮箱会话，并统一通过邮箱内容脚本轮询验证码。
 - `background/message-router.js`：后台消息路由层，负责处理 `chrome.runtime.onMessage` 进入的所有业务消息；`LOG / STEP_COMPLETE / STEP_ERROR` 会把消息里的真实 `step` 继续传给结构化日志，跳过登录验证码这类派生日志也按当前步骤 key 写入；当前额外接入 PayPal 账号池的新增与切换、2925 账号池的新增、导入、切换、登录、禁用与删除消息，以及 IP 代理的同步、切换、Change 与出口检测消息；手动改邮箱、手动取邮箱等入口也统一经这里落到 `setEmailState`，同步维护注册邮箱运行态；当侧栏关闭 `oauthFlowTimeoutEnabled` 时，会立即清空已存在的 OAuth 总预算 deadline；手动 `EXECUTE_NODE` 会先按 `stepExecutionRangeByFlow` 校验当前节点是否允许执行。
 - `background/registration-email-state.js`：注册邮箱运行态共享模块，负责维护 `registrationEmailState = { current, previous, source, updatedAt }`，并提供“当前邮箱清空时保留上一比较基线”“Duck 生成前解析比较基线”“Step 8 `add-email` 写入邮箱时按需保留手机号身份”的统一工具。
 - `core/flow-kernel/runtime-state.js`：运行态视图与 patch 构造模块，负责把会话字段归一到 `runtimeState / sharedState / serviceState / flowState` 结构，并维护 flow-aware 的 session patch、节点状态默认值与兼容视图输出。
@@ -152,6 +155,11 @@
 ## `flows/`
 
 - `flows/openai/mail-rules.js`：OpenAI flow 的验证码邮件规则定义，负责按注册/登录节点输出 code pattern、关键词、目标邮箱提示、2925 receive 弱匹配与轮询参数。
+- `flows/kiro/mail-rules.js`：Kiro flow 的 AWS Builder ID 邮件规则定义，负责按注册验证码节点与桌面授权验证码节点输出 AWS 发件人、主题、关键词、code pattern、目标邮箱提示、2925 receive 弱匹配与轮询参数。
+- `flows/grok/index.js`：Grok flow 定义，声明 `webchat2api` target、Grok 注册页 runtime source、Grok 专属设置分组、能力边界与本地 SSO 导出属性；该 flow 当前没有 publication target，也不支持贡献 adapter。
+- `flows/grok/workflow.js`：Grok workflow 定义，固定输出打开注册页、提交邮箱、提交验证码、提交资料、提取 SSO Cookie 五个节点。
+- `flows/grok/mail-rules.js`：Grok flow 的 xAI / Grok 验证码邮件规则定义，负责输出发件人、主题、关键词、`ABC-123` 与 6 位码 pattern、目标邮箱提示、2925 receive 弱匹配与轮询参数。
+- `flows/grok/content/register-page.js`：Grok 注册页内容脚本，负责五个 Grok 节点的 DOM 操作、页面状态读取与局部点击事件坐标补齐，不修改全局浏览器原型。
 
 ## `icons/`
 
@@ -178,9 +186,10 @@
 ## `shared/`
 
 - `core/flow-kernel/flow-capabilities.js`：flow 能力矩阵归一化模块，负责根据 `activeFlowId` 与来源解析 sidepanel 的显隐能力、来源作用域、贡献模式边界、步骤范围 UI 作用域，以及 Plus 模式下 `账号接入策略` 的可选项、可编辑性与最终生效值。
-- `core/flow-kernel/flow-registry.js`：flow/source/settings group 总注册表，定义 `openai / kiro` 两套 flow、各自 target/runtime source、可见分组、driver 定义，以及默认 target 和默认 `kiro.rs` 配置。
+- `core/flow-kernel/flow-registry.js`：flow/source/settings group 总注册表，定义 `openai / kiro / grok` 三套 flow、各自 target/runtime source、可见分组、driver 定义，以及默认 target 和默认 `kiro.rs` 配置。
 - `shared/kiro-timeouts.js`：Kiro 共享超时常量与归一化工具，负责注册页/桌面授权链路复用的页面加载超时配置。
-- `core/flow-kernel/settings-schema.js`：统一设置 schema 与归一化层，负责把持久配置收敛到 `settingsState.services.*` 与 `settingsState.flows.*` 结构，并维护 `activeFlowId`、OpenAI 的 integration target、Kiro 的 `flows.kiro.targetId / targets` 与 `stepExecutionRangeByFlow`。
+- `shared/contribution-registry.js`：贡献 adapter 与教程入口注册表，负责 OpenAI / Kiro 贡献 adapter、教程入口和发布贡献 flow 校验；默认发布校验只覆盖声明了 publication target 或支持贡献的 flow，Grok 这类本地 SSO 导出 flow 不自动纳入贡献 adapter 缺失检查。
+- `core/flow-kernel/settings-schema.js`：统一设置 schema 与归一化层，负责把持久配置收敛到 `settingsState.services.*` 与 `settingsState.flows.*` 结构，并维护 `activeFlowId`、OpenAI 的 integration target、Kiro/Grok 的 `flows.<flowId>.targetId / targets` 与 `stepExecutionRangeByFlow`。
 - `core/flow-kernel/source-registry.js`：运行时来源注册表，负责合并 flow runtime source 与共享 mail source，统一 source family、driver、URL 归属和 cleanup owner 判定。
 
 ## `sidepanel/`
@@ -270,7 +279,9 @@
 - `tests/background-mail2925-relogin-wait.test.js`：测试 2925 强制重登入口 URL、长登录超时与前后固定等待窗口。
 - `tests/background-mail2925-session-module.test.js`：测试 2925 会话模块已接入且导出工厂，并覆盖命中上限后“禁用 24 小时 + 切下一个号 + 自动登录”的核心链路。
 - `tests/background-mail2925-signup-flow.test.js`：测试注册页辅助层在 2925 provider 下，会先确保账号池里已分配可用账号，再继续生成别名邮箱。
-- `tests/background-mail-rule-registry-module.test.js`：测试邮件规则注册表与 OpenAI mail rules 模块接入，并覆盖验证码轮询 payload 构造。
+- `tests/background-flow-mail-polling-module.test.js`：测试 flow-aware 邮件轮询调度层对 API provider、网页邮箱 provider、2925 会话准备和 2925 上限恢复的共享分派行为。
+- `tests/background-mail-rule-registry-module.test.js`：测试邮件规则注册表与 OpenAI / Kiro mail rules 模块接入，并覆盖各 flow 验证码轮询 payload 构造。
+- `tests/background-grok-state-module.test.js`：测试 Grok 运行态 helper 的默认值、兼容字段投影、节点完成回写、下游重置、fresh-attempt keep-state 与 SSO Cookie 保留规则。
 - `tests/background-message-router-module.test.js`：测试消息路由模块已接入且导出工厂。
 - `tests/background-message-router-plus-final-step.test.js`：测试消息路由会按 Plus 当前最终节点追加成功记录，不再写死步骤 10。
 - `tests/background-message-router-step2-skip.test.js`：测试步骤 2 直接落到验证码页时的跳步与状态保护逻辑，并覆盖邮箱身份写入时清理旧手机号注册运行态。
@@ -358,6 +369,7 @@
 - `tests/sidepanel-contribution-button.test.js`：测试侧边栏顶部 `贡献` 按钮的 HTML 接线、更新提示气泡接线，以及相关脚本加载顺序。
 - `tests/sidepanel-account-records-manager.test.js`：测试侧边栏账号记录覆盖层的 HTML 接入、helper 地址归一化与 manager 渲染逻辑。
 - `tests/contribution-content-update-service.test.js`：测试贡献内容更新服务对公开摘要接口的归一化、版本提取与失败回退缓存逻辑。
+- `tests/contribution-registry.test.js`：测试贡献 adapter 注册、教程入口解析、默认发布贡献 flow 校验，以及 Grok 本地 SSO 导出 flow 不被自动纳入发布贡献检查。
 - `tests/flow-capabilities-module.test.js`：测试 flow 能力矩阵模块对来源作用域、显隐能力和贡献模式边界的归一化。
 - `tests/flow-registry-settings-schema.test.js`：测试 flow registry 与 settings schema 之间的默认值、来源映射和 flow-specific 配置结构保持一致。
 - `tests/sidepanel-custom-email-pool.test.js`：测试侧边栏自定义邮箱池、自定义邮箱服务号池的 HTML 接线，以及邮箱池长度与自动轮数之间的联动规则。
@@ -365,6 +377,7 @@
 - `tests/sidepanel-contribution-mode-flow-scope.test.js`：测试贡献模式只在 `openai` flow 内生效，不会污染 Kiro flow 的来源与面板作用域。
 - `tests/sidepanel-contribution-update-hint.test.js`：测试顶部贡献更新轻提示在公告、教程和托管 auto-run 提醒并存时的文案合成。
 - `tests/sidepanel-flow-source-registry.test.js`：测试 sidepanel 的 flow/source 选择器、Kiro 来源切换与显隐分组接线。
+- `tests/grok-runner.test.js`：测试 Grok 注册页执行器对邮箱提交、验证码轮询、资料提交、SSO Cookie 提取、账号记录收尾和完成状态持久化的关键链路。
 - `tests/sidepanel-auto-run-content-refresh.test.js`：测试点击“自动”时会先冻结当前轮数并刷新贡献内容更新摘要，且刷新失败或启动前状态回灌不会阻塞或改写自动流程启动目标。
 - `tests/sidepanel-auto-run-risk-warning.test.js`：测试自动运行在高轮数且未配置节点轮询时会弹出风险提醒。
 - `tests/sidepanel-cloudflare-temp-email-random-subdomain.test.js`：测试 Cloudflare Temp Email 独立区域、随机子域名开关、域名列表恢复与提示文案联动。