@gecho-ai/gecho-bridge 1.1.19 → 1.1.26

package/.claude-plugin/plugin.json

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

package/README.md

@@ -1,37 +1,54 @@
 # Gecho Bridge 🚀
 
-🌐 **Gecho Bridge** is a universal MCP (Model Context Protocol) tool designed to build a bridge between your large language model (LLM) and your local browser.
-After installation, whether you use **OpenClaw**, **Hermes**, or **Trae**, your AI assistant can directly control the browser to automate TikTok search, data collection, and deep business opportunity insights.
+**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.
 
----
+## ⚠️ Critical Prerequisite: Read Before Use
 
-## ✨ Who Is It For
+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:
 
-- 📊 **Competitor analysis**: Enter a keyword and quickly get engagement data for top TikTok videos.
-- 💡 **Finding winning products**: Use deep insight tools to analyze trends in specific categories (such as "portable blender") and identify underserved blue-ocean opportunities.
-- 🤖 **Automated operations**: Let a large model directly control the browser, auto-scroll, scrape data, and generate reports, eliminating tedious manual counting.
+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.
 
-## 🚀 What It Can Do
+If any of these are missing, TikTok search and insight tools may fail even if the Skill or plugin is installed.
 
-- Automatically launch Chrome, search TikTok for a target keyword, and simulate natural human-like scrolling.
-- Collect large volumes of structured data (video ID, title, likes, playback link, and more) and safely save it as JSON files.
-- Run **asynchronous deep insights** based on large-scale retrieval to intelligently summarize winning-product trends and potential business opportunities.
+## 🚀 3-Step Quick Start
 
-## 🔗 Related Links
+### Step 1: Install the Gecho Chrome extension
 
