@yanhaidao/wecom 2.2.4 → 2.2.7

package/.claude/settings.local.json

@@ -0,0 +1,11 @@
+{
+  "permissions": {
+    "allow": [
+      "Bash(npx tsc:*)",
+      "Bash(./node_modules/.bin/tsc:*)",
+      "Bash(npm install)",
+      "Bash(npx vitest:*)",
+      "Bash(node --input-type=module -e:*)"
+    ]
+  }
+}

package/CLAUDE.md

@@ -0,0 +1,238 @@
+# CLAUDE.md
+
+This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
+
+## Project Overview
+
+This is an **OpenClaw Channel Plugin** for WeCom (企业微信 / WeChat Work). It enables AI bot integration with enterprise WeChat through a dual-mode architecture.
+
+- **Package**: `@yanhaidao/wecom`
+- **Type**: ES Module (NodeNext)
+- **Entry**: `index.ts`
+
+## Architecture
+
+### Dual-Mode Design (Bot + Agent)
+
+The plugin implements a unique dual-mode architecture:
+
+| Mode | Purpose | Webhook Path | Capabilities |
+|------|---------|--------------|--------------|
+| **Bot** (智能体) | Real-time streaming chat | `/wecom`, `/wecom/bot` | Streaming responses, low latency, text/image only |
+| **Agent** (自建应用) | Fallback & broadcast | `/wecom/agent` | File sending, broadcasts, long tasks (>6min) |
+
+**Key Design Principle**: Bot is preferred for conversations; Agent is used as fallback when Bot cannot deliver (files, timeouts) or for proactive broadcasts.
+
+### Core Components
+
+```
+index.ts              # Plugin entry - registers channel and HTTP handlers
+src/
+  channel.ts          # ChannelPlugin implementation, lifecycle management
+  monitor.ts          # Core webhook handler, message flow, stream state
+  runtime.ts          # Runtime state singleton
+  http.ts             # HTTP client with undici + proxy support
+  crypto.ts           # AES-CBC encryption/decryption for webhooks
+  media.ts            # Media file download/decryption
+  outbound.ts         # Outbound message adapter
+  target.ts           # Target resolution (user/party/tag/chat)
+  dynamic-agent.ts    # Dynamic agent routing (per-user/per-group isolation)
+  agent/
+    api-client.ts     # WeCom API client with AccessToken caching
+    handler.ts        # XML webhook handler for Agent mode
+  config/
+    schema.ts         # Zod schemas for configuration
+  monitor/
+    state.ts          # StreamStore and ActiveReplyStore with TTL pruning
+  types/constants.ts  # API endpoints and limits
+```
+
+### Stream State Management
+
+The plugin uses a sophisticated stream state system (`src/monitor/state.ts`):
+
+- **StreamStore**: Manages message streams with 6-minute timeout window
+- **ActiveReplyStore**: Tracks `response_url` for proactive pushes
+- **Pending Queue**: Debounces rapid messages (500ms default)
+- **Message Deduplication**: Uses `msgid` to prevent duplicate processing
+
+### Token Management
+
+Agent mode uses automatic AccessToken caching (`src/agent/api-client.ts`):
+- Token cached with 60-second refresh buffer
+- Automatic retry on expiration
+- Thread-safe refresh deduplication
+
+## Development Commands
+
+### Testing
+
+This project uses **Vitest**. Tests extend from a base config at `../../vitest.config.ts`:
+
+```bash
+# Run all tests
+npx vitest --config vitest.config.ts
+
+# Run specific test file
+npx vitest --config vitest.config.ts src/crypto.test.ts
+
+# Run tests matching pattern
+npx vitest --config vitest.config.ts --testNamePattern="should encrypt"
+
+# Watch mode
+npx vitest --config vitest.config.ts --watch
+```
+
+Test files are located alongside source files with `.test.ts` suffix:
+- `src/crypto.test.ts`
+- `src/monitor.integration.test.ts`
+- `src/monitor/state.queue.test.ts`
+- etc.
+
+### Type Checking
+
+```bash
+npx tsc --noEmit
+```
+
+### Build
+
+The plugin is loaded directly as TypeScript by OpenClaw. No build step is required for development, but type checking is recommended.
+
+## Configuration Schema
+
+Configuration is validated via Zod (`src/config/schema.ts`):
+
+```typescript
+{
+  enabled: boolean,
+  bot: {
+    token: string,              // Bot webhook token
+    encodingAESKey: string,     // AES encryption key
+    receiveId: string?,         // Optional receive ID
+    streamPlaceholderContent: string?,  // "Thinking..."
+    welcomeText: string?,
+    dm: { policy, allowFrom }
+  },
+  agent: {
+    corpId: string,
+    corpSecret: string,
+    agentId: number,
+    token: string,              // Callback token
+    encodingAESKey: string,     // Callback AES key
+    welcomeText: string?,
+    dm: { policy, allowFrom }
+  },
+  network: {
+    egressProxyUrl: string?     // For dynamic IP scenarios
+  },
+  media: {
+    maxBytes: number?           // Default 25MB
+  },
+  dynamicAgents: {
+    enabled: boolean?           // Enable per-user/per-group agents
+    dmCreateAgent: boolean?     // Create agent per DM user
+    groupEnabled: boolean?      // Enable for group chats
+    adminUsers: string[]?       // Admin users (bypass dynamic routing)
+  }
+}
+```
+
+### Dynamic Agent Routing
+
+When `dynamicAgents.enabled` is `true`, the plugin automatically creates isolated Agent instances for each user/group:
+
+```bash
+# Enable dynamic agents
+openclaw config set channels.wecom.dynamicAgents.enabled true
+
+# Configure admin users (use main agent)
+openclaw config set channels.wecom.dynamicAgents.adminUsers '["admin1","admin2"]'
+```
+
+**Generated Agent ID format**: `wecom-{type}-{peerId}`
+- DM: `wecom-dm-zhangsan`
+- Group: `wecom-group-wr123456`
+
+Dynamic agents are automatically added to `agents.list` in the config file.
+
+## Key Technical Details
+
+### Webhook Security
+
+- **Signature Verification**: HMAC-SHA256 with token
+- **Encryption**: AES-CBC with PKCS#7 padding (32-byte blocks)
+- **Paths**: `/wecom` (legacy), `/wecom/bot`, `/wecom/agent`
+
+### Timeout Handling
+
+Bot mode has a 6-minute window (360s) for streaming responses. The plugin:
+- Tracks deadline: `createdAt + 6 * 60 * 1000`
+- Switches to Agent fallback at `deadline - 30s` margin
+- Sends DM via Agent for remaining content
+
+### Media Handling
+
+- **Inbound**: Decrypts WeCom encrypted media URLs
+- **Outbound Images**: Base64 encoded via `msg_item` in stream
+- **Outbound Files**: Requires Agent mode, sent via `media/upload` + `message/send`
+- **Max Size**: 25MB default (configurable via `channels.wecom.media.maxBytes`)
+
+### Proxy Support
+
+For servers with dynamic IPs (common error: `60020 not allow to access from your ip`):
+
+```bash
+openclaw config set channels.wecom.network.egressProxyUrl "http://proxy.company.local:3128"
+```
+
+## Testing Notes
+
+- Tests use Vitest with `../../vitest.config.ts` as base
+- Integration tests mock WeCom API responses
+- Crypto tests verify AES encryption round-trips
+- Monitor tests cover stream state transitions and queue behavior
+
+## Common Patterns
+
+### Adding a New Message Type Handler
+
+1. Update `buildInboundBody()` in `src/monitor.ts` to parse the message
+2. Add type definitions in `src/types/message.ts`
+3. Update `processInboundMessage()` if media handling is needed
+
+### Agent API Calls
+
+Always use `api-client.ts` methods which handle token management:
+
+```typescript
+import { sendText, uploadMedia } from "./agent/api-client.js";
+
+// Token is automatically cached and refreshed
+await sendText({ agent, toUser: "userid", text: "Hello" });
+```
+
+### Stream Content Updates
+
+Use `streamStore.updateStream()` for thread-safe updates:
+
+```typescript
+streamStore.updateStream(streamId, (state) => {
+  state.content = "new content";
+  state.finished = true;
+});
+```
+
+## Dependencies
+
+- `undici`: HTTP client with proxy support
+- `fast-xml-parser`: XML parsing for Agent callbacks
+- `zod`: Configuration validation
+- `openclaw`: Peer dependency (>=2026.1.26)
+
+## WeCom API Endpoints Used
+
+- `GET_TOKEN`: `https://qyapi.weixin.qq.com/cgi-bin/gettoken`
+- `SEND_MESSAGE`: `https://qyapi.weixin.qq.com/cgi-bin/message/send`
+- `UPLOAD_MEDIA`: `https://qyapi.weixin.qq.com/cgi-bin/media/upload`
+- `DOWNLOAD_MEDIA`: `https://qyapi.weixin.qq.com/cgi-bin/media/get`

