Merge branch 'master' into codex/upstream-pr

2026-04-20 16:04:13 +08:00
parent 01477d6bd0 8dd6daccd1
commit 5318a0975b
44 changed files with 4677 additions and 346 deletions
@@ -37,7 +37,8 @@
 - 向后台发送命令
 - 接收后台广播并更新 UI
 - 动态渲染步骤列表
- 顶部提供一个临时 `贡献` 按钮，用于直接打开账号贡献上传页
+- 管理顶部“贡献”按钮与贡献模式主面板；贡献模式本身是 sidepanel 的运行态 UI 模式，不是新的 `panelMode` 来源
+- 在贡献模式下复用同一套主自动流程启动，并在面板内展示贡献链路的 `OAUTH / 回调 / 总状态` 三块实时状态
 - 在日志区通过“记录”按钮打开独立的邮箱记录覆盖层，并展示成功/失败/停止/重试统计与分页列表
 - 查询 GitHub Releases 并展示更新卡片；当前更新服务会区分 `Pro` 与 legacy `v` 两个版本族，排序时优先保持版本族语义一致，同时会在读取缓存后重新排序，避免旧缓存把 `v` 版本误显示为比 `Pro` 更新

@@ -119,6 +120,15 @@
 保存运行态：

 - 当前步骤状态
+- 当前 sidepanel UI 模式 `contributionMode`
+- 贡献 OAuth 会话字段：
+  - `contributionSessionId`
+  - `contributionAuthUrl`
+  - `contributionAuthState`
+  - `contributionCallbackUrl`
+  - `contributionStatus`
+  - `contributionStatusMessage`
+  - `contributionLastPollAt`
 - OAuth 链接
 - 当前邮箱 / 密码
 - 第 8 步固定的验证码页显示邮箱 `step8VerificationTargetEmail`
@@ -147,6 +157,11 @@
 - 账号运行历史 `accountRunHistory`（以邮箱为主键，保存该邮箱最近一次状态：成功/失败/停止）
 - 账号运行历史本地同步开关与 helper 地址

+注意：
+
+- `contributionMode` 不属于持久配置，也不参与导入/导出；它只存在于运行态
+- `panelMode` 仍然只表示 `cpa | sub2api` 来源，不能把贡献模式实现成新的来源枚举
+
 当启用了独立的账号运行历史本地同步配置时，账号运行历史会通过 [scripts/hotmail_helper.py](c:/Users/projectf/Downloads/codex注册扩展/scripts/hotmail_helper.py) 整体同步写入 `data/account-run-history.json` 快照文件，便于开发者直接查看完整记录。
 这条配置链路独立于 `mailProvider` 和 Hotmail 的接码模式。

@@ -161,22 +176,33 @@
 - `ICLOUD_LOGIN_REQUIRED`
 - `ICLOUD_ALIASES_CHANGED`

-### 4.4 临时贡献入口
+### 4.4 贡献模式链路

-当前 `dev` 分支里的贡献能力先以“临时上传入口”形式提供，而不是完整接入主自动链。
-
-流程：
+贡献模式的目标不是新增一个 provider，而是在 sidepanel 内开启一套“贡献账号”专用 UI，并把公开贡献服务并进原有 10 步主链：

 1. 用户点击顶部 `贡献`
