Hermes/FlowPilot
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

feat: 添加项目完整链路说明和开发规范文档

Browse Source
This commit is contained in:
QLHazyCoder
2026-04-17 02:01:13 +08:00
parent 3071f94f7c
commit e48941806f
5 changed files with 775 additions and 432 deletions
Download Patch File Download Diff File Expand all files Collapse all files
项目完整链路说明.md
+394
View File
@@ -0,0 +1,394 @@
# 项目完整链路说明
本文档面向 AI 与开发者，目标是让阅读者在最短时间内理解“项目做什么、怎么跑、数据怎么流、功能链路怎么串”，从而在新增功能时不漏逻辑、不误改边界。
使用建议：
1. 先阅读 [项目文件结构说明.md](c:/Users/projectf/Downloads/codex注册扩展/项目文件结构说明.md)
2. 再阅读本文
3. 最后阅读 [项目开发规范（AI协作）.md](c:/Users/projectf/Downloads/codex注册扩展/项目开发规范（AI协作）.md)
## 1. 项目目标
这是一个 Chrome 扩展，用于自动执行一整套 OpenAI / ChatGPT OAuth 注册与登录流程。
它的核心价值不是“打开一个页面点几个按钮”，而是把下面这些环节串成一条完整可恢复的自动化链路：
- 生成或选取注册邮箱
- 打开 ChatGPT / OpenAI 注册入口
- 提交邮箱和密码
- 轮询注册验证码
- 填写姓名和生日
- 刷新 OAuth 链接并登录
- 轮询登录验证码
- 自动确认 OAuth 同意页
- 把 localhost 回调提交到 CPA 或 SUB2API
## 2. 核心运行参与者
### 2.1 Sidepanel
[sidepanel/sidepanel.html](c:/Users/projectf/Downloads/codex注册扩展/sidepanel/sidepanel.html) + [sidepanel/sidepanel.js](c:/Users/projectf/Downloads/codex注册扩展/sidepanel/sidepanel.js)
职责：
- 展示配置与步骤状态
- 接收用户输入
- 向后台发送命令
- 接收后台广播并更新 UI
- 动态渲染步骤列表
### 2.2 Background Service Worker
[background.js](c:/Users/projectf/Downloads/codex注册扩展/background.js)
职责：
- 扩展后台入口
- 装配所有模块
- 统一承接 runtime message
- 协调步骤执行
- 管理状态、自动运行、标签页与内容脚本通信
### 2.3 Content Scripts
[content](c:/Users/projectf/Downloads/codex注册扩展/content)
职责：
- 在目标网页上执行 DOM 交互
- 读取邮件内容或页面状态
- 将步骤成功/失败状态上报给后台
### 2.4 Helper / Utils / Provider Logic
分布在根目录和 `background/` 下。
职责：
- 抽离第三方邮箱 provider 的纯逻辑
- 抽离邮件匹配与验证码提取
- 抽离共享验证码流程、自动运行流程和运行时基础设施
## 3. 入口与装配关系
### 3.1 扩展入口
[manifest.json](c:/Users/projectf/Downloads/codex注册扩展/manifest.json) 声明：
- `background.service_worker = background.js`
- `side_panel.default_path = sidepanel/sidepanel.html`
- 多组内容脚本自动注入规则
### 3.2 背景层装配
[background.js](c:/Users/projectf/Downloads/codex注册扩展/background.js) 通过 `importScripts(...)` 依次加载：
- 共享数据与纯工具
- provider 纯逻辑
- 后台桥接层
- 后台共享流程层
- 后台运行时与消息路由层
- 步骤执行模块
因此 `background.js` 现在更像：
- 常量定义中心
- 模块依赖装配器
- 极少量保留函数
- Chrome 事件挂接入口
### 3.3 步骤注册
[data/step-definitions.js](c:/Users/projectf/Downloads/codex注册扩展/data/step-definitions.js) 提供共享步骤元数据。
[background/steps/registry.js](c:/Users/projectf/Downloads/codex注册扩展/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 配置
- 自动运行默认配置
### 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](c:/Users/projectf/Downloads/codex注册扩展/content/utils.js) 在脚本加载后会发送 `CONTENT_SCRIPT_READY`。
后台收到后会：
- 注册当前来源对应的 tab
- 标记 ready
- 冲刷排队命令
### 5.2 队列与重试
[background/tab-runtime.js](c:/Users/projectf/Downloads/codex注册扩展/background/tab-runtime.js) 负责：
- `queueCommand`
- `flushCommand`
- `sendTabMessageWithTimeout`
- `sendToContentScriptResilient`
- `sendToMailContentScriptResilient`
这保证了：
- 页面切换导致脚本暂时失联时，后台不会立刻误判彻底失败
- 邮箱页或注册页能在注入恢复后继续执行
## 6. 手动步骤完整链路
### Step 1
文件：
- [background/steps/open-chatgpt.js](c:/Users/projectf/Downloads/codex注册扩展/background/steps/open-chatgpt.js)
- [content/signup-page.js](c:/Users/projectf/Downloads/codex注册扩展/content/signup-page.js)
流程：
1. 后台打开 ChatGPT 官网
2. 等待注册入口页内容脚本就绪
3. 标记 Step 1 完成
### Step 2
文件：
- [background/steps/submit-signup-email.js](c:/Users/projectf/Downloads/codex注册扩展/background/steps/submit-signup-email.js)
流程：
1. 解析本轮应使用的邮箱
2. 打开或复用注册页
3. 点击注册入口并提交邮箱
4. 等待跳转到密码页
### Step 3
文件：
- [background/steps/fill-password.js](c:/Users/projectf/Downloads/codex注册扩展/background/steps/fill-password.js)
流程：
1. 生成或读取密码
2. 更新运行态密码
3. 记录账号快照
4. 让内容脚本填写密码并继续
### Step 4 / Step 7
文件：
- [background/steps/fetch-signup-code.js](c:/Users/projectf/Downloads/codex注册扩展/background/steps/fetch-signup-code.js)
- [background/steps/fetch-login-code.js](c:/Users/projectf/Downloads/codex注册扩展/background/steps/fetch-login-code.js)
- [background/verification-flow.js](c:/Users/projectf/Downloads/codex注册扩展/background/verification-flow.js)
这两步共享验证码主流程：
1. 确定 provider
2. 必要时重发验证码
3. 轮询邮箱或 API
4. 提取验证码
5. 回填页面
6. 若页面拒绝，则重试或回退
### Step 5
文件：
- [background/steps/fill-profile.js](c:/Users/projectf/Downloads/codex注册扩展/background/steps/fill-profile.js)
流程：
1. 生成随机姓名和生日
2. 内容脚本填写资料
3. 如果页面跳到 ChatGPT onboarding，则执行跳过链路
### Step 6
文件：
- [background/steps/oauth-login.js](c:/Users/projectf/Downloads/codex注册扩展/background/steps/oauth-login.js)
流程：
1. 清理登录前 Cookie
2. 通过 CPA / SUB2API 刷新 OAuth 地址
3. 打开最新 OAuth 链接
4. 登录
5. 确保真正进入验证码页
6. 如果未进入验证码页，则按可恢复逻辑重试
### Step 8
文件：
- [background/steps/confirm-oauth.js](c:/Users/projectf/Downloads/codex注册扩展/background/steps/confirm-oauth.js)
流程：
1. 监听 localhost callback
2. 准备 OAuth 同意页
3. 尝试多轮点击“继续”
4. 一旦捕获 localhost callback，写入状态并完成步骤
### Step 9
文件：
- [background/steps/platform-verify.js](c:/Users/projectf/Downloads/codex注册扩展/background/steps/platform-verify.js)
流程：
1. 校验 localhost callback 是否有效
2. 判断是 CPA 还是 SUB2API
3. 打开相应后台
4. 提交回调地址
5. 完成平台侧验证
6. 做成功后的清理与标记
## 7. 邮箱与 provider 链路
### 7.1 生成邮箱
文件：
- [background/generated-email-helpers.js](c:/Users/projectf/Downloads/codex注册扩展/background/generated-email-helpers.js)
支持：
- Duck
- Cloudflare
- Cloudflare Temp Email
- iCloud 隐私邮箱
### 7.2 Hotmail
组成：
- [hotmail-utils.js](c:/Users/projectf/Downloads/codex注册扩展/hotmail-utils.js)
- [microsoft-email.js](c:/Users/projectf/Downloads/codex注册扩展/microsoft-email.js)
- [scripts/hotmail_helper.py](c:/Users/projectf/Downloads/codex注册扩展/scripts/hotmail_helper.py)
模式：
- API 对接
- 本地 helper
### 7.3 LuckMail
组成：
- [luckmail-utils.js](c:/Users/projectf/Downloads/codex注册扩展/luckmail-utils.js)
- LuckMail 相关后台领域逻辑仍在 [background.js](c:/Users/projectf/Downloads/codex注册扩展/background.js)
### 7.4 iCloud
组成：
- [icloud-utils.js](c:/Users/projectf/Downloads/codex注册扩展/icloud-utils.js)
- [content/icloud-mail.js](c:/Users/projectf/Downloads/codex注册扩展/content/icloud-mail.js)
## 8. 自动运行完整链路
文件：
- [background/auto-run-controller.js](c:/Users/projectf/Downloads/codex注册扩展/background/auto-run-controller.js)
流程：
1. 读取总轮数与模式
2. 计算是否从中断点继续
3. 每轮执行前重置必要运行态
4. 执行 `runAutoSequenceFromStep`
5. 如果失败，根据设置决定：
- 立即停止
- 当前轮重试
- 下一轮继续
6. 如果配置了线程间隔，则挂计时计划
7. 所有轮次结束后输出汇总
## 9. 新增功能时最容易漏掉的地方
### 新增步骤
必须同时检查：
1. [data/step-definitions.js](c:/Users/projectf/Downloads/codex注册扩展/data/step-definitions.js)
2. [background/steps](c:/Users/projectf/Downloads/codex注册扩展/background/steps)
3. [background/steps/registry.js](c:/Users/projectf/Downloads/codex注册扩展/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. 结构文档 / 开发规范是否需要更新
## 10. 文档联动规则
修改下列内容时，必须同步更新文档：
- 文件结构变更
更新 [项目文件结构说明.md](c:/Users/projectf/Downloads/codex注册扩展/项目文件结构说明.md)
- 运行链路变更
更新 [项目完整链路说明.md](c:/Users/projectf/Downloads/codex注册扩展/项目完整链路说明.md)
- 规范、边界、步骤接入方式变更
更新 [项目开发规范（AI协作）.md](c:/Users/projectf/Downloads/codex注册扩展/项目开发规范（AI协作）.md)