@mocrane/wecom 2026.3.14 → 2026.3.20

package/README.md

@@ -1,17 +1,10 @@
 # OpenClaw 企业微信（WeCom）Channel 插件
 
-> [!WARNING]
-> **OpenClaw 3.1+ 升级必读**：升级到 OpenClaw `3.1` 及以上版本的用户务必同步升级本插件，并将企业微信回调 URL 更新为 OpenClaw 推荐路径：`/plugins/wecom/bot/{accountId}` 与 `/plugins/wecom/agent/{accountId}`（旧 `/wecom/*` 仍兼容但不再维护）。
-
 <p align="center">
-  <img src="https://img.shields.io/badge/Original%20Project-YanHaidao-orange?style=for-the-badge&logo=github" alt="Original Project" />
+  <a href="https://github.com/TencentCloud-Lighthouse/openclaw-wecom"><img src="https://img.shields.io/badge/GitHub-TencentCloud--Lighthouse%2Fwecom-blue?style=for-the-badge&logo=github" alt="GitHub Repo" /></a>
   <img src="https://img.shields.io/badge/License-ISC-blue?style=for-the-badge" alt="License" />
 </p>
 
-> [!WARNING]
-> **原创声明**：本项目涉及的“多账号隔离与矩阵路由架构”、“Bot+Agent双模融合架构”、“长任务超时接力逻辑”及“全自动媒体流转接”等核心设计均为作者 **YanHaidao** 独立思考与实践的原创成果。
-> 欢迎技术交流与合规引用，但**严禁任何不经授权的“功能像素级抄袭”或删除原作者署名的代码搬运行为**。
-
 <p align="center">
   <strong>🚀 企业级双模式 AI 助手接入方案</strong>
 </p>
@@ -477,10 +470,6 @@ Agent 输出 `{"template_card": ...}` 时自动渲染为交互卡片：
 
 ## 七、📮 联系我
 
