@gecho-ai/gecho-bridge 1.1.26 → 1.1.28

package/.claude-plugin/plugin.json

@@ -1,5 +1,5 @@
 {
   "name": "@gecho-ai/gecho-bridge",
-  "version": "1.1.26",
+  "version": "1.1.28",
   "description": "TikTok Search Tool for OpenClaw"
 }

package/dist/mcp-client.cjs

@@ -33854,7 +33854,7 @@ var require_package = __commonJS({
   "package.json"(exports2, module2) {
     module2.exports = {
       name: "@gecho-ai/gecho-bridge",
-      version: "1.1.26",
+      version: "1.1.28",
       description: "TikTok Search and Insight tools for OpenClaw, connecting LLMs to TikTok via Chrome Extension.",
       main: "mcp-client.js",
       bin: {
@@ -33868,6 +33868,7 @@ var require_package = __commonJS({
         ".mcp.json",
         "openclaw.plugin.json",
         "skills",
+        "distribution-skills",
         "README.md",
         "README.zh.md",
         "qywx.jpg"
@@ -34017,12 +34018,19 @@ function requestShutdown() {
   });
 }
 function startServiceDetached() {
-  const child = spawn("node", [SERVICE_PATH], {
-    detached: true,
-    stdio: "ignore"
-    // 静默启动，不占用当前终端
+  const isWindows = process.platform === "win32";
+  const child = spawn(process.execPath, [SERVICE_PATH], {
+    // On Windows, detached creates a separate process group. It is unnecessary
+    // after unref() and has proved unreliable for the browser launched by this
+    // service when the parent is a desktop MCP host. Keep the Unix behaviour.
+    detached: !isWindows,
+    stdio: "ignore",
+    windowsHide: true,
+    // Make this equivalent to running `node server.js` from the package.
+    cwd: __dirname
   });
   child.unref();
+  return child;
 }
 async function waitForServiceDown() {
   let retries = 10;

package/dist/server.cjs

@@ -3640,7 +3640,7 @@ var require_package = __commonJS({
   "package.json"(exports2, module2) {
     module2.exports = {
       name: "@gecho-ai/gecho-bridge",
-      version: "1.1.26",
+      version: "1.1.28",
       description: "TikTok Search and Insight tools for OpenClaw, connecting LLMs to TikTok via Chrome Extension.",
       main: "mcp-client.js",
       bin: {
@@ -3654,6 +3654,7 @@ var require_package = __commonJS({
         ".mcp.json",
         "openclaw.plugin.json",
         "skills",
+        "distribution-skills",
         "README.md",
         "README.zh.md",
         "qywx.jpg"
@@ -3699,9 +3700,10 @@ var { WebSocketServer } = require_ws();
 var http = require("http");
 var fs = require("fs");
 var path = require("path");
+var { spawn } = require("child_process");
 var packageJson = require_package();
-var WS_PORT = 18792;
-var HTTP_PORT = 18793;
+var WS_PORT = Number(process["env"].GECHO_WS_PORT || 18792);
+var HTTP_PORT = Number(process["env"].GECHO_HTTP_PORT || 18793);
 var SERVICE_PROTOCOL_VERSION = 2;
 var SERVICE_STARTED_AT = Date.now();
 var DEFAULT_DATA_DIR = path.join(__dirname, "data");
@@ -3709,14 +3711,32 @@ var JOBS_DIR = process["env"].GECHO_DATA_DIR || DEFAULT_DATA_DIR;
 var JOBS_STORE_PATH = path.join(JOBS_DIR, ".async_jobs.json");
 var JOB_DETAILS_DIR = path.join(JOBS_DIR, "jobs");
 var REQUEST_INDEX_PATH = path.join(JOBS_DIR, ".async_request_index.json");
+var BROWSER_CONNECTION_PATH = path.join(JOBS_DIR, ".browser_connection.json");
 var JOB_TTL_MS = Number(process["env"].GECHO_JOB_TTL_MS || 3 * 24 * 60 * 60 * 1e3);
 var MAX_PERSISTED_JOBS = Number(process["env"].GECHO_MAX_PERSISTED_JOBS || 2e3);
 var CLEANUP_INTERVAL_MS = Number(process["env"].GECHO_CLEANUP_INTERVAL_MS || 10 * 60 * 1e3);
+var EXTENSION_CONNECT_TIMEOUT_MS = Math.max(1e3, Number(process["env"].GECHO_EXTENSION_CONNECT_TIMEOUT_MS || 3e4));
+var EXTENSION_CONNECT_POLL_MS = 500;
+var EXTENSION_READY_GRACE_MS = Math.max(0, Number(process["env"].GECHO_EXTENSION_READY_GRACE_MS || 1500));
+var AUTO_LAUNCH_BROWSER = process["env"].GECHO_AUTO_LAUNCH_BROWSER !== "0";
+var AUTO_LAUNCH_BROWSER_DRY_RUN = process["env"].GECHO_AUTO_LAUNCH_BROWSER_DRY_RUN === "1";
+var AUTO_LAUNCH_BROWSER_COOLDOWN_MS = Math.max(0, Number(process["env"].GECHO_AUTO_LAUNCH_BROWSER_COOLDOWN_MS || 1e4));
 var extensionSocket = null;
+var wss = null;
+var lastExtensionConnectedAt = 0;
+var lastBrowserConnection = null;
+var browserLaunchPromise = null;
+var lastBrowserLaunchAt = 0;
 var pendingRequests = /* @__PURE__ */ new Map();
 var requestIdCounter = 1;
 var shuttingDown = false;
 var lastDispatchedRequestId = "";
+var BRIDGE_TRACE_LIMIT = 100;
+var bridgeTrace = [];
+function traceBridgeEvent(event, details = {}) {
+  bridgeTrace.push({ at: Date.now(), event, ...details });
+  if (bridgeTrace.length > BRIDGE_TRACE_LIMIT) bridgeTrace.shift();
+}
 var asyncJobs = /* @__PURE__ */ new Map();
 var requestIndex = /* @__PURE__ */ new Map();
 var ASYNC_ATTEMPT_TIMEOUT_MS = 36e4;
@@ -3738,6 +3758,27 @@ function ensureJobDetailsDirReady() {
 function getJobDetailPath(jobId) {
   return path.join(JOB_DETAILS_DIR, `${jobId}.json`);
 }
+function writeFileAtomic(targetPath, content) {
+  const tmpPath = `${targetPath}.tmp-${process.pid}-${Date.now()}`;
+  fs.writeFileSync(tmpPath, content, "utf8");
+  try {
+    fs.renameSync(tmpPath, targetPath);
+  } catch (e) {
+    if (e && (e.code === "EEXIST" || e.code === "EPERM")) {
+      try {
+        fs.unlinkSync(targetPath);
+      } catch (_ignore) {
+      }
+      fs.renameSync(tmpPath, targetPath);
+    } else {
+      try {
+        fs.unlinkSync(tmpPath);
+      } catch (_ignore) {
+      }
+      throw e;
+    }
+  }
+}
 function enqueueWrite(task, label = "write_task") {
   writeQueue = writeQueue.then(async () => {
     await task();
@@ -3768,6 +3809,267 @@ async function writeFileAtomicAsync(targetPath, content) {
     }
   }
 }
+function getOpenExtensionSocket() {
+  if (extensionSocket && extensionSocket.readyState === 1) {
+    return extensionSocket;
+  }
+  if (wss) {
+    for (const socket of wss.clients) {
+      if (socket.readyState === 1) {
+        extensionSocket = socket;
+        return socket;
+      }
+    }
+  }
+  return null;
+}
+function isExtensionConnected() {
+  return !!getOpenExtensionSocket();
+}
+function normalizeBrowserName(value) {
+  const normalized = String(value || "").trim().toLowerCase();
+  if (normalized === "edge" || normalized === "microsoft-edge" || normalized === "msedge") return "edge";
+  if (normalized === "chrome" || normalized === "google-chrome") return "chrome";
+  return "";
+}
+function detectBrowserFromUserAgent(userAgent) {
+  const value = String(userAgent || "");
+  if (/\bEdg\//i.test(value)) return "edge";
+  if (/\bChrome\//i.test(value) && !/\b(?:OPR|Edg)\//i.test(value)) return "chrome";
+  return "";
+}
+function loadLastBrowserConnection() {
+  try {
+    if (!fs.existsSync(BROWSER_CONNECTION_PATH)) return null;
+    const parsed = JSON.parse(fs.readFileSync(BROWSER_CONNECTION_PATH, "utf8") || "{}");
+    const browser = normalizeBrowserName(parsed?.browser);
+    if (!browser) return null;
+    return {
+      browser,
+      detectedAt: Number(parsed.detectedAt || 0) || 0
+    };
+  } catch (e) {
+    console.warn(`Failed to load last browser connection: ${e.message}`);
+    return null;
+  }
+}
+function persistLastBrowserConnection(browser) {
+  const normalized = normalizeBrowserName(browser);
+  if (!normalized) return;
+  lastBrowserConnection = { browser: normalized, detectedAt: Date.now() };
+  try {
+    ensureJobsDirReady();
+    writeFileAtomic(BROWSER_CONNECTION_PATH, JSON.stringify(lastBrowserConnection));
+  } catch (e) {
+    console.warn(`Failed to persist last browser connection: ${e.message}`);
+  }
+}
+function findFirstExistingPath(paths) {
+  return paths.find((candidate) => {
+    try {
+      return !!candidate && fs.existsSync(candidate);
+    } catch (_e) {
+      return false;
+    }
+  }) || "";
+}
+function findFirstCommand(commands) {
+  const pathEntries = String(process["env"].PATH || "").split(path.delimiter).filter(Boolean);
+  const extensions = process.platform === "win32" ? String(process["env"].PATHEXT || ".EXE;.CMD;.BAT;.COM").split(";") : [""];
+  for (const command of commands) {
+    for (const entry of pathEntries) {
+      for (const extension of extensions) {
+        const executable = path.join(entry, process.platform === "win32" ? `${command}${extension}` : command);
+        if (fs.existsSync(executable)) return executable;
+      }
+    }
+  }
+  return "";
+}
+function getWindowsBrowserExecutable(browser) {
+  const normalized = normalizeBrowserName(browser);
+  const executable = normalized === "edge" ? "msedge.exe" : "chrome.exe";
+  const vendorPath = normalized === "edge" ? ["Microsoft", "Edge", "Application"] : ["Google", "Chrome", "Application"];
+  const roots = [
+    process["env"].LOCALAPPDATA,
+    process["env"].PROGRAMFILES,
+    process["env"]["PROGRAMFILES(X86)"]
+  ].filter(Boolean);
+  return findFirstExistingPath(roots.map((root) => path.join(root, ...vendorPath, executable)));
+}
+function isBrowserInstalled(browser) {
+  const normalized = normalizeBrowserName(browser);
+  if (!normalized) return false;
+  if (process.platform === "darwin") {
+    const appName = normalized === "edge" ? "Microsoft Edge.app" : "Google Chrome.app";
+    return !!findFirstExistingPath([
+      path.join("/Applications", appName),
+      path.join("/System/Applications", appName)
+    ]);
+  }
+  if (process.platform === "win32") {
+    return !!getWindowsBrowserExecutable(normalized);
+  }
+  return !!findFirstCommand(
+    normalized === "edge" ? ["microsoft-edge", "microsoft-edge-stable"] : ["google-chrome", "google-chrome-stable"]
+  );
+}
+function getBrowserToLaunch() {
+  const configured = normalizeBrowserName(process["env"].GECHO_BROWSER);
+  if (configured) return configured;
+  if (lastBrowserConnection?.browser) return lastBrowserConnection.browser;
+  if (isBrowserInstalled("chrome")) return "chrome";
+  if (isBrowserInstalled("edge")) return "edge";
+  return "";
+}
+function getBrowserLaunchSpec(browser) {
+  const normalized = normalizeBrowserName(browser);
+  const appName = normalized === "edge" ? "Microsoft Edge" : "Google Chrome";
+  if (!normalized) return null;
+  if (process.platform === "darwin") {
+    return {
+      command: "open",
+      args: ["-a", appName, "--args", "--new-window", "about:blank"]
+    };
+  }
+  if (process.platform === "win32") {
+    const browserPath = getWindowsBrowserExecutable(normalized);
+    if (browserPath) {
+      return {
+        command: browserPath,
+        args: ["--new-window", "about:blank"]
+      };
+    }
+    const executable2 = normalized === "edge" ? "msedge" : "chrome";
+    return {
+      command: "cmd.exe",
+      args: ["/d", "/s", "/c", "start", "", executable2, "--new-window", "about:blank"]
+    };
+  }
+  const executable = findFirstCommand(
+    normalized === "edge" ? ["microsoft-edge", "microsoft-edge-stable"] : ["google-chrome", "google-chrome-stable"]
+  ) || (normalized === "edge" ? "microsoft-edge" : "google-chrome");
+  return {
+    command: executable,
+    args: ["--new-window", "about:blank"]
+  };
+}
+async function launchBrowserForExtension() {
+  if (!AUTO_LAUNCH_BROWSER) {
+    return { attempted: false, launched: false, reason: "disabled" };
+  }
+  const browser = getBrowserToLaunch();
+  const spec = getBrowserLaunchSpec(browser);
+  if (!spec) {
+    return { attempted: false, launched: false, reason: "browser_unknown" };
+  }
+  if (browserLaunchPromise) return browserLaunchPromise;
+  if (Date.now() - lastBrowserLaunchAt < AUTO_LAUNCH_BROWSER_COOLDOWN_MS) {
+    return { attempted: false, launched: false, browser, reason: "cooldown" };
+  }
+  lastBrowserLaunchAt = Date.now();
+  browserLaunchPromise = new Promise((resolve) => {
+    if (AUTO_LAUNCH_BROWSER_DRY_RUN) {
+      console.log(`\u{1F9EA} Browser launch dry run: ${browser}`);
+      resolve({ attempted: true, launched: true, browser, dryRun: true });
+      return;
+    }
+    let child;
+    try {
+      child = spawn(spec.command, spec.args, {
+        // A detached Windows process starts in a separate process group. That
+        // extra isolation is not needed for a GUI browser after unref(), and
+        // can prevent an extension service worker from reconnecting when the
+        // bridge itself was started by a desktop MCP host.
+        detached: process.platform !== "win32",
+        stdio: "ignore",
+        windowsHide: true
+      });
+    } catch (e) {
+      resolve({ attempted: true, launched: false, browser, reason: e.message });
+      return;
+    }
+    child.once("error", (e) => {
+      resolve({ attempted: true, launched: false, browser, reason: e.message });
+    });
+    child.once("spawn", () => {
+      child.unref();
+      console.log(`\u{1F310} Started ${browser} while waiting for the extension connection`);
+      resolve({ attempted: true, launched: true, browser });
+    });
+  });
+  try {
+    return await browserLaunchPromise;
+  } finally {
+    browserLaunchPromise = null;
+  }
+}
+function waitForExtensionConnection(timeoutMs = EXTENSION_CONNECT_TIMEOUT_MS) {
+  return new Promise((resolve) => {
+    if (isExtensionConnected()) return resolve(true);
+    let waited = 0;
+    const checkTimer = setInterval(() => {
+      waited += EXTENSION_CONNECT_POLL_MS;
+      if (isExtensionConnected()) {
+        clearInterval(checkTimer);
+        resolve(true);
+      } else if (waited >= timeoutMs) {
+        clearInterval(checkTimer);
+        resolve(false);
+      }
+    }, EXTENSION_CONNECT_POLL_MS);
+  });
+}
+async function waitForExtensionReadyGracePeriod() {
+  const remainingMs = Math.max(0, EXTENSION_READY_GRACE_MS - (Date.now() - lastExtensionConnectedAt));
+  if (remainingMs === 0) return isExtensionConnected();
+  traceBridgeEvent("extension_ready_grace_wait_started", { remainingMs });
+  await new Promise((resolve) => setTimeout(resolve, remainingMs));
+  const connected = isExtensionConnected();
+  traceBridgeEvent("extension_ready_grace_wait_finished", { connected });
+  return connected;
+}
+async function ensureExtensionConnection(action) {
+  if (isExtensionConnected()) {
+    traceBridgeEvent("extension_already_connected", { action });
+    return { connected: true, launch: { attempted: false, launched: false, reason: "already_connected" } };
+  }
+  traceBridgeEvent("extension_connection_wait_started", { action });
+  const launch = await launchBrowserForExtension();
+  console.log(
+    `\u23F3 Extension not connected yet. Waiting up to ${EXTENSION_CONNECT_TIMEOUT_MS / 1e3}s (action: ${action}, browser: ${launch.browser || "unknown"})`
+  );
+  const connected = await waitForExtensionConnection();
+  const ready = connected && await waitForExtensionReadyGracePeriod();
+  traceBridgeEvent("extension_connection_wait_finished", {
+    action,
+    connected: ready,
+    browser: launch.browser || "",
+    launchReason: launch.reason || ""
+  });
+  return { connected: ready, launch };
+}
+function extensionConnectionError(connection) {
+  const launch = connection?.launch || {};
+  const details = [];
+  if (launch.reason === "browser_unknown") {
+    details.push("Bridge has not identified a browser yet. Open Edge or Chrome with the Gecho extension once, then retry.");
+  } else if (launch.reason === "disabled") {
+    details.push("Automatic browser launch is disabled (GECHO_AUTO_LAUNCH_BROWSER=0).");
+  } else if (launch.reason === "cooldown") {
+    details.push(`${launch.browser} was started recently; it did not reconnect in time.`);
+  } else if (launch.attempted && !launch.launched) {
+    details.push(`Failed to start ${launch.browser || "the saved browser"}: ${launch.reason || "unknown error"}`);
+  } else if (launch.attempted) {
+    details.push(`${launch.browser} was started, but its extension did not connect in time.`);
+  }
+  return [
+    "Extension not connected.",
+    ...details,
+    "Check that the Gecho extension is installed, enabled, and signed in for that browser profile."
+  ].join(" ");
+}
+lastBrowserConnection = loadLastBrowserConnection();
 function sanitizeJobForDisk(job = {}) {
   const copy = { ...job };
   delete copy.data;
@@ -4197,17 +4499,19 @@ function hydrateJobWithDataFromFile(job) {
     return job;
   }
 }
-function runAsyncAttempt({ jobId, action, params, payload, attempt }) {
-  if (!extensionSocket || extensionSocket.readyState !== 1) {
+async function runAsyncAttempt({ jobId, action, params, payload, attempt }) {
+  const connection = await ensureExtensionConnection(action);
+  if (!connection.connected) {
     updateJob(jobId, {
       status: "error",
       stage: "extension_disconnected",
-      error: "Extension not connected during async dispatch"
+      error: extensionConnectionError(connection)
     });
     return;
   }
   const requestId = `${jobId}:a${attempt}`;
   lastDispatchedRequestId = requestId;
+  traceBridgeEvent("action_dispatched", { action, requestId, async: true });
   requestIndex.set(requestId, { jobId, attempt, updatedAt: Date.now() });
   schedulePersistRequestIndex();
   appendJobEvent(jobId, "attempt_started", { attempt, requestId });
@@ -4290,14 +4594,19 @@ function gracefulShutdown(reason) {
     }
   }
 }
-var wss = new WebSocketServer({ port: WS_PORT, host: "127.0.0.1" });
-wss.on("connection", (ws) => {
-  console.log("\u2705 Chrome Extension connected to Service Layer");
+wss = new WebSocketServer({ port: WS_PORT, host: "127.0.0.1" });
+wss.on("connection", (ws, request) => {
+  const browser = detectBrowserFromUserAgent(request?.headers?.["user-agent"]);
+  if (browser) persistLastBrowserConnection(browser);
+  console.log(`\u2705 Browser extension connected to Service Layer${browser ? ` (${browser})` : ""}`);
   extensionSocket = ws;
+  lastExtensionConnectedAt = Date.now();
+  traceBridgeEvent("extension_connected", { browser, clientCount: wss.clients.size });
   ws.on("message", (message) => {
     try {
       const parsed = JSON.parse(message);
       if (parsed.method === "action_progress" && parsed.requestId) {
+        traceBridgeEvent("extension_progress", { requestId: parsed.requestId });
         const pending = pendingRequests.get(parsed.requestId);
         if (!pending) {
           console.warn(`WARN action_progress requestId not found: ${parsed.requestId}`);
@@ -4317,6 +4626,7 @@ wss.on("connection", (ws) => {
         }
       }
       if (parsed.method === "action_result" && parsed.requestId) {
+        traceBridgeEvent("extension_result", { requestId: parsed.requestId });
         console.log(`\u{1F4E9} Received result from extension (ID: ${parsed.requestId})`);
         const pending = pendingRequests.get(parsed.requestId);
         if (pending) {
@@ -4349,8 +4659,13 @@ wss.on("connection", (ws) => {
     }
   });
   ws.on("close", () => {
-    console.log("\u274C Chrome Extension disconnected");
-    extensionSocket = null;
+    console.log("\u274C Browser extension disconnected");
+    traceBridgeEvent("extension_disconnected", { clientCount: wss.clients.size });
+    if (extensionSocket === ws) extensionSocket = null;
+  });
+  ws.on("error", (error) => {
+    traceBridgeEvent("extension_socket_error", { message: error.message });
+    console.warn(`Browser extension WebSocket error: ${error.message}`);
   });
 });
 loadAsyncJobsFromDisk();
@@ -4378,7 +4693,14 @@ var server = http.createServer(async (req, res) => {
       servicePath: __filename,
       startedAt: SERVICE_STARTED_AT,
       sourceMtimeMs: getServiceSourceMtimeMs(),
-      dataDir: JOBS_DIR
+      dataDir: JOBS_DIR,
+      extensionConnected: isExtensionConnected(),
+      lastConnectedBrowser: lastBrowserConnection?.browser || null,
+      autoBrowserLaunch: {
+        enabled: AUTO_LAUNCH_BROWSER,
+        browser: getBrowserToLaunch() || null
+      },
+      bridgeTrace: bridgeTrace.slice(-30)
     }));
   }
   if (req.method === "POST" && req.url === "/shutdown") {
@@ -4431,29 +4753,10 @@ var server = http.createServer(async (req, res) => {
           res.statusCode = 400;
           return res.end(JSON.stringify({ error: "Missing action" }));
         }
-        if (!extensionSocket || extensionSocket.readyState !== 1) {
-          console.log(`\u23F3 Extension not connected yet. Waiting for connection... (action: ${action})`);
-          const maxWaitMs = 15e3;
-          const checkIntervalMs = 500;
-          let waited = 0;
-          await new Promise((resolve) => {
-            const checkTimer = setInterval(() => {
-              waited += checkIntervalMs;
-              if (extensionSocket && extensionSocket.readyState === 1) {
-                clearInterval(checkTimer);
-                resolve();
-              } else if (waited >= maxWaitMs) {
-                clearInterval(checkTimer);
-                resolve();
-              }
-            }, checkIntervalMs);
-          });
-          if (!extensionSocket || extensionSocket.readyState !== 1) {
-            res.statusCode = 503;
-            return res.end(JSON.stringify({
-              error: "Extension not connected. Chrome \u63D2\u4EF6\u672A\u8FDE\u63A5\u3002\n\u8BF7\u68C0\u67E5\uFF1A\n1. Chrome \u662F\u5426\u4FDD\u6301\u6253\u5F00\u72B6\u6001\n2. Gecho TikTok Bridge \u63D2\u4EF6\u662F\u5426\u4ECD\u5728\u8FD0\u884C\uFF08\u6269\u5C55\u56FE\u6807\u662F\u5426\u4EAE\u7740\uFF09\n3. TikTok tab \u662F\u5426\u6D3B\u8DC3\uFF08\u6700\u597D\u5728 tiktok.com \u9875\u9762\u4E0A\uFF09\n\u5982\u679C\u63D2\u4EF6\u521A\u542F\u52A8\uFF0C\u8BF7\u7B49\u5F85\u51E0\u79D2\u540E\u518D\u8BD5\u3002"
-            }));
-          }
+        const connection = await ensureExtensionConnection(action);
+        if (!connection.connected) {
+          res.statusCode = 503;
+          return res.end(JSON.stringify({ error: extensionConnectionError(connection) }));
         }
         const jobId = `job-${Date.now()}-${requestIdCounter++}`;
         console.log(`\u{1F680} Dispatching ASYNC action: [${action}], jobId: ${jobId}`);
@@ -4509,33 +4812,15 @@ var server = http.createServer(async (req, res) => {
           res.statusCode = 400;
           return res.end(JSON.stringify({ error: "Missing action" }));
         }
-        if (!extensionSocket || extensionSocket.readyState !== 1) {
-          console.log(`\u23F3 Extension not connected yet. Waiting for connection... (action: ${action})`);
-          const maxWaitMs = 15e3;
-          const checkIntervalMs = 500;
-          let waited = 0;
-          await new Promise((resolve) => {
-            const checkTimer = setInterval(() => {
-              waited += checkIntervalMs;
-              if (extensionSocket && extensionSocket.readyState === 1) {
-                clearInterval(checkTimer);
-                resolve();
-              } else if (waited >= maxWaitMs) {
-                clearInterval(checkTimer);
-                resolve();
-              }
-            }, checkIntervalMs);
-          });
-          if (!extensionSocket || extensionSocket.readyState !== 1) {
-            res.statusCode = 503;
-            return res.end(JSON.stringify({
-              error: "Extension not connected. Chrome \u63D2\u4EF6\u672A\u8FDE\u63A5\u3002\n\u8BF7\u68C0\u67E5\uFF1A\n1. Chrome \u662F\u5426\u4FDD\u6301\u6253\u5F00\u72B6\u6001\n2. Gecho TikTok Bridge \u63D2\u4EF6\u662F\u5426\u4ECD\u5728\u8FD0\u884C\uFF08\u6269\u5C55\u56FE\u6807\u662F\u5426\u4EAE\u7740\uFF09\n3. TikTok tab \u662F\u5426\u6D3B\u8DC3\uFF08\u6700\u597D\u5728 tiktok.com \u9875\u9762\u4E0A\uFF09\n\u5982\u679C\u63D2\u4EF6\u521A\u542F\u52A8\uFF0C\u8BF7\u7B49\u5F85\u51E0\u79D2\u540E\u518D\u8BD5\u3002"
-            }));
-          }
+        const connection = await ensureExtensionConnection(action);
+        if (!connection.connected) {
+          res.statusCode = 503;
+          return res.end(JSON.stringify({ error: extensionConnectionError(connection) }));
         }
         console.log(`\u{1F680} Dispatching action: [${action}]`);
         const requestId = `svc-${Date.now()}-${requestIdCounter++}`;
         lastDispatchedRequestId = requestId;
+        traceBridgeEvent("action_dispatched", { action, requestId, async: false });
         const { action: _a, ...params } = payload;
         const result = await new Promise((resolve) => {
           const timeoutId = setTimeout(() => {