Hermes/FlowPilot
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
14a3e9d6b216e910ff8c965276c73de950271732
FlowPilot/项目完整链路说明.md
T

18 KiB
Raw Blame History

项目完整链路说明

本文档面向 AI 与开发者，目标是让阅读者在最短时间内理解“项目做什么、怎么跑、数据怎么流、功能链路怎么串”，从而在新增功能时不漏逻辑、不误改边界。

使用建议：

  1. 先阅读 项目文件结构说明.md
  2. 再阅读本文
  3. 最后阅读 项目开发规范（AI协作）.md

1. 项目目标

这是一个 Chrome 扩展，用于自动执行一整套 OpenAI / ChatGPT OAuth 注册与登录流程。

它的核心价值不是“打开一个页面点几个按钮”，而是把下面这些环节串成一条完整可恢复的自动化链路：

  • 生成或选取注册邮箱
  • 打开 ChatGPT / OpenAI 注册入口
  • 提交邮箱和密码
  • 轮询注册验证码
  • 填写姓名和生日
  • 刷新 OAuth 链接并登录
  • 轮询登录验证码
  • 自动确认 OAuth 同意页
  • 把 localhost 回调提交到 CPA 或 SUB2API

2. 核心运行参与者

2.1 Sidepanel

sidepanel/sidepanel.html + sidepanel/sidepanel.js

职责：

  • 展示配置与步骤状态
  • 接收用户输入
  • 向后台发送命令
  • 接收后台广播并更新 UI
  • 动态渲染步骤列表
  • 在日志区通过“记录”按钮打开独立的邮箱记录覆盖层，并展示成功/失败/停止/重试统计与分页列表

2.2 Background Service Worker

background.js

职责：

  • 扩展后台入口
  • 装配所有模块
  • 统一承接 runtime message
  • 协调步骤执行
  • 管理状态、自动运行、标签页与内容脚本通信

2.3 Content Scripts

content

职责：

  • 在目标网页上执行 DOM 交互
  • 读取邮件内容或页面状态
  • 将步骤成功/失败状态上报给后台

2.4 Helper / Utils / Provider Logic

分布在根目录和 background/ 下。

职责：

  • 抽离第三方邮箱 provider 的纯逻辑
  • 抽离邮件匹配与验证码提取
  • 抽离共享验证码流程、自动运行流程和运行时基础设施

3. 入口与装配关系

3.1 扩展入口

manifest.json 声明：

  • background.service_worker = background.js
  • side_panel.default_path = sidepanel/sidepanel.html
  • 多组内容脚本自动注入规则

3.2 背景层装配

background.js 通过 importScripts(...) 依次加载：

  • 共享数据与纯工具
  • provider 纯逻辑
  • 后台桥接层
  • 后台共享流程层
  • 后台运行时与消息路由层
  • 步骤执行模块

因此 background.js 现在更像：

  • 常量定义中心
  • 模块依赖装配器
  • 极少量保留函数
  • Chrome 事件挂接入口

3.3 步骤注册

data/step-definitions.js 提供共享步骤元数据。
background/steps/registry.js 负责把“步骤元数据”映射到“步骤执行器”。

这意味着：

  • 步骤顺序靠 order
  • 步骤文件名靠语义
  • 新增步骤时不需要重命名后续文件

4. 状态与存储链路

4.1 chrome.storage.session

保存运行态：

  • 当前步骤状态
  • OAuth 链接
  • 当前邮箱 / 密码
  • localhost 回调地址
  • 自动运行轮次信息
  • 当前自动运行 session 标识 autoRunSessionId
  • 标签注册表
  • 最近打开的来源地址
  • LuckMail 当前运行时选择

4.2 chrome.storage.local

保存持久配置与账号运行历史：

  • CPA / SUB2API 配置
  • 邮箱 provider 配置
  • Hotmail 账号池
  • Cloudflare / Temp Email 设置
  • iCloud 相关偏好
  • LuckMail API 配置
  • 自动运行默认配置
  • 账号运行历史 accountRunHistory（以邮箱为主键，保存该邮箱最近一次状态：成功/失败/停止）
  • 账号运行历史本地同步开关与 helper 地址

