From 390ae35966080c31c86c3f27f0cdcb5dad4aa817 Mon Sep 17 00:00:00 2001
From: QLHazyCoder <2825305047@qq.com>
Date: Sun, 19 Apr 2026 00:06:20 +0800
Subject: [PATCH] =?UTF-8?q?feat:=20=E6=B7=BB=E5=8A=A0=E8=B4=A1=E7=8C=AE?=
 =?UTF-8?q?=E6=8C=89=E9=92=AE=EF=BC=8C=E5=85=81=E8=AE=B8=E7=94=A8=E6=88=B7?=
 =?UTF-8?q?=E7=9B=B4=E6=8E=A5=E6=89=93=E5=BC=80=E8=B4=A6=E5=8F=B7=E8=B4=A1?=
 =?UTF-8?q?=E7=8C=AE=E4=B8=8A=E4=BC=A0=E9=A1=B5=E9=9D=A2=EF=BC=8C=E5=B9=B6?=
 =?UTF-8?q?=E5=A2=9E=E5=BC=BA=E7=9B=B8=E5=85=B3=E9=80=BB=E8=BE=91=E4=B8=8E?=
 =?UTF-8?q?=E6=B5=8B=E8=AF=95?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

---
 sidepanel/sidepanel.css                     |   6 +
 sidepanel/sidepanel.html                    |   2 +
 sidepanel/sidepanel.js                      |  36 ++++++
 tests/sidepanel-contribution-button.test.js | 127 ++++++++++++++++++++
 项目完整链路说明.md                         |  19 +++
 项目开发规范（AI协作）.md                   |   9 ++
 项目文件结构说明.md                         |   5 +-
 7 files changed, 202 insertions(+), 2 deletions(-)
 create mode 100644 tests/sidepanel-contribution-button.test.js

diff --git a/sidepanel/sidepanel.css b/sidepanel/sidepanel.css
index 55aedf5..e0961aa 100644
--- a/sidepanel/sidepanel.css
+++ b/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 {
diff --git a/sidepanel/sidepanel.html b/sidepanel/sidepanel.html
index f405a4e..3be2c00 100644
--- a/sidepanel/sidepanel.html
+++ b/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">
diff --git a/sidepanel/sidepanel.js b/sidepanel/sidepanel.js
index cc4b3a5..cad5e78 100644
--- a/sidepanel/sidepanel.js
+++ b/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();
 });
diff --git a/tests/sidepanel-contribution-button.test.js b/tests/sidepanel-contribution-button.test.js
new file mode 100644
index 0000000..05d0e13
--- /dev/null
+++ b/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(),
+    /当前流程运行中/
+  );
+});
diff --git a/项目完整链路说明.md b/项目完整链路说明.md
index f12fc5e..ba5bb83 100644
--- a/项目完整链路说明.md
+++ b/项目完整链路说明.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 机制
diff --git a/项目开发规范（AI协作）.md b/项目开发规范（AI协作）.md
index fdc753f..4584e64 100644
--- a/项目开发规范（AI协作）.md
+++ b/项目开发规范（AI协作）.md
@@ -109,6 +109,15 @@
 6. 是否挂在正确的职责域中
 7. 文档
 
+### 3.4 新增顶部入口按钮
+
+如果新增的是 sidepanel 顶部快捷入口按钮，至少同步检查：
+
+1. 是否应该复用现有确认弹窗与统一跳转逻辑
+2. 是否需要在步骤运行中或自动运行中禁用
+3. 是否补了最小 HTML 接线测试和按钮行为测试
+4. 是否同步更新结构文档与链路文档
+
 ## 4. 测试规范
 
 ### 4.1 原则
diff --git a/项目文件结构说明.md b/项目文件结构说明.md
index b6c2b8c..8e027ec 100644
--- a/项目文件结构说明.md
+++ b/项目文件结构说明.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.js`：侧边栏主入口脚本，负责 UI 状态同步、动态步骤渲染、按钮交互、独立本地同步配置、共享验证码自动重发次数配置与广播接收，并装配 Hotmail / iCloud / LuckMail / 邮箱记录面板 manager；同时把 Gmail / 2925 的基邮箱输入、完整注册邮箱输入、自动生成按钮与兼容性校验统一接到共享别名逻辑上。
+- `sidepanel/sidepanel.html`：侧边栏页面结构；当前步骤列表已改为动态容器，日志区提供“记录”按钮并挂接邮箱记录覆盖层，顶部新增临时 `贡献` 按钮用于直接打开账号贡献上传页，同时继续加载 `managed-alias-utils.js`，把旧的“邮箱前缀”字段语义改为“别名基邮箱”。
+- `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 登录地址解析逻辑。