From 6056a94d91c05c65897156aa3a28e194b320e110 Mon Sep 17 00:00:00 2001
From: QLHazyCoder <qlhazycoder@users.noreply.github.com>
Date: Tue, 5 May 2026 04:57:30 +0800
Subject: [PATCH] =?UTF-8?q?feat:=20=E5=88=A0=E9=99=A4=E8=BF=87=E6=97=B6?=
 =?UTF-8?q?=E7=9A=84=20Hotmail=20OAuth=20=E7=9B=B8=E5=85=B3=E6=96=87?=
 =?UTF-8?q?=E6=A1=A3?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

---
 .../2026-04-16-architecture-refactor-plan.md  | 189 ------------
 .../2026-04-10-hotmail-oauth-mail-pool.md     | 271 ------------------
 .../specs/2026-04-10-hotmail-oauth-design.md  | 197 -------------
 3 files changed, 657 deletions(-)
 delete mode 100644 docs/refactor/2026-04-16-architecture-refactor-plan.md
 delete mode 100644 docs/superpowers/plans/2026-04-10-hotmail-oauth-mail-pool.md
 delete mode 100644 docs/superpowers/specs/2026-04-10-hotmail-oauth-design.md

diff --git a/docs/refactor/2026-04-16-architecture-refactor-plan.md b/docs/refactor/2026-04-16-architecture-refactor-plan.md
deleted file mode 100644
index 180198a..0000000
--- a/docs/refactor/2026-04-16-architecture-refactor-plan.md
+++ /dev/null
@@ -1,189 +0,0 @@
-# 2026-04-16 Architecture Refactor Plan
-
-## 目标
-
-在不破坏现有 1~9 步自动化流程、消息流、状态机和测试保护面的前提下，逐步拆分当前超大的主文件，降低后续开发和排障成本。
-
-## 当前事实
-
-- 这是一个无构建步骤的 Manifest V3 扩展。
-- `background.js` 是 classic service worker，当前依赖 `importScripts(...)`。
-- `sidepanel/sidepanel.html` 通过多个 `<script>` 直接加载脚本。
-- 运行态核心链路依赖：
-  - `chrome.storage.session` 保存流程态
-  - `chrome.storage.local` 保存配置态
-  - `chrome.runtime.sendMessage` 贯穿 sidepanel / background / content scripts
-  - `chrome.tabs` / `chrome.webNavigation` / `chrome.debugger` 支撑步骤执行
-- 测试不仅验证行为，还会直接从 `background.js` / `sidepanel.js` / `content/*.js` 按函数名提取源码执行。
-
-## 已确认基线
-
-- `bun test` 当前基线：`84 pass / 0 fail`
-- 关键大文件规模：
-  - `background.js`: 7481 行
-  - `sidepanel/sidepanel.js`: 4531 行
-  - `content/signup-page.js`: 1969 行
-
-## 当前结构压力点
-
-### `background.js`
-
-- 状态/配置、邮箱提供者、Tab 管理、消息路由、自动运行状态机、步骤 1~9 全部集中在单文件。
-- 文件内同时存在：
-  - 纯函数
-  - 网络请求
-  - 存储读写
-  - 浏览器 API 调度
-  - 步骤业务逻辑
-- 风险最高的区域不是“代码长”，而是“跨区域共享状态太多”。
-
-### `sidepanel/sidepanel.js`
-
-- 同时承担：
-  - DOM 查询
-  - 状态同步
-  - 配置读写
-  - 多个 provider 管理器
-  - 按钮事件绑定
-  - background 广播处理
-- Hotmail / LuckMail / iCloud 三块都已经是天然的 feature slice，但仍堆在一个文件里。
-
-## 重构硬约束
-
-### 约束 1：先拆“强内聚功能块”，后拆“流程主干”
-
-优先拆：
-
-- Hotmail 账号池 UI
-- LuckMail 管理 UI
-- iCloud 别名管理 UI
-- CPA / SUB2API 面板桥接层
-
-暂缓拆：
-
-- `executeStep1~9`
-- `autoRunLoop`
-- `handleMessage`
-- `resolveVerificationStep`
-
-原因：这些主干函数既是运行核心，也是当前测试抽取最密集的区域。
-
-### 约束 2：第一阶段尽量不改变被测试函数的“定义位置”
-
-由于现有测试会直接从源文件提取函数源码，第一阶段要避免大规模把被测函数从原文件移走。
-
-### 约束 3：运行边界不能变
-
-以下运行边界必须保持：
-
-- `background.js` 继续是 service worker 入口
-- `sidepanel/sidepanel.html` 继续是 sidepanel 入口
-- content script 注入方式不变
-- 所有 runtime message type 不变
-- storage key 不变
-
-## 目标结构
-
-### 背景层目标
-
-```txt
-background.js
-background/
-  state/
-    settings.js
-    session-state.js
-  runtime/
-    tabs.js
-    command-queue.js
-    logging.js
-    message-router.js
-  providers/
-    hotmail.js
-    luckmail.js
-    icloud.js
-    generated-email.js
-  steps/
-    step1.js
-    step2.js
-    step3.js
-    verification.js
-    step5.js
-    step6.js
-    step7.js
-    step8.js
-    step9.js
-  auto-run/
-    scheduler.js
-    loop.js
-```
-
-### Sidepanel 层目标
-
-```txt
-sidepanel/sidepanel.js
-sidepanel/
-  hotmail-manager.js
-  luckmail-manager.js
-  icloud-manager.js
-  auto-run-ui.js
-  runtime-listeners.js
-  update-service.js
-```
-
-## 分阶段执行顺序
-
-### Phase 1
-
-先拆 `sidepanel` 的强内聚管理区块。
-
-- 先拆 Hotmail manager
-- 再拆 iCloud manager
-- 再拆 LuckMail manager
-
-原因：
-
-- 不触碰主流程状态机
-- 风险主要局限在 sidepanel UI
-- 可以验证“多脚本 + 工厂上下文”的拆分模式
-
-### Phase 2
-
-拆 `background.js` 中和主流程相对解耦的桥接层。
-
-- CPA / SUB2API OAuth 桥接
-- 邮箱 provider 的 API 访问层
-- Cloudflare / Duck / iCloud 生成邮箱层
-
-### Phase 3
-
-拆 `background.js` 中的运行时基础设施。
-
-- tab registry
-- command queue
-- logging
-- storage helpers
-
-### Phase 4
-
-最后拆步骤执行器与 auto-run 主循环。
-
-- `executeStep1~9`
-- `resolveVerificationStep`
-- `autoRunLoop`
-
-## 第一阶段落地策略
-
-本轮先做：
-
-1. 新增 `sidepanel/hotmail-manager.js`
-2. 让 `sidepanel.js` 通过工厂方式接入 Hotmail manager
-3. 不改变 runtime message type
-4. 不改变 Hotmail 区块的 UI 行为
-5. 跑现有测试确认基线仍然成立
-
-## 验收标准
-
-- `bun test` 继续全绿
-- sidepanel Hotmail 区块行为无回归
-- `sidepanel.js` 不再直接承载 Hotmail 账号池的大段渲染和事件逻辑
-- 后续可以按同样模式继续拆 iCloud / LuckMail
diff --git a/docs/superpowers/plans/2026-04-10-hotmail-oauth-mail-pool.md b/docs/superpowers/plans/2026-04-10-hotmail-oauth-mail-pool.md
deleted file mode 100644
index 820ba69..0000000
--- a/docs/superpowers/plans/2026-04-10-hotmail-oauth-mail-pool.md
+++ /dev/null
@@ -1,271 +0,0 @@
-# Hotmail OAuth Mail Pool Implementation Plan
-
-> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking.
-
-**Goal:** Add a Hotmail account pool with Microsoft OAuth authorization and Microsoft Graph mail polling, then wire it into the existing automation flow as a new mail provider.
-
-**Architecture:** Keep the existing 1~9 step orchestrator in `background.js`, add a new `hotmail-api` provider path, and extend the side panel to manage Hotmail accounts. Preserve QQ, 163, and Inbucket behavior while introducing account allocation, token management, and Graph-based verification-code retrieval.
-
-**Tech Stack:** Chrome Extension MV3, plain JavaScript, `chrome.identity.launchWebAuthFlow`, `fetch`, `chrome.storage.local`, `chrome.storage.session`
-
----
-
-### Task 1: Extend State Model for Hotmail Accounts
-
-**Files:**
-- Modify: `background.js`
-- Modify: `README.md`
-
-- [ ] **Step 1: Write the failing test**
-
-Document the expected account shape and provider behavior in code comments or development notes before implementation:
-
-```js
-// Expected local storage shape:
-// hotmailAccounts: [{ id, email, password, clientId, accessToken, refreshToken, expiresAt, status, lastUsedAt, lastAuthAt, lastError }]
-// mailProvider accepts 'hotmail-api'
-```
-
-- [ ] **Step 2: Run test to verify it fails**
-
-Run a manual smoke check by loading the current extension and confirming there is no `hotmail-api` provider and no persisted Hotmail account state.
-
-Expected: The provider does not exist yet and account state is absent.
-
-- [ ] **Step 3: Write minimal implementation**
-
-Add new persisted keys and runtime state helpers in `background.js`:
-
-- `hotmailAccounts`
-- `currentHotmailAccountId`
-- helper functions to read, write, upsert, delete, and mark account status
-
-- [ ] **Step 4: Run test to verify it passes**
-
-Reload the extension and confirm Hotmail account state can be read and written through background message handlers.
-
-- [ ] **Step 5: Commit**
-
-```bash
-git add background.js README.md
-git commit -m "feat: add hotmail account state model"
-```
-
-### Task 2: Add Hotmail Account Pool UI
-
-**Files:**
-- Modify: `sidepanel/sidepanel.html`
-- Modify: `sidepanel/sidepanel.css`
-- Modify: `sidepanel/sidepanel.js`
-
-- [ ] **Step 1: Write the failing test**
-
-Describe the expected UI state:
-
-- provider selector includes `hotmail-api`
-- Hotmail account section renders a list
-- user can add, authorize, test, and delete accounts
-
-- [ ] **Step 2: Run test to verify it fails**
-
-Reload the current extension.
-
-Expected: No Hotmail provider option and no account section.
-
-- [ ] **Step 3: Write minimal implementation**
-
-Add:
-
-- a new provider option
-- a Hotmail accounts management section
-- side panel event handlers for add, authorize, test, delete, and select current account status
-
-- [ ] **Step 4: Run test to verify it passes**
-
-Reload the extension and verify:
-
-- the new provider is visible
-- the section appears only when selected
-- account rows render correctly from stored state
-
-- [ ] **Step 5: Commit**
-
-```bash
-git add sidepanel/sidepanel.html sidepanel/sidepanel.css sidepanel/sidepanel.js
-git commit -m "feat: add hotmail account pool panel"
-```
-
-### Task 3: Implement Microsoft OAuth Authorization
-
-**Files:**
-- Modify: `background.js`
-- Modify: `manifest.json`
-
-- [ ] **Step 1: Write the failing test**
-
-Define the expected authorization flow in a focused helper-oriented checklist:
-
-- PKCE code verifier/challenge can be created
-- auth URL includes client ID, redirect URI, state, scope, and challenge
-- callback code is parsed and validated
-- token response updates the account record
-
-- [ ] **Step 2: Run test to verify it fails**
-
-Trigger the new `Authorize` action from the side panel.
-
-Expected: The action is not implemented yet and fails.
-
-- [ ] **Step 3: Write minimal implementation**
-
-Add background handlers and helpers for:
-
-- PKCE generation
-- OAuth URL creation
-- `chrome.identity.getRedirectURL()`
-- `chrome.identity.launchWebAuthFlow`
-- code exchange via Microsoft token endpoint
-- account token persistence and error reporting
-
-- [ ] **Step 4: Run test to verify it passes**
-
-Manually authorize a Hotmail account and confirm:
-
-- the login flow opens
-- tokens are saved to the target account
-- account status becomes `authorized`
-
-- [ ] **Step 5: Commit**
-
-```bash
-git add background.js manifest.json
-git commit -m "feat: add microsoft oauth authorization"
-```
-
-### Task 4: Implement Token Refresh and Graph Mail Polling
-
-**Files:**
-- Modify: `background.js`
-
-- [ ] **Step 1: Write the failing test**
-
-Define the expected helper behavior:
-
-- expired access token refreshes with `refresh_token`
-- Graph mail fetch returns recent inbox messages
-- filtering returns the newest matching verification code after the requested timestamp
-
-- [ ] **Step 2: Run test to verify it fails**
-
-Use the side panel `Test Mail Access` action before implementing the Graph path.
-
-Expected: The action fails because Graph mail polling does not exist yet.
-
-- [ ] **Step 3: Write minimal implementation**
-
-Add helpers in `background.js` for:
-
-- token freshness check
-- refresh-token grant request
-- Graph inbox fetch
-- mail filtering
-- verification code extraction
-
-- [ ] **Step 4: Run test to verify it passes**
-
-Authorize a Hotmail account and verify the test action can fetch mailbox data and surface a success or meaningful “no matching mail” response.
-
-- [ ] **Step 5: Commit**
-
-```bash
-git add background.js
-git commit -m "feat: add graph mail polling"
-```
-
-### Task 5: Wire Hotmail Provider into Step 3, Step 4, Step 7, and Auto Run
-
-**Files:**
-- Modify: `background.js`
-- Modify: `sidepanel/sidepanel.js`
-- Modify: `README.md`
-
-- [ ] **Step 1: Write the failing test**
-
-Define the expected run behavior:
-
-- Auto mode chooses a fresh authorized Hotmail account for each new run
-- Step 3 uses the selected account email and password
-- Step 4 and Step 7 read verification mail through Graph instead of mailbox tabs
-
-- [ ] **Step 2: Run test to verify it fails**
-
-Select `hotmail-api` and run a manual or auto flow.
-
-Expected: The flow cannot yet allocate an account or fetch verification codes from Graph.
-
-- [ ] **Step 3: Write minimal implementation**
-
-Update:
-
-- provider branching in `getMailConfig()` or a replacement provider resolver
-- account allocation at fresh run start
-- Step 3 account-backed credentials
-- Step 4 and Step 7 Graph polling path
-- auto-run preconditions for Hotmail accounts
-
-- [ ] **Step 4: Run test to verify it passes**
-
-Run:
-
-1. manual Step 3 + Step 4 on a selected account
-2. manual Step 6 + Step 7 on the same account
-3. one full Auto run with `hotmail-api`
-
-Expected: no mailbox tab is opened for Hotmail, and verification codes come from Graph.
-
-- [ ] **Step 5: Commit**
-
-```bash
-git add background.js sidepanel/sidepanel.js README.md
-git commit -m "feat: integrate hotmail api provider into automation flow"
-```
-
-### Task 6: Regression Verification and Cleanup
-
-**Files:**
-- Modify: `README.md`
-
-- [ ] **Step 1: Write the failing test**
-
-List the required regression checks:
-
-- QQ provider still opens QQ mail tab
-- 163 provider still opens 163 mail tab
-- Inbucket provider still opens mailbox page
-- Hotmail provider uses API path only
-
-- [ ] **Step 2: Run test to verify it fails**
-
-Manually inspect pre-change behavior expectations against the new code before cleanup.
-
-Expected: Any missing provider branch or broken selector is identified.
-
-- [ ] **Step 3: Write minimal implementation**
-
-Clean up labels, update README usage instructions, and ensure all branches show accurate UI copy.
-
-- [ ] **Step 4: Run test to verify it passes**
-
-Reload the extension and perform:
-
-- provider switch smoke test
-- account add/delete smoke test
-- one OAuth authorization smoke test
-- one mail access smoke test
-
-- [ ] **Step 5: Commit**
-
-```bash
-git add README.md
-git commit -m "docs: document hotmail oauth mail provider"
-```
diff --git a/docs/superpowers/specs/2026-04-10-hotmail-oauth-design.md b/docs/superpowers/specs/2026-04-10-hotmail-oauth-design.md
deleted file mode 100644
index 67c0efa..0000000
--- a/docs/superpowers/specs/2026-04-10-hotmail-oauth-design.md
+++ /dev/null
@@ -1,197 +0,0 @@
-# Hotmail OAuth + Graph Mail Design
-
-## Goal
-
-Replace the existing DuckDuckGo plus webmail polling flow with a Hotmail account pool that:
-
-- authorizes each Hotmail account inside the extension via Microsoft OAuth
-- stores per-account tokens locally
-- selects a fresh account for each automated run
-- fetches verification emails through Microsoft Graph instead of mailbox page DOM polling
-
-The existing 1~9 step flow should remain intact wherever possible. The new work should be isolated to account selection, authorization, and email retrieval.
-
-## Existing Constraints
-
-- The project is a Manifest V3 Chrome extension with no build step.
-- Runtime orchestration lives in `background.js`.
-- The side panel is plain HTML/CSS/JS.
-- Step 4 and Step 7 currently depend on provider-specific content scripts for QQ, 163, and Inbucket mailbox polling.
-- Auto mode already supports retries, pauses, and restoring session state.
-
-## Design Summary
-
-The new Hotmail path introduces three focused subsystems:
-
-1. `hotmail-account-pool`
-   Maintains a reusable list of Hotmail accounts and their OAuth credentials.
-2. `microsoft-oauth`
-   Handles Microsoft authorization code flow with PKCE through `chrome.identity.launchWebAuthFlow`.
-3. `hotmail-graph-mail`
-   Reads inbox messages from Microsoft Graph and extracts verification codes for Step 4 and Step 7.
-
-The main flow continues to use the existing step state machine in `background.js`.
-
-## Architecture
-
-### 1. Account Pool
-
-Persist a new `hotmailAccounts` array in `chrome.storage.local`.
-
-Each account record stores:
-
-- `id`
-- `email`
-- `password`
-- `clientId`
-- `accessToken`
-- `refreshToken`
-- `expiresAt`
-- `status`
-- `lastUsedAt`
-- `lastAuthAt`
-- `lastError`
-
-The current run stores `currentHotmailAccountId` in `chrome.storage.session`.
-
-When `mailProvider = hotmail-api`, Auto mode must allocate one account at the start of a fresh run, write its email into the existing `email` runtime field, and reuse the same account through Step 3, Step 4, Step 6, and Step 7.
-
-### 2. OAuth Flow
-
-Each account is authorized separately from the side panel.
-
-Flow:
-
-1. User clicks `Authorize` on an account row.
-2. Background generates PKCE verifier/challenge and a random `state`.
-3. Background launches Microsoft sign-in via `chrome.identity.launchWebAuthFlow`.
-4. Microsoft redirects back to the extension redirect URL.
-5. Background validates `state`, exchanges `code` for tokens, and updates the account record.
-
-The extension requests delegated scopes only:
-
-- `openid`
-- `profile`
-- `offline_access`
-- `https://graph.microsoft.com/Mail.Read`
-- `https://graph.microsoft.com/User.Read`
-
-The design assumes one shared `clientId` across accounts is valid, while `refreshToken` remains per account.
-
-### 3. Graph Mail Retrieval
-
-Hotmail mail retrieval runs inside background logic and does not require a mail tab or content script.
-
-The provider performs:
-
-1. Resolve the current Hotmail account from session state.
-2. Refresh the token if missing or near expiry.
-3. Call Microsoft Graph to fetch recent inbox messages.
-4. Filter by sender, subject, and time window.
-5. Extract a 6-digit verification code from message metadata or preview/body.
-6. Return the code to the existing Step 4 or Step 7 submission flow.
-
-The first iteration should prefer stable fields such as:
-
-- `from.emailAddress.address`
-- `subject`
-- `receivedDateTime`
-- `bodyPreview`
-
-Full HTML body parsing is explicitly deferred unless needed.
-
-## Integration with Existing Steps
-
-### Step 3
-
-Step 3 keeps filling the OpenAI page in the same way, but when `mailProvider = hotmail-api`, the email comes from the selected account pool entry instead of the manual email box or Duck address.
-
-### Step 4 and Step 7
-
-The existing retry and resend behavior stays in place, but the provider path changes:
-
-- old providers: `qq`, `163`, `inbucket`
-- new provider: `hotmail-api`
-
-The orchestration layer should branch before opening any mailbox tab. For `hotmail-api`, it calls a background helper instead of `sendToMailContentScriptResilient`.
-
-### Auto Run
-
-Auto run changes:
-
-- remove the Duck auto-fetch dependency when `hotmail-api` is selected
-- allocate a fresh Hotmail account at the start of a new run
-- fail early if no authorized account is available
-- preserve the existing retry and skip-failure semantics
-
-## Side Panel Changes
-
-The current single email entry remains for backward compatibility, but a new account-pool section is added when `hotmail-api` is selected.
-
-New UI capabilities:
-
-- list Hotmail accounts
-- add an account
-- delete an account
-- authorize an account
-- test mail access for an account
-- show status and last error
-
-The existing provider selector gains a `hotmail-api` option.
-
-## Error Handling
-
-The new path must surface actionable errors:
-
-- no Hotmail account available
-- missing `clientId`
-- OAuth denied or cancelled
-- token exchange failed
-- refresh token invalid
-- Graph mail read failed
-- no matching verification mail found in the time window
-
-Account-level failures should update the account record `status` and `lastError` without corrupting unrelated accounts.
-
-## Security and Storage Tradeoffs
-
-- Tokens and account passwords are stored in `chrome.storage.local` for operator convenience.
-- This is acceptable for the current operator-managed extension model, but it increases the trust requirement of the local browser profile.
-- No secret should be hard-coded in the repository.
-
-## Testing Strategy
-
-Because the project has no automated test harness today, implementation should carve out pure helper functions where possible and validate them with focused runtime checks.
-
-The minimum verification surface:
-
-- account selection logic
-- PKCE helper generation
-- OAuth callback parsing and state validation
-- token refresh request/response handling
-- Graph message filtering and code extraction
-- Step 4 and Step 7 provider branch behavior
-- Auto run allocation of a fresh account per run
-
-## Deferred Work
-
-The first version intentionally excludes:
-
-- bulk import/export UX
-- bulk authorize all accounts
-- advanced HTML message parsing
-- mailbox delete/move/archive behavior
-- background local service or server proxy
-- removal of existing QQ/163/Inbucket support
-
-## Implementation Boundary
-
-Modify only the minimum set of files needed to add the new provider while keeping current providers operational:
-
-- `manifest.json`
-- `background.js`
-- `sidepanel/sidepanel.html`
-- `sidepanel/sidepanel.css`
-- `sidepanel/sidepanel.js`
-
-If helper extraction becomes necessary, prefer adding small new files under `content/` or the repo root only if they clearly reduce complexity in `background.js`.