@gecho-ai/gecho-bridge 1.0.0

package/README.md

@@ -0,0 +1,70 @@
+# Gecho Bridge 🚀
+
+Gecho Bridge is an MCP (Model Context Protocol) server that connects AI Agents (like Claude Desktop, Cursor, or OpenClaw) to TikTok via a Chrome extension. It allows your AI models to search and retrieve TikTok video metadata directly from the browser.
+
+## Features
+
+- **Automated Search**: Search TikTok with keywords and auto-scroll to fetch results.
+- **Data Retrieval**: Get video IDs, titles, like counts, and play URLs.
+- **Dual-Layer Architecture**: A lightweight MCP Client that automatically manages a persistent Service Layer.
+- **Lazy Start**: The bridge automatically starts the background service when needed.
+
+## Installation
+
+### 1. Install via npm
+```bash
+npm install -g @gecho-ai/gecho-bridge
+```
+
+### 2. Install Chrome Extension
+Ensure you have the Gecho TikTok Extension installed and active in your Chrome browser. The bridge communicates with this extension via WebSocket.
+
+## Configuration
+
+### Claude Desktop
+Add the following to your `claude_desktop_config.json`:
+
+```json
+{
+  "mcpServers": {
+    "gecho-bridge": {
+      "command": "npx",
+      "args": ["-y", "@gecho-ai/gecho-bridge@latest"]
+    }
+  }
+}
+```
+
+### Cursor
+Go to Settings -> MCP.
+Add a new MCP server:
+- **Name**: gecho-bridge
+- **Type**: command
+- **Command**: `npx -y @gecho-ai/gecho-bridge@latest`
+
+## Usage
+
+Once configured, you can ask your AI:
+
+- "Search TikTok for 'cooking recipes'"
+- "Find trending TikTok videos about AI agents"
+
+## Development
+
+If you want to run the bridge locally from source:
+
+```bash
+git clone https://github.com/gecho-ai/bridge.git
+cd bridge
+npm install
+node mcp-client.js
+```
+
+## Architecture
+
+- **Service Layer (server.js)**: Maintains the WebSocket connection with the Chrome extension (Port 18792) and exposes an HTTP API (Port 18793).
+- **Client Layer (mcp-client.js)**: Implements the MCP Stdio protocol and forwards requests to the Service Layer.
+
+## License
+
+MIT

package/index.js

