openclaw-xiaoyou 1.0.0

package/docs/publish-and-deploy.md

@@ -0,0 +1,296 @@
+# openclaw-xiaoyou 发布与部署指南
+
+## 1. 整体流程
+
+```
+开发者侧                                          用户侧
+─────────                                          ──────
+
+  编写代码                                         在 OpenClaw 中输入口令
+     │                                                  │
+     ▼                                                  ▼
+  npm run build                                    Agent 读取 Xiaoyou-SKILL.md
+     │                                                  │
+     ▼                                                  ▼
+  npm publish ──▶ npm 仓库 ◀── openclaw plugins install
+     │               │                                  │
+     ▼               │                                  ▼
+  上传脚本到服务器    │                             curl install-xiayou.sh
+                     │                                  │
+                     └──────────────────────────────────┘
+                          脚本从 npm 拉取插件包
+```
+
+## 2. 开发者侧：构建与发布
+
+### 2.1 前置条件
+
+- Node.js >= 18
+- npm 账号（公共 npm）或私有仓库访问权限
+- OpenClaw 开发环境（用于本地测试）
+
+### 2.2 构建
+
+```bash
+cd openclaw-ws-bridge
+
+# 安装依赖
+npm install
+
+# 编译 TypeScript → dist/
+npm run build
+
+# 运行测试确认
+npm test
+```
+
+构建产物在 `dist/` 目录，包含编译后的 JS 文件和类型声明。
+
+### 2.3 发布前检查
+
+确认 `package.json` 中的关键字段：
+
+```json
+{
+  "name": "openclaw-xiaoyou",       ← npm 包名，用户安装时用
+  "version": "1.0.0",              ← 每次发布前递增
+  "type": "module",
+  "openclaw": {
+    "extensions": ["./index.ts"],
+    "setupEntry": "./setup-entry.ts",
+    "channel": {
+      "id": "xiaoyou"               ← OpenClaw 内部 channel 标识
+    }
+  }
+}
+```
+
+确认 `.gitignore` 或 `.npmignore` 不会排除必要文件。npm 发布时需要包含：
+
+```
+index.ts / dist/index.js
+setup-entry.ts / dist/setup-entry.js
+src/ 或 dist/src/
+package.json
+openclaw.plugin.json
+```
+
+### 2.4 发布到公共 npm
+
+```bash
+# 首次使用需要登录
+npm login
+
+# 检查将要发布的文件
+npm pack --dry-run
+
+# 发布
+npm publish
+
+# 发布指定 tag（如 beta 版本）
+npm publish --tag beta
+```
+
+发布成功后，任何人都可以通过以下方式安装：
+
+```bash
+openclaw plugins install openclaw-xiaoyou
+# 或
+npm install openclaw-xiaoyou
+```
+
+### 2.5 发布到私有 npm 仓库
+
+如果使用企业私有仓库（Verdaccio / Nexus / GitHub Packages / 阿里云 npm 等）：
+
+#### 方式一：使用 scope（推荐）
+
+修改 `package.json`：
+
+```json
+{
+  "name": "@yourorg/openclaw-xiaoyou",
+  "publishConfig": {
+    "registry": "https://npm.yourcompany.com/"
+  }
+}
+```
+
+同时修改 `install-xiayou.sh` 中的 `PLUGIN_NAME`：
+
+```bash
+PLUGIN_NAME="@yourorg/openclaw-xiaoyou"
+```
+
+发布：
+
+```bash
+npm publish --registry https://npm.yourcompany.com/
+```
+
+#### 方式二：不使用 scope
+
+```bash
+# 临时指定 registry 发布
+npm publish --registry https://npm.yourcompany.com/
+```
+
+### 2.6 版本管理
+
+每次发布新版本前递增版本号：
+
+```bash
+# 补丁版本 1.0.0 → 1.0.1（bug 修复）
+npm version patch
+
+# 次版本 1.0.0 → 1.1.0（新功能）
+npm version minor
+
+# 主版本 1.0.0 → 2.0.0（破坏性变更）
+npm version major
+
+# 然后发布
+npm publish
+```
+
+## 3. 开发者侧：部署脚本和文档
+
+### 3.1 需要上传到服务器的文件
+
+将以下两个文件上传到 `https://aitest.haiersmarthomes.com/aiservice/claw/`：
+
+| 文件 | 服务器路径 | 用途 |
+|------|-----------|------|
+| `install-xiayou.sh` | `/aiservice/claw/install-xiayou.sh` | 一键安装脚本 |
+| `Xiaoyou-SKILL.md` | `/aiservice/claw/Xiaoyou-SKILL.md` | Agent 技能文档 |
+
+上传后确认可访问：
+
+```bash
+# 验证脚本可下载
+curl -fsSL https://aitest.haiersmarthomes.com/aiservice/claw/install-xiayou.sh | head -5
+
+# 验证 SKILL 文档可下载
+curl -fsSL https://aitest.haiersmarthomes.com/aiservice/claw/Xiaoyou-SKILL.md | head -5
+```
+
+### 3.2 服务器目录结构
+
+```
+/aiservice/claw/
+├── install-xiayou.sh       # 安装脚本
+└── Xiaoyou-SKILL.md         # 技能文档
+```
+
+npm 仓库（公共或私有）：
+
+```
+openclaw-xiaoyou@1.0.0       # 插件包（由 npm publish 发布）
+```
+
+## 4. 用户侧：安装使用
+
+### 4.1 通过 OpenClaw Agent 口令安装（推荐）
+
+用户在 OpenClaw 对话中输入：
+
+```
+按照 https://aitest.haiersmarthomes.com/aiservice/claw/Xiaoyou-SKILL.md 文档完成小优 channel 配置，
+wsUrl 为 wss://im.corp.example.com/ws，token 为 my-enterprise-token
+```
+
+Agent 会自动：
+1. 读取 SKILL.md
+2. 执行 `curl | bash` 安装脚本
+3. 脚本从 npm 拉取 `openclaw-xiaoyou` 插件
+4. 写入 channel 配置
+
+### 4.2 通过命令行手动安装
+
+```bash
+curl -fsSL https://aitest.haiersmarthomes.com/aiservice/claw/install-xiayou.sh | bash -s -- \
+  --ws-url wss://im.corp.example.com/ws \
+  --token my-enterprise-token
+```
+
+### 4.3 私有 npm 仓库的用户侧配置
+
+如果插件发布在私有 npm，用户机器上需要先配置 registry：
+
+```bash
+# 方式一：全局配置（影响所有 npm 操作）
+npm config set registry https://npm.yourcompany.com/
+
+# 方式二：仅对 scope 配置（推荐，不影响其他包）
+npm config set @yourorg:registry https://npm.yourcompany.com/
+
+# 方式三：通过 .npmrc 文件（放在用户 home 目录）
+echo "@yourorg:registry=https://npm.yourcompany.com/" >> ~/.npmrc
+```
+
+如果私有仓库需要认证：
+
+```bash
+# 登录私有仓库
+npm login --registry https://npm.yourcompany.com/
+
+# 或手动配置 token
+echo "//npm.yourcompany.com/:_authToken=YOUR_TOKEN" >> ~/.npmrc
+```
+
+配置完成后，安装脚本中的 `openclaw plugins install` 就能自动从私有仓库拉包。
+
+## 5. 更新发布流程
+
+当插件代码有更新时：
+
+```bash
+# 1. 修改代码
+# 2. 运行测试
+npm test
+
+# 3. 递增版本
+npm version patch   # 或 minor / major
+
+# 4. 构建
+npm run build
+
+# 5. 发布
+npm publish
+
+# 6. 如果脚本或文档也有变更，重新上传到服务器
+```
+
+用户侧升级：
+
+```bash
+# 通过脚本升级（自动检测新版本）
+curl -fsSL https://aitest.haiersmarthomes.com/aiservice/claw/install-xiayou.sh | bash -s --
+
+# 或指定版本
+curl -fsSL https://aitest.haiersmarthomes.com/aiservice/claw/install-xiayou.sh | bash -s -- --version 1.1.0
+```
+
+## 6. 完整操作清单
+
+### 首次发布
+
+```
+□ npm install && npm run build && npm test
+□ npm login（首次）
+□ npm publish
+□ 上传 install-xiayou.sh 到服务器
+□ 上传 Xiaoyou-SKILL.md 到服务器
+□ 验证 curl 可下载脚本和文档
+□ 在测试环境执行安装脚本验证
+```
+
+### 后续更新
+
+```
+□ 修改代码 → npm test
+□ npm version patch/minor/major
+□ npm run build
+□ npm publish
+□ 如有脚本/文档变更，重新上传到服务器
+```