当启用了独立的账号运行历史本地同步配置时，账号运行历史会通过 scripts/hotmail_helper.py 整体同步写入 data/account-run-history.json 快照文件，便于开发者直接查看完整记录。 这条配置链路独立于 mailProvider 和 Hotmail 的接码模式。

4.3 状态广播

后台通过 runtime message 向 sidepanel 广播：

  • LOG_ENTRY
  • STEP_STATUS_CHANGED
  • DATA_UPDATED
  • AUTO_RUN_STATUS
  • ICLOUD_LOGIN_REQUIRED
  • ICLOUD_ALIASES_CHANGED

5. 内容脚本通信链路

5.1 READY 机制

content/utils.js 在脚本加载后会发送 CONTENT_SCRIPT_READY。

后台收到后会：

  • 注册当前来源对应的 tab
  • 标记 ready
  • 冲刷排队命令

5.2 队列与重试

background/tab-runtime.js 负责：

  • queueCommand
  • flushCommand
  • sendTabMessageWithTimeout
  • sendToContentScriptResilient
  • sendToMailContentScriptResilient

这保证了：

  • 页面切换导致脚本暂时失联时，后台不会立刻误判彻底失败
  • 邮箱页或注册页能在注入恢复后继续执行
  • 用户点击 Stop 后，标签完成等待、注入后的短暂延迟和内容脚本重试等待会尽快中断，不会因为底层轮询还在 sleep 而继续往下恢复

6. 手动步骤完整链路

Step 1

文件：

流程：

  1. 后台打开 ChatGPT 官网并复用/创建注册页标签
  2. 等待注册页内容脚本就绪（仅做连接与注入确认）
  3. 不在 Step 1 检测或点击注册入口
  4. 标记 Step 1 完成

补充：

  • 手动点击“跳过步骤 1”时，会级联将步骤 2~5 标记为跳过；其中已完成或正在运行的步骤不会被改写。

Step 2

文件：

流程：

  1. 解析本轮应使用的邮箱
  2. 打开或复用注册页
  3. 点击注册入口并提交邮箱
  4. 以当前邮箱先写入一条“停止（流程尚未完成）”的记录占位
  5. 等待邮箱提交后的真实落地页
  6. 如果进入密码页，则继续执行 Step 3
  7. 如果直接进入邮箱验证码页，则自动跳过 Step 3 并进入 Step 4

Step 3

文件：

流程：

  1. 生成或读取密码
  2. 更新运行态密码
  3. 记录账号快照
  4. 让内容脚本填写密码
  5. 内容脚本先上报 Step 3 完成信号
  6. 上报完成后再异步点击提交，避免页面跳转打断响应通道
  7. 延迟提交真正触发前会再次检查 Stop 状态，避免用户已停止时页面仍继续自动提交
  8. 后台在真正确认 Step 3 完成前，会额外检查提交后是否切换页面；如果出现认证页 Try again / 重试 页面，会先自动点击 重试 恢复，再继续后续链路

Step 4 / Step 7

文件：

这两步共享验证码主流程：

  1. 确定 provider
  2. 必要时重发验证码
  3. 轮询邮箱或 API
  4. 提取验证码
  5. 回填页面
  6. 若页面拒绝，则重试或回退

补充行为：

  • 2925 provider 会拉长单轮轮询窗口，并关闭 Step 4 / 8 的自动重发间隔，减少因邮件延迟过早判负。

  • Step 4 / 8 会在当前验证码步骤启动时固定一次邮件筛选时间窗；本步后续即使触发重新发送验证码，也继续沿用这一次启动时间作为筛选基准，不再随着重发时间前移。

  • 自动重新发送验证码次数现在使用 sidepanel 里的单一“验证码重发”配置；普通邮箱仍按 25 秒间隔节流，Hotmail / 2925 不走这个 25 秒间隔。Step 4 若启用先请求新验证码，会先消耗一次当前步骤的自动重发次数。

  • Auto 模式下，如果 Step 4 当前轮失败，后台会沿用当前邮箱回到 Step 1 重新开始当前轮，而不是立刻换邮箱开新尝试。

