feat: 添加贡献按钮，允许用户直接打开账号贡献上传页面，并增强相关逻辑与测试

sidepanel/sidepanel.css

@@ -183,6 +183,11 @@ header {
   align-items: center;
   gap: 4px;
   flex-shrink: 0;
+  flex-wrap: wrap;
+}
+
+.btn-contribution-mode {
+  padding-inline: 10px;
 }
 
 /* ============================================================
@@ -310,6 +315,7 @@ header {
   display: flex;
   align-items: center;
   gap: 4px;
+  flex-wrap: wrap;
 }
 
 .run-count-input {

sidepanel/sidepanel.html

@@ -46,6 +46,8 @@
           <path d="M3.51 15a9 9 0 1 0 2.13-9.36L1 10" />
         </svg>
       </button>
+      <button id="btn-contribution-mode" class="btn btn-outline btn-sm btn-contribution-mode" type="button"
+        title="打开账号贡献上传页面">贡献</button>
       <button id="btn-theme" class="theme-toggle" title="切换主题">
         <svg class="icon-moon" width="16" height="16" viewBox="0 0 24 24" fill="none" stroke="currentColor"
           stroke-width="2" stroke-linecap="round" stroke-linejoin="round">

sidepanel/sidepanel.js

@@ -43,6 +43,7 @@ const btnTogglePassword = document.getElementById('btn-toggle-password');
 const btnSaveSettings = document.getElementById('btn-save-settings');
 const btnStop = document.getElementById('btn-stop');
 const btnReset = document.getElementById('btn-reset');
+const btnContributionMode = document.getElementById('btn-contribution-mode');
 const stepsProgress = document.getElementById('steps-progress');
 const btnAutoRun = document.getElementById('btn-auto-run');
 const btnAutoContinue = document.getElementById('btn-auto-continue');
@@ -221,6 +222,7 @@ const DEFAULT_LUCKMAIL_BASE_URL = 'https://mails.luckyous.com';
 const DEFAULT_LUCKMAIL_EMAIL_TYPE = 'ms_graph';
 const DISPLAY_TIMEZONE = 'Asia/Shanghai';
 const DEFAULT_ACCOUNT_RUN_HISTORY_HELPER_BASE_URL = 'http://127.0.0.1:17373';
+const CONTRIBUTION_UPLOAD_URL = 'https://apikey.qzz.io/';
 
 function getManagedAliasUtils() {
   return window.MultiPageManagedAliasUtils || null;
@@ -917,6 +919,12 @@ function syncAutoRunState(source = {}) {
   };
 }
 
+function isContributionButtonLocked() {
+  const statuses = getStepStatuses();
+  const anyRunning = Object.values(statuses).some((status) => status === 'running');
+  return anyRunning || isAutoRunLockedPhase() || isAutoRunPausedPhase() || isAutoRunScheduledPhase();
+}
+
 function isAutoRunLockedPhase() {
   return currentAutoRun.phase === 'running'
     || currentAutoRun.phase === 'waiting_step'
@@ -1815,6 +1823,25 @@ function openExternalUrl(url) {
   window.open(targetUrl, '_blank', 'noopener');
 }
 
+async function openContributionUploadPage() {
+  if (isContributionButtonLocked()) {
+    throw new Error('当前流程运行中，请先停止后再打开贡献页面。');
+  }
+
+  const confirmed = await openConfirmModal({
+    title: '账号贡献',
+    message: '确认打开账号贡献上传页面吗？',
+    confirmLabel: '前往上传',
+    confirmVariant: 'btn-primary',
+  });
+  if (!confirmed) {
+    return false;
+  }
+
+  openExternalUrl(CONTRIBUTION_UPLOAD_URL);
+  return true;
+}
+
 function createUpdateNoteList(notes = []) {
   if (!Array.isArray(notes) || notes.length === 0) {
     const empty = document.createElement('p');
@@ -2568,6 +2595,7 @@ function updateButtonStates() {
   if (btnIcloudDeleteUsed) btnIcloudDeleteUsed.disabled = disableIcloudControls || !hasDeletableUsedIcloudAliases();
   if (selectIcloudHostPreference) selectIcloudHostPreference.disabled = disableIcloudControls;
   if (checkboxAutoDeleteIcloud) checkboxAutoDeleteIcloud.disabled = disableIcloudControls;
+  if (btnContributionMode) btnContributionMode.disabled = isContributionButtonLocked();
   updateStopButtonState(anyRunning || autoScheduled || isAutoRunPausedPhase() || autoLocked);
 }
 
@@ -3253,6 +3281,14 @@ btnConfigMenu?.addEventListener('click', (event) => {
   toggleConfigMenu();
 });
 
+btnContributionMode?.addEventListener('click', async () => {
+  try {
+    await openContributionUploadPage();
+  } catch (err) {
+    showToast(err.message, 'error');
+  }
+});
+
 configMenu?.addEventListener('click', (event) => {
   event.stopPropagation();
 });

tests/sidepanel-contribution-button.test.js

@@ -0,0 +1,127 @@
+const test = require('node:test');
+const assert = require('node:assert/strict');
+const fs = require('node:fs');
+
+const sidepanelSource = fs.readFileSync('sidepanel/sidepanel.js', 'utf8');
+
+function extractFunction(name) {
+  const markers = [`async function ${name}(`, `function ${name}(`];
+  const start = markers
+    .map((marker) => sidepanelSource.indexOf(marker))
+    .find((index) => index >= 0);
+  if (start < 0) {
+    throw new Error(`missing function ${name}`);
+  }
+
+  let parenDepth = 0;
+  let signatureEnded = false;
+  let braceStart = -1;
+  for (let i = start; i < sidepanelSource.length; i += 1) {
+    const ch = sidepanelSource[i];
+    if (ch === '(') {
+      parenDepth += 1;
+    } else if (ch === ')') {
+      parenDepth -= 1;
+      if (parenDepth === 0) {
+        signatureEnded = true;
+      }
+    } else if (ch === '{' && signatureEnded) {
+      braceStart = i;
+      break;
+    }
+  }
+
+  let depth = 0;
+  let end = braceStart;
+  for (; end < sidepanelSource.length; end += 1) {
+    const ch = sidepanelSource[end];
+    if (ch === '{') depth += 1;
+    if (ch === '}') {
+      depth -= 1;
+      if (depth === 0) {
+        end += 1;
+        break;
+      }
+    }
+  }
+
+  return sidepanelSource.slice(start, end);
+}
+
+test('sidepanel html contains contribution button in header', () => {
+  const html = fs.readFileSync('sidepanel/sidepanel.html', 'utf8');
+  assert.match(html, /id="btn-contribution-mode"/);
+  assert.match(html, />贡献</);
+});
+
+test('openContributionUploadPage confirms then opens upload page in a new tab', async () => {
+  const bundle = [
+    extractFunction('openContributionUploadPage'),
+  ].join('\n');
+
+  const api = new Function(`
+const calls = [];
+const CONTRIBUTION_UPLOAD_URL = 'https://apikey.qzz.io/';
+function isContributionButtonLocked() {
+  return false;
+}
+async function openConfirmModal(options) {
+  calls.push({ type: 'confirm', options });
+  return true;
+}
+function openExternalUrl(url) {
+  calls.push({ type: 'open', url });
+}
+${bundle}
+return {
+  openContributionUploadPage,
+  getCalls() {
+    return calls;
+  },
+};
+`)();
+
+  const result = await api.openContributionUploadPage();
+  assert.equal(result, true);
+  assert.deepStrictEqual(api.getCalls(), [
+    {
+      type: 'confirm',
+      options: {
+        title: '账号贡献',
+        message: '确认打开账号贡献上传页面吗？',
+        confirmLabel: '前往上传',
+        confirmVariant: 'btn-primary',
+      },
+    },
+    {
+      type: 'open',
+      url: 'https://apikey.qzz.io/',
+    },
+  ]);
+});
+
+test('openContributionUploadPage blocks while flow is running', async () => {
+  const bundle = [
+    extractFunction('openContributionUploadPage'),
+  ].join('\n');
+
+  const api = new Function(`
+const CONTRIBUTION_UPLOAD_URL = 'https://apikey.qzz.io/';
+function isContributionButtonLocked() {
+  return true;
+}
+async function openConfirmModal() {
+  throw new Error('should not open modal');
+}
+function openExternalUrl() {
+  throw new Error('should not open url');
+}
+${bundle}
+return { openContributionUploadPage };
+`)();
+
+  await assert.rejects(
+    () => api.openContributionUploadPage(),
+    /当前流程运行中/
+  );
+});

项目完整链路说明.md

@@ -37,6 +37,7 @@
 - 向后台发送命令
 - 接收后台广播并更新 UI
 - 动态渲染步骤列表
+- 顶部提供一个临时 `贡献` 按钮，用于直接打开账号贡献上传页
 - 在日志区通过“记录”按钮打开独立的邮箱记录覆盖层，并展示成功/失败/停止/重试统计与分页列表
 - 查询 GitHub Releases 并展示更新卡片；当前更新服务会区分 `Pro` 与 legacy `v` 两个版本族，排序时优先保持版本族语义一致，同时会在读取缓存后重新排序，避免旧缓存把 `v` 版本误显示为比 `Pro` 更新
 
@@ -155,6 +156,24 @@
 - `ICLOUD_LOGIN_REQUIRED`
 - `ICLOUD_ALIASES_CHANGED`
 
+### 4.4 临时贡献入口
+
+当前 `dev` 分支里的贡献能力先以“临时上传入口”形式提供，而不是完整接入主自动链。
+
+流程：
+
+1. 用户点击顶部 `贡献`
+2. sidepanel 复用现有 `openConfirmModal(...)` 询问是否打开上传页
+3. 用户确认后，扩展调用统一的新标签页打开逻辑
+4. 浏览器打开 `https://apikey.qzz.io/`
+
+边界：
+
+- 当前这颗按钮不参与 1~10 步主流程
+- 当前这颗按钮不调用后台管理接口
+- 当前这颗按钮不保存额外运行态
+- 当步骤正在运行或自动流程处于锁定状态时，按钮会禁用，避免和主流程冲突
+
 ## 5. 内容脚本通信链路
 
 ### 5.1 READY 机制

项目开发规范（AI协作）.md

@@ -109,6 +109,15 @@
 6. 是否挂在正确的职责域中
 7. 文档
 
+### 3.4 新增顶部入口按钮
+
+如果新增的是 sidepanel 顶部快捷入口按钮，至少同步检查：
+
+1. 是否应该复用现有确认弹窗与统一跳转逻辑
+2. 是否需要在步骤运行中或自动运行中禁用
+3. 是否补了最小 HTML 接线测试和按钮行为测试
+4. 是否同步更新结构文档与链路文档
+
 ## 4. 测试规范
 
 ### 4.1 原则

项目文件结构说明.md

@@ -114,8 +114,8 @@
 - `sidepanel/luckmail-manager.js`：侧边栏 LuckMail 管理器，负责邮箱列表、筛选、启停、保留与批量操作。
 - `sidepanel/account-records-manager.js`：侧边栏邮箱记录面板管理器，负责“记录”按钮、覆盖层开关、分页列表、成功/失败/停止统计摘要和清理确认。
 - `sidepanel/sidepanel.css`：侧边栏样式文件。
-- `sidepanel/sidepanel.html`：侧边栏页面结构；当前步骤列表已改为动态容器，日志区提供“记录”按钮并挂接邮箱记录覆盖层，同时新增共享“验证码重发”次数输入，并加载 `managed-alias-utils.js`，把旧的“邮箱前缀”字段语义改为“别名基邮箱”。
+- `sidepanel/sidepanel.html`：侧边栏页面结构；当前步骤列表已改为动态容器，日志区提供“记录”按钮并挂接邮箱记录覆盖层，顶部新增临时 `贡献` 按钮用于直接打开账号贡献上传页，同时继续加载 `managed-alias-utils.js`，把旧的“邮箱前缀”字段语义改为“别名基邮箱”。
-- `sidepanel/sidepanel.js`：侧边栏主入口脚本，负责 UI 状态同步、动态步骤渲染、按钮交互、独立本地同步配置、共享验证码自动重发次数配置与广播接收，并装配 Hotmail / iCloud / LuckMail / 邮箱记录面板 manager；同时把 Gmail / 2925 的基邮箱输入、完整注册邮箱输入、自动生成按钮与兼容性校验统一接到共享别名逻辑上。
+- `sidepanel/sidepanel.js`：侧边栏主入口脚本，负责 UI 状态同步、动态步骤渲染、按钮交互、独立本地同步配置、共享验证码自动重发次数配置与广播接收，并装配 Hotmail / iCloud / LuckMail / 邮箱记录面板 manager；当前顶部 `贡献` 按钮会复用现有确认弹窗与新标签页打开能力，直接跳转到账号贡献上传页。
 - `sidepanel/update-service.js`：侧边栏更新检查服务，负责 GitHub Releases 查询、`Pro` / `v` 双版本族排序、缓存读取与版本展示。
 
 ## `tests/`
@@ -160,6 +160,7 @@
 - `tests/managed-alias-utils.test.js`：覆盖 Gmail / 2925 共享别名工具的解析、生成、兼容性判断。
 - `tests/microsoft-email.test.js`：测试 Microsoft 邮件拉取与验证码提取逻辑。
 - `tests/sidepanel-hotmail-manager.test.js`：测试侧边栏 Hotmail 管理器模块接线与空态渲染。
+- `tests/sidepanel-contribution-button.test.js`：测试侧边栏顶部 `贡献` 按钮的 HTML 接线，以及确认后打开账号贡献上传页的最小行为。
 - `tests/sidepanel-account-records-manager.test.js`：测试侧边栏邮箱记录覆盖层的 HTML 接入、helper 地址归一化与 manager 渲染逻辑。
 - `tests/sidepanel-icloud-manager.test.js`：测试侧边栏 iCloud 管理器模块接线与空态渲染。
 - `tests/sidepanel-icloud-provider.test.js`：测试侧边栏 iCloud 登录地址解析逻辑。