@wecom/wecom-openclaw-plugin 1.0.12-beta.3 → 1.0.13-beta.0

package/dist/src/const.d.ts

@@ -62,3 +62,9 @@ export declare const FILE_MAX_BYTES: number;
 export declare const ABSOLUTE_MAX_BYTES: number;
 /** 上传分片大小（字节，Base64 编码前）：512KB */
 export declare const UPLOAD_CHUNK_SIZE: number;
+/** 版本检查事件名称（SDK 事件监听用） */
+export declare const EVENT_ENTER_CHECK_UPDATE = "event.enter_check_update";
+/** 版本检查事件回复命令名称 */
+export declare const CMD_ENTER_EVENT_REPLY = "ww_ai_robot_enter_event";
+/** WSClient scene 参数：企微 OpenClaw 场景 */
+export declare const SCENE_WECOM_OPENCLAW = 1;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@wecom/wecom-openclaw-plugin",
-  "version": "1.0.12-beta.3",
+  "version": "1.0.13-beta.0",
   "type": "module",
   "main": "dist/index.cjs.js",
   "module": "dist/index.esm.js",
@@ -57,6 +57,6 @@
   },
   "dependencies": {
     "file-type": "^21.3.0",
-    "@wecom/aibot-node-sdk": "^1.0.2"
+    "@wecom/aibot-node-sdk": "^1.0.3-beta.3"
   }
 }

package/skills/wecom-msg/SKILL.md

@@ -0,0 +1,109 @@
+---
+name: wecom-msg
+description: 企业微信消息技能。提供会话列表查询、消息记录拉取和文本消息发送能力。当用户需要"查看消息"、"看聊天记录"、"发消息给某人"、"最近有什么消息"、"给群里发消息"时触发。
+metadata:
+  {
+    "openclaw": { "emoji": "💬" },
+  }
+---
+
+# 企业微信消息技能
+
+> `wecom_mcp` 是一个 MCP tool，所有操作通过调用该 tool 完成。
+
+> ⚠️ **前置条件**：首次调用 `wecom_mcp` 前，必须按 `wecom-preflight` 技能执行前置条件检查，确保工具已加入白名单。
+
+通过 `wecom_mcp call msg <接口名> '<json入参>'` 与企业微信消息系统交互。
+
+---
+
+## 接口列表
+
+### get_msg_chat_list — 获取会话列表
+
+使用 `wecom_mcp` tool 调用 `wecom_mcp call msg get_msg_chat_list '{"begin_time": "2026-03-11 00:00:00", "end_time": "2026-03-17 23:59:59"}'`
+
+按时间范围查询有消息的会话列表，支持分页。参见 [API 详情](references/api-get-msg-chat-list.md)。
+
+### get_messages — 拉取会话消息
+
+使用 `wecom_mcp` tool 调用 `wecom_mcp call msg get_messages '{"chat_type": 1, "chatid": "zhangsan", "begin_time": "2026-03-17 09:00:00", "end_time": "2026-03-17 18:00:00"}'`
+
+根据会话类型和 ID 拉取指定时间范围内的消息记录，支持分页。仅支持 7 天内。参见 [API 详情](references/api-get-messages.md)。
+
+### send_message — 发送文本消息
+
+使用 `wecom_mcp` tool 调用 `wecom_mcp call msg send_message '{"chat_type": 1, "chatid": "zhangsan", "msgtype": "text", "text": {"content": "hello world"}}'`
+
+向单聊或群聊发送文本消息。参见 [API 详情](references/api-send-message.md)。
+
+
+## 注意事项
+
+- 所有时间参数使用 `YYYY-MM-DD HH:mm:ss` 格式；用户说"昨天"、"最近一周"等相对时间时，根据当前日期推算
+- `get_messages` 仅支持拉取请求时刻往前 **7 天**内的消息，超出需告知用户此限制
+- 目前仅支持**文本**消息的拉取和发送；用户要求发送图片、文件等需告知不支持
+- 发送消息内容最大 **2048 字节**
+- 会话类型：`1`-单聊（`chatid` 为对方 userid），`2`-群聊（`chatid` 为群 ID）
+- **chatid 查找规则**：当用户提供的是人名或群名而非 ID 时，先调用 `get_msg_chat_list` 拉取会话列表，然后在返回的 `chats` 中按 `chat_name` 进行本地筛选匹配，获取对应的 `chat_id` 作为 `chatid`。匹配策略参照：精确匹配直接使用；模糊匹配到多个结果时展示候选列表让用户选择；无匹配时告知用户未找到
+- **发送消息前必须向用户确认**发送对象和消息内容，防止误发
+- 分页响应中 `has_more` 为 `true` 或 `next_cursor` 不为空时，**必须告知用户还有更多数据**，询问是否继续查看
+- `errcode != 0` 时展示 `errmsg` 中的错误信息；遇 HTTP 错误时主动重试，最多 3 次
+
+---
+
+## 典型工作流
+
+### 查看会话列表
+
+**经典 query 示例：**
+- "看看我最近一周有哪些聊天"
+- "这几天谁给我发过消息"
+- "最近有哪些群聊活跃"
+
+**流程：**
+1. 根据用户意图计算时间范围（如"最近一周"→近 7 天）
+2. 调用 `get_msg_chat_list` 获取会话列表
+3. 展示会话名称、最后消息时间、消息数量等信息
+4. 若 `has_more` 为 `true`，告知用户还有更多并询问是否继续
+
+### 查看聊天记录
+
+**经典 query 示例：**
+- "帮我看看和张三最近的聊天记录"
+- "看看项目群里最近的消息"
+- "我和李四昨天聊了什么"
+
+**流程：**
+1. **确定 chatid**：调用 `get_msg_chat_list` 拉取会话列表，在 `chats` 中按 `chat_name` 匹配用户提供的人名/群名，获取 `chat_id`
+   - 精确匹配到唯一结果：直接使用
+   - 模糊匹配到多个结果：展示候选列表，让用户选择
+   - 无匹配结果：告知用户未找到对应会话
+2. 根据会话类型设置 `chat_type`（单聊=`1`，群聊=`2`），调用 `get_messages` 拉取消息列表
+3. 展示发送者、时间和消息内容；若 `next_cursor` 不为空，告知用户还有更多消息
+
+### 发送消息
+
+**经典 query 示例：**
+- "帮我给张三发一条消息：明天会议改到下午3点"
+- "在项目群里发一条消息：今天下午3点开会"
+- "给李四回复：收到，谢谢"
+
+**流程：**
+1. **确定 chatid**：调用 `get_msg_chat_list` 拉取会话列表，在 `chats` 中按 `chat_name` 匹配用户提供的人名/群名，获取 `chat_id`
+   - 精确匹配到唯一结果：直接使用
+   - 模糊匹配到多个结果：展示候选列表，让用户选择
+   - 无匹配结果：告知用户未找到对应会话
+2. **确认发送**：向用户确认发送对象和内容（如："即将向 张三 发送：'明天会议改到下午3点'，确认发送吗？"）
+3. 用户确认后调用 `send_message` 发送
+4. 展示发送结果
+
+### 查看消息并回复
+
+**经典 query 示例：**
+- "看看张三给我发了什么，然后帮我回复收到"
+- "查看项目群消息，然后回复一下"
+
+**流程：**
+1. 先按"查看聊天记录"流程拉取并展示消息
+2. 再按"发送消息"流程确认并发送回复

