@wecom/wecom-openclaw-plugin 2026.3.20-beta.1 → 2026.3.20-beta.4

package/dist/src/mcp/transport.d.ts

@@ -9,6 +9,8 @@
  * - SSE 流式响应解析
  * - MCP 配置运行时缓存（通过 WSClient 拉取 URL 并缓存在内存中）
  */
+/** 媒体下载请求超时时间（毫秒），base64 编码的媒体文件最大可达 ~27MB */
+export declare const MEDIA_DOWNLOAD_TIMEOUT_MS = 120000;
 /**
  * MCP JSON-RPC 错误
  *
@@ -44,6 +46,11 @@ export interface McpToolInfo {
     description?: string;
     inputSchema?: Record<string, unknown>;
 }
+/** sendJsonRpc 的可选配置 */
+export interface SendJsonRpcOptions {
+    /** 自定义 HTTP 请求超时时间（毫秒），默认使用 HTTP_REQUEST_TIMEOUT_MS */
+    timeoutMs?: number;
+}
 /**
  * 发送 JSON-RPC 请求到 MCP Server（Streamable HTTP 协议）
  *
@@ -54,6 +61,7 @@ export interface McpToolInfo {
  * @param category - MCP 品类名称
  * @param method - JSON-RPC 方法名
  * @param params - JSON-RPC 参数
+ * @param options - 可选配置（如自定义超时）
  * @returns JSON-RPC result
  */
-export declare function sendJsonRpc(category: string, method: string, params?: Record<string, unknown>): Promise<unknown>;
+export declare function sendJsonRpc(category: string, method: string, params?: Record<string, unknown>, options?: SendJsonRpcOptions): Promise<unknown>;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@wecom/wecom-openclaw-plugin",
-  "version": "2026.3.20-beta.1",
+  "version": "2026.3.20-beta.4",
   "type": "module",
   "main": "dist/index.cjs.js",
   "module": "dist/index.esm.js",

