refactor flows into canonical runtime architecture

项目完整链路说明.md

@@ -1,4 +1,4 @@
-# 项目完整链路说明
+# 项目完整链路说明
 
 本文档面向 AI 与开发者，目标是让阅读者在最短时间内理解“项目做什么、怎么跑、数据怎么流、功能链路怎么串”，从而在新增功能时不漏逻辑、不误改边界。
 
@@ -124,10 +124,10 @@
 
 ### 3.3 Flow / Source 注册
 
-[shared/flow-registry.js](./shared/flow-registry.js) 定义 flow、来源、可见设置分组、runtime source 与 driver。
-[shared/source-registry.js](./shared/source-registry.js) 负责把 flow runtime source 与共享 mail source 合并成统一来源视图。
-[shared/flow-capabilities.js](./shared/flow-capabilities.js) 负责把当前 flow/source 解析成 sidepanel 的能力矩阵。
-[shared/settings-schema.js](./shared/settings-schema.js) 负责把旧平铺字段与新的 `flows.*` 配置结构互转。
+[core/flow-kernel/flow-registry.js](./core/flow-kernel/flow-registry.js) 定义 flow、来源、可见设置分组、runtime source 与 driver。
+[core/flow-kernel/source-registry.js](./core/flow-kernel/source-registry.js) 负责把 flow runtime source 与共享 mail source 合并成统一来源视图。
+[core/flow-kernel/flow-capabilities.js](./core/flow-kernel/flow-capabilities.js) 负责把当前 flow/source 解析成 sidepanel 的能力矩阵。
+[core/flow-kernel/settings-schema.js](./core/flow-kernel/settings-schema.js) 负责把旧平铺字段与新的 `flows.*` 配置结构互转。
 
 这意味着：
 
@@ -138,14 +138,14 @@
 
 ### 3.3.1 Workflow 与运行态基础设施
 
-[background/workflow-engine.js](./background/workflow-engine.js) 负责把当前 flow 的 workflow 节点定义变成统一的执行视图，包括：
+[core/flow-kernel/workflow-engine.js](./core/flow-kernel/workflow-engine.js) 负责把当前 flow 的 workflow 节点定义变成统一的执行视图，包括：
 
 - 节点默认状态 `pending`
 - 当前 workflow 的节点顺序与 `nodeId`
 - `next` 后继节点解析
 - `getFirstUnfinishedNodeId / getRunningNodeIds / hasSavedProgress` 这类自动运行与恢复入口共享判断
 
-[background/runtime-state.js](./background/runtime-state.js) 则负责把 session 运行态整理成统一的结构化视图与 patch 入口：
+[core/flow-kernel/runtime-state.js](./core/flow-kernel/runtime-state.js) 则负责把 session 运行态整理成统一的结构化视图与 patch 入口：
 
 - `runtimeState`：当前运行中的 node、nodeStatuses、activeRunId 等核心执行态
 - `sharedState`：automation window、tab registry、最近来源 URL 这类跨 flow 共享运行态
@@ -157,7 +157,7 @@
 ### 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。
-[background/steps/registry.js](./background/steps/registry.js) 负责把“workflow node 元数据”映射到“步骤执行器”，同时保留 `flowId / nodeId / displayOrder / executeKey` 等稳定节点元数据。
+[core/flow-kernel/step-registry.js](./core/flow-kernel/step-registry.js) 负责把“workflow node 元数据”映射到“步骤执行器”，同时保留 `flowId / nodeId / displayOrder / executeKey` 等稳定节点元数据。
 
 这意味着：
 
@@ -244,7 +244,7 @@
 
 补充：
 
-- `background/runtime-state.js` 会把会话运行态统一整理成 `runtimeState / sharedState / serviceState / flowState` 四层结构；当前顶层那些 `currentNodeId / nodeStatuses / automationWindowId / ipProxyApplied* / flowId / runId` 等兼容字段，都是这份结构化运行态的投影视图，不应再当成另一套平行状态机维护。
+- `core/flow-kernel/runtime-state.js` 会把会话运行态统一整理成 `runtimeState / sharedState / serviceState / flowState` 四层结构；当前顶层那些 `currentNodeId / nodeStatuses / automationWindowId / ipProxyApplied* / flowId / runId` 等兼容字段，都是这份结构化运行态的投影视图，不应再当成另一套平行状态机维护。
 - `automationWindowId` 会同时存在于顶层兼容字段与 `runtimeState.sharedState` 视图中；真正目的是约束自动化只在当前 sidepanel 所在窗口里继续接管标签页，而不是把不同窗口里的同类页面串到一起。
 - `content/mail-2925.js` 会把“当前验证码步骤启动会话”对应的已试验证码写入 `chrome.storage.session`，键为 `seen2925CodeState`；同一个 Step 4 / Step 8 会话里试过的验证码不会再次提交，新会话开始时会重置。
 
