@hpplay-lebo/cluster-hub 2.0.0

package/README.md

@@ -0,0 +1,243 @@
+# @hpplay-lebo/cluster-hub
+
+OpenClaw Hub 集群插件 — 让多台 OpenClaw 节点跨网络协作，实现聊天、任务分发和集群管理。
+
+## 功能
+
+- 🌐 **跨网络组网** — 通过云端 Hub 中转，不同网络下的 OpenClaw 节点自动组成集群
+- 💬 **节点间聊天** — 从飞书/控制台与集群中任意节点对话（不限父子关系）
+- ⚡ **任务分发** — 向子节点下发任务，支持批量并行 + 等待汇总
+- 🌳 **树形集群** — 支持多层树形结构（最大深度 5 层），邀请码加入
+- 📊 **状态监控** — 实时心跳、在线状态、任务统计
+- 🔌 **自动重连** — 断线后自动重连，离线消息队列
+- 🛠️ **CLI + AI 工具 + RPC** — 三种使用方式
+
+## 安装
+
+### 方式一：npm 安装（推荐）
+
+```bash
+npm install @hpplay-lebo/cluster-hub
+
+# 链接到 OpenClaw 插件目录
+ln -s $(npm root)/@hpplay-lebo/cluster-hub ~/.openclaw/extensions/cluster-hub
+
+# 重启 Gateway
+openclaw gateway restart
+```
+
+### 方式二：手动安装
+
+```bash
+# 下载/复制插件到 extensions 目录
+cp -r cluster-hub ~/.openclaw/extensions/cluster-hub
+
+# 重启 Gateway
+openclaw gateway restart
+```
+
+### 验证安装
+
+```bash
+openclaw plugins list
+# 应看到 cluster-hub 状态为 loaded
+```
+
+## 配置
+
+安装后编辑 `~/.openclaw/openclaw.json`，在 `plugins.entries` 中添加 `cluster-hub` 配置：
+
+```jsonc
+{
+  "plugins": {
+    "entries": {
+      "cluster-hub": {
+        "enabled": true,
+        "config": {
+          // Hub 服务地址
+          "hubUrl": "https://hub.openclaw.ai",
+          // 节点显示名称
+          "nodeName": "My Mac",
+          // 节点别名（集群内唯一，用于 #别名 提及）
+          "nodeAlias": "home",
+          // 能力标签
+          "capabilities": ["coding", "shell"],
+          // 启动时自动连接 Hub
+          "autoConnect": true
+
+          // === 以下字段注册后自动写入，无需手动填 ===
+          // "nodeId": "",
+          // "token": "",
+          // "clusterId": "",
+          // "parentId": null
+        }
+      }
+    }
+  }
+}
+```
+
+> **注意**: 以上只展示了 `cluster-hub` 相关配置，实际 `openclaw.json` 中还有其他配置项（`auth`、`agents`、`channels` 等），请勿覆盖已有内容。
+
+### 加入已有集群（子节点）
+
+获取父节点的 ID 和邀请码，在配置中添加 `parentId`：
+
+```jsonc
+{
+  "config": {
+    "hubUrl": "https://hub.openclaw.ai",
+    "nodeName": "Office Mac",
+    "nodeAlias": "office",
+    "parentId": "父节点的UUID",
+    "capabilities": ["coding", "shell"]
+  }
+}
+```
+
+## 快速开始
+
+### 1. 创建集群（根节点）
+
+配置好 `hubUrl`、`nodeName`、`nodeAlias` 后注册：
+
+```bash
+openclaw hub register
+```
+
+注册成功后 `nodeId`、`token`、`clusterId` 自动写入配置。
+
+### 2. 加入集群（子节点）
+
+```bash
+openclaw hub register --parent <父节点ID> --invite <邀请码>
+```
+
+### 3. 开始使用
+
+```bash
+# 查看集群状态
+openclaw hub status
+
+# 查看所有节点
+openclaw hub nodes
+
+# 给节点发指令
+openclaw hub send <节点别名> "检查磁盘空间"
+
+# 查看任务
+openclaw hub tasks
+```
+
+## AI 工具
+
+安装后 AI 自动获得以下工具：
+
+| 工具 | 说明 |
+|------|------|
+| `hub_status` | 查看 Hub 连接状态和节点列表 |
+| `hub_nodes` | 列出集群所有节点详情 |
+| `hub_send` | 给节点发送任务 |
+| `hub_batch_send` | 批量向多个节点下发任务（并行） |
+| `hub_wait_task` | 等待单个任务完成并返回结果 |
+| `hub_wait_all` | 等待多个任务全部完成并汇总 |
+| `hub_tasks` | 查看任务队列和历史 |
+
+**AI 对话示例：**
+
+```
+"查看集群状态"
+"让 #office 执行 ls -la"
+"给所有节点发送 '报告系统负载'"
+```
+
+## Gateway RPC
+
+插件向 Gateway 注册了 18+ 个 RPC 方法（`hub.*`），供控制台和外部工具调用：
+
+| RPC | 说明 |
+|-----|------|
+| `hub.status` | 连接状态 + changeSeq |
+| `hub.connect` / `hub.disconnect` | 连接/断开 Hub |
+| `hub.register` / `hub.unregister` | 注册/注销节点 |
+| `hub.nodes` / `hub.node` | 节点列表/详情 |
+| `hub.children` / `hub.tree` / `hub.clusters` | 子节点/树形/集群 |
+| `hub.node.update` | 更新节点名称/别名 |
+| `hub.invite.set` / `hub.invite.get` | 设置/获取邀请码 |
+| `hub.task.send` / `hub.task.list` / `hub.task.get` / `hub.task.cancel` / `hub.task.clear` | 任务管理 |
+| `hub.chat.send` / `hub.chat.history` / `hub.chat.list` / `hub.chat.clear` | 聊天管理 |
+| `hub.node.events` | 节点上下线事件 |
+
+## 配置项
+
+| 配置项 | 类型 | 默认值 | 说明 |
+|--------|------|--------|------|
+| `hubUrl` | string | — | Hub 服务地址 |
+| `nodeName` | string | — | 节点显示名称 |
+| `nodeAlias` | string | — | 节点别名（`#` 提及用，集群内唯一） |
+| `capabilities` | string[] | `["coding","shell"]` | 能力标签 |
+| `parentId` | string\|null | null | 父节点 ID（null = 创建新集群） |
+| `autoConnect` | boolean | true | 启动时自动连接 |
+| `selfTaskMode` | `"local"\|"hub"` | `"local"` | 自发任务模式 |
+| `heartbeatIntervalMs` | number | 30000 | 心跳间隔 (ms) |
+| `reconnectIntervalMs` | number | 5000 | 断线重连间隔 (ms) |
+| `taskTimeoutMs` | number | 300000 | 任务超时 (ms) |
+| `nodeId` | string | — | 注册后自动写入 |
+| `token` | string | — | JWT Token，注册后自动写入 |
+| `clusterId` | string | — | 集群 ID，注册后自动写入 |
+
+## 消息类型
+
+Hub 节点间通过 WebSocket 通信，支持以下消息类型：
+
+| 类型 | 方向 | 说明 |
+|------|------|------|
+| `task` | 父→子 | 下发任务 |
+| `result` | 子→父 | 任务结果 |
+| `task_ack` / `task_status` | 子→父 | 任务状态上报 |
+| `task_cancel` | 父→子 | 取消任务 |
+| `chat` | 任意 | 节点间聊天（不限父子） |
+| `direct` | 任意 | 点对点消息（同集群） |
+| `broadcast` | 父→全部 | 广播 |
+| `heartbeat` | 双向 | 心跳保活 |
+
+## 文件结构
+
+```
+cluster-hub/
+├── package.json
+├── openclaw.plugin.json    # 插件清单 + 配置 Schema
+├── README.md
+├── docs/
+│   └── CLI.md              # CLI 命令完整参考
+└── src/
+    ├── index.ts            # 插件入口（RPC + AI 工具 + CLI + 后台服务）
+    ├── hub-client.ts       # Hub 通讯客户端（WebSocket + REST）
+    ├── store.ts            # 持久化存储（任务/聊天/节点事件）
+    └── types.ts            # 类型定义
+```
+
+## 架构
+
+```
+┌─────────────────┐     ┌─────────────────┐
+│  OpenClaw Node  │     │  OpenClaw Node  │
+│  (cluster-hub)  │     │  (cluster-hub)  │
+└────────┬────────┘     └────────┬────────┘
+         │ WebSocket              │ WebSocket
+         └──────────┐  ┌─────────┘
+                 ┌───┴──┴───┐
+                 │  Hub 服务  │
+                 │ (云端中转)  │
+                 └───┬──┬───┘
+         ┌──────────┘  └─────────┐
+         │ WebSocket              │ WebSocket
+┌────────┴────────┐     ┌────────┴────────┐
+│  OpenClaw Node  │     │   飞书机器人     │
+│  (cluster-hub)  │     │  (Hub 内置)     │
+└─────────────────┘     └─────────────────┘
+```
+
+## License
+
+MIT

