@xgjktech/xg_cwork_im 1.0.0

package/README.md

@@ -0,0 +1,284 @@
+# XG CWork IM Channel for OpenClaw
+
+小橙工作台 IM 机器人 Channel 插件，通过 WebSocket 长连接接收 `@` 消息，由 OpenClaw AI 处理后自动回复。
+
+## 工作原理
+
+```
+IM 系统  →  WebSocket  →  插件（本项目）  →  OpenClaw AI  →  IM 发送接口  →  IM 系统
+```
+
+1. 插件启动时用 `appKey` 换取 `access_token` 和 `userId`
+2. 建立 WebSocket 长连接，接收 `robotMention` 事件
+3. 将收到的消息转发给 OpenClaw 处理
+4. OpenClaw AI 回复后，插件调用 IM 接口发送消息并 `@` 原始发送者
+
+---
+
+## 前置条件
+
+- 已安装 [OpenClaw](https://github.com/openclaw) (`>=2026.2.13`)
+- 已在 IM 后台注册机器人，获取到 `appKey`
+
+---
+
+## 安装
+
+### 方法 A：通过 npm 包安装（推荐）
+
+一条命令完成安装，依赖由 OpenClaw 自动处理：
+
+```bash
+openclaw plugins install @xgjktech/xg_cwork_im
+```
+
+运行 `openclaw plugins list` 确认列表中有 `xg_cwork_im` 即可。
+
+### 方法 B：通过本地源码安装
+
+如需二次开发或无法使用 npm 安装时，可克隆后以链接模式安装：
+
+```bash
+git clone https://github.com/cwei001/openclaw-channel-xg-cwork-im.git
+cd openclaw-channel-xg-cwork-im
+npm install
+openclaw plugins install -l .
+```
+
+### 方法 C：手动安装
+
+1. 将本仓库下载或复制到 `~/.openclaw/extensions/xg_cwork_im`（Windows 为 `%USERPROFILE%\.openclaw\extensions\xg_cwork_im`）。
+2. 确保目录内包含 `index.ts`、`openclaw.plugin.json`、`package.json`。
+3. 在该目录执行 `npm install --omit=dev` 或 `npm run install:prod` 安装依赖。
+4. 运行 `openclaw plugins list` 确认 `xg_cwork_im` 已显示。
+
+### 方法 D：国内网络环境（npm 镜像源）
+
+若执行 `openclaw plugins install @xgjktech/xg_cwork_im` 时卡在「Installing plugin dependencies...」或出现 `npm install failed`，可临时指定国内镜像源：
+
+```bash
+NPM_CONFIG_REGISTRY=https://registry.npmmirror.com openclaw plugins install @xgjktech/xg_cwork_im
+```
+
+若插件已半安装（扩展目录存在但依赖未装全），可进入插件目录手动补装：
+
+```bash
+cd ~/.openclaw/extensions/xg_cwork_im
+# Windows: cd %USERPROFILE%\.openclaw\extensions\xg_cwork_im
+rm -rf node_modules package-lock.json
+NPM_CONFIG_REGISTRY=https://registry.npmmirror.com npm install
+```
+
+---
+
+## 配置
+
+### 步骤 1：启用并信任插件
+
+执行以下命令，将 `xg_cwork_im` 插件添加到 OpenClaw 的信任白名单中：
+
+```bash
+openclaw plugins enable xg_cwork_im
+```
+
+### 步骤 2：配置 Channel 账户信息
+
+编辑 `~/.openclaw/openclaw.json`，添加以下配置：
+
+```json
+{
+  "channels": {
+    "xg_cwork_im": {
+      "baseUrl": "https://cwork-web-test.xgjktech.com.cn",
+      "wsBaseUrl": "wss://cwork-web-test.xgjktech.com.cn",
+      "accounts": [
+        { "appKey": "你的机器人 appKey", "agentId": "main", "name": "个人助手" }
+      ]
+    }
+  }
+}
+```
+
+> **多账户**：如有多个机器人，在 `accounts` 数组里继续追加即可，每个账户可指定不同的 `agentId` 对应不同的 OpenClaw Agent。
+
+### 步骤 3：重启 Gateway
+
+配置完成后，重启网关使配置生效：
+
+```bash
+openclaw gateway restart
+```
+
+---
+
+## 完整配置参考
+
+`~/.openclaw/openclaw.json` 参考结构（示例使用 CWork 测试/生产域名，详细请参考 `docs/im服务接口说明.md`）：
+
+```json5
+{
+  "plugins": {
+    "enabled": true,
+    "allow": ["xg_cwork_im"]
+  },
+  "channels": {
+    "xg_cwork_im": {
+      "baseUrl": "https://cwork-web-test.xgjktech.com.cn",
+      "wsBaseUrl": "wss://cwork-web-test.xgjktech.com.cn",
+      "groupPolicy": "mention",
+      "debug": false,
+      "accounts": [
+        { "appKey": "appKey_机器人A", "agentId": "main",  "name": "个人助手" },
+        { "appKey": "appKey_机器人B", "agentId": "sales", "name": "销售助手" }
+      ]
+    }
+  }
+}
+```
+
+### 生产环境配置示例
+
+```json5
+{
+  "channels": {
+    "xg_cwork_im": {
+      "baseUrl": "https://sg-al-cwork-web.mediportal.com.cn",
+      "wsBaseUrl": "wss://sg-al-cwork-web.mediportal.com.cn",
+      "groupPolicy": "mention",
+      "debug": false,
+      "maxConnectionAttempts": 20,
+      "maxReconnectDelay": 120000,
+      "accounts": [
+        { "appKey": "你的生产 appKey", "agentId": "main", "name": "个人助手" }
+      ]
+    }
+  }
+}
+```
+
+---
+
+## 配置项说明
+
+### 顶层配置（`channels.xg_cwork_im`）
+
+| 选项 | 类型 | 默认值 | 说明 |
+|---|---|---|---|
+| `baseUrl` | string | **必填** | IM 服务域名（API 接口地址） |
+| `wsBaseUrl` | string | — | **可选**。WebSocket 独立域名。若不填，插件将尝试自动映射。 |
+| `groupPolicy` | string | `"mention"` | `open`=收全部消息；`mention`=仅 @ 机器人触发 |
+| `enabled` | boolean | `true` | 是否启用 |
+| `debug` | boolean | `false` | 开启调试日志 |
+| `maxConnectionAttempts` | number | `10` | WebSocket 最大重连次数 |
+| `initialReconnectDelay` | number | `1000` | 初始重连延迟（ms） |
+| `maxReconnectDelay` | number | `60000` | 最大重连延迟（ms） |
+| `reconnectJitter` | number | `0.3` | 重连抖动因子（0-1） |
+
+### 账户配置（`accounts[n]`）
+
+| 选项 | 类型 | 默认值 | 说明 |
+|---|---|---|---|
+| `appKey` | string | **必填** | 机器人 appKey（IM 后台注册获取） |
+| `agentId` | string | `"main"` | 对应的 OpenClaw Agent ID |
+| `name` | string | — | 账户显示名称（仅用于日志标识） |
+| `groupPolicy` | string | 继承顶层 | 可覆盖顶层的 groupPolicy |
+
+---
+
+## 故障排除
+
+### 收不到消息
+- 确认 `appKey` 正确，且机器人已在 IM 后台激活
+- 查看 OpenClaw 日志，确认 WebSocket 连接成功（`WebSocket connected successfully`）
+- 群聊中确认已 `@` 机器人
+
+### WebSocket 频繁断连
+- 检查网络稳定性
+- 适当增大 `maxConnectionAttempts` 和 `maxReconnectDelay`
+- 开启 `debug: true` 查看详细日志
+
+### token 相关报错
+- 确认 `baseUrl` 域名可达
+- 确认 `appKey` 有效（可在 IM 后台查看机器人状态）
+
+---
+
+## 项目结构
+
+```
+openclaw-channel-xg-cwork-im/
+├── index.ts                # 插件入口
+├── src/
+│   ├── types.ts            # 类型定义
+│   ├── auth.ts             # 认证（appKey → token）
+│   ├── connection.ts       # WebSocket 连接管理
+│   ├── send-service.ts     # IM 消息发送
+│   ├── group-history-tool.ts      # 拉取群消息历史的 Agent Tool
+│   └── channel.ts          # Channel Plugin 主定义
+├── package.json
+├── tsconfig.json
+├── openclaw.plugin.json
+└── README.md
+```
+
+---
+
+## 维护者：发布到 npm
+
+本插件包名为 `@xgjktech/xg_cwork_im`（scoped 包）。按以下步骤发布到 npm 后，同事即可用 `openclaw plugins install @xgjktech/xg_cwork_im` 安装。
+
+### 1. 注册 / 登录 npm
+
+- 无账号：打开 [https://www.npmjs.com/signup](https://www.npmjs.com/signup) 注册。
+- 已有账号：在项目根目录执行：
+
+```bash
+npm login
+```
+
+按提示输入 Username、Password、Email 及一次性验证码（若开启 2FA）。
+
+### 2. 确认 scope 权限
+
+包名是 `@xgjktech/xg_cwork_im`，表示属于 **scope** `@xgjktech`。两种方式二选一：
+
+- **使用 npm 组织**：在 [npm 官网](https://www.npmjs.com/) 登录 → Organizations → Create → 创建名为 `xgjktech` 的组织，并把你的账号加入。
+- **使用个人 scope**：若你希望包名是个人 scope（如 `@你的用户名/xg_cwork_im`），需把 `package.json` 里的 `"name"` 改成 `@你的用户名/xg_cwork_im`，并同步修改 README 中的安装命令。
+
+### 3. 发布前检查
+
+在仓库根目录执行：
+
+```bash
+# 查看将要随包发布的文件（与 package.json 的 "files" 一致）
+npm pack --dry-run
+```
+
+确认没有敏感文件（如 `.env`、密钥）。`package.json` 里已通过 `"files"` 指定只发布必要文件。
+
+### 4. 执行发布
+
+**scoped 包首次发布必须加 `--access public`**，否则会变成付费的私有包：
+
+```bash
+npm publish --access public
+```
+
+发布成功后可在 [https://www.npmjs.com/package/@xgjktech/xg_cwork_im](https://www.npmjs.com/package/@xgjktech/xg_cwork_im) 查看。
+
+### 5. 后续更新
+
+修改代码后，先在 `package.json` 里把 `version` 提高（如 `1.0.0` → `1.0.1`），再执行：
+
+```bash
+npm publish --access public
+```
+
+（若该 scope 下此前已发布过公开包，可只执行 `npm publish`。）
+
+### 常见问题
+
+- **403 Forbidden**：当前账号无 `@xgjktech` 的发布权限，需在 npm 上创建/加入组织，或将包名改为你的个人 scope。
+- **402 Payment Required**：未加 `--access public`，scoped 包被当成私有包，需改为 `npm publish --access public`。
+- **国内网络**：可临时使用镜像登录与发布（不推荐长期用镜像发布）：  
+  `npm login --registry=https://registry.npmjs.org/`，发布时仍用默认 registry 或 `--registry=https://registry.npmjs.org/`。

package/index.ts

@@ -0,0 +1,33 @@
+/**
+ * XG-IM Channel Plugin for OpenClaw
+ *
+ * 插件入口：注册 XG-IM channel，并注入 PluginRuntime 供消息路由使用
+ */
+
+import type { OpenClawPluginApi } from "openclaw/plugin-sdk";
+import { emptyPluginConfigSchema } from "openclaw/plugin-sdk";
+import { setXgImRuntime, xgCworkImChannelPlugin } from "./src/channel.js";
+import { buildGroupHistoryTool, extractXgCworkImConfig } from "./src/group-history-tool.js";
+import { buildSendGroupMessageTool } from "./src/send-group-message-tool.js";
+import type { XgCworkImPluginModule } from "./src/types.js";
+
+const plugin: XgCworkImPluginModule = {
+    id: "xg_cwork_im",
+    name: "XG CWork IM Channel",
+    description: "小橙工作台 IM 机器人 Channel 插件，通过 WebSocket 长连接接入",
+    configSchema: emptyPluginConfigSchema(),
+    register(api: OpenClawPluginApi): void {
+        setXgImRuntime(api.runtime);
+        api.registerChannel({ plugin: xgCworkImChannelPlugin });
+        // 注册 AI 工具（静态工具对象，确保 toolNames 正确注册）
+        const cworkConfig = extractXgCworkImConfig(api.config);
+        if (cworkConfig) {
+            api.registerTool(buildGroupHistoryTool(cworkConfig));
+            api.registerTool(buildSendGroupMessageTool(cworkConfig));
+        } else {
+            console.warn("[xg_cwork_im] channel config not found, skipping tool registration");
+        }
+    },
+};
+
+export default plugin;

package/openclaw.plugin.json

@@ -0,0 +1,11 @@
+{
+    "id": "xg_cwork_im",
+    "channels": [
+        "xg_cwork_im"
+    ],
+    "configSchema": {
+        "type": "object",
+        "additionalProperties": true,
+        "properties": {}
+    }
+}

package/package.json

@@ -0,0 +1,63 @@
+{
+  "name": "@xgjktech/xg_cwork_im",
+  "version": "1.0.0",
+  "description": "XG CWork IM channel plugin for OpenClaw",
+  "keywords": [
+    "bot",
+    "channel",
+    "openclaw",
+    "xgim",
+    "im"
+  ],
+  "license": "MIT",
+  "type": "module",
+  "main": "index.ts",
+  "files": [
+    ".npmrc",
+    "index.ts",
+    "src/*.ts",
+    "openclaw.plugin.json"
+  ],
+  "scripts": {
+    "type-check": "tsc -p tsconfig.json --noEmit",
+    "lint": "tsc -p tsconfig.json --noEmit",
+    "install:prod": "npm install --omit=dev"
+  },
+  "dependencies": {
+    "axios": "^1.6.0",
+    "ws": "^8.17.0",
+    "zod": "^3.22.0"
+  },
+  "devDependencies": {
+    "@types/node": "^20.0.0",
+    "@types/ws": "^8.5.10",
+    "typescript": "^5.3.0"
+  },
+  "peerDependencies": {
+    "openclaw": ">=2026.2.13"
+  },
+  "openclaw": {
+    "extensions": [
+      "./index.ts"
+    ],
+    "channels": [
+      "xg_cwork_im"
+    ],
+    "installDependencies": false,
+    "channel": {
+      "id": "xg_cwork_im",
+      "label": "XG CWork IM",
+      "selectionLabel": "XG CWork IM (小橙工作台)",
+      "blurb": "小橙工作台 IM 机器人 Channel 插件，通过 WebSocket 长连接接收消息。",
+      "aliases": [
+        "xg_cwork_im",
+        "xgim",
+        "im"
+      ]
+    },
+    "install": {
+      "localPath": ".",
+      "defaultChoice": "local"
+    }
+  }
+}

package/src/auth.ts

@@ -0,0 +1,79 @@
+/**
+ * XG-IM 认证模块
+ *
+ * 通过 appKey 换取 access_token 和机器人 userId。
+ * token 有效期一年，启动时获取一次并缓存，无需定期刷新。
+ */
+
+import axios from "axios";
+import type { BotIdentity, GetTokenResponse, XgImConfig } from "./types.js";
+
+export type Log = {
+    info: (msg: string) => void;
+    warn?: (msg: string) => void;
+    error: (msg: string) => void;
+    debug?: (msg: string) => void;
+};
+
+/** 运行时 token 缓存，按 appKey 索引 */
+const tokenCache = new Map<string, BotIdentity>();
+
+/**
+ * 通过 appKey 获取机器人身份信息（token + userId）。
+ * 若缓存中已有有效 token，直接返回缓存；否则请求接口。
+ *
+ * @param config  插件配置
+ * @param log     日志接口
+ * @param force   强制重新获取（忽略缓存）
+ */
+export async function getToken(
+    config: XgImConfig,
+    log?: Log,
+    force = false,
+): Promise<BotIdentity> {
+    if (!config.appKey) {
+        throw new Error("[cwork_im] appKey is required");
+    }
+    const cacheKey = `${config.baseUrl}:${config.appKey}`;
+
+    if (!force) {
+        const cached = tokenCache.get(cacheKey);
+        if (cached) {
+            log?.info?.(`[cwork_im] Using cached token for appKey=${config.appKey}`);
+            return cached;
+        }
+    }
+
+    const url = `${config.baseUrl}/user/login/appkey?appKey=${encodeURIComponent(config.appKey)}&appCode=im`;
+    log?.info(`[cwork_im:auth] GET ${url} appKey=${config.appKey}`);
+
+    const response = await axios.get<GetTokenResponse>(url, {
+        headers: { "Content-Type": "application/json" },
+        timeout: 10_000,
+    });
+
+    const body = response.data;
+    log?.info(`[cwork_im:auth] Response status=${response.status} resultCode=${body?.resultCode ?? "n/a"}`);
+    if (!body?.data?.xgToken || !body?.data?.empId) {
+        throw new Error(
+            `[cwork_im] getToken failed: unexpected response — ${JSON.stringify(body)}`,
+        );
+    }
+
+    const identity: BotIdentity = {
+        token: body.data.xgToken,
+        userId: body.data.empId,
+        name: body.data.userName ?? "bot",
+    };
+
+    tokenCache.set(cacheKey, identity);
+    log?.info(`[cwork_im:auth] Token acquired: userId=${identity.userId} name=${identity.name} appKey=${config.appKey}`);
+
+    return identity;
+}
+
+/** 清除指定账户的 token 缓存（用于重连时强制重新鉴权） */
+export function clearTokenCache(config: XgImConfig): void {
+    const cacheKey = `${config.baseUrl}:${config.appKey}`;
+    tokenCache.delete(cacheKey);
+}