-微信交流群（扫码入群）：
-
-![企业微信交流群](https://openclaw.cc/wechat-openclaw-cn-qr.jpg)
-
 维护者：mocrane
 
 ---
@@ -500,7 +489,22 @@ Agent 输出 `{"template_card": ...}` 时自动渲染为交互卡片：
 <a id="sec-10"></a>
 ## 八、📝 更新日志
 
-### 2026.3.3（今日更新简报）
+### 2026.3.19
+
+- 【多媒体发送】📎 **机器人富媒体发送**：Bot 支持向用户发送文件、图片、视频，补齐发送侧多模态能力。
+- 【MCP 集成】🧩 **企业级 MCP 工具接入**：群聊与私聊中支持调用日程、待办、通讯录 MCP，实现对话式办公协作。
+
+### 2026.3.15
+
+- 【文档能力】📄 **企微文档操作支持**：新增企业微信文档读写操作能力，可在对话中直接操作企微文档。
+- 【交互体验】⌨️ **打字机效果**：支持逐字流式输出的打字机效果，提升对话交互体验。
+
+### 2026.3.8
+
+- 【长连接】🔗 **Bot 长连接模式**：企微机器人支持长连接（WebSocket）模式，降低延迟、提升连接稳定性。
+- 【主动触达】📤 **长连接模式主动发送**：长连接模式下 Bot 支持主动向用户发送消息，突破传统被动回复限制。
+
+### 2026.3.3
 
 - 【SDK适配】♻️ **插件 HTTP 注册升级**：入口改为 `registerHttpRoute`（`/plugins/wecom` + `match=prefix` + `auth=plugin`），适配 OpenClaw 新版插件接口。
 - 【兼容修复】🔁 **旧入口保持可达**：同步注册 `/wecom` 前缀路由，保障历史 Bot/Agent 回调地址继续可用。

package/index.ts

@@ -4,6 +4,7 @@ import { emptyPluginConfigSchema } from "openclaw/plugin-sdk";
 import { handleWecomWebhookRequest } from "./src/monitor.js";
 import { setWecomRuntime } from "./src/runtime.js";
 import { wecomPlugin } from "./src/channel.js";
+import { createWeComMcpTool } from "./src/mcp/index.js";
 
 const plugin = {
   id: "wecom",
@@ -17,6 +18,8 @@ const plugin = {
    * 1. 注入 Runtime 环境 (api.runtime)。
    * 2. 注册 WeCom 渠道插件 (ChannelPlugin)。
    * 3. 注册 Webhook HTTP 路由（推荐 /plugins/wecom/*，兼容 /wecom*）。
+   * 4. 注册 wecom_mcp 工具 (MCP Streamable HTTP 调用)。
+   * 5. 注入 MEDIA 指令提示词（仅 wecom 通道），指导 LLM 使用 MEDIA: 语法发送文件。
    */
   register(api: OpenClawPluginApi) {
     setWecomRuntime(api.runtime);
@@ -30,6 +33,40 @@ const plugin = {
         match: "prefix",
       });
     }
+
+    // 注册 wecom_mcp：通过 HTTP 直接调用企业微信 MCP Server
+    api.registerTool(createWeComMcpTool(), { name: "wecom_mcp" });
+
+    // 注入媒体发送指令和文件大小限制提示词（与官方 @wecom/wecom-openclaw-plugin 保持一致）。
+    // 仅 wecom 通道注入，避免影响其他通道。
+    // deliver 回调中保留兜底正则解析，作为双重保障。
+    api.on("before_prompt_build", (_event, ctx) => {
+      if (ctx.channelId !== "wecom") return;
+      return {
+        prependContext: [
+          "【发送文件/图片/视频/语音】",
+          "当你需要向用户发送文件、图片、视频或语音时，必须在回复中单独一行使用 MEDIA: 指令，后面跟文件的本地路径。",
+          "格式：MEDIA: /文件的绝对路径",
+          "文件优先存放到 ~/.openclaw 目录下，确保路径可访问。",
+          "示例：",
+          "  MEDIA: ~/.openclaw/output.png",
+          "  MEDIA: ~/.openclaw/report.pdf",
+          "系统会自动识别文件类型并发送给用户。",
+          "",
+          "注意事项：",
+          "- MEDIA: 必须在行首，后面紧跟文件路径（不是 URL）",
+          "- 如果路径中包含空格，可以用反引号包裹：MEDIA: `/path/to/my file.png`",
+          "- 每个文件单独一行 MEDIA: 指令",
+          "- 可以在 MEDIA: 指令前后附带文字说明",
+          "",
+          "【文件大小限制】",
+          "- 图片不超过 10MB，视频不超过 10MB，语音不超过 2MB（仅支持 AMR 格式），文件不超过 20MB",
+          "- 语音消息仅支持 AMR 格式（.amr），如需发送语音请确保文件为 AMR 格式",
+          "- 超过大小限制的图片/视频/语音会被自动转为文件格式发送",
+          "- 如果文件超过 20MB，将无法发送，请提前告知用户并尝试缩减文件大小",
+        ].join("\n"),
+      };
+    });
   },
 };
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mocrane/wecom",
-  "version": "2026.3.14",
+  "version": "2026.3.20",
   "type": "module",
   "description": "OpenClaw WeCom (WeChat Work) intelligent bot channel plugin",
   "main": "index.ts",