package/docs/CLI.md

@@ -0,0 +1,279 @@
+# OpenClaw Hub CLI 命令参考
+
+所有命令以 `openclaw hub` 开头。
+
+## 命令列表
+
+| 命令 | 说明 |
+|------|------|
+| `openclaw hub status` | 查看 Hub 连接和集群状态 |
+| `openclaw hub nodes` | 列出所有节点（表格形式） |
+| `openclaw hub tree` | 显示节点树形结构 |
+| `openclaw hub register` | 注册本节点到 Hub |
+| `openclaw hub unregister` | 从 Hub 注销节点 |
+| `openclaw hub send` | 给节点发送指令/任务 |
+| `openclaw hub tasks` | 查看任务列表 |
+| `openclaw hub connect` | 手动连接 Hub |
+| `openclaw hub disconnect` | 断开 Hub 连接 |
+| `openclaw hub help` | 列出所有可用命令 |
+
+---
+
+## 详细说明
+
+### `openclaw hub status`
+
+查看 Hub 连接状态、注册状态、自发任务模式、任务统计和在线节点。
+
+```bash
+openclaw hub status
+```
+
+输出示例：
+```
+📡 Hub 集群状态
+
+  连接:     ✅ 已连接
+  注册:     ✅ 已注册
+  节点:     16578344-4e63-442e-930a-2090a1f6cc13
+  自发任务: 🏠 本地模式
+  任务:     0 进行中, 3 完成, 0 失败
+
+  节点列表 (2):
+    🟢 招财Mac (@home) [coding,shell] load=0%
+    ⚫ 办公室Mac (@office) [coding,shell] load=0%
+```
+
+---
+
+### `openclaw hub nodes`
+
+以表格形式列出集群中所有节点的详细信息。
+
+```bash
+openclaw hub nodes
+```
+
+显示字段：id、name、alias、online、parent、load、capabilities
+
+---
+
+### `openclaw hub tree`
+
+以树形结构显示本集群的节点层级关系。
+
+```bash
+openclaw hub tree
+```
+
+输出示例：
+```
+└── 🟢 招财Mac (@home)
+    ├── 🟢 办公室Mac (@office)
+    └── ⚫ 树莓派 (@rpi)
+```
+
+---
+
+### `openclaw hub register`
+
+注册本节点到 Hub 集群。注册成功后 `nodeId`、`token`、`clusterId` 自动写入配置。
+
+```bash
+# 注册为根节点（创建新集群）
+openclaw hub register --name "我的Mac" --alias "home"
+
+# 注册为子节点（加入已有集群）
+openclaw hub register --name "办公室Mac" --alias "office" --parent <父节点ID>
+```
+
+**参数：**
+
+| 参数 | 说明 |
+|------|------|
+| `--name <name>` | 节点显示名称 |
+| `--alias <alias>` | 节点别名（同集群内唯一，用于 @提及） |
+| `--parent <parentId>` | 父节点 ID（不填则创建新集群为根节点） |
+
+> ⚠️ 别名（alias）在同一集群中必须唯一，否则注册会失败（`ALIAS_CONFLICT`）。
+
+---
+
+### `openclaw hub unregister`
+
+从 Hub 注销节点，清除注册信息。
+
+```bash
+# 注销自己
+openclaw hub unregister
+
+# 注销指定节点
+openclaw hub unregister --node <nodeId>
+```
+
+**参数：**
+
+| 参数 | 说明 |
+|------|------|
+| `--node <nodeId>` | 指定要注销的节点 ID（默认注销自己） |
+
+---
+
+### `openclaw hub send <nodeId> <instruction>`
+
+给指定节点发送任务指令。
+
+```bash
+# 发送任务给子节点
+openclaw hub send <nodeId> "检查磁盘空间"
+
+# 自发本地任务（selfTaskMode=local 时同步等结果）
+openclaw hub send <自己的nodeId> "执行 ls -la"
+
+# 指定超时
+openclaw hub send <nodeId> "编译项目" --timeout 600000
+```
+
+**参数：**
+
+| 参数 | 说明 |
+|------|------|
+| `<nodeId>` | 目标节点 ID（必填） |
+| `<instruction>` | 任务指令内容（必填） |
+| `--timeout <ms>` | 超时毫秒数（默认 300000 = 5分钟） |
+
+---
+
+### `openclaw hub tasks`
+
+查看任务列表（表格形式），显示任务 ID、目标节点、状态、指令摘要和耗时。
+
+```bash
+# 查看最近任务
+openclaw hub tasks
+
+# 指定数量
+openclaw hub tasks --limit 50
+```
+
+**参数：**
+
+| 参数 | 说明 |
+|------|------|
+| `--limit <n>` | 显示数量（默认 20） |
+
+---
+
+### `openclaw hub connect`
+
+手动连接到 Hub WebSocket。通常不需要手动调用（`autoConnect: true` 时自动连接）。
+
+```bash
+openclaw hub connect
+```
+
+---
+
+### `openclaw hub disconnect`
+
+手动断开 Hub WebSocket 连接。
+
+```bash
+openclaw hub disconnect
+```
+
+---
+
+### `openclaw hub help`
+
+列出所有可用的 hub 子命令。
+
+```bash
+openclaw hub help
+# 或
+openclaw hub --help
+```
+
+---
+
+## AI 工具
+
+除 CLI 外，插件还注册了以下 AI 工具，可在对话中自然调用：
+
+| 工具 | 说明 | 使用方式 |
+|------|------|----------|
+| `hub_status` | 查看集群状态 | "查看 Hub 状态" |
+| `hub_nodes` | 列出所有节点 | "列出 Hub 节点" |
+| `hub_send` | 发送任务（单个） | "让 @home 执行 xxx" |
+| `hub_batch_send` | 批量下发任务（并行） | "同时让三个节点分别执行..." |
+| `hub_wait_task` | 等待单个任务完成 | "等任务 xxx 完成后告诉我结果" |
+| `hub_wait_all` | 等待多个任务全部完成 | "等所有任务完成后汇总" |
+| `hub_tasks` | 查看任务进度 | "看看 Hub 任务进度" |
+
+---
+
+## Gateway RPC
+
+插件注册的所有 Gateway RPC 方法（供控制台/程序调用）：
+
+### 状态与连接
+| RPC | 说明 |
+|-----|------|
+| `hub.status` | 获取整体状态（连接、节点列表、任务摘要） |
+| `hub.connect` | 手动连接 Hub |
+| `hub.disconnect` | 断开连接 |
+| `hub.ping` | 检查连通性 |
+| `hub.config.get` | 获取当前配置 |
+| `hub.config.set` | 更新配置 |
+
+### 节点管理
+| RPC | 参数 | 说明 |
+|-----|------|------|
+| `hub.nodes` | — | 获取所有节点列表 |
+| `hub.node.get` | `nodeId` | 获取单个节点信息 |
+| `hub.node.update` | `nodeId, name?, alias?` | 更新节点名称/别名 |
+| `hub.tree` | `nodeId?` | 获取树形结构 |
+| `hub.children` | `nodeId?` | 获取直接子节点 |
+| `hub.clusters` | — | 获取集群列表 |
+| `hub.register` | `name, alias, parentId?, capabilities?` | 注册节点 |
+| `hub.register.child` | `name, alias, parentId?, capabilities?` | 注册子节点 |
+| `hub.unregister` | `nodeId?` | 注销节点 |
+| `hub.reparent` | `nodeId, newParentId` | 变更父节点 |
+
+### 邀请码
+| RPC | 说明 |
+|-----|------|
+| `hub.invite-code.get` | 获取当前邀请码 |
+| `hub.invite-code.set` | 设置/刷新邀请码（可选 `code` 参数） |
+
+### 任务系统
+| RPC | 参数 | 说明 |
+|-----|------|------|
+| `hub.task.send` | `nodeId, instruction` | 发送任务（异步） |
+| `hub.task.batch` | `tasks: [{nodeId, instruction}]` | 批量下发任务（并行） |
+| `hub.task.list` | `nodeId?, status?, limit?` | 获取任务列表 |
+| `hub.task.get` | `taskId` | 获取单个任务 |
+| `hub.task.cancel` | `taskId` | 取消任务 |
+| `hub.task.clear` | `before?` | 清理已完成任务 |
+
+### 远程聊天
+| RPC | 参数 | 说明 |
+|-----|------|------|
+| `hub.chat.send` | `nodeId, content, whole?, autoRefreshMs?` | 发送聊天消息 |
+| `hub.chat.history` | `nodeId, limit?` | 获取聊天记录 |
+| `hub.chat.list` | — | 获取活跃聊天节点列表 |
+| `hub.chat.clear` | `nodeId` | 清除聊天记录 |
+
+### 节点事件
+| RPC | 说明 |
+|-----|------|
+| `hub.node.events` | 获取节点上下线事件记录 |
+
+### 兼容旧接口
+| RPC | 说明 |
+|-----|------|
+| `hub.send` | → `hub.task.send` |
+| `hub.send.sync` | 自发本地同步执行 |
+| `hub.tasks` | → `hub.task.list` + 队列状态 |
+| `hub.messages` | 获取消息历史 |
+| `hub.messages.clear` | 清除消息 |

