@wecom/wecom-openclaw-plugin 1.0.12 → 1.0.13-beta.1

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",
+  "version": "1.0.13-beta.1",
   "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,120 @@
+---
+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` 格式
+- **默认范围**：用户未指定时，默认使用最近7天（当前时间往前推7天）
+- **限制**：开始时间不能早于当前时间的7天前，不能晚于当前时间
+- **相对时间支持**：支持"昨天"、"最近三天"等自动推算
+
+### chatid查找规则
+- 当用户提供人名或群名而非ID时：
+  1. 调用 `get_msg_chat_list` 获取会话列表
+  2. 在 `chats` 中按 `chat_name` 匹配
+  3. **匹配策略**：
+     - 精确匹配唯一结果：直接使用
+     - 模糊匹配多个结果：展示候选列表让用户选择
+     - 无匹配结果：告知用户未找到
+
+### userid转username
+**流程**：
+1. 调用 `wecom-contact-lookup get_userlist` 获取用户列表
+2. 建立userid到username的映射关系
+3. **展示策略**：
+   - 精确匹配：显示username
+   - 无匹配：保持显示userid
+
+---
+
+## 典型工作流
+
+### 查看会话列表
+**用户query示例**：
+- "看看我最近一周有哪些聊天"
+- "这几天谁给我发过消息"
+
+**执行流程**：
+1. 确定时间范围（用户指定或默认7天）
+2. 验证时间参数有效性
+3. 调用 `get_msg_chat_list`
+4. 展示会话信息
+5. 分页提示（如有更多数据）
+
+### 查看聊天记录
+**用户query示例**：
+- "帮我看看和张三最近的聊天记录"
+- "看看项目群里最近的消息"
+
+**执行流程**：
+1. 通过chatid查找规则确定目标会话
+2. 确定时间范围
+3. 查询user name映射关系
+4. 调用 `get_messages` 拉取消息
+5. 展示消息（userid转username，链接处理）
+6. 分页提示
+
+### 发送消息
+**用户query示例**：
+- "帮我给张三发一条消息：明天会议改到下午3点"
+- "在项目群里发一条消息：今天下午3点开会"
+
+**执行流程**：
+1. 通过chatid查找规则确定目标会话
+2. 直接调用 `send_message` 发送
+3. 展示发送结果
+
+### 查看消息并回复
+**用户query示例**：
+- "看看张三给我发了什么，然后帮我回复收到"
+
+**执行流程**：
+1. 先执行"查看聊天记录"流程
+2. 再执行"发送消息"流程
+
+---
+
+## 错误处理
+- **时间范围超限**：告知用户7天限制并调整为有效范围
+- **会话未找到**：明确告知用户未找到对应会话
+- **API错误**：展示具体错误信息，必要时重试
+- **网络问题**：HTTP错误时主动重试最多3次

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"
+}
+```