merge: release/20260519 → main (wecom v2026.5.12)

Integrates @wecom/wecom-openclaw-plugin webhook module + QR login support.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

Author: hiwepy

.gitignore

@@ -1 +1,4 @@
 node_modules
+dist/
+*.tgz
+*.srcbak

CLAUDE.md

@@ -4,22 +4,23 @@ This file provides guidance to Claude Code (claude.ai/code) when working with co
 
 ## 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.
+This is an **OpenClaw Channel Plugin** for WeCom (企业微信 / WeChat Work). It enables AI bot integration with enterprise WeChat through a multi-mode architecture.
 
-- **Package**: `@mocrane/wecom`
+- **Package**: `@partme.ai/wecom`
 - **Type**: ES Module (NodeNext)
 - **Entry**: `index.ts`
 
 ## Architecture
 
-### Dual-Mode Design (Bot + Agent)
+### Multi-Mode Design (WebSocket + Webhook Bot + Agent)
 
-The plugin implements a unique dual-mode architecture:
+The plugin implements three connection modes:
 
 | 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) |
+| **WebSocket** (Bot 长连接) | Real-time streaming chat | N/A (WS) | Streaming responses, low latency |
+| **Webhook** (Bot URL 回调) | HTTP callback for restricted networks | `/wecom`, `/wecom/bot`, `/plugins/wecom/bot` | Streaming via `response_url`, 6min window, Agent fallback |
+| **Agent** (自建应用) | Fallback & broadcast | `/wecom/agent`, `/plugins/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.
 
@@ -29,32 +30,67 @@ The plugin implements a unique dual-mode architecture:
 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
+  monitor.ts          # WebSocket message processing + backward-compat webhook handler
   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)
+  gateway-monitor.ts  # Account lifecycle: dispatch WS / webhook gateway / agent registration
+  ws-adapter.ts       # WebSocket client adapter (@wecom/aibot-node-sdk)
+
+  # ── Webhook mode (integrated from @wecom/wecom-openclaw-plugin) ──
+  webhook/
+    index.ts          # Re-exports: handler, gateway, state, helpers, types
+    handler.ts        # HTTP GET/POST handler with multi-account signature matching
+    gateway.ts        # Lifecycle: start/stop webhook targets, prune timer
+    monitor.ts        # startAgentForStream() — message processing, Agent dispatch, deliver
+    state.ts          # StreamStore + ActiveReplyStore + WebhookMonitorState (singleton)
+    helpers.ts        # buildInboundBody, processInboundMessage, buildFallbackPrompt, MIME detect
+    types.ts          # WebhookInboundMessage, StreamState, PendingInbound, WecomWebhookTarget
+    target.ts         # Path-indexed target registry (register/unregister/resolve)
+    http.ts           # undici fetch wrapper with ProxyAgent
+    media.ts          # AES-256-CBC media decryption (decryptWecomMediaWithMeta)
+    command-auth.ts   # DM policy + command authorization
+    video-frame.ts    # ffmpeg first-frame extraction for video messages
+
   agent/
     api-client.ts     # WeCom API client with AccessToken caching
     handler.ts        # XML webhook handler for Agent mode
+    webhook.ts        # Agent HTTP handler (GET echostr verify, POST XML decrypt)
   config/
     schema.ts         # Zod schemas for configuration
+    accounts.ts       # Account resolution, mode detection, conflict checking
+    network.ts        # Proxy resolution chain
+    routing.ts        # Fail-closed routing policy
   monitor/
-    state.ts          # StreamStore and ActiveReplyStore with TTL pruning
-  types/constants.ts  # API endpoints and limits
+    state.ts          # StreamStore and ActiveReplyStore (WebSocket mode)
+    types.ts          # StreamState, PendingInbound types
+  mcp/                # wecom_mcp tool: JSON-RPC over Streamable HTTP
+  crypto/             # AES-256-CBC, SHA1 signature, XML encrypt/decrypt
+  media/              # Media uploader, constants
+  shared/             # XML parser, command auth utilities
+  types/              # TypeScript types: config, account, message, constants
+  compat/             # SDK version compatibility shim
 ```
 
 ### Stream State Management
 