package/index.ts

@@ -0,0 +1,70 @@
+/**
+ * openclaw-xiaoyou 插件入口
+ *
+ * 安装方式:
+ *   openclaw plugins install openclaw-xiaoyou
+ *   openclaw plugins enable openclaw-xiaoyou
+ *
+ * 配置方式:
+ *   openclaw channels add --channel xiaoyou
+ */
+
+import { xiayouPlugin, setRuntime } from "./src/channel.js";
+
+const plugin = {
+  id: "xiaoyou",
+  name: "Xiaoyou",
+  description: "Bridge OpenClaw to enterprise services via persistent WebSocket connection",
+
+  register(api: any) {
+    // 注入 runtime，供 gateway/outbound 内部使用
+    setRuntime(api.runtime);
+
+    // 注册 channel
+    api.registerChannel({ plugin: xiayouPlugin });
+
+    // 注册 CLI 子命令
+    api.registerCli?.(
+      ({ program }: any) => {
+        const cmd = program
+          .command("xiaoyou")
+          .description("Xiaoyou channel management");
+
+        cmd
+          .command("status")
+          .description("Show enterprise WebSocket connection status")
+          .action(async () => {
+            const status = await xiayouPlugin.status.describe({
+              account: { accountId: "default" },
+            });
+            console.log(JSON.stringify(status, null, 2));
+          });
+
+        cmd
+          .command("test")
+          .description("Send a test reply through the bridge")
+          .option("--to <conversationId>", "Target conversation ID")
+          .option("--text <text>", "Message text", "Hello from OpenClaw!")
+          .action(async (opts: any) => {
+            if (!opts.to) {
+              console.error("--to <conversationId> is required");
+              return;
+            }
+            const result = await xiayouPlugin.outbound.send({
+              account: { accountId: "default" },
+              to: opts.to,
+              payload: { kind: "text", text: opts.text },
+            });
+            console.log(JSON.stringify(result, null, 2));
+          });
+      },
+      {
+        descriptors: [
+          { name: "xiaoyou", description: "Xiaoyou channel management", hasSubcommands: true },
+        ],
+      }
+    );
+  },
+};
+
+export default plugin;

