chendeben/codex-oauth-automation-extension

# 项目完整链路说明

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

使用建议：

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

文件：

流程：

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

补充：

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

Step 2

文件：

background/steps/submit-signup-email.js

流程：

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

Step 3

文件：

background/steps/fill-password.js

流程：

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

Step 4 / Step 7

文件：

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

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

补充行为：

2925 provider 会拉长单轮轮询窗口，并关闭 Step 4 / 8 的自动重发间隔，减少因邮件延迟过早判负。
Step 4 / 8 会在当前验证码步骤启动时固定一次邮件筛选时间窗；本步后续即使触发重新发送验证码，也继续沿用这一次启动时间作为筛选基准，不再随着重发时间前移。
自动重新发送验证码次数现在使用 sidepanel 里的单一“验证码重发”配置；普通邮箱仍按 25 秒间隔节流，Hotmail / 2925 不走这个 25 秒间隔。Step 4 若启用先请求新验证码，会先消耗一次当前步骤的自动重发次数。
Auto 模式下，如果 Step 4 当前轮失败，后台会沿用当前邮箱回到 Step 1 重新开始当前轮，而不是立刻换邮箱开新尝试。

Step 5

文件：

background/steps/fill-profile.js

流程：

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

Step 6

文件：

background/steps/clear-login-cookies.js

流程：

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

Step 7

文件：

background/steps/oauth-login.js

流程：

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

Step 8

文件：

background/steps/fetch-login-code.js

流程：

确认当前认证页已经进入登录验证码页
打开邮箱页或 API 轮询入口
轮询登录验证码
回填登录验证码
如果登录验证码提交后页面进入 add-phone / 手机号页，则立即判为 fatal 错误，不再把步骤 8 视为成功
如遇邮箱轮询类失败或显式的 STEP8_RESTART_STEP7 恢复错误，则按有限次数回到 Step 7 重试
获取到登录验证码后不再触发“刷新 OAuth 并重走 Step 7”的前置回放，直接在当前验证码页提交并继续进入 Step 9

Step 9

文件：

background/steps/confirm-oauth.js

流程：

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

Step 10

文件：

background/steps/platform-verify.js

流程：

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

7. 邮箱与 provider 链路

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

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

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

当前行为约定：

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

文件：

background/generated-email-helpers.js

支持：

Duck
Cloudflare
Cloudflare Temp Email
iCloud 隐私邮箱

7.2 Hotmail

组成：

模式：

API 对接
本地 helper

补充：

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

7.3 LuckMail

组成：

luckmail-utils.js
LuckMail 相关后台领域逻辑仍在 background.js

7.4 iCloud

组成：

8. 自动运行完整链路

文件：

background/auto-run-controller.js

流程：

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

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

新增步骤

必须同时检查：

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

新增 provider

必须同时检查：

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

新增配置项

必须同时检查：

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

10. 文档联动规则

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

文件结构变更
更新项目文件结构说明.md
运行链路变更
更新项目完整链路说明.md
规范、边界、步骤接入方式变更
更新项目开发规范（AI协作）.md

2026-04 链路补充：认证页共享恢复
新增共享恢复层：content/auth-page-recovery.js。
Step 4 在等待注册验证码页时，如果命中认证页 Try again / 重试 页，会先自动点击 重试 恢复，再继续回到密码页重提和验证码页确认流程。
Step 7 在识别到登录超时报错页时，不会在当前步骤内部点击 重试，而是直接返回可恢复失败，交给后续链路回到 Step 7 重跑。
Step 8 如果发现认证页已经进入登录超时报错/重试页，会直接报错并回到 Step 7 重新开始，而不是在 Step 8 内部点击 重试。
Step 9 在点击 OAuth 同意页 继续 后，会额外检查是否进入认证页重试页；若命中则先自动点击 重试 恢复，再重新执行当前轮的 继续 点击。

项目完整链路说明.md 19 KB Permalink History Raw

1. 项目目标

2. 核心运行参与者

2.1 Sidepanel

2.2 Background Service Worker

2.3 Content Scripts

2.4 Helper / Utils / Provider Logic

3. 入口与装配关系

3.1 扩展入口

3.2 背景层装配

3.3 步骤注册

4. 状态与存储链路

4.1 chrome.storage.session

4.2 chrome.storage.local

4.3 状态广播

5. 内容脚本通信链路

5.1 READY 机制

5.2 队列与重试

6. 手动步骤完整链路

Step 1

Step 2

Step 3

Step 4 / Step 7

Step 5

Step 6

Step 7

Step 8

Step 9

Step 10

7. 邮箱与 provider 链路

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

7.2 共享模块分工

7.1 生成邮箱

7.2 Hotmail

7.3 LuckMail

7.4 iCloud

8. 自动运行完整链路

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

新增步骤

新增 provider

新增配置项

10. 文档联动规则

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

项目完整链路说明.md 19 KB

Permalink History Raw

4.1 `chrome.storage.session`

4.2 `chrome.storage.local`