@hpplay-lebo/cluster-hub 2.0.0 → 3.0.0

package/README.md

@@ -10,27 +10,15 @@ OpenClaw Hub 集群插件 — 让多台 OpenClaw 节点跨网络协作，实现
 - 🌳 **树形集群** — 支持多层树形结构（最大深度 5 层），邀请码加入
 - 📊 **状态监控** — 实时心跳、在线状态、任务统计
 - 🔌 **自动重连** — 断线后自动重连，离线消息队列
+- 📄 **飞书工具下发** — Hub 自动下发飞书凭据，子节点无需配置即可操作飞书文档/知识库/云空间
 - 🛠️ **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
+# 克隆到 OpenClaw 插件目录
+cd ~/.openclaw/extensions
+git clone https://github.com/shenyingjun5/cluster-hub.git cluster-hub
 
 # 重启 Gateway
 openclaw gateway restart
@@ -143,6 +131,20 @@ openclaw hub tasks
 | `hub_wait_all` | 等待多个任务全部完成并汇总 |
 | `hub_tasks` | 查看任务队列和历史 |
 
+### 飞书工具（Hub 自动下发）
+
+如果 Hub 配置了飞书应用凭据，节点连接后自动获得以下工具：
+
+| 工具 | 说明 |
+|------|------|
+| `feishu_doc` | 文档操作（读/写/追加/创建/块编辑） |
+| `feishu_wiki` | 知识库操作（空间/节点/创建） |
+| `feishu_drive` | 云空间管理（文件列表/创建文件夹/移动/删除） |
+| `feishu_perm` | 权限管理（查看/添加/移除协作者） |
+| `feishu_app_scopes` | 查看应用权限 |
+
+> **冲突处理**: 如果节点已安装并启用了 OpenClaw 飞书插件，Hub 下发的工具会自动跳过，不会冲突。
+
 **AI 对话示例：**
 
 ```
@@ -213,6 +215,7 @@ cluster-hub/
 └── src/
     ├── index.ts            # 插件入口（RPC + AI 工具 + CLI + 后台服务）
     ├── hub-client.ts       # Hub 通讯客户端（WebSocket + REST）
+    ├── feishu-tools.ts     # 飞书工具集（Hub 下发凭据，自动注册）
     ├── store.ts            # 持久化存储（任务/聊天/节点事件）
     └── types.ts            # 类型定义
 ```
