@gecho-ai/gecho-bridge 1.1.37 → 1.1.38-beta.1

package/.claude-plugin/plugin.json

@@ -1,5 +1,5 @@
 {
   "name": "@gecho-ai/gecho-bridge",
-  "version": "1.1.37",
-  "description": "TikTok Search Tool for OpenClaw"
+  "version": "1.1.38",
+  "description": "Browser research tools for OpenClaw via the Gecho Chrome Extension"
 }

package/README.md

@@ -1,16 +1,16 @@
 # Gecho Bridge 🚀
 
-**Gecho Bridge connects AI clients such as OpenClaw, Hermes, Trae, and Claude Code to a live Chrome browser through MCP and the Gecho Chrome extension.** Use it to search TikTok videos, collect structured metadata, save JSON results, and run async product, trend, competitor, and content insight workflows.
+**Gecho Bridge connects AI clients such as OpenClaw, Hermes, Trae, and Claude Code to a live Chrome browser through MCP and the Gecho Chrome extension.** Use it to search TikTok videos, YouTube Shorts, Facebook Reels, X posts, and Amazon products, collect structured metadata, save JSON results, and run async product, trend, competitor, and content insight workflows.
 
 ## ⚠️ Critical Prerequisite: Read Before Use
 
-Gecho Bridge cannot work from the README, Skill page, or MCP config alone. Before the first TikTok search or insight job, all 3 items below are required:
+Gecho Bridge cannot work from the README, Skill page, or MCP config alone. Before the first platform search or insight job, all 3 items below are required:
 
 1. **Configure Gecho Bridge MCP** in your AI client.
 2. **Install the Gecho Chrome extension** and log in to your Gecho account.
-3. **Log in to TikTok web in Chrome** and keep the logged-in TikTok tab open.
+3. **Log in to the target platform in Chrome** and keep the logged-in platform tab open.
 
-If any of these are missing, TikTok search and insight tools may fail even if the Skill or plugin is installed.
+If any of these are missing, the selected platform tool may fail even if the Skill or plugin is installed.
 
 ## 🚀 3-Step Quick Start
 