@@ -366,7 +366,7 @@ IP 代理模块在同步、切换、Change、出口探测和自动运行成功
 
 ### 5.2 队列与重试
 
-[background/tab-runtime.js](./background/tab-runtime.js) 负责：
+[core/flow-kernel/tab-runtime.js](./core/flow-kernel/tab-runtime.js) 负责：
 
 - `queueCommand`
 - `flushCommand`
@@ -386,7 +386,7 @@ IP 代理模块在同步、切换、Change、出口探测和自动运行成功
 
 当前接入方式：
 
-- 它会在 `content/utils.js` 之后注入到需要真实页面交互的 bundle，例如 `signup-page`、`plus-checkout`、`paypal-flow`、`gopay-flow`，以及 `mail-2925` 这类仍有页面级点击/清理动作的链路。
+- 它会在 `content/utils.js` 之后注入到需要真实页面交互的 bundle，例如 `openai-auth`、`plus-checkout`、`paypal-flow`、`gopay-flow`，以及 `mail-2925` 这类仍有页面级点击/清理动作的链路。
 - 它主要包装输入、选择、点击、提交与短等待这类页面内操作；当前默认节奏为 2 秒。
 - `confirm-oauth`、`platform-verify` 这类后台节点不走这一层；邮箱 API 轮询、短信 API 轮询、WhatsApp 读码和其他纯后台请求也不应被硬塞进 2 秒延迟。
 - `operationDelayEnabled` 这个持久字段现在仍会被内容脚本监听，但对外语义已经等价于“始终启用”，保留它主要是为了兼容旧配置与统一注入同步。
@@ -397,8 +397,8 @@ IP 代理模块在同步、切换、Change、出口探测和自动运行成功
 
 文件：
 
-- [background/steps/open-chatgpt.js](./background/steps/open-chatgpt.js)
-- [content/signup-page.js](./content/signup-page.js)
+- [flows/openai/background/steps/open-chatgpt.js](./flows/openai/background/steps/open-chatgpt.js)
+- [flows/openai/content/openai-auth.js](./flows/openai/content/openai-auth.js)
 
 流程：
 
@@ -415,7 +415,7 @@ IP 代理模块在同步、切换、Change、出口探测和自动运行成功
 
 文件：
 
-- [background/steps/submit-signup-email.js](./background/steps/submit-signup-email.js)
+- [flows/openai/background/steps/submit-signup-email.js](./flows/openai/background/steps/submit-signup-email.js)
 
 流程：
 
@@ -425,7 +425,7 @@ IP 代理模块在同步、切换、Change、出口探测和自动运行成功
 4. 内容脚本识别到官网“免费注册 / Sign up / Register”入口后，会先等待 3 秒再点击；如果点击后仍停留在官网入口页、没有进入邮箱或手机号输入页，会再次等待 3 秒后重试，最多额外重试 5 次，且每次真正点击前都会检查 Stop 状态
 5. 邮箱注册时，如果注册弹窗默认停留在手机号输入模式，会先尝试点击 `继续使用电子邮件地址登录 / Continue using email address` 一类按钮切回邮箱输入模式
 6. 邮箱注册分支：提交邮箱；邮箱输入框识别同时兼容本地化占位与 `aria-label`
-7. 手机号注册分支：先点击官网“免费注册”并切换到手机号注册入口，必要时展开更多选项；确认手机号输入页就绪后，按“已有 signup activation > 手动填写的运行态手机号 > 接码平台新申请号码”的顺序决定手机号来源，避免重复买号。内容脚本会通过 `content/phone-country-utils.js` 共享工具按号码最长区号和平台国家名切换手机号国家下拉框，兼容 `+(44)` / `(+44)` / `+44` 等页面文案；必须确认可视下拉按钮的区号已同步后才填写并提交，若仍显示旧国家则停止提交
+7. 手机号注册分支：先点击官网“免费注册”并切换到手机号注册入口，必要时展开更多选项；确认手机号输入页就绪后，按“已有 signup activation > 手动填写的运行态手机号 > 接码平台新申请号码”的顺序决定手机号来源，避免重复买号。内容脚本会通过 `flows/openai/content/phone-country-utils.js` 共享工具按号码最长区号和平台国家名切换手机号国家下拉框，兼容 `+(44)` / `(+44)` / `+44` 等页面文案；必须确认可视下拉按钮的区号已同步后才填写并提交，若仍显示旧国家则停止提交
 8. 以当前统一账号标识先写入一条“停止（流程尚未完成）”的记录占位；邮箱账号占位邮箱，phone-only 账号占位手机号
 9. 等待身份提交后的真实落地页
 10. 如果进入密码页，则继续执行 Step 3