@@ -238,6 +241,10 @@ cluster-hub/
 └─────────────────┘     └─────────────────┘
 ```
 
+## 文档
+
+- **[CLI 命令参考](docs/CLI.md)** — 所有 CLI 命令、AI 工具、Gateway RPC 详细说明
+
 ## License
 
 MIT

package/docs/GUIDE.md

@@ -0,0 +1,286 @@
+# OpenClaw Hub 集群 — 新手安装指引
+
+## 目录
+
+- [前置条件](#前置条件)
+- [第一步：安装插件](#第一步安装插件)
+- [第二步：创建集群（根节点）](#第二步创建集群根节点)
+- [第三步：添加子节点](#第三步添加子节点)
+- [第四步：飞书机器人](#第四步飞书机器人)
+- [AI 对话指令](#ai-对话指令)
+- [CLI 命令速查](#cli-命令速查)
+- [常见问题](#常见问题)
+
+---
+
+## 前置条件
+
+- 已安装 [OpenClaw](https://github.com/openclaw/openclaw)
+- OpenClaw Gateway 正常运行（`openclaw gateway status`）
+- 有终端/命令行访问权限
+
+---
+
+## 第一步：安装插件
+
+在终端执行：
+
+```bash
+# 克隆插件到 OpenClaw 插件目录
+cd ~/.openclaw/extensions
+git clone https://github.com/shenyingjun5/cluster-hub.git cluster-hub
+
+# 重启 Gateway 加载插件
+kill -9 $(pgrep -f "openclaw.*gateway")
+openclaw gateway start
+```
+
+验证安装：
+
+```bash
+openclaw plugins list
+# 应看到 cluster-hub 状态为 loaded
+```
+
+---
+
+## 第二步：创建集群（根节点）
+
+> 每个集群需要一个根节点作为管理者。一般由团队负责人创建。
+
+### 2.1 注册根节点
+
+```bash
+openclaw hub register --name "我的Mac" --alias home
+```
+
+- `--name`：节点显示名称（支持中文）
+- `--alias`：节点别名，集群内唯一，用于 `#别名` 提及（仅允许字母数字下划线横线，1-64位）
+
+注册成功后会输出：
+
+```
+✅ 注册成功! 节点 ID: xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx
+  WebSocket: 已连接
+```
+
+配置自动写入 `~/.openclaw/openclaw.json`，无需手动修改。
+
+### 2.2 生成邀请码
+
+根节点创建后，生成邀请码供其他人加入：
+
+```bash
+openclaw hub invite --new
+```
+
+输出示例：
+
+```
+✅ 新邀请码: K2XPWV
+
+子节点加入命令:
+  openclaw hub register --parent xxxxxxxx --invite K2XPWV --name "节点名" --alias "别名"
+```
+
+**把节点 ID、邀请码一起发给要加入集群的人。**
+
+飞书机器人绑定也需要这两个信息。
+
+### 2.3 查看当前邀请码
+
+```bash
+openclaw hub invite
+```
+
+---
+
+## 第三步：添加子节点
+
+> 每个想加入集群的人在自己的电脑上操作。
+
+### 3.1 安装插件（同第一步）
+
+```bash
+cd ~/.openclaw/extensions
+git clone https://github.com/shenyingjun5/cluster-hub.git cluster-hub
+kill -9 $(pgrep -f "openclaw.*gateway")
+openclaw gateway start
+```
+
+### 3.2 用邀请码注册
+
+使用根节点管理者提供的命令：
+
+```bash
+openclaw hub register --parent <根节点ID> --invite <邀请码> --name "办公室Mac" --alias office
+```
+
+注册成功后自动连接。
+
+### 3.3 验证连接
+
+```bash
+openclaw hub status
+```
+
+应看到 `WebSocket: 已连接`，以及集群中的其他节点。
+
+---
+
+## 第四步：飞书机器人
+
+通过飞书机器人「进宝」，可以直接在飞书里和集群中的任意节点对话。
+
+### 4.1 添加机器人
+
+在飞书中搜索并添加「进宝」机器人为好友。
+
+### 4.2 绑定集群
+
+首次给进宝发消息会收到欢迎卡片。向集群管理员获取**集群 ID**（即根节点 ID）和**邀请码**，然后发送：
+
+```
+/bind <集群ID> <邀请码>
+```
+
+示例：
+
+```
+/bind 16578344-xxxx-xxxx-xxxx-xxxxxxxxxxxx K2XPWV
+```
+
+绑定成功后会显示集群信息和默认对话节点。
+
+### 4.3 聊天方式
+
+| 你发送 | 效果 |
+|--------|------|
+| `你好` | 发给默认节点 |
+| `#home 检查磁盘` | 发给指定节点 #home |
+| `#all 报告系统负载` | 广播给所有在线节点，每个节点单独回复 |
+| `#home`（仅别名无文字） | 显示该节点状态信息 |
+
+### 4.4 机器人命令
+
+| 命令 | 中文别名 | 说明 |
+|------|----------|------|
+| `/bind <ID> <邀请码>` | `/绑定` | 绑定集群 |
+| `/unbind` | `/解绑` | 解除绑定 |
+| `/list` 或 `/ls` | `/节点` | 查看集群所有节点及在线状态 |
+| `/who` | `/谁` | 查看当前默认对话节点 |
+| `/switch #别名` | `/切换 #别名` | 切换默认对话节点 |
+| `/status` | `/状态` | 查看集群状态总览 |
+| `/tasks` | `/任务` | 查看任务完成情况 |
+| `/info` | `/信息` | 查看绑定信息 |
+| `/help` | `/帮助` | 帮助 |
+
+---
+
+## AI 对话指令
+
+安装插件后，你的 OpenClaw AI 自动获得集群能力。直接用自然语言对话即可：
+
+### 状态查询
+
+| 你说 | AI 做什么 |
+|------|-----------|
+| "查看集群状态" | 显示 Hub 连接状态、在线节点数 |
+| "列出所有节点" | 显示每个节点的名称、别名、在线状态 |
+| "查看任务列表" | 显示任务队列和历史 |
+
+### 任务下发
+
+| 你说 | AI 做什么 |
+|------|-----------|
+| "让 macAir 检查磁盘空间" | 给 macAir 节点发任务 |
+| "给 office 执行 npm test" | 给 office 节点发任务 |
+| "给所有节点发送'报告系统负载'" | 批量下发到所有子节点 |
+
+### 任务编排（高级）
+
+| 你说 | AI 做什么 |
+|------|-----------|
+| "让 home 写代码，macAir 负责测试" | 分解任务 → 分发到不同节点 → 等待汇总 |
+| "同时让三个节点各自检查安全更新" | 并行下发 → 等待全部完成 → 汇总结果 |
+| "先让 gpu-server 训练模型，完成后让 home 分析结果" | 串行编排（Pipeline 模式） |
+
+### 邀请码管理
+
+| 你说 | AI 做什么 |
+|------|-----------|
+| "查看邀请码" | 显示当前邀请码 |
+| "生成新邀请码" | 创建新的邀请码 |
+
+---
+
+## CLI 命令速查
+
+```bash
+# 状态
+openclaw hub status          # 连接状态 + 节点列表
+openclaw hub nodes           # 所有节点详情
+openclaw hub tree            # 树形结构
+
+# 注册
+openclaw hub register                                              # 注册为根节点
+openclaw hub register --name "名称" --alias "别名"                   # 指定名称和别名
+openclaw hub register --parent <ID> --invite <邀请码>                # 注册为子节点
+openclaw hub unregister                                             # 注销本节点
+openclaw hub unregister --node <ID>                                 # 注销指定节点
+
+# 邀请码
+openclaw hub invite          # 查看当前邀请码
+openclaw hub invite --new    # 生成新邀请码
+
+# 任务
+openclaw hub send <别名> "指令"   # 发送任务
+openclaw hub tasks               # 查看任务
+
+# 连接
+openclaw hub connect         # 手动连接
+openclaw hub disconnect      # 断开连接
+```
+
+---
+
+## 常见问题
+
+### Q: 注册时提示 "别名已被使用"
+
+别名在集群内必须唯一（不区分大小写）。换一个别名，或联系管理员清除旧节点。
+
+### Q: 显示已注册但 WebSocket 未连接
+
+```bash
+# 完全重启 Gateway
+kill -9 $(pgrep -f "openclaw.*gateway")
+openclaw gateway start
+```
+
+### Q: 插件更新后命令没变化
+
+必须 `kill -9` 完全重启 Gateway，普通重启不会重新加载插件代码。
+
+```bash
+# 更新插件
+cd ~/.openclaw/extensions/cluster-hub && git pull
+
+# 完全重启
+kill -9 $(pgrep -f "openclaw.*gateway")
+openclaw gateway start
+```
+
+### Q: 子节点无法给父节点发任务
+
+这是设计如此。任务下发只能从父到子。节点间聊天（通过飞书机器人）不受此限制。
+
+### Q: 飞书机器人没有回复
+
+1. 确认已执行 `/bind <集群ID> <邀请码>` 绑定成功
+2. 确认目标节点在线（`/list` 查看）
+3. 目标节点的 Gateway 必须在运行
+
+### Q: 怎么切换飞书默认对话节点
+
+发送 `/switch #别名`，例如 `/switch #home`。之后直接发文字就会发给新的默认节点。用 `/who` 查看当前默认节点。

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hpplay-lebo/cluster-hub",
-  "version": "2.0.0",
+  "version": "3.0.0",
   "description": "OpenClaw Hub cluster plugin — cross-network node collaboration, chat, and task orchestration",
   "author": "HPPlay",
   "license": "MIT",