package/README.md

@@ -44,23 +44,16 @@
 
 ---
 
-<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>
-
-
 
 ## 📊 模式能力对比
 
 | 能力维度 | 🤖 Bot 模式 | 🧩 Agent 模式 | ✨ **本插件 (双模)** |
-|:---|:---:|:---:|:---:|
-| **流式响应** | ✅ 原生支持 | ❌ 不支持 | **✅ 完美支持** |
-| **发送文件/图** | ❌ 不支持 | ✅ 支持 | **✅ 自动切换** |
-| **主动推送** | ❌ 仅回调 | ✅ 随时推送 | **✅ 完整 API** |
-| **Cronjob 定时** | ❌ 仅回调 | ✅ 支持 | **✅ 完美集成** |
-| **接收语音** | ✅ 转文字 | ✅ 语音+文字 | **✅ 双路处理** |
-| **群聊支持** | ✅ @即回 | ⚠️ 仅自建群 | **✅ 混合支持** |
+|:---|:---|:---|:---|
+| **接收消息 (单聊)** | ✅ 文本/图片/语音/文件 | ✅ 文本/图片/语音/视频/位置/链接 | **✅ 全能互补** (覆盖所有类型) |
+| **接收消息 (群聊)** | ✅ 文本/引用 | ❌ 不支持 (无回调) | **✅ 文本/引用** |
+| **发送消息** | ❌ 仅支持文本/图片/Markdown | ✅ **全格式支持** (文本/图片/视频/文件等) | **✅ 智能路由** (自动切换) |
+| **流式响应** | ✅ **支持** (打字机效果) | ❌ 不支持 | **✅ 完美支持** |
+| **主动推送** | ❌ 仅被动回复 | ✅ **支持** (指定用户/部门/标签) | **✅ 完整 API** |
 
 ---
 