@@ -0,0 +1,284 @@
+#!/usr/bin/env node
+
+// 🐷 1.1 MCP 标准格式: 引入 MCP SDK 核心类。StdioServerTransport 是最通用的通信方式。
+const { Server } = require("@modelcontextprotocol/sdk/server/index.js");
+const { StdioServerTransport } = require("@modelcontextprotocol/sdk/server/stdio.js");
+const {
+  CallToolRequestSchema,
+  ListToolsRequestSchema,
+} = require("@modelcontextprotocol/sdk/types.js");
+const fs = require("fs");
+const path = require("path");
+
+// 🐷 1.2 桥接技术栈: 引入 WebSocketServer，用于与 Chrome 扩展建立双向通信。
+const { WebSocketServer } = require("ws");
+
+// 🐷 1.3 桥接逻辑: 初始化 WebSocket 服务器变量。
+const WS_PORT = 18792;
+let extensionSocket = null;
+let wss = null;
+
+// 🐷 1.4 改造点: 增加一个 Map 来存储等待中的请求回调，实现“请求-响应”模式。
+// 参考了 mcp-chrome-bridge/dist/native-messaging-host.js [L114] 的设计。
+const pendingRequests = new Map();
+let requestIdCounter = 1;
+
+/**
+ * 🐷 1.4.1 异步等待插件连接的辅助函数
+ * 逻辑: 每隔 500ms 检查一次 extensionSocket，最多等待 timeoutMs。
+ * 解决问题: MCP 启动瞬间插件可能还在重连空窗期。
+ */
+async function waitForExtension(timeoutMs = 10000) {
+  const start = Date.now();
+  while (Date.now() - start < timeoutMs) {
+    if (extensionSocket && extensionSocket.readyState === 1) {
+      return true;
+    }
+    await new Promise(resolve => setTimeout(resolve, 500));
+  }
+  return false;
+}
+
+function initWss() {
+  if (wss) return wss;
+  
+  wss = new WebSocketServer({ port: WS_PORT, host: "127.0.0.1" });
+  
+  wss.on("error", (err) => {
+    if (err.code === "EADDRINUSE") {
+      console.error(`\n❌ 错误: 端口 ${WS_PORT} 已被占用!`);
+      console.error(`这通常是因为另一个 tiktok_bridge 进程正在运行。`);
+      console.error(`请执行以下命令清理残留进程后重试:`);
+      console.error(`lsof -i :${WS_PORT} | grep LISTEN | awk '{print $2}' | xargs kill -9\n`);
+    } else {
+      console.error("WebSocket Server Error:", err);
+    }
+    process.exit(1);
+  });
+
+  wss.on("connection", (ws) => {
+    console.error("Chrome Extension connected to Bridge!");
+    extensionSocket = ws;
+
+    ws.on("message", (message) => {
+      try {
+        const parsed = JSON.parse(message);
+        // 🐷 1.4.2 响应匹配逻辑: 使用 requestId 确保结果精准回传给对应的 MCP 请求。
+        // 参考了 mcp-chrome-bridge/dist/native-messaging-host.js [L54] 的 handleMessage 逻辑。
+        if (parsed.method === "action_result" && parsed.requestId) {
+          console.error(`🐷 收到插件抓取的数据结果 (ID: ${parsed.requestId})`);
+          const pending = pendingRequests.get(parsed.requestId);
+          if (pending) {
+            clearTimeout(pending.timeoutId);
+            pending.resolve(parsed.data);
+            pendingRequests.delete(parsed.requestId);
+          }
+        }
+      } catch (e) {
+        console.error("Error parsing extension message:", e);
+      }
+    });
+
+    ws.on("close", () => {
+      console.error("Chrome Extension disconnected.");
+      extensionSocket = null;
+    });
+  });
+  return wss;
+}
+
+// 🐷 2.1 MCP 标准格式: 创建 MCP Server 实例，定义服务器名称和版本。
+const server = new Server(
+  {
+    name: "tiktok-bridge",
+    version: "1.0.0",
+  },
+  {
+    capabilities: {
+      // 🐷 2.2 MCP 标准格式: 声明支持“工具 (Tools)”功能。
+      tools: {},
+    },
+  }
+);
+
+// 🐷 3.1 Skills 标准格式: 定义工具列表。这是 AI 模型能理解的“技能”描述。
+server.setRequestHandler(ListToolsRequestSchema, async () => {
+  return {
+    tools: [
+      {
+        // 🐷 3.2 Skills 标准格式: 工具名称和描述。
+        name: "tiktok_search_top_200",
+        description: "在 TikTok 上搜索关键词，自动滚动加载至少 200 条结果，并全部返回。",
+        // 🐷 3.3 Skills 标准格式: 输入参数 Schema。
+        inputSchema: {
+          type: "object",
+          properties: {
+            query: {
+              type: "string",
+              description: "搜索关键词 (例如: '猫薄荷')"
+            }
+          },
+          required: ["query"]
+        }
+      }
+    ]
+  };
+});
+
+// 🐷 4.1 MCP 标准格式: 处理具体的工具调用请求。
+server.setRequestHandler(CallToolRequestSchema, async (request) => {
+  if (request.params.name === "tiktok_search_top_200") {
+    const { query } = request.params.arguments;
+
+    // 🐷 4.2 桥接逻辑: 参考 mcp-chrome-bridge/dist/server/index.js [L48] 的逻辑，先确保连接就绪。
+    // 增加 10s 的异步等待窗口，防止插件重连期间直接报错。
+    const isConnected = await waitForExtension(10000);
+    if (!isConnected) {
+      return {
+        content: [{ type: "text", text: "错误: Chrome 插件未连接，请确保插件已开启并显示 ON。" }],
+        isError: true
+      };
+    }
+
+    // 🐷 4.3 改造点: 发送带 requestId 的指令并等待插件回传。
+    // 参考了 mcp-chrome-bridge/dist/native-messaging-host.js [L114] 的设计。
+    const result = await new Promise((resolve, reject) => {
+      const requestId = `mcp-${Date.now()}-${requestIdCounter++}`;
+      
+      const timeoutId = setTimeout(() => {
+        if (pendingRequests.has(requestId)) {
+          pendingRequests.delete(requestId);
+          resolve({ error: "抓取超时 (120s)，请检查浏览器是否已停止滚动" });
+        }
+      }, 120000);
+
+      pendingRequests.set(requestId, { resolve, reject, timeoutId });
+
+      const payload = {
+        method: "execute_action",
+        params: { action: "search", params: { query } },
+        requestId: requestId // 🐷 关键: 发送请求 ID
+      };
+      extensionSocket.send(JSON.stringify(payload));
+    });
+
+    // 🐷 4.5 改造点: 将抓取到的 200+ 条完整数据持久化存储到本地文件夹
+    let savedPath = "";
+    if (Array.isArray(result) && result.length > 0) {
+      const dataDir = path.join(__dirname, "..", "data");
+      if (!fs.existsSync(dataDir)) {
+        fs.mkdirSync(dataDir, { recursive: true });
+      }
+      
+      // 1. 生成固定文件名 (适配 OpenClaw 预期)
+      const fixedFilename = `${query}_search_results.json`;
+      const fixedPath = path.join(dataDir, fixedFilename);
+      fs.writeFileSync(fixedPath, JSON.stringify(result, null, 2), "utf8");
+      
+      // 2. 生成带时间戳的备份
+      const timestamp = new Date().toISOString().replace(/[:.]/g, "-");
+      const backupFilename = `${query}_${timestamp}.json`;
+      const backupPath = path.join(dataDir, backupFilename);
+      fs.writeFileSync(backupPath, JSON.stringify(result, null, 2), "utf8");
+      
+      savedPath = fixedPath;
+      console.error(`🐷 数据已保存至: ${fixedPath} (备份: ${backupFilename})`);
+    }
+
+    // 🐷 4.6 MCP 标准格式: 返回抓取到的前 20 条高赞视频给 AI，并告知存储路径。
+    const top20 = Array.isArray(result) ? result.slice(0, 20) : [];
+    
+    return {
+      content: [
+        { 
+          type: "text", 
+          text: `✅ 抓取完成！共获取 ${Array.isArray(result) ? result.length : 0} 条数据。\n` +
+                `📂 原始数据已存储至: ${savedPath}\n\n` +
+                `以下是点赞最高的前 20 条结果：\n` +
+                JSON.stringify(top20, null, 2) 
+        }
+      ]
+    };
+  }
+
+  throw new Error("Tool not found");
+});
+
+// 🐷 5.1 启动模式检测: 支持 MCP 模式和 CLI 直接调用模式
+// 参考了 mcp-chrome-bridge/dist/cli.js 的思路，支持多模式启动。
+async function run() {
+  const args = process.argv.slice(2);
+  let toolName = "";
+  let query = "cat";
+
+  for (let i = 0; i < args.length; i++) {
+    if (args[i] === "--tool" && i + 1 < args.length) {
+      toolName = args[i + 1];
+      i++;
+    } else if (args[i] === "--query" && i + 1 < args.length) {
+      query = args[i + 1];
+      i++;
+    } else if (i === 0 && !args[i].startsWith("--")) {
+      toolName = args[i];
+    } else if (i === 1 && !args[i].startsWith("--")) {
+      query = args[i];
+    }
+  }
+
+  const isCliMode = toolName === "tiktok_search_top_200" || toolName === "search";
+
+  if (isCliMode) {
+    // 🐷 CLI 模式: 简化后的逻辑，复用 pendingRequests。
+    console.error(`🐷 CLI 模式启动: 正在搜索 [${query}]...`);
+    initWss();
+    
+    // 等待插件连接
+    const isConnected = await waitForExtension(15000);
+    if (!isConnected) {
+      console.error("❌ 错误: 插件未连接，请确保插件已开启。");
+      process.exit(1);
+    }
+
+    const requestId = `cli-${Date.now()}`;
+    const result = await new Promise((resolve) => {
+      const timeoutId = setTimeout(() => {
+        pendingRequests.delete(requestId);
+        resolve({ error: "抓取超时 (120s)" });
+      }, 120000);
+
+      pendingRequests.set(requestId, { resolve, timeoutId });
+
+      extensionSocket.send(JSON.stringify({
+        method: "execute_action",
+        params: { action: "search", params: { query } },
+        requestId: requestId
+      }));
+    });
+
+    // 保存结果并退出
+    if (Array.isArray(result)) {
+      const dataDir = path.join(__dirname, "..", "data");
+      if (!fs.existsSync(dataDir)) fs.mkdirSync(dataDir, { recursive: true });
+      const filePath = path.join(dataDir, `${query}_search_results.json`);
+      fs.writeFileSync(filePath, JSON.stringify(result, null, 2));
+      console.error(`🐷 数据已保存至: ${filePath}`);
+      process.stdout.write(JSON.stringify(result, null, 2) + "\n");
+    } else {
+      console.error("❌ 抓取失败:", result.error || "未知错误");
+    }
+    process.exit(0);
+  } else {
+    // 🐷 标准 MCP 模式 (STDIO)
+    initWss();
+    const transport = new StdioServerTransport();
+    await server.connect(transport);
+    console.error("🐷 TikTok Bridge MCP Server 已启动 (STDIO 模式)");
+  }
+}
+
+// 🐷 修改后的启动入口
+run().catch((error) => {
+  console.error("Status: Error");
+  console.error("Error details:", error);
+  process.exit(1);
+});

