Hermes/FlowPilot
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
700a9295703caab3a4bd5a8cb36d0e3fc216ca1b
FlowPilot/项目文件结构说明.md
T
QLHazyCoder 700a929570 feat: support Cloud Mail email provider 
- Merge the latest dev branch into PR #212 for a clean dev-targeted review base.

- Add Cloud Mail/SkyMail provider support for email generation and verification-code polling.

- Move Cloud Mail runtime logic into a dedicated background module and add docs plus regression tests.
2026-05-08 17:40:41 +08:00

273 lines
46 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# 项目文件结构说明
本文档列出当前仓库中所有“非忽略文件”，并说明每个文件的作用。
不纳入本清单的忽略目录：
- `.github/`
- `_metadata/`
- `docs/md/`
- `.vscode/`
- `.git/`
更新规则：
- 新增、删除、重命名非忽略文件后，必须同步更新本文件。
- 如果文件职责发生明显变化，也必须同步更新本文件中的说明。
- 本文档不保留“增量补充”“结构补充”一类追加章节；结构变化时，直接更新对应文件条目与职责说明。
## 根目录
- `.gitignore`：定义仓库忽略规则，当前忽略 `docs/md/`、`.github/`、`_metadata/`、`.vscode/` 等目录。
- `LICENSE`：项目许可证文件。
- `README.md`：面向使用者的项目介绍、安装说明、能力清单与操作指引。
- `background.js`：扩展后台 Service Worker 入口壳，负责模块装配、初始化、全局常量、少量保留的领域函数与运行入口；当前新增 `oauthFlowTimeoutEnabled` 持久化配置，并统一承接 OAuth 授权后链总预算开关与剩余预算计算。
- `cloudmail-utils.js`：Cloud Mail / SkyMail 相关的纯工具函数，负责 API 地址、域名、鉴权头、邮件列表响应与邮件正文归一化。
- `cloudflare-temp-email-utils.js`：Cloudflare Temp Email 相关的纯工具函数，负责 URL、域名、邮件内容与 MIME 数据归一化。
- `gopay-utils.js`：GoPay / GPC Plus 支付相关纯工具函数，负责支付方式归一化、GoPay 手机号/OTP/PIN 归一化、GPC API 地址归一化、API Key 请求头、任务创建/查询/OTP/PIN/停止 URL 与余额响应解析。
- `hotmail-utils.js`：Hotmail 账号与验证码提取相关的纯工具函数，负责账号筛选、验证码匹配、第三方接口数据归一化。
- `icloud-utils.js`：iCloud 隐私邮箱相关的纯工具函数，负责 host、别名列表、保留状态、已用状态等归一化。
- `luckmail-utils.js`：LuckMail 相关的纯工具函数，负责邮箱购买记录、标签、邮件 cursor、验证码匹配等归一化。
- `mail-provider-utils.js`：网页邮箱 provider 配置纯工具，负责 `163 / 163 VIP / 126 / QQ / Inbucket / Hotmail` 的基础归一化与页面入口配置，并统一承接 iCloud 转发收码目标邮箱 provider 的归一化、选项列表和收码入口配置。
- `mail2925-utils.js`：2925 账号池相关的纯工具函数，负责账号归一化、冷却期判断、可用账号挑选、批量导入解析与列表更新。
- `managed-alias-utils.js`：共享 Gmail / 2925 的别名邮箱规则，负责解析基邮箱、校验“当前完整注册邮箱”是否仍与基邮箱兼容、生成 Gmail `+tag` 与 2925 随机后缀邮箱，并输出 sidepanel 可复用的 UI 文案；当前还统一承接 `mail2925Mode` 的归一化与“2925 仅在 provide 模式下参与别名生成”的共享判定。
- `paypal-utils.js`：PayPal 账号池相关的纯工具函数，负责账号归一化、按 ID 查找和列表 upsert。
- `manifest.json`：Chrome 扩展清单，声明权限、背景脚本、侧边栏、内容脚本与规则集；当前额外声明 `proxy / webRequest / webRequestAuthProvider`，用于 IP 代理 PAC 接管和代理鉴权回填。
- `microsoft-email.js`：Microsoft Graph / Outlook 邮件读取辅助模块，负责刷新令牌换 token、邮箱夹轮询和验证码提取。
- `package.json`：仓库最小 Node 包配置，目前主要提供测试脚本定义。
- `rules.json`：静态 DNR 规则，主要处理 iCloud 相关请求头。
- `start-hotmail-helper.bat`：Windows 下启动本地 helper 的脚本；当前既服务于 Hotmail 本地收信，也服务于账号记录快照同步。
- `start-hotmail-helper.command`：macOS 下启动本地 helper 的脚本；当前既服务于 Hotmail 本地收信，也服务于账号记录快照同步。
- `开发者AI开发与PR提交流程.md`：仓库现有的 AI 开发与 PR 提交流程说明。
- `项目文件结构说明.md`：当前文件，维护整个仓库非忽略文件的结构与职责索引。
- `项目完整链路说明.md`：面向 AI/开发者的完整功能链路说明，用于快速理解系统整体运行过程。
- `项目开发规范（AI协作）.md`：面向 AI/开发者的项目开发规范、约束与变更检查清单。
## `background/`
- `background/account-run-history.js`：账号记录模块，负责以统一账号标识维护最新记录；邮箱注册以邮箱为主身份，手机号注册以手机号为主身份，同一轮后续绑定的手机号或邮箱会并入同一条记录并覆盖旧占位状态；模块统一归一化成功/失败/停止三态并落地到 `chrome.storage.local`，兼容 phone-only 与 email+phone 组合记录、空密码，并按默认本地 helper 地址自动尝试把完整快照同步到本地 helper；若 helper 未启动，则静默跳过。
- `background/auto-run-controller.js`：自动运行主控制器，封装多轮执行、重试、轮次摘要、线程间隔与倒计时恢复逻辑；当前自动流程会绑定 `autoRunSessionId`，手动停止后旧的倒计时计划、旧重试链路和旧恢复入口不会再复活已失效的自动运行；fresh-attempt reset 时会额外保留 Plus 模式与 PayPal 配置、`gmailBaseEmail`、`mail2925BaseEmail` 与当前 2925 账号选择，避免自动流程重置后丢失关键持久配置。
- `background/contribution-oauth.js`：贡献模式的公开 OAuth 流程模块，负责调用 `apikey.qzz.io` 的公开贡献接口、保存贡献会话运行态、在主 10 步流程里为步骤 7 提供贡献登录地址、在步骤 9/10 衔接 callback 捕获与兼容提交 `/oauth/api/submit-callback`，并把真实服务端状态映射回 sidepanel 运行态。
- `background/cloudmail-provider.js`：Cloud Mail / SkyMail 后台 provider 模块，负责 Token 获取、邮箱创建、邮件列表读取、验证码轮询和生成/转发收件目标邮箱选择。
- `background/generated-email-helpers.js`：生成邮箱辅助层，除了 Duck / Cloudflare / iCloud / Cloudflare Temp Email，也统一承接 Gmail / 2925 的别名邮箱生成入口与自定义邮箱池读取；当 provider 为 2925 且 `mail2925Mode = provide` 时，会先确保当前账号池里已有可用账号，再基于该账号生成别名邮箱；若 `mail2925Mode = receive`，则会回退到普通邮箱生成链路；当生成方式为 iCloud 且 `icloudFetchMode = always_new` 时，会强制跳过未用别名复用并新建别名；当生成方式为 `custom-pool` 时，会按当前目标轮次读取邮箱池中的对应邮箱。
- `background/ip-proxy-core.js`：IP 代理核心模块，负责代理条目解析、账号/接口代理池运行态、PAC 应用与清除、代理鉴权回填、出口探测、失败时的目标站点 fail-close 防漏规则，以及自动运行成功阈值后的代理切换支撑。
- `background/ip-proxy-provider-711proxy.js`：711Proxy provider 规则模块，负责从账号串中识别和写回 `region / session / sessTime` 等参数，并在固定账号模式下把侧栏配置转换为最终生效的代理账号。
- `background/logging-status.js`：后台日志、步骤状态、错误信息和若干状态判断的公共工具层；日志条目统一写入结构化 `step / stepKey`，sidepanel 只读取该元数据渲染步骤标签，不再从日志正文解析步骤号；当前额外承接 `add-phone / 手机号页` 这类认证 fatal 错误的共享判定，并会把 Step 2 的“手机号输入模式未切成功”与真正的 auth `add-phone` 页面区分开，避免自动运行误停机。
- `background/mail-2925-session.js`：2925 会话模块，负责 2925 账号池持久化、当前账号切换、cookie 清理登出、自动登录、命中“子邮箱已达上限邮箱”后的 24 小时禁用与自动切号。
- `background/message-router.js`：后台消息路由层，负责处理 `chrome.runtime.onMessage` 进入的所有业务消息；`LOG / STEP_COMPLETE / STEP_ERROR` 会把消息里的真实 `step` 继续传给结构化日志，跳过登录验证码这类派生日志也按当前步骤 key 写入；当前额外接入 PayPal 账号池的新增与切换、2925 账号池的新增、导入、切换、登录、禁用与删除消息，以及 IP 代理的同步、切换、Change 与出口检测消息；当侧栏关闭 `oauthFlowTimeoutEnabled` 时，会立即清空已存在的 OAuth 总预算 deadline。
- `background/navigation-utils.js`：导航与 URL 判断工具层，负责 callback、入口页、CPA / SUB2API / Codex2API 地址归一化、来源标签页家族判断与步骤跳转相关判断。
- `background/paypal-account-store.js`：PayPal 账号池持久化模块，负责保存账号列表、切换当前账号，并把当前选中账号同步回兼容字段 `paypalEmail / paypalPassword`。
- `background/phone-verification-flow.js`：手机号验证码共享流程模块，负责复用 HeroSMS / 5sim / NexSMS 的取号、复用、轮询、重发、换号与收尾能力；既承接 OAuth 后置 `add-phone / phone-verification` 页面，也承接手机号注册 Step 4 和 Step 8 中真实出现的 `phone-verification` 页面，并保持 `signupPhone*` 运行态与 `currentPhoneActivation` 隔离；后置 add-phone 成功后会把已绑定手机号写入运行态 `phoneNumber`，供账号记录并入同一轮；提交后置手机号验证码时会一并透传可复用的资料页 payload，便于认证页偶发跳回资料页时继续补齐；该流程由调用方传入当前可见步骤号，手机号日志不会再固定显示普通模式 Step 9。
- `background/panel-bridge.js`：来源桥接层；CPA / SUB2API 继续封装页面打开、脚本注入和通信，Codex2API 则直接通过后台协议生成 OAuth 地址。
- `background/signup-flow-helpers.js`：注册页辅助层，负责打开注册入口、等待密码页以及解析当前流程所用邮箱；在 Gmail 与 `2925 + provide` 模式下会优先复用已经存在且仍兼容的完整注册邮箱，只有不兼容或为空时才重新生成；当 provider 为 2925 且启用了 provide 模式下的号池时，会先确保账号池中已选中可用账号。
- `background/tab-runtime.js`：标签页与内容脚本运行时基础设施，封装标签注册、冲突清理、消息超时、注入重试与队列；内容脚本恢复等待日志支持 `logStep / logStepKey`，用于保持 Plus 复用步骤的日志标签正确；当前等待标签完成、等待标签完成并短暂稳定、注入后的短暂延迟和内容脚本重试等待都已做 Stop 感知，避免用户停止后后台还继续等待并恢复执行。
- `background/verification-flow.js`：注册/登录验证码共享流程层，封装重发、轮询、提交、失败回退、自定义邮箱跳过、共享验证码自动重发次数配置、Cloud Mail API 轮询以及 2925 长轮询参数；日志步骤号使用 `completionStep`，因此 Plus 登录验证码会显示可见第 11 步而不是内部复用的 Step 8；当前验证码提交重试上限为 15 次，2925 每次重发验证码之间都会固定跑完一轮 15 次邮箱刷新轮询；若 `mail2925Mode = receive`，会额外把目标注册邮箱传给 2925 内容脚本做弱匹配；若登录验证码提交后页面转入 `add-phone / 手机号页`，则会把“后续需要手机号验证”的结果继续传给 OAuth 确认步骤，而不是误判为普通失败；若登录验证码提交后通信中断但认证页已进入 OAuth 同意页或手机号验证页，会按真实页面状态继续后续流程；若 2925 轮询命中“子邮箱已达上限邮箱”，会转入 2925 会话模块执行“记录时间、禁用 24 小时、切下一个账号并重新登录”，然后直接结束当前尝试。
## `background/steps/`
- `background/steps/wait-registration-success.js`：步骤 6 实现，负责注册资料提交后等待 20 秒，让注册成功状态和页面跳转稳定；默认不清理 cookies，只有侧栏第六步 `清 Cookies` 开关开启时才会在等待结束后清理 ChatGPT / OpenAI 相关 cookies。
- `background/steps/confirm-oauth.js`：步骤 9 实现，负责 OAuth 同意页按钮定位、点击、localhost 回调监听与回调完成；等待 callback 期间会动态检查 OAuth 总预算开关，关闭后仅保留本地回调等待超时。
- `background/steps/create-plus-checkout.js`：Plus 模式第 6 步实现，负责在已登录 ChatGPT 页面创建 PayPal / GoPay checkout session，或在 GPC 模式下读取 accessToken 并通过 `https://gpc.qlhazycoder.top/api/gp/tasks` 创建队列任务，记录 checkout / GPC task 运行态。
- `background/steps/fetch-login-code.js`：步骤 8 实现，负责按真实认证页状态分发登录后续流程：邮箱验证码页走邮箱轮询、验证码回填与回退控制；真实 `phone-verification` 页才复用手机号验证码共享流程；手机号注册登录后若进入 `add-email`，会先生成/解析邮箱并提交绑定，再进入邮箱验证码轮询；邮箱分支对非 2925 provider 会固定当前验证码页显示邮箱作为本次 Step 8 的目标邮箱，当 provider 为 2925 时，会在轮询前先确保当前 2925 账号已自动登录。
- `background/steps/fetch-signup-code.js`：步骤 4 实现，负责注册验证码阶段的页面准备与验证码流程入口；邮箱注册继续走邮箱验证码，手机号注册改走短信验证码；当 provider 为 2925 时，会在邮箱轮询前先确保当前 2925 账号已自动登录。
- `background/steps/fill-plus-checkout.js`：Plus 模式第 7 步实现，负责驱动 PayPal / GoPay checkout 页面选择付款方式、填写账单地址、提交订阅并等待跳转；GPC 模式则轮询队列任务，按远端 `api_waiting_for` 提交 OTP / PIN，并在任务失败、过期或取消时清理运行态。
- `background/steps/fill-password.js`：步骤 3 实现，负责密码生成、保存、回填与提交；当前已改为身份中立，手机号注册遇到无密码页时会按页面状态自动跳过。
- `background/steps/fill-profile.js`：步骤 5 实现，负责姓名、生日填写并把资料提交给注册页内容脚本。
- `background/steps/oauth-login.js`：步骤 7 实现，负责刷新 OAuth 链接、登录和确保进入验证码页；当前会根据 `accountIdentifierType / accountIdentifier` 选择邮箱或手机号登录，手机号账号会先探测并切换手机号登录入口；普通可恢复登录态失败会按上限重试，但一旦识别到认证流程进入 `add-phone / 手机号页`，会立即退出步骤 7 内部重试。
- `background/steps/open-chatgpt.js`：步骤 1 实现，负责打开 ChatGPT 官网并确认入口就绪。
- `background/steps/paypal-approve.js`：Plus 模式第 8 步实现，负责驱动 PayPal 登录、关闭可见通行密钥提示、点击“同意并继续”，并等待授权流程离开 PayPal 页面。
- `background/steps/platform-verify.js`：平台回调验证实现，普通模式为步骤 10，Plus 模式为可见步骤 13；负责 CPA / SUB2API 回调验证，以及 Codex2API 的协议式 callback code/state 交换，所有平台验证日志和完成信号都按当前可见步骤上报。
- `background/steps/plus-return-confirm.js`：Plus 模式第 9 步实现，负责等待 PayPal 授权后回跳到 ChatGPT / OpenAI 页面，页面加载完成后固定等待 1 秒再完成。
- `background/steps/registry.js`：步骤注册表工厂，负责用稳定的步骤元数据映射到执行器。
- `background/steps/submit-signup-email.js`：步骤 2 实现，负责按 `signupMethod` 在邮箱注册与手机号注册之间分发；邮箱分支会先点击官网“免费注册”再提交邮箱并清理旧手机号注册运行态，手机号分支会先点击官网“免费注册”并切到手机号注册入口，确认手机号输入页就绪后优先复用已有 signup activation，其次使用手动运行态手机号，最后才申请接码平台号码并提交，最后根据落地页判断是否跳过后续密码步骤。
## `content/`
- `content/activation-utils.js`：内容脚本通用激活策略工具，负责按钮点击方式判断与平台回调可恢复失败文案判断。
- `content/auth-page-recovery.js`：认证页共享恢复模块，统一封装 `Try again / 重试` 页识别、点击重试和等待退出重试页；当前由注册验证码等待、OAuth 登录恢复、OAuth 同意页重试恢复链路复用。
- `content/duck-mail.js`：DuckDuckGo Email Protection 页面脚本，负责生成或读取 `@duck.com` 地址。
- `content/gmail-mail.js`：Gmail 邮箱轮询脚本，负责在 Gmail 页面中匹配验证码邮件。
- `content/icloud-mail.js`：iCloud 邮箱页面脚本，负责在 iCloud Mail 页面中读取邮件详情和验证码。
- `content/inbucket-mail.js`：Inbucket 邮箱轮询脚本，负责在 Inbucket 页面中读取、删除验证码邮件。
- `content/mail-163.js`：163 / 163 VIP / 126 邮箱轮询脚本，负责网页邮箱验证码读取和邮件清理。
- `content/mail-2925.js`：2925 邮箱页面脚本，负责 2925 邮箱自动登录态确认、收件轮询、按步骤会话隔离“已试验证码”、在每次重发验证码之间执行一轮最多 15 次的邮箱刷新轮询、命中邮件后立即删当前邮件，以及在成功后配合后台执行整箱清理；若页面出现“子邮箱已达上限邮箱”提示，会立即上报后台进入切号链路；当后台显式开启 `mail2925MatchTargetEmail` 时，会对邮件里显式出现的目标邮箱做弱匹配，避免 `receive` 模式误捞别人的验证码。
- `content/paypal-flow.js`：PayPal 页面脚本，负责识别登录表单、填写 PayPal 账号密码、在账号页固定执行 `focus -> clear -> fill -> blur` 重新触发邮箱输入事件、处理页面内可见通行密钥提示，并点击 PayPal 授权页的“同意并继续”按钮。
- `content/phone-country-utils.js`：手机号国家/区号共享工具层，负责手机号纯数字归一化、国家文案/别名归一化、`+(44)` / `(+44)` / `+44` 区号提取、按号码最长区号匹配国家选项，并由注册页与后续手机号验证页共同复用。
- `content/phone-auth.js`：认证页手机号验证脚本，负责识别 `add-phone / phone-verification` 页面、选择国家、填写手机号、提交短信验证码、触发重发短信，以及把“回到 add-phone / 进入 OAuth 同意页”的结果反馈给后台。
- `content/plus-checkout.js`：ChatGPT Plus checkout 页面脚本，负责读取 `/api/auth/session` 创建 Plus checkout、选择 PayPal、填写账单姓名、触发 Google 地址推荐、校验结构化地址字段并点击订阅。
- `content/qq-mail.js`：QQ 邮箱轮询脚本，负责网页邮箱验证码读取。
- `content/signup-page.js`：注册、登录、授权主内容脚本，负责 OpenAI / ChatGPT 页面上的步骤执行；其中 Step 2 / 3 的延迟点击与延迟提交在真正触发前会先检查 Stop 状态，避免停止后页面继续自动点击；当前 Step 2 同时支持邮箱注册与手机号注册入口切换、手机号国家下拉框同步校验、手机号填写与提交；Step 3 收尾会识别手机号注册密码页的 `Incorrect phone number or password` 并上报当前轮重开信号；Step 7 / 8 登录链路会额外识别手机号输入页、手机号登录入口、`phone-verification` 与真实 `add-email` 页面，避免把手机验证码页或添加邮箱页误判成普通邮箱登录入口；Step 9 后置手机号验证完成后若偶发进入资料页，会复用 Step 5 的姓名生日填写逻辑再继续等待 OAuth 同意页。
- `content/sub2api-panel.js`：SUB2API 后台内容脚本，负责获取 OAuth 地址和提交 localhost 回调；平台验证请求会读取 `visibleStep`，普通模式承接步骤 10，Plus 模式承接步骤 13。
- `content/utils.js`：内容脚本公共工具层，负责结构化日志、READY / COMPLETE / ERROR 上报、元素等待、输入与点击；内容脚本日志通过 `{ step, stepKey }` 上报，正文不再承担步骤号解析职责。
- `content/vps-panel.js`：CPA 面板内容脚本，负责获取 OAuth 地址、提交回调 URL，并基于精确成功徽标与错误态做平台验证判定；当前支持普通步骤 10 与 Plus 可见步骤 13。
## `data/`
- `data/names.js`：随机姓名、生日等测试数据源。
- `data/address-sources.js`：Plus 模式本地地址 seed 表，负责按国家选择用于触发 checkout 内置 Google 地址推荐的查询词和结构化地址 fallback；第一版不实时抓取外部地址网站。
- `data/step-definitions.js`：共享步骤元数据，前后台共同使用，用于动态渲染和步骤注册；当前同时提供普通 10 步定义与 Plus 模式 13 步定义，并会按 `plusPaymentMethod / signupMethod` 动态解析实际步骤标题。
## `docs/`
- `docs/仓库协作者AI分析PR与合并标准流程.md`：仓库协作者进行 AI 分析 PR 与合并时的流程说明。
- `docs/ip-proxy-module.md`：IP Proxy 模块说明，记录模块定位、后台/侧栏代码结构、当前功能范围、711Proxy 参数联动、操作方式、发布策略与已知限制。
- `docs/使用教程.md`：旧版完整使用教程，保留尚未完全拆分的 HeroSMS、IP 代理、GoPay 等补充章节。
- `docs/使用教程/使用教程.md`：分部分使用教程总索引。
- `docs/使用教程/使用教程书写模板.md`：后续维护分部分教程时使用的书写与拆分模板。
- `docs/使用教程/分部分/*.md`：按主题拆分后的使用教程正文。
- `docs/images/交流群.jpg`：README 中展示的官网 / QQ 交流群入口图片。
- `docs/refactor/2026-04-16-architecture-refactor-plan.md`：本轮重构阶段的结构设计与迁移计划记录。
- `docs/superpowers/plans/2026-04-10-hotmail-oauth-mail-pool.md`：Hotmail OAuth 邮箱池实现计划文档。
- `docs/superpowers/specs/2026-04-10-hotmail-oauth-design.md`：Hotmail OAuth + Graph Mail 的设计规格文档。
## `icons/`
- `icons/icon128.png`：扩展 128 像素图标。
- `icons/icon16.png`：扩展 16 像素图标。
- `icons/icon48.png`：扩展 48 像素图标。
## `scripts/`
- `scripts/gpc_sms_helper_macos.py`：GPC Plus helper 的 macOS 本地短信验证码 helper，读取本机 Messages 数据库中的 GoPay/OpenAI 短信 OTP，并通过 `http://127.0.0.1:18767/latest-otp?phone=...&consume=1` 提供给扩展按手机号自动轮询；`/otp` 仍保留兼容，`consume=1` 会消费本次返回的验证码记录，避免下次重复读取。
- `scripts/hotmail_helper.py`：本地 helper 服务，负责通过本地接口协助 Hotmail 获取邮件和验证码，并提供账号记录 JSON 快照同步接口；旧的文本追加接口仍保留作兼容。
## `sidepanel/`
- `sidepanel/account-pool-ui.js`：侧边栏号池表单共享 UI helper，负责 Hotmail / 2925 账号池新增表单的显隐、头部“添加账号/取消添加”按钮文案切换、清空表单与首字段聚焦。
- `sidepanel/hotmail-manager.js`：侧边栏 Hotmail 账号池管理器，负责列表、导入、验证、测试收信和批量操作。
- `sidepanel/icloud-manager.js`：侧边栏 iCloud 隐私邮箱管理器，负责列表、筛选、保留、删除和批量操作。
- `sidepanel/luckmail-manager.js`：侧边栏 LuckMail 管理器，负责邮箱列表、筛选、启停、保留与批量操作。
- `sidepanel/mail-2925-manager.js`：侧边栏 2925 账号池管理器，负责 2925 账号的新增、导入、切换、手动登录、启停、清冷却与删除。
- `sidepanel/form-dialog.js`：侧边栏公共表单弹窗模块，负责渲染可复用的小型表单弹窗，支持动态字段、校验、确认与取消。
- `sidepanel/account-records-manager.js`：侧边栏账号记录面板管理器，负责“记录”按钮、覆盖层开关、分页列表、成功/失败/停止统计摘要和清理确认；展示时按 `accountIdentifierType` 决定主身份，手机号注册显示手机号并把绑定邮箱放副行，邮箱注册显示邮箱并把后续绑定手机号放副行。
- `sidepanel/contribution-content-update-service.js`：侧边栏贡献内容更新服务，负责拉取 `https://apikey.qzz.io/api/content-summary`、缓存公开公告/教程摘要，并输出可用于提示展示的 `promptVersion` 与最新更新时间。
- `sidepanel/contribution-mode.js`：侧边栏贡献模式管理器，负责顶部“贡献”按钮、确认弹窗、贡献模式显隐、复用主自动流程启动、侧栏内贡献状态轮询、上传页跳转，以及贡献模式下对来源选择、配置入口、记录入口和敏感配置行（包括 Codex2API 配置）的禁用与隐藏。
- `sidepanel/ip-proxy-panel.js`：侧边栏 IP 代理面板逻辑，负责代理配置显隐、服务/模式切换、账号串参数同步、状态卡渲染，以及同步、下一条、Change、检测出口、检查 IP 等按钮行为。
- `sidepanel/ip-proxy-provider-711proxy.js`：侧边栏 711Proxy 输入辅助逻辑，负责从 host、username、region 输入中推断和归一化国家/地区参数。
- `sidepanel/sidepanel.css`：侧边栏样式文件；当前额外提供 Hotmail / 2925 共用的号池表单容器、操作按钮行、统一的收起态列表高度样式，以及 IP 代理配置区、状态卡和操作按钮样式。
- `sidepanel/sidepanel.html`：侧边栏页面结构；当前步骤列表已改为动态容器，日志区提供“记录”按钮并挂接账号记录覆盖层，顶部新增“贡
献”按钮并在设置卡片中新增贡献模式主面板；贡献按钮下方额外挂接一个可关闭的轻提示气泡，用于提示公开公告 / 使用教程有更新；贡献面板内
展示 `OAUTH / 回调 / 总状态` 三块真实运行态信息，同时把“接码”开关与“验证码重发”拆成同一行展示；只有开启接码后，下面的 HeroSMS 平
台、国家与 API Key 行才会显示；页面继续加载 `managed-alias-utils.js` 与 `mail-provider-utils.js`，并把旧的“邮箱前缀”字段语义改为“别
名基邮箱”；当 provider 为 2925 时，会额外显示 `提供邮箱 / 接收邮箱` 模式切换，并把“2925 号池”从别名基邮箱行拆成独立配置行，避免
receive 模式把账号池开关一起隐藏；当前在 `邮箱生成` 区域新增 `自定义邮箱池` 选项和多行邮箱池输入框，并在 `邮箱服务 = 自定义邮箱` 时
额外显示 `自定义号池` 文本框；当邮箱服务为 iCloud 时，额外提供目标邮箱类型与转发邮箱 provider 配置，用于选择直接从 iCloud 收件箱收
码或从 QQ / 网易 / Gmail 转发目标邮箱收码；当邮箱服务或邮箱生成器为 Cloud Mail 时，额外显示 API 地址、管理员账号、接收邮箱和生成域名配置行；来源下拉框当前支持 `CPA / SUB2API / Codex2API`，其中 Codex2API 额外提供后台地址和管理密
钥配置行；设置卡片新增 `IP代理` 开关与代理配置折叠区，支持 711Proxy 账号密码模式、代理状态卡与出口检测按钮；接码卡内把注册方式、接码配置、接码订单运行态与“注册手机号”身份运行态分层展示，“注册手机号”位于订单运行状态下方，不嵌入当前分配/验证码网格；设置卡片新增 `Plus 模式` 开关与 PayPal 账号下拉框，右侧使用公共表单弹窗添加账号；GPC Plus 配置额外提供只读 API 地址、API Key、专用手机号、OTP 渠道、本地 OTP helper 开关、helper URL 与 PIN，并提供 `购买卡密` 与 `转换 API Key` 入口；Hotmail / 2925 两个账号池当前都使用统一的头部“添加账号/取消添加”按钮和共享表单容器；设置卡片还新增“授权总超时”开关，用于控制 Step 7 后链 5 分钟总预算。
- `sidepanel/paypal-manager.js`：侧边栏 PayPal 账号管理器，负责 Plus 模式下的账号下拉框渲染、添加账号弹窗、保存账号与切换当前账号。
- `sidepanel/sidepanel.js`：侧边栏主入口脚本，负责 UI 状态同步、动态步骤渲染、按钮交互、共享验证码自动重发次数配置与广播接收，并装
配 Hotmail / 2925 / iCloud / LuckMail / 贡献模式 / 账号记录面板 / 贡献内容更新服务；当前贡献模式的“开始贡献”会直接复用主自动流程启
动逻辑，而独立 manager 负责贡献运行态展示与轮询，同时把 Gmail / 2925 的基邮箱输入、完整注册邮箱输入、自动生成按钮与兼容性校验统一接
到共享别名逻辑上；当 provider 为 2925 时，会根据 `mail2925Mode` 决定是否启用别名基邮箱链路，而 2925 号池开关与当前账号选择则独立显
示并同时服务于 provide / receive 两种模式；当 provider 为 iCloud 时，会保存并回显目标邮箱类型与转发邮箱 provider，相关 provider 选
项和 label 复用 `mail-provider-utils.js`；Cloud Mail 配置保存、回显和显隐由这里接入，可分别服务于邮箱生成器和转发收件 provider；`自定义邮箱池` 模式会按邮箱池长度锁定自动轮数，并把当前输入的邮箱池配置参与自动启动前保
存；点击“自动”时会先冻结当时的目标轮数，避免启动前的异步刷新、保存或后台旧状态回灌把输入框重置为 1；`邮箱服务 = 自定义邮箱` 时，如果配置了 `customMailProviderPool`，也会按号池长度锁定自动轮数并在 Auto 中按轮次分配注册邮箱，同时
在普通失败时继续复用当前邮箱，只有成功或出现手机号验证时才切换下一个邮箱；Plus 模式开启后，步骤列表会切换为 13 步，并显示 PayPal 账
号下拉框与添加入口；当前选中的 PayPal 账号会同步回兼容字段 `paypalEmail / paypalPassword` 供后台步骤复用；Step 8 的自定义邮箱确认弹
窗当前额外提供“出现手机号验证”按钮，用于直接走与真实 add-phone 一致的 fatal 分支；HeroSMS 国家列表
会在 sidepanel 初始化时拉取并恢复到本地保存的国家/API 设置，接码开关关闭时会直接隐藏相关配置；账号记录快照同步改为默认自动模式，只
要本地 helper 可用就会自动落盘；新来源 Codex2API 在这里仅补充来源配置接线、表单显隐和 Step 10 按钮文案，不承接协议业务逻辑；
Hotmail / 2925 的新增表单显隐统一接到 `sidepanel/account-pool-ui.js` 这一层共享 helper；IP 代理配置保存、服务配置快照、开关应用和运行态回显由这里接入消息路由，具体解析/状态渲染下沉到 `sidepanel/ip-proxy-panel.js`；侧边栏初始化与点击“自动”前会刷新一次贡献站
公开内容摘要，并按本地关闭版本决定是否展示轻提示，同时在首次初始化后按现有规则决定是否弹出新手引导提示；当前会保存、回显并热更新 `oauthFlowTimeoutEnabled` 设置；日志渲染只读取结构化 `entry.step` 生成步骤标签，不再正则解析日志正文；注册手机号输入框只同步运行态身份，不写入持久配置。
- `sidepanel/update-service.js`：侧边栏更新检查服务，负责 GitHub Releases 查询、`Ultra` / 历史 `Pro` / legacy `v` 版本族排序、缓存读取与版本展示。
## `tests/`
- `tests/activation-utils.test.js`：测试内容脚本激活策略与平台回调可恢复错误判断。
- `tests/address-sources.test.js`：测试 Plus 模式本地地址 seed 表的国家归一化、fallback 国家选择与基础地址字段。
- `tests/auth-page-recovery.test.js`：测试认证页共享恢复层的重试页识别与恢复行为。
- `tests/auto-run-fresh-attempt-reset.test.js`：测试自动运行在新一轮开始前会重置旧运行时上下文，并补充 `gmailBaseEmail` / `mail2925BaseEmail` 在 fresh reset 后仍被保留的回归验证。
- `tests/auto-run-step4-mail2925-thread-terminate.test.js`：测试步骤 4 命中 2925“结束当前尝试”错误时，不会再沿用当前邮箱回到步骤 1 重开，而是直接把错误抛给自动重试控制器。
- `tests/auto-run-timer-session-guard.test.js`：测试自动运行的旧计时计划在 Stop 使 session 失效后，不能再把已停止的自动流程重新拉起。
- `tests/auto-run-add-phone-stop.test.js`：测试自动运行控制器在开启自动重试时，遇到 `add-phone / 手机号页` 会直接结束当前轮并继续下一轮，而不是把整条自动流程暂停。
- `tests/auto-run-step6-restart.test.js`：测试自动运行在后半段授权链路遇错时会回到步骤 7 重开，并在命中 add-phone 或泛化手机号页 fatal 错误时停止重开。
- `tests/auto-step-random-delay.test.js`：测试自动运行步间延迟与旧配置键兼容解析。
- `tests/background-auto-run-module.test.js`：测试自动运行控制器模块已接入且导出工厂。
- `tests/background-account-run-history-module.test.js`：测试账号记录模块已接入、导出工厂，能够保留并归一化停止记录、归一化失败标签、计算自动重试次数、归并同一轮邮箱/手机号身份，并支持清理后同步完整快照。
- `tests/background-account-history-settings.test.js`：测试账号运行历史的独立配置项归一化，不再复用 Hotmail 模式作为启停条件。
- `tests/background-contribution-mode.test.js`：测试贡献模式的后台运行态与公开 OAuth 接入，覆盖 `contributionMode` 只存在于运行态、`SET_CONTRIBUTION_MODE / POLL_CONTRIBUTION_STATUS` 消息接入、reset 保留贡献运行态，以及 callback 自动提交在“无需手动提交”场景下的兼容处理。
- `tests/background-custom-email-pool.test.js`：测试后台对自定义邮箱池生成方式，以及自定义邮箱服务号池的归一化、标签文案和按轮次取邮箱逻辑。
- `tests/background-generated-email-module.test.js`：测试生成邮箱辅助模块已接入且导出工厂，并覆盖 2925 receive 模式回退普通邮箱生成、自定义邮箱池按轮次取值、2925 provide 模式账号池预热，以及 iCloud `always_new` 传参。
- `tests/background-icloud.test.js`：测试 iCloud 相关后台纯函数与别名收尾逻辑。
- `tests/background-icloud-login-help.test.js`：测试 iCloud 登录判定、页面上下文回退、别名缓存回退和保留异常恢复的关键源码约束。
- `tests/background-icloud-mail-provider.test.js`：测试 iCloud 邮箱 provider 配置解析，并覆盖转发收码模式复用共享 provider 配置。
- `tests/background-ip-proxy-core.test.js`：测试 IP 代理核心解析与接入约束，覆盖注释行过滤、代理条目归一化、711 固定账号参数叠加、PAC 生成、侧栏脚本加载顺序和自动切换阈值钳制。
- `tests/background-logging-status-module.test.js`：测试日志 / 状态模块已接入且导出工厂。
- `tests/background-luckmail.test.js`：测试 LuckMail 相关后台逻辑，如购买、复用、标记已用与重置。
- `tests/background-mail2925-session-module.test.js`：测试 2925 会话模块已接入且导出工厂，并覆盖命中上限后“禁用 24 小时 + 切下一个号 + 自动登录”的核心链路。
- `tests/background-mail2925-signup-flow.test.js`：测试注册页辅助层在 2925 provider 下，会先确保账号池里已分配可用账号，再继续生成别名邮箱。
- `tests/background-message-router-module.test.js`：测试消息路由模块已接入且导出工厂。
- `tests/background-message-router-step2-skip.test.js`：测试步骤 2 直接落到验证码页时的跳步与状态保护逻辑，并覆盖邮箱身份写入时清理旧手机号注册运行态。
- `tests/background-navigation-utils-module.test.js`：测试导航工具模块已接入且导出工厂。
- `tests/background-panel-bridge-module.test.js`：测试面板桥接模块已接入且导出工厂。
- `tests/background-paypal-account-store-module.test.js`：测试 PayPal 账号池后台模块已接入、导出工厂，并覆盖当前账号选择会同步回兼容字段 `paypalEmail / paypalPassword`。
- `tests/background-platform-verify-codex2api.test.js`：测试 Codex2API 新来源在步骤 10 走协议式 callback 交换，不依赖后台页面注入。
- `tests/background-signup-flow-module.test.js`：测试注册页辅助模块已接入且导出工厂。
- `tests/background-skip-step-linking.test.js`：测试手动跳过步骤 1 时，会级联跳过步骤 2~5，并仅跳过其中未完成且未运行的步骤。
- `tests/background-signup-step2-branching.test.js`：测试在 Gmail / 2925 模式下，已有兼容别名邮箱时应直接复用，不应再次重生成。
- `tests/background-step-modules.test.js`：测试步骤模块文件都已由后台入口加载。
- `tests/background-step5-submit-short-circuit.test.js`：测试步骤 5 会把生成好的资料直接转发给内容脚本，并依赖完成信号收尾。
- `tests/background-step6-retry-limit.test.js`：测试步骤 6 的注册成功等待、可选 cookies 清理开关，以及步骤 7 的有限重试上限与 `add-phone` 命中后的立即跳出行为。
- `tests/background-step7-recovery.test.js`：测试步骤 8 获取登录验证码后直接提交（不再回放步骤 7），覆盖邮箱验证码页、真实手机验证码页、`add-email` 绑定邮箱后收码、2925 固定回看窗口与关闭重发间隔。
- `tests/background-step-registry.test.js`：测试后台步骤注册表和共享步骤定义已接入。
- `tests/background-tab-runtime-module.test.js`：测试标签运行时模块已接入且导出工厂，并覆盖等待标签完成、等待标签稳定完成，以及等待过程中的 Stop 中断行为。
- `tests/background-verification-flow-module.test.js`：测试验证码流程模块已接入且导出工厂。
- `tests/phone-auth-country-match.test.js`：测试认证页手机号国家选择在页面本地化时，仍能用 HeroSMS 的英文国家名匹配对应国家选项。
- `tests/phone-country-utils.test.js`：测试手机号国家/区号共享工具的区号提取、最长前缀解析、国家别名匹配，以及 manifest 与后台动态注入顺序。
- `tests/phone-verification-flow.test.js`：测试手机号验证共享流程对 HeroSMS 的取号、复用、重发、换号与 Step 7 重开错误分支。
- `tests/paypal-approve-detection.test.js`：测试 Plus 第 8 步后台执行器对 PayPal 标签页发现、分离式账号/密码页识别、联合登录页识别，以及登录后直接离开 PayPal 页的分支判断。
- `tests/paypal-flow-content.test.js`：测试 PayPal 内容脚本对可见邮箱/密码输入框的识别，并覆盖邮箱页即使已预填相同账号也会先清空再重填后继续下一步。
- `tests/gpc-sms-helper-script.test.js`：测试 GPC macOS 本地短信 helper 在非 macOS 环境下会提示平台与 iPhone 短信转发要求。
- `tests/plus-checkout-billing-tab-resolution.test.js`：测试 Plus 第 7 步可直接接管当前 checkout 标签页，并把 PayPal、账单地址、Google 地址推荐和订阅按钮操作路由到对应 Stripe iframe；当前也覆盖 GPC 队列任务轮询、本地 OTP 自动读取、手动 OTP 输入、PIN 提交与任务终止分支。
- `tests/cloudflare-temp-email-provider.test.js`：测试 Cloudflare Temp Email provider 的轮询与目标邮箱选择逻辑。
- `tests/cloudflare-temp-email-utils.test.js`：测试 Cloudflare Temp Email 工具层的 URL、域名、邮件解析逻辑。
- `tests/cloudmail-provider.test.js`：测试 Cloud Mail provider 的验证码轮询和生成/转发收件目标邮箱选择逻辑。
- `tests/cloudmail-utils.test.js`：测试 Cloud Mail 工具层的 URL、域名、鉴权头、Token 与邮件响应归一化逻辑。
- `tests/content-utils.test.js`：测试内容脚本公共工具层对 `mail.126.com` 等网页邮箱来源的识别逻辑。
- `tests/hotmail-api-mode.test.js`：测试 Hotmail API 模式相关文案和集成方式。
- `tests/hotmail-cors-headers.test.js`：测试 Microsoft token 请求相关 DNR 配置。
- `tests/hotmail-utils.test.js`：测试 Hotmail 工具层的账号筛选、验证码提取和消息匹配逻辑。
- `tests/icloud-mail-content.test.js`：测试 iCloud Mail 内容脚本读取邮件正文和选中状态逻辑。
- `tests/icloud-utils.test.js`：测试 iCloud 工具层的 host、别名列表、保留状态与筛选逻辑。
- `tests/luckmail-utils.test.js`：测试 LuckMail 工具层的购买记录、邮件、游标和验证码匹配逻辑。
- `tests/mail-provider-utils.test.js`：测试网页邮箱 provider 配置工具对 `126` 等 provider 的归一化与入口配置解析，以及 iCloud 转发收码 provider 选项、归一化和配置复用。
- `tests/mail-2925-content.test.js`：测试 2925 邮箱内容脚本的轮询快照、忽略邮箱对比、按步骤会话隔离已试验证码、单封邮件删除与整箱删除逻辑。
- `tests/mail2925-utils.test.js`：测试 2925 账号池工具层的账号归一化、冷却期判断、可用账号挑选与批量导入解析。
- `tests/managed-alias-utils.test.js`：覆盖 Gmail / 2925 共享别名工具的解析、生成、兼容性判断。
- `tests/microsoft-email.test.js`：测试 Microsoft 邮件拉取与验证码提取逻辑。
- `tests/sidepanel-hotmail-manager.test.js`：测试侧边栏 Hotmail 管理器模块接线、共享号池表单显隐交互与空态渲染。
- `tests/sidepanel-contribution-button.test.js`：测试侧边栏顶部 `贡献` 按钮的 HTML 接线、更新提示气泡接线，以及相关脚本加载顺序。
- `tests/sidepanel-account-records-manager.test.js`：测试侧边栏账号记录覆盖层的 HTML 接入、helper 地址归一化与 manager 渲染逻辑。
- `tests/contribution-content-update-service.test.js`：测试贡献内容更新服务对公开摘要接口的归一化、版本提取与失败回退缓存逻辑。
- `tests/sidepanel-custom-email-pool.test.js`：测试侧边栏自定义邮箱池、自定义邮箱服务号池的 HTML 接线，以及邮箱池长度与自动轮数之间的联动规则。
- `tests/sidepanel-contribution-mode.test.js`：测试侧边栏贡献模式的 HTML 接线、runtime-only 设置保护，以及贡献模式 manager 复用主自动流启动、状态轮询和退出清理逻辑。
- `tests/sidepanel-auto-run-content-refresh.test.js`：测试点击“自动”时会先冻结当前轮数并刷新贡献内容更新摘要，且刷新失败或启动前状态回灌不会阻塞或改写自动流程启动目标。
- `tests/sidepanel-icloud-manager.test.js`：测试侧边栏 iCloud 管理器模块接线与空态渲染。
- `tests/sidepanel-icloud-provider.test.js`：测试侧边栏 iCloud 登录地址解析、目标邮箱类型 / 转发邮箱 provider 保存、回显和显隐联动。
- `tests/sidepanel-luckmail-manager.test.js`：测试侧边栏 LuckMail 管理器模块接线与空态渲染。
- `tests/sidepanel-mail2925-manager.test.js`：测试侧边栏 2925 管理器模块接线、共享号池表单脚本加载顺序、显隐交互与空态渲染。
- `tests/sidepanel-mail2925-mode.test.js`：测试侧边栏保留 `2925 provide / receive` 模式行与独立的号池配置行，并验证 sidepanel 只在 provide 模式下把 2925 视为别名邮箱 provider。
- `tests/sidepanel-paypal-manager.test.js`：测试侧边栏公共表单弹窗脚本与 PayPal manager 的加载顺序，以及 PayPal 账号保存后会立即选中当前账号。
- `tests/signup-entry-diagnostics.test.js`：测试注册入口与密码页诊断快照输出，包括密码页错误文案字段。
- `tests/signup-step2-email-switch.test.js`：测试 Step 2 在手机号输入模式下切回邮箱输入模式、本地化邮箱输入框识别，以及手机号注册时国家下拉框可视区号同步。
- `tests/signup-page-tab-cleanup.test.js`：测试注册页来源标签的冲突清理逻辑。
- `tests/step-definitions-module.test.js`：测试共享步骤定义模块及侧边栏脚本加载顺序。
- `tests/step3-direct-complete.test.js`：测试步骤 3 在提交前先完成上报，并保留延迟提交回调的可执行性验证。
- `tests/step5-age-consent.test.js`：测试步骤 5 在年龄页会先勾选顶部“我同意以下所有各项”复选框，再点击提交。
- `tests/step5-direct-complete.test.js`：测试步骤 5 在资料页点击提交后立即完成当前步骤。
- `tests/step6-login-state.test.js`：测试 OAuth 登录状态识别逻辑，当前对应步骤 7 链路，并覆盖 `phone-verification` 页面不会被误判成邮箱验证码页、真实 `add-email` 页面不会被误判成普通邮箱输入页。
- `tests/step6-timeout-recovery.test.js`：测试 OAuth 登录超时报错页的可恢复结果构造，当前对应步骤 7 链路。
- `tests/step7-phone-login-entry.test.js`：测试 OAuth 手机号登录入口识别、真实 add-phone 与手机号登录页区分、慢切换等待窗口、手机号登录页可视国家下拉框会按本轮号码区号自动切换，以及输入框只剩区号时不会继续提交。
- `tests/step8-callback-handling.test.js`：测试 localhost 回调地址捕获逻辑，当前对应步骤 9。
- `tests/step8-debugger-stop.test.js`：测试调试器点击在 Stop 场景下的中止行为，当前对应步骤 9。
- `tests/step8-retry-page-recovery.test.js`：测试 OAuth 同意页点击后的重试页恢复分支，以及手机号验证完成后会继续回到 OAuth 同意页等待，当前对应步骤 9。
- `tests/step8-state-timeout-retry.test.js`：测试认证页通信错误是否可判定为可重试，当前对应步骤 9。
- `tests/step8-stop-cleanup.test.js`：测试 OAuth 确认流程在 Stop 后能正确清理监听器与挂起状态，当前对应步骤 9。
- `tests/step9-profile-after-phone-verification.test.js`：测试 Step 9 后置手机号验证提交后若落到注册资料页，会复用 Step 5 资料填写逻辑，并覆盖未出现资料页时继续保持原 OAuth 同意页路径。
- `tests/step9-cpa-mode.test.js`：测试本地 CPA 平台回调跳过策略判断，当前作用于步骤 10。
- `tests/step9-localhost-cleanup-scope.test.js`：测试 localhost callback 与路径前缀残留页的精确清理范围，当前对应步骤 10 收尾。
- `tests/step9-status-diagnostics.test.js`：测试平台回调成功判定、红色错误态过滤，以及成功徽标与失败提示并存时的优先级，当前对应步骤 10。
- `tests/update-service.test.js`：测试侧边栏更新检查服务在 `Ultra` / 历史 `Pro` / legacy `v` 混合版本和旧缓存场景下都能按版本族正确排序，不会把历史版本误显示成最新可升级版本。
- `tests/verification-stop-propagation.test.js`：测试验证码流程在 Stop 场景下的错误传播与不中途降级。
- `tests/verification-flow-polling.test.js`：测试 2925 长轮询参数、验证码提交流程中的 `beforeSubmit` 钩子执行顺序，以及步骤 8 提交验证码后进入手机号页时会把“继续手机号验证”状态交给步骤 9 处理。
Reference in New Issue View Git Blame Copy Permalink