-2. 扩展调用统一的新标签页打开逻辑
-3. 浏览器直接打开 `https://apikey.qzz.io/`
+2. sidepanel 直接通过 `SET_CONTRIBUTION_MODE` 切换运行态，不再弹确认窗口
+3. 进入贡献模式后会强制 `panelMode = cpa`，并临时清空运行态 `customPassword`、禁用运行态账号记录快照同步
+4. sidepanel 隐藏 CPA 管理地址、管理密钥、SUB2API 配置、自定义密码、本地同步等普通模式配置，并禁用来源选择、配置菜单和记录入口
+5. 用户点击 `开始贡献` 后，不再单独走一条旁路 OAuth 流程，而是直接复用顶部 `自动` 的同一套主自动流
+6. 步骤 1~6 仍按原来的注册自动化执行
+7. 当主流程进入步骤 7 时，后台改为调用公开接口 `POST https://apikey.qzz.io/oauth/api/start` 申请贡献登录地址，而不是去 CPA / SUB2API 面板刷新 OAuth
+8. 步骤 7 拿到 `session_id / auth_url / state` 后，继续沿用原有登录链路进入授权页
+9. 步骤 9 仍负责捕获 localhost callback；贡献模式下后台也会持续监听导航变化，必要时提前兼容处理 callback
+10. 步骤 10 在贡献模式下不再打开 CPA 管理页，而是围绕公开贡献会话做 callback 提交兼容和最终状态确认；当状态进入 `auto_approved / auto_rejected / manual_review_required / expired / error` 时结束
+11. 当前服务端如果返回“无需手动提交 callback”，扩展会把它视为兼容成功态，而不是报错
+12. `已有认证文件？前往上传` 继续打开 `https://apikey.qzz.io/`
+13. `退出贡献模式` 会清理贡献会话相关运行态，`重置` 只重置主流程状态，不会自动退出贡献模式

-边界：
+这条链路的关键边界是：

- 当前这颗按钮不参与 1~10 步主流程
- 当前这颗按钮不调用后台管理接口
- 当前这颗按钮不保存额外运行态
- 当步骤正在运行或自动流程处于锁定状态时，按钮会禁用，避免和主流程冲突
+- 扩展会调用公开贡献 API，但这条调用被折叠进主 10 步自动链，而不是额外分出一条独立“贡献 OAuth 小流程”
+- 扩展不会保存 token
+- 扩展不会持有任何管理密钥
+- 扩展代码中不能直接调用 `/v0/management/*`
+- 扩展不会直接访问生产管理面或生产 auth-dir
+- 安全边界仍然在服务端；扩展只负责公开 OAuth 贡献前端流程
+- 退出贡献模式后，要恢复普通模式 UI，并恢复持久配置中的自定义密码/本地同步偏好

 ## 5. 内容脚本通信链路

@@ -257,7 +283,7 @@
 5. 内容脚本先上报 Step 3 完成信号
 6. 上报完成后再异步点击提交，避免页面跳转打断响应通道
 7. 延迟提交真正触发前会再次检查 Stop 状态，避免用户已停止时页面仍继续自动提交
-8. 后台在真正确认 Step 3 完成前，会额外检查提交后是否切换页面；如果出现认证页 `Try again / 重试` 页面，会先通过共享恢复逻辑最多自动点击 5 次 `重试` 尝试恢复，再继续后续链路
+8. 后台在真正确认 Step 3 完成前，会额外检查提交后是否切换页面；如果出现认证页 `Try again / 重试` 页面，或 `/email-verification` 上的 `405 / Route Error` 重试页，会先通过共享恢复逻辑最多自动点击 5 次 `重试` 尝试恢复，再继续后续链路

 ### Step 4 / Step 8

@@ -278,12 +304,11 @@

 补充行为：

- `2925` provider 会拉长单轮轮询窗口，并关闭 Step 4 / 8 的自动重发间隔，减少因邮件延迟过早判负。
- 普通邮箱仍会携带 `filterAfterTimestamp` 做时间窗筛选；`2925` 不再依赖时间窗，而是以“当前收件箱快照 + 刷新后新增邮件”作为优先匹配依据。
+- `2925` provider 会关闭 Step 4 / 8 的自动重发间隔 25 秒节流；每次“重新发送验证码”之间，会在邮箱页内部执行一轮固定 15 次的刷新轮询，不再因 OAuth 剩余时间预算而缩短。
+- 普通邮箱仍会携带 `filterAfterTimestamp` 做时间窗筛选；`2925` 当前既不依赖时间窗，也不再做“新旧邮件快照差集”比较，而是每次刷新后直接遍历当前列表中的匹配邮件。
 - 自动重新发送验证码次数现在使用 sidepanel 里的单一“验证码重发”配置；普通邮箱仍按 25 秒间隔节流，Hotmail / 2925 不走这个 25 秒间隔。Step 4 若启用先请求新验证码，会先消耗一次当前步骤的自动重发次数。