package/mcp-client.js

@@ -0,0 +1,179 @@
+#!/usr/bin/env node
+
+/**
+ * Client 层 (Client Layer) - 2.0 自动增强版
+ * 职责: 
+ * 1. 提供标准的 MCP Stdio 协议接口。
+ * 2. [新增] 启动时自动检查 Service 层是否在线。
+ * 3. [新增] 若 Service 不在线，自动静默启动 server.js (Lazy Start)。
+ * 4. 转发工具请求到 Service 层。
+ */
+
+const { Server } = require("@modelcontextprotocol/sdk/server/index.js");
+const { StdioServerTransport } = require("@modelcontextprotocol/sdk/server/stdio.js");
+const {
+  CallToolRequestSchema,
+  ListToolsRequestSchema,
+} = require("@modelcontextprotocol/sdk/types.js");
+const http = require("http");
+const { spawn } = require("child_process");
+const path = require("path");
+
+const HTTP_SERVICE_URL = "http://127.0.0.1:18793/search";
+const SERVICE_PATH = path.join(__dirname, "server.js");
+
+const server = new Server(
+  { name: "tiktok-bridge-client", version: "1.1.0" },
+  { capabilities: { tools: {} } }
+);
+
+/**
+ * 检查服务是否在线
+ */
+function checkServiceAlive() {
+  return new Promise((resolve) => {
+    const req = http.get("http://127.0.0.1:18793/ping", (res) => {
+      resolve(res.statusCode === 200);
+    });
+    req.on("error", () => resolve(false));
+    req.end();
+  });
+}
+
+/**
+ * 自动拉起 Service 层
+ */
+async function ensureServiceRunning() {
+  const alive = await checkServiceAlive();
+  if (alive) {
+    console.error("🐷 Service Layer is already running.");
+    return;
+  }
+
+  console.error("🐷 Service Layer not found. Starting it automatically...");
+  
+  const child = spawn("node", [SERVICE_PATH], {
+    detached: true,
+    stdio: "ignore" // 静默启动，不占用当前终端
+  });
+
+  child.unref(); // 让子进程独立运行，父进程退出时不影响它
+
+  // 等待服务启动成功
+  let retries = 5;
+  while (retries > 0) {
+    await new Promise(r => setTimeout(r, 1000));
+    if (await checkServiceAlive()) {
+      console.error("✅ Service Layer started successfully.");
+      return;
+    }
+    retries--;
+  }
+  throw new Error("Failed to start Service Layer after 5s.");
+}
+
+// 1. 定义工具
+server.setRequestHandler(ListToolsRequestSchema, async () => {
+  return {
+    tools: [
+      {
+        name: "tiktok_search_top_200",
+        description: "在 TikTok 上搜索关键词，自动滚动加载至少 200 条结果，并全部返回。",
+        inputSchema: {
+          type: "object",
+          properties: {
+            query: { type: "string", description: "搜索关键词 (例如: '猫薄荷')" }
+          },
+          required: ["query"]
+        }
+      }
+    ]
+  };
+});
+
+// 2. 转发工具请求到 Service 层
+server.setRequestHandler(CallToolRequestSchema, async (request) => {
+  if (request.params.name === "tiktok_search_top_200") {
+    const { query } = request.params.arguments;
+
+    try {
+      const requestService = () => new Promise((resolve, reject) => {
+        const req = http.request(HTTP_SERVICE_URL, {
+          method: "POST",
+          headers: { "Content-Type": "application/json" }
+        }, (res) => {
+          let body = "";
+          res.on("data", (chunk) => body += chunk);
+          res.on("end", () => {
+            let parsed = {};
+            try {
+              parsed = JSON.parse(body || "{}");
+            } catch (_e) {
+              parsed = {};
+            }
+            if (res.statusCode >= 400) {
+              reject(new Error(parsed.error || `HTTP ${res.statusCode}`));
+            } else {
+              resolve(parsed.data);
+            }
+          });
+        });
+
+        req.on("error", () => reject(new Error("Service Layer communication error")));
+        req.write(JSON.stringify({ query }));
+        req.end();
+      });
+
+      let result;
+      try {
+        result = await requestService();
+      } catch (firstError) {
+        if (String(firstError.message || "").includes("communication error")) {
+          await ensureServiceRunning();
+          await new Promise(r => setTimeout(r, 800));
+          result = await requestService();
+        } else {
+          throw firstError;
+        }
+      }
+
+      if (result.error) {
+        return { content: [{ type: "text", text: `❌ 错误: ${result.error}` }], isError: true };
+      }
+
+      const top20 = Array.isArray(result) ? result.slice(0, 20) : [];
+      return {
+        content: [
+          { 
+            type: "text", 
+            text: `✅ 抓取完成！共获取 ${Array.isArray(result) ? result.length : 0} 条数据。\n` +
+                  `📂 完整结果已保存在本地 data 目录。\n\n` +
+                  `以下是点赞最高的前 20 条结果：\n` +
+                  JSON.stringify(top20, null, 2) 
+          }
+        ]
+      };
+    } catch (e) {
+      return { 
+        content: [{ type: "text", text: `❌ 转发失败: ${e.message}.` }], 
+        isError: true 
+      };
+    }
+  }
+  throw new Error("Tool not found");
+});
+
+// 3. 启动
+async function main() {
+  try {
+    await ensureServiceRunning();
+    const transport = new StdioServerTransport();
+    await server.connect(transport);
+    console.error("🐷 TikTok Bridge MCP Client is running (STDIO)");
+  } catch (e) {
+    console.error(`❌ Client initialization failed: ${e.message}`);
+    process.exit(1);
+  }
+}
+
+main().catch(console.error);