package/skills/wecom-msg/references/api-get-messages.md

@@ -0,0 +1,68 @@
+# get_messages API
+
+根据会话类型和会话 ID，拉取指定时间范围内的消息记录。目前仅支持文本类型消息。
+
+## 参数说明
+
+| 参数 | 类型 | 必填 | 说明 |
+|------|------|------|------|
+| `chat_type` | integer | ✅ | 会话类型，`1`-单聊，`2`-群聊 |
+| `chatid` | string | ✅ | 会话 ID，单聊时为 userid，群聊时为群 ID，最大 256 字节 |
+| `begin_time` | string | ✅ | 拉取开始时间，格式：`YYYY-MM-DD HH:mm:ss`，仅支持请求时刻往前 **7 天**内 |
+| `end_time` | string | ✅ | 拉取结束时间，格式：`YYYY-MM-DD HH:mm:ss`，必须 ≥ `begin_time` |
+| `cursor` | string | ❌ | 分页游标，首次请求不传，后续传入上次响应的 `next_cursor`，最大 256 字节 |
+
+## 请求示例
+
+单聊：
+
+使用 `wecom_mcp` tool 调用 `wecom_mcp call msg get_messages '{"chat_type": 1, "chatid": "zhangsan", "begin_time": "2026-03-17 09:00:00", "end_time": "2026-03-17 18:00:00"}'`
+
+群聊：
+
+使用 `wecom_mcp` tool 调用 `wecom_mcp call msg get_messages '{"chat_type": 2, "chatid": "wrxxxxxxxx", "begin_time": "2026-03-17 09:00:00", "end_time": "2026-03-17 18:00:00"}'`
+
+分页请求：
+
+使用 `wecom_mcp` tool 调用 `wecom_mcp call msg get_messages '{"chat_type": 1, "chatid": "zhangsan", "begin_time": "2026-03-17 09:00:00", "end_time": "2026-03-17 18:00:00", "cursor": "CURSOR_xxxxxx"}'`
+
+## 返回字段
+
+| 字段 | 类型 | 说明 |
+|------|------|------|
+| `errcode` | integer | 返回码，`0` 表示成功 |
+| `errmsg` | string | 错误信息 |
+| `messages` | array | 消息列表 |
+| `messages[].userid` | string | 消息发送者的 userid |
+| `messages[].send_time` | string | 发送时间，格式：`YYYY-MM-DD HH:mm:ss` |
+| `messages[].msgtype` | string | 消息类型，目前仅支持 `text` |
+| `messages[].text.content` | string | 消息内容 |
+| `next_cursor` | string | 分页游标，为空表示已拉取完毕 |
+
+## 响应示例
+
+```json
+{
+    "errcode": 0,
+    "errmsg": "ok",
+    "messages": [
+        {
+            "userid": "zhangsan",
+            "send_time": "2026-03-17 09:30:00",
+            "msgtype": "text",
+            "text": {
+                "content": "你好"
+            }
+        },
+        {
+            "userid": "lisi",
+            "send_time": "2026-03-17 09:35:00",
+            "msgtype": "text",
+            "text": {
+                "content": "你好，有什么可以帮助你的？"
+            }
+        }
+    ],
+    "next_cursor": "CURSOR_xxxxxx"
+}
+```

