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

# 项目文件结构说明

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

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

- `.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、验证码匹配等归一化。
- `managed-alias-utils.js`：共享 Gmail / 2925 的别名邮箱规则，负责解析基邮箱、校验“当前完整注册邮箱”是否仍与基邮箱兼容、生成 Gmail `+tag` 与 2925 随机后缀邮箱，并输出 sidepanel 可复用的 UI 文案。
- `manifest.json`：Chrome 扩展清单，声明权限、背景脚本、侧边栏、内容脚本与规则集。
- `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`，并在启用独立本地 txt 留档配置后追加写入文本日志。
- `background/auto-run-controller.js`：自动运行主控制器，封装多轮执行、重试、轮次摘要、线程间隔与倒计时恢复逻辑；fresh-attempt reset 时会额外保留 `gmailBaseEmail` 与 `mail2925BaseEmail`，避免自动流程重置后丢失别名基邮箱配置。
- `background/generated-email-helpers.js`：生成邮箱辅助层，除了 Duck / Cloudflare / iCloud / Cloudflare Temp Email，也统一承接 Gmail / 2925 的别名邮箱生成入口。
- `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`：注册页辅助层，负责打开注册入口、等待密码页以及解析当前流程所用邮箱；在 Gmail / 2925 模式下会优先复用已经存在且仍兼容的完整注册邮箱，只有不兼容或为空时才重新生成。
- `background/tab-runtime.js`：标签页与内容脚本运行时基础设施，封装标签注册、冲突清理、消息超时、注入重试与队列。
- `background/verification-flow.js`：注册/登录验证码共享流程层，封装重发、轮询、提交、失败回退、自定义邮箱跳过以及 2925 长轮询参数。

## `background/steps/`

- `background/steps/clear-login-cookies.js`：步骤 6 实现，负责登录前 Cookie 清理。
- `background/steps/confirm-oauth.js`：步骤 9 实现，负责 OAuth 同意页按钮定位、点击、localhost 回调监听与回调完成。
- `background/steps/fetch-login-code.js`：步骤 8 实现，负责登录验证码阶段的邮箱轮询、验证码回填与回退控制。
- `background/steps/fetch-signup-code.js`：步骤 4 实现，负责注册验证码阶段的页面准备与验证码流程入口。
- `background/steps/fill-password.js`：步骤 3 实现，负责密码生成、保存、回填与提交。
- `background/steps/fill-profile.js`：步骤 5 实现，负责姓名、生日填写并把资料提交给注册页内容脚本。
- `background/steps/oauth-login.js`：步骤 7 实现，负责刷新 OAuth 链接、登录和确保进入验证码页。
- `background/steps/open-chatgpt.js`：步骤 1 实现，负责打开 ChatGPT 官网并确认入口就绪。
- `background/steps/platform-verify.js`：步骤 10 实现，负责 CPA / SUB2API 回调验证。
- `background/steps/registry.js`：步骤注册表工厂，负责用稳定的步骤元数据映射到执行器。
- `background/steps/submit-signup-email.js`：步骤 2 实现，负责注册入口点击、邮箱提交与提交后落地页分支判断。

## `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 邮箱轮询脚本，负责网页邮箱验证码读取和邮件清理。
- `content/mail-2925.js`：2925 邮箱页面脚本，负责 2925 邮箱收件轮询与验证码匹配。
- `content/qq-mail.js`：QQ 邮箱轮询脚本，负责网页邮箱验证码读取。
- `content/signup-page.js`：注册、登录、授权主内容脚本，负责 OpenAI / ChatGPT 页面上的步骤执行。
- `content/sub2api-panel.js`：SUB2API 后台内容脚本，负责获取 OAuth 地址和提交 localhost 回调；当前承接步骤 10。
- `content/utils.js`：内容脚本公共工具层，负责日志、READY / COMPLETE / ERROR 上报、元素等待、输入与点击。
- `content/vps-panel.js`：CPA 面板内容脚本，负责获取 OAuth 地址、提交回调 URL，并基于精确成功徽标与错误态做步骤 10 判定。

## `data/`

- `data/names.js`：随机姓名、生日等测试数据源。
- `data/step-definitions.js`：共享步骤元数据，前后台共同使用，用于动态渲染和步骤注册。

## `docs/`

- `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`：本地 helper 服务，负责通过本地接口协助 Hotmail 获取邮件和验证码，并提供账号运行历史文本追加接口。

## `sidepanel/`