package/src/feishu-tools.ts

@@ -0,0 +1,586 @@
+/**
+ * 飞书工具集 — 轻量 REST 实现（不依赖 @larksuiteoapi/node-sdk）
+ * 由 Hub 下发 appId/appSecret，自动注册 AI 工具
+ */
+
+// ============================================================
+//  Feishu REST Client
+// ============================================================
+
+interface FeishuCredentials {
+  appId: string;
+  appSecret: string;
+  domain?: string;
+}
+
+let _credentials: FeishuCredentials | null = null;
+let _tenantToken: string | null = null;
+let _tokenExpiresAt = 0;
+
+function getBaseUrl(domain?: string): string {
+  if (domain === 'lark') return 'https://open.larksuite.com';
+  if (domain && domain !== 'feishu') return domain.replace(/\/+$/, '');
+  return 'https://open.feishu.cn';
+}
+
+export function setCredentials(creds: FeishuCredentials) {
+  _credentials = creds;
+  _tenantToken = null;
+  _tokenExpiresAt = 0;
+}
+
+export function hasCredentials(): boolean {
+  return !!_credentials?.appId && !!_credentials?.appSecret;
+}
+
+async function getTenantToken(): Promise<string> {
+  if (!_credentials) throw new Error('飞书凭据未配置');
+
+  if (_tenantToken && Date.now() < _tokenExpiresAt) {
+    return _tenantToken;
+  }
+
+  const base = getBaseUrl(_credentials.domain);
+  const res = await fetch(`${base}/open-apis/auth/v3/tenant_access_token/internal`, {
+    method: 'POST',
+    headers: { 'Content-Type': 'application/json' },
+    body: JSON.stringify({
+      app_id: _credentials.appId,
+      app_secret: _credentials.appSecret,
+    }),
+  });
+
+  const data = await res.json() as any;
+  if (data.code !== 0) {
+    throw new Error(`获取 tenant_access_token 失败: ${data.msg}`);
+  }
+
+  _tenantToken = data.tenant_access_token;
+  _tokenExpiresAt = Date.now() + (data.expire - 300) * 1000; // 提前5分钟刷新
+  return _tenantToken!;
+}
+
+async function feishuGet(path: string, params?: Record<string, string>): Promise<any> {
+  const token = await getTenantToken();
+  const base = getBaseUrl(_credentials?.domain);
+  const url = new URL(`${base}${path}`);
+  if (params) {
+    for (const [k, v] of Object.entries(params)) {
+      if (v !== undefined) url.searchParams.set(k, v);
+    }
+  }
+  const res = await fetch(url.toString(), {
+    headers: { Authorization: `Bearer ${token}` },
+  });
+  const data = await res.json() as any;
+  if (data.code !== 0) throw new Error(data.msg || `API error ${data.code}`);
+  return data.data;
+}
+
+async function feishuPost(path: string, body: any): Promise<any> {
+  const token = await getTenantToken();
+  const base = getBaseUrl(_credentials?.domain);
+  const res = await fetch(`${base}${path}`, {
+    method: 'POST',
+    headers: {
+      Authorization: `Bearer ${token}`,
+      'Content-Type': 'application/json',
+    },
+    body: JSON.stringify(body),
+  });
+  const data = await res.json() as any;
+  if (data.code !== 0) throw new Error(data.msg || `API error ${data.code}`);
+  return data.data;
+}
+
+async function feishuPatch(path: string, body: any): Promise<any> {
+  const token = await getTenantToken();
+  const base = getBaseUrl(_credentials?.domain);
+  const res = await fetch(`${base}${path}`, {
+    method: 'PATCH',
+    headers: {
+      Authorization: `Bearer ${token}`,
+      'Content-Type': 'application/json',
+    },
+    body: JSON.stringify(body),
+  });
+  const data = await res.json() as any;
+  if (data.code !== 0) throw new Error(data.msg || `API error ${data.code}`);
+  return data.data;
+}
+
+async function feishuDelete(path: string, params?: Record<string, string>): Promise<any> {
+  const token = await getTenantToken();
+  const base = getBaseUrl(_credentials?.domain);
+  const url = new URL(`${base}${path}`);
+  if (params) {
+    for (const [k, v] of Object.entries(params)) {
+      if (v !== undefined) url.searchParams.set(k, v);
+    }
+  }
+  const res = await fetch(url.toString(), {
+    method: 'DELETE',
+    headers: { Authorization: `Bearer ${token}` },
+  });
+  const data = await res.json() as any;
+  if (data.code !== 0) throw new Error(data.msg || `API error ${data.code}`);
+  return data.data;
+}
+
+async function feishuPut(path: string, body: any): Promise<any> {
+  const token = await getTenantToken();
+  const base = getBaseUrl(_credentials?.domain);
+  const res = await fetch(`${base}${path}`, {
+    method: 'PUT',
+    headers: {
+      Authorization: `Bearer ${token}`,
+      'Content-Type': 'application/json',
+    },
+    body: JSON.stringify(body),
+  });
+  const data = await res.json() as any;
+  if (data.code !== 0) throw new Error(data.msg || `API error ${data.code}`);
+  return data.data;
+}
+
+// ============================================================
+//  Document API
+// ============================================================
+
+async function docRead(docToken: string) {
+  const [content, info, blocks] = await Promise.all([
+    feishuGet(`/open-apis/docx/v1/documents/${docToken}/raw_content`),
+    feishuGet(`/open-apis/docx/v1/documents/${docToken}`),
+    feishuGet(`/open-apis/docx/v1/documents/${docToken}/blocks`),
+  ]);
+
+  const BLOCK_TYPE_NAMES: Record<number, string> = {
+    1: 'Page', 2: 'Text', 3: 'Heading1', 4: 'Heading2', 5: 'Heading3',
+    12: 'Bullet', 13: 'Ordered', 14: 'Code', 15: 'Quote', 17: 'Todo',
+    18: 'Bitable', 22: 'Divider', 27: 'Image', 31: 'Table',
+  };
+  const blockItems = blocks?.items || [];
+  const blockCounts: Record<string, number> = {};
+  for (const b of blockItems) {
+    const name = BLOCK_TYPE_NAMES[b.block_type] || `type_${b.block_type}`;
+    blockCounts[name] = (blockCounts[name] || 0) + 1;
+  }
+
+  return {
+    title: info?.document?.title,
+    content: content?.content,
+    revision_id: info?.document?.revision_id,
+    block_count: blockItems.length,
+    block_types: blockCounts,
+  };
+}
+
+async function docCreate(title: string, folderToken?: string) {
+  const data = await feishuPost('/open-apis/docx/v1/documents', {
+    title,
+    folder_token: folderToken,
+  });
+  const doc = data?.document;
+  return {
+    document_id: doc?.document_id,
+    title: doc?.title,
+    url: `https://feishu.cn/docx/${doc?.document_id}`,
+  };
+}
+
+async function docWrite(docToken: string, markdown: string) {
+  // 1. 转换 markdown 为 blocks
+  const converted = await feishuPost('/open-apis/docx/v1/documents/convert', {
+    content_type: 'markdown',
+    content: markdown,
+  });
+  const blocks = converted?.blocks || [];
+
+  // 2. 清除现有内容
+  const existing = await feishuGet(`/open-apis/docx/v1/documents/${docToken}/blocks`);
+  const childIds = (existing?.items || [])
+    .filter((b: any) => b.parent_id === docToken && b.block_type !== 1)
+    .map((b: any) => b.block_id);
+
+  if (childIds.length > 0) {
+    await feishuDelete(`/open-apis/docx/v1/documents/${docToken}/blocks/${docToken}/children`, {
+      start_index: '0',
+      end_index: String(childIds.length),
+    });
+  }
+
+  // 3. 插入新内容
+  if (blocks.length === 0) {
+    return { success: true, blocks_deleted: childIds.length, blocks_added: 0 };
+  }
+
+  const inserted = await feishuPost(
+    `/open-apis/docx/v1/documents/${docToken}/blocks/${docToken}/children`,
+    { children: blocks },
+  );
+
+  return {
+    success: true,
+    blocks_deleted: childIds.length,
+    blocks_added: inserted?.children?.length || 0,
+  };
+}
+
+async function docAppend(docToken: string, markdown: string) {
+  const converted = await feishuPost('/open-apis/docx/v1/documents/convert', {
+    content_type: 'markdown',
+    content: markdown,
+  });
+  const blocks = converted?.blocks || [];
+  if (blocks.length === 0) throw new Error('Content is empty');
+
+  const inserted = await feishuPost(
+    `/open-apis/docx/v1/documents/${docToken}/blocks/${docToken}/children`,
+    { children: blocks },
+  );
+
+  return {
+    success: true,
+    blocks_added: inserted?.children?.length || 0,
+  };
+}
+
+async function docListBlocks(docToken: string) {
+  return await feishuGet(`/open-apis/docx/v1/documents/${docToken}/blocks`);
+}
+
+async function docGetBlock(docToken: string, blockId: string) {
+  return await feishuGet(`/open-apis/docx/v1/documents/${docToken}/blocks/${blockId}`);
+}
+
+async function docUpdateBlock(docToken: string, blockId: string, content: string) {
+  await feishuPatch(`/open-apis/docx/v1/documents/${docToken}/blocks/${blockId}`, {
+    update_text_elements: {
+      elements: [{ text_run: { content } }],
+    },
+  });
+  return { success: true, block_id: blockId };
+}
+
+async function docDeleteBlock(docToken: string, blockId: string) {
+  const blockInfo = await feishuGet(`/open-apis/docx/v1/documents/${docToken}/blocks/${blockId}`);
+  const parentId = blockInfo?.block?.parent_id || docToken;
+  const children = await feishuGet(`/open-apis/docx/v1/documents/${docToken}/blocks/${parentId}/children`);
+  const items = children?.items || [];
+  const index = items.findIndex((item: any) => item.block_id === blockId);
+  if (index === -1) throw new Error('Block not found');
+
+  await feishuDelete(`/open-apis/docx/v1/documents/${docToken}/blocks/${parentId}/children`, {
+    start_index: String(index),
+    end_index: String(index + 1),
+  });
+  return { success: true, deleted_block_id: blockId };
+}
+
+// ============================================================
+//  Wiki API
+// ============================================================
+
+async function wikiSpaces() {
+  const data = await feishuGet('/open-apis/wiki/v2/spaces');
+  return {
+    spaces: (data?.items || []).map((s: any) => ({
+      space_id: s.space_id, name: s.name, description: s.description, visibility: s.visibility,
+    })),
+  };
+}
+
+async function wikiNodes(spaceId: string, parentNodeToken?: string) {
+  const params: Record<string, string> = {};
+  if (parentNodeToken) params.parent_node_token = parentNodeToken;
+  const data = await feishuGet(`/open-apis/wiki/v2/spaces/${spaceId}/nodes`, params);
+  return {
+    nodes: (data?.items || []).map((n: any) => ({
+      node_token: n.node_token, obj_token: n.obj_token, obj_type: n.obj_type,
+      title: n.title, has_child: n.has_child,
+    })),
+  };
+}
+
+async function wikiGet(token: string) {
+  const data = await feishuGet('/open-apis/wiki/v2/spaces/get_node', { token });
+  const node = data?.node;
+  return {
+    node_token: node?.node_token, space_id: node?.space_id, obj_token: node?.obj_token,
+    obj_type: node?.obj_type, title: node?.title, parent_node_token: node?.parent_node_token,
+    has_child: node?.has_child,
+  };
+}
+
+async function wikiCreate(spaceId: string, title: string, objType?: string, parentNodeToken?: string) {
+  const data = await feishuPost(`/open-apis/wiki/v2/spaces/${spaceId}/nodes`, {
+    obj_type: objType || 'docx', node_type: 'origin', title, parent_node_token: parentNodeToken,
+  });
+  const node = data?.node;
+  return { node_token: node?.node_token, obj_token: node?.obj_token, title: node?.title };
+}
+
+// ============================================================
+//  Drive API
+// ============================================================
+
+async function driveList(folderToken?: string) {
+  const params: Record<string, string> = {};
+  if (folderToken && folderToken !== '0') params.folder_token = folderToken;
+  const data = await feishuGet('/open-apis/drive/v1/files', params);
+  return {
+    files: (data?.files || []).map((f: any) => ({
+      token: f.token, name: f.name, type: f.type, url: f.url,
+      created_time: f.created_time, modified_time: f.modified_time,
+    })),
+  };
+}
+
+async function driveCreateFolder(name: string, folderToken?: string) {
+  const data = await feishuPost('/open-apis/drive/v1/files/create_folder', {
+    name, folder_token: folderToken || '0',
+  });
+  return { token: data?.token, url: data?.url };
+}
+
+async function driveMove(fileToken: string, type: string, folderToken: string) {
+  const data = await feishuPost(`/open-apis/drive/v1/files/${fileToken}/move`, {
+    type, folder_token: folderToken,
+  });
+  return { success: true, task_id: data?.task_id };
+}
+
+async function driveDelete(fileToken: string, type: string) {
+  const data = await feishuDelete(`/open-apis/drive/v1/files/${fileToken}`, { type });
+  return { success: true, task_id: data?.task_id };
+}
+
+// ============================================================
+//  Permission API
+// ============================================================
+
+async function permList(token: string, type: string) {
+  const data = await feishuGet(`/open-apis/drive/v1/permissions/${token}/members`, { type });
+  return {
+    members: (data?.items || []).map((m: any) => ({
+      member_type: m.member_type, member_id: m.member_id, perm: m.perm, name: m.name,
+    })),
+  };
+}
+
+async function permAdd(token: string, type: string, memberType: string, memberId: string, perm: string) {
+  const data = await feishuPost(`/open-apis/drive/v1/permissions/${token}/members?type=${type}&need_notification=false`, {
+    member_type: memberType, member_id: memberId, perm,
+  });
+  return { success: true, member: data?.member };
+}
+
+async function permRemove(token: string, type: string, memberType: string, memberId: string) {
+  await feishuDelete(`/open-apis/drive/v1/permissions/${token}/members/${memberId}`, {
+    type, member_type: memberType,
+  });
+  return { success: true };
+}
+
+// ============================================================
+//  App Scopes API
+// ============================================================
+
+async function appScopes() {
+  const data = await feishuGet('/open-apis/application/v6/scopes');
+  const scopes = data?.scopes || [];
+  const granted = scopes.filter((s: any) => s.grant_status === 1);
+  const pending = scopes.filter((s: any) => s.grant_status !== 1);
+  return {
+    granted: granted.map((s: any) => ({ name: s.scope_name, type: s.scope_type })),
+    pending: pending.map((s: any) => ({ name: s.scope_name, type: s.scope_type })),
+    summary: `${granted.length} granted, ${pending.length} pending`,
+  };
+}
+
+// ============================================================
+//  Tool Registration
+// ============================================================
+
+function json(data: unknown) {
+  return {
+    content: [{ type: 'text' as const, text: JSON.stringify(data, null, 2) }],
+    details: data,
+  };
+}
+
+let _registered = false;
+
+export function isFeishuToolsRegistered(): boolean {
+  return _registered;
+}
+
+export function registerFeishuTools(api: any, logger: any): boolean {
+  if (_registered) {
+    logger.info('[feishu-tools] 已注册，跳过');
+    return false;
+  }
+
+  if (!hasCredentials()) {
+    logger.info('[feishu-tools] 无飞书凭据，跳过');
+    return false;
+  }
+
+  // 检测 OpenClaw 飞书插件是否已启用
+  // 只有飞书插件 enabled 且有配置时才跳过；disabled 或不存在时正常注册
+  try {
+    const config = api.config;
+    const entries = config?.plugins?.entries || {};
+    const feishuEntry = entries['feishu'] as any;
+    // 飞书插件存在且未明确 disable → 说明它会注册工具，我们跳过
+    if (feishuEntry && feishuEntry.enabled !== false) {
+      // 还要确认它有实际的飞书账号配置（有 appId），否则它也不会注册工具
+      const accounts = feishuEntry.config?.accounts || feishuEntry.accounts;
+      const hasAccount = Array.isArray(accounts) 
+        ? accounts.some((a: any) => a.appId || a.config?.appId)
+        : (feishuEntry.config?.appId || feishuEntry.appId);
+      if (hasAccount) {
+        logger.info('[feishu-tools] 检测到 OpenClaw 飞书插件已启用，跳过注册');
+        return false;
+      }
+    }
+  } catch {}
+
+  // ---- feishu_doc ----
+  api.registerTool({
+    name: 'feishu_doc',
+    label: 'Feishu Doc',
+    description: 'Feishu document operations. Actions: read, write, append, create, list_blocks, get_block, update_block, delete_block',
+    parameters: {
+      type: 'object',
+      properties: {
+        action: { type: 'string', enum: ['read', 'write', 'append', 'create', 'list_blocks', 'get_block', 'update_block', 'delete_block'], description: 'Action to perform' },
+        doc_token: { type: 'string', description: 'Document token (from URL /docx/XXX)' },
+        content: { type: 'string', description: 'Markdown content (for write/append/update_block)' },
+        title: { type: 'string', description: 'Document title (for create)' },
+        folder_token: { type: 'string', description: 'Target folder token (optional)' },
+        block_id: { type: 'string', description: 'Block ID (for get_block/update_block/delete_block)' },
+      },
+      required: ['action'],
+    },
+    async execute(_id: string, p: any) {
+      try {
+        switch (p.action) {
+          case 'read': return json(await docRead(p.doc_token));
+          case 'write': return json(await docWrite(p.doc_token, p.content));
+          case 'append': return json(await docAppend(p.doc_token, p.content));
+          case 'create': return json(await docCreate(p.title, p.folder_token));
+          case 'list_blocks': return json(await docListBlocks(p.doc_token));
+          case 'get_block': return json(await docGetBlock(p.doc_token, p.block_id));
+          case 'update_block': return json(await docUpdateBlock(p.doc_token, p.block_id, p.content));
+          case 'delete_block': return json(await docDeleteBlock(p.doc_token, p.block_id));
+          default: return json({ error: `Unknown action: ${p.action}` });
+        }
+      } catch (err: any) { return json({ error: err.message }); }
+    },
+  }, { name: 'feishu_doc' });
+
+  // ---- feishu_wiki ----
+  api.registerTool({
+    name: 'feishu_wiki',
+    label: 'Feishu Wiki',
+    description: 'Feishu knowledge base operations. Actions: spaces, nodes, get, create',
+    parameters: {
+      type: 'object',
+      properties: {
+        action: { type: 'string', enum: ['spaces', 'nodes', 'get', 'create'], description: 'Action' },
+        space_id: { type: 'string', description: 'Knowledge space ID' },
+        token: { type: 'string', description: 'Wiki node token (from URL /wiki/XXX)' },
+        title: { type: 'string', description: 'Node title' },
+        obj_type: { type: 'string', description: 'Object type (default: docx)' },
+        parent_node_token: { type: 'string', description: 'Parent node token' },
+      },
+      required: ['action'],
+    },
+    async execute(_id: string, p: any) {
+      try {
+        switch (p.action) {
+          case 'spaces': return json(await wikiSpaces());
+          case 'nodes': return json(await wikiNodes(p.space_id, p.parent_node_token));
+          case 'get': return json(await wikiGet(p.token));
+          case 'create': return json(await wikiCreate(p.space_id, p.title, p.obj_type, p.parent_node_token));
+          default: return json({ error: `Unknown action: ${p.action}` });
+        }
+      } catch (err: any) { return json({ error: err.message }); }
+    },
+  }, { name: 'feishu_wiki' });
+
+  // ---- feishu_drive ----
+  api.registerTool({
+    name: 'feishu_drive',
+    label: 'Feishu Drive',
+    description: 'Feishu cloud storage operations. Actions: list, create_folder, move, delete',
+    parameters: {
+      type: 'object',
+      properties: {
+        action: { type: 'string', enum: ['list', 'create_folder', 'move', 'delete'], description: 'Action' },
+        folder_token: { type: 'string', description: 'Folder token' },
+        file_token: { type: 'string', description: 'File token' },
+        name: { type: 'string', description: 'Folder name (for create_folder)' },
+        type: { type: 'string', description: 'File type (doc/docx/sheet/bitable/folder/file)' },
+      },
+      required: ['action'],
+    },
+    async execute(_id: string, p: any) {
+      try {
+        switch (p.action) {
+          case 'list': return json(await driveList(p.folder_token));
+          case 'create_folder': return json(await driveCreateFolder(p.name, p.folder_token));
+          case 'move': return json(await driveMove(p.file_token, p.type, p.folder_token));
+          case 'delete': return json(await driveDelete(p.file_token, p.type));
+          default: return json({ error: `Unknown action: ${p.action}` });
+        }
+      } catch (err: any) { return json({ error: err.message }); }
+    },
+  }, { name: 'feishu_drive' });
+
+  // ---- feishu_perm ----
+  api.registerTool({
+    name: 'feishu_perm',
+    label: 'Feishu Perm',
+    description: 'Feishu permission management. Actions: list, add, remove',
+    parameters: {
+      type: 'object',
+      properties: {
+        action: { type: 'string', enum: ['list', 'add', 'remove'], description: 'Action' },
+        token: { type: 'string', description: 'File token' },
+        type: { type: 'string', description: 'Token type (doc/docx/sheet/bitable/folder/file/wiki)' },
+        member_type: { type: 'string', description: 'Member type (email/openid/userid)' },
+        member_id: { type: 'string', description: 'Member ID' },
+        perm: { type: 'string', description: 'Permission (view/edit/full_access)' },
+      },
+      required: ['action'],
+    },
+    async execute(_id: string, p: any) {
+      try {
+        switch (p.action) {
+          case 'list': return json(await permList(p.token, p.type));
+          case 'add': return json(await permAdd(p.token, p.type, p.member_type, p.member_id, p.perm));
+          case 'remove': return json(await permRemove(p.token, p.type, p.member_type, p.member_id));
+          default: return json({ error: `Unknown action: ${p.action}` });
+        }
+      } catch (err: any) { return json({ error: err.message }); }
+    },
+  }, { name: 'feishu_perm' });
+
+  // ---- feishu_app_scopes ----
+  api.registerTool({
+    name: 'feishu_app_scopes',
+    label: 'Feishu App Scopes',
+    description: 'List current Feishu app permissions (scopes).',
+    parameters: { type: 'object', properties: {} },
+    async execute() {
+      try { return json(await appScopes()); }
+      catch (err: any) { return json({ error: err.message }); }
+    },
+  }, { name: 'feishu_app_scopes' });
+
+  _registered = true;
+  logger.info('[feishu-tools] ✅ 已注册 5 个飞书工具（feishu_doc/wiki/drive/perm/app_scopes）');
+  return true;
+}