@@ -89,8 +82,13 @@ 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 '[]' 
+# DM 门禁（推荐显式设置 policy）
+# - open: 默认放开（所有人可用）
+# - disabled: 全部禁用
+# - allowlist: 仅 allowFrom 允许的人可用
+openclaw config set channels.wecom.bot.dm.policy "open"
+# policy=allowlist 时生效（例如只允许某些 userid；"*" 表示允许所有人）
+openclaw config set channels.wecom.bot.dm.allowFrom '["*"]'
 ```
 
 ### 3. 配置 Agent 模式（自建应用，可选）
@@ -103,8 +101,8 @@ 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 '[]'
+openclaw config set channels.wecom.agent.dm.policy "open"
+openclaw config set channels.wecom.agent.dm.allowFrom '["*"]'
 ```
 
 ### 4. 高级网络配置 (公网出口代理)
@@ -317,9 +315,15 @@ Agent 输出 `{"template_card": ...}` 时自动渲染为交互卡片：
 **Q4: 群里 @机器人 发送文件失败？**
 > **A:** 因为企业微信 Bot 接口本身不支持发送非图片文件。我们的解决方案是：自动检测到文件发送需求后，改为通过 Agent 私信该用户发送文件，并在群里给出 "文件已私信发给您" 的提示。
 