@@ -125,6 +125,49 @@ A new team Skill also requires at least one team category ID. For an existing Sk
 
 Official documentation: [CLI installation](https://skillhub.cn/install/skillhub.md), [community publishing](https://skillhub.cn/ai/release.md), [enterprise publishing](https://skillhub.cn/enterprise/dashboard/publish), and [enterprise API keys](https://skillhub.cn/enterprise/dashboard/keys).
 
+### WorkBuddy Skill Packaging
+
+WorkBuddy uses a separate Skill package format, so a Tencent SkillHub staging copy must not be uploaded directly.
+The repository creates Git-ignored copies under `tmp/workbuddy-publish/`, adds
+`display_name`, `display_name_en`, `description_zh`, `description_en`, `version`, and `author`, and packages
+each Skill using WorkBuddy's official `skills/<skill-name>/SKILL.md` layout.
+
+```bash
+# Create WorkBuddy-only staging copies
+npm run skillhub:workbuddy:stage
+
+# Build all English and Chinese ZIPs and validate their structure
+npm run skillhub:workbuddy:dry-run
+
+# Prepare one Chinese Skill
+npm run skillhub:workbuddy:dry-run -- \
+  --skill tiktok-video-search --locale zh-CN
+```
+
+ZIP files are written to `tmp/workbuddy-publish/archives/` (each must be no larger than 3MB) for manual upload to the
+[WorkBuddy Open Platform](https://open.workbuddy.cn/). The script has no login or submit command and never uses
+Tencent SkillHub `skh_...` or `sk-ent-...` credentials. See the official [WorkBuddy Skill documentation](https://open.workbuddy.cn/docs/skill).
+
+### WorkBuddy Open Platform Connector
+
+WorkBuddy's open platform Connector publication is separate from Skill publication. The Connector ZIP contains the
+platform metadata and the MCP startup configuration; it is not one of the Skill ZIPs above.
+
+```bash
+# Build and validate the Connector ZIP for the current package version
+npm run skillhub:workbuddy:connector:dry-run
+```
+
+The uploadable file is generated at:
+
+```text
+tmp/workbuddy-connector/gecho-bridge-workbuddy-v1.1.37.zip
+```
+
+It uses the public `@gecho-ai/gecho-bridge@1.1.37` npm package as a local Stdio MCP server. The generated ZIP contains
+`connector-meta.json`, `mcp.json`, `icon.svg`, and a concise Connector Skill. It is only staged locally; this command
+does not upload or submit a review request. See the official [WorkBuddy Connector documentation](https://open.workbuddy.cn/docs/connector).
+
 ### Option 2: One-Click Setup in Hermes (Hermes Skill Hub)
 You can quickly add the service to Hermes and restart it with the following commands:
 ```bash
@@ -167,7 +210,7 @@ After the environment is configured and your AI client has restarted, you can di
 ### ✅ Self-Check Before First Use
 1. `gecho-bridge` MCP is configured, or the `@gecho-ai/gecho-bridge-bundle` plugin is installed.
 2. The [Gecho browser extension](https://chromewebstore.google.com/detail/pjkaeenpekolahdbccjfenjcmanemlbj?utm_source=item-share-cb) is installed.
-3. TikTok is open in Chrome and the account is logged in.
+3. The target platform is open in Chrome and the account is logged in (TikTok, YouTube, Facebook, X, or Amazon as applicable).
 4. The Gecho extension is logged in to a Gecho account and online.
 5. The TikTok page is not stuck or left on a CAPTCHA page.
 
@@ -185,8 +228,9 @@ Focused single-tool Skills are also available:
 - **Amazon**: `amazon-search`, `amazon-product`, `amazon-reviews`.
 - **TikTok**: `tiktok-video-search` for keyword-based video search; `tiktok-video` for a specific video’s detail, comments, and replies; `tiktok-influencer`, `tiktok-insight`, `tiktok-product`, and `tiktok-shop-search` for focused workflows.
 - **X**: `x-search` and `x-post-detail`.
+- **Short-form video**: `youtube-shorts-search` for YouTube Shorts and `facebook-reels-search` for Facebook Reels.
 
-Use `tiktok-video-search` when you want to discover videos by keyword. Use `tiktok-video` when you already have a video URL and need its detail data. If you want the full TikTok research workflow, use `tiktok-search`.
+Use `tiktok-video-search`, `youtube-shorts-search`, or `facebook-reels-search` when you want to discover short-form videos by keyword. Use `tiktok-video` when you already have a video URL and need its detail data. If you want the full TikTok research workflow, use `tiktok-search`.
 
 ### 🔍 Basic Search (`tiktok_search`)
 Suitable for quickly retrieving and collecting video data.
@@ -237,6 +281,8 @@ If installation is successful, you should see `Status: loaded` and `MCP servers:
 ### 2. Note about the local background service
 - Gecho Bridge automatically starts a local service on demand so the MCP client can talk to the browser extension.
 - This service only listens on `127.0.0.1` and is expected to stay available while you use the plugin.
+- You can also manage it independently with `npm run server:start`, `npm run server:status`, and `npm run server:stop`.
+- To run it after user login, use `npx gecho-bridge-server install`; remove the startup entry with `npx gecho-bridge-server uninstall`.
 - If Chrome or the extension was restarted and requests start failing, first run `openclaw gateway restart`, then try again.
 
 ### 3. Error: Extension not connected
@@ -285,6 +331,8 @@ npm run server
 - **Client layer** (`mcp-client.js`): The standard MCP STDIO integration layer, responsible for communicating with clients such as OpenClaw, Hermes, and Trae, and declaring the Tools specification.
 - **Service layer** (`server.js`): The local resident service layer, responsible for communicating with the browser extension via WebSocket and executing the actual scraping and persistence. (Supports a Lazy Start mechanism and launches only when needed.)
 
+See [`docs/scheduled-flywheel-bridge.md`](docs/scheduled-flywheel-bridge.md) for scheduled flywheel APIs, standalone Bridge operation, and user-level login startup.
+
 ## License
 
 MIT

package/README.zh.md

@@ -1,16 +1,16 @@
 # Gecho Bridge 🚀
 
-**Gecho Bridge 通过 MCP 和 Gecho Chrome 扩展，把 OpenClaw、Hermes、Trae、Claude Code 等 AI 客户端连接到真实 Chrome 浏览器。** 你可以用它搜索 TikTok 视频、采集结构化元数据、保存 JSON 结果，并运行异步的产品、趋势、竞品和内容洞察工作流。
+**Gecho Bridge 通过 MCP 和 Gecho Chrome 扩展，把 OpenClaw、Hermes、Trae、Claude Code 等 AI 客户端连接到真实 Chrome 浏览器。** 你可以用它搜索 TikTok 视频、YouTube Shorts、Facebook Reels、X 帖子和 Amazon 商品，采集结构化元数据、保存 JSON 结果，并运行异步的产品、趋势、竞品和内容洞察工作流。
 
 ## ⚠️ 重要前置：使用前必看
 
-Gecho Bridge 不能只靠 README、Skill 页面或 MCP 配置单独运行。首次搜索 TikTok 或运行洞察任务前，必须同时满足下面 3 个条件：
+Gecho Bridge 不能只靠 README、Skill 页面或 MCP 配置单独运行。首次搜索平台内容或运行洞察任务前，必须同时满足下面 3 个条件：
 
 1. **在 AI 客户端中配置 Gecho Bridge MCP**。
 2. **安装 Gecho Chrome 扩展**，并在扩展中登录 Gecho 账号。
-3. **在 Chrome 中登录 TikTok 网页版**，并保持已登录的 TikTok 标签页打开。
+3. **在 Chrome 中登录目标平台**，并保持已登录的平台标签页打开。
 
-如果任一条件缺失，即使 Skill 或 Plugin 已安装，TikTok 搜索和洞察功能也可能无法正常运行。
+如果任一条件缺失，即使 Skill 或 Plugin 已安装，所选平台的搜索功能也可能无法正常运行。
 
 ## 🚀 3 步快速上手
 
@@ -125,6 +125,54 @@ npm run skillhub:tencent:publish -- \
 
 官方文档：[CLI 安装](https://skillhub.cn/install/skillhub.md)、[公共发布](https://skillhub.cn/ai/release.md)、[企业发布控制台](https://skillhub.cn/enterprise/dashboard/publish)、[企业 API Key](https://skillhub.cn/enterprise/dashboard/keys)。
 
+### WorkBuddy Skill 发布准备
+
+WorkBuddy 使用独立的 Skill 包格式，不能直接上传腾讯 SkillHub 副本。项目会从源 Skill 创建被 Git 忽略的
+`tmp/workbuddy-publish/` 副本，补齐 `display_name`、`display_name_en`、`description_zh`、
+`description_en`、`version` 和 `author`，并按 WorkBuddy 官方要求使用
+`skills/<skill-name>/SKILL.md` 目录结构打包。
+
+```bash
+# 只生成 WorkBuddy 临时副本
+npm run skillhub:workbuddy:stage
+
+# 生成全部中英文 ZIP，并进行本地结构校验
+npm run skillhub:workbuddy:dry-run
+
+# 只准备一个中文 Skill
+npm run skillhub:workbuddy:dry-run -- \
+  --skill tiktok-video-search --locale zh-CN
+```
+
+输出的 ZIP 位于 `tmp/workbuddy-publish/archives/`（单个不超过 3MB），可在 [WorkBuddy 开放平台](https://open.workbuddy.cn/)
+手动上传。脚本没有登录或自动提交功能，不会使用腾讯 SkillHub 的 `skh_...` 或 `sk-ent-...` Key。
+WorkBuddy 官方格式参考：[Skill 文档](https://open.workbuddy.cn/docs/skill)。
+
+### Aily SkillHub 发布
+
+Aily 当前通过网页上传 Skill 压缩包。项目提供了浏览器自动化脚本，复用已登录的 Edge，
+从 `tmp/manual-skill-packages/manifest.tsv` 读取压缩包，并使用每个 Skill 的
+`publish.json` 中 `platforms.aily-skillhub.displayName` 自动填写展示名称。
+
+首次使用需要完全退出 Edge 后，以远程调试端口启动，再在该窗口登录 Aily：
+
+```bash
+/Applications/Microsoft\ Edge.app/Contents/MacOS/Microsoft\ Edge \
+  --remote-debugging-port=9222
+```
+
+然后执行：
+
+```bash
+npm run skill:package:manual
+npm run skillhub:aily:dry-run -- --skill tiktok-shop-search --locale zh-CN
+npm run skillhub:aily:publish -- --skill tiktok-shop-search --locale zh-CN
+```
+
+脚本只修改网页表单，不修改源 Skill，也不保存浏览器凭证；发布结果写入
+`tmp/aily-browser-publish/results.json`。完整参数和批量发布方式见
+[`scripts/README.md`](scripts/README.md)。
+
 ### 方式二：在 Hermes 中一键配置 (Hermes Skill Hub)
 你可以通过以下命令将服务快捷添加到 Hermes 并重启：
 ```bash
@@ -167,7 +215,7 @@ claude mcp add gecho-bridge -- npx -y @gecho-ai/gecho-bridge@latest
 ### ✅ 首次使用前自检
 1. 已配置 `gecho-bridge` MCP，或已安装 `@gecho-ai/gecho-bridge-bundle` Plugin。
 2. 已安装 [Gecho 浏览器扩展](https://chromewebstore.google.com/detail/pjkaeenpekolahdbccjfenjcmanemlbj?utm_source=item-share-cb)。
-3. Chrome 中已打开 TikTok 并登录账号。
+3. Chrome 中已打开目标平台并登录账号（按任务选择 TikTok、YouTube、Facebook、X 或 Amazon）。
 4. Gecho 扩展已登录 Gecho 账号并处于在线状态。
 5. TikTok 页面未卡住或未停在验证码页面。
 
@@ -185,8 +233,9 @@ Gecho 提供四个聚合 Skill：
 - **Amazon**：`amazon-search`、`amazon-product`、`amazon-reviews`。
 - **TikTok**：`tiktok-video-search` 用于按关键词搜索视频；`tiktok-video` 用于指定视频的详情、评论和回复；另有 `tiktok-influencer`、`tiktok-insight`、`tiktok-product` 和 `tiktok-shop-search`。
 - **X**：`x-search` 和 `x-post-detail`。
+- **短视频**：`youtube-shorts-search` 用于 YouTube Shorts，`facebook-reels-search` 用于 Facebook Reels。
 
-需要按关键词发现视频时使用 `tiktok-video-search`；已有视频 URL、需要获取视频详情时使用 `tiktok-video`。需要完整 TikTok 研究工作流时，使用 `tiktok-search`。
+需要按关键词发现短视频时使用 `tiktok-video-search`、`youtube-shorts-search` 或 `facebook-reels-search`；已有视频 URL、需要获取视频详情时使用 `tiktok-video`。需要完整 TikTok 研究工作流时，使用 `tiktok-search`。
 
 ### 🔍 基础搜索 (`tiktok_search`)
 适用于快速检索和收集视频数据。
@@ -237,6 +286,8 @@ openclaw plugins info @gecho-ai/gecho-bridge-bundle
 ### 2. 关于本地后台服务的说明
 - Gecho Bridge 会在需要时自动拉起本地服务，用来让 MCP 客户端和浏览器扩展通信。
 - 这个服务只监听 `127.0.0.1`，在你使用插件期间保持可用属于正常行为。
+- 也可以独立管理服务：`npm run server:start`、`npm run server:status`、`npm run server:stop`。
+- 如需用户登录后自动运行，可执行 `npx gecho-bridge-server install`；卸载启动项执行 `npx gecho-bridge-server uninstall`。
 - 如果你重启了 Chrome 或扩展，随后请求开始失败，先执行一次 `openclaw gateway restart`，再重试。
 
 ### 3. 报错：提示扩展未连接
@@ -285,6 +336,8 @@ npm run server
 - **Client 层** (`mcp-client.js`)：标准 MCP STDIO 接入层，负责与 OpenClaw/Hermes/Trae 等客户端通信，并声明 Tools 规范。
 - **Service 层** (`server.js`)：本地常驻服务层，负责与浏览器扩展通过 WebSocket 通信，执行实际抓取与落盘。（支持 Lazy Start 机制，仅在需要时自动拉起）。
 
+自动飞轮的定时任务接口、Bridge 独立运行和用户级开机启动说明见 [`docs/scheduled-flywheel-bridge.md`](docs/scheduled-flywheel-bridge.md)。
+
 ## License
 
 MIT

package/action-result.js

@@ -0,0 +1,53 @@
+const ACTION_RESULT_METADATA_FIELDS = ["meta", "errorCode", "errorMessage"];
+
+function isRecord(value) {
+  return value !== null && typeof value === "object" && !Array.isArray(value);
+}
+
+function hasOwn(value, key) {
+  return Object.prototype.hasOwnProperty.call(value, key);
+}
+
+function getActionResultMetadata(result) {
+  const metadata = {};
+  if (!isRecord(result)) return metadata;
+
+  for (const field of ACTION_RESULT_METADATA_FIELDS) {
+    if (hasOwn(result, field)) metadata[field] = result[field];
+  }
+  return metadata;
+}
+
+function createActionResultEnvelope(message) {
+  const source = isRecord(message) ? message : {};
+  return {
+    data: source.data,
+    ...getActionResultMetadata(source)
+  };
+}
+
+function normalizeActionResult(result) {
+  if (!isRecord(result) || !hasOwn(result, "data")) return { data: result };
+  return {
+    data: result.data,
+    ...getActionResultMetadata(result)
+  };
+}
+
+function isHardActionResultFailure(result) {
+  if (!isRecord(result)) return false;
+
+  const hasFailure = ["errorCode", "errorMessage"].some((field) => {
+    return hasOwn(result, field) && result[field] !== undefined && result[field] !== null && result[field] !== "";
+  });
+  if (!hasFailure) return false;
+
+  return String(result.meta?.status || "").toLowerCase() !== "partial";
+}
+
+module.exports = {
+  createActionResultEnvelope,
+  getActionResultMetadata,
+  isHardActionResultFailure,
+  normalizeActionResult
+};

package/bridge-service.js

@@ -0,0 +1,187 @@
+#!/usr/bin/env node
+
+"use strict";
+
+const http = require("node:http");
+const path = require("node:path");
+const { spawn } = require("node:child_process");
+const packageJson = require("./package.json");
+const { getDefaultDataDir } = require("./data-dir");
+const {
+  getStartupStatus,
+  installStartup,
+  uninstallStartup
+} = require("./bridge-startup");
+
+const HTTP_PORT = Number(process.env.GECHO_HTTP_PORT || 18793);
+const SERVICE_BASE_URL = `http://127.0.0.1:${HTTP_PORT}`;
+const SERVICE_PATH = path.join(__dirname, "server.js");
+const SERVICE_PROTOCOL_VERSION = 2;
+const START_TIMEOUT_MS = Math.max(1000, Number(process.env.GECHO_SERVICE_START_TIMEOUT_MS || 10000));
+const POLL_INTERVAL_MS = 200;
+
+function requestJson(requestPath, method = "GET") {
+  return new Promise((resolve) => {
+    const request = http.request(`${SERVICE_BASE_URL}${requestPath}`, { method }, (response) => {
+      let body = "";
+      response.setEncoding("utf8");
+      response.on("data", (chunk) => { body += chunk; });
+      response.on("end", () => {
+        let parsed = {};
+        try { parsed = JSON.parse(body || "{}"); } catch (_error) {}
+        resolve({
+          ok: response.statusCode >= 200 && response.statusCode < 300,
+          statusCode: response.statusCode || 0,
+          body: parsed
+        });
+      });
+    });
+    request.on("error", () => resolve({ ok: false, statusCode: 0, body: {} }));
+    request.setTimeout(800, () => {
+      request.destroy();
+      resolve({ ok: false, statusCode: 0, body: {} });
+    });
+    request.end();
+  });
+}
+
+function expectedDataDir() {
+  return path.resolve(process.env.GECHO_DATA_DIR || getDefaultDataDir());
+}
+
+function isCompatibleService(info) {
+  if (!info || info.status !== "ok") return false;
+  if (Number(info.serviceProtocolVersion || 0) !== SERVICE_PROTOCOL_VERSION) return false;
+  if (info.packageVersion && info.packageVersion !== packageJson.version) return false;
+  return !info.dataDir || path.resolve(String(info.dataDir)) === expectedDataDir();
+}
+
+async function getServiceInfo() {
+  const response = await requestJson("/ping");
+  return response.ok ? response.body : null;
+}
+
+async function waitForService({ running = true, timeoutMs = START_TIMEOUT_MS } = {}) {
+  const startedAt = Date.now();
+  while (Date.now() - startedAt <= timeoutMs) {
+    const info = await getServiceInfo();
+    if (running ? isCompatibleService(info) : !info) return info;
+    await new Promise((resolve) => setTimeout(resolve, POLL_INTERVAL_MS));
+  }
+  return null;
+}
+
+async function stopService() {
+  const info = await getServiceInfo();
+  if (!info) return { status: "not running" };
+
+  await requestJson("/shutdown", "POST");
+  const stopped = await waitForService({ running: false });
+  if (stopped === null && Number.isInteger(Number(info.pid)) && Number(info.pid) > 0) {
+    try { process.kill(Number(info.pid), "SIGTERM"); } catch (_error) {}
+    await waitForService({ running: false, timeoutMs: 3000 });
+  }
+  return { status: "stopped", pid: info.pid || null };
+}
+
+async function startService() {
+  const current = await getServiceInfo();
+  if (isCompatibleService(current)) {
+    return { status: "already running", pid: current.pid || null };
+  }
+  if (current) await stopService();
+
+  const child = spawn(process.execPath, [SERVICE_PATH], {
+    cwd: __dirname,
+    env: process.env,
+    detached: true,
+    stdio: "ignore",
+    windowsHide: true
+  });
+  child.unref();
+  const started = await waitForService();
+  if (!started) {
+    const error = new Error("Bridge service did not become ready");
+    error.code = "BRIDGE_SERVICE_START_FAILED";
+    throw error;
+  }
+  return { status: "started", pid: started.pid || child.pid || null };
+}
+
+async function printStatus() {
+  const info = await getServiceInfo();
+  if (info) {
+    process.stdout.write(`${JSON.stringify(info)}\n`);
+    return true;
+  }
+  process.stdout.write(`${JSON.stringify({ status: "not running", url: SERVICE_BASE_URL })}\n`);
+  return false;
+}
+
+function printUsage() {
+  process.stdout.write([
+    "Usage: gecho-bridge-server <start|status|stop|restart|install|uninstall|startup-status>",
+    "",
+    "  start    Start the standalone local Bridge service",
+    "  status   Print Bridge health and scheduler status",
+    "  stop     Stop the local Bridge service",
+    "  restart  Restart the local Bridge service",
+    "  install  Install a user-level login startup entry",
+    "  uninstall Remove the user-level login startup entry",
+    "  startup-status  Print login startup configuration status",
+    ""
+  ].join("\n"));
+}
+
+async function main(argv = process.argv.slice(2)) {
+  const command = String(argv[0] || "start").trim().toLowerCase();
+  if (command === "status") {
+    const running = await printStatus();
+    process.exitCode = running ? 0 : 1;
+    return;
+  }
+  if (command === "start") {
+    process.stdout.write(`${JSON.stringify(await startService())}\n`);
+    return;
+  }
+  if (command === "stop") {
+    process.stdout.write(`${JSON.stringify(await stopService())}\n`);
+    return;
+  }
+  if (command === "restart") {
+    await stopService();
+    process.stdout.write(`${JSON.stringify(await startService())}\n`);
+    return;
+  }
+  if (command === "install") {
+    process.stdout.write(`${JSON.stringify(installStartup())}\n`);
+    return;
+  }
+  if (command === "uninstall") {
+    process.stdout.write(`${JSON.stringify(uninstallStartup())}\n`);
+    return;
+  }
+  if (command === "startup-status") {
+    const status = getStartupStatus();
+    process.stdout.write(`${JSON.stringify(status)}\n`);
+    process.exitCode = status.configured ? 0 : 1;
+    return;
+  }
+  printUsage();
+  process.exitCode = 2;
+}
+
+if (require.main === module) {
+  main().catch((error) => {
+    console.error(`gecho-bridge-server: ${error.message || error}`);
+    process.exitCode = 1;
+  });
+}
+
+module.exports = {
+  getServiceInfo,
+  isCompatibleService,
+  main,
+  startService,
+  stopService
+};