@@ -435,7 +435,7 @@ IP 代理模块在同步、切换、Change、出口探测和自动运行成功
 
 文件：
 
-- [background/steps/fill-password.js](./background/steps/fill-password.js)
+- [flows/openai/background/steps/fill-password.js](./flows/openai/background/steps/fill-password.js)
 
 流程：
 
@@ -460,8 +460,8 @@ IP 代理模块在同步、切换、Change、出口探测和自动运行成功
 
 文件：
 
-- [background/steps/fetch-signup-code.js](./background/steps/fetch-signup-code.js)
-- [background/steps/fetch-login-code.js](./background/steps/fetch-login-code.js)
+- [flows/openai/background/steps/fetch-signup-code.js](./flows/openai/background/steps/fetch-signup-code.js)
+- [flows/openai/background/steps/fetch-login-code.js](./flows/openai/background/steps/fetch-login-code.js)
 - [background/verification-flow.js](./background/verification-flow.js)
 
 这两步共享验证码主流程：
@@ -489,7 +489,7 @@ IP 代理模块在同步、切换、Change、出口探测和自动运行成功
 - `2925` 内容脚本会把每一封实际打开检测的邮件立即删除；同一验证码步骤启动后，试过的验证码会按“步骤 ID + 启动时间”隔离缓存，不会在本次步骤里重复提交；如果再次遇到相同验证码，对应邮件也会在读取后立即删除，避免后续反复打开。
 - `2925` 在 provide 模式下仍保持宽松匹配：只要邮件内容命中 ChatGPT / OpenAI 验证码过滤条件，就会尝试该邮件。
 - `2925` 在 receive 模式下会恢复“弱目标邮箱匹配”：只有当邮件里显式出现了其他收件邮箱时才会跳过；如果邮件里没有明确写出邮箱，仍允许继续尝试该验证码。
-- 手动点击 Step 4 重新执行时，后台会先检查 `signup-page` 认证页标签是否仍然存在；如果步骤 1 / 2 打开的认证页已经关闭，就会直接提示“请先执行步骤 1 或步骤 2，确保认证页仍然打开并停留在验证码页”，不会先重置后续步骤再报技术错误。
+- 手动点击 Step 4 重新执行时，后台会先检查 `openai-auth` 认证页标签是否仍然存在；如果步骤 1 / 2 打开的认证页已经关闭，就会直接提示“请先执行步骤 1 或步骤 2，确保认证页仍然打开并停留在验证码页”，不会先重置后续步骤再报技术错误。
 - 当验证码最终提交成功后，后台会异步向 2925 邮箱页发送 `DELETE_ALL_EMAILS`，执行“全选 + 删除”清理剩余邮件，不阻塞主流程。
 - 如果 `2925` 邮箱页在轮询期间出现“子邮箱已达上限邮箱”，后台会记录当前时间，把当前 2925 账号禁用 24 小时，自动切到下一个可用账号并完成登录，然后直接报错结束当前尝试；如果 Auto 开启了自动重试，现有控制器会按原逻辑进入下一次尝试。
 
@@ -499,7 +499,7 @@ IP 代理模块在同步、切换、Change、出口探测和自动运行成功
 
 文件：
 
-- [background/steps/fill-profile.js](./background/steps/fill-profile.js)
+- [flows/openai/background/steps/fill-profile.js](./flows/openai/background/steps/fill-profile.js)
 
 流程：
 
@@ -513,7 +513,7 @@ IP 代理模块在同步、切换、Change、出口探测和自动运行成功
 
 文件：
 
-- [background/steps/wait-registration-success.js](./background/steps/wait-registration-success.js)
+- [flows/openai/background/steps/wait-registration-success.js](./flows/openai/background/steps/wait-registration-success.js)
 
 流程：
 
@@ -526,7 +526,7 @@ IP 代理模块在同步、切换、Change、出口探测和自动运行成功
 
 文件：
 
-- [background/steps/oauth-login.js](./background/steps/oauth-login.js)
+- [flows/openai/background/steps/oauth-login.js](./flows/openai/background/steps/oauth-login.js)
 
 流程：
 
@@ -554,7 +554,7 @@ IP 代理模块在同步、切换、Change、出口探测和自动运行成功
 
 文件：
 
-- [background/steps/fetch-login-code.js](./background/steps/fetch-login-code.js)
+- [flows/openai/background/steps/fetch-login-code.js](./flows/openai/background/steps/fetch-login-code.js)
 
 流程：
 
@@ -589,7 +589,7 @@ IP 代理模块在同步、切换、Change、出口探测和自动运行成功
 
 文件：
 
