openclaw-xiaoyou 1.0.0

package/README.md

@@ -0,0 +1,163 @@
+# openclaw-xiaoyou
+
+OpenClaw channel 插件 —— 通过持久 WebSocket 出站连接桥接企业内部服务。
+
+## 架构
+
+```
+┌──────────────┐    WebSocket (出站)    ┌──────────────────────────┐
+│              │◀══════════════════════▶│                          │
+│  企业 IM     │    xiaoyou 插件        │  OpenClaw Gateway        │
+│  服务端      │    (运行在 Gateway 内) │  (port 18789)            │
+│              │                        │  ├─ xiaoyou plugin       │
+└──────────────┘                        │  ├─ Agent / LLM          │
+     ▲                                  │  └─ Tools / Memory       │
+     │ 用户消息                         └──────────────────────────┘
+     ▼
+  企业用户
+```
+
+插件安装在 OpenClaw 中，由 Gateway 管理生命周期。企业侧无需暴露公网端口。
+
+## 安装
+
+```bash
+# 从 npm 安装
+openclaw plugins install openclaw-xiaoyou
+openclaw plugins enable openclaw-xiaoyou
+
+# 或从本地路径安装
+openclaw plugins install /path/to/openclaw-xiaoyou
+openclaw plugins enable openclaw-xiaoyou
+```
+
+## 配置
+
+配置写在 **OpenClaw 的配置文件**中，不是插件目录里的单独文件。
+OpenClaw 启动时会自动加载配置并注入给插件。
+
+**配置文件位置**：`~/.openclaw/config.json`
+
+### 方式一：命令行交互式向导（推荐）
+
+```bash
+openclaw channels add --channel xiaoyou
+```
+
+向导会依次提示你填写 `wsUrl`、`authToken` 等，自动写入配置文件。
+
+### 方式二：手动编辑配置文件
+
+打开 `~/.openclaw/config.json`，在 `channels` 下添加 `xiaoyou` 段：
+
+```json
+{
+  "channels": {
+    "xiaoyou": {
+      "enabled": true,
+      "wsUrl": "wss://im.corp.example.com/ws",
+      "authToken": "your-enterprise-auth-token",
+      "dmSecurity": "open",
+      "allowFrom": [],
+      "reconnectIntervalMs": 3000,
+      "maxReconnectAttempts": 0,
+      "heartbeatIntervalMs": 30000,
+      "heartbeatTimeoutMs": 10000
+    }
+  }
+}
+```
+
+> 插件目录下的 `config.example.json` 是配置模板，可以直接复制其中
+> `channels.xiaoyou` 部分到你的 `~/.openclaw/config.json` 中。
+
+### 配置项
+
+| 配置项 | 类型 | 必填 | 默认值 | 说明 |
+|--------|------|------|--------|------|
+| `enabled` | boolean | 否 | false | 启用/禁用 |
+| `wsUrl` | string | ✅ | — | 企业 WebSocket 服务地址 |
+| `authToken` | string | ✅ | — | 连接企业服务的认证 Token |
+| `dmSecurity` | string | 否 | open | 安全策略：`open` / `allowlist` |
+| `allowFrom` | string[] | 否 | [] | 白名单用户 ID（`allowlist` 时生效） |
+| `reconnectIntervalMs` | number | 否 | 3000 | 重连基础间隔（ms），指数退避 |
+| `maxReconnectAttempts` | number | 否 | 0 | 最大重连次数，0 = 无限 |
+| `heartbeatIntervalMs` | number | 否 | 30000 | 心跳间隔（ms） |
+| `heartbeatTimeoutMs` | number | 否 | 10000 | 心跳超时（ms） |
+
+### 多账号
+
+同时连接多个企业服务：
+
+```json
+{
+  "channels": {
+    "xiaoyou": {
+      "enabled": true,
+      "wsUrl": "wss://default.corp.com/ws",
+      "authToken": "default-token",
+      "accounts": {
+        "sales": {
+          "wsUrl": "wss://sales.corp.com/ws",
+          "authToken": "sales-token"
+        },
+        "support": {
+          "wsUrl": "wss://support.corp.com/ws",
+          "authToken": "support-token"
+        }
+      }
+    }
+  }
+}
+```
+
+## CLI 命令
+
+```bash
+# 查看连接状态
+openclaw xiaoyou status
+
+# 发送测试消息
+openclaw xiaoyou test --to <conversationId> --text "Hello"
+```
+
+## 本地开发测试
+
+```bash
+cd openclaw-xiaoyou
+
+# 安装依赖
+npm install
+
+# 终端 1: 启动模拟企业服务
+npm run demo:server
+
+# 终端 2: 启动 OpenClaw Gateway（配置 wsUrl 指向 ws://127.0.0.1:9090）
+openclaw gateway
+
+# 在终端 1 中输入消息，观察 Agent 回复
+```
+
+## 文件结构
+
+```
+openclaw-xiaoyou/
+├── package.json              # openclaw.channel 元数据
+├── openclaw.plugin.json      # 插件 manifest + 配置 schema
+├── index.ts                  # 插件入口 (register)
+├── setup-entry.ts            # 轻量 setup 入口
+├── config.example.json       # 配置模板（供用户参考复制）
+├── demo-enterprise-server.ts # 企业服务端 Mock
+├── docs/
+│   └── communication-flow.md # 通信架构文档
+└── src/
+    ├── types.ts              # 协议类型定义
+    ├── enterprise-client.ts  # 企业 WebSocket 客户端
+    ├── channel.ts            # ChannelPlugin 实现
+    ├── channel.test.ts       # 测试
+    └── onboarding.ts         # 交互式配置向导
+```
+
+## License
+
+MIT