-- **Official Website**: [https://gecho.ai/](https://gecho.ai/)
-- **GitHub**: [https://github.com/gecho-ai/gecho-bridge](https://github.com/gecho-ai/gecho-bridge)
-- **ClawHub Plugin Page**: [https://clawhub.ai/p/gecho-ai](https://clawhub.ai/p/gecho-ai)
-- **Chrome Browser Extension**: [Install from Chrome Web Store](https://chromewebstore.google.com/detail/pjkaeenpekolahdbccjfenjcmanemlbj?utm_source=item-share-cb)
+1. Open the [Gecho Chrome extension download page](https://chromewebstore.google.com/detail/pjkaeenpekolahdbccjfenjcmanemlbj?utm_source=item-share-cb).
+2. Click `Add to Chrome`, then confirm `Add extension`.
 
-## 💬 Community & Feedback
+### Step 2: Log in to the Gecho extension
 
-Welcome to join our community for discussion or feedback:
+Open the Gecho extension in Chrome, log in to your Gecho account, and keep the extension online.
 
-- **Discord Community**: [Join Discord](https://discord.gg/RFDVZMR6Tn)
-- **WeCom Group**: Scan the QR code below to join
+### Step 3: Log in to TikTok web
 
-![WeCom QR Code](https://github.com/gecho-ai/gecho-bridge/blob/main/qywx.jpg)
+Open TikTok in Chrome, log in to the TikTok web app, and keep the logged-in TikTok tab open while using Gecho.
+
+After setup is complete, return to OpenClaw Dashboard, Hermes, or your MCP client and ask:
+
+- "Search computers on TikTok"
+- "Search hamburgers on TikTok"
+- "Run TikTok insight for portable blender"
+
+## 🔗 Official Links & Setup Help
+
+- **Official Website**: [https://gecho.ai/](https://gecho.ai/)
+- **Chrome Extension**: [Install from Chrome Web Store](https://chromewebstore.google.com/detail/pjkaeenpekolahdbccjfenjcmanemlbj?utm_source=item-share-cb)
+- **OpenClaw Setup Video**: [OpenClaw + TikTok setup tutorial](https://www.youtube.com/watch?v=ggwY9hISHcQ)
+- **Hermes Setup Video**: [Hermes + TikTok setup tutorial](https://www.youtube.com/watch?v=zHKnuWnxt_c)
+- **YouTube Channel**: [@Gecho-AI](https://www.youtube.com/@Gecho-AI)
+- **GitHub**: [https://github.com/gecho-ai/gecho-bridge](https://github.com/gecho-ai/gecho-bridge)
+- **ClawHub Plugin Page**: [https://clawhub.ai/p/gecho-ai](https://clawhub.ai/p/gecho-ai)
+- **Discord Support**: [Join Discord](https://discord.gg/RFDVZMR6Tn)
+- **WeCom Group**: [View group QR code](https://github.com/gecho-ai/gecho-bridge/blob/main/qywx.jpg)
+- **1:1 Support**: [View personal support QR code](https://github.com/gecho-ai/gecho-bridge/blob/main/wx.jpg)
+
+| WeCom Group | 1:1 Support |
+| :---: | :---: |
+| <img src="https://raw.githubusercontent.com/gecho-ai/gecho-bridge/main/qywx.jpg" width="160" alt="WeCom Group QR Code" /> | <img src="https://raw.githubusercontent.com/gecho-ai/gecho-bridge/main/wx.jpg" width="160" alt="Personal Support QR Code" /> |
 
 ---
 
@@ -45,7 +62,9 @@ The **Skill** on ClawHub mainly provides calling instructions for the large mode
 ### 0. Prerequisites
 1. **Node.js**: >= 18 (must support `npm` / `npx`).
 2. **Browser extension**: Please [install the Gecho browser extension here first](https://chromewebstore.google.com/detail/pjkaeenpekolahdbccjfenjcmanemlbj?utm_source=item-share-cb).
-3. **Network and state**: Make sure your local network can access TikTok reliably, and log in to both your browser account and the browser extension.
+3. **Gecho login**: Open the Gecho extension in Chrome and log in to your Gecho account. Keep the extension online.
+4. **TikTok login**: Open TikTok in Chrome, log in to the TikTok web app, and keep the logged-in TikTok tab open.
+5. **Network and state**: Make sure your local network can access TikTok reliably and the TikTok tab is not blocked by CAPTCHA, login walls, or a frozen page.
 
 ### Option 1: One-Click Installation in OpenClaw (ClawHub)
 ClawHub offers two installation types: `Skill` and `Plugin`.
@@ -76,6 +95,7 @@ hermes mcp add gecho-bridge --command npx --args="-y" --args="@gecho-ai/gecho-br
 hermes restart
 ```
 *After restart, you can check the installation status with `hermes mcp list`.*
+*Reference only: if Hermes reports `npx` or `node` as missing even though Node is installed on your machine, that is usually a Hermes shell/PATH issue rather than a Gecho Bridge issue. On macOS with Homebrew, one workaround is to register the MCP server with an absolute command path: `hermes mcp add gecho-bridge --command /opt/homebrew/bin/npx --args="-y" --args="@gecho-ai/gecho-bridge@latest"` and then run `hermes restart`.*
 
 ### Option 3: Configure in General Clients Such as Trae / Claude Desktop
 In MCP clients that support manual configuration, open the corresponding `mcp.json` or `claude_desktop_config.json` file and add the following node:
@@ -90,6 +110,16 @@ In MCP clients that support manual configuration, open the corresponding `mcp.js
 }
 ```
 
+### Option 4: One-Click Setup in Claude Code
+You can quickly add the service to Claude Code with the following command:
+```bash
+claude mcp add gecho-bridge -- npx -y @gecho-ai/gecho-bridge@latest
+```
+- By default, the configuration is saved at the **project level** (`.claude/settings.json`).
+- Use `--scope user` to make it available for all projects, or `--scope local` for a local-only configuration.
+- After adding, use `claude mcp list` to verify the server is registered.
+- Restart Claude Code if the MCP tools don't appear immediately.
+
 ---
 
 ## 🏁 Quick Start & Common Workflows
@@ -100,7 +130,18 @@ After the environment is configured and your AI client has restarted, you can di
 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.
-4. The Gecho extension is logged in and online, and the TikTok page is not stuck or left on a CAPTCHA page.
+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.
+
+### 🧩 Skills
+
+Gecho provides both an aggregate TikTok Skill and focused single-tool Skills:
+
+- **`tiktok-search`**: the default aggregate Skill for the complete TikTok search and insight workflow. It covers `tiktok_search`, `tiktok_insight`, and `check_insight_status`.
+- **`tiktok-video-search`**: a focused distribution Skill for keyword-based TikTok video search and metadata collection.
+- **`tiktok-insight`**: a focused distribution Skill for TikTok product, trend, competitor, and content insight jobs, plus insight status checks.
+
+If you only need one focused capability, use the single-tool Skills. If you want the full research workflow, use `tiktok-search`.
 
 ### 🔍 Basic Search (`tiktok_search`)
 Suitable for quickly retrieving and collecting video data.
@@ -167,6 +208,24 @@ If installation is successful, you should see `Status: loaded` and `MCP servers:
 
 ---
 
+## ❓ FAQ
+
+### Why is the Chrome extension required? Can't I just use the web page?
+
+Gecho needs real-time platform data from a live browser session, such as TikTok videos and other platform data in Gecho workflows. The Chrome extension connects the AI workflow to your logged-in Chrome session; the Skill page alone cannot collect this data.
+
+### Why do I need to log in to TikTok? Can I use it without login?
+
+TikTok limits content access for logged-out users. After you log in, the extension can access the complete data available in your browser session, such as video captions/scripts, comments, engagement data, and other signals when available.
+
+Gecho does not ask for or collect your TikTok password, private account information, or publish anything on your behalf.
+
+### Need help?
+
+Join our [Discord](https://discord.gg/RFDVZMR6Tn), scan the [WeCom group QR code](https://github.com/gecho-ai/gecho-bridge/blob/main/qywx.jpg), or scan the [personal support QR code](https://github.com/gecho-ai/gecho-bridge/blob/main/wx.jpg) for 1:1 support.
+
+---
+
 ## 🧑‍💻 Local Development
 
 For developers who want to build on top of this tool:

package/README.zh.md

@@ -1,37 +1,54 @@
 # Gecho Bridge 🚀
 
-🌐 **Gecho Bridge** 是一款通用的 MCP（Model Context Protocol）工具，旨在为你的大语言模型（LLM）与本地浏览器之间搭建一座桥梁。
-安装后，无论是使用 **OpenClaw**、**Hermes** 还是 **Trae**，你的 AI 助手都能直接控制浏览器，自动化完成 TikTok 搜索、数据抓取与深度商机洞察。
+**Gecho Bridge 通过 MCP 和 Gecho Chrome 扩展，把 OpenClaw、Hermes、Trae、Claude Code 等 AI 客户端连接到真实 Chrome 浏览器。** 你可以用它搜索 TikTok 视频、采集结构化元数据、保存 JSON 结果，并运行异步的产品、趋势、竞品和内容洞察工作流。
 
----
+## ⚠️ 重要前置：使用前必看
 
-## ✨ 适合谁用
+Gecho Bridge 不能只靠 README、Skill 页面或 MCP 配置单独运行。首次搜索 TikTok 或运行洞察任务前，必须同时满足下面 3 个条件：
 
-- 📊 **分析竞品**：输入关键词，快速获取 TikTok 前排高赞视频的各项互动数据。
-- 💡 **寻找爆款**：使用深度洞察工具分析特定品类（如 "portable blender"）的流行趋势，捕捉未被满足的市场蓝海。
-- 🤖 **自动化运营**：让大模型直接指挥浏览器，自动翻页抓取并生成数据报表，免去繁琐的手动统计。
+1. **在 AI 客户端中配置 Gecho Bridge MCP**。
+2. **安装 Gecho Chrome 扩展**，并在扩展中登录 Gecho 账号。
+3. **在 Chrome 中登录 TikTok 网页版**，并保持已登录的 TikTok 标签页打开。
 
-## 🚀 能做什么
+如果任一条件缺失，即使 Skill 或 Plugin 已安装，TikTok 搜索和洞察功能也可能无法正常运行。
 
-- 自动唤起 Chrome 并在 TikTok 搜索指定关键词，模拟真人自然滚动加载。
-- 抓取海量结构化数据（视频 ID、标题、点赞量、播放链接等）并自动安全落盘为 JSON 文件。
-- 执行基于大数据检索的**异步深度洞察**，智能提炼爆款趋势与潜在商机。
+## 🚀 3 步快速上手
 
-## 🔗 相关链接
+### 第一步：安装 Gecho Chrome 扩展
 
-- **官网**：[https://gecho.ai/](https://gecho.ai/)
-- **GitHub**：[https://github.com/gecho-ai/gecho-bridge](https://github.com/gecho-ai/gecho-bridge)
-- **ClawHub 插件页**：[https://clawhub.ai/p/gecho-ai](https://clawhub.ai/p/gecho-ai)
-- **Chrome 浏览器扩展**：[前往 Chrome 网上应用店下载](https://chromewebstore.google.com/detail/pjkaeenpekolahdbccjfenjcmanemlbj?utm_source=item-share-cb)
+1. 打开 [Gecho Chrome 扩展下载页](https://chromewebstore.google.com/detail/pjkaeenpekolahdbccjfenjcmanemlbj?utm_source=item-share-cb)。
+2. 点击 `添加至 Chrome`，然后确认 `添加扩展程序`。
 
-## 💬 交流与反馈
+### 第二步：登录 Gecho 扩展
 
-欢迎加入我们的社区进行交流或反馈问题：
+在 Chrome 中打开 Gecho 扩展，登录 Gecho 账号，并保持扩展在线。
 
-- **Discord 社区**：[点击加入 Discord](https://discord.gg/RFDVZMR6Tn)
-- **企业微信群**：扫描下方二维码加入
+### 第三步：登录 TikTok 网页版
 
-![企业微信二维码](https://github.com/gecho-ai/gecho-bridge/blob/main/qywx.jpg)
+在 Chrome 中打开 TikTok 网页版并登录账号，使用 Gecho 时保持已登录的 TikTok 标签页打开。
+
+完成后，回到 OpenClaw Dashboard、Hermes 或其他 MCP 客户端，直接发送：
+
+- “Search 电脑 on TikTok”
+- “Search 汉堡 on TikTok”
+- “Run TikTok insight for portable blender”
+
+## 🔗 官方链接与安装帮助
+
+- **官网**：[https://gecho.ai/](https://gecho.ai/)
+- **Chrome 扩展**：[前往 Chrome 网上应用店下载](https://chromewebstore.google.com/detail/pjkaeenpekolahdbccjfenjcmanemlbj?utm_source=item-share-cb)
+- **OpenClaw 安装教程**：[OpenClaw + TikTok 安装视频](https://www.youtube.com/watch?v=ggwY9hISHcQ)
+- **Hermes 安装教程**：[Hermes + TikTok 安装视频](https://www.youtube.com/watch?v=zHKnuWnxt_c)
+- **YouTube 主页**：[@Gecho-AI](https://www.youtube.com/@Gecho-AI)
+- **GitHub**：[https://github.com/gecho-ai/gecho-bridge](https://github.com/gecho-ai/gecho-bridge)
+- **ClawHub 插件页**：[https://clawhub.ai/p/gecho-ai](https://clawhub.ai/p/gecho-ai)
+- **Discord 支持**：[点击加入 Discord](https://discord.gg/RFDVZMR6Tn)
+- **企业微信群**：[查看群二维码](https://github.com/gecho-ai/gecho-bridge/blob/main/qywx.jpg)
+- **1 对 1 客服**：[查看客服二维码](https://github.com/gecho-ai/gecho-bridge/blob/main/wx.jpg)
+
+| 企业微信群 | 1 对 1 客服 |
+| :---: | :---: |
+| <img src="https://raw.githubusercontent.com/gecho-ai/gecho-bridge/main/qywx.jpg" width="160" alt="企业微信群二维码" /> | <img src="https://raw.githubusercontent.com/gecho-ai/gecho-bridge/main/wx.jpg" width="160" alt="1 对 1 客服二维码" /> |
 
 ---
 
@@ -45,7 +62,9 @@ ClawHub 上的 **Skill** 主要提供给大模型的调用指令，本身不是
 ### 0. 前置环境要求
 1. **Node.js**：>= 18（需支持 `npm` / `npx`）。
 2. **浏览器扩展**：请先[点击此处安装 Gecho 浏览器扩展](https://chromewebstore.google.com/detail/pjkaeenpekolahdbccjfenjcmanemlbj?utm_source=item-share-cb)。
-3. **网络与状态**：确保本地网络可稳定访问 TikTok，并在浏览器中登录账号，登录浏览器扩展。
+3. **Gecho 登录**：在 Chrome 中打开 Gecho 扩展，并登录 Gecho 账号，保持扩展在线。
+4. **TikTok 登录**：在 Chrome 中打开 TikTok 网页版并登录账号，保持已登录的 TikTok 标签页打开。
+5. **网络与状态**：确保本地网络可稳定访问 TikTok，且 TikTok 页面没有停在验证码、登录墙或卡死状态。
 
 ### 方式一：在 OpenClaw 中一键安装 (ClawHub)
 ClawHub 中有两种安装方式：`Skill` 与 `Plugin`。
@@ -76,6 +95,7 @@ hermes mcp add gecho-bridge --command npx --args="-y" --args="@gecho-ai/gecho-br
 hermes restart
 ```
 *重启后，可通过 `hermes mcp list` 检查安装状态。*
+*仅供参考：如果你的机器已经安装了 Node，但 Hermes 仍提示 `npx` 或 `node` 不存在，这通常是 Hermes 自身 shell/PATH 环境的问题，不是 Gecho Bridge 的问题。在 macOS + Homebrew 下，一个常见绕过方式是改用绝对路径注册 MCP：`hermes mcp add gecho-bridge --command /opt/homebrew/bin/npx --args="-y" --args="@gecho-ai/gecho-bridge@latest"`，然后执行 `hermes restart`。*
 
 ### 方式三：在 Trae / Claude Desktop 等通用客户端配置
 在支持手动配置的 MCP 客户端中，打开对应的 `mcp.json` 或 `claude_desktop_config.json` 文件，添加如下节点：
@@ -90,6 +110,16 @@ hermes restart
 }
 ```
 
+### 方式四：在 Claude Code 中一键配置
+你可以通过以下命令将服务快捷添加到 Claude Code 中：
+```bash
+claude mcp add gecho-bridge -- npx -y @gecho-ai/gecho-bridge@latest
+```
+- 默认情况下，该配置保存在**项目级别**（`.claude/settings.json`）。
+- 可以添加 `--scope user` 使其对所有项目生效，或使用 `--scope local` 仅在当前目录生效。
+- 添加完成后，使用 `claude mcp list` 验证服务是否注册成功。
+- 如果 MCP 工具没有立即出现，请重启 Claude Code。
+
 ---
 
 ## 🏁 快速开始与常见流程
@@ -100,7 +130,18 @@ hermes restart
 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 并登录账号。
-4. Gecho 扩展已登录并处于在线状态，TikTok 页面未卡住或未停在验证码页面。
+4. Gecho 扩展已登录 Gecho 账号并处于在线状态。
+5. TikTok 页面未卡住或未停在验证码页面。
+
+### 🧩 Skills 说明
+
+Gecho 同时提供 TikTok 聚合 Skill 和单工具分发 Skill：
+
+- **`tiktok-search`**：默认聚合 Skill，适合完整 TikTok 搜索 + 洞察工作流，覆盖 `tiktok_search`、`tiktok_insight` 和 `check_insight_status`。
+- **`tiktok-video-search`**：单工具分发 Skill，适合按关键词搜索 TikTok 视频并采集元数据。
+- **`tiktok-insight`**：单工具分发 Skill，适合 TikTok 产品、趋势、竞品和内容洞察任务，并支持查询洞察任务状态。
+
+如果只需要某个单点能力，可以使用单工具 Skill；如果需要完整研究流程，建议使用 `tiktok-search`。
 
 ### 🔍 基础搜索 (`tiktok_search`)
 适用于快速检索和收集视频数据。
@@ -167,6 +208,24 @@ openclaw plugins info @gecho-ai/gecho-bridge-bundle
 
 ---
 
+## ❓ 常见问题（FAQ）
+
+### 为什么一定要装 Chrome 插件？不能直接在网页用吗？
+
+Gecho 需要从真实浏览器会话中获取实时平台数据，例如 TikTok 视频以及 Gecho 工作流中的其他平台数据。Chrome 扩展负责把 AI 工作流连接到你已登录的 Chrome 会话；仅靠 Skill 页面本身无法完成这些数据获取。
+
+### 为什么还要登录 TikTok？不登录不能用吗？
+
+TikTok 对未登录用户的内容访问权限有限。登录后，扩展才能访问你浏览器会话中可见的完整数据，例如视频文案/脚本、评论、互动数据以及其他可用信号。
+
+Gecho 不会索取或收集你的 TikTok 密码、隐私信息，也不会代表你发布任何内容。
+
+### 还有问题？
+
+欢迎加入 [Discord](https://discord.gg/RFDVZMR6Tn)、扫描 [企业微信群二维码](https://github.com/gecho-ai/gecho-bridge/blob/main/qywx.jpg)，或扫描 [1 对 1 客服二维码](https://github.com/gecho-ai/gecho-bridge/blob/main/wx.jpg) 获取支持。
+
+---
+
 ## 🧑‍💻 本地开发
 
 对于希望基于本工具进行二次开发的开发者：