package/openclaw.plugin.json

@@ -0,0 +1,151 @@
+{
+  "id": "cluster-hub",
+  "name": "Cluster Hub",
+  "version": "2.0.0",
+  "description": "OpenClaw Hub 云端集群插件 — 通过 Hub 中转实现跨网络节点注册、任务分发、实时通讯",
+  "author": "招财",
+  "configSchema": {
+    "type": "object",
+    "additionalProperties": false,
+    "properties": {
+      "hubUrl": {
+        "type": "string",
+        "default": "https://openclaw-hub.hpplay.com.cn",
+        "description": "Hub 服务地址"
+      },
+      "adminKey": {
+        "type": "string",
+        "description": "Hub Admin Key（用于注册根节点）"
+      },
+      "nodeId": {
+        "type": "string",
+        "description": "本节点 ID（注册后自动写入）"
+      },
+      "nodeName": {
+        "type": "string",
+        "description": "本节点显示名称"
+      },
+      "nodeAlias": {
+        "type": "string",
+        "description": "本节点别名（用于 @ 提及）"
+      },
+      "token": {
+        "type": "string",
+        "description": "Node Token（JWT，注册后自动写入）"
+      },
+      "clusterId": {
+        "type": "string",
+        "description": "所属集群 ID（注册后自动写入）"
+      },
+      "parentId": {
+        "type": [
+          "string",
+          "null"
+        ],
+        "description": "父节点 ID（null = 根节点）"
+      },
+      "capabilities": {
+        "type": "array",
+        "items": {
+          "type": "string"
+        },
+        "default": [
+          "coding",
+          "shell"
+        ],
+        "description": "本节点能力标签"
+      },
+      "heartbeatIntervalMs": {
+        "type": "number",
+        "default": 30000,
+        "description": "心跳间隔 (ms)"
+      },
+      "reconnectIntervalMs": {
+        "type": "number",
+        "default": 5000,
+        "description": "断线重连间隔 (ms)"
+      },
+      "taskTimeoutMs": {
+        "type": "number",
+        "default": 300000,
+        "description": "任务默认超时 (ms)"
+      },
+      "autoConnect": {
+        "type": "boolean",
+        "default": true,
+        "description": "启动时自动连接 Hub WebSocket"
+      },
+      "autoInjectSession": {
+        "type": "boolean",
+        "default": true,
+        "description": "收到任务时自动注入主会话执行"
+      },
+      "selfTaskMode": {
+        "type": "string",
+        "enum": [
+          "local",
+          "hub"
+        ],
+        "default": "local",
+        "description": "自发任务执行模式：local=本地直接执行，hub=通过Hub中转"
+      }
+    }
+  },
+  "uiHints": {
+    "hubUrl": {
+      "label": "Hub 地址",
+      "placeholder": "https://openclaw-hub.hpplay.com.cn"
+    },
+    "adminKey": {
+      "label": "Admin Key",
+      "sensitive": true
+    },
+    "nodeId": {
+      "label": "节点 ID",
+      "help": "注册后自动填写"
+    },
+    "nodeName": {
+      "label": "节点名称",
+      "placeholder": "我的 Mac"
+    },
+    "nodeAlias": {
+      "label": "节点别名",
+      "placeholder": "home"
+    },
+    "token": {
+      "label": "Node Token",
+      "sensitive": true,
+      "help": "注册后自动填写"
+    },
+    "clusterId": {
+      "label": "集群 ID",
+      "help": "注册后自动填写"
+    },
+    "parentId": {
+      "label": "父节点 ID",
+      "help": "null 表示根节点"
+    },
+    "capabilities": {
+      "label": "能力标签",
+      "help": "coding, shell, browser, gpu 等"
+    },
+    "heartbeatIntervalMs": {
+      "label": "心跳间隔",
+      "suffix": "ms"
+    },
+    "reconnectIntervalMs": {
+      "label": "重连间隔",
+      "suffix": "ms"
+    },
+    "taskTimeoutMs": {
+      "label": "任务超时",
+      "suffix": "ms"
+    },
+    "autoConnect": {
+      "label": "自动连接"
+    },
+    "autoInjectSession": {
+      "label": "收到任务自动执行"
+    }
+  }
+}

package/package.json

@@ -0,0 +1,40 @@
+{
+  "name": "@hpplay-lebo/cluster-hub",
+  "version": "2.0.0",
+  "description": "OpenClaw Hub cluster plugin — cross-network node collaboration, chat, and task orchestration",
+  "author": "HPPlay",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/shenyingjun5/cluster-hub"
+  },
+  "homepage": "https://github.com/shenyingjun5/cluster-hub#readme",
+  "openclaw": {
+    "extensions": [
+      "./src/index.ts"
+    ]
+  },
+  "files": [
+    "src/",
+    "openclaw.plugin.json",
+    "README.md",
+    "docs/"
+  ],
+  "keywords": [
+    "openclaw",
+    "openclaw-plugin",
+    "cluster",
+    "hub",
+    "multi-node",
+    "task-orchestration",
+    "ai-agent"
+  ],
+  "scripts": {
+    "build": "tsc --noEmit"
+  },
+  "devDependencies": {
+    "@types/node": "^20.19.33",
+    "@types/ws": "^8.18.1",
+    "typescript": "^5.9.3"
+  }
+}