package/openclaw.plugin.json

@@ -0,0 +1,74 @@
+{
+  "id": "xiaoyou",
+  "name": "Xiaoyou",
+  "description": "Bridge OpenClaw to enterprise services via persistent WebSocket connection",
+  "version": "1.0.0",
+  "channel": {
+    "id": "xiaoyou",
+    "configSchema": {
+      "type": "object",
+      "required": ["wsUrl", "authToken"],
+      "properties": {
+        "enabled": {
+          "type": "boolean",
+          "default": false,
+          "description": "启用/禁用此 channel"
+        },
+        "wsUrl": {
+          "type": "string",
+          "description": "企业 WebSocket 服务地址",
+          "examples": ["wss://im.corp.example.com/ws", "ws://192.168.1.100:9090"]
+        },
+        "authToken": {
+          "type": "string",
+          "sensitive": true,
+          "description": "连接企业服务的认证 Token"
+        },
+        "dmSecurity": {
+          "type": "string",
+          "enum": ["open", "allowlist"],
+          "default": "open",
+          "description": "DM 安全策略。open=允许所有用户，allowlist=仅白名单用户"
+        },
+        "allowFrom": {
+          "type": "array",
+          "items": { "type": "string" },
+          "default": [],
+          "description": "白名单用户 ID 列表（dmSecurity=allowlist 时生效）"
+        },
+        "reconnectIntervalMs": {
+          "type": "number",
+          "default": 3000,
+          "description": "重连基础间隔（毫秒），实际按指数退避递增"
+        },
+        "maxReconnectAttempts": {
+          "type": "number",
+          "default": 0,
+          "description": "最大重连次数，0=无限重试"
+        },
+        "heartbeatIntervalMs": {
+          "type": "number",
+          "default": 30000,
+          "description": "心跳发送间隔（毫秒）"
+        },
+        "heartbeatTimeoutMs": {
+          "type": "number",
+          "default": 10000,
+          "description": "心跳超时时间（毫秒），超时则断开重连"
+        },
+        "accounts": {
+          "type": "object",
+          "description": "多账号配置，key 为 accountId，值为上述字段的覆盖",
+          "additionalProperties": {
+            "type": "object",
+            "properties": {
+              "wsUrl": { "type": "string" },
+              "authToken": { "type": "string", "sensitive": true },
+              "allowFrom": { "type": "array", "items": { "type": "string" } }
+            }
+          }
+        }
+      }
+    }
+  }
+}