package/skills/wecom-msg/references/api-get-msg-chat-list.md

@@ -0,0 +1,58 @@
+# get_msg_chat_list API
+
+获取指定时间范围内有消息的会话列表，支持分页查询。
+
+## 参数说明
+
+| 参数 | 类型 | 必填 | 说明 |
+|------|------|------|------|
+| `begin_time` | string | ✅ | 拉取开始时间，格式：`YYYY-MM-DD HH:mm:ss` |
+| `end_time` | string | ✅ | 拉取结束时间，格式：`YYYY-MM-DD HH:mm:ss` |
+| `cursor` | string | ❌ | 分页游标，首次请求不传，后续传入上次响应的 `next_cursor`，最大长度 256 |
+
+## 请求示例
+
+使用 `wecom_mcp` tool 调用 `wecom_mcp call msg get_msg_chat_list '{"begin_time": "2026-03-11 00:00:00", "end_time": "2026-03-17 23:59:59"}'`
+
+分页请求：
+
+使用 `wecom_mcp` tool 调用 `wecom_mcp call msg get_msg_chat_list '{"begin_time": "2026-03-11 00:00:00", "end_time": "2026-03-17 23:59:59", "cursor": "NEXT_CURSOR"}'`
+
+## 返回字段
+
+| 字段 | 类型 | 说明 |
+|------|------|------|
+| `errcode` | integer | 返回码，`0` 表示成功 |
+| `errmsg` | string | 错误信息 |
+| `chats` | array | 会话列表 |
+| `chats[].chat_id` | string | 会话 ID |
+| `chats[].chat_name` | string | 会话名称 |
+| `chats[].last_msg_time` | string | 最后一条消息时间，格式：`YYYY-MM-DD HH:mm:ss` |
+| `chats[].msg_count` | integer | 消息数量 |
+| `has_more` | boolean | 是否还有更多数据 |
+| `next_cursor` | string | 分页游标，用于下一次请求 |
+
+## 响应示例
+
+```json
+{
+    "errcode": 0,
+    "errmsg": "ok",
+    "chats": [
+        {
+            "chat_id": "CHAT_ID",
+            "chat_name": "张三",
+            "last_msg_time": "2026-03-17 15:30:45",
+            "msg_count": 128
+        },
+        {
+            "chat_id": "CHAT_ID_2",
+            "chat_name": "项目讨论群",
+            "last_msg_time": "2026-03-16 09:12:33",
+            "msg_count": 56
+        }
+    ],
+    "has_more": true,
+    "next_cursor": "NEXT_CURSOR"
+}
+```

package/skills/wecom-msg/references/api-send-message.md

@@ -0,0 +1,39 @@
+# send_message API
+
+向单聊或群聊发送文本消息。
+
+## 参数说明
+
+| 参数 | 类型 | 必填 | 说明 |
+|------|------|------|------|
+| `chat_type` | integer | ✅ | 会话类型，`1`-单聊，`2`-群聊 |
+| `chatid` | string | ✅ | 会话 ID，单聊时为 userid，群聊时为群 ID，最大 256 字节 |
+| `msgtype` | string | ✅ | 消息类型，目前仅支持 `text` |
+| `text` | object | ✅ | 文本消息内容 |
+| `text.content` | string | ✅ | 消息内容，最大 2048 字节 |
+
+## 请求示例
+
+单聊：
+
+使用 `wecom_mcp` tool 调用 `wecom_mcp call msg send_message '{"chat_type": 1, "chatid": "zhangsan", "msgtype": "text", "text": {"content": "hello world"}}'`
+
+群聊：
+
+使用 `wecom_mcp` tool 调用 `wecom_mcp call msg send_message '{"chat_type": 2, "chatid": "wrxxxxxxxx", "msgtype": "text", "text": {"content": "大家好"}}'`
+
+## 返回字段
+
+| 字段 | 类型 | 说明 |
+|------|------|------|
+| `errcode` | integer | 返回码，`0` 表示成功 |
+| `errmsg` | string | 错误信息 |
+
+## 响应示例
+
+```json
+{
+    "errcode": 0,
+    "errmsg": "ok"
+}
+```