-**Q5: Cronjob 定时任务怎么发给群？**
+**Q5: 为什么在 Agent 模式下发送文件（如 PDF、Word）给机器人没有反应？**
+> **A:** 这是由于企业微信官方接口限制。自建应用（Agent）的消息回调接口仅支持：文本、图片、语音、视频、位置和链接信息。**不支持**通用文件（File）类型的回调，因此插件无法感知您发送的文件。
+
+**Q6: Cronjob 定时任务怎么发给群？**
 > **A:** Cronjob 必须走 Agent 通道（Bot 无法主动发消息）。您只需在配置中指定 `to: "party:1"` (部门) 或 `to: "group:wr123..."` (外部群)，即可实现定时推送到群。
 
+**Q7: 为什么发视频给 Bot 没反应？**
+> **A:** 官方 Bot 接口**不支持接收视频**。如果您需要处理视频内容，请配置并使用 Agent 模式（Agent 支持接收视频）。
+
 ---
 
 ## 联系我
@@ -334,12 +338,26 @@ Agent 输出 `{"template_card": ...}` 时自动渲染为交互卡片：
 
 ## 更新日志
 
+### 2026.2.7
+
+- ✨ **动态 Agent 路由**：新增按用户/群组隔离的动态路由功能，支持为每个对话主体自动分配独立的 Agent 实例（如 `wecom-dm-xxx`）。
+- 🛠 **自动注册机制**：动态生成的 Agent 会自动异步注册到 `agents.list` 配置中，实现多租户 Agent 的无感扩容与管理。
+- 🛡 **权限与兼容性**：支持 `adminUsers` 白名单绕过机制以使用主 Agent；功能默认关闭，确保对现有配置完全兼容。
+- ⚙️ **精细化配置**：新增 `channels.wecom.dynamicAgents` 配置项，可独立控制私聊和群聊的动态路由行为。
+- 🙏 **特别致谢**：感谢 [WhyMeta](https://github.com/WhyMeta) 开发者对动态路由实施方案的贡献。
+
+### 2026.2.5
+
+- 🛠 **体验优化**：WeCom 媒体（图片/语音/视频/文件）处理的默认大小上限提升到 25MB，减少大文件因超限导致的“下载/保存失败”。
+- 📌 **可配置提示**：若仍遇到 Media exceeds ... limit，日志/回复会提示通过 channels.wecom.media.maxBytes 调整上限，并给出可直接执行的 openclaw config set 示例命令。
+
 ### 2026.2.4
 
 - 🚀 **架构升级**：实施 "Bot 优先 + Agent 兜底" 策略，兼顾流式体验与长任务稳定性（6分钟切换）。
-- ✨ **全模态支持**：Agent 模式完整支持接收与发送图片、文件、语音、视频。
+- ✨ **全模态支持**：Agent 模式完整支持接收图片/语音/视频（文件仅支持发送）。
 - ✨ **Cronjob 增强**：支持向部门 (`party:ID`) 和标签 (`tag:ID`) 广播消息。
 - 🛠 **Monitor 重构**：统一的消息防抖与流状态管理，提升并发稳定性。
+- 🛠 **体验优化**：修复企微重试导致的重复回复（Bot/Agent 均做 `msgid` 去重）；优化 Bot 连续多条消息的排队/合并回执，避免“重复同一答案”或“消息失败提示”。
 - 🐞 **修复**：Outbound ID 解析逻辑及 API 客户端参数缺失问题。
 
 ### 2026.2.3

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@yanhaidao/wecom",
-  "version": "2.2.4",
+  "version": "2.2.7",
   "type": "module",
   "description": "OpenClaw WeCom (WeChat Work) intelligent bot channel plugin",
   "author": "YanHaidao (VX: YanHaidao)",
@@ -43,4 +43,4 @@
     "@types/node": "^25.2.0",
     "typescript": "^5.9.3"
   }
