dabi-chromeagent-relay 1.0.0

package/README.md

@@ -0,0 +1,171 @@
+# dabi-relay
+
+把本地 `http://localhost:51234` ChromeAgent/Relay Tool API 暴露给 OpenClaw。
+
+## 交付方式
+
+推荐直接交付 `openclaw/plugins/dist/` 整个目录。
+
+从这个版本开始，`dist/` 已经包含：
+
+- OpenClaw 插件入口
+- bundled relay 入口
+- relay 所需 `public/configs`
+- bundled relay 的 `playwright-core` 运行时依赖
+
+这意味着客户安装时不再需要手动创建 `playwright-core` symlink。
+
+如果某些打包/分发流程把 `bundled-relay/node_modules` 过滤掉了，客户只需要在插件目录执行一次：
+
+```bash
+node install.mjs
+```
+
+该 helper 会按 `bundled-relay/package.json` 自动补齐缺失的运行时依赖。
+
+## 新能力：插件自带 relay
+
+这个插件现在支持把 relay 一起打包进 OpenClaw 插件目录。
+
+默认行为：
+
+1. 先检查 relay 健康状态
+2. 如果 relay 没启动，并且 `autoStart=true`
+3. 优先启动插件包内自带的 bundled relay
+4. 等待 `/health` 可用后继续执行 tool
+
+这意味着客户安装 OpenClaw 插件后，通常**不需要再单独部署一份外部 relay 项目**。
+
+---
+
+## 提供的 OpenClaw tools
+
+通用 relay tools：
+
+- `chromeagent_relay_health`
+- `chromeagent_relay_list_tools`
+- `chromeagent_relay_execute_tool`
+- `chromeagent_relay_wait_task`
+
+专用小红书 tools：
+
+- `xhs_list_runtimes`
+- `xhs_list_tabs`
+- `xhs_publish_note`
+- `xhs_save_note_draft`
+
+---
+
+## OpenClaw 配置示例
+
+### 推荐：直接使用插件内置 relay
+
+```json5
+{
+  plugins: {
+    allow: ["chromeagent-relay"],
+    load: {
+      paths: ["/path/to/chromeagent-relay-plugin/dist"]
+    },
+    entries: {
+      "chromeagent-relay": {
+        enabled: true,
+        config: {
+          baseUrl: "http://localhost:51234",
+          relayPort: 51234,
+          autoStart: true,
+          preferBundledRelay: true,
+          startupTimeoutMs: 15000,
+          startupPollIntervalMs: 500,
+          defaultPollIntervalMs: 1000,
+          defaultTimeoutMs: 30000
+        }
+      }
+    }
+  }
+}
+```
+
+### 可选：改成外部 relay 启动命令
+
+如果你仍然想用外部独立 relay，可以覆盖成：
+
+```json5
+{
+  plugins: {
+    entries: {
+      "chromeagent-relay": {
+        enabled: true,
+        config: {
+          baseUrl: "http://localhost:51234",
+          autoStart: true,
+          preferBundledRelay: false,
+          relayCommand: "npm",
+          relayArgs: ["run", "relay"],
+          relayCwd: "/opt/chromeagent"
+        }
+      }
+    }
+  }
+}
+```
+
+---
+
+## 打包产物结构
+
+构建后插件 dist 目录会包含：
+
+- `dist/index.js`：OpenClaw 插件入口
+- `dist/openclaw.plugin.json`
+- `dist/README.md`
+- `dist/install.mjs`：缺失运行时依赖时的一键修复 helper
+- `dist/bundled-relay/index.js`：内置 relay 入口
+- `dist/bundled-relay/package.json`：bundled relay 运行时依赖清单
+- `dist/bundled-relay/node_modules/playwright-core/**`
+- `dist/bundled-relay/public/**`：relay 运行所需 configs
+
+所以对客户来说，**安装 OpenClaw 插件本身就会带上 relay**。
+
+---
+
+## 注意事项
+
+### 1. 仍然需要宿主机提供的外部依赖
+
+内置 relay 已打包进插件，`playwright-core` 也随插件一起交付；宿主机仍需要：
+
+- Node.js
+- Chrome / Chromium 浏览器
+- ChromeAgent 浏览器扩展并连上 relay runtime
+
+也就是说，客户侧不再需要额外手工安装 `playwright-core`，除非分发过程把插件自带的 `node_modules` 删除了；那时运行 `node install.mjs` 即可恢复。
+
+### 2. OpenClaw 和 relay 需要在同一台机器
+
+插件自动拉起的是**本机** relay 进程，不是远程机器上的 relay。
+
+### 3. Chrome runtime 还是要由浏览器扩展那边连接上来
+
+内置 relay 解决的是“relay 进程启动和分发”问题，不替代浏览器插件本身。
+
+---
+
+## 建议交付方式
+
+如果你是发客户，建议交付：
+
+1. OpenClaw 插件 `dist` 目录
+2. Chrome 扩展 build/zip 产物
+3. 一份最小安装说明
+
+这样客户安装 OpenClaw 插件后，调用工具时就会自动拉起 bundled relay。
+
+## 客户安装步骤
+
+1. 把 `dist/` 整个目录复制到客户机器，例如 `/opt/openclaw-plugins/chromeagent-relay/`
+2. 在 OpenClaw 配置里把插件加载路径指向这个目录
+3. 保持 `autoStart=true` 且 `preferBundledRelay=true`
+4. 安装并启用 ChromeAgent 浏览器扩展
+5. 如果插件目录里的 `bundled-relay/node_modules` 被安全软件、打包脚本或制品系统裁掉，进入插件目录执行 `node install.mjs`
+6. 正常调用 OpenClaw tools，插件会自动拉起 bundled relay