Step 5

文件：

流程：

  1. 生成随机姓名和生日
  2. 内容脚本填写资料并点击“完成帐户创建”
  3. 点击后立即上报 Step 5 完成，不再等待页面结果
  4. 自动运行在进入 Step 6 前仅额外等待当前页面加载完成，不再在 Step 5 阶段接管 ChatGPT 跳转或 onboarding 跳过

Step 6

文件：

流程：

  1. 等待登录前清理延迟
  2. 直接删除 ChatGPT / OpenAI cookies
  3. 必要时用 browsingData 补扫 cookies
  4. 完成后进入后续登录链路

Step 7

文件：

流程：

  1. 通过 CPA / SUB2API 刷新 OAuth 地址
  2. 打开最新 OAuth 链接
  3. 登录
  4. 确保真正进入验证码页
  5. 如果未进入验证码页，则按可恢复逻辑最多重试 3 次；但一旦当前失败已经明确进入 https://auth.openai.com/add-phone，则立即退出步骤 7 内部重试，不再继续第 2 / 3 次尝试
  6. 自动运行一旦进入步骤 7 之后的链路，若后续步骤报错且认证页未进入 https://auth.openai.com/add-phone，则统一回到步骤 7 重新开始授权流程
  7. CPA 回调阶段固定为步骤 9，不再支持“第七步回调”跳过步骤 7/8

Step 8

文件：

流程：

  1. 确认当前认证页已经进入登录验证码页
  2. 打开邮箱页或 API 轮询入口
  3. 轮询登录验证码
  4. 回填登录验证码
  5. 如遇邮箱轮询类失败，则按有限次数回到 Step 7 重试
  6. 获取到登录验证码后不再触发“刷新 OAuth 并重走 Step 7”的前置回放，直接在当前验证码页提交并继续进入 Step 9

Step 9

文件：

流程：

  1. 监听 localhost callback
  2. 准备 OAuth 同意页
  3. 尝试多轮点击“继续”
  4. 一旦捕获 localhost callback，写入状态并完成步骤

Step 10

文件：

流程：

  1. 校验 localhost callback 是否有效
  2. 判断是 CPA 还是 SUB2API
  3. 打开相应后台
  4. 提交回调地址
  5. 仅当出现精确成功徽标，且该徽标不是红色/错误态、页面上也没有同时可见的失败提示时，才判定成功
  6. 识别 认证失败:*、认证失败: timeout of 30000ms exceeded、回调 URL 提交失败: oauth flow is not pending 等失败提示并立即报错
  7. 完成平台侧验证
  8. 追加账号运行历史成功记录
  9. 做成功后的清理与标记

7. 邮箱与 provider 链路

7.1 2026-04-17 补充：Gmail / 2925 统一别名邮箱链路

本轮将 Gmail 与 2925 的注册邮箱逻辑统一收敛为“共享别名邮箱链路”：

  • 两者都先填写“基邮箱”
    • Gmail：name@gmail.com
    • 2925：name@2925.com
  • 两者都允许两种入口：
    • 点击侧边栏按钮自动生成完整注册邮箱
    • 直接在“注册邮箱”输入框中手动填写完整邮箱

当前行为约定：

  1. sidepanel 展示“别名基邮箱”输入框，并根据当前 provider 显示对应文案
  2. 点击 获取 / 生成 时：
    • Gmail 生成 name+tag@gmail.com
    • 2925 生成 name123456@2925.com
  3. Step 2 / Step 3 进入注册流程前，会先判断当前 state.email
    • 如果已经是与当前基邮箱兼容的完整邮箱，则直接复用
    • 如果为空或不兼容，则按当前 provider 重新生成
  4. 保存或执行 Step 3 时，如果手动填写的完整邮箱与当前 Gmail / 2925 基邮箱不兼容，sidepanel 会直接拦截
  5. auto-run fresh attempt reset 时，会保留：
    • gmailBaseEmail
    • mail2925BaseEmail