-}
+}

package/scripts/test-proxy.ts

@@ -0,0 +1,70 @@
+import { wecomFetch } from "../src/http.js";
+
+const args = process.argv.slice(2);
+let proxyUrl = "";
+
+if (args.includes("--host")) {
+    const hostIndex = args.indexOf("--host");
+    const portIndex = args.indexOf("--port");
+    const userIndex = args.indexOf("--user");
+    const passIndex = args.indexOf("--pass");
+
+    if (hostIndex === -1 || portIndex === -1) {
+        console.error("Error: --host and --port are required when using specific params.");
+        process.exit(1);
+    }
+
+    const host = args[hostIndex + 1];
+    const port = args[portIndex + 1];
+    const user = userIndex !== -1 ? args[userIndex + 1] : "";
+    const pass = passIndex !== -1 ? args[passIndex + 1] : "";
+
+    if (user && pass) {
+        // Safe encoding
+        proxyUrl = `http://${encodeURIComponent(user)}:${encodeURIComponent(pass)}@${host}:${port}`;
+    } else {
+        proxyUrl = `http://${host}:${port}`;
+    }
+} else {
+    proxyUrl = args[0] || process.env.PROXY_URL || "";
+}
+
+if (!proxyUrl) {
+  console.error("Usage: npx tsx extensions/wecom/scripts/test-proxy.ts <proxy_url>");
+  console.error("   OR: npx tsx extensions/wecom/scripts/test-proxy.ts --host <ip> --port <port> --user <u?> --pass <p?>");
+  process.exit(1);
+}
+
+console.log(`Testing proxy: ${proxyUrl.replace(/:([^:@]+)@/, ":***@")}`); // Mask password in log
+
+async function run() {
+  try {
+    // 1. Test IP echo to verify traffic goes through proxy
+    console.log("1. Checking IP via httpbin.org...");
+    const ipRes = await wecomFetch("https://httpbin.org/ip", {}, { proxyUrl, timeoutMs: 10000 });
+    if (!ipRes.ok) {
+        throw new Error(`IP check failed: ${ipRes.status} ${ipRes.statusText}`);
+    }
+    const ipJson = await ipRes.json();
+    console.log("   Result:", ipJson);
+
+    // 2. Test WeCom API connectivity
+    console.log("2. Checking WeCom connectivity...");
+    const wecomRes = await wecomFetch("https://qyapi.weixin.qq.com/cgi-bin/gettoken", {}, { proxyUrl, timeoutMs: 10000 });
+    const wecomJson = await wecomRes.json();
+    console.log("   Result:", wecomJson);
+    console.log("✅ Proxy works!");
+
+  } catch (err) {
+    // Extract cause for better debugging
+    const cause = (err as any).cause;
+    if (cause) {
+        console.error("❌ Proxy test failed (Cause):", cause);
+    } else {
+        console.error("❌ Proxy test failed:", err);
+    }
+    process.exit(1);
+  }
+}
+
+run();

package/src/agent/api-client.ts

@@ -118,11 +118,26 @@ export async function sendText(params: {
         headers: { "Content-Type": "application/json" },
         body: JSON.stringify(body),
     }, { proxyUrl: resolveWecomEgressProxyUrlFromNetwork(agent.network), timeoutMs: LIMITS.REQUEST_TIMEOUT_MS });
-    const json = await res.json() as { errcode?: number; errmsg?: string };
+    const json = await res.json() as {
+        errcode?: number;
+        errmsg?: string;
+        invaliduser?: string;
+        invalidparty?: string;
+        invalidtag?: string;
+    };
 
     if (json?.errcode !== 0) {
         throw new Error(`send failed: ${json?.errcode} ${json?.errmsg}`);
     }