@@ -43,7 +43,7 @@
     }
   },
   "dependencies": {
-    "@wecom/aibot-node-sdk": "^1.0.0",
+    "@wecom/aibot-node-sdk": "^1.0.2",
     "fast-xml-parser": "5.3.4",
     "file-type": "^18.7.0",
     "undici": "^7.20.0",
@@ -54,7 +54,8 @@
   },
   "devDependencies": {
     "@types/node": "^25.2.0",
-    "typescript": "^5.9.3"
+    "typescript": "^5.9.3",
+    "vitest": "^4.1.0"
   },
   "clawdbot": {
     "extensions": [

package/skills/wecom-contact-lookup/SKILL.md

@@ -0,0 +1,162 @@
+---
+name: wecom-contact-lookup
+description: 通讯录成员查询技能，基于 MCP tool 协议封装的 `get_userlist` 接口，获取当前用户可见范围内的通讯录成员，支持按姓名/别名本地筛选匹配。返回 userid、姓名和别名。⚠️ 仅返回当前用户有权限查看的成员，非全量成员。
+---
+
+# 通讯录成员查询技能
+
+> `wecom_mcp` 是一个 MCP tool，所有操作通过调用该 tool 完成。
+
+> ⚠️ **前置条件**：首次调用 `wecom_mcp` 前，必须按 `wecom-preflight` 技能执行前置条件检查，确保工具已加入白名单。
+
+通过 MCP tool 协议封装的 `get_userlist` 接口，获取当前用户可见范围内的通讯录成员，并在本地按姓名/别名进行筛选匹配。
+
+## 操作
+
+### 1. 获取全量通讯录成员
+
+获取当前用户可见范围内的所有企业成员信息：
+
+**调用示例：**
+
+使用 `wecom_mcp` tool 调用 `wecom_mcp call contact get_userlist '{}'`
+
+**返回格式：**
+
+```json
+{
+    "errcode": 0,
+    "errmsg": "ok",
+    "userlist": [
+        {
+            "userid": "zhangsan",
+            "name": "张三",
+            "alias": "Sam"
+        },
+        {
+            "userid": "lisi",
+            "name": "李四",
+            "alias": ""
+        }
+    ]
+}
+```
+
+**返回字段说明：**
+
+| 字段 | 类型 | 说明 |
+|------|------|------|
+| `errcode` | integer | 返回码，`0` 表示成功 |
+| `errmsg` | string | 错误信息 |
+| `userlist` | array | 用户列表 |
+| `userlist[].userid` | string | 用户唯一 ID |
+| `userlist[].name` | string | 用户姓名 |
+| `userlist[].alias` | string | 用户别名，可能为空 |
+
+---
+
+### 2. 按姓名/别名搜索人员
+
+`get_userlist` 返回全量成员后，在本地对结果进行筛选匹配：
+
+- **精确匹配**：`name` 或 `alias` 与关键词完全一致，直接使用
+- **模糊匹配**：`name` 或 `alias` 包含关键词，返回所有匹配结果
+- **无结果**：告知用户未找到对应人员
+
+**搜索示例：**
+
+用户问："帮我找一下张三是谁？"
+
+1. 调用 `get_userlist` 获取全量成员
+2. 在 `userlist` 中筛选 `name` 或 `alias` 包含"张三"的成员
+3. 返回匹配结果
+
+---
+
+## 注意事项
+
+- `get_userlist` 返回的是当前用户**可见范围内**的成员，需经过可见性规则过滤，不一定是全公司所有人员；返回字段仅包含 `userid`、`name`（姓名）和 `alias`（别名）
+- ⚠️ **超过 10 人时接口将报错**：若 `userlist` 返回成员数量超过 10 人，视为异常，应立即停止处理并向用户说明：
+
+  > 当前通讯录可见成员数量超过了本技能支持的上限（10 人）。
+  > 本技能仅适用于可见范围较小的场景，无法在大范围通讯录中使用。
+  > 建议缩小可见范围后重试，或通过其他方式查询目标人员。
+
+- `userid` 是用户的唯一标识，在需要传递用户 ID 给其他接口时使用此字段
+- `alias` 字段可能为空字符串，搜索时需做空值判断
+- 若搜索结果有多个同名人员，需将所有候选人展示给用户选择，不得自行决定
+- 若 `errcode` 不为 `0`，说明接口调用失败，需告知用户错误信息（`errmsg`）
+
+---
+
+## 典型工作流
+
+### 工作流 1：查询人员信息
+
+用户问："帮我查一下 Sam 是谁？"
+
+1. 使用 `wecom_mcp` tool 调用 `wecom_mcp call contact get_userlist '{}'` 获取全量成员列表
+
+2. 在结果中筛选 `alias` 为 `Sam` 或 `name` 包含 `Sam` 的成员
+3. 若找到唯一匹配，直接展示结果：
+
+```
+📇 找到成员：
+- 姓名：张三
+- 别名：Sam
+- 用户ID：zhangsan
+```
+
+4. 若找到多个匹配，展示候选列表请用户确认：
+
+```
+🔍 找到多个匹配成员，请确认您要查询的是哪位：
+
+1. 张三（别名：Sam，ID：zhangsan）
+2. 张三丰（别名：Sam2，ID：zhangsan2）
+
+请问您要查询的是哪一位？
+```
+
+---
+
+### 工作流 2：为其他功能提供 userid 转换
+
+用户问："帮我发消息给张三"
+
+1. 使用 `wecom_mcp` tool 调用 `wecom_mcp call contact get_userlist '{}'` 获取全量成员
+
+2. 筛选 `name` 为"张三"的成员，确认 `userid`
+3. 将 `userid` 传递给消息发送接口
+
+---
+
+### 工作流 3：批量查询多个人员
+
+用户问："帮我查一下张三和李四分别是谁？"
+
+1. 使用 `wecom_mcp` tool 调用 `wecom_mcp call contact get_userlist '{}'` 获取全量成员列表
+
+2. 分别筛选"张三"和"李四"的匹配结果
+3. 汇总后一并展示
+
+> 注意：只需调用一次 `get_userlist`，在本地对结果进行多次筛选，避免重复调用接口。
+
+---
+
+## 快速参考
+
+### 接口说明
+
+| 接口 | 用途 | 输入 | 返回 |
+|------|------|------|------|
+| `get_userlist` | 获取可见范围内全量通讯录成员 | 无 | 用户列表（userid、name、alias） |
+
+### 本地筛选策略
+
+| 场景 | 策略 |
+|------|------|
+| 精确匹配（name 或 alias 完全一致） | 直接使用，无需用户确认 |
+| 模糊匹配（name 或 alias 包含关键词），唯一结果 | 直接使用，向用户展示结果 |
+| 模糊匹配，多个结果 | 展示候选列表，请用户选择 |
+| 无匹配结果 | 告知用户未找到对应人员 |

package/skills/wecom-doc-manager/SKILL.md

@@ -0,0 +1,64 @@
+---
+name: wecom-doc-manager
+description: 企业微信文档管理技能。提供文档的创建、读取和编辑能力，支持通过 docid 或文档 URL 操作企业微信文档（doc_type=3）和智能表格（doc_type=10）。适用场景：(1) 以 Markdown 格式导出获取文档完整内容（异步轮询） (2) 新建文档或智能表格 (3) 用 Markdown 格式覆写文档内容。当用户需要查看文档内容、创建新文档、编辑文档正文时触发此 Skill。
+---
+
+# 企业微信文档管理
+
+> `wecom_mcp` 是一个 MCP tool，所有操作通过调用该 tool 完成。
+
+> ⚠️ **前置条件**：首次调用 `wecom_mcp` 前，必须按 `wecom-preflight` 技能执行前置条件检查，确保工具已加入白名单。
+
+管理企业微信文档的创建、读取和编辑。所有接口支持通过 `docid` 或 `url` 二选一定位文档。
+
+## 调用方式
+
+通过 `wecom_mcp` tool 调用，品类为 `doc`：
+
+使用 `wecom_mcp` tool 调用 `wecom_mcp call doc <tool_name> '<json_params>'` 调用指定技能
+
+## 返回格式说明
+
+所有接口返回 JSON 对象，包含以下公共字段：
+
+| 字段 | 类型 | 说明 |
+|------|------|------|
+| `errcode` | integer | 返回码，`0` 表示成功，非 `0` 表示失败 |
+| `errmsg` | string | 错误信息，成功时为 `"ok"` |
+
+当 `errcode` 不为 `0` 时，说明接口调用失败，可重试 1 次；若仍失败，将 `errcode` 和 `errmsg` 展示给用户。
+
+### get_doc_content
+
+获取文档完整内容数据，只能以 Markdown 格式返回。采用**异步轮询机制**：首次调用无需传 `task_id`，接口返回 `task_id`；若 `task_done` 为 false，需携带该 `task_id` 再次调用，直到 `task_done` 为 true 时返回完整内容。
+
+- 首次调用（不传 task_id）：使用 `wecom_mcp` tool 调用 `wecom_mcp call doc get_doc_content '{"docid": "DOCID", "type": 2}'`
+- 轮询（携带上次返回的 task_id）：使用 `wecom_mcp` tool 调用 `wecom_mcp call doc get_doc_content '{"docid": "DOCID", "type": 2, "task_id": "xxx"}'`
+- 或通过 URL：使用 `wecom_mcp` tool 调用 `wecom_mcp call doc get_doc_content '{"url": "https://doc.weixin.qq.com/doc/xxx", "type": 2}'`
+
+参见 [API 详情](references/api-export-document.md)。
+
+### create_doc
+
+新建文档（doc_type=3）或智能表格（doc_type=10）。创建成功返回 url 和 docid。
+
+- 使用 `wecom_mcp` tool 调用 `wecom_mcp call doc create_doc '{"doc_type": 3, "doc_name": "项目周报"}'`
+- 使用 `wecom_mcp` tool 调用 `wecom_mcp call doc create_doc '{"doc_type": 10, "doc_name": "任务跟踪表"}'`
+
+**注意**：docid 仅在创建时返回，需妥善保存。创建智能表格时默认包含一个子表，可通过 `smartsheet_get_sheet` 查询其 sheet_id。
+
+参见 [API 详情](references/api-create-doc.md)。
+
+### edit_doc_content
+
+用 Markdown 内容覆写文档正文。`content_type` 固定为 `1`（Markdown）。
+
+使用 `wecom_mcp` tool 调用 `wecom_mcp call doc edit_doc_content '{"docid": "DOCID", "content": "# 标题\n\n正文内容", "content_type": 1}'`
+
+参见 [API 详情](references/api-edit-doc-content.md)。
+
+## 典型工作流
+
+1. **读取文档** → 使用 `wecom_mcp` tool 调用 `wecom_mcp call doc get_doc_content '{"docid": "DOCID", "type": 2}'`，若 `task_done` 为 false 则携带 `task_id` 继续轮询
+2. **创建新文档** → 使用 `wecom_mcp` tool 调用 `wecom_mcp call doc create_doc '{"doc_type": 3, "doc_name": "文档名"}'`，保存返回的 docid
+3. **编辑文档** → 先 get_doc_content 了解当前内容，再 edit_doc_content 覆写

package/skills/wecom-doc-manager/references/api-create-doc.md

@@ -0,0 +1,56 @@
+# create_doc API
+
+新建文档、表格或智能表格。创建成功后返回文档访问链接和 docid。
+
+## 技能定义
+
+```json
+{
+    "name": "create_doc",
+    "description": "新建文档、表格或智能表格。支持在指定空间和目录下创建，可设置文档管理员。创建成功后返回文档访问链接和 docid（docid 仅在创建时返回，需妥善保存）。注意：创建智能表格（doc_type=10）时，文档会默认包含一个子表，可通过 smartsheet_get_sheet 查询其 sheet_id，无需额外调用 smartsheet_add_sheet。",
+    "inputSchema": {
+        "properties": {
+            "doc_type": {
+                "description": "文档类型：3-文档，10-智能表格",
+                "enum": [3, 10],
+                "title": "Doc Type",
+                "type": "integer"
+            },
+            "doc_name": {
+                "description": "文档名字，最多 255 个字符，超过会被截断",
+                "title": "Doc Name",
+                "type": "string"
+            }
+        },
+        "required": ["doc_type", "doc_name"],
+        "title": "create_docArguments",
+        "type": "object"
+    }
+}
+```
+
+## 请求示例
+
+```json
+{
+    "doc_type": 3,
+    "doc_name": "项目周报"
+}
+```
+
+## 响应示例
+
+```json
+{
+    "errcode": 0,
+    "errmsg": "ok",
+    "url": "https://doc.weixin.qq.com/doc/xxx",
+    "docid": "DOCID"
+}
+```
+
+## 注意事项
+
+- `doc_type=3` 创建普通文档
+- `doc_type=10` 创建智能表格，默认包含一个子表
+- docid 仅在创建时返回，后续无法再获取，务必保存

package/skills/wecom-doc-manager/references/api-edit-doc-content.md

@@ -0,0 +1,68 @@
+# edit_doc_content API
+
+编辑（覆写）文档内容。
+
+## 技能定义
+
+```json
+{
+    "name": "edit_doc_content",
+    "description": "编辑文档内容",
+    "inputSchema": {
+        "properties": {
+            "docid": {
+                "description": "文档 id，与 url 二选一传入",
+                "title": "Docid",
+                "type": "string"
+            },
+            "url": {
+                "description": "文档的访问链接，与 docid 二选一传入",
+                "title": "URL",
+                "type": "string"
+            },
+            "content": {
+                "description": "覆写的文档内容",
+                "title": "Content",
+                "type": "string"
+            },
+            "content_type": {
+                "description": "内容类型格式。1:markdown",
+                "enum": [1],
+                "title": "Content Type",
+                "type": "integer"
+            }
+        },
+        "oneOf": [
+            { "required": ["docid", "content", "content_type"] },
+            { "required": ["url", "content", "content_type"] }
+        ],
+        "title": "edit_doc_contentArguments",
+        "type": "object"
+    }
+}
+```
+
+## 请求示例
+
+```json
+{
+    "docid": "DOCID",
+    "content": "# 标题\n\n正文内容",
+    "content_type": 1
+}
+```
+
+## 响应示例
+
+```json
+{
+    "errcode": 0,
+    "errmsg": "ok"
+}
+```
+
+## 注意事项
+
+- `content_type` 当前仅支持 `1`（Markdown 格式）
+- 此操作为**覆写**，会替换文档全部内容
+- 建议先调用 `get_document` 了解当前内容再编辑

package/skills/wecom-doc-manager/references/api-export-document.md

@@ -0,0 +1,88 @@
+# get_doc_content API
+
+获取企业微信文档的完整内容数据，以 Markdown 格式返回。该接口采用异步轮询机制：首次调用无需传 task_id，接口会返回 task_id；若 task_done 为 false，需携带该 task_id 再次调用，直到 task_done 为 true 时返回完整内容。
+
+## 技能定义
+
+```json
+{
+    "name": "get_doc_content",
+    "description": "获取企业微信文档的完整内容数据，以 Markdown 格式返回。该接口采用异步轮询机制：首次调用无需传 task_id，接口会返回 task_id；若 task_done 为 false，需携带该 task_id 再次调用，直到 task_done 为 true 时返回完整内容。",
+    "inputSchema": {
+        "properties": {
+            "docid": {
+                "description": "文档的 docid，与 url 二选一传入",
+                "title": "Doc ID",
+                "type": "string"
+            },
+            "url": {
+                "description": "文档的访问链接，与 docid 二选一传入",
+                "title": "URL",
+                "type": "string"
+            },
+            "type": {
+                "description": "内容返回格式。2: Markdown 格式",
+                "enum": [2],
+                "title": "Type",
+                "type": "integer"
+            },
+            "task_id": {
+                "description": "任务 ID，用于异步轮询。初次调用时不填，后续轮询时填写上次返回的 task_id",
+                "title": "Task ID",
+                "type": "string"
+            }
+        },
+        "oneOf": [
+            { "required": ["docid", "type"] },
+            { "required": ["url", "type"] }
+        ],
+        "title": "get_doc_contentArguments",
+        "type": "object"
+    }
+}
+```
+
+## 参数说明
+
+| 参数 | 类型 | 必填 | 说明 |
+|---|---|---|---|
+| docid | string | 与 url 二选一 | 文档的 docid |
+| url | string | 与 docid 二选一 | 文档的访问链接 |
+| type | integer | 是 | 内容返回格式，固定传 `2`（Markdown 格式） |
+| task_id | string | 否 | 任务 ID，初次调用不填，后续轮询时填写上次返回的 task_id |
+
+## 异步轮询机制
+
+1. **首次调用**：传入 `docid`/`url` 和 `type: 2`，不传 `task_id`
+2. **检查响应**：若 `task_done` 为 `false`，记录返回的 `task_id`
+3. **轮询调用**：携带 `task_id` 再次调用，直到 `task_done` 为 `true`
+4. **获取内容**：当 `task_done` 为 `true` 时，`content` 字段包含完整的 Markdown 内容
+
+## 请求示例
+
+```json
+// 首次调用
+{
+    "docid": "DOCID",
+    "type": 2
+}
+
+// 轮询调用
+{
+    "docid": "DOCID",
+    "type": 2,
+    "task_id": "xxx"
+}
+```
+
+## 响应示例
+
+```json
+{
+    "errcode": 0,
+    "errmsg": "ok",
+    "content": "# 文档标题\n\n文档正文内容...",
+    "task_id": "xxxxx",
+    "task_done": true
+}
+```