package/package.json

@@ -0,0 +1,35 @@
+{
+  "name": "@gecho-ai/gecho-bridge",
+  "version": "1.0.0",
+  "description": "MCP Bridge for TikTok Extension Relay - Connecting LLMs to TikTok via Chrome Extension",
+  "main": "mcp-client.js",
+  "bin": {
+    "gecho-bridge": "mcp-client.js"
+  },
+  "files": [
+    "*.js",
+    "package.json"
+  ],
+  "scripts": {
+    "start": "node mcp-client.js",
+    "server": "node server.js"
+  },
+  "keywords": [
+    "mcp",
+    "tiktok",
+    "bridge",
+    "automation",
+    "llm",
+    "gecho"
+  ],
+  "author": "Gecho AI",
+  "license": "MIT",
+  "type": "commonjs",
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.27.1",
+    "ws": "^8.19.0"
+  },
+  "publishConfig": {
+  "access": "public"
+  }
+}

package/search_direct.js

@@ -0,0 +1,65 @@
+#!/usr/bin/env node
+
+const http = require('http');
+
+async function searchTikTok(query) {
+  console.log(`🔍 正在搜索 TikTok: "${query}"...`);
+  
+  return new Promise((resolve, reject) => {
+    const req = http.request('http://127.0.0.1:18793/search', {
+      method: 'POST',
+      headers: {
+        'Content-Type': 'application/json'
+      }
+    }, (res) => {
+      let data = '';
+      
+      res.on('data', (chunk) => {
+        data += chunk;
+      });
+      
+      res.on('end', () => {
+        try {
+          const result = JSON.parse(data);
+          console.log(`✅ 搜索完成！状态码: ${res.statusCode}`);
+          
+          if (res.statusCode >= 400) {
+            console.error(`❌ 错误: ${result.error || '未知错误'}`);
+            reject(new Error(result.error || `HTTP ${res.statusCode}`));
+          } else {
+            console.log(`📊 获取到 ${Array.isArray(result.data) ? result.data.length : 0} 条结果`);
+            
+            // 显示前5条结果
+            if (Array.isArray(result.data) && result.data.length > 0) {
+              console.log('\n📈 点赞最高的前5条结果:');
+              result.data.slice(0, 5).forEach((item, index) => {
+                console.log(`${index + 1}. ${item.title || '无标题'}`);
+                console.log(`   作者: ${item.author || '未知'}`);
+                console.log(`   点赞: ${item.likes || 0} | 评论: ${item.comments || 0}`);
+                console.log(`   链接: ${item.url || '无链接'}`);
+                console.log('');
+              });
+            }
+            
+            resolve(result);
+          }
+        } catch (error) {
+          console.error('❌ 解析响应失败:', error);
+          reject(error);
+        }
+      });
+    });
+    
+    req.on('error', (error) => {
+      console.error('❌ 请求失败:', error.message);
+      reject(error);
+    });
+    
+    req.write(JSON.stringify({ query }));
+    req.end();
+  });
+}
+
+// 执行搜索
+const query = process.argv[2] || '麦香鱼';
+searchTikTok(query).catch(console.error);