package/package.json

@@ -0,0 +1,34 @@
+{
+  "name": "openclaw-xiaoyou",
+  "version": "1.0.0",
+  "type": "module",
+  "description": "Xiaoyou channel plugin for OpenClaw — connects enterprise services via persistent outbound WebSocket",
+  "openclaw": {
+    "extensions": ["./index.ts"],
+    "setupEntry": "./setup-entry.ts",
+    "channel": {
+      "id": "xiaoyou",
+      "label": "Xiaoyou",
+      "selectionLabel": "Xiaoyou (enterprise WebSocket)",
+      "blurb": "Bridge OpenClaw to enterprise services via persistent WebSocket.",
+      "docsPath": "/channels/xiaoyou",
+      "aliases": ["xiaoyou"],
+      "order": 50
+    }
+  },
+  "dependencies": {
+    "ws": "^8.18.0"
+  },
+  "devDependencies": {
+    "@types/node": "^22.0.0",
+    "@types/ws": "^8.5.0",
+    "tsx": "^4.19.0",
+    "typescript": "^5.5.0",
+    "vitest": "^2.0.0"
+  },
+  "scripts": {
+    "build": "tsc",
+    "test": "vitest run",
+    "demo:server": "tsx demo-enterprise-server.ts"
+  }
+}

package/setup-entry.ts

@@ -0,0 +1,18 @@
+/**
+ * 轻量 setup 入口
+ *
+ * 当 channel 未启用时，OpenClaw 只加载此文件，
+ * 不会引入 ws 等重型依赖。
+ */
+
+import { xiayouPlugin } from "./src/channel.js";
+
+export default {
+  id: "xiaoyou",
+  name: "Xiaoyou",
+  description: "Bridge OpenClaw to enterprise services via WebSocket",
+  setup: {
+    resolveAccount: xiayouPlugin.config.resolveAccount,
+    inspectAccount: xiayouPlugin.config.inspectAccount,
+  },
+};

package/src/channel.test.ts