- `sidepanel/hotmail-manager.js`：侧边栏 Hotmail 账号池管理器，负责列表、导入、验证、测试收信和批量操作。
- `sidepanel/icloud-manager.js`：侧边栏 iCloud 隐私邮箱管理器，负责列表、筛选、保留、删除和批量操作。
- `sidepanel/luckmail-manager.js`：侧边栏 LuckMail 管理器，负责邮箱列表、筛选、启停、保留与批量操作。
- `sidepanel/sidepanel.css`：侧边栏样式文件。
- `sidepanel/sidepanel.html`：侧边栏页面结构；当前步骤列表已改为动态容器，日志区标题下方预留账号运行历史摘要条带，且会加载 `managed-alias-utils.js`，把旧的“邮箱前缀”字段语义改为“别名基邮箱”。
- `sidepanel/sidepanel.js`：侧边栏主入口脚本，负责 UI 状态同步、动态步骤渲染、按钮交互、账号运行历史摘要渲染、独立 txt 留档配置与广播接收；同时把 Gmail / 2925 的基邮箱输入、完整注册邮箱输入、自动生成按钮与兼容性校验统一接到共享别名逻辑上。
- `sidepanel/update-service.js`：侧边栏更新检查服务，负责 GitHub Releases 查询与版本展示。

## `tests/`

- `tests/activation-utils.test.js`：测试内容脚本激活策略与平台回调可恢复错误判断。
- `tests/auth-page-recovery.test.js`：测试认证页共享恢复层的重试页识别与恢复行为。
- `tests/auto-run-fresh-attempt-reset.test.js`：测试自动运行在新一轮开始前会重置旧运行时上下文，并补充 `gmailBaseEmail` / `mail2925BaseEmail` 在 fresh reset 后仍被保留的回归验证。
- `tests/auto-run-step6-restart.test.js`：测试自动运行在后半段授权链路遇错时会回到步骤 7 重开，并在命中 add-phone 时停止重开。
- `tests/auto-step-random-delay.test.js`：测试自动运行步间延迟与旧配置键兼容解析。
- `tests/background-auto-run-module.test.js`：测试自动运行控制器模块已接入且导出工厂。
- `tests/background-account-run-history-module.test.js`：测试账号运行历史模块已接入、导出工厂，并能在不启用本地 helper 时正确持久化记录。
- `tests/background-account-history-settings.test.js`：测试账号运行历史的独立配置项归一化，不再复用 Hotmail 模式作为启停条件。
- `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-message-router-step2-skip.test.js`：测试步骤 2 直接落到验证码页时的跳步与状态保护逻辑。
- `tests/background-navigation-utils-module.test.js`：测试导航工具模块已接入且导出工厂。
- `tests/background-panel-bridge-module.test.js`：测试面板桥接模块已接入且导出工厂。
- `tests/background-signup-flow-module.test.js`：测试注册页辅助模块已接入且导出工厂。
- `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 的有限重试上限。
- `tests/background-step7-recovery.test.js`：测试步骤 8 在 CPA 模式下会先回放步骤 7 再提交登录验证码，并为 2925 关闭重发间隔。
- `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/managed-alias-utils.test.js`：覆盖 Gmail / 2925 共享别名工具的解析、生成、兼容性判断。
- `tests/microsoft-email.test.js`：测试 Microsoft 邮件拉取与验证码提取逻辑。
- `tests/sidepanel-hotmail-manager.test.js`：测试侧边栏 Hotmail 管理器模块接线与空态渲染。
- `tests/sidepanel-account-run-history.test.js`：测试侧边栏日志区下方的账号运行历史条带结构、独立留档配置控件与状态分类摘要逻辑。
- `tests/sidepanel-icloud-manager.test.js`：测试侧边栏 iCloud 管理器模块接线与空态渲染。
- `tests/sidepanel-icloud-provider.test.js`：测试侧边栏 iCloud 登录地址解析逻辑。
- `tests/sidepanel-luckmail-manager.test.js`：测试侧边栏 LuckMail 管理器模块接线与空态渲染。
- `tests/signup-entry-diagnostics.test.js`：测试注册入口诊断快照输出。
- `tests/signup-page-tab-cleanup.test.js`：测试注册页来源标签的冲突清理逻辑。
- `tests/step-definitions-module.test.js`：测试共享步骤定义模块及侧边栏脚本加载顺序。
- `tests/step3-direct-complete.test.js`：测试步骤 3 在提交前先完成上报。
- `tests/step5-direct-complete.test.js`：测试步骤 5 在资料页点击提交后立即完成当前步骤。
- `tests/step6-login-state.test.js`：测试 OAuth 登录状态识别逻辑，当前对应步骤 7 链路。
- `tests/step6-timeout-recovery.test.js`：测试 OAuth 登录超时报错页的可恢复结果构造，当前对应步骤 7 链路。
- `tests/step8-callback-handling.test.js`：测试 localhost 回调地址捕获逻辑，当前对应步骤 9。
- `tests/step8-debugger-stop.test.js`：测试调试器点击在 Stop 场景下的中止行为，当前对应步骤 9。
- `tests/step8-retry-page-recovery.test.js`：测试 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/verification-stop-propagation.test.js`：测试验证码流程在 Stop 场景下的错误传播与不中途降级。
- `tests/verification-flow-polling.test.js`：测试 2925 长轮询参数，以及验证码提交流程中的 `beforeSubmit` 钩子执行顺序。