+
+    if (json?.invaliduser || json?.invalidparty || json?.invalidtag) {
+        const details = [
+            json.invaliduser ? `invaliduser=${json.invaliduser}` : "",
+            json.invalidparty ? `invalidparty=${json.invalidparty}` : "",
+            json.invalidtag ? `invalidtag=${json.invalidtag}` : ""
+        ].filter(Boolean).join(", ");
+        throw new Error(`send partial failure: ${details}`);
+    }
 }
 
 /**
@@ -246,11 +261,26 @@ export async function sendMedia(params: {
         headers: { "Content-Type": "application/json" },
         body: JSON.stringify(body),
     }, { proxyUrl: resolveWecomEgressProxyUrlFromNetwork(agent.network), timeoutMs: LIMITS.REQUEST_TIMEOUT_MS });
-    const json = await res.json() as { errcode?: number; errmsg?: string };
+    const json = await res.json() as {
+        errcode?: number;
+        errmsg?: string;
+        invaliduser?: string;
+        invalidparty?: string;
+        invalidtag?: string;
+    };
 
     if (json?.errcode !== 0) {
         throw new Error(`send ${mediaType} failed: ${json?.errcode} ${json?.errmsg}`);
     }
+
+    if (json?.invaliduser || json?.invalidparty || json?.invalidtag) {
+        const details = [
+            json.invaliduser ? `invaliduser=${json.invaliduser}` : "",
+            json.invalidparty ? `invalidparty=${json.invalidparty}` : "",
+            json.invalidtag ? `invalidtag=${json.invalidtag}` : ""
+        ].filter(Boolean).join(", ");
+        throw new Error(`send ${mediaType} partial failure: ${details}`);
+    }
 }
 
 /**
@@ -263,7 +293,8 @@ export async function sendMedia(params: {
 export async function downloadMedia(params: {
     agent: ResolvedAgentAccount;
     mediaId: string;
-}): Promise<{ buffer: Buffer; contentType: string }> {
+    maxBytes?: number;
+}): Promise<{ buffer: Buffer; contentType: string; filename?: string }> {
     const { agent, mediaId } = params;
     const token = await getAccessToken(agent);
     const url = `${API_ENDPOINTS.DOWNLOAD_MEDIA}?access_token=${encodeURIComponent(token)}&media_id=${encodeURIComponent(mediaId)}`;
@@ -275,6 +306,24 @@ export async function downloadMedia(params: {
     }
 
     const contentType = res.headers.get("content-type") || "application/octet-stream";
+    const disposition = res.headers.get("content-disposition") || "";
+    const filename = (() => {
+        // 兼容：filename="a.md" / filename=a.md / filename*=UTF-8''a%2Eb.md
+        const mStar = disposition.match(/filename\*\s*=\s*([^;]+)/i);
+        if (mStar) {
+            const raw = mStar[1]!.trim().replace(/^"(.*)"$/, "$1");
+            const parts = raw.split("''");
+            const encoded = parts.length === 2 ? parts[1]! : raw;
+            try {
+                return decodeURIComponent(encoded);
+            } catch {
+                return encoded;
+            }
+        }
+        const m = disposition.match(/filename\s*=\s*([^;]+)/i);
+        if (!m) return undefined;
+        return m[1]!.trim().replace(/^"(.*)"$/, "$1") || undefined;
+    })();
 
     // 检查是否返回了错误 JSON
     if (contentType.includes("application/json")) {
@@ -282,6 +331,6 @@ export async function downloadMedia(params: {
         throw new Error(`download failed: ${json?.errcode} ${json?.errmsg}`);
     }
 
-    const buffer = await readResponseBodyAsBuffer(res);
-    return { buffer, contentType };
+    const buffer = await readResponseBodyAsBuffer(res, params.maxBytes);
+    return { buffer, contentType, filename };
 }