@mocrane/wecom 2026.3.9 → 2026.3.12

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>
@@ -29,7 +22,7 @@
 <a id="sec-1"></a>
 ## 💡 核心价值：为什么选择本插件？
 
-### 独创架构：Bot + Agent 双模融合 (Original Design by YanHaidao)
+### 独创架构：Bot + Agent 双模融合
 
 传统的企微插件通常只能在 "只能聊天的机器人 (Bot)" 和 "只能推送的自建应用 (Agent)" 之间二选一。
 本插件采用 **双模并行架构**，同时压榨两种模式的极限能力：
@@ -37,7 +30,7 @@
 *   **Bot 通道 (智能体)**：负责 **实时对话**。提供毫秒级流式响应（打字机效果），零延迟交互。
 *   **Agent 通道 (自建应用)**：负责 **能力兜底**。当需要发送图片/文件、进行全员广播、或 Bot 对话超时（>6分钟）时，无缝切换到 Agent 通道接管。
 
-### 🚀 企业级：多账号（Multi-account）矩阵隔离 (Original Design)
+### 🚀 企业级：多账号（Multi-account）矩阵隔离
 
 本插件支持 **无限扩展的账号矩阵**，这是本插件区别于普通插件的核心壁垒：
 
@@ -339,8 +332,8 @@ openclaw channels status
 7. 记录回调 Token 和 EncodingAESKey
 
 <div align="center">
-  <img src="https://cdn.jsdelivr.net/npm/@mocrane/wecom@latest/assets/03.bot.page.png" width="45%" alt="Bot Config" />
-  <img src="https://cdn.jsdelivr.net/npm/@mocrane/wecom@latest/assets/03.agent.page.png" width="45%" alt="Agent Config" />
+  <img src="https://raw.githubusercontent.com/TencentCloud-Lighthouse/openclaw-wecom/main/assets/03.bot.page.png" width="45%" alt="Bot Config" />
+  <img src="https://raw.githubusercontent.com/TencentCloud-Lighthouse/openclaw-wecom/main/assets/03.agent.page.png" width="45%" alt="Agent Config" />
 </div>
 
 ---
@@ -477,30 +470,40 @@ Agent 输出 `{"template_card": ...}` 时自动渲染为交互卡片：
 
 ## 七、📮 联系我
 
-微信交流群（扫码入群）：
-
-![企业微信交流群](https://openclaw.cc/wechat-openclaw-cn-qr.jpg)
-
 维护者：mocrane
 
 ---
 
 <a id="sec-legal"></a>
 
-## ⚖️ 授权与原创声明
+## ⚖️ 授权与致谢
 
-本项目采用 **ISC License** 开源协议，并在此强调以下要求：
+本项目采用 **ISC License** 开源协议。
 
-1. **保留署名**：根据 ISC 协议，您在任何分发、修改或使用本项目（或其部分逻辑）时，**必须**在显著位置完整保留本项目的版权声明（Copyright Notice）。
-2. **尊重原创**：本项目包含的“Bot/Agent 自动化互补架构”、“长对话超时接力”、“WeCom 全媒体流自动化处理”等核心逻辑均为作者 **YanHaidao** 独立思考与实践的原创成果。
-3. **维权申明**：对于恶意删除署名、像素级抄袭、混淆视听的恶意搬运行为，作者保留在社区公示及通过法律途径维权的权利。
+- **开源协议**：您在分发、修改或使用本项目时，请遵循 ISC 协议的相关要求。
+- **致谢**：本项目最初基于 **YanHaidao** 的企业微信插件 fork 而来，感谢其在早期版本中的工作与贡献。当前版本已由 **mocrane** 独立重构与维护。
 
 ---
 
 <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/clawdbot.plugin.json

@@ -1,6 +1,7 @@
 {
   "id": "wecom",
   "channels": ["wecom"],
+  "skills": ["./skills"],
   "configSchema": {
     "type": "object",
     "additionalProperties": false,

package/index.ts

@@ -1,9 +1,10 @@
 import type { OpenClawPluginApi } from "openclaw/plugin-sdk";
-import { emptyPluginConfigSchema } from "openclaw/plugin-sdk";
+import { emptyPluginConfigSchema } from "./src/compat/plugin-sdk-shim.js";
 
 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 通道注入，避免污染其他通道（如 Telegram/Discord）的 system prompt。
+    // deliver 回调中保留兜底正则解析，作为双重保障。
+    api.on("before_prompt_build", (_event, ctx) => {
+      if (ctx.channelId !== "wecom") return;
+      return {
+        systemPrompt: [
+          "【发送文件/图片/视频/语音】",
+          "当你需要向用户发送文件、图片、视频或语音时，必须在回复中单独一行使用 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/openclaw.plugin.json

@@ -1,6 +1,7 @@
 {
   "id": "wecom",
   "channels": ["wecom"],
+  "skills": ["./skills"],
   "configSchema": {
     "type": "object",
     "additionalProperties": false,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mocrane/wecom",
-  "version": "2026.3.9",
+  "version": "2026.3.12",
   "type": "module",
   "description": "OpenClaw WeCom (WeChat Work) intelligent bot channel plugin",
   "main": "index.ts",
@@ -9,6 +9,7 @@
     "src/",
     "assets/",
     "changelog/",
+    "skills/",
     "openclaw.plugin.json",
     "clawdbot.plugin.json",
     "README.md",
@@ -42,17 +43,19 @@
     }
   },
   "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",
     "zod": "^4.3.6"
   },
   "peerDependencies": {
-    "openclaw": ">=2026.2.24"
+    "openclaw": "^2026.3.11"
   },
   "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 包含关键词），唯一结果 | 直接使用，向用户展示结果 |
+| 模糊匹配，多个结果 | 展示候选列表，请用户选择 |
+| 无匹配结果 | 告知用户未找到对应人员 |