-The plugin uses a sophisticated stream state system (`src/monitor/state.ts`):
+The plugin uses sophisticated stream state systems for both modes:
 
+**WebSocket mode** (`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
+- Exports `getSessionChatInfo()` for MCP tool context (preserves original-case chatId)
+
+**Webhook mode** (`src/webhook/state.ts`):
+- Separate singleton (`WebhookMonitorState`) with same StreamStore + ActiveReplyStore pattern
+- Additional `conversationState`/`batchKey`/`ackStream` queue semantics for multi-message merge
+- Used by `webhook/gateway.ts` and `webhook/monitor.ts`
 
 ### Token Management
 
@@ -67,23 +103,23 @@ Agent mode uses automatic AccessToken caching (`src/agent/api-client.ts`):
 
 ### Testing
 
-This project uses **Vitest**. Tests extend from a base config at `../../vitest.config.ts`:
+This project uses **Vitest**:
 
 ```bash
 # Run all tests
-npx vitest --config vitest.config.ts
+npx vitest --config vitest.config.ts run
 
 # Run specific test file
-npx vitest --config vitest.config.ts src/crypto.test.ts
+npx vitest --config vitest.config.ts run src/crypto.test.ts
 
 # Run tests matching pattern
-npx vitest --config vitest.config.ts --testNamePattern="should encrypt"
+npx vitest --config vitest.config.ts run -t "should encrypt"
 
 # Watch mode
 npx vitest --config vitest.config.ts --watch
 ```
 
-Test files are located alongside source files with `.test.ts` suffix:
+Test files are located alongside source files with `.test.ts` suffix (16 test files total):
 - `src/crypto.test.ts`
 - `src/monitor.integration.test.ts`
 - `src/monitor/state.queue.test.ts`
@@ -97,7 +133,7 @@ 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.
+The plugin is loaded directly as TypeScript by OpenClaw. No build step is required for development, but type checking is recommended. For distribution, use `npm pack`.
 
 ## Configuration Schema
 
@@ -107,6 +143,11 @@ Configuration is validated via Zod (`src/config/schema.ts`):
 {
   enabled: boolean,
   bot: {
+    connectionMode: 'websocket' | 'webhook',
+    // WebSocket mode:
+    botId: string,
+    secret: string,
+    // Webhook mode:
     token: string,              // Bot webhook token
     encodingAESKey: string,     // AES encryption key
     receiveId: string?,         // Optional receive ID
@@ -123,11 +164,14 @@ Configuration is validated via Zod (`src/config/schema.ts`):
     welcomeText: string?,
     dm: { policy, allowFrom }
   },
+  accounts: {                   // Multi-account (matrix mode)
+    main: { bot: {...}, agent: {...} }
+  },
   network: {
     egressProxyUrl: string?     // For dynamic IP scenarios
   },
   media: {
-    maxBytes: number?           // Default 25MB
+    maxBytes: number?           // Default 20MB
   },
   dynamicAgents: {
     enabled: boolean?           // Enable per-user/per-group agents
@@ -160,23 +204,23 @@ Dynamic agents are automatically added to `agents.list` in the config file.
 
 ### 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`
+- **Signature Verification**: SHA1(token, timestamp, nonce, encrypt) via `@wecom/aibot-node-sdk` WecomCrypto
+- **Encryption**: AES-256-CBC with PKCS#7 padding (32-byte blocks)
+- **Paths**: `/wecom` (legacy), `/wecom/bot` (bot), `/wecom/agent` (agent), `/plugins/wecom/bot/*`, `/plugins/wecom/agent/*`
 
 ### Timeout Handling
 
-Bot mode has a 6-minute window (360s) for streaming responses. The plugin:
+Bot webhook 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
+- **Inbound**: Decrypts WeCom encrypted media URLs (AES-256-CBC)
 - **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`)
+- **Max Size**: 20MB default (configurable via `channels.wecom.media.maxBytes`)
 
 ### Proxy Support
 
@@ -186,9 +230,13 @@ For servers with dynamic IPs (common error: `60020 not allow to access from your
 openclaw config set channels.wecom.network.egressProxyUrl "http://proxy.company.local:3128"
 ```
 
+### message tool denial
+
+`buildCfgForDispatch()` in `webhook/helpers.ts` adds `"message"` to `tools.deny` to prevent Agent from bypassing Bot delivery via the message tool.
+
 ## Testing Notes
 
-- Tests use Vitest with `../../vitest.config.ts` as base
+- Tests use Vitest with co-located test files
 - Integration tests mock WeCom API responses
 - Crypto tests verify AES encryption round-trips
 - Monitor tests cover stream state transitions and queue behavior
@@ -197,7 +245,7 @@ openclaw config set channels.wecom.network.egressProxyUrl "http://proxy.company.
 
 ### Adding a New Message Type Handler
 
-1. Update `buildInboundBody()` in `src/monitor.ts` to parse the message
+1. Update `buildInboundBody()` in `src/webhook/helpers.ts` or `src/monitor.ts` to parse the message
 2. Add type definitions in `src/types/message.ts`
 3. Update `processInboundMessage()` if media handling is needed
 
@@ -225,14 +273,17 @@ streamStore.updateStream(streamId, (state) => {
 
 ## Dependencies
 
+- `@wecom/aibot-node-sdk`: Official WeCom Bot WebSocket SDK + crypto
 - `undici`: HTTP client with proxy support
 - `fast-xml-parser`: XML parsing for Agent callbacks
+- `file-type`: MIME type detection from file buffers
 - `zod`: Configuration validation
 - `openclaw`: Peer dependency (>=2026.2.24)
 
 ## 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`
+- `SEND_APPCHAT`: `https://qyapi.weixin.qq.com/cgi-bin/appchat/send`
 - `UPLOAD_MEDIA`: `https://qyapi.weixin.qq.com/cgi-bin/media/upload`
 - `DOWNLOAD_MEDIA`: `https://qyapi.weixin.qq.com/cgi-bin/media/get`

MIGRATION_SCOPE.md

@@ -2,7 +2,7 @@
 
 ## 背景
 
-| | 官方插件 `@tencent/wecom-openclaw-plugin` | 本项目 `@mocrane/wecom` |
+| | 官方插件 `@tencent/wecom-openclaw-plugin` | 本项目 `@partme.ai/wecom` |
 |---|---|---|
 | **支持的 Bot 模式** | WebSocket 长连接（唯一） | WebSocket + **Webhook (URL 回调)** |
 | **支持 Agent 模式** | 否 | **是**（自建应用，XML 回调 + API 回复） |

README.md

@@ -81,10 +81,12 @@
 ### 1.1 安装插件
 
 ```bash
-openclaw plugins install @mocrane/wecom
+openclaw plugins install @partme.ai/wecom
 openclaw plugins enable wecom
 ```
 
+
+
 也可以通过命令行向导快速配置：
 
 ```bash

index.ts

@@ -1,10 +1,15 @@
 import type { OpenClawPluginApi } from "openclaw/plugin-sdk";
+import type { OpenClawPluginToolContext } from "openclaw/plugin-sdk/plugin-entry";
 import { emptyPluginConfigSchema, ensureConfigHelpers } from "./src/compat/plugin-sdk-shim.js";
 
-import { handleWecomWebhookRequest } from "./src/monitor.js";
-import { setWecomRuntime } from "./src/runtime.js";
+import { handleWeComWebhookRequest } from "./src/monitor.js";
+import { handleWecomWebhookRequest as handleWecomBotWebhook } from "./src/webhook/index.js";
+import { setWeComRuntime } from "./src/runtime.js";
 import { wecomPlugin } from "./src/channel.js";
 import { createWeComMcpTool } from "./src/mcp/index.js";
+import { getSessionChatInfo } from "./src/monitor/state.js";
+import { createWeComAgentWebhookHandler } from "./src/agent/webhook.js";
+import { CHANNEL_ID, WEBHOOK_PATHS } from "./src/types/constants.js";
 
 const plugin = {
   id: "wecom",
@@ -27,20 +32,61 @@ const plugin = {
     // 有充足的异步间隙）。
     void ensureConfigHelpers();
 
-    setWecomRuntime(api.runtime);
+    setWeComRuntime(api.runtime);
     api.registerChannel({ plugin: wecomPlugin });
+
+    // ── Agent webhook HTTP 路由 ────────────────────────────────────────
+    const agentWebhookHandler = createWeComAgentWebhookHandler(api.runtime);
+    const agentRoutes = [WEBHOOK_PATHS.AGENT_PLUGIN, WEBHOOK_PATHS.AGENT];
+    for (const path of agentRoutes) {
+      api.registerHttpRoute({
+        path,
+        handler: agentWebhookHandler,
+        auth: "plugin",
+        match: "prefix",
+      });
+    }
+
+    // ── Bot webhook HTTP 路由（新 webhook 模块，支持多账号签名匹配） ──
+    const botWebhookRoutes = [WEBHOOK_PATHS.BOT_PLUGIN, WEBHOOK_PATHS.BOT_ALT, WEBHOOK_PATHS.BOT];
+    for (const routePath of botWebhookRoutes) {
+      api.registerHttpRoute({
+        path: routePath,
+        handler: handleWecomBotWebhook,
+        auth: "plugin",
+        match: "prefix",
+      });
+    }
+
+    // ── 历史兼容路由（保留 monitor.ts 统一入口） ─────────────────────
     const routes = ["/plugins/wecom", "/wecom"];
     for (const path of routes) {
       api.registerHttpRoute({
         path,
-        handler: handleWecomWebhookRequest,
+        handler: handleWeComWebhookRequest,
         auth: "plugin",
         match: "prefix",
       });
     }
 
     // 注册 wecom_mcp：通过 HTTP 直接调用企业微信 MCP Server
-    api.registerTool(createWeComMcpTool(), { name: "wecom_mcp" });
+    // 使用 factory 函数，每次调用时从 sessionKey 获取原始大小写的 chatId/chatType，
+    // 避免 OpenClaw core 小写化 sessionKey 导致企业微信 API 报 invalid chatid
+    api.registerTool(
+      (ctx: OpenClawPluginToolContext) => {
+        const trustedRequesterUserId =
+          ctx.messageChannel === CHANNEL_ID ? ctx.requesterSenderId?.trim() ?? undefined : undefined;
+
+        const sessionChat = getSessionChatInfo(ctx.sessionKey);
+        return createWeComMcpTool({
+          requesterUserId: trustedRequesterUserId,
+          accountId: ctx.agentAccountId,
+          chatId: sessionChat?.chatId,
+          chatType: sessionChat?.chatType,
+        });
+      },
+      { name: "wecom_mcp" },
+    );
 
     // 注入媒体发送指令和文件大小限制提示词（与官方 @wecom/wecom-openclaw-plugin 保持一致）。
     // 仅 wecom 通道注入，避免污染其他通道（如 Telegram/Discord）的 system prompt。
@@ -69,6 +115,9 @@ const plugin = {
           "- 语音消息仅支持 AMR 格式（.amr），如需发送语音请确保文件为 AMR 格式",
           "- 超过大小限制的图片/视频/语音会被自动转为文件格式发送",
           "- 如果文件超过 20MB，将无法发送，请提前告知用户并尝试缩减文件大小",
+          "",
+          "【发送模板卡片消息】",
+          "当需要向用户发送结构化卡片消息（如通知、投票、按钮选择等）时，请在回复中直接输出 JSON 代码块（```json ... ```），其中 card_type 字段标明卡片类型。详见 wecom-send-template-card 技能。",
         ].join("\n"),
       };
     });

openclaw.plugin.json

@@ -6,6 +6,15 @@
     "type": "object",
     "additionalProperties": false,
     "properties": {}
+  },
+  "channelConfigs": {
+    "wecom": {
+      "configSchema": {
+        "type": "object",
+        "additionalProperties": true,
+        "properties": {}
+      }
+    }
   }
 }