@xgjktech/xg_cwork_im 1.0.8 → 1.0.9

package/README.md

@@ -1,360 +1,367 @@
-# 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 回复后，插件：
-   - 先通过 WebSocket `START` 让 IM 端显示一条「思考中」占位消息；
-   - 当 AI 产出第一条完整回复时，用 HTTP `/im/message/send` 覆盖这条占位消息；
-   - 若有多条回复，则后续每条都通过 HTTP 作为**独立消息**发送；
-   - 首条回复若在配置的超时时间内一直未产生，会自动将占位消息更新为「当前请求处理超时，请稍后重试」。
-
----
-
-## 前置条件
-
-- 已安装 [OpenClaw](https://github.com/openclaw) (`>=2026.2.13`)
-- 已在 IM 后台注册机器人，获取到 `appKey`
-
----
-
-## 安装
-
-推荐同事通过 **npm** 安装，无需访问内部 Git；需要改源码时再从内部仓库克隆（方法 B）。
-
-### 方法 A：通过 npm 包安装（推荐）
-
-一条命令完成安装，依赖由 OpenClaw 自动处理：
-
-```bash
-openclaw plugins install @xgjktech/xg_cwork_im
-```
-
-运行 `openclaw plugins list` 确认列表中有 `xg_cwork_im` 即可。
-
-### 方法 B：通过本地源码安装
-
-如需二次开发或无法使用 npm 安装时，可从内部 Git 克隆后以链接模式安装：
-
-```bash
-git clone http://192.168.3.200/openclaw/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
-```
-
----
-
-## 更新已安装的插件
-
-当插件发布新版本后，已安装的用户可按以下方式更新。
-
-### 通过 npm 安装的（方法 A）
-
-使用**插件 id**（不是 npm 包名）执行更新：
-
-```bash
-openclaw plugins update xg_cwork_im
-```
-
-更新完成后执行 `openclaw gateway restart` 使新版本生效。
-
-国内网络可临时指定镜像源后再更新：
-
-```bash
-NPM_CONFIG_REGISTRY=https://registry.npmmirror.com openclaw plugins update xg_cwork_im
-```
-
-### 通过本地源码 / 链接安装的（方法 B）
-
-在插件目录拉取最新代码后重启网关：
-
-```bash
-cd openclaw-channel-xg-cwork-im   # 进入当时克隆的目录
-git pull
-npm install
-openclaw gateway restart
-```
-
-### 手动安装的（方法 C）
-
-重新从内部 Git 下载或复制最新代码到 `~/.openclaw/extensions/xg_cwork_im`，在该目录执行 `npm install --omit=dev` 或 `npm run install:prod`，再执行 `openclaw gateway restart`。
-
----
-
-## 配置
-
-### 步骤 1：启用并信任插件
-
-执行以下命令，将 `xg_cwork_im` 插件添加到 OpenClaw 的信任白名单中：
-
-```bash
-openclaw plugins enable xg_cwork_im
-```
-
-### 步骤 2：配置 Channel 账户信息
-
-编辑 `~/.openclaw/openclaw.json`，添加以下配置（推荐 `accounts` 使用对象 map，key 即 `accountId`）：
-
-```json
-{
-  "channels": {
-    "xg_cwork_im": {
-      "baseUrl": "https://cwork-web-test.xgjktech.com.cn",
-      "wsBaseUrl": "wss://cwork-web-test.xgjktech.com.cn",
-      "accounts": {
-        "main": { "appKey": "你的机器人 appKey", "agentId": "main", "name": "个人助手" }
-      }
-    }
-  }
-}
-```
-
-> **多账户**：如有多个机器人，在 `accounts` 中继续追加即可（对象 map：key 为 `accountId`）。每个账户可指定不同的 `agentId` 对应不同的 OpenClaw Agent。
-
-> **accounts.default（可选）**：OpenClaw 的 `doctor --fix` 可能会自动生成 `accounts.default`，用于存放默认项（例如 `groupPolicy` 等）。本插件会把 `accounts.default` 作为“默认覆盖”合并到每个真实账号上，但 **不会**把它当作一个需要启动连接的账号。
-
-### 步骤 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,
-      // 可选：首条 AI 回复超时时间（毫秒），默认 30 分钟
-      // 未配置时：30 * 60_000 = 1800000
-      "firstReplyTimeoutMs": 1800000,
-      "accounts": {
-        "main": { "appKey": "appKey_机器人A", "agentId": "main",  "name": "个人助手" },
-        "sales": { "appKey": "appKey_机器人B", "agentId": "sales", "name": "销售助手" }
-      }
-    }
-  },
-  "bindings": [
-    { "type": "route", "agentId": "main", "match": { "channel": "xg_cwork_im", "accountId": "main" } },
-    { "type": "route", "agentId": "sales", "match": { "channel": "xg_cwork_im", "accountId": "sales" } }
-  ]
-}
-```
-
-### 生产环境配置示例
-
-```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": 200,
-      "maxReconnectDelay": 120000,
-      // 生产环境可根据需要调整首回复超时时间（毫秒）
-      "firstReplyTimeoutMs": 300000,
-      "accounts": {
-        "main": { "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） |
-| `firstReplyTimeoutMs` | number | `300000` | **首条 AI 回复超时时间（毫秒）**。用于保护「思考中」占位消息：若在该时间窗口内 AI 没有任何回复，则自动将占位消息更新为「当前请求处理超时，请稍后重试」。|
-
-### 账户配置（`accounts.<accountId>` / `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
-│   ├── send-group-message-tool.ts # 发送群消息的 Agent Tool
-│   └── channel.ts          # Channel Plugin 主定义
-├── package.json
-├── tsconfig.json
-├── openclaw.plugin.json
-└── README.md
-```
-
----
-
-## 代码仓库与发布流程说明
-
-- **代码仓库**：本项目在**内部 Git** 管理，地址：`http://192.168.3.200/openclaw/openclaw-channel-xg-cwork-im`，不推送到 GitHub。
-- **安装方式**：同事安装请优先使用 **npm**（方法 A）；需要改源码时从内部 Git 克隆（方法 B）。
-- **发布流程**：在内部 Git 上开发、提交后，由维护者**发布到 npm**；同事通过 `openclaw plugins install @xgjktech/xg_cwork_im` 安装，无需访问 Git。
-
----
-
-## 维护者：如何发布到 npm（详细步骤）
-
-代码在内部 Git 上维护，发布到 npm 后同事即可一条命令安装。按下列步骤操作。
-
-### 步骤 1：在 npm 注册 / 登录
-
-1. 无 npm 账号：打开 [https://www.npmjs.com/signup](https://www.npmjs.com/signup) 注册。
-2. 在项目根目录执行：
-
-```bash
-npm login
-```
-
-3. 按提示输入 **Username**、**Password**、**Email**。
-4. 若账号开启了**双因素认证（2FA）**，发布时必须使用：
-   - 在 npm 网站 **Access Tokens** 里创建 **Granular Access Token**，勾选 **Publish packages**，并勾选 **Bypass 2FA**；或  
-   - 在命令行登录时使用 **OTP**（一次性密码）。  
-   否则会报错：`Two-factor authentication or granular access token with bypass 2fa enabled is required to publish packages`。
-
-### 步骤 2：确认 scope 与权限
-
-- 包名为 `@xgjktech/xg_cwork_im`，属于 **scope** `@xgjktech`。
-- 在 [npm 官网](https://www.npmjs.com/) 登录 → **Organizations** → **Create**，创建组织名为 **xgjktech**，确保你的账号有该组织的发布权限。
-- 若改用个人 scope（如 `@你的用户名/xg_cwork_im`），需修改 `package.json` 的 `"name"` 并同步改 README 中的安装命令。
-
-### 步骤 3：发布前检查
-
-在项目根目录执行：
-
-```bash
-npm pack --dry-run
-```
-
-确认列出的文件无敏感内容（如 `.env`、密钥）。发布内容由 `package.json` 的 `"files"` 控制。
-
-### 步骤 4：执行发布
-
-**scoped 包必须加 `--access public`**，否则会按私有包计费并可能报 402：
-
-```bash
-npm publish --access public
-```
-
-成功后可在此查看：  
-[https://www.npmjs.com/package/@xgjktech/xg_cwork_im](https://www.npmjs.com/package/@xgjktech/xg_cwork_im)
-
-### 步骤 5：后续更新（重新推送到 npm）
-
-每次发新版本都按下面做一遍即可：
-
-1. 在内部 Git 上改代码、提交、推送。
-2. 在 **package.json** 里把 **version** 升高（如 `1.0.0` → `1.0.1`），保存。
-3. 在项目根目录执行：
-
-```bash
-npm publish --access public
-```
-
-4. 通知同事执行 **更新已安装的插件**（见上文「更新已安装的插件」），例如：  
-   `openclaw plugins update xg_cwork_im` → `openclaw gateway restart`。
-
-（若该 scope 已发过公开包，有时可只执行 `npm publish`，建议仍带 `--access public` 避免误发成私有。）
-
-### 常见问题
-
-| 报错或现象 | 原因 | 处理 |
-|-----------|------|------|
-| **403 Forbidden**，且提示需 2FA 或 token | 账号开启 2FA 后，普通登录无法发布 | 使用 **Granular Access Token**（勾选 Publish + Bypass 2FA），或在发布时提供 OTP |
-| **403 Forbidden**，无 2FA 提示 | 当前账号无 `@xgjktech` 发布权限 | 在 npm 创建/加入组织 `xgjktech`，或将包名改为个人 scope |
-| **402 Payment Required** | 未加 `--access public`，scoped 包被视为私有 | 执行 `npm publish --access public` |
-| 国内网络登录/发布慢或超时 | 默认 registry 在国外 | 登录：`npm login --registry=https://registry.npmjs.org/`；发布时也可加 `--registry=https://registry.npmjs.org/`，不推荐长期用第三方镜像发布 |
+# 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 回复后，插件：
+   - 先通过 WebSocket `START` 让 IM 端显示一条「思考中」占位消息；
+   - 当 AI 产出第一条完整回复时，用 HTTP `/im/message/send` 覆盖这条占位消息；
+   - 若有多条回复，则后续每条都通过 HTTP 作为**独立消息**发送；
+   - 首条回复若在配置的超时时间内一直未产生，会自动将占位消息更新为「当前请求处理超时，请稍后重试」。
+
+---
+
+## 前置条件
+
+- 已安装 [OpenClaw](https://github.com/openclaw) (`>=2026.2.13`)
+- 已在 IM 后台注册机器人，获取到 `appKey`
+
+---
+
+## 安装
+
+推荐同事通过 **npm** 安装，无需访问内部 Git；需要改源码时再从内部仓库克隆（方法 B）。
+
+### 方法 A：通过 npm 包安装（推荐）
+
+一条命令完成安装，依赖由 OpenClaw 自动处理：
+
+```bash
+openclaw plugins install @xgjktech/xg_cwork_im
+```
+
+运行 `openclaw plugins list` 确认列表中有 `xg_cwork_im` 即可。
+
+### 方法 B：通过本地源码安装
+
+如需二次开发或无法使用 npm 安装时，可从内部 Git 克隆后以链接模式安装：
+
+```bash
+git clone http://192.168.3.200/openclaw/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
+```
+
+---
+
+## 更新已安装的插件
+
+当插件发布新版本后，已安装的用户可按以下方式更新。
+
+### 通过 npm 安装的（方法 A）
+
+使用**插件 id**（不是 npm 包名）执行更新：
+
+```bash
+openclaw plugins update xg_cwork_im
+```
+
+更新完成后执行 `openclaw gateway restart` 使新版本生效。
+
+国内网络可临时指定镜像源后再更新：
+
+```bash
+NPM_CONFIG_REGISTRY=https://registry.npmmirror.com openclaw plugins update xg_cwork_im
+```
+
+### 通过本地源码 / 链接安装的（方法 B）
+
+在插件目录拉取最新代码后重启网关：
+
+```bash
+cd openclaw-channel-xg-cwork-im   # 进入当时克隆的目录
+git pull
+npm install
+openclaw gateway restart
+```
+
+### 手动安装的（方法 C）
+
+重新从内部 Git 下载或复制最新代码到 `~/.openclaw/extensions/xg_cwork_im`，在该目录执行 `npm install --omit=dev` 或 `npm run install:prod`，再执行 `openclaw gateway restart`。
+
+---
+
+## 配置
+
+### 步骤 1：启用并信任插件
+
+执行以下命令，将 `xg_cwork_im` 插件添加到 OpenClaw 的信任白名单中：
+
+```bash
+openclaw plugins enable xg_cwork_im
+```
+
+### 步骤 2：配置 Channel 账户信息
+
+编辑 `~/.openclaw/openclaw.json`，添加以下配置（推荐 `accounts` 使用对象 map，key 即 `accountId`）：
+
+```json
+{
+  "channels": {
+    "xg_cwork_im": {
+      "baseUrl": "https://cwork-web-test.xgjktech.com.cn",
+      "wsBaseUrl": "wss://cwork-web-test.xgjktech.com.cn",
+      "accounts": {
+        "main": { "appKey": "你的机器人 appKey", "agentId": "main", "name": "个人助手" }
+      }
+    }
+  }
+}
+```
+
+> **多账户**：如有多个机器人，在 `accounts` 中继续追加即可（对象 map：key 为 `accountId`）。每个账户可指定不同的 `agentId` 对应不同的 OpenClaw Agent。
+
+> **accounts.default（可选）**：OpenClaw 的 `doctor --fix` 可能会自动生成 `accounts.default`，用于存放默认项（例如 `groupPolicy` 等）。本插件会把 `accounts.default` 作为“默认覆盖”合并到每个真实账号上，但 **不会**把它当作一个需要启动连接的账号。
+
+### 步骤 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,
+      // 可选：首条 AI 回复超时时间（毫秒），默认 30 分钟
+      // 未配置时：30 * 60_000 = 1800000
+      "firstReplyTimeoutMs": 1800000,
+      // 可选：入站附件先下载到当前 Agent workspace 下该子目录，再以 file:// 交给 OpenClaw
+      "inboundMediaWorkspaceSubdir": "xg_im_inbound",
+      "accounts": {
+        "main": { "appKey": "appKey_机器人A", "agentId": "main",  "name": "个人助手" },
+        "sales": { "appKey": "appKey_机器人B", "agentId": "sales", "name": "销售助手" }
+      }
+    }
+  },
+  "bindings": [
+    { "type": "route", "agentId": "main", "match": { "channel": "xg_cwork_im", "accountId": "main" } },
+    { "type": "route", "agentId": "sales", "match": { "channel": "xg_cwork_im", "accountId": "sales" } }
+  ]
+}
+```
+
+### 生产环境配置示例
+
+```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": 200,
+      "maxReconnectDelay": 120000,
+      // 生产环境可根据需要调整首回复超时时间（毫秒）
+      "firstReplyTimeoutMs": 300000,
+      // 按需启用：入站附件落盘到 workspace，见配置表 inboundMediaWorkspaceSubdir
+      // "inboundMediaWorkspaceSubdir": "xg_im_inbound",
+      "accounts": {
+        "main": { "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） |
+| `firstReplyTimeoutMs` | number | `300000` | **首条 AI 回复超时时间（毫秒）**。用于保护「思考中」占位消息：若在该时间窗口内 AI 没有任何回复，则自动将占位消息更新为「当前请求处理超时，请稍后重试」。|
+| `inboundMediaWorkspaceSubdir` | string | — | **可选**。非空时，将入站附件先下载到**当前 Agent workspace** 下该**相对子目录**（如 `xg_im_inbound`），路径约定：`{子目录}/{发送者 userId}/{YYYY-MM-DD}/{文件名}_{HHmmssmmm}.ext`（时间为本机写入时刻），再向 OpenClaw 传入本地 `file://` 路径；未配置则仍使用 IM 返回的 URL。需 OpenClaw runtime 提供 `resolveAgentWorkspaceDir`。 |
+
+### 账户配置（`accounts.<accountId>` / `accounts[n]`）
+
+| 选项 | 类型 | 默认值 | 说明 |
+|---|---|---|---|
+| `appKey` | string | **必填** | 机器人 appKey（IM 后台注册获取） |
+| `agentId` | string | `"main"` | 对应的 OpenClaw Agent ID |
+| `name` | string | — | 账户显示名称（仅用于日志标识） |
+| `groupPolicy` | string | 继承顶层 | 可覆盖顶层的 groupPolicy |
+| `inboundMediaWorkspaceSubdir` | string | 继承顶层 | 可覆盖顶层的入站附件落盘子目录 |
+
+---
+
+## 故障排除
+
+### 收不到消息
+- 确认 `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
+│   ├── send-group-message-tool.ts # 发送群消息的 Agent Tool
+│   ├── inbound-media-local.ts   # 可选：入站附件落盘到 workspace 子目录
+│   └── channel.ts          # Channel Plugin 主定义
+├── package.json
+├── tsconfig.json
+├── openclaw.plugin.json
+└── README.md
+```
+
+---
+
+## 代码仓库与发布流程说明
+
+- **代码仓库**：本项目在**内部 Git** 管理，地址：`http://192.168.3.200/openclaw/openclaw-channel-xg-cwork-im`，不推送到 GitHub。
+- **安装方式**：同事安装请优先使用 **npm**（方法 A）；需要改源码时从内部 Git 克隆（方法 B）。
+- **发布流程**：在内部 Git 上开发、提交后，由维护者**发布到 npm**；同事通过 `openclaw plugins install @xgjktech/xg_cwork_im` 安装，无需访问 Git。
+
+---
+
+## 维护者：如何发布到 npm（详细步骤）
+
+代码在内部 Git 上维护，发布到 npm 后同事即可一条命令安装。按下列步骤操作。
+
+### 步骤 1：在 npm 注册 / 登录
+
+1. 无 npm 账号：打开 [https://www.npmjs.com/signup](https://www.npmjs.com/signup) 注册。
+2. 在项目根目录执行：
+
+```bash
+npm login
+```
+
+3. 按提示输入 **Username**、**Password**、**Email**。
+4. 若账号开启了**双因素认证（2FA）**，发布时必须使用：
+   - 在 npm 网站 **Access Tokens** 里创建 **Granular Access Token**，勾选 **Publish packages**，并勾选 **Bypass 2FA**；或  
+   - 在命令行登录时使用 **OTP**（一次性密码）。  
+   否则会报错：`Two-factor authentication or granular access token with bypass 2fa enabled is required to publish packages`。
+
+### 步骤 2：确认 scope 与权限
+
+- 包名为 `@xgjktech/xg_cwork_im`，属于 **scope** `@xgjktech`。
+- 在 [npm 官网](https://www.npmjs.com/) 登录 → **Organizations** → **Create**，创建组织名为 **xgjktech**，确保你的账号有该组织的发布权限。
+- 若改用个人 scope（如 `@你的用户名/xg_cwork_im`），需修改 `package.json` 的 `"name"` 并同步改 README 中的安装命令。
+
+### 步骤 3：发布前检查
+
+在项目根目录执行：
+
+```bash
+npm pack --dry-run
+```
+
+确认列出的文件无敏感内容（如 `.env`、密钥）。发布内容由 `package.json` 的 `"files"` 控制。
+
+### 步骤 4：执行发布
+
+**scoped 包必须加 `--access public`**，否则会按私有包计费并可能报 402：
+
+```bash
+npm publish --access public
+```
+
+成功后可在此查看：  
+[https://www.npmjs.com/package/@xgjktech/xg_cwork_im](https://www.npmjs.com/package/@xgjktech/xg_cwork_im)
+
+### 步骤 5：后续更新（重新推送到 npm）
+
+每次发新版本都按下面做一遍即可：
+
+1. 在内部 Git 上改代码、提交、推送。
+2. 在 **package.json** 里把 **version** 升高（如 `1.0.0` → `1.0.1`），保存。
+3. 在项目根目录执行：
+
+```bash
+npm publish --access public
+```
+
+4. 通知同事执行 **更新已安装的插件**（见上文「更新已安装的插件」），例如：  
+   `openclaw plugins update xg_cwork_im` → `openclaw gateway restart`。
+
+（若该 scope 已发过公开包，有时可只执行 `npm publish`，建议仍带 `--access public` 避免误发成私有。）
+
+### 常见问题
+
+| 报错或现象 | 原因 | 处理 |
+|-----------|------|------|
+| **403 Forbidden**，且提示需 2FA 或 token | 账号开启 2FA 后，普通登录无法发布 | 使用 **Granular Access Token**（勾选 Publish + Bypass 2FA），或在发布时提供 OTP |
+| **403 Forbidden**，无 2FA 提示 | 当前账号无 `@xgjktech` 发布权限 | 在 npm 创建/加入组织 `xgjktech`，或将包名改为个人 scope |
+| **402 Payment Required** | 未加 `--access public`，scoped 包被视为私有 | 执行 `npm publish --access public` |
+| 国内网络登录/发布慢或超时 | 默认 registry 在国外 | 登录：`npm login --registry=https://registry.npmjs.org/`；发布时也可加 `--registry=https://registry.npmjs.org/`，不推荐长期用第三方镜像发布 |