Hermes/FlowPilot
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
ccea024f9af1f463231782833be7b8071487e0c4
FlowPilot/项目文件结构说明.md
T

18 KiB
Raw Blame History

项目文件结构说明

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

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

  • .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：邮箱记录模块，负责把旧的 append-only 结果流水归一化为成功/失败摘要记录，落地到 chrome.storage.local，支持清理记录，并在启用独立本地同步配置后把完整快照同步到本地 helper。
  • 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 获取邮件和验证码，并提供邮箱记录 JSON 快照同步接口；旧的文本追加接口仍保留作兼容。

sidepanel/

  • sidepanel/hotmail-manager.js：侧边栏 Hotmail 账号池管理器，负责列表、导入、验证、测试收信和批量操作。
  • sidepanel/icloud-manager.js：侧边栏 iCloud 隐私邮箱管理器，负责列表、筛选、保留、删除和批量操作。
  • sidepanel/luckmail-manager.js：侧边栏 LuckMail 管理器，负责邮箱列表、筛选、启停、保留与批量操作。
  • sidepanel/account-records-manager.js：侧边栏邮箱记录面板管理器，负责“记录”按钮、覆盖层开关、分页列表、统计摘要和清理确认。
  • sidepanel/sidepanel.css：侧边栏样式文件。
  • sidepanel/sidepanel.html：侧边栏页面结构；当前步骤列表已改为动态容器，日志区提供“记录”按钮并挂接邮箱记录覆盖层，同时新增共享“验证码重发”次数输入，并加载 managed-alias-utils.js，把旧的“邮箱前缀”字段语义改为“别名基邮箱”。
  • sidepanel/sidepanel.js：侧边栏主入口脚本，负责 UI 状态同步、动态步骤渲染、按钮交互、独立本地同步配置、共享验证码自动重发次数配置与广播接收，并装配 Hotmail / iCloud / LuckMail / 邮箱记录面板 manager；同时把 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：测试邮箱记录模块已接入、导出工厂，能够过滤停止记录、归一化失败标签、计算自动重试次数，并支持清理后同步完整快照。
  • 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-records-manager.test.js：测试侧边栏邮箱记录覆盖层的 HTML 接入、helper 地址归一化与 manager 渲染逻辑。
  • 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 钩子执行顺序。
Reference in New Issue View Git Blame Copy Permalink