@sunnoy/wecom 1.1.0 → 1.2.0

package/README.md

@@ -4,24 +4,27 @@
 
 `openclaw-plugin-wecom` is an Enterprise WeChat (WeCom) integration plugin developed for the [OpenClaw](https://github.com/openclaw/openclaw) framework. It enables seamless AI capabilities in Enterprise WeChat with advanced features.
 
-## ✨ Key Features
-
-- 🌊 **Streaming Output**: Built on WeCom's latest AI bot streaming mechanism for smooth typewriter-style responses.
-- 🤖 **Dynamic Agent Management**: Automatically creates isolated agents per direct message user or group chat, with independent workspaces and conversation contexts.
-- 👥 **Deep Group Chat Integration**: Supports group message parsing with @mention triggering.
-- 🎤 **Voice Message Support**: Automatically processes voice messages transcribed by WeCom into text for AI interaction (direct messages only).
-- 🖼️ **Image Support**: Automatic base64 encoding and sending of local images (screenshots, generated images) without requiring additional configuration.
-- 🛠️ **Command Enhancement**: Built-in commands (e.g., `/new` for new sessions, `/status` for status) with allowlist configuration.
-- 🔒 **Security & Authentication**: Full support for WeCom message encryption/decryption, URL verification, and sender validation.
-- ⚡ **High-Performance Async Processing**: Asynchronous message architecture ensures responsive gateway even during long AI inference.
-
-## 📋 Prerequisites
+## Key Features
+
+- **Streaming Output**: Built on WeCom's latest AI bot streaming mechanism for smooth typewriter-style responses.
+- **Dynamic Agent Management**: Automatically creates isolated agents per direct message user or group chat, with independent workspaces and conversation contexts.
+- **Deep Group Chat Integration**: Supports group message parsing with @mention triggering.
+- **Rich Message Types**: Handles text, image, voice, mixed (text+image), file, location, and link messages.
+- **Inbound Image Decryption**: Automatically decrypts WeCom-encrypted images using AES-256-CBC for AI vision processing.
+- **Outbound Image Support**: Automatic base64 encoding and sending of local images (screenshots, generated images) via `msg_item` API.
+- **Message Debounce**: Rapid consecutive messages from the same user are merged into a single AI request.
+- **Admin Users**: Configurable admin list that bypasses command allowlist and dynamic agent routing.
+- **Command Allowlist**: Built-in commands (e.g., `/new`, `/status`) with configurable allowlist to restrict sensitive operations.
+- **Security & Authentication**: Full support for WeCom message encryption/decryption, URL verification, and sender validation.
+- **High-Performance Async Processing**: Asynchronous message architecture ensures responsive gateway even during long AI inference.
+
+## Prerequisites
 
 - [OpenClaw](https://github.com/openclaw/openclaw) installed (version 2026.1.30+)
 - Enterprise WeChat admin access to create intelligent robot applications
 - Server address accessible from Enterprise WeChat (HTTP/HTTPS)
 
-## 🚀 Installation
+## Installation
 
 ```bash
 openclaw plugins install @sunnoy/wecom
@@ -33,7 +36,7 @@ This command will automatically:
 - Update your OpenClaw configuration
 - Register the plugin
 
-## ⚙️ Configuration
+## Configuration
 
 Add to your OpenClaw configuration file (`~/.openclaw/openclaw.json`):
 
@@ -51,6 +54,7 @@ Add to your OpenClaw configuration file (`~/.openclaw/openclaw.json`):
       "enabled": true,
       "token": "Your Token",
       "encodingAesKey": "Your EncodingAESKey",
+      "adminUsers": ["admin-userid"],
       "commands": {
         "enabled": true,
         "allowlist": ["/new", "/status", "/help", "/compact"]
@@ -67,19 +71,48 @@ Add to your OpenClaw configuration file (`~/.openclaw/openclaw.json`):
 | `plugins.entries.wecom.enabled` | boolean | Yes | Enable the plugin |
 | `channels.wecom.token` | string | Yes | WeCom bot Token |
 | `channels.wecom.encodingAesKey` | string | Yes | WeCom message encryption key (43 chars) |
+| `channels.wecom.adminUsers` | array | No | Admin user IDs (bypass command allowlist and dynamic routing) |
 | `channels.wecom.commands.allowlist` | array | No | Command allowlist |
 
-## 🔌 Enterprise WeChat Configuration
+## Enterprise WeChat Configuration
 
 1. Log in to [Enterprise WeChat Admin Console](https://work.weixin.qq.com/)
-2. Navigate to "Application Management" → "Applications" → "Create Application" → Select "Intelligent Robot"
+2. Navigate to "Application Management" > "Applications" > "Create Application" > Select "Intelligent Robot"
 3. Configure "Receive Messages":
    - **URL**: `https://your-domain.com/webhooks/wecom`
    - **Token**: Match `channels.wecom.token`
    - **EncodingAESKey**: Match `channels.wecom.encodingAesKey`
 4. Save and enable message receiving
 
-## 🤖 Dynamic Agent Routing
+## Supported Message Types
+
+| Type | Direction | Description |
+|------|-----------|-------------|
+| Text | Inbound/Outbound | Plain text messages |
+| Image | Inbound/Outbound | Encrypted images (inbound are auto-decrypted); outbound via `msg_item` base64 |
+| Voice | Inbound | Auto-transcribed by WeCom, processed as text (DM only) |
+| Mixed | Inbound | Text + image combination messages |
+| File | Inbound | File attachments (downloaded and passed to AI for analysis) |
+| Location | Inbound | Location shares (converted to text description) |
+| Link | Inbound | Shared links (title, description, URL extracted as text) |
+
+## Admin Users
+
+Admin users bypass the command allowlist and skip dynamic agent routing (routed to the main agent directly).
+
+```json
+{
+  "channels": {
+    "wecom": {
+      "adminUsers": ["user1", "user2"]
+    }
+  }
+}
+```
+
+Admin user IDs are case-insensitive and matched against the WeCom `userid` field.
+
+## Dynamic Agent Routing
 
 The plugin implements per-user/per-group agent isolation:
 
@@ -90,6 +123,7 @@ The plugin implements per-user/per-group agent isolation:
    - **Group Chats**: `wecom-group-<chatId>`
 2. OpenClaw automatically creates/reuses the corresponding agent workspace
 3. Each user/group has independent conversation history and context
+4. **Admin users** skip dynamic routing and use the main agent directly
 
 ### Advanced Configuration
 
@@ -135,7 +169,7 @@ To route all messages to the default agent:
 }
 ```
 
-## 🛠️ Command Allowlist
+## Command Allowlist
 
 Prevent regular users from executing sensitive Gateway management commands through WeCom messages.
 
@@ -156,51 +190,33 @@ Prevent regular users from executing sensitive Gateway management commands throu
 
 | Command | Description | Safety Level |
 |---------|-------------|--------------|
-| `/new` | Reset conversation, start new session | ✅ User-level |
-| `/compact` | Compress current session context | ✅ User-level |
-| `/help` | Show help information | ✅ User-level |
-| `/status` | Show Agent status | ✅ User-level |
+| `/new` | Reset conversation, start new session | User-level |
+| `/compact` | Compress current session context | User-level |
+| `/help` | Show help information | User-level |
+| `/status` | Show Agent status | User-level |
 
-> ⚠️ **Security Note**: Do not add `/gateway`, `/plugins`, or other management commands to the allowlist to prevent regular users from gaining Gateway instance admin privileges.
+> **Security Note**: Do not add `/gateway`, `/plugins`, or other management commands to the allowlist to prevent regular users from gaining Gateway instance admin privileges. Admin users configured in `adminUsers` bypass this restriction.
 
-## ❓ FAQ
+## Message Debounce
 
-### Q: What plugin ID should I use in the configuration file?
+When a user sends multiple messages in rapid succession (within 2 seconds), the plugin automatically merges them into a single AI request. This prevents multiple concurrent LLM calls for the same user and provides a more coherent response.
 
-**A:** Use the **complete plugin ID** in `plugins.entries`:
+- The first message's stream receives the AI response
+- Subsequent merged messages show a notice that they have been combined
+- Commands (messages starting with `/`) bypass debounce and are processed immediately
 
-```json
-{
-  "plugins": {
-    "entries": {
-      "wecom": { "enabled": true }  // ✅ Correct
-    }
-  }
-}
-```
-
-**Do not** use the channel id:
-```json
-{
-  "plugins": {
-    "entries": {
-      "wecom": { "enabled": true }  // ❌ Incorrect
-    }
-  }
-}
-```
-
-### Q: Why does `openclaw doctor` report warnings?
+## FAQ
 
-**A:** If you see configuration warnings, run:
+### Q: How does inbound image handling work?
 
-```bash
-openclaw doctor --fix
-```
+**A:** WeCom encrypts images sent by users with AES-256-CBC. The plugin automatically:
+1. Downloads the encrypted image from WeCom's URL
+2. Decrypts it using the configured `encodingAesKey`
+3. Saves it locally and passes it to the AI for vision analysis
 
-This will automatically fix common configuration issues.
+Mixed messages (text + images) are fully supported — text and images are extracted and sent together.
 
-### Q: How does image sending work?
+### Q: How does outbound image sending work?
 
 **A:** The plugin automatically handles images generated by OpenClaw (such as browser screenshots):
 
@@ -209,18 +225,16 @@ This will automatically fix common configuration issues.
 - **No configuration needed**: Works out of the box with tools like browser screenshot
 - Images appear when the AI completes its response (streaming doesn't support incremental image sending)
 
-**Example:**
-```
-User: "Take a screenshot of GitHub homepage"
-AI: [Takes screenshot] → Image displays properly in WeCom ✅
-```
-
 If an image fails to process (size limit, invalid format), the text response will still be delivered and an error will be logged.
 
 ### Q: Does the bot support voice messages?
 
 **A:** Yes! Voice messages in direct chats are automatically transcribed by WeCom and processed as text. No additional configuration needed.
 
+### Q: Does the bot support file messages?
+
+**A:** Yes. Files sent by users are downloaded and passed to the AI as attachments. The AI can analyze file contents (e.g., reading a PDF or parsing a code file). MIME types are auto-detected from the file extension.
+
 ### Q: How to configure auth token for public-facing OpenClaw with WeCom callbacks?
 
 **A:** WeCom bot **does not need** OpenClaw's Gateway Auth Token.
@@ -248,7 +262,7 @@ If an image fails to process (size limit, invalid format), the text response wil
    {
      "channels": {
        "wecom": {
-         "encodingAesKey": "..."  // ✅ Correct
+         "encodingAesKey": "..."
        }
      }
    }
@@ -262,7 +276,7 @@ If an image fails to process (size limit, invalid format), the text response wil
 
 3. **Check for extra spaces/newlines**: Ensure no leading/trailing whitespace in the key string
 
-## 📂 Project Structure
+## Project Structure
 
 ```
 openclaw-plugin-wecom/
@@ -270,20 +284,20 @@ openclaw-plugin-wecom/
 ├── webhook.js            # WeCom HTTP communication handler
 ├── dynamic-agent.js      # Dynamic agent routing logic
 ├── stream-manager.js     # Streaming response manager
-├── crypto.js             # WeCom encryption algorithms
-├── client.js             # Client logic
+├── image-processor.js    # Image encoding/validation for msg_item
+├── crypto.js             # WeCom encryption algorithms (message + media)
 ├── logger.js             # Logging module
-├── utils.js              # Utility functions
+├── utils.js              # Utility functions (TTL cache, deduplication)
 ├── package.json          # npm package config
 └── openclaw.plugin.json  # OpenClaw plugin manifest
 ```
 
-## 🤝 Contributing
+## Contributing
 
 We welcome contributions! Please submit Issues or Pull Requests for bugs or feature suggestions.
 
 See [CONTRIBUTING.md](./CONTRIBUTING.md) for details.
 
-## 📄 License
+## License
 
 This project is licensed under the [ISC License](./LICENSE).

package/README_ZH.md

@@ -4,24 +4,27 @@
 
 `openclaw-plugin-wecom` 是一个专为 [OpenClaw](https://github.com/openclaw/openclaw) 框架开发的企业微信（WeCom）集成插件。它允许你将强大的 AI 能力无缝接入企业微信，并支持多项高级功能。
 
-## ✨ 核心特性
-
-- 🌊 **流式输出 (Streaming)**: 基于企业微信最新的 AI 机器人流式分片机制，实现流畅的打字机式回复体验。
-- 🤖 **动态 Agent 管理**: 默认按"每个私聊用户 / 每个群聊"自动创建独立 Agent。每个 Agent 拥有独立的工作区与对话上下文，实现更强的数据隔离。
-- 👥 **群聊深度集成**: 支持群聊消息解析，可通过 @提及（At-mention）精准触发机器人响应。
-- 🎤 **语音消息支持**: 自动处理企业微信转录后的语音消息，转换为文本进行 AI 交互（仅限私聊）。
-- 🖼️ **图片支持**: 自动将本地图片（截图、生成的图像）进行 base64 编码并发送，无需额外配置。
-- 🛠️ **指令增强**: 内置常用指令支持（如 `/new` 开启新会话、`/status` 查看状态等），并提供指令白名单配置功能。
-- 🔒 **安全与认证**: 完整支持企业微信消息加解密、URL 验证及发送者身份校验。
-- ⚡ **高性能异步处理**: 采用异步消息处理架构，确保即使在长耗时 AI 推理过程中，企业微信网关也能保持高响应性。
-
-## 📋 前置要求
+## 核心特性
+
+- **流式输出 (Streaming)**: 基于企业微信最新的 AI 机器人流式分片机制，实现流畅的打字机式回复体验。
+- **动态 Agent 管理**: 默认按"每个私聊用户 / 每个群聊"自动创建独立 Agent。每个 Agent 拥有独立的工作区与对话上下文，实现更强的数据隔离。
+- **群聊深度集成**: 支持群聊消息解析，可通过 @提及（At-mention）精准触发机器人响应。
+- **丰富消息类型**: 支持文本、图片、语音、图文混排、文件、位置、链接等消息类型。
+- **入站图片解密**: 自动解密企业微信 AES-256-CBC 加密的图片，用于 AI 视觉分析。
+- **出站图片发送**: 自动将本地图片（截图、生成的图像）进行 base64 编码，通过 `msg_item` API 发送。
+- **消息防抖合并**: 同一用户在短时间内（2 秒内）连续发送的多条消息会自动合并为一次 AI 请求。
+- **管理员用户**: 可配置管理员列表，绕过指令白名单和动态 Agent 路由限制。
+- **指令白名单**: 内置常用指令支持（如 `/new`、`/status`），并提供指令白名单配置功能。
+- **安全与认证**: 完整支持企业微信消息加解密、URL 验证及发送者身份校验。
+- **高性能异步处理**: 采用异步消息处理架构，确保即使在长耗时 AI 推理过程中，企业微信网关也能保持高响应性。
+
+## 前置要求
 
 - 已安装 [OpenClaw](https://github.com/openclaw/openclaw) (版本 2026.1.30+)
 - 企业微信管理后台权限，可创建智能机器人应用
 - 可从企业微信访问的服务器地址（HTTP/HTTPS）
 
-## 🚀 安装
+## 安装
 
 ```bash
 openclaw plugins install @sunnoy/wecom
@@ -33,7 +36,7 @@ openclaw plugins install @sunnoy/wecom
 - 更新 OpenClaw 配置
 - 注册插件
 
-## ⚙️ 配置
+## 配置
 
 在 OpenClaw 配置文件（`~/.openclaw/openclaw.json`）中添加：
 
@@ -51,6 +54,7 @@ openclaw plugins install @sunnoy/wecom
       "enabled": true,
       "token": "你的 Token",
       "encodingAesKey": "你的 EncodingAESKey",
+      "adminUsers": ["管理员userid"],
       "commands": {
         "enabled": true,
         "allowlist": ["/new", "/status", "/help", "/compact"]
@@ -67,19 +71,48 @@ openclaw plugins install @sunnoy/wecom
 | `plugins.entries.wecom.enabled` | boolean | 是 | 启用插件 |
 | `channels.wecom.token` | string | 是 | 企业微信机器人 Token |
 | `channels.wecom.encodingAesKey` | string | 是 | 企业微信消息加密密钥（43 位） |
+| `channels.wecom.adminUsers` | array | 否 | 管理员用户 ID 列表（绕过指令白名单和动态路由） |
 | `channels.wecom.commands.allowlist` | array | 否 | 允许的指令白名单 |
 
-## 🔌 企业微信后台配置
+## 企业微信后台配置
 
 1. 登录[企业微信管理后台](https://work.weixin.qq.com/)
-2. 进入"应用管理" → "应用" → "创建应用" → 选择"智能机器人"
+2. 进入"应用管理" > "应用" > "创建应用" > 选择"智能机器人"
 3. 在"接收消息配置"中设置：
    - **URL**: `https://your-domain.com/webhooks/wecom`
    - **Token**: 与 `channels.wecom.token` 一致
    - **EncodingAESKey**: 与 `channels.wecom.encodingAesKey` 一致
 4. 保存配置并启用消息接收
 
-## 🤖 动态 Agent 路由
+## 支持的消息类型
+
+| 类型 | 方向 | 说明 |
+|------|------|------|
+| 文本 (text) | 收/发 | 纯文本消息 |
+| 图片 (image) | 收/发 | 入站图片自动解密；出站通过 `msg_item` base64 发送 |
+| 语音 (voice) | 收 | 企业微信自动转文字后处理（仅限私聊） |
+| 图文混排 (mixed) | 收 | 文本 + 图片混合消息 |
+| 文件 (file) | 收 | 文件附件（下载后传给 AI 分析） |
+| 位置 (location) | 收 | 位置分享（转换为文本描述） |
+| 链接 (link) | 收 | 分享链接（提取标题、描述、URL 为文本） |
+
+## 管理员用户
+
+管理员用户可以绕过指令白名单限制，并跳过动态 Agent 路由（直接路由到主 Agent）。
+
+```json
+{
+  "channels": {
+    "wecom": {
+      "adminUsers": ["user1", "user2"]
+    }
+  }
+}
+```
+
+管理员用户 ID 不区分大小写，匹配企业微信的 `userid` 字段。
+
+## 动态 Agent 路由
 
 本插件实现"按人/按群隔离"的 Agent 管理：
 
@@ -90,6 +123,7 @@ openclaw plugins install @sunnoy/wecom
    - **群聊**: `wecom-group-<chatId>`
 2. OpenClaw 自动创建/复用对应的 Agent 工作区
 3. 每个用户/群聊拥有独立的对话历史和上下文
+4. **管理员用户**跳过动态路由，直接使用主 Agent
 
 ### 高级配置
 
@@ -135,7 +169,7 @@ openclaw plugins install @sunnoy/wecom
 }
 ```
 
-## 🛠️ 指令白名单
+## 指令白名单
 
 为防止普通用户通过企业微信消息执行敏感的 Gateway 管理指令，本插件支持**指令白名单**机制。
 
@@ -156,51 +190,33 @@ openclaw plugins install @sunnoy/wecom
 
 | 指令 | 说明 | 安全级别 |
 |------|------|----------|
-| `/new` | 重置当前对话，开启全新会话 | ✅ 用户级 |
-| `/compact` | 压缩当前会话上下文 | ✅ 用户级 |
-| `/help` | 查看帮助信息 | ✅ 用户级 |
-| `/status` | 查看当前 Agent 状态 | ✅ 用户级 |
+| `/new` | 重置当前对话，开启全新会话 | 用户级 |
+| `/compact` | 压缩当前会话上下文 | 用户级 |
+| `/help` | 查看帮助信息 | 用户级 |
+| `/status` | 查看当前 Agent 状态 | 用户级 |
 
-> ⚠️ **安全提示**：不要将 `/gateway`、`/plugins` 等管理指令添加到白名单，避免普通用户获得 Gateway 实例的管理权限。
+> **安全提示**：不要将 `/gateway`、`/plugins` 等管理指令添加到白名单，避免普通用户获得 Gateway 实例的管理权限。配置在 `adminUsers` 中的管理员不受此限制。
 
-## ❓ 常见问题 (FAQ)
+## 消息防抖合并
 
-### Q: 配置文件中的插件 ID 应该使用什么？
+当用户在短时间内（2 秒内）连续发送多条消息时，插件会自动将它们合并为一次 AI 请求。这样可以避免同一用户触发多个并发的 LLM 调用，提供更连贯的回复。
 
-**A:** 在 `plugins.entries` 中，应该使用**完整的插件 ID**：
+- 第一条消息的流式通道接收 AI 回复
+- 后续被合并的消息会显示已合并的提示
+- 指令消息（以 `/` 开头）不参与防抖，会立即处理
 
-```json
-{
-  "plugins": {
-    "entries": {
-      "wecom": { "enabled": true }  // ✅ 正确
-    }
-  }
-}
-```
-
-**不要**使用 channel id：
-```json
-{
-  "plugins": {
-    "entries": {
-      "wecom": { "enabled": true }  // ❌ 错误
-    }
-  }
-}
-```
-
-### Q: 为什么 `openclaw doctor` 报告警告？
+## 常见问题 (FAQ)
 
-**A:** 如果看到配置警告，运行：
+### Q: 入站图片是怎么处理的？
 
-```bash
-openclaw doctor --fix
-```
+**A:** 企业微信使用 AES-256-CBC 加密用户发送的图片。插件会自动：
+1. 从企业微信的 URL 下载加密图片
+2. 使用配置的 `encodingAesKey` 解密
+3. 保存到本地并传给 AI 进行视觉分析
 
-这会自动修复常见的配置问题。
+图文混排消息也完全支持——文本和图片会一起提取并发送给 AI。
 
-### Q: 图片发送是如何工作的？
+### Q: 出站图片发送是如何工作的？
 
 **A:** 插件会自动处理 OpenClaw 生成的图片（如浏览器截图）：
 
@@ -209,18 +225,16 @@ openclaw doctor --fix
 - **无需配置**：开箱即用，配合浏览器截图等工具自动生效
 - 图片会在 AI 完成回复后显示（流式输出不支持增量发送图片）
 
-**示例：**
-```
-用户："帮我截个 GitHub 首页的图"
-AI：[执行截图] → 图片在企业微信中正常显示 ✅
-```
-
 如果图片处理失败（超出大小限制、格式不支持等），文本回复仍会正常发送，错误信息会记录在日志中。
 
 ### Q: 机器人支持语音消息吗？
 
 **A:** 支持！私聊中的语音消息会被企业微信自动转录为文字并作为文本处理，无需额外配置。
 
+### Q: 机器人支持文件消息吗？
+
+**A:** 支持。用户发送的文件会被下载并作为附件传给 AI。AI 可以分析文件内容（如读取 PDF 或解析代码文件）。MIME 类型根据文件扩展名自动检测。
+
 ### Q: OpenClaw 开放公网需要 auth token，企业微信回调如何配置？
 
 **A:** 企业微信机器人**不需要**配置 OpenClaw 的 Gateway Auth Token。
@@ -248,7 +262,7 @@ AI：[执行截图] → 图片在企业微信中正常显示 ✅
    {
      "channels": {
        "wecom": {
-         "encodingAesKey": "..."  // ✅ 正确
+         "encodingAesKey": "..."
        }
      }
    }
@@ -262,7 +276,7 @@ AI：[执行截图] → 图片在企业微信中正常显示 ✅
 
 3. **检查是否有多余空格/换行**：确保密钥字符串前后没有空格或换行符
 
-## 📂 项目结构
+## 项目结构
 
 ```
 openclaw-plugin-wecom/
@@ -270,20 +284,20 @@ openclaw-plugin-wecom/
 ├── webhook.js            # 企业微信 HTTP 通信处理
 ├── dynamic-agent.js      # 动态 Agent 分配逻辑
 ├── stream-manager.js     # 流式回复管理
-├── crypto.js             # 企业微信加密算法
-├── client.js             # 客户端逻辑
+├── image-processor.js    # 图片编码/校验（msg_item）
+├── crypto.js             # 企业微信加密算法（消息 + 媒体）
 ├── logger.js             # 日志模块
-├── utils.js              # 工具函数
+├── utils.js              # 工具函数（TTL 缓存、消息去重）
 ├── package.json          # npm 包配置
 └── openclaw.plugin.json  # OpenClaw 插件清单
 ```
 
-## 🤝 贡献规范
+## 贡献规范
 
 我们非常欢迎开发者参与贡献！如果你发现了 Bug 或有更好的功能建议，请提交 Issue 或 Pull Request。
 
 详见 [CONTRIBUTING.md](./CONTRIBUTING.md)
 
-## 📄 开源协议
+## 开源协议
 
 本项目采用 [ISC License](./LICENSE) 协议。