@yanhaidao/wecom 2.0.1 → 2.2.3

package/README.md

@@ -1,121 +1,247 @@
 # OpenClaw 企业微信（WeCom）Channel 插件
 
-维护者：YanHaidao（VX：YanHaidao）
+<p align="center">
+  <strong>🚀 企业级双模式 AI 助手接入方案</strong>
+</p>
 
-状态：支持企业微信智能机器人（API 模式）加密回调 + 被动回复（stream）。
+<p align="center">
+  <a href="#功能亮点">功能亮点</a> •
+  <a href="#模式对比">模式对比</a> •
+  <a href="#快速开始">快速开始</a> •
+  <a href="#配置说明">配置说明</a> •
+  <a href="#联系我">联系我</a>
+</p>
 
-## 联系我
+---
 
-微信交流群（扫码入群）：
+## 🚀 全网首发 · 功能全面 —— 功能亮点
 
-![企业微信交流群](https://cdn.jsdelivr.net/npm/@yanhaidao/wecom@latest/assets/link-me.jpg)
+本插件提供**完整支持企业微信双模式（Bot + Agent）**的深度集成方案。相比目前其他的开源方案，我们提供企业级生产环境所需的全部特性：
+
+| 核心特性 | 本插件 | 其他开源方案 | 优势说明 |
+|:---|:---:|:---:|:---|
+| 🔥 **双模式并行** | ✅ **完美支持** | ❌ 仅支持单模式 | 同时使用 Bot 的便捷与 Agent 的强大能力 |
+| ⚡ **原生流式回复** | ✅ **Bot/Agent 全支持** | ❌ 伪流式/不支持 | 真实打字机效果，告别长时间转圈等待 |
+| 📡 **主动消息推送** | ✅ **支持** | ❌ 仅被动回复 | 可随时通过 API 发送消息，脱离回调限制 |
+| 🔐 **双协议加密** | ✅ **JSON + XML** | ⚠️ 部分支持 | 完整兼容企微新旧两种加密标准，安全无忧 |
+| 📎 **全媒体处理** | ✅ **图片/语音/文件/视频** | ⚠️ 仅文本/图片 | 自动解密下载媒体文件，语音自动转文字 |
+| 🎴 **交互式卡片** | ✅ **Template Card** | ❌ 不支持 | 支持按钮交互回调，打造复杂业务流 |
+| 🔄 **Token 自运维** | ✅ **自动缓存刷新** | ❌ 需手工处理 | 内置 AccessToken 管理器，故障自动重试 |
 
-## 文件与图片入模（说明）
 
-图片/文件 URL 下载内容为加密数据，需使用 `EncodingAESKey` 解密后再解析并入模。
 
-## 测试页截图（文件上传 / 解析）
+<div align="center">
+  <img src="https://cdn.jsdelivr.net/npm/@yanhaidao/wecom@latest/assets/01.image.jpg" width="45%" />
+  <img src="https://cdn.jsdelivr.net/npm/@yanhaidao/wecom@latest/assets/02.image.jpg" width="45%" />
+</div>
 
-> 图片过大可替换为压缩版（保持文件名不变即可）。
 
-![WeCom 测试页截图（文件上传 / 解析）](https://cdn.jsdelivr.net/npm/@yanhaidao/wecom@latest/assets/01.image.jpg)
 
-## A2UI 交互卡片（template_card）
+---
 
-- Agent 输出 `{"template_card": ...}`（JSON）时：单聊且有 `response_url` 会发送交互卡片；群聊或无 `response_url` 自动降级为文本说明（不透出原始 JSON）。
-- 收到 `template_card_event` 时：会转换为伪文本消息触发 Agent，并基于 `msgid` 去重避免重复处理。
-- 卡片相关的示例/skill：加群获取（见上方交流群二维码）。
+## 模式对比
 
-## 安装
+###  Bot vs Agent 你该选哪个？
+
+| 维度 | Bot 模式（智能体） | Agent 模式（自建应用） |
+|:---|:---|:---|
+| **接入方式** | 企微后台「智能机器人」 | 企微后台「自建应用」 |
+| **回调格式** | JSON 加密 | XML 加密 |
+| **回复机制** | response_url 被动回复 | API 主动发送 |
+| **流式支持** | ✅ 原生 stream 刷新 | ❌ 模拟分段 |
+| **主动推送** | ❌ 无法脱离回调 | ✅ 任意时机发送 |
+| **媒体能力** | 受限（URL 方式） | 完整（media_id） |
+| **被动回复图片** | ✅ 已实现 | ✅ 已实现 |
+| **Outbound 发图片** | ❌ API 不支持 | ✅ 已实现 |
+| **Outbound 发文本** | ❌ API 不支持 | ✅ 已实现 |
+| **适用场景** | 快速体验、轻量对话 | 企业级部署、业务集成 |
+
+> 💡 **推荐配置**：两种模式可同时启用！Bot 用于日常快速对话，Agent 用于主动通知和媒体发送。
+
+---
+
+## 快速开始
+
+### 1. 安装插件
 
-### 从 npm 安装
 ```bash
 openclaw plugins install @yanhaidao/wecom
 openclaw plugins enable wecom
+```
+
+也可以通过命令行向导快速配置：
+
+```bash
+openclaw config --section channels
+```
+
+### 2. 配置 Bot 模式（智能体）
+
+```bash
+openclaw config set channels.wecom.enabled true
+openclaw config set channels.wecom.bot.token "YOUR_BOT_TOKEN"
+openclaw config set channels.wecom.bot.encodingAESKey "YOUR_BOT_AES_KEY"
+openclaw config set channels.wecom.bot.receiveId ""
+openclaw config set channels.wecom.bot.streamPlaceholderContent "正在思考..."
+openclaw config set channels.wecom.bot.welcomeText "你好！我是 AI 助手"
+# 不配置表示所有人可用，配置则进入白名单模式
+openclaw config set channels.wecom.bot.dm.allowFrom '["user1", "user2"]' 
+```
+
+### 3. 配置 Agent 模式（自建应用，可选）
+
+```bash
+openclaw config set channels.wecom.enabled true
+openclaw config set channels.wecom.agent.corpId "YOUR_CORP_ID"
+openclaw config set channels.wecom.agent.corpSecret "YOUR_CORP_SECRET"
+openclaw config set channels.wecom.agent.agentId 1000001
+openclaw config set channels.wecom.agent.token "YOUR_CALLBACK_TOKEN"
+openclaw config set channels.wecom.agent.encodingAESKey "YOUR_CALLBACK_AES_KEY"
+openclaw config set channels.wecom.agent.welcomeText "欢迎使用智能助手"
+openclaw config set channels.wecom.agent.dm.allowFrom '["user1", "user2"]'
+```
+
+### 4. 验证
+
+```bash
 openclaw gateway restart
+openclaw channels status
 ```
 
-## 配置结构参考
+---
+
+## 配置说明
 
-```json
+### 完整配置结构
+
+```jsonc
 {
   "channels": {
     "wecom": {
       "enabled": true,
-      "webhookPath": "/wecom",
-      "token": "YOUR_TOKEN",
-      "encodingAESKey": "YOUR_ENCODING_AES_KEY",
-      "receiveId": "",
-      "streamPlaceholderContent": "正在思考...",
-      "dm": { "policy": "pairing" }
+      
+      // Bot 模式配置（智能体）
+      "bot": {
+        "token": "YOUR_BOT_TOKEN",
+        "encodingAESKey": "YOUR_BOT_AES_KEY",
+        "receiveId": "",                        // 可选，用于解密校验
+        "streamPlaceholderContent": "正在思考...",
+        "welcomeText": "你好！我是 AI 助手",
+        "dm": { "allowFrom": [] }               // 私聊限制
+      },
+      
+      // Agent 模式配置（自建应用）
+      "agent": {
+        "corpId": "YOUR_CORP_ID",
+        "corpSecret": "YOUR_CORP_SECRET",
+        "agentId": 1000001,
+        "token": "YOUR_CALLBACK_TOKEN",         // 企微后台「设置API接收」
+        "encodingAESKey": "YOUR_CALLBACK_AES_KEY",
+        "welcomeText": "欢迎使用智能助手",
+        "dm": { "allowFrom": [] }
+      }
     }
   }
 }
 ```
 
-## 接入企业微信
+### Webhook 路径（固定）
 
-### 搭建企微 Bot（API 模式）
+| 模式 | 路径 | 说明 |
+|:---|:---|:---|
+| Bot | `/wecom/bot` | 智能体回调 |
+| Agent | `/wecom/agent` | 自建应用回调 |
 
-1. 登录企业微信管理后台  
-进入「安全与管理」→「管理工具」→「智能机器人」：`https://work.weixin.qq.com/wework_admin/frame#/manageTools`
+### DM 策略
 
-2. 创建机器人（务必选择 API 模式）  
-创建机器人时需要填写回调 URL（公网可访问的 HTTPS 地址），例如：`https://example.com/wecom`
+- **不配置 `dm.allowFrom`** → 所有人可用（默认）
+- **配置 `dm.allowFrom: ["user1", "user2"]`** → 白名单模式，仅列表内用户可私聊
 
-3. 记录机器人配置  
-在机器人详情里找到并保存以下信息，后续会写入 OpenClaw 配置：
-- Token
-- EncodingAESKey
-- ReceiveId（如果你的机器人/回调配置需要校验的话）
+### 常用指令
 
-## 快速开始
+| 指令 | 说明 | 示例 |
+|:---|:---|:---|
+| `/new` | 🆕 开启新会话 (重置上下文) | `/new` 或 `/new GPT-4` |
+| `/reset` | 🔄 重置会话 (同 /new) | `/reset` |
 
-1. 启用插件
-```bash
-openclaw plugins enable wecom
-```
+---
 
-2. 配置企业微信机器人（必需）
-```bash
-openclaw config set channels.wecom.enabled true
-openclaw config set channels.wecom.webhookPath "/wecom"
-openclaw config set channels.wecom.token "YOUR_TOKEN"
-openclaw config set channels.wecom.encodingAESKey "YOUR_ENCODING_AES_KEY"
-openclaw config set channels.wecom.receiveId ""
-```
+## 企业微信接入指南
 
-3. 配置 Gateway（示例）
-```bash
-openclaw config set gateway.mode "local"
-openclaw config set gateway.bind "0.0.0.0"
-openclaw config set gateway.port 18789
-```
+### Bot 模式（智能机器人）
 
-4. 重启 Gateway
-```bash
-openclaw gateway restart
-```
+1. 登录 [企业微信管理后台](https://work.weixin.qq.com/wework_admin/frame#/manageTools)
+2. 进入「安全与管理」→「管理工具」→「智能机器人」
+3. 创建机器人，选择 **API 模式**
+4. 填写回调 URL：`https://your-domain.com/wecom/bot`
+5. 记录 Token 和 EncodingAESKey
 
-5. 验证
-```bash
-openclaw channels status
-```
+### Agent 模式（自建应用）
+
+1. 登录 [企业微信管理后台](https://work.weixin.qq.com/wework_admin/frame#/apps)
+2. 进入「应用管理」→「自建」→ 创建应用
+3. 获取 AgentId、CorpId、Secret
+4. **重要：** 进入「企业可信IP」→「配置」→ 添加你服务器的 IP 地址
+5. 在应用详情中设置「接收消息 - 设置API接收」
+6. 填写回调 URL：`https://your-domain.com/wecom/agent`
+7. 记录回调 Token 和 EncodingAESKey
+
+---
 
-## 说明
+## 高级功能
+
+### A2UI 交互卡片
+
+Agent 输出 `{"template_card": ...}` 时自动渲染为交互卡片：
+
+- ✅ 单聊场景：发送真实交互卡片
+- ✅ 按钮点击：触发 `template_card_event` 回调
+- ✅ 自动去重：基于 `msgid` 避免重复处理
+- ⚠️ 群聊降级：自动转为文本描述
+
+### 富媒体处理
+
+| 类型 | Bot 模式 | Agent 模式 |
+|:---|:---|:---|
+| 图片 | ✅ URL 解密入模 | ✅ media_id 下载 |
+| 文件 | ✅ URL 解密入模 | ✅ media_id 下载 |
+| 语音 | ✅ 转文字入模 | ✅ 识别结果 + 原始音频 |
+| 视频 | ❌ | ✅ media_id 下载 |
+
+### DM 策略
+
+- **不配置 `dm.allowFrom`** → 所有人可用（默认）
+- **配置 `dm.allowFrom: ["user1", "user2"]`** → 白名单模式，仅列表内用户可私聊
+
+---
+
+## 联系我
+
+微信交流群（扫码入群）：
+
+![企业微信交流群](https://cdn.jsdelivr.net/npm/@yanhaidao/wecom@latest/assets/link-me.jpg)
+
+维护者：YanHaidao（VX：YanHaidao）
 
-- webhook 必须是公网 HTTPS。出于安全考虑，建议只对外暴露 `/wecom` 路径。
-- stream 模式：第一次回包可能是占位符；随后 WeCom 会以 `msgtype=stream` 回调刷新拉取完整内容。
-- 限制：仅支持被动回复，不支持脱离回调的主动发送。
+---
 
+## 更新日志
 
+### 2026.2.3
 
-# 更新日志
+- 🎉 **重大更新**：新增 Agent 模式（自建应用）支持
+- ✨ 双模式并行：Bot + Agent 可同时运行
+- ✨ AccessToken 自动管理：缓存 + 智能刷新
+- ✨ Agent 主动推送：脱离回调限制
+- ✨ XML 加解密：完整 Agent 回调支持
+- 📁 代码重构：模块化解耦设计
 
-## 2026.1.31
+### 2026.1.31
 
-- 文档：补充入模与测试截图说明。
+- 文档：补充入模与测试截图说明
+- 新增文件支持
+- 新增卡片支持
 
-## 2026.1.30
+### 2026.1.30
 
-- 项目更名：Clawdbot → OpenClaw（CLI：`clawdbot` → `openclaw`）。
+- 项目更名：Clawdbot → OpenClaw

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@yanhaidao/wecom",
-  "version": "2.0.1",
+  "version": "2.2.3",
   "type": "module",
   "description": "OpenClaw WeCom (WeChat Work) intelligent bot channel plugin",
   "author": "YanHaidao (VX: YanHaidao)",
@@ -33,6 +33,7 @@
   },
   "dependencies": {
     "axios": "^1.13.4",
+    "fast-xml-parser": "5.3.4",
     "zod": "^4.3.6"
   },
   "peerDependencies": {

package/src/agent/api-client.ts

@@ -0,0 +1,225 @@
+/**
+ * WeCom Agent API 客户端
+ * 管理 AccessToken 缓存和 API 调用
+ */
+
+import crypto from "node:crypto";
+import { API_ENDPOINTS, LIMITS } from "../types/constants.js";
+import type { ResolvedAgentAccount } from "../types/index.js";
+
+type TokenCache = {
+    token: string;
+    expiresAt: number;
+    refreshPromise: Promise<string> | null;
+};
+
+const tokenCaches = new Map<string, TokenCache>();
+
+/**
+ * 获取 AccessToken (带缓存)
+ */
+export async function getAccessToken(agent: ResolvedAgentAccount): Promise<string> {
+    const cacheKey = `${agent.corpId}:${agent.agentId}`;
+    let cache = tokenCaches.get(cacheKey);
+
+    if (!cache) {
+        cache = { token: "", expiresAt: 0, refreshPromise: null };
+        tokenCaches.set(cacheKey, cache);
+    }
+
+    const now = Date.now();
+    if (cache.token && cache.expiresAt > now + LIMITS.TOKEN_REFRESH_BUFFER_MS) {
+        return cache.token;
+    }
+
+    // 防止并发刷新
+    if (cache.refreshPromise) {
+        return cache.refreshPromise;
+    }
+
+    cache.refreshPromise = (async () => {
+        try {
+            const url = `${API_ENDPOINTS.GET_TOKEN}?corpid=${encodeURIComponent(agent.corpId)}&corpsecret=${encodeURIComponent(agent.corpSecret)}`;
+            const res = await fetch(url, { signal: AbortSignal.timeout(LIMITS.REQUEST_TIMEOUT_MS) });
+            const json = await res.json() as { access_token?: string; expires_in?: number; errcode?: number; errmsg?: string };
+
+            if (!json?.access_token) {
+                throw new Error(`gettoken failed: ${json?.errcode} ${json?.errmsg}`);
+            }
+
+            cache!.token = json.access_token;
+            cache!.expiresAt = Date.now() + (json.expires_in ?? 7200) * 1000;
+            return cache!.token;
+        } finally {
+            cache!.refreshPromise = null;
+        }
+    })();
+
+    return cache.refreshPromise;
+}
+
+/**
+ * 发送文本消息
+ */
+export async function sendText(params: {
+    agent: ResolvedAgentAccount;
+    toUser?: string;
+    chatId?: string;
+    text: string;
+}): Promise<void> {
+    const { agent, toUser, chatId, text } = params;
+    const token = await getAccessToken(agent);
+
+    const useChat = Boolean(chatId);
+    const url = useChat
+        ? `${API_ENDPOINTS.SEND_APPCHAT}?access_token=${encodeURIComponent(token)}`
+        : `${API_ENDPOINTS.SEND_MESSAGE}?access_token=${encodeURIComponent(token)}`;
+
+    const body = useChat
+        ? { chatid: chatId, msgtype: "text", text: { content: text } }
+        : { touser: toUser, msgtype: "text", agentid: agent.agentId, text: { content: text } };
+
+    const res = await fetch(url, {
+        method: "POST",
+        headers: { "Content-Type": "application/json" },
+        body: JSON.stringify(body),
+        signal: AbortSignal.timeout(LIMITS.REQUEST_TIMEOUT_MS),
+    });
+    const json = await res.json() as { errcode?: number; errmsg?: string };
+
+    if (json?.errcode !== 0) {
+        throw new Error(`send failed: ${json?.errcode} ${json?.errmsg}`);
+    }
+}
+
+/**
+ * 上传媒体文件
+ */
+export async function uploadMedia(params: {
+    agent: ResolvedAgentAccount;
+    type: "image" | "voice" | "video" | "file";
+    buffer: Buffer;
+    filename: string;
+}): Promise<string> {
+    const { agent, type, buffer, filename } = params;
+    const token = await getAccessToken(agent);
+    // 添加 debug=1 参数获取更多错误信息
+    const url = `${API_ENDPOINTS.UPLOAD_MEDIA}?access_token=${encodeURIComponent(token)}&type=${encodeURIComponent(type)}&debug=1`;
+
+    // DEBUG: 输出上传信息
+    console.log(`[wecom-upload] Uploading media: type=${type}, filename=${filename}, size=${buffer.length} bytes`);
+
+    // 手动构造 multipart/form-data 请求体
+    // 企业微信要求包含 filename 和 filelength
+    const boundary = `----WebKitFormBoundary${crypto.randomBytes(16).toString("hex")}`;
+
+    // 根据文件类型设置 Content-Type
+    const contentTypeMap: Record<string, string> = {
+        jpg: "image/jpg", jpeg: "image/jpeg", png: "image/png", gif: "image/gif",
+        bmp: "image/bmp", amr: "voice/amr", mp4: "video/mp4",
+    };
+    const ext = filename.split(".").pop()?.toLowerCase() || "";
+    const fileContentType = contentTypeMap[ext] || "application/octet-stream";
+
+    // 构造 multipart body
+    const header = Buffer.from(
+        `--${boundary}\r\n` +
+        `Content-Disposition: form-data; name="media"; filename="${filename}"; filelength=${buffer.length}\r\n` +
+        `Content-Type: ${fileContentType}\r\n\r\n`
+    );
+    const footer = Buffer.from(`\r\n--${boundary}--\r\n`);
+    const body = Buffer.concat([header, buffer, footer]);
+
+    console.log(`[wecom-upload] Multipart body size=${body.length}, boundary=${boundary}, fileContentType=${fileContentType}`);
+
+    const res = await fetch(url, {
+        method: "POST",
+        headers: {
+            "Content-Type": `multipart/form-data; boundary=${boundary}`,
+            "Content-Length": String(body.length),
+        },
+        body: body,
+        signal: AbortSignal.timeout(LIMITS.REQUEST_TIMEOUT_MS),
+    });
+    const json = await res.json() as { media_id?: string; errcode?: number; errmsg?: string };
+
+    // DEBUG: 输出完整响应
+    console.log(`[wecom-upload] Response:`, JSON.stringify(json));
+
+    if (!json?.media_id) {
+        throw new Error(`upload failed: ${json?.errcode} ${json?.errmsg}`);
+    }
+    return json.media_id;
+}
+
+/**
+ * 发送媒体消息
+ */
+export async function sendMedia(params: {
+    agent: ResolvedAgentAccount;
+    toUser?: string;
+    chatId?: string;
+    mediaId: string;
+    mediaType: "image" | "voice" | "video" | "file";
+    title?: string;
+    description?: string;
+}): Promise<void> {
+    const { agent, toUser, chatId, mediaId, mediaType, title, description } = params;
+    const token = await getAccessToken(agent);
+
+    const useChat = Boolean(chatId);
+    const url = useChat
+        ? `${API_ENDPOINTS.SEND_APPCHAT}?access_token=${encodeURIComponent(token)}`
+        : `${API_ENDPOINTS.SEND_MESSAGE}?access_token=${encodeURIComponent(token)}`;
+
+    const mediaPayload = mediaType === "video"
+        ? { media_id: mediaId, title: title ?? "Video", description: description ?? "" }
+        : { media_id: mediaId };
+
+    const body = useChat
+        ? { chatid: chatId, msgtype: mediaType, [mediaType]: mediaPayload }
+        : { touser: toUser, msgtype: mediaType, agentid: agent.agentId, [mediaType]: mediaPayload };
+
+    const res = await fetch(url, {
+        method: "POST",
+        headers: { "Content-Type": "application/json" },
+        body: JSON.stringify(body),
+        signal: AbortSignal.timeout(LIMITS.REQUEST_TIMEOUT_MS),
+    });
+    const json = await res.json() as { errcode?: number; errmsg?: string };
+
+    if (json?.errcode !== 0) {
+        throw new Error(`send ${mediaType} failed: ${json?.errcode} ${json?.errmsg}`);
+    }
+}
+
+/**
+ * 下载媒体文件
+ */
+export async function downloadMedia(params: {
+    agent: ResolvedAgentAccount;
+    mediaId: string;
+}): Promise<{ buffer: Buffer; contentType: string }> {
+    const { agent, mediaId } = params;
+    const token = await getAccessToken(agent);
+    const url = `${API_ENDPOINTS.DOWNLOAD_MEDIA}?access_token=${encodeURIComponent(token)}&media_id=${encodeURIComponent(mediaId)}`;
+
+    const res = await fetch(url, {
+        signal: AbortSignal.timeout(LIMITS.REQUEST_TIMEOUT_MS),
+    });
+
+    if (!res.ok) {
+        throw new Error(`download failed: ${res.status}`);
+    }
+
+    const contentType = res.headers.get("content-type") || "application/octet-stream";
+
+    // 检查是否返回了错误 JSON
+    if (contentType.includes("application/json")) {
+        const json = await res.json() as { errcode?: number; errmsg?: string };
+        throw new Error(`download failed: ${json?.errcode} ${json?.errmsg}`);
+    }
+
+    const buffer = Buffer.from(await res.arrayBuffer());
+    return { buffer, contentType };
+}