- 验证码提交重试上限当前为 7 次；页面明确拒绝验证码时，会在上限内继续拉取新验证码并重提。
- `2925` 内容脚本会把每次成功读到的目标邮件立即删除；同一验证码步骤启动后，试过的验证码会按“步骤 ID + 启动时间”隔离缓存，不会在本次步骤里重复提交。
- `2925` 在连续 3 轮未发现新增邮件后，会回退检查列表里现存的匹配邮件；每轮轮询之间只刷新 1 次收件箱列表。
+- 验证码提交重试上限当前为 15 次；页面明确拒绝验证码时，会在上限内继续拉取新验证码并重提。
+- `2925` 内容脚本会把每一封实际打开检测的邮件立即删除；同一验证码步骤启动后，试过的验证码会按“步骤 ID + 启动时间”隔离缓存，不会在本次步骤里重复提交；如果再次遇到相同验证码，对应邮件也会在读取后立即删除，避免后续反复打开。
 - `2925` 当前不再对邮件里的收件邮箱做比对，只要邮件内容命中 ChatGPT / OpenAI 验证码过滤条件，就会尝试该邮件。
 - 当验证码最终提交成功后，后台会异步向 2925 邮箱页发送 `DELETE_ALL_EMAILS`，执行“全选 + 删除”清理剩余邮件，不阻塞主流程。

@@ -326,12 +351,17 @@

 1. 通过 CPA / SUB2API 刷新 OAuth 地址
 2. 打开最新 OAuth 链接
-3. 登录
+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

+贡献模式补充：
+
+- 贡献模式下，步骤 7 不再从 CPA / SUB2API 面板刷新 OAuth，而是直接调用公开贡献接口 `/oauth/api/start`
+- 贡献接口返回的 `auth_url` 会写回运行态 `oauthUrl`，后续步骤 7 / 8 / 9 继续复用现有授权链路
+
 ### Step 8

 文件：
@@ -384,6 +414,12 @@
 8. 追加账号运行历史成功记录
 9. 做成功后的清理与标记

+贡献模式补充：
+
+- 贡献模式下，步骤 10 不再打开 CPA 管理页
+- 步骤 10 会先尝试提交已捕获的 callback URL，随后轮询公开贡献状态，直到进入最终态
+- `auto_approved` 与 `manual_review_required` 视为主流程完成；`auto_rejected / expired / error` 视为当前轮失败
+
 ## 7. 邮箱与 provider 链路

 ### 7.1 2026-04-17 补充：Gmail / 2925 统一别名邮箱链路
@@ -561,7 +597,8 @@
 ## 2026-04 链路补充：认证页共享恢复

 - 新增共享恢复层：`content/auth-page-recovery.js`。
- Step 4 在等待注册验证码页时，如果命中认证页 `Try again / 重试` 页，会先通过共享恢复逻辑最多自动点击 5 次 `重试` 尝试恢复，再继续回到密码页重提和验证码页确认流程。
+- Step 4 在等待注册验证码页时，如果命中认证页 `Try again / 重试` 页，或 `/email-verification` 上的 `405 / Route Error` 重试页，会先通过共享恢复逻辑最多自动点击 5 次 `重试` 尝试恢复，再继续回到密码页重提和验证码页确认流程。
+- 但如果 Step 4 的认证重试页正文中出现 `user_already_exists`，则会直接视为“当前用户已存在”：不点击 `重试`，不再回到步骤 1 重开当前轮，而是立即结束当前轮；开启自动重试时直接进入下一轮。
 - Step 7 在识别到登录超时报错页时，会先通过共享恢复逻辑最多自动点击 5 次 `重试` 尝试恢复当前页面；若仍未恢复，则按原有可恢复失败逻辑重跑 Step 7。
 - Step 8 如果发现认证页已经进入登录超时报错/重试页，会直接报错并回到 Step 7 重新开始，而不是在 Step 8 内部点击 `重试`。
 - 任意认证页重试页如果正文中出现 `max_check_attempts`，会被视为 Cloudflare 风控触发：后台立刻完全停止流程，侧边栏会复用现有确认弹窗提示等待 15~30 分钟后再试，避免继续刷新或反复重试加重风控，确认按钮显示为“我知道了”。