@@ -0,0 +1,140 @@
+import { describe, it, expect } from "vitest";
+import { xiayouPlugin } from "./channel.js";
+
+const fullCfg = {
+  channels: {
+    xiaoyou: {
+      wsUrl: "wss://im.corp.example.com/ws",
+      authToken: "test-token-123",
+      allowFrom: ["user-1", "user-2"],
+      dmSecurity: "allowlist",
+      reconnectIntervalMs: 5000,
+      heartbeatIntervalMs: 15000,
+    },
+  },
+};
+
+describe("config adapter", () => {
+  it("resolves account with all fields", () => {
+    const acct = xiayouPlugin.config.resolveAccount(fullCfg, undefined);
+    expect(acct.wsUrl).toBe("wss://im.corp.example.com/ws");
+    expect(acct.authToken).toBe("test-token-123");
+    expect(acct.allowFrom).toEqual(["user-1", "user-2"]);
+    expect(acct.reconnectIntervalMs).toBe(5000);
+    expect(acct.heartbeatIntervalMs).toBe(15000);
+    expect(acct.heartbeatTimeoutMs).toBe(10000);
+  });
+
+  it("applies defaults for optional fields", () => {
+    const cfg = { channels: { xiaoyou: { wsUrl: "ws://localhost:9090", authToken: "t" } } };
+    const acct = xiayouPlugin.config.resolveAccount(cfg, undefined);
+    expect(acct.reconnectIntervalMs).toBe(3000);
+    expect(acct.maxReconnectAttempts).toBe(0);
+    expect(acct.heartbeatIntervalMs).toBe(30000);
+    expect(acct.heartbeatTimeoutMs).toBe(10000);
+  });
+
+  it("throws when wsUrl missing", () => {
+    expect(() => xiayouPlugin.config.resolveAccount({ channels: { xiaoyou: {} } }, undefined))
+      .toThrow("wsUrl is required");
+  });
+
+  it("throws when section missing", () => {
+    expect(() => xiayouPlugin.config.resolveAccount({ channels: {} }, undefined))
+      .toThrow("config section not found");
+  });
+
+  it("resolves multi-account override", () => {
+    const cfg = {
+      channels: {
+        xiaoyou: {
+          wsUrl: "ws://default/ws",
+          authToken: "default-token",
+          accounts: {
+            sales: { wsUrl: "ws://sales/ws", authToken: "sales-token" },
+          },
+        },
+      },
+    };
+    const acct = xiayouPlugin.config.resolveAccount(cfg, "sales");
+    expect(acct.wsUrl).toBe("ws://sales/ws");
+    expect(acct.authToken).toBe("sales-token");
+  });
+
+  it("falls back to default when accountId not in accounts", () => {
+    const cfg = {
+      channels: {
+        xiaoyou: {
+          wsUrl: "ws://default/ws",
+          authToken: "default-token",
+          accounts: { sales: { wsUrl: "ws://sales/ws" } },
+        },
+      },
+    };
+    const acct = xiayouPlugin.config.resolveAccount(cfg, "unknown");
+    expect(acct.wsUrl).toBe("ws://default/ws");
+  });
+});
+
+describe("inspectAccount", () => {
+  it("reports configured", () => {
+    const r = xiayouPlugin.config.inspectAccount(fullCfg, undefined);
+    expect(r.enabled).toBe(true);
+    expect(r.configured).toBe(true);
+    expect(r.tokenStatus).toBe("available");
+  });
+
+  it("reports not configured", () => {
+    const r = xiayouPlugin.config.inspectAccount({ channels: {} }, undefined);
+    expect(r.enabled).toBe(false);
+    expect(r.configured).toBe(false);
+  });
+});
+
+describe("listAccounts", () => {
+  it("returns default when no accounts section", () => {
+    expect(xiayouPlugin.config.listAccounts(fullCfg)).toEqual(["default"]);
+  });
+
+  it("returns account keys", () => {
+    const cfg = {
+      channels: {
+        xiaoyou: {
+          wsUrl: "ws://x",
+          accounts: { a: {}, b: {} },
+        },
+      },
+    };
+    expect(xiayouPlugin.config.listAccounts(cfg)).toEqual(["a", "b"]);
+  });
+
+  it("returns empty when not configured", () => {
+    expect(xiayouPlugin.config.listAccounts({ channels: {} })).toEqual([]);
+  });
+});
+
+describe("capabilities", () => {
+  it("declares correct feature set", () => {
+    const c = xiayouPlugin.capabilities;
+    expect(c.media).toBe(true);
+    expect(c.reply).toBe(true);
+    expect(c.edit).toBe(false);
+    expect(c.polls).toBe(false);
+    expect(c.reactions).toBe(false);
+  });
+});
+
+describe("status adapter", () => {
+  it("reports issues when not connected", async () => {
+    const s = await xiayouPlugin.status.describe({
+      account: { accountId: "default", wsUrl: "ws://x", authToken: "t" },
+    });
+    expect(s.summary).toBe("error");
+    expect(s.issues.some((i: any) => i.message.includes("not connected"))).toBe(true);
+  });
+
+  it("reports wsUrl missing", async () => {
+    const s = await xiayouPlugin.status.describe({ account: { accountId: "default" } });
+    expect(s.issues.some((i: any) => i.message.includes("wsUrl"))).toBe(true);
+  });
+});