From 74820b8bb2e3aaa0c36c0518437453ce5ead1ae3 Mon Sep 17 00:00:00 2001 From: Q3CC Date: Sat, 16 May 2026 22:13:22 +0800 Subject: [PATCH] docs: document YYDS Mail provider integration --- README.md | 23 +++++++++++++++++++++-- 项目完整链路说明.md | 23 +++++++++++++++++++++++ 项目文件结构说明.md | 12 ++++++++---- 3 files changed, 52 insertions(+), 6 deletions(-) diff --git a/README.md b/README.md index 6ea1b06..0e8b31d 100644 --- a/README.md +++ b/README.md @@ -2,7 +2,7 @@ 一个用于批量跑通 ChatGPT OAuth 注册/登录流程的 Chrome 扩展。 -当前版本基于侧边栏控制，支持单步执行、整套自动执行、停止当前流程、保存常用配置，以及通过 DuckDuckGo / QQ / 163 / 163 VIP / 126 / Inbucket / Hotmail / Cloud Mail 协助获取验证码。 +当前版本基于侧边栏控制，支持单步执行、整套自动执行、停止当前流程、保存常用配置，以及通过 DuckDuckGo / QQ / 163 / 163 VIP / 126 / Inbucket / Hotmail / Cloud Mail / YYDS Mail 协助获取验证码。 ## 插件效果 @@ -39,6 +39,7 @@ - 支持 `Hotmail`：继续使用 `邮箱 + 客户端 ID + 刷新令牌（refresh token）`，并可在远程服务与本地助手两种模式间切换 - 支持 `2925`：新增多账号池、自动登录登出、Step 4 / Step 8 命中“子邮箱已达上限邮箱”后的 24 小时禁用与自动切号 - 支持 `Cloud Mail`：可通过 skymail.ink API 生成自定义域邮箱，也可作为转发收件通道轮询验证码 +- 支持 `YYDS Mail`：通过 API Key 自动创建临时邮箱，并用返回的临时 Bearer token 读取验证码邮件 - 支持 `QQ Mail`、`163 Mail`、`163 VIP Mail`、`126 Mail`、`Inbucket mailbox` - 支持从 DuckDuckGo Email Protection 自动生成新的 `@duck.com` 地址 - 支持基于 Cloudflare 自定义域名自动生成随机邮箱前缀 @@ -207,11 +208,12 @@ Step 1 和 Step 10 都依赖这个地址。 ### `Mail` -支持八种验证码来源： +支持九种验证码来源： - `Hotmail` - `2925` - `Cloud Mail` +- `YYDS Mail` - `163 Mail` - `163 VIP Mail` - `126 Mail` @@ -223,9 +225,26 @@ Step 1 和 Step 10 都依赖这个地址。 - `Hotmail` 通过侧边栏里的 Hotmail 账号池选择账号，可切换为远程服务模式或本地助手模式 - `2925` 通过侧边栏里的 2925 账号池选择账号，并在 Step 4 / Step 8 前自动校验网页邮箱登录态 - `Cloud Mail` 通过侧边栏配置 API 地址、管理员账号、接收邮箱或生成域名，可直接生成邮箱或轮询转发收件箱 +- `YYDS Mail` 通过侧边栏配置 API Key 与 Base URL；点击“获取”或自动运行时会创建新的临时邮箱，Step 4 / Step 8 使用返回的临时 token 轮询验证码 - `QQ`、`163`、`163 VIP`、`126` 用于直接轮询网页邮箱 - `Inbucket` 通过你在侧边栏里配置的 host 访问 `mailbox` 页面：`https:///m//` +### `YYDS Mail` + +仅当 `Mail = YYDS Mail` 时使用。 + +可配置项： + +- `API Key`：用于创建临时邮箱，请求头为 `X-API-Key` +- `Base URL`：默认 `https://maliapi.215.im/v1`，可按自建或兼容服务地址修改 + +行为说明： + +1. 点击注册邮箱区域的 `获取`，或 Auto 每轮准备邮箱时，扩展会调用 `POST /accounts` 创建临时邮箱。 +2. 创建请求只发送 `localPart`；最终注册邮箱以后端返回的 `address` 为准。 +3. 后台保存本轮返回的临时 `token`，Step 4 / Step 8 通过 `Bearer token` 读取 `/messages` 与 `/messages/{id}`。 +4. 平台验证完成或重置当前流程后，会清空本轮 YYDS Mail 邮箱运行态；API Key 与 Base URL 配置会保留，下一轮重新创建邮箱。 + ### `Hotmail 账号池` 仅当 `Mail = Hotmail` 时使用。 diff --git a/项目完整链路说明.md b/项目完整链路说明.md index 62c52cb..df45edc 100644 --- a/项目完整链路说明.md +++ b/项目完整链路说明.md @@ -172,6 +172,7 @@ - 标签注册表 - 最近打开的来源地址 - LuckMail 当前运行时选择 +- YYDS Mail 当前运行时邮箱 `currentYydsMailInbox`，保存本轮创建得到的最终邮箱地址和临时 Bearer token - 2925 当前选中的账号 ID `currentMail2925AccountId`（运行时会同步到持久配置，用于重开浏览器后恢复同一个号池账号） 补充： @@ -190,6 +191,7 @@ - PayPal 账号池配置 `paypalAccounts / currentPayPalAccountId`，以及供后台步骤兼容读取的 `paypalEmail / paypalPassword` - 邮箱 provider 配置 - Cloud Mail / SkyMail API 配置：`cloudMailBaseUrl / cloudMailAdminEmail / cloudMailAdminPassword / cloudMailToken / cloudMailReceiveMailbox / cloudMailDomain / cloudMailDomains` +- YYDS Mail API 配置：`yydsMailApiKey / yydsMailBaseUrl`；reset 会保留这两个持久配置，但清空 `currentYydsMailInbox`，确保下一轮重新创建临时邮箱 - Hotmail 账号池 - 2925 账号池 - 2925 是否启用号池模式 `mail2925UseAccountPool` @@ -681,6 +683,7 @@ Plus 模式可见步骤： - Cloudflare - Cloudflare Temp Email - Cloud Mail +- YYDS Mail - 自定义邮箱池 - iCloud 隐私邮箱 @@ -707,6 +710,26 @@ Plus 模式可见步骤： 4. 邮件读取统一走 `/api/public/emailList`，返回数据先经 `cloudmail-utils.js` 归一化，再复用现有验证码匹配与时间窗过滤逻辑。 5. 如果 Token 失效，后台会尝试重新登录刷新 Token 后重试当前 API 请求。 +### 7.1.2 YYDS Mail + +组成： + +- [yyds-mail-utils.js](c:/Users/projectf/Downloads/codex注册扩展/yyds-mail-utils.js) +- [background/yyds-mail-provider.js](c:/Users/projectf/Downloads/codex注册扩展/background/yyds-mail-provider.js) +- [background/verification-flow.js](c:/Users/projectf/Downloads/codex注册扩展/background/verification-flow.js) +- [sidepanel/sidepanel.html](c:/Users/projectf/Downloads/codex注册扩展/sidepanel/sidepanel.html) +- [sidepanel/sidepanel.js](c:/Users/projectf/Downloads/codex注册扩展/sidepanel/sidepanel.js) + +链路： + +1. 侧栏在 `Mail = YYDS Mail` 时只展示 `API Key` 与 `Base URL`，不展示普通邮箱生成、转发邮箱或账号池配置。 +2. 持久配置只保存 `yydsMailApiKey / yydsMailBaseUrl`；本轮真实邮箱和临时 token 只保存在运行态 `currentYydsMailInbox`。 +3. 手动点击“获取”、Step 3 需要生成邮箱、或 Auto 每轮准备邮箱时，后台通过 `POST /accounts` 创建邮箱，请求头使用 `X-API-Key`，请求体只发送自动生成或用户传入的 `localPart`。 +4. 创建成功后以后端返回的最终 `address` 为准回写 `email / registrationEmailState`，并把返回的 `token` 写入 `currentYydsMailInbox`，Step 8 `add-email` 的手机号身份链路仍通过共享注册邮箱状态持久化保留 `signupPhone* / accountIdentifier*`。 +5. Step 4 / Step 8 轮询验证码时，`background/verification-flow.js` 会把 `provider = yyds-mail` 路由到后台 provider；后台用临时 token 发送 `Authorization: Bearer ` 调用 `/messages` 与 `/messages/{id}`，再复用现有验证码匹配、时间窗、排除旧验证码等规则。 +6. 平台验证完成后的成功收尾会清空 `currentYydsMailInbox` 与当前邮箱运行态，下一轮重新创建新的 YYDS Mail 邮箱。 +7. `reset` 保留 YYDS Mail 的 API Key / Base URL 配置，但清空当前邮箱运行态，避免旧临时 token 被下一轮误用。 + ### 7.2 Hotmail 组成： diff --git a/项目文件结构说明.md b/项目文件结构说明.md index 0371d96..d81f0c0 100644 --- a/项目文件结构说明.md +++ b/项目文件结构说明.md @@ -28,7 +28,8 @@ - `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 的归一化、选项列表和收码入口配置。 +- `yyds-mail-utils.js`：YYDS Mail 相关的纯工具函数，负责 API 地址、API Key、临时邮箱、Bearer token、邮件列表/详情、验证码字段与 Graph-like 邮件结构归一化。 +- `mail-provider-utils.js`：网页邮箱 provider 配置纯工具，负责 `163 / 163 VIP / 126 / QQ / Inbucket / Hotmail / YYDS Mail` 的基础归一化与页面入口配置，并统一承接 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。 @@ -49,6 +50,7 @@ - `background/auto-run-controller.js`：自动运行主控制器，封装多轮执行、重试、轮次摘要、线程间隔与倒计时恢复逻辑；当前自动流程会绑定 `autoRunSessionId`，手动停止后旧的倒计时计划、旧重试链路和旧恢复入口不会再复活已失效的自动运行；fresh-attempt reset 时会额外保留 Plus 模式与 PayPal 配置、`gmailBaseEmail`、`mail2925BaseEmail` 与当前 2925 账号选择，避免自动流程重置后丢失关键持久配置。 - `background/contribution-oauth.js`：贡献模式的公开 OAuth 流程模块，负责调用 `flowpilot.qlhazycoder.top` 的公开贡献接口、保存贡献会话运行态、在主 10 步流程里为步骤 7 提供贡献登录地址、在步骤 9/10 衔接 callback 捕获与兼容提交 `/oauth/api/submit-callback`，并把真实服务端状态映射回 sidepanel 运行态。 - `background/cloudmail-provider.js`：Cloud Mail / SkyMail 后台 provider 模块，负责 Token 获取、邮箱创建、邮件列表读取、验证码轮询和生成/转发收件目标邮箱选择；新生成的 Cloud Mail 地址会统一走共享注册邮箱状态持久化，既回写带来源标记的注册邮箱运行态，也能在 Step 8 `add-email` 的手机号身份链路中保留 `signupPhone* / accountIdentifier*`。 +- `background/yyds-mail-provider.js`：YYDS Mail 后台 provider 模块，负责通过 `X-API-Key` 创建临时邮箱、保存返回的地址与临时 Bearer token、按 `/messages` 与 `/messages/{id}` 读取验证码邮件，并在成功收尾或 reset 时清空当前运行态邮箱。 - `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` 时，会按当前目标轮次读取邮箱池中的对应邮箱；Duck 生成前会优先结合 `registrationEmailState` 与侧栏当前可见邮箱解析对比基线，避免重复拿到旧地址；所有生成结果都会统一走共享注册邮箱状态持久化，普通邮箱流仍切回邮箱身份，Step 8 `add-email` 的手机号身份流则保留当前手机号身份。 - `background/ip-proxy-core.js`：IP 代理核心模块，负责代理条目解析、账号/接口代理池运行态、PAC 应用与清除、代理鉴权回填、出口探测、失败时的目标站点 fail-close 防漏规则，以及自动运行成功阈值后的代理切换支撑。 - `background/ip-proxy-provider-711proxy.js`：711Proxy provider 规则模块，负责从账号串中识别和写回 `region / session / sessTime` 等参数，并在固定账号模式下把侧栏配置转换为最终生效的代理账号。 @@ -63,7 +65,7 @@ - `background/sub2api-api.js`：SUB2API 管理接口直连模块，负责后台登录 SUB2API、解析 openai 分组、按配置选择代理、生成 OpenAI OAuth 地址、交换 localhost callback 授权码并创建 SUB2API 账号；主链路不再依赖 SUB2API 后台页面 DOM 自动化。 - `background/signup-flow-helpers.js`：注册页辅助层，负责打开注册入口、Step 2 打开入口页后的加载完成与额外 3 秒稳定等待、等待密码页以及解析当前流程所用邮箱；在 Gmail 与 `2925 + provide` 模式下会优先复用已经存在且仍兼容的完整注册邮箱，只有不兼容或为空时才重新生成；当 provider 为 2925 且启用了 provide 模式下的号池时，会先确保账号池中已选中可用账号；若邮箱生成器在生成阶段已经写回运行态，这里不会再重复覆盖 `registrationEmailState`，但仍会在 Step 8 `add-email` 的手机号身份场景下通过共享持久化按需保留手机号身份。 - `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/verification-flow.js`：注册/登录验证码共享流程层，封装重发、轮询、提交、失败回退、自定义邮箱跳过、共享验证码自动重发次数配置、Cloud Mail / YYDS Mail API 轮询以及 2925 长轮询参数；日志步骤号使用 `completionStep`，因此 Plus 登录验证码会显示可见第 11 步而不是内部复用的 Step 8；当前验证码提交重试上限为 15 次，2925 每次重发验证码之间都会固定跑完一轮 15 次邮箱刷新轮询；若 `mail2925Mode = receive`，会额外把目标注册邮箱传给 2925 内容脚本做弱匹配；若登录验证码提交后页面转入 `add-phone / 手机号页`，则会把“后续需要手机号验证”的结果继续传给 OAuth 确认步骤，而不是误判为普通失败；若登录验证码提交后通信中断但认证页已进入 OAuth 同意页或手机号验证页，会按真实页面状态继续后续流程；若 2925 轮询命中“子邮箱已达上限邮箱”，会转入 2925 会话模块执行“记录时间、禁用 24 小时、切下一个账号并重新登录”，然后直接结束当前尝试。 ## `background/steps/` @@ -160,7 +162,7 @@ 名基邮箱”；当 provider 为 2925 时，会额外显示 `提供邮箱 / 接收邮箱` 模式切换，并把“2925 号池”从别名基邮箱行拆成独立配置行，避免 receive 模式把账号池开关一起隐藏；当前在 `邮箱生成` 区域新增 `自定义邮箱池` 选项和多行邮箱池输入框，并在 `邮箱服务 = 自定义邮箱` 时 额外显示 `自定义号池` 文本框；当邮箱服务为 iCloud 时，额外提供目标邮箱类型与转发邮箱 provider 配置，用于选择直接从 iCloud 收件箱收 - 码或从 QQ / 网易 / Gmail 转发目标邮箱收码；当邮箱服务或邮箱生成器为 Cloud Mail 时，额外显示 API 地址、管理员账号、接收邮箱和生成域名配置行；来源下拉框当前支持 `CPA / SUB2API / Codex2API`，其中 Codex2API 额外提供后台地址和管理密 + 码或从 QQ / 网易 / Gmail 转发目标邮箱收码；当邮箱服务或邮箱生成器为 Cloud Mail 时，额外显示 API 地址、管理员账号、接收邮箱和生成域名配置行；当邮箱服务为 YYDS Mail 时，额外显示 API Key 与 Base URL 配置行，并隐藏普通邮箱生成/转发邮箱相关配置；来源下拉框当前支持 `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 状态同步、动态步骤渲染、按钮交互、共享验证码自动重发次数配置与广播接收，并装 @@ -168,7 +170,7 @@ 动逻辑，而独立 manager 负责贡献运行态展示与轮询，同时把 Gmail / 2925 的基邮箱输入、完整注册邮箱输入、自动生成按钮与兼容性校验统一接 到共享别名逻辑上；当 provider 为 2925 时，会根据 `mail2925Mode` 决定是否启用别名基邮箱链路，而 2925 号池开关与当前账号选择则独立显 示并同时服务于 provide / receive 两种模式；当 provider 为 iCloud 时，会保存并回显目标邮箱类型与转发邮箱 provider，相关 provider 选 - 项和 label 复用 `mail-provider-utils.js`；Cloud Mail 配置保存、回显和显隐由这里接入，可分别服务于邮箱生成器和转发收件 provider；手动点击“获取/生成邮箱”时，这里会把输入框当前可见邮箱一并传给后台，作为 Duck 新地址检测的优先对比基线；`自定义邮箱池` 模式会按邮箱池长度锁定自动轮数，并把当前输入的邮箱池配置参与自动启动前保 + 项和 label 复用 `mail-provider-utils.js`；Cloud Mail 配置保存、回显和显隐由这里接入，可分别服务于邮箱生成器和转发收件 provider；YYDS Mail 配置保存、回显和显隐由这里接入，只暴露 API Key / Base URL，并在点击“获取”或自动运行时委托后台创建临时邮箱；手动点击“获取/生成邮箱”时，这里会把输入框当前可见邮箱一并传给后台，作为 Duck 新地址检测的优先对比基线；`自定义邮箱池` 模式会按邮箱池长度锁定自动轮数，并把当前输入的邮箱池配置参与自动启动前保 存；点击“自动”时会先冻结当时的目标轮数，避免启动前的异步刷新、保存或后台旧状态回灌把输入框重置为 1；`邮箱服务 = 自定义邮箱` 时，如果配置了 `customMailProviderPool`，也会按号池长度锁定自动轮数并在 Auto 中按轮次分配注册邮箱，同时 在普通失败时继续复用当前邮箱，只有成功或出现手机号验证时才切换下一个邮箱；Plus 模式开启后，步骤列表会切换为 13 步，并显示 PayPal 账 号下拉框与添加入口；当前选中的 PayPal 账号会同步回兼容字段 `paypalEmail / paypalPassword` 供后台步骤复用；Step 8 的自定义邮箱确认弹 @@ -233,6 +235,8 @@ - `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/yyds-mail-provider.test.js`：测试 YYDS Mail provider 创建邮箱、临时 token 收信、邮件详情读取、验证码轮询与运行态清理逻辑。 +- `tests/yyds-mail-utils.test.js`：测试 YYDS Mail 工具层的 Base URL、请求头、邮箱响应、邮件列表/详情与验证码字段归一化逻辑。 - `tests/content-utils.test.js`：测试内容脚本公共工具层对 `mail.126.com` 等网页邮箱来源的识别逻辑。 - `tests/duck-mail-content.test.js`：测试 Duck 页面脚本会等待页面现有地址或显式基线出现后再比较新地址，并要求新地址稳定渲染后才判定生成成功。 - `tests/hotmail-api-mode.test.js`：测试 Hotmail API 模式相关文案和集成方式。