package/config.example.json

@@ -0,0 +1,35 @@
+{
+  "_说明": "将此文件中的 channels.xiaoyou 部分复制到你的 OpenClaw 配置文件中",
+  "_配置文件位置": "~/.openclaw/config.json",
+  "_添加方式": "也可以通过命令 openclaw channels add --channel xiaoyou 交互式配置",
+
+  "channels": {
+    "xiaoyou": {
+      "enabled": true,
+
+      "_comment_wsUrl": "【必填】企业 WebSocket 服务地址",
+      "wsUrl": "wss://im.corp.example.com/ws",
+
+      "_comment_authToken": "【必填】连接企业服务的认证 Token",
+      "authToken": "your-enterprise-auth-token",
+
+      "_comment_dmSecurity": "DM 安全策略: open=允许所有人, allowlist=仅白名单",
+      "dmSecurity": "open",
+
+      "_comment_allowFrom": "白名单用户 ID 列表 (dmSecurity=allowlist 时生效)",
+      "allowFrom": [],
+
+      "_comment_reconnect": "重连基础间隔(ms)，实际按 3s→6s→12s→...→60s 指数退避",
+      "reconnectIntervalMs": 3000,
+
+      "_comment_maxReconnect": "最大重连次数，0=无限重试",
+      "maxReconnectAttempts": 0,
+
+      "_comment_heartbeat": "心跳间隔(ms)，插件定时向企业服务发 ping",
+      "heartbeatIntervalMs": 30000,
+
+      "_comment_heartbeatTimeout": "心跳超时(ms)，超时未收到 pong 则断开重连",
+      "heartbeatTimeoutMs": 10000
+    }
+  }
+}

package/demo-enterprise-server.ts