package/skills/wecom-msg/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: wecom-msg
-description: 企业微信消息技能。提供会话列表查询、消息记录拉取和文本消息发送能力。当用户需要"查看消息"、"看聊天记录"、"发消息给某人"、"最近有什么消息"、"给群里发消息"时触发。
+description: 企业微信消息技能。提供会话列表查询、消息记录拉取（支持文本/图片/文件/语音/视频）、多媒体文件获取和文本消息发送能力。当用户需要"查看消息"、"看聊天记录"、"发消息给某人"、"最近有什么消息"、"给群里发消息"、"看看发了什么图片/文件"时触发。
 metadata:
   {
     "openclaw": { "emoji": "💬" },
@@ -29,7 +29,13 @@ metadata:
 
 使用 `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)。
+根据会话类型和 ID 拉取指定时间范围内的消息记录，支持分页。支持 text/image/file/voice/video 消息类型，仅支持 7 天内。参见 [API 详情](references/api-get-messages.md)。
+
+### get_msg_media — 获取消息文件内容
+
+使用 `wecom_mcp` tool 调用 `wecom_mcp call msg get_msg_media '{"media_id": "MEDIAID_xxxxxx"}'`
+
+根据文件 ID 自动下载文件到本地，返回文件的本地路径（`local_path`）、名称、类型、大小及 MIME 类型。用于获取图片、文件、语音、视频等非文本消息的实际内容。参见 [API 详情](references/api-get-msg-media.md)。
 
 ### send_message — 发送文本消息
 
@@ -90,8 +96,33 @@ metadata:
 2. 通过 **chatid查找规则** 确定目标会话的 `chatid` 和 `chat_type`
 3. 调用 `get_messages` 拉取消息列表
 4. 调用 `wecom-contact-lookup` 的 `get_userlist` 获取通讯录，建立 userid→姓名 映射
-5. 展示消息时将 `userid` 替换为可读姓名，格式：`姓名 [时间]: 内容`
-6. 若 `next_cursor` 不为空，告知用户还有更多消息可继续查看
+5. **统计非文本消息**：遍历消息列表，统计 `msgtype` 非 `text` 的消息（image/file/voice/video）数量和类型
+6. 展示消息时将 `userid` 替换为可读姓名，格式：
+   - 文本消息：`姓名 [时间]: 内容`
+   - 图片消息：`姓名 [时间]:[图片]`
+   - 文件消息：`姓名 [时间]:[文件] 文件名称`
+   - 语音消息：`姓名 [时间]:[语音] 语音内容`
+   - 视频消息：`姓名 [时间]:[视频]`
+7. **非文本消息处理**：展示完消息后，如果存在非文本消息：
+   - **主动询问是否下载**：告知用户非文本消息数量和类型（如："以上聊天中包含 2 张图片、1 个文件，是否需要下载到本地？"）
+   - 用户确认后，逐个调用 `get_msg_media` 接口，接口会自动下载文件并返回 `local_path`
+   - **检查文件后缀**：每个文件下载完成后，检查 `local_path` 对应的文件是否具有正确的后缀名：
+     - 根据 `get_msg_media` 返回的 `content_type`（MIME 类型）和 `name` 字段判断：
+       - 如果文件名缺少后缀（如 `screenshot` 而非 `screenshot.png`），根据 `content_type` 自动补上正确后缀（如 `image/png` → `.png`，`application/pdf` → `.pdf`，`audio/amr` → `.amr`，`video/mp4` → `.mp4`）
+       - 如果文件名后缀与 `content_type` 不一致，以 `content_type` 为准进行修正
+     - 补全或修正后缀后，将文件重命名为正确的文件名
+     - 确认文件可正常读取（文件大小 > 0），若文件为空或损坏则告知用户该文件下载异常
+   - ⚠️ **不要对下载的文件使用 `MEDIA:` 指令**：这些文件是从聊天记录中下载的历史附件，仅需告知用户本地存放路径即可，**严禁**通过 `MEDIA:` 指令重新发送给用户
+   - ⚠️ **必须主动告知文件位置**（此步骤不可省略）：所有文件下载并检查完成后，**必须立即、主动**以汇总形式向用户展示文件存放目录和每个文件的完整路径，不要等用户询问。示例：
+     > 📁 文件已下载到以下位置：
+     > - 图片：`/tmp/wecom_media/screenshot.png`
+     > - 文件：`/tmp/wecom_media/report.pdf`
+     >
+     > 你可以在 `/tmp/wecom_media/` 目录下找到所有下载的文件。
+   - ⚠️**询问是否删除**（此步骤不可省略）：告知文件位置后，**必须立即、主动**询问用户是否需要删除已下载的临时文件（如："如果不再需要这些文件，是否需要我帮你清理？"）
+     - 用户确认删除后，删除 `local_path` 对应的文件
+     - 用户不需要删除则保留文件
+8. 若 `next_cursor` 不为空，告知用户还有更多消息可继续查看
 
 ### 发送消息
 **用户query示例**：

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

@@ -1,6 +1,6 @@
 # get_messages API
 
-根据会话类型和会话 ID，拉取指定时间范围内的消息记录。目前仅支持文本类型消息。
+根据会话类型和会话 ID，拉取指定时间范围内的消息记录。支持文本、图片、文件、语音、视频类型消息。
 
 ## 参数说明
 
@@ -30,14 +30,25 @@
 
 | 字段 | 类型 | 说明 |
 |------|------|------|
-| `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 | 分页游标，为空表示已拉取完毕 |
+| `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`-文本消息，`image`-图片消息，`file`-文件消息，`voice`-语音消息，`video`-视频消息 |
+| `messages[].text` | Object | 文本消息内容，`msgtype` 为 `text` 时返回 |
+| `messages[].text.content` | String | 消息内容 |
+| `messages[].image` | Object | 图片消息内容，`msgtype` 为 `image` 时返回 |
+| `messages[].image.media_id` | String | 图片的 media_id，可通过 `get_msg_media` 接口下载 |
+| `messages[].image.name` | String | 图片文件名称 |
+| `messages[].file` | Object | 文件消息内容，`msgtype` 为 `file` 时返回 |
+| `messages[].file.media_id` | String | 文件的 media_id，可通过 `get_msg_media` 接口下载 |
+| `messages[].file.name` | String | 文件名称 |
+| `messages[].voice` | Object | 语音消息内容，`msgtype` 为 `voice` 时返回 |
+| `messages[].voice.media_id` | String | 语音的 media_id，可通过 `get_msg_media` 接口下载 |
+| `messages[].video` | Object | 视频消息内容，`msgtype` 为 `video` 时返回 |
+| `messages[].video.media_id` | String | 视频的 media_id，可通过 `get_msg_media` 接口下载 |
+| `next_cursor` | String | 分页游标，为空表示已拉取完毕 |
 
 ## 响应示例
 
@@ -57,12 +68,26 @@
         {
             "userid": "lisi",
             "send_time": "2026-03-17 09:35:00",
-            "msgtype": "text",
-            "text": {
-                "content": "你好，有什么可以帮助你的？"
+            "msgtype": "image",
+            "image": {
+                "media_id": "MEDIAID_xxxxxx",
+                "name": "screenshot.png"
+            }
+        },
+        {
+            "userid": "zhangsan",
+            "send_time": "2026-03-17 09:40:00",
+            "msgtype": "file",
+            "file": {
+                "media_id": "MEDIAID_yyyyyy",
+                "name": "report.pdf"
             }
         }
     ],
     "next_cursor": "CURSOR_xxxxxx"
 }
 ```
+
+## 非文本消息处理
+
+当 `msgtype` 为 `image`、`file`、`voice`、`video` 时，消息体中包含 `media_id`。需要调用 [get_msg_media](api-get-msg-media.md) 接口获取文件的本地路径（`local_path`），再进行展示。

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

@@ -0,0 +1,44 @@
+# get_msg_media API
+
+获取消息文件内容。根据文件 ID 自动下载文件到本地，返回本地文件路径、文件名称、类型、大小及内容类型。
+
+## 参数说明
+
+| 参数 | 类型 | 必填 | 说明 |
+|------|------|------|------|
+| `media_id` | string | ✅ | 文件 ID，长度 1~256 |
+
+## 请求示例
+
+使用 `wecom_mcp` tool 调用 `wecom_mcp call msg get_msg_media '{"media_id": "MEDIAID_xxxxxx"}'`
+
+## 返回字段
+
+| 字段 | 类型 | 说明 |
+|------|------|------|
+| `errcode` | Integer | 返回码，`0` 表示成功 |
+| `errmsg` | String | 错误信息 |
+| `media_item` | Object | 文件内容 |
+| `media_item.media_id` | String | 文件 ID |
+| `media_item.name` | String | 文件名称 |
+| `media_item.type` | String | 文件类型，`image`-图片，`voice`-语音，`video`-视频，`file`-普通文件 |
+| `media_item.local_path` | String | 文件下载后的本地路径 |
+| `media_item.size` | Integer | 文件大小（字节） |
+| `media_item.content_type` | String | 文件 MIME 类型，如 `image/png`、`application/pdf` 等 |
+
+## 响应示例
+
+```json
+{
+    "errcode": 0,
+    "errmsg": "ok",
+    "media_item": {
+        "media_id": "MEDIAID_xxxxxx",
+        "name": "screenshot.png",
+        "type": "image",
+        "local_path": "/tmp/wecom_media/screenshot.png",
+        "size": 102400,
+        "content_type": "image/png"
+    }
+}
+```

package/skills/wecom-send-media/SKILL.md

@@ -43,9 +43,7 @@ MEDIA: <文件的绝对路径>
 | 语音 | 2 MB | **仅支持 AMR 格式**（`.amr`） |
 | 文件 | 20 MB | 不限 |
 
-⚠️ 重要：请务必**先检查文件大小和格式**是否满足要求再使用 `MEDIA:` 指令。如果不满足要求，请主动告知用户。
-
-## 降级与限制处理
+⚠️ 重要：请务必**先检查文件大小和格式**是否满足要求。如果不满足要求，请主动告知用户以下”降级与限制处理“措施：
 
 - **自动降级**：当图片、视频或语音超过各自的大小限制时，系统会自动将其转为文件消息发送，请主动告诉用户。
 - **硬性上限**：文件大小超过 20 MB 时无法发送。请主动告知用户，并尝试压缩或拆分文件后再发送。