package/search_mcp.js

@@ -0,0 +1,67 @@
+#!/usr/bin/env node
+
+const { Client } = require("@modelcontextprotocol/sdk/client/index.js");
+const { StdioClientTransport } = require("@modelcontextprotocol/sdk/client/stdio.js");
+const { spawn } = require("child_process");
+const path = require("path");
+
+async function searchTikTok(query) {
+  console.log(`🔍 正在搜索 TikTok: "${query}"...`);
+  
+  // 启动 MCP 客户端进程
+  const mcpClient = spawn("node", [path.join(__dirname, "mcp-client.js")], {
+    stdio: ["pipe", "pipe", "pipe"] // stdin, stdout, stderr
+  });
+
+  // 创建 MCP 客户端
+  const client = new Client(
+    { name: "tiktok-search-client", version: "1.0.0" },
+    { capabilities: {} }
+  );
+
+  // 使用 stdio 传输
+  const transport = new StdioClientTransport({
+    command: "node",
+    args: [path.join(__dirname, "mcp-client.js")]
+  });
+
+  try {
+    // 连接
+    await client.connect(transport);
+    console.log("✅ 已连接到 TikTok Bridge MCP 客户端");
+
+    // 列出可用工具
+    const tools = await client.request({
+      method: "tools/list",
+      params: {}
+    });
+    console.log("📋 可用工具:", tools.tools.map(t => t.name));
+
+    // 调用搜索工具
+    const result = await client.request({
+      method: "tools/call",
+      params: {
+        name: "tiktok_search_top_200",
+        arguments: { query }
+      }
+    });
+
+    console.log("✅ 搜索完成!");
+    console.log("📊 结果:", JSON.stringify(result, null, 2));
+
+    // 断开连接
+    await client.close();
+    mcpClient.kill();
+
+    return result;
+
+  } catch (error) {
+    console.error("❌ 搜索失败:", error);
+    mcpClient.kill();
+    throw error;
+  }
+}
+
+// 执行搜索
+const query = process.argv[2] || "麦香鱼";
+searchTikTok(query).catch(console.error);