@@ -0,0 +1,138 @@
+/**
+ * 企业服务端 Mock —— 模拟企业 IM 的 WebSocket 服务
+ *
+ * 启动:
+ *   npx tsx demo-enterprise-server.ts
+ *   npm run demo:server
+ *
+ * 它会：
+ * 1. 在 ws://127.0.0.1:9090 启动 WebSocket 服务
+ * 2. 接受 xiaoyou 插件的连接和认证
+ * 3. 提供交互式命令行，手动发送消息
+ * 4. 打印收到的 Agent 回复
+ */
+
+import { WebSocketServer, WebSocket } from "ws";
+import { createInterface } from "node:readline";
+
+const PORT = 9090;
+const EXPECTED_TOKEN = "demo-enterprise-token";
+
+const wss = new WebSocketServer({ port: PORT });
+let activeWs: WebSocket | null = null;
+
+console.log(`\n╔══════════════════════════════════════════════════╗`);
+console.log(`║  企业 IM Mock Server                              ║`);
+console.log(`║  监听: ws://127.0.0.1:${PORT}                        ║`);
+console.log(`║  认证 Token: ${EXPECTED_TOKEN}              ║`);
+console.log(`╚══════════════════════════════════════════════════╝\n`);
+console.log(`等待 xiaoyou 插件连接...\n`);
+
+wss.on("connection", (ws, req) => {
+  console.log(`[server] 新连接: ${req.socket.remoteAddress}`);
+  activeWs = ws;
+
+  ws.on("message", (data) => {
+    const raw = data.toString();
+    let msg: any;
+    try { msg = JSON.parse(raw); } catch { console.log(`[server] 无效 JSON: ${raw.slice(0, 200)}`); return; }
+
+    switch (msg.type) {
+      case "auth": {
+        console.log(`[server] 收到认证请求, token=${msg.token?.slice(0, 16)}...`);
+        if (msg.token === EXPECTED_TOKEN) {
+          ws.send(JSON.stringify({ type: "auth_result", ok: true, sessionId: `sess-${Date.now()}` }));
+          console.log("[server] ✓ 认证成功\n");
+          console.log("────────────────────────────────────────────");
+          console.log("  现在可以输入消息发送给 Agent:");
+          console.log("  格式: <文本>              (默认 conv=demo, user=test-user)");
+          console.log("  格式: /conv <id> <文本>   (指定 conversationId)");
+          console.log("  格式: /user <id> <文本>   (指定 senderId)");
+          console.log("  格式: /quit               (退出)");
+          console.log("────────────────────────────────────────────\n");
+        } else {
+          ws.send(JSON.stringify({ type: "auth_result", ok: false, error: "invalid token" }));
+          console.log("[server] ✗ 认证失败\n");
+        }
+        break;
+      }
+      case "ping": {
+        ws.send(JSON.stringify({ type: "pong", seq: msg.seq, ts: Date.now() }));
+        break;
+      }
+      case "reply": {
+        console.log(`\n${"═".repeat(50)}`);
+        console.log(`  🤖 Agent 回复`);
+        console.log(`  会话:    ${msg.conversationId}`);
+        console.log(`  消息ID:  ${msg.messageId}`);
+        console.log(`  内容:    ${msg.text}`);
+        if (msg.mediaUrls?.length) console.log(`  媒体:    ${JSON.stringify(msg.mediaUrls)}`);
+        console.log(`  时间:    ${new Date(msg.timestamp).toLocaleString()}`);
+        console.log(`${"═".repeat(50)}\n`);
+        break;
+      }
+      default:
+        console.log(`[server] 未知消息: ${msg.type}`);
+    }
+  });
+
+  ws.on("close", (code, reason) => {
+    console.log(`[server] 连接关闭 (code=${code}, reason=${reason.toString()})`);
+    if (activeWs === ws) activeWs = null;
+  });
+
+  ws.on("error", (err) => {
+    console.error(`[server] 错误: ${err.message}`);
+  });
+});
+
+// ─── 交互式命令行 ────────────────────────────────────
+
+const rl = createInterface({ input: process.stdin, output: process.stdout });
+
+rl.on("line", (line) => {
+  const input = line.trim();
+  if (!input) return;
+
+  if (input === "/quit") {
+    console.log("[server] 退出...");
+    wss.close();
+    rl.close();
+    process.exit(0);
+  }
+
+  if (!activeWs || activeWs.readyState !== WebSocket.OPEN) {
+    console.log("[server] 无活跃连接，无法发送");
+    return;
+  }
+
+  let conversationId = "demo";
+  let senderId = "test-user";
+  let senderName = "测试用户";
+  let text = input;
+
+  // /conv <id> <text>
+  if (input.startsWith("/conv ")) {
+    const parts = input.slice(6).split(" ");
+    conversationId = parts[0];
+    text = parts.slice(1).join(" ");
+  }
+  // /user <id> <text>
+  else if (input.startsWith("/user ")) {
+    const parts = input.slice(6).split(" ");
+    senderId = parts[0];
+    text = parts.slice(1).join(" ");
+  }
+
+  const msg = {
+    type: "message",
+    conversationId,
+    senderId,
+    senderName,
+    text,
+    metadata: { source: "enterprise-mock" },
+  };
+
+  activeWs.send(JSON.stringify(msg));
+  console.log(`[server] → 已发送: [${senderId}@${conversationId}] ${text}`);
+});

package/docs/Xiaoyou-SKILL.md

