feat: 实现浏览器扩展与桌面端的自动配对功能

XiaoYouChR · XiaoYouChR · commit 563e3aefde6f · 2026-05-04T20:04:08.000+08:00
diff --git a/app/services/browser_service.py b/app/services/browser_service.py
@@ -4,18 +4,19 @@
 from typing import TYPE_CHECKING, Any, Self
 from secrets import token_urlsafe
 
-from PySide6.QtCore import QObject, QTimer, Slot
+from PySide6.QtCore import QObject, QTimer, Slot, Qt
 from PySide6.QtNetwork import QHostAddress
 from PySide6.QtWebSockets import QWebSocketServer
 from loguru import logger
 from orjson import dumps, loads
+from qfluentwidgets import MessageBox
 
 from app.bases.models import Task, TaskStatus
 from app.services.core_service import coreService
 from app.services.feature_service import featureService
 from app.supports.config import VERSION, cfg
 from app.supports.recorder import taskRecorder
-from app.supports.utils import getProxies, openFile, openFolder
+from app.supports.utils import bringWindowToTop, getProxies, openFile, openFolder
 
 if TYPE_CHECKING:
     from PySide6.QtWebSockets import QWebSocket
@@ -35,6 +36,8 @@ class BrowserMessageType(StrEnum):
     ERROR = "error"
     HELLO = "hello"
     HELLO_ACK = "hello_ack"
+    PAIR_REQUEST = "pair_request"
+    PAIR_RESULT = "pair_result"
     SUBSCRIBE_TASKS = "subscribe_tasks"
     TASK_SNAPSHOT = "task_snapshot"
     CREATE_TASK = "create_task"
@@ -204,6 +207,41 @@ def _sendError(
             payload["requestId"] = requestId
         self._send(session, payload)
 
+    def _showPairRequestDialog(self, session: _BrowserClientSession, data: dict[str, Any]) -> bool:
+        extensionVersion = self._stringField(data, "extensionVersion", self.tr("未知"))
+        clientKind = self._stringField(data, "clientKind", self.tr("浏览器扩展"))
+        peerAddress = f"{session.socket.peerAddress().toString()}:{session.socket.peerPort()}"
+        content = self.tr(
+            "浏览器扩展正在请求连接到 Ghost Downloader。\n\n"
+            "来源: {0}\n"
+            "客户端: {1}\n"
+            "扩展版本: {2}\n\n"
+            "仅在你刚刚点击扩展里的“自动配对”时允许。"
+        ).format(peerAddress, clientKind, extensionVersion)
+
+        bringWindowToTop(self.mainWindow)
+        dialog = MessageBox(self.tr("浏览器扩展配对请求"), content, self.mainWindow)
+        dialog.yesButton.setText(self.tr("允许配对"))
+        dialog.cancelButton.setText(self.tr("拒绝"))
+        dialog.contentLabel.setTextInteractionFlags(Qt.TextInteractionFlag.TextSelectableByMouse)
+        return bool(dialog.exec())
+
+    def _handlePairRequest(self, session: _BrowserClientSession, data: dict[str, Any]) -> None:
+        requestId = self._stringField(data, "requestId")
+
+        if int(data.get("protocolVersion") or 0) != self.PROTOCOL_VERSION:
+            result = {"ok": False, "message": self.tr("协议版本不匹配")}
+        elif not self._showPairRequestDialog(session, data):
+            result = {"ok": False, "message": self.tr("已拒绝配对请求")}
+        else:
+            result = {"ok": True, "message": self.tr("配对成功"), "token": self.pairToken}
+
+        self._send(session, {
+            "type": BrowserMessageType.PAIR_RESULT,
+            "requestId": requestId,
+            **result,
+        })
+
     @staticmethod
     def _stringField(data: dict[str, Any], key: str, default: str = "") -> str:
         value = data.get(key)
@@ -691,6 +729,10 @@ def _onReceiveMessage(self, message: str):
             self._sendError(session, self.tr("未知的消息类型"))
             return
 
+        if messageType == BrowserMessageType.PAIR_REQUEST:
+            self._handlePairRequest(session, data)
+            return
+
         if messageType == BrowserMessageType.HELLO:
             requestId = self._stringField(data, "requestId") or None
             if int(data.get("protocolVersion") or 0) != self.PROTOCOL_VERSION:
diff --git a/app/supports/utils.py b/app/supports/utils.py
@@ -285,13 +285,13 @@ def getLocalTimeFromGithubApiTime(gmtTimeStr: str) -> str:
     return localTime.strftime("%Y-%m-%d %H:%M:%S")
 
 
-def bringWindowToTop(window):
+def bringWindowToTop(window) -> None:
     window.show()
-    if window.isMinimized():
-        window.showNormal()
-    # 激活窗口，使其显示在最前面
-    window.activateWindow()
+    window.setWindowState(
+        (window.windowState() & ~Qt.WindowState.WindowMinimized) | Qt.WindowState.WindowActive
+    )
     window.raise_()
+    window.activateWindow()
 
 
 def showMessageBox(
diff --git a/browser_extension/app/src/background.ts b/browser_extension/app/src/background.ts
@@ -302,6 +302,14 @@ chrome.runtime.onMessage.addListener((message, sender, sendResponse) => {
     })());
   }
 
+  if (message.type === "popup_request_pairing") {
+    void desktopBridge.requestPairing().catch(() => {
+      // The bridge snapshot carries the user-facing pairing failure message.
+    });
+    sendResponse({ ok: true, message: "配对请求已发送，请在桌面端确认" });
+    return true;
+  }
+
   if (message.type === "popup_set_intercept_downloads") {
     return reply(sendResponse, (async () => {
       interceptDownloads = Boolean(message.enabled);
diff --git a/browser_extension/app/src/background/desktop-bridge.ts b/browser_extension/app/src/background/desktop-bridge.ts
@@ -18,6 +18,16 @@ type PendingRequest = {
   timeoutId: number;
 };
 
+type PairingResponse = {
+  type?: string;
+  ok?: boolean;
+  token?: string;
+  message?: string;
+};
+
+const PAIRING_TIMEOUT_MS = 60000;
+const MISSING_PAIRING_MESSAGE = "请在扩展设置页自动配对桌面端";
+
 export type DesktopBridgeSnapshot = {
   connectionState: DesktopConnectionState;
   connectionMessage: string;
@@ -32,7 +42,7 @@ export function createDesktopBridge() {
   let reconnectTimer: number | null = null;
 
   let connectionState: DesktopConnectionState = "missing_token";
-  let connectionMessage = "请先在扩展设置里填写配对令牌";
+  let connectionMessage = MISSING_PAIRING_MESSAGE;
   let desktopVersion = "";
   let pairToken = "";
   let serverUrl = DEFAULT_SERVER_URL;
@@ -125,7 +135,7 @@ export function createDesktopBridge() {
     if (!pairToken) {
       desktopVersion = "";
       taskSnapshot = [];
-      setConnectionState("missing_token", "请先在扩展设置里填写配对令牌");
+      setConnectionState("missing_token", MISSING_PAIRING_MESSAGE);
       return;
     }
 
@@ -190,6 +200,83 @@ export function createDesktopBridge() {
     });
   }
 
+  async function requestPairing(): Promise<void> {
+    clearReconnectTimer();
+    setConnectionState("connecting", "正在请求桌面端确认配对");
+
+    try {
+      const token = await new Promise<string>((resolve, reject) => {
+        const socket = new WebSocket(serverUrl);
+        let settled = false;
+        let timeoutId = 0;
+
+        const finish = (done: () => void) => {
+          if (settled) {
+            return;
+          }
+          settled = true;
+          self.clearTimeout(timeoutId);
+          socket.close();
+          done();
+        };
+
+        timeoutId = self.setTimeout(() => {
+          finish(() => reject(new Error("等待桌面端确认配对超时")));
+        }, PAIRING_TIMEOUT_MS);
+
+        socket.addEventListener("open", () => {
+          socket.send(
+            JSON.stringify({
+              type: "pair_request",
+              requestId: nextRequestId(),
+              protocolVersion: PROTOCOL_VERSION,
+              extensionVersion: chrome.runtime.getManifest().version,
+              clientKind: "browser_extension",
+            }),
+          );
+        });
+
+        socket.addEventListener("message", (event) => {
+          let response: PairingResponse;
+          try {
+            response = JSON.parse(String(event.data ?? "")) as PairingResponse;
+          } catch {
+            return;
+          }
+          if (response.type !== "pair_result") {
+            return;
+          }
+
+          if (!response.ok) {
+            finish(() => reject(new Error(response.message || "桌面端已拒绝配对请求")));
+            return;
+          }
+
+          const token = String(response.token ?? "").trim();
+          if (!token) {
+            finish(() => reject(new Error("桌面端未返回配对令牌")));
+            return;
+          }
+
+          finish(() => resolve(token));
+        });
+
+        socket.addEventListener("close", () => {
+          finish(() => reject(new Error("配对连接已断开")));
+        });
+
+        socket.addEventListener("error", () => {
+          finish(() => reject(new Error("无法连接到 Ghost Downloader")));
+        });
+      });
+      await setToken(token);
+    } catch (error: unknown) {
+      const message = error instanceof Error ? error.message : "自动配对失败";
+      setConnectionState(pairToken ? "disconnected" : "missing_token", message);
+      throw error;
+    }
+  }
+
   async function sendRequest<T extends DesktopRequestResult>(payload: Record<string, unknown>): Promise<T> {
     if (!isReady() || !desktopSocket) {
       throw new Error("Ghost Downloader 未连接");
@@ -241,7 +328,7 @@ export function createDesktopBridge() {
       desktopSocket.close();
       desktopSocket = null;
     }
-    setConnectionState("missing_token", "请先在扩展设置里填写配对令牌");
+    setConnectionState("missing_token", MISSING_PAIRING_MESSAGE);
   }
 
   async function setServerUrl(nextServerUrl: string) {
@@ -288,6 +375,7 @@ export function createDesktopBridge() {
     handleReconnectAlarm,
     isReady,
     loadPersistentState,
+    requestPairing,
     sendRequest,
     setServerUrl,
     setToken,
diff --git a/browser_extension/app/src/popup/App.tsx b/browser_extension/app/src/popup/App.tsx
@@ -99,9 +99,11 @@ export function App({
             savingToken={bridge.isSavingToken}
             savingServerUrl={bridge.isSavingServerUrl}
             refreshingConnection={bridge.isRefreshingConnection}
+            requestingPairing={bridge.isRequestingPairing}
             onSaveToken={bridge.saveToken}
             onSaveServerUrl={bridge.saveServerUrl}
             onRefreshConnection={bridge.refreshConnection}
+            onRequestPairing={bridge.requestPairing}
             themePreference={themePreference}
             resolvedThemePreference={resolvedThemePreference}
             onThemePreferenceChange={onThemePreferenceChange}
diff --git a/browser_extension/app/src/popup/components/SettingsPage.tsx b/browser_extension/app/src/popup/components/SettingsPage.tsx
@@ -12,6 +12,7 @@ import {
 import {
   ArrowClockwiseRegular,
   ClipboardPasteRegular,
+  PlugConnectedRegular,
 } from "@fluentui/react-icons";
 import { useEffect, useState } from "react";
 
@@ -81,9 +82,11 @@ export function SettingsPage({
   savingToken,
   savingServerUrl,
   refreshingConnection,
+  requestingPairing,
   onSaveToken,
   onSaveServerUrl,
   onRefreshConnection,
+  onRequestPairing,
   themePreference,
   resolvedThemePreference,
   onThemePreferenceChange,
@@ -96,9 +99,11 @@ export function SettingsPage({
   savingToken?: boolean;
   savingServerUrl?: boolean;
   refreshingConnection?: boolean;
+  requestingPairing?: boolean;
   onSaveToken: (value: string) => Promise<boolean>;
   onSaveServerUrl: (value: string) => Promise<boolean>;
   onRefreshConnection: () => Promise<boolean>;
+  onRequestPairing: () => Promise<boolean>;
   themePreference: ThemePreference;
   resolvedThemePreference: Exclude<ThemePreference, "system">;
   onThemePreferenceChange: (nextPreference: ThemePreference) => void;
@@ -167,7 +172,17 @@ export function SettingsPage({
       <Card appearance="filled-alternative" className={styles.card}>
         <div className={styles.header}>
           <Body1Strong>连接配置</Body1Strong>
-          <ConnectionStatusBadge state={connectionState} message={connectionMessage} />
+          <div className={styles.inputRow}>
+            <ConnectionStatusBadge state={connectionState} message={connectionMessage} />
+            <Button
+              appearance="primary"
+              disabled={requestingPairing || savingToken || savingServerUrl}
+              icon={<PlugConnectedRegular />}
+              onClick={() => void onRequestPairing()}
+            >
+              自动配对
+            </Button>
+          </div>
         </div>
 
         <Field label="本地服务地址">
diff --git a/browser_extension/app/src/popup/hooks/usePopupBridge.ts b/browser_extension/app/src/popup/hooks/usePopupBridge.ts
@@ -60,7 +60,7 @@ function createEmptyMediaState(): MediaPlaybackState {
 function createEmptyPayload(): PopupStatePayload {
   return {
     connectionState: "missing_token",
-    connectionMessage: "请先在扩展设置里填写配对令牌",
+    connectionMessage: "请在扩展设置页自动配对桌面端",
     desktopVersion: "",
     token: "",
     serverUrl: "",
@@ -160,6 +160,7 @@ export function usePopupBridge(activeView: PopupView) {
   const [isSavingToken, setIsSavingToken] = useState(false);
   const [isSavingServerUrl, setIsSavingServerUrl] = useState(false);
   const [isRefreshingConnection, setIsRefreshingConnection] = useState(false);
+  const [isRequestingPairing, setIsRequestingPairing] = useState(false);
   const [isUpdatingIntercept, setIsUpdatingIntercept] = useState(false);
   const [isUpdatingMediaDownloadOverlay, setIsUpdatingMediaDownloadOverlay] = useState(false);
   const [isUpdatingMedia, setIsUpdatingMedia] = useState(false);
@@ -338,6 +339,30 @@ export function usePopupBridge(activeView: PopupView) {
     }
   }, [applyPopupState, requestPopupState, setFlash]);
 
+  const requestPairing = useCallback(async () => {
+    setIsRequestingPairing(true);
+    try {
+      const result = await sendRuntimeMessage<DesktopRequestResult>({
+        type: "popup_request_pairing",
+      });
+      if (!result.ok) {
+        throw new Error(result.message || "自动配对失败");
+      }
+      setFlash(result.message || "配对请求已发送，请在桌面端确认");
+      void refreshState(activeViewRef.current).catch(() => {
+        // Ignore transient popup refresh failures.
+      });
+      return true;
+    } catch (error) {
+      setFlash(getErrorMessage(error, "自动配对失败"), "error");
+      return false;
+    } finally {
+      if (mountedRef.current) {
+        setIsRequestingPairing(false);
+      }
+    }
+  }, [refreshState, setFlash]);
+
   const setInterceptDownloads = useCallback(
     async (enabled: boolean) => {
       setIsUpdatingIntercept(true);
@@ -572,12 +597,14 @@ export function usePopupBridge(activeView: PopupView) {
     isSavingToken,
     isSavingServerUrl,
     isRefreshingConnection,
+    isRequestingPairing,
     isUpdatingIntercept,
     isUpdatingMediaDownloadOverlay,
     isUpdatingMedia,
     saveToken,
     saveServerUrl,
     refreshConnection,
+    requestPairing,
     setInterceptDownloads,
     setMediaDownloadOverlay,
     performTaskAction,
diff --git a/browser_extension/app/src/shared/constants.ts b/browser_extension/app/src/shared/constants.ts
@@ -52,8 +52,8 @@ export const HELP_CONTENT: Record<string, { title: string; body: string[] }> = {
     title: "如何配对桌面端",
     body: [
       "1. 在 Ghost-Downloader-3 桌面端设置页开启“启用浏览器扩展”。",
-      "2. 复制桌面端显示的配对令牌。",
-      "3. 回到扩展设置页，把令牌粘贴到“配对令牌”输入框并保存。",
+      "2. 在扩展设置页点击“自动配对”。",
+      "3. 回到桌面端确认配对请求。",
       "4. 连接状态变成“已连接”后，浏览器就能直接管理桌面任务了。",
     ],
   },
@@ -77,7 +77,7 @@ export const HELP_CONTENT: Record<string, { title: string; body: string[] }> = {
     title: "故障排查",
     body: [
       "1. 先确认桌面端浏览器扩展服务已经开启。",
-      "2. 检查配对令牌是否和桌面端一致，必要时重新生成后再次保存。",
+      "2. 优先点击“自动配对”，失败时再检查配对令牌是否和桌面端一致。",
       "3. 如果状态一直断开，尝试点击设置页里的重新连接。",
       "4. 浏览器下载没有被接管时，可先确认顶部“拦截下载”开关是否开启。",
     ],