package/src/hub-client.ts

@@ -164,6 +164,27 @@ export class HubClient {
     return res.json();
   }
 
+  async httpPut(path: string, body: any): Promise<any> {
+    const url = `${this.config.hubUrl}${path}`;
+    const headers: Record<string, string> = { 'Content-Type': 'application/json' };
+    if (this.config.token) {
+      headers['Authorization'] = `Bearer ${this.config.token}`;
+    }
+    if (this.config.adminKey) {
+      headers['X-Admin-Key'] = this.config.adminKey;
+    }
+    const res = await fetch(url, {
+      method: 'PUT',
+      headers,
+      body: JSON.stringify(body),
+    });
+    if (!res.ok) {
+      const text = await res.text();
+      throw new Error(`Hub HTTP ${res.status}: ${text}`);
+    }
+    return res.json();
+  }
+
   private async httpDelete(path: string): Promise<any> {
     const url = `${this.config.hubUrl}${path}`;
     const headers: Record<string, string> = {};
@@ -515,9 +536,21 @@ export class HubClient {
     pending.resolve(result);
   }
 
+  // 共享配置回调
+  public onSharedConfig?: (config: any) => void;
+
   private handleDirect(msg: WSMessage): void {
-    if (msg.payload?.action === 'connected') {
+    if (msg.payload?.action === 'connected' || msg.payload?.event === 'connected') {
       this.logger.info(`[cluster-hub] 连接确认: nodeId=${msg.payload.nodeId}`);
+      // 连接时附带的共享配置
+      if (msg.payload?.sharedConfig && this.onSharedConfig) {
+        this.onSharedConfig(msg.payload.sharedConfig);
+      }
+    } else if (msg.payload?.event === 'shared_config') {
+      // Hub 推送的配置更新
+      if (msg.payload?.config && this.onSharedConfig) {
+        this.onSharedConfig(msg.payload.config);
+      }
     }
   }
 

package/src/index.ts

@@ -17,6 +17,7 @@ import path from 'path';
 import fs from 'fs';
 import { HubClient } from './hub-client.js';
 import { TaskStore, ChatStore, NodeEventStore } from './store.js';
+import { setCredentials, registerFeishuTools, hasCredentials } from './feishu-tools.js';
 import type {
   HubPluginConfig, DEFAULT_CONFIG, ResultPayload, WSMessage,
   QueuedTask, ChatConfig, StoredTask, StoredChatMessage, StoredNodeEvent,
@@ -667,6 +668,15 @@ const plugin = {
       handleNodeEvent('node_offline', { nodeId });
     };
 
+    // Hub 下发共享配置 → 注册飞书工具
+    client.onSharedConfig = (config: any) => {
+      api.logger.info(`[cluster-hub] 收到共享配置: ${JSON.stringify(Object.keys(config))}`);
+      if (config.feishu?.appId && config.feishu?.appSecret) {
+        setCredentials(config.feishu);
+        registerFeishuTools(api, api.logger);
+      }
+    };
+
     // ------------------------------------------------------------------
     // Gateway RPC 方法 — 每个 handler 都捕获 broadcast 引用
     // ------------------------------------------------------------------
@@ -840,6 +850,32 @@ const plugin = {
       }
     });
 
+    // hub.shared-config.get — 获取共享配置
+    api.registerGatewayMethod('hub.shared-config.get', async ({ context, respond }: any) => {
+      captureBroadcast(context);
+      try {
+        const clusterId = client.getConfig().clusterId;
+        if (!clusterId) { respond(false, { message: '未注册' }); return; }
+        const data = await client.httpGet(`/api/clusters/${clusterId}/shared-config`);
+        respond(true, data.data || data);
+      } catch (err: any) {
+        respond(false, { message: err.message });
+      }
+    });
+
+    // hub.shared-config.set — 设置共享配置（仅根节点）
+    api.registerGatewayMethod('hub.shared-config.set', async ({ context, respond, params }: any) => {
+      captureBroadcast(context);
+      try {
+        const clusterId = client.getConfig().clusterId;
+        if (!clusterId) { respond(false, { message: '未注册' }); return; }
+        const data = await client.httpPut(`/api/clusters/${clusterId}/shared-config`, params || {});
+        respond(true, data.data || data);
+      } catch (err: any) {
+        respond(false, { message: err.message });
+      }
+    });
+
     // hub.unregister — 注销节点
     api.registerGatewayMethod('hub.unregister', async ({ context, respond, params }: any) => {
       captureBroadcast(context);
@@ -1582,12 +1618,14 @@ const plugin = {
         .option('--name <name>', '节点名称')
         .option('--alias <alias>', '节点别名')
         .option('--parent <parentId>', '父节点 ID')
+        .option('--invite <code>', '邀请码（加入已有集群时需要）')
         .action(async (opts: any) => {
           try {
             const result = await client.register({
               name: opts.name || client.getConfig().nodeName || 'OpenClaw Node',
               alias: opts.alias || client.getConfig().nodeAlias || `node-${Date.now()}`,
               parentId: opts.parent || null,
+              inviteCode: opts.invite || undefined,
               capabilities: client.getConfig().capabilities,
             });
             await persistConfig();
@@ -1658,6 +1696,36 @@ const plugin = {
         client.disconnect();
         console.log('✅ 已断开');
       });
+
+      hub.command('invite')
+        .description('查看或生成邀请码')
+        .option('--new', '生成新邀请码')
+        .option('--node <nodeId>', '指定节点 ID')
+        .action(async (opts: any) => {
+          const nodeId = opts.node || client.getConfig().nodeId;
+          if (!nodeId) { console.error('❌ 没有节点 ID'); return; }
+          try {
+            if (opts.new) {
+              const data = await client.httpPost(`/api/nodes/${nodeId}/invite-code`, {});
+              const code = data.data?.inviteCode || data.inviteCode;
+              console.log(`✅ 新邀请码: ${code}`);
+              console.log(`\n子节点加入命令:`);
+              console.log(`  openclaw hub register --parent ${nodeId} --invite ${code} --name "节点名" --alias "别名"`);
+            } else {
+              const data = await client.httpGet(`/api/nodes/${nodeId}/invite-code`);
+              const code = data.data?.inviteCode || data.inviteCode;
+              if (code) {
+                console.log(`📋 当前邀请码: ${code}`);
+                console.log(`\n子节点加入命令:`);
+                console.log(`  openclaw hub register --parent ${nodeId} --invite ${code} --name "节点名" --alias "别名"`);
+              } else {
+                console.log('暂无邀请码，使用 openclaw hub invite --new 生成');
+              }
+            }
+          } catch (err: any) {
+            console.error(`❌ 失败: ${err.message}`);
+          }
+        });
     }, { commands: ['hub'] });
 
     // ------------------------------------------------------------------

package/src/types.ts

@@ -85,6 +85,7 @@ export interface RegisterRequest {
   name: string;
   alias: string;
   parentId?: string | null;
+  inviteCode?: string;
   capabilities?: string[];
 }