@@ -0,0 +1,111 @@
+---
+name: xiaoyou-install-router
+description: Use when users want to install, upgrade, uninstall, configure, or troubleshoot Xiaoyou (小优) channel integration for OpenClaw. Xiaoyou bridges OpenClaw to enterprise services via persistent WebSocket.
+---
+
+# 小优 Channel 安装入口
+
+小优 channel 安装、升级、卸载统一使用远程脚本：
+
+```bash
+https://aitest.haiersmarthomes.com/aiservice/claw/install-xiaoyou.sh
+```
+
+不要把 OpenClaw 的底层安装命令拆散执行。除非远程脚本失败且需要排障，否则直接调用 `install-xiaoyou.sh`。
+
+## 触发词
+
+- "安装小优" / "小优安装"
+- "小优接入" / "接入小优"
+- "配置 xiaoyou" / "xiaoyou 配置"
+- "升级小优" / "更新小优"
+- "卸载小优" / "移除小优"
+- "我想用小优" / "启用小优"
+- "小优 channel" / "xiaoyou channel"
+
+## 标准执行
+
+优先直接通过 `curl | bash` 执行远程脚本：
+
+```bash
+curl -fsSL https://aitest.haiersmarthomes.com/aiservice/claw/install-xiaoyou.sh | bash -s -- --ws-url wss://im.corp.example.com/ws --token <AccessToken>
+```
+
+### 参数说明
+
+| 参数 | 必填 | 说明 |
+|------|------|------|
+| `--ws-url <url>` | ✅ 首次安装 | 企业 WebSocket 服务地址 |
+| `--token <token>` | ✅ 首次安装 | 企业服务认证 Token |
+| `--version <ver>` | 否 | 指定 openclaw-xiaoyou 版本，默认 latest |
+| `--check-only` | 否 | 只输出计划，不执行真实改动 |
+| `uninstall` | 否 | 卸载小优 channel |
+
+### 首次安装
+
+用户必须提供 `--ws-url` 和 `--token`：
+
+```bash
+curl -fsSL https://aitest.haiersmarthomes.com/aiservice/claw/install-xiaoyou.sh | bash -s -- --ws-url wss://im.corp.example.com/ws --token my-enterprise-token
+```
+
+### 升级
+
+已安装后的升级可以不传参数，脚本会复用现有配置：
+
+```bash
+curl -fsSL https://aitest.haiersmarthomes.com/aiservice/claw/install-xiaoyou.sh | bash -s --
+```
+
+如果升级时传入 `--ws-url` 或 `--token`，会覆盖现有配置。
+
+### 指定版本
+
+```bash
+curl -fsSL https://aitest.haiersmarthomes.com/aiservice/claw/install-xiaoyou.sh | bash -s -- --version 1.0.2 --ws-url wss://im.corp.example.com/ws --token my-token
+```
+
+## 卸载
+
+```bash
+curl -fsSL https://aitest.haiersmarthomes.com/aiservice/claw/install-xiaoyou.sh | bash -s -- uninstall
+```
+
+卸载会删除 xiaoyou channel 配置、插件记录和扩展目录。
+
+## 预检
+
+```bash
+curl -fsSL https://aitest.haiersmarthomes.com/aiservice/claw/install-xiaoyou.sh | bash -s -- --check-only
+curl -fsSL https://aitest.haiersmarthomes.com/aiservice/claw/install-xiaoyou.sh | bash -s -- uninstall --check-only
+```
+
+## 失败处理
+
+如果脚本执行失败，优先让用户提供完整 `[xiaoyou-install]` 日志。常见判断：
+
+| 日志现象 | 处理 |
+|----------|------|
+| 缺少 `--ws-url` | 要求用户提供企业 WebSocket 服务地址 |
+| 缺少 `--token` | 要求用户提供企业服务认证 Token |
+| 未检测到 OpenClaw | 提示用户先安装并启动 OpenClaw |
+| npm latest 查询失败 | 可让脚本继续幂等安装，或指定 `--version` |
+| wsUrl 格式不合法 | 地址必须以 `ws://` 或 `wss://` 开头 |
+
+## 脚本做了什么
+
+1. 检测 OpenClaw 是否已安装并运行
+2. 安装/升级 `openclaw-xiaoyou` 插件（`openclaw plugins install openclaw-xiaoyou@latest`）
+3. 写入 channel 配置到 `~/.openclaw/openclaw.json`：
+   - `channels.xiaoyou.enabled = true`
+   - `channels.xiaoyou.wsUrl = <用户提供的地址>`
+   - `channels.xiaoyou.authToken = <用户提供的 token>`
+   - `channels.xiaoyou.dmSecurity = open`
+4. 检查插件状态和 gateway 运行状态
+
+## 完成定义
+
+- 脚本退出码为 0。
+- 日志显示安装、升级或卸载流程完成。
+- 安装场景下，`openclaw xiaoyou status` 显示 connected。
+- 企业服务端能收到来自 xiaoyou 插件的 WebSocket 连接。