FlowPilot/项目文件结构说明.md

项目文件结构说明

本文档列出当前仓库中所有“非忽略文件”，并说明每个文件的作用。

不纳入本清单的忽略目录：

• .github/
• _metadata/
• docs/md/
• .vscode/
• .git/

更新规则：

• 新增、删除、重命名非忽略文件后，必须同步更新本文件。
• 如果文件职责发生明显变化，也必须同步更新本文件中的说明。
• 本文档不保留“增量补充”“结构补充”一类追加章节；结构变化时，直接更新对应文件条目与职责说明。

根目录

• .gitignore：定义仓库忽略规则，当前忽略 docs/md/、.github/、_metadata/、.vscode/ 等目录。
• LICENSE：项目许可证文件。
• README.md：面向使用者的项目介绍、安装说明、能力清单与操作指引。
• background.js：扩展后台 Service Worker 入口壳，负责模块装配、初始化、全局常量、少量保留的领域函数与运行入口；当前新增 oauthFlowTimeoutEnabled 持久化配置，并统一承接 OAuth 授权后链总预算开关与剩余预算计算。
• cloudflare-temp-email-utils.js：Cloudflare Temp Email 相关的纯工具函数，负责 URL、域名、邮件内容与 MIME 数据归一化。
• 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：账号记录模块，负责以统一账号标识维护最新记录（优先邮箱，phone-only 时改用 accountIdentifier / phoneNumber），在步骤 2 设定身份后支持先写入“停止/未完成”占位状态，统一归一化成功/失败/停止三态并落地到 chrome.storage.local，兼容 phone-only 记录与空密码，并按默认本地 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/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 隔离；该流程由调用方传入当前可见步骤号，手机号日志不会再固定显示普通模式 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：注册/登录验证码共享流程层，封装重发、轮询、提交、失败回退、自定义邮箱跳过、共享验证码自动重发次数配置以及 2925 长轮询参数；日志步骤号使用 completionStep，因此 Plus 登录验证码会显示可见第 11 步而不是内部复用的 Step 8；当前验证码提交重试上限为 15 次，2925 每次重发验证码之间都会固定跑完一轮 15 次邮箱刷新轮询；若 mail2925Mode = receive，会额外把目标注册邮箱传给 2925 内容脚本做弱匹配；若登录验证码提交后页面转入 add-phone / 手机号页，则会把“后续需要手机号验证”的结果继续传给 OAuth 确认步骤，而不是误判为普通失败；若登录验证码提交后通信中断但认证页已进入 OAuth 同意页或手机号验证页，会按真实页面状态继续后续流程；若 2925 轮询命中“子邮箱已达上限邮箱”，会转入 2925 会话模块执行“记录时间、禁用 24 小时、切下一个账号并重新登录”，然后直接结束当前尝试。

background/steps/

• background/steps/clear-login-cookies.js：步骤 6 实现，负责登录前 Cookie 清理。
• background/steps/confirm-oauth.js：步骤 9 实现，负责 OAuth 同意页按钮定位、点击、localhost 回调监听与回调完成；等待 callback 期间会动态检查 OAuth 总预算开关，关闭后仅保留本地回调等待超时。
• background/steps/create-plus-checkout.js：Plus 模式第 6 步实现，负责在已登录 ChatGPT 页面创建 Plus checkout session，打开 chatgpt.com/checkout/openai_ie/{checkout_session_id} 短链，并记录 checkout 运行态。
• 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 步实现，负责驱动 checkout 页面选择 PayPal、生成账单姓名、读取本地地址 seed、触发地址推荐、提交订阅并等待跳转到 PayPal。
• 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 7 / 8 登录链路会额外识别手机号输入页、手机号登录入口、phone-verification 与真实 add-email 页面，避免把手机验证码页或添加邮箱页误判成普通邮箱登录入口。
• 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：面向使用者的补充教程文档，当前说明扩展更新流程与 Clash Verge 的“非港轮询”配置步骤。
• docs/images/交流群.jpg：README 中展示的官网 / QQ 交流群入口图片。
• docs/images/微信.png：侧边栏 Plus 功能支持弹窗使用的微信打赏二维码图片。
• 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/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：侧边栏账号记录面板管理器，负责“记录”按钮、覆盖层开关、分页列表、成功/失败/停止统计摘要和清理确认；展示时优先显示邮箱，phone-only 记录则回退显示手机号或统一账号标识。
• 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 转发目标邮箱收码；来源下拉框当前支持 CPA / SUB2API / Codex2API，其中 Codex2API 额外提供后台地址和管理密 钥配置行；设置卡片新增 IP代理 开关与代理配置折叠区，支持 711Proxy 账号密码模式、代理状态卡与出口检测按钮；接码卡内把注册方式、接码配置、接码订单运行态与“注册手机号”身份运行态分层展示，“注册手机号”位于订单运行状态下方，不嵌入当前分配/验证码网格；设置卡片新增 Plus 模式 开关与 PayPal 账号下拉框，右侧使用公共表单弹窗添加账号；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；自定义邮箱池 模式会按邮箱池长度锁定自动轮数，并把当前输入的邮箱池配置参与自动启动前保 存；点击“自动”时会先冻结当时的目标轮数，避免启动前的异步刷新、保存或后台旧状态回灌把输入框重置为 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 的 Cookie 清理，以及步骤 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/plus-checkout-billing-tab-resolution.test.js：测试 Plus 第 7 步可直接接管当前 checkout 标签页，并把 PayPal、账单地址、Google 地址推荐和订阅按钮操作路由到对应 Stripe iframe。
• tests/cloudflare-temp-email-provider.test.js：测试 Cloudflare Temp Email provider 的轮询与目标邮箱选择逻辑。
• tests/cloudflare-temp-email-utils.test.js：测试 Cloudflare Temp Email 工具层的 URL、域名、邮件解析逻辑。
• 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-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 处理。