7.2 共享模块分工

  • managed-alias-utils.js 统一承接 Gmail / 2925 的：

    • 基邮箱解析
    • 完整邮箱兼容性判断
    • 别名邮箱生成
    • UI 文案输出

  • background/generated-email-helpers.js 在原有 Duck / Cloudflare / iCloud / Cloudflare Temp Email 生成链路之外，新增 Gmail / 2925 的共享生成接入。

  • background/signup-flow-helpers.js 负责在真正提交注册邮箱前做“复用已有完整邮箱 / 重新生成”的最终决策。

7.1 生成邮箱

文件：

支持：

  • Duck
  • Cloudflare
  • Cloudflare Temp Email
  • iCloud 隐私邮箱

7.2 Hotmail

组成：

模式：

  • API 对接
  • 本地 helper

补充：

  • 本地 helper 除了收信与验证码读取，还提供邮箱记录 JSON 快照同步接口。
  • 账号运行历史本地同步由独立配置控制，不再绑定 Hotmail 的本地助手模式。

7.3 LuckMail

组成：

7.4 iCloud

组成：

8. 自动运行完整链路

文件：

流程：

  1. 读取总轮数与模式
  2. 为本轮自动流程分配唯一 autoRunSessionId
  3. 计算是否从中断点继续
  4. 每轮执行前重置必要运行态
  5. 执行 runAutoSequenceFromStep
    • 步骤 7 内部仍保留登录态恢复的有限重试，但 add-phone / 手机号页 属于立即跳出的不可重试错误
    • 一旦进入步骤 7~10，遇到普通报错且认证流程未进入 add-phone，则自动回到步骤 7 无限重开
    • 如果是手动停止，则立即退出自动流程，不会再触发“回到步骤 7 重开”
  6. 如果失败，根据设置决定：
    • 立即停止
    • 当前轮重试
    • 下一轮继续
  7. 当前轮最终失败时，写入邮箱记录，并在自动重试链路中累计重试次数
    • 手动停止与自动停止会写入“停止”状态（若后续同邮箱成功/失败，会被覆盖为最新状态）
  8. 如果配置了线程间隔，则挂计时计划；计时计划会带上当前 autoRunSessionId
  9. 旧 timer / 旧 alarm / 旧恢复入口只有在 session 仍有效时才允许恢复执行；Stop 会立即使当前 session 失效，防止“停止后旧倒计时又把流程重新拉起”
  10. 所有轮次结束后输出汇总，并清空当前 session 标识

9. 新增功能时最容易漏掉的地方

新增步骤

必须同时检查：

  1. data/step-definitions.js
  2. background/steps
  3. background/steps/registry.js
  4. 自动运行链路是否需要纳入
  5. Step 状态传播和侧边栏展示是否需要适配
  6. 测试是否要补

新增 provider

必须同时检查：

  1. provider 纯工具
  2. 后台 provider 调度分支
  3. 侧边栏配置项
  4. 动态邮箱生成逻辑
  5. Step 4 / 7 的验证码流
  6. 成功收尾逻辑

新增配置项

必须同时检查：

  1. PERSISTED_SETTING_DEFAULTS
  2. normalizePersistentSettingValue
  3. 导入导出逻辑
  4. sidepanel 表单与状态恢复
  5. 是否错误挂靠到无关 provider / manager 配置下
  6. 结构文档 / 开发规范是否需要更新

10. 文档联动规则

修改下列内容时，必须同步更新文档：

2026-04 链路补充：认证页共享恢复

  • 新增共享恢复层：content/auth-page-recovery.js。
  • Step 4 在等待注册验证码页时，如果命中认证页 Try again / 重试 页，会先自动点击 重试 恢复，再继续回到密码页重提和验证码页确认流程。
  • Step 7 在识别到登录超时报错页时，会先尝试自动点击 重试 恢复当前页面，再按原有有限重试逻辑重新执行整步。
  • Step 9 在点击 OAuth 同意页 继续 后，会额外检查是否进入认证页重试页；若命中则先自动点击 重试 恢复，再重新执行当前轮的 继续 点击。
Reference in New Issue View Git Blame Copy Permalink