-- [background/steps/confirm-oauth.js](./background/steps/confirm-oauth.js)
+- [flows/openai/background/steps/confirm-oauth.js](./flows/openai/background/steps/confirm-oauth.js)
 
 流程：
 
@@ -615,7 +615,7 @@ IP 代理模块在同步、切换、Change、出口探测和自动运行成功
 
 文件：
 
-- [background/steps/platform-verify.js](./background/steps/platform-verify.js)
+- [flows/openai/background/steps/platform-verify.js](./flows/openai/background/steps/platform-verify.js)
 
 说明：
 
@@ -646,7 +646,7 @@ SUB2API 补充：
 - 步骤 7 直接调用 `POST /api/v1/auth/login` 登录管理接口，再调用 `/api/v1/admin/groups/all` 校验目标 openai 分组；如果配置了默认代理，会读取 `/api/v1/admin/proxies/all?with_count=true` 并按名称或 ID 选择代理。
 - 步骤 7 调用 `POST /api/v1/admin/openai/generate-auth-url` 获取 `auth_url / session_id / state`，并把目标分组 ID、代理 ID、草稿账号名写入运行态。
 - 步骤 10，以及 Plus 仍走 OAuth 尾链时的 `platform-verify` 节点，会直接用 localhost callback 中的 `code / state` 调用 `POST /api/v1/admin/openai/exchange-code`，再用返回的 OpenAI token 信息调用 `POST /api/v1/admin/accounts` 创建 SUB2API 账号。
-- SUB2API 主链路不再打开后台页面，也不再依赖 `content/sub2api-panel.js` 的 DOM 自动化；该内容脚本仅保留为旧后台页面路径的兼容能力。
+- SUB2API 主链路不再打开后台页面，也不再依赖 `flows/openai/content/sub2api-panel.js` 的 DOM 自动化；该内容脚本仅保留为旧后台页面路径的兼容能力。
 
 贡献模式补充：
 
@@ -1159,8 +1159,8 @@ Hide My Email 获取与管理链路：
 
 1. [data/step-definitions.js](./data/step-definitions.js)
 2. [background/steps](./background/steps)
-3. [background/steps/registry.js](./background/steps/registry.js)
-4. 如果步骤属于新 flow，还必须同步检查 [shared/flow-registry.js](./shared/flow-registry.js) 与 [shared/settings-schema.js](./shared/settings-schema.js)
+3. [core/flow-kernel/step-registry.js](./core/flow-kernel/step-registry.js)
+4. 如果步骤属于新 flow，还必须同步检查 [core/flow-kernel/flow-registry.js](./core/flow-kernel/flow-registry.js) 与 [core/flow-kernel/settings-schema.js](./core/flow-kernel/settings-schema.js)
 4. 自动运行链路是否需要纳入
 5. Step 状态传播和侧边栏展示是否需要适配
 6. 测试是否要补
@@ -1204,7 +1204,7 @@ Hide My Email 获取与管理链路：
   更新 [项目开发规范（AI协作）.md](./项目开发规范（AI协作）.md)
 ## 2026-04 链路补充：认证页共享恢复
 
-- 新增共享恢复层：`content/auth-page-recovery.js`。
+- 新增共享恢复层：`flows/openai/content/auth-page-recovery.js`。
 - Step 4 在等待注册验证码页时，如果命中认证页 `Try again / 重试` 页，或 `/email-verification` 上的 `405 / Route Error` 重试页，会先通过共享恢复逻辑最多自动点击 5 次 `重试` 尝试恢复，再继续回到密码页重提和验证码页确认流程。
 - 但如果 Step 4 的认证重试页正文中出现 `user_already_exists`，则会直接视为“当前用户已存在”：不点击 `重试`，不再回到步骤 1 重开当前轮，而是立即结束当前轮；开启自动重试时直接进入下一轮。
 - Step 7 在识别到登录超时报错页时，会先通过共享恢复逻辑最多自动点击 5 次 `重试` 尝试恢复当前页面；恢复成功后会优先按当前页面状态继续当前登录流程，例如直接续跑邮箱页或密码页；只有仍未恢复到可继续状态时，才按原有可恢复失败逻辑重跑 Step 7。
@@ -1219,3 +1219,4 @@ Hide My Email 获取与管理链路：
 - `2925` 在 Step 4 / Step 8 现在会携带固定的步骤开始时间窗口，实际筛选下限为“步骤开始时间向前回看 10 分钟”。
 - 为了保留这段固定时间窗内已经到达的验证码邮件，后台不再在轮询开始前预先清空 2925 邮箱。
 - `2925` 验证码最终提交成功后，后台仍会异步发送 `DELETE_ALL_EMAILS` 做收尾清理。
+