package/server.js

@@ -0,0 +1,129 @@
+#!/usr/bin/env node
+
+/**
+ * Service 层 (Service Layer)
+ * 职责: 
+ * 1. 维持与 Chrome 扩展的 WebSocket 连接 (端口 18792)。
+ * 2. 暴露 HTTP API (端口 18793) 供 Client 层调用。
+ * 3. 负责数据的抓取、清洗和本地持久化。
+ */
+
+const { WebSocketServer } = require("ws");
+const http = require("http");
+const fs = require("fs");
+const path = require("path");
+
+const WS_PORT = 18792;
+const HTTP_PORT = 18793;
+
+let extensionSocket = null;
+const pendingRequests = new Map();
+let requestIdCounter = 1;
+
+// --- WebSocket Server (与插件通信) ---
+const wss = new WebSocketServer({ port: WS_PORT, host: "127.0.0.1" });
+
+wss.on("connection", (ws) => {
+  console.log("✅ Chrome Extension connected to Service Layer");
+  extensionSocket = ws;
+
+  ws.on("message", (message) => {
+    try {
+      const parsed = JSON.parse(message);
+      if (parsed.method === "action_result" && parsed.requestId) {
+        console.log(`📩 Received result from extension (ID: ${parsed.requestId})`);
+        const pending = pendingRequests.get(parsed.requestId);
+        if (pending) {
+          clearTimeout(pending.timeoutId);
+          pending.resolve(parsed.data);
+          pendingRequests.delete(parsed.requestId);
+        }
+      }
+    } catch (e) {
+      console.error("Error parsing extension message:", e);
+    }
+  });
+
+  ws.on("close", () => {
+    console.log("❌ Chrome Extension disconnected");
+    extensionSocket = null;
+  });
+});
+
+wss.on("error", (err) => {
+  if (err.code === "EADDRINUSE") {
+    console.error(`❌ WS Port ${WS_PORT} is in use!`);
+    process.exit(1);
+  } else {
+    console.error("WS Error:", err);
+  }
+});
+
+// --- HTTP Server (供 Client 层调用) ---
+const server = http.createServer(async (req, res) => {
+  res.setHeader("Content-Type", "application/json");
+
+  // 健康检查接口
+  if (req.method === "GET" && req.url === "/ping") {
+    return res.end(JSON.stringify({ status: "ok" }));
+  }
+
+  if (req.method === "POST" && req.url === "/search") {
+    let body = "";
+    req.on("data", chunk => { body += chunk; });
+    req.on("end", async () => {
+      try {
+        const { query } = JSON.parse(body);
+        if (!query) {
+          res.statusCode = 400;
+          return res.end(JSON.stringify({ error: "Missing query" }));
+        }
+
+        if (!extensionSocket || extensionSocket.readyState !== 1) {
+          res.statusCode = 503;
+          return res.end(JSON.stringify({ error: "Extension not connected" }));
+        }
+
+        console.log(`🔍 Processing search request for: [${query}]`);
+        const requestId = `svc-${Date.now()}-${requestIdCounter++}`;
+        
+        const result = await new Promise((resolve) => {
+          const timeoutId = setTimeout(() => {
+            pendingRequests.delete(requestId);
+            resolve({ error: "Scraping timeout (120s)" });
+          }, 120000);
+
+          pendingRequests.set(requestId, { resolve, timeoutId });
+
+          extensionSocket.send(JSON.stringify({
+            method: "execute_action",
+            params: { action: "search", params: { query } },
+            requestId: requestId
+          }));
+        });
+
+        // 持久化存储
+        if (Array.isArray(result) && result.length > 0) {
+          const dataDir = path.join(__dirname, "..", "data");
+          if (!fs.existsSync(dataDir)) fs.mkdirSync(dataDir, { recursive: true });
+          const fixedPath = path.join(dataDir, `${query}_search_results.json`);
+          fs.writeFileSync(fixedPath, JSON.stringify(result, null, 2), "utf8");
+        }
+
+        res.end(JSON.stringify({ success: true, data: result }));
+      } catch (e) {
+        res.statusCode = 500;
+        res.end(JSON.stringify({ error: e.message }));
+      }
+    });
+  } else {
+    res.statusCode = 404;
+    res.end(JSON.stringify({ error: "Not found" }));
+  }
+});
+
+server.listen(HTTP_PORT, "127.0.0.1", () => {
+  console.log(`🚀 TikTok Bridge Service Layer is running:`);
+  console.log(`   - WebSocket (Extension): ws://127.0.0.1:${WS_PORT}`);
+  console.log(`   - HTTP API (Client): http://127.0.0.1:${HTTP_PORT}`);
+});