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

12 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 回调地址
  • 自动运行轮次信息
  • 标签注册表
  • 最近打开的来源地址
  • LuckMail 当前运行时选择

4.2 chrome.storage.local

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

  • CPA / SUB2API 配置
  • 邮箱 provider 配置
  • Hotmail 账号池
  • Cloudflare / Temp Email 设置
  • iCloud 相关偏好
  • LuckMail API 配置
  • 自动运行默认配置
  • 账号运行历史 accountRunHistory
  • 账号运行历史 txt 留档开关与 helper 地址

当启用了独立的账号运行历史 txt 留档配置时，账号运行历史会通过 scripts/hotmail_helper.py 追加写入 data/account-run-history.txt 文本文件，便于离线留档。 这条配置链路独立于 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

这保证了：

  • 页面切换导致脚本暂时失联时，后台不会立刻误判彻底失败
  • 邮箱页或注册页能在注入恢复后继续执行

6. 手动步骤完整链路

Step 1

文件：

流程：

  1. 后台打开 ChatGPT 官网
  2. 等待注册入口页内容脚本就绪
  3. 标记 Step 1 完成

Step 2

文件：

流程：

  1. 解析本轮应使用的邮箱
  2. 打开或复用注册页
  3. 点击注册入口并提交邮箱
  4. 等待跳转到密码页

Step 3

文件：

流程：

  1. 生成或读取密码
  2. 更新运行态密码
  3. 记录账号快照
  4. 让内容脚本填写密码并继续

Step 4 / Step 7

文件：

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

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

补充行为：

  • 2925 provider 会拉长单轮轮询窗口，并关闭 Step 4 / 7 的自动重发间隔，减少因邮件延迟过早判负。
  • CPA 模式下，Step 7 在真正回填登录验证码前，会先刷新最新 OAuth 地址并快速重走一次 Step 6，降低验证码等待过久导致 OAuth 过期的概率。

Step 5

文件：

流程：

  1. 生成随机姓名和生日
  2. 内容脚本填写资料
  3. 如果页面跳到 ChatGPT onboarding，则执行跳过链路

Step 6

文件：

流程：

  1. 清理登录前 Cookie
  2. 通过 CPA / SUB2API 刷新 OAuth 地址
  3. 打开最新 OAuth 链接
  4. 登录
  5. 确保真正进入验证码页
  6. 如果未进入验证码页，则按可恢复逻辑最多重试 3 次

Step 8

文件：

流程：

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

Step 9

文件：

流程：

  1. 校验 localhost callback 是否有效
  2. 判断是 CPA 还是 SUB2API
  3. 打开相应后台
  4. 提交回调地址
  5. 完成平台侧验证
  6. 追加账号运行历史成功记录
  7. 做成功后的清理与标记

7. 邮箱与 provider 链路

7.1 生成邮箱

文件：

支持：

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

7.2 Hotmail

组成：

模式：

  • API 对接
  • 本地 helper

补充：

  • 本地 helper 除了收信与验证码读取，还提供账号运行历史文本追加接口。
  • 账号运行历史 txt 留档由独立配置控制，不再绑定 Hotmail 的本地助手模式。

7.3 LuckMail

组成：

7.4 iCloud

组成：

8. 自动运行完整链路

文件：

流程：

  1. 读取总轮数与模式
  2. 计算是否从中断点继续
  3. 每轮执行前重置必要运行态
  4. 执行 runAutoSequenceFromStep
  5. 如果失败，根据设置决定：
    • 立即停止
    • 当前轮重试
    • 下一轮继续
  6. 当前轮最终失败或被停止时，追加账号运行历史记录
  7. 如果配置了线程间隔，则挂计时计划
  8. 所有轮次结束后输出汇总

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. 文档联动规则

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

Reference in New Issue View Git Blame Copy Permalink