feat: 添加 Native Messaging 桥接，支持 CLI 和 AI Agent 控制扩展

package.json

@@ -1,7 +1,7 @@
 {
   "name": "pt-depiler",
   "private": true,
-  "version": "0.0.5",
+  "version": "0.0.6",
   "type": "module",
   "homepage": "https://github.com/pt-plugins/PT-depiler",
   "packageManager": "pnpm@10.21.0",

privacy-statement.md

@@ -17,12 +17,18 @@
   - 使用 `https` 的方式配置服务器地址；
   - 启用备份数据加密（采用 [AES](https://en.wikipedia.org/wiki/Advanced_Encryption_Standard)）功能后再进行备份操作；
 
-## 四、与第三人共用个人信息之政策
+## 四、原生通信桥（Native Messaging）
+- 当您在设置页面中授予 `nativeMessaging` 权限并启用原生通信桥功能后，助手将通过 Chrome Native Messaging 机制与本地安装的 CLI 工具（ptd-cli）进行通信；
+- 通过此通道可访问的信息包括：站点配置、搜索结果、下载历史、用户信息、下载器状态等；
+- 所有通信均在本地进行（浏览器与本机进程之间），不会将数据发送至任何远程服务器；
+- 此功能为可选功能，需要用户主动授权并启用，您可以随时在设置页面中撤销权限或禁用该功能；
+
+## 五、与第三人共用个人信息之政策
 - 助手不会收集任何相关的个人信息，所以助手绝不会提供、交换、出租或出售任何您的个人信息给其他个人、团体、私人企业或公务机关；
 
-## 五、Cookie之使用
+## 六、Cookie之使用
 - 当您进行搜索操作时，助手会访问您已配置的站点，Cookie 由浏览器提供，助手无权访问也不会对内容进行探测和修改，一切内容由浏览器和站点进行相互验证；
 - 当您授权助手访问 Cookie 信息时，这些信息仅用于备份和恢复操作，助手不会在除此之外的任何其他操作中使用它们；
 
-## 六、隐私权保护政策之修正
+## 七、隐私权保护政策之修正
 - 助手隐私权保护政策将按用户需求变更而随时进行修正，修正后的条款将在本页面显示。

src/entries/background/main.ts

@@ -8,6 +8,7 @@ import "./utils/contextMenus.ts";
 import "./utils/omnibox.ts";
 import "./utils/alarms.ts";
 import "./utils/webRequest.ts";
+import "./utils/nativeMessaging.ts";
 
 // 监听 点击图标 事件
 chrome.action.onClicked.addListener(async () => {

src/entries/background/utils/nativeMessaging.ts

@@ -0,0 +1,335 @@
+import { onMessage, sendMessage } from "@/messages.ts";
+import { setupOffscreenDocument } from "./offscreen.ts";
+import type { BridgeState, BridgeStatus } from "@/shared/types.ts";
+
+const NATIVE_HOST_NAME = "com.ptd.native";
+const INSTANCE_ID_KEY = "ptd_native_instance_id";
+const ENABLED_KEY = "ptd_native_bridge_enabled";
+const RECONNECT_BASE_MS = 1000;
+const RECONNECT_MAX_MS = 30000;
+const MAX_RECONNECT_ATTEMPTS = 10;
+
+/** Errors that indicate the native host is not installed — no point retrying. */
+const FATAL_ERRORS = [
+  "Specified native messaging host not found.",
+  "Access to the specified native messaging host is forbidden.",
+];
+
+/** Methods the bridge will proxy to sendMessage(). Everything else is rejected. */
+const ALLOWED_METHODS = new Set([
+  // Site config
+  "getSiteList",
+  "getSiteUserConfig",
+  "getSiteFavicon",
+  "clearSiteFaviconCache",
+  // Search
+  "getSiteSearchResult",
+  "getMediaServerSearchResult",
+  // Download and downloader
+  "getDownloaderList",
+  "getDownloaderConfig",
+  "getDownloaderVersion",
+  "getDownloaderStatus",
+  "getTorrentDownloadLink",
+  "getTorrentInfoForVerification",
+  "downloadTorrent",
+  "getDownloadHistory",
+  "getDownloadHistoryById",
+  "deleteDownloadHistoryById",
+  "clearDownloadHistory",
+  // User info
+  "getSiteUserInfoResult",
+  "cancelUserInfoQueue",
+  "getSiteUserInfo",
+  "removeSiteUserInfo",
+  // Keep-upload
+  "getKeepUploadTasks",
+  "getKeepUploadTaskById",
+  "createKeepUploadTask",
+  "updateKeepUploadTask",
+  "deleteKeepUploadTask",
+  "clearKeepUploadTasks",
+]);
+
+// ── Module-scoped state ──────────────────────────────────────────────
+
+let port: chrome.runtime.Port | null = null;
+let reconnectTimer: ReturnType<typeof setTimeout> | null = null;
+let reconnectAttempt = 0;
+let enabled = true;
+let state: BridgeState = "no-permission";
+let lastError: string | undefined;
+let intentionalDisconnect = false;
+
+// ── Helpers ──────────────────────────────────────────────────────────
+
+async function getOrCreateInstanceId(): Promise<string> {
+  const stored = await chrome.storage.local.get(INSTANCE_ID_KEY);
+  const storedInstanceId = stored[INSTANCE_ID_KEY];
+
+  if (typeof storedInstanceId === "string" && storedInstanceId.length > 0) {
+    return storedInstanceId;
+  }
+  const id = crypto.randomUUID();
+  await chrome.storage.local.set({ [INSTANCE_ID_KEY]: id });
+  return id;
+}
+
+async function checkPermission(): Promise<boolean> {
+  try {
+    return await chrome.permissions.contains({ permissions: ["nativeMessaging"] });
+  } catch {
+    return false;
+  }
+}
+
+async function getStatus(): Promise<BridgeStatus> {
+  const permissionGranted = await checkPermission();
+  return {
+    permissionGranted,
+    enabled,
+    state,
+    connected: port !== null && state === "connected",
+    lastError,
+  };
+}
+
+function clearReconnectTimer() {
+  if (reconnectTimer !== null) {
+    clearTimeout(reconnectTimer);
+    reconnectTimer = null;
+  }
+}
+
+// ── Lifecycle ────────────────────────────────────────────────────────
+
+function disconnect(intentional: boolean) {
+  intentionalDisconnect = intentional;
+  clearReconnectTimer();
+  reconnectAttempt = 0;
+
+  if (port) {
+    try {
+      port.disconnect();
+    } catch {
+      // Already disconnected — ignore
+    }
+    port = null;
+  }
+}
+
+function scheduleReconnect() {
+  clearReconnectTimer();
+  reconnectAttempt++;
+
+  if (reconnectAttempt > MAX_RECONNECT_ATTEMPTS) {
+    state = "error";
+    lastError = `Gave up after ${MAX_RECONNECT_ATTEMPTS} reconnect attempts`;
+    console.debug("[PTD] Native bridge exceeded max reconnect attempts, giving up.");
+    return;
+  }
+
+  const delay = Math.min(RECONNECT_BASE_MS * 2 ** reconnectAttempt, RECONNECT_MAX_MS);
+  state = "retrying";
+  console.debug(
+    `[PTD] Native bridge reconnecting in ${delay}ms (attempt ${reconnectAttempt}/${MAX_RECONNECT_ATTEMPTS})...`,
+  );
+  reconnectTimer = setTimeout(connect, delay);
+}
+
+function connect() {
+  if (!enabled) {
+    return;
+  }
+
+  clearReconnectTimer();
+  state = "connecting";
+  lastError = undefined;
+  intentionalDisconnect = false;
+
+  let currentPort: chrome.runtime.Port;
+  try {
+    currentPort = chrome.runtime.connectNative(NATIVE_HOST_NAME);
+    port = currentPort;
+  } catch (e: any) {
+    state = "error";
+    lastError = e?.message ?? String(e);
+    console.debug("[PTD] Native messaging host not available:", lastError);
+    return;
+  }
+
+  // Send hello handshake — mark connected after successful send.
+  // The native host does not send an ack, so a successful postMessage
+  // is our best signal. If the host is absent, onDisconnect fires.
+  getOrCreateInstanceId()
+    .then((instanceId) => {
+      if (port !== currentPort) return;
+
+      try {
+        currentPort.postMessage({
+          type: "hello",
+          instanceId,
+          browser: __BROWSER__,
+          extensionId: chrome.runtime.id,
+          version: __EXT_VERSION__,
+          capabilities: ["bridge-v1"],
+        });
+      } catch (e: any) {
+        state = "error";
+        lastError = e?.message ?? String(e);
+        console.debug("[PTD] Failed to send native hello message:", lastError);
+        return;
+      }
+
+      state = "connected";
+      reconnectAttempt = 0;
+    })
+    .catch((e: any) => {
+      if (port !== currentPort) return;
+      state = "error";
+      lastError = e?.message ?? String(e);
+      console.debug("[PTD] Failed to get or create native instance id:", lastError);
+      try {
+        currentPort.disconnect();
+      } catch {
+        // ignore
+      }
+    });
+
+  currentPort.onMessage.addListener(async (msg: any) => {
+    if (msg?.type !== "request" || !msg.id || !msg.method) {
+      return;
+    }
+
+    const { id, method, params } = msg;
+
+    if (!ALLOWED_METHODS.has(method)) {
+      currentPort.postMessage({
+        type: "response",
+        id,
+        error: { code: "METHOD_NOT_ALLOWED", message: `Method '${method}' is not allowed` },
+      });
+      return;
+    }
+
+    try {
+      await setupOffscreenDocument();
+      const result = await sendMessage(method as any, params);
+      if (port === currentPort) {
+        currentPort.postMessage({ type: "response", id, result });
+      }
+    } catch (e: any) {
+      if (port === currentPort) {
+        currentPort.postMessage({
+          type: "response",
+          id,
+          error: { code: "EXTENSION_ERROR", message: e?.message ?? String(e) },
+        });
+      }
+    }
+  });
+
+  currentPort.onDisconnect.addListener(() => {
+    const err = chrome.runtime.lastError;
+    const errMsg = err?.message ?? "";
+
+    // Stale port — a new connection has already replaced this one
+    if (port !== currentPort) return;
+
+    port = null;
+
+    if (intentionalDisconnect) {
+      return;
+    }
+
+    if (err) {
+      console.debug("[PTD] Native messaging disconnected:", errMsg);
+    }
+
+    if (FATAL_ERRORS.some((e) => errMsg.includes(e))) {
+      state = "error";
+      lastError = errMsg;
+      console.debug("[PTD] Native host not available, CLI bridge disabled.");
+      return;
+    }
+
+    lastError = errMsg || "Connection lost";
+    scheduleReconnect();
+  });
+}
+
+async function init() {
+  const permissionGranted = await checkPermission();
+
+  // Refresh enabled flag
+  const stored = await chrome.storage.local.get(ENABLED_KEY);
+  enabled = stored[ENABLED_KEY] !== false; // default true
+
+  if (!permissionGranted) {
+    disconnect(true);
+    state = "no-permission";
+    lastError = undefined;
+    return;
+  }
+
+  if (!enabled) {
+    disconnect(true);
+    state = "disabled";
+    lastError = undefined;
+    return;
+  }
+
+  connect();
+}
+
+// ── Runtime permission listeners ─────────────────────────────────────
+
+chrome.permissions.onAdded?.addListener((permissions) => {
+  if (permissions.permissions?.includes("nativeMessaging")) {
+    init();
+  }
+});
+
+chrome.permissions.onRemoved?.addListener((permissions) => {
+  if (permissions.permissions?.includes("nativeMessaging")) {
+    init();
+  }
+});
+
+// ── Message handlers ─────────────────────────────────────────────────
+
+onMessage("nativeBridgeGetStatus", async () => {
+  return getStatus();
+});
+
+onMessage("nativeBridgeSetEnabled", async ({ data }) => {
+  if (typeof data !== "boolean") {
+    return getStatus();
+  }
+  await chrome.storage.local.set({ [ENABLED_KEY]: data });
+  await init();
+  if (state === "connecting") {
+    await new Promise((r) => setTimeout(r, 200));
+  }
+  return getStatus();
+});
+
+onMessage("nativeBridgeReconnect", async () => {
+  const permissionGranted = await checkPermission();
+  if (!permissionGranted) {
+    lastError = "Permission not granted — cannot reconnect";
+    return getStatus();
+  }
+  if (!enabled) {
+    lastError = "Bridge is disabled — cannot reconnect";
+    return getStatus();
+  }
+
+  disconnect(true);
+  connect();
+  return getStatus();
+});
+
+// ── Startup ──────────────────────────────────────────────────────────
+
+init();

src/entries/messages.ts

@@ -40,6 +40,7 @@ import {
   AugmentedRequired,
   IKeepUploadTask,
   TKeepUploadTaskKey,
+  BridgeStatus,
 } from "@/shared/types.ts";
 
 import { isDebug } from "~/helper.ts";
@@ -145,6 +146,15 @@ interface ProtocolMap extends TMessageMap {
   updateKeepUploadTask(task: IKeepUploadTask): void;
   deleteKeepUploadTask(taskId: TKeepUploadTaskKey): void;
   clearKeepUploadTasks(): void;
+
+  // 2.8 Lightweight list queries (for CLI discovery)
+  getSiteList(): Array<{ id: string; name: string; url: string; offline: boolean }>;
+  getDownloaderList(): Array<{ id: string; name: string; type: string; enabled: boolean; address: string }>;
+
+  // 2.9 Native messaging bridge control
+  nativeBridgeGetStatus(): BridgeStatus;
+  nativeBridgeSetEnabled(data: boolean): BridgeStatus;
+  nativeBridgeReconnect(): BridgeStatus;
 }
 
 // 全局消息处理函数映射