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

项目文件结构说明.md

@@ -0,0 +1,159 @@
+# 项目文件结构说明
+
+本文档列出当前仓库中所有“非忽略文件”，并说明每个文件的作用。
+
+不纳入本清单的忽略目录：
+
+- `.github/`
+- `_metadata/`
+- `docs/md/`
+- `.vscode/`
+- `.git/`
+
+更新规则：
+
+- 新增、删除、重命名非忽略文件后，必须同步更新本文件。
+- 如果文件职责发生明显变化，也必须同步更新本文件中的说明。
+
+## 根目录
+
+- `.gitignore`：定义仓库忽略规则，当前忽略 `docs/md/`、`.github/`、`_metadata/`、`.vscode/` 等目录。
+- `LICENSE`：项目许可证文件。
+- `README.md`：面向使用者的项目介绍、安装说明、能力清单与操作指引。
+- `background.js`：扩展后台 Service Worker 入口壳，负责模块装配、初始化、全局常量、少量保留的领域函数与运行入口。
+- `cloudflare-temp-email-utils.js`：Cloudflare Temp Email 相关的纯工具函数，负责 URL、域名、邮件内容与 MIME 数据归一化。
+- `hotmail-utils.js`：Hotmail 账号与验证码提取相关的纯工具函数，负责账号筛选、验证码匹配、第三方接口数据归一化。
+- `icloud-utils.js`：iCloud 隐私邮箱相关的纯工具函数，负责 host、别名列表、保留状态、已用状态等归一化。
+- `luckmail-utils.js`：LuckMail 相关的纯工具函数，负责邮箱购买记录、标签、邮件 cursor、验证码匹配等归一化。
+- `manifest.json`：Chrome 扩展清单，声明权限、背景脚本、侧边栏、内容脚本与规则集。
+- `microsoft-email.js`：Microsoft Graph / Outlook 邮件读取辅助模块，负责刷新令牌换 token、邮箱夹轮询和验证码提取。
+- `package.json`：仓库最小 Node 包配置，目前主要提供测试脚本定义。
+- `rules.json`：静态 DNR 规则，主要处理 iCloud 相关请求头。
+- `start-hotmail-helper.bat`：Windows 下启动本地 Hotmail helper 的脚本。
+- `start-hotmail-helper.command`：macOS 下启动本地 Hotmail helper 的脚本。
+- `开发者AI开发与PR提交流程.md`：仓库现有的 AI 开发与 PR 提交流程说明。
+- `项目文件结构说明.md`：当前文件，维护整个仓库非忽略文件的结构与职责索引。
+- `项目完整链路说明.md`：面向 AI/开发者的完整功能链路说明，用于快速理解系统整体运行过程。
+- `项目开发规范（AI协作）.md`：面向 AI/开发者的项目开发规范、约束与变更检查清单。
+
+## `background/`
+
+- `background/auto-run-controller.js`：自动运行主控制器，封装多轮执行、重试、轮次摘要、线程间隔与倒计时恢复逻辑。
+- `background/generated-email-helpers.js`：生成邮箱辅助层，封装 Duck、Cloudflare、Cloudflare Temp Email、iCloud 隐私邮箱的获取逻辑。
+- `background/logging-status.js`：后台日志、步骤状态、错误信息和若干状态判断的公共工具层。
+- `background/message-router.js`：后台消息路由层，负责处理 `chrome.runtime.onMessage` 进入的所有业务消息。
+- `background/navigation-utils.js`：导航与 URL 判断工具层，负责 callback、入口页、CPA/SUB2API 地址、步骤跳转相关判断。
+- `background/panel-bridge.js`：CPA / SUB2API 面板桥接层，封装 OAuth 地址获取所需的页面打开、脚本注入和通信。
+- `background/signup-flow-helpers.js`：注册页辅助层，负责打开注册入口、等待密码页以及解析当前流程所用邮箱。
+- `background/tab-runtime.js`：标签页与内容脚本运行时基础设施，封装标签注册、冲突清理、消息超时、注入重试与队列。
+- `background/verification-flow.js`：注册/登录验证码共享流程层，封装重发、轮询、提交、失败回退与自定义邮箱跳过逻辑。
+
+## `background/steps/`
+
+- `background/steps/confirm-oauth.js`：步骤 8 实现，负责 OAuth 同意页按钮定位、点击、localhost 回调监听与回调完成。
+- `background/steps/fetch-login-code.js`：步骤 7 实现，负责登录验证码阶段的邮箱轮询与回退控制。
+- `background/steps/fetch-signup-code.js`：步骤 4 实现，负责注册验证码阶段的页面准备与验证码流程入口。
+- `background/steps/fill-password.js`：步骤 3 实现，负责密码生成、保存、回填与提交。
+- `background/steps/fill-profile.js`：步骤 5 实现，负责姓名、生日填写与 ChatGPT onboarding 跳过流程。
+- `background/steps/oauth-login.js`：步骤 6 实现，负责刷新 OAuth 链接、登录和确保进入验证码页。
+- `background/steps/open-chatgpt.js`：步骤 1 实现，负责打开 ChatGPT 官网并确认入口就绪。
+- `background/steps/platform-verify.js`：步骤 9 实现，负责 CPA / SUB2API 回调验证。
+- `background/steps/registry.js`：步骤注册表工厂，负责用稳定的步骤元数据映射到执行器。
+- `background/steps/submit-signup-email.js`：步骤 2 实现，负责注册入口点击、邮箱提交与密码页等待。
+
+## `content/`
+
+- `content/activation-utils.js`：内容脚本通用激活策略工具，负责按钮点击方式判断等轻量辅助逻辑。
+- `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 邮箱轮询脚本，负责网页邮箱验证码读取和邮件清理。
+- `content/mail-2925.js`：2925 邮箱页面脚本，负责 2925 邮箱收件轮询与验证码匹配。
+- `content/qq-mail.js`：QQ 邮箱轮询脚本，负责网页邮箱验证码读取。
+- `content/signup-page.js`：注册/登录/授权主内容脚本，负责 OpenAI / ChatGPT 页面上的步骤执行。
+- `content/sub2api-panel.js`：SUB2API 后台内容脚本，负责获取 OAuth 地址和提交 localhost 回调。
+- `content/utils.js`：内容脚本公共工具层，负责日志、READY/COMPLETE/ERROR 上报、元素等待、输入与点击。
+- `content/vps-panel.js`：CPA 面板内容脚本，负责获取 OAuth 地址和提交回调 URL。
+
+## `data/`
+
+- `data/names.js`：随机姓名、生日等测试数据源。
+- `data/step-definitions.js`：共享步骤元数据，前后台共同使用，用于动态渲染和步骤注册。
+
+## `docs/`
+
+- `docs/Hotmail双模式适配开发方案及开发记录.md`：Hotmail 双模式接入的历史方案和开发记录。
+- `docs/仓库协作者AI分析PR与合并标准流程.md`：仓库协作者进行 AI 分析 PR 与合并时的流程说明。
+- `docs/images/交流群.jpg`：README 中展示的交流群图片资源。
+- `docs/images/十轮自动.png`：README 中展示的自动运行效果图。
+- `docs/images/微信.png`：README 中展示的微信收款码图片。
+- `docs/images/支付宝.jpg`：README 中展示的支付宝收款码图片。
+- `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`：本地 Hotmail helper 服务，负责通过本地接口协助获取邮件和验证码。
+
+## `sidepanel/`
+
+- `sidepanel/hotmail-manager.js`：侧边栏 Hotmail 账号池管理器，负责列表、导入、验证、测试收信和批量操作。
+- `sidepanel/icloud-manager.js`：侧边栏 iCloud 隐私邮箱管理器，负责列表、筛选、保留、删除和批量操作。
+- `sidepanel/luckmail-manager.js`：侧边栏 LuckMail 管理器，负责邮箱列表、筛选、启停、保留与批量操作。
+- `sidepanel/sidepanel.css`：侧边栏样式文件。
+- `sidepanel/sidepanel.html`：侧边栏页面结构，当前步骤列表已改为动态容器。
+- `sidepanel/sidepanel.js`：侧边栏主入口脚本，负责 UI 状态同步、动态步骤渲染、按钮交互与广播接收。
+- `sidepanel/update-service.js`：侧边栏更新检查服务，负责 GitHub Releases 查询与版本展示。
+
+## `tests/`
+
+- `tests/activation-utils.test.js`：测试内容脚本激活策略与 Step 9 可恢复错误判断。
+- `tests/auto-run-fresh-attempt-reset.test.js`：测试自动运行在新一轮开始前会重置旧运行时上下文。
+- `tests/auto-step-random-delay.test.js`：测试自动运行步间延迟与旧配置键兼容解析。
+- `tests/background-auto-run-module.test.js`：测试自动运行控制器模块已接入且导出工厂。
+- `tests/background-generated-email-module.test.js`：测试生成邮箱辅助模块已接入且导出工厂。
+- `tests/background-icloud.test.js`：测试 iCloud 相关后台纯函数与别名收尾逻辑。
+- `tests/background-icloud-mail-provider.test.js`：测试 iCloud 邮箱 provider 配置解析。
+- `tests/background-logging-status-module.test.js`：测试日志/状态模块已接入且导出工厂。
+- `tests/background-luckmail.test.js`：测试 LuckMail 相关后台逻辑，如购买、复用、标记已用与重置。
+- `tests/background-message-router-module.test.js`：测试消息路由模块已接入且导出工厂。
+- `tests/background-navigation-utils-module.test.js`：测试导航工具模块已接入且导出工厂。
+- `tests/background-panel-bridge-module.test.js`：测试面板桥接模块已接入且导出工厂。
+- `tests/background-signup-flow-module.test.js`：测试注册页辅助模块已接入且导出工厂。
+- `tests/background-step-modules.test.js`：测试步骤模块文件都已由后台入口加载。
+- `tests/background-step-registry.test.js`：测试后台步骤注册表和共享步骤定义已接入。
+- `tests/background-tab-runtime-module.test.js`：测试标签运行时模块已接入且导出工厂。
+- `tests/background-verification-flow-module.test.js`：测试验证码流程模块已接入且导出工厂。
+- `tests/cloudflare-temp-email-provider.test.js`：测试 Cloudflare Temp Email provider 的轮询与目标邮箱选择逻辑。
+- `tests/cloudflare-temp-email-utils.test.js`：测试 Cloudflare Temp Email 工具层的 URL、域名、邮件解析逻辑。
+- `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/microsoft-email.test.js`：测试 Microsoft 邮件拉取与验证码提取逻辑。
+- `tests/sidepanel-hotmail-manager.test.js`：测试侧边栏 Hotmail 管理器模块接线与空态渲染。
+- `tests/sidepanel-icloud-manager.test.js`：测试侧边栏 iCloud 管理器模块接线与空态渲染。
+- `tests/sidepanel-icloud-provider.test.js`：测试侧边栏 iCloud 登录地址解析逻辑。
+- `tests/sidepanel-luckmail-manager.test.js`：测试侧边栏 LuckMail 管理器模块接线与空态渲染。
+- `tests/signup-page-tab-cleanup.test.js`：测试注册页来源标签的冲突清理逻辑。
+- `tests/step-definitions-module.test.js`：测试共享步骤定义模块及侧边栏脚本加载顺序。
+- `tests/step5-chatgpt-onboarding.test.js`：测试 Step 5 的 ChatGPT onboarding 判断与跳过逻辑。
+- `tests/step5-chatgpt-redirect-race.test.js`：测试 Step 5 跨域跳转 race 下的 chatgpt.com 兜底判断。
+- `tests/step6-login-state.test.js`：测试 Step 6 登录状态判断逻辑。
+- `tests/step8-callback-handling.test.js`：测试 Step 8 回调地址捕获逻辑。
+- `tests/step8-debugger-stop.test.js`：测试 Step 8 调试器点击在 Stop 场景下的中止行为。
+- `tests/step8-state-timeout-retry.test.js`：测试 Step 8 通信错误是否可判定为可重试。
+- `tests/step8-stop-cleanup.test.js`：测试 Step 8 在 Stop 后能正确清理监听器与挂起状态。
+- `tests/step9-cpa-mode.test.js`：测试本地 CPA Step 9 策略判断。
+- `tests/step9-localhost-cleanup-scope.test.js`：测试 Step 9 仅清理精确命中的 localhost callback 和路径前缀残留页。
+- `tests/verification-stop-propagation.test.js`：测试验证码流程在 Stop 场景下的错误传播与不中途降级。