@yanhaidao/wecom 2.2.5 → 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/GEMINI.md

@@ -0,0 +1,76 @@
+# 企业微信 (WeCom) 插件上下文
+
+## 平台架构：机器人 (Bot) vs 自建应用 (Agent)
+
+本插件采用 **双模 (Dual-Mode)** 架构，结合了企业微信“智能机器人”和“自建应用”的优势。
+
+### 1. 定义与边界
+
+| 特性 | **Bot (智能机器人)** | **Agent (自建应用)** |
+| :--- | :--- | :--- |
+| **身份** | 虚拟用户/助手。 | 工作台中的服务应用。 |
+| **位置** | 存在于 **会话** 中 (单聊或群聊)。 | 存在于 **工作台** 或应用列表。 |
+| **协议** | **JSON** (加密)。 | **XML** (加密)。 |
+| **交互** | 对话式 (回复用户)。 | 事务式 (通知用户/系统)。 |
+| **流式 (Stream)** | ✅ **支持** (打字机效果)。 | ❌ 不支持。 |
+| **文件能力** | ❌ **受限** (被动回复无法发文件)。 | ✅ **完整支持** (API 发送视频、文件、图片)。 |
+| **群聊支持** | ✅ 原生支持 (可被 @)。 | ⚠️ 受限 (仅能在自建群或通过 API 推送)。 |
+
+### 2. 通信协议
+
+#### A. Bot (智能机器人)
+*   **接收 (回调)**:
+    *   **格式**: JSON。
+    *   **单聊**: `chattype: "single"`. 无 `chatid`。`cid` = `from.userid`。
+    *   **群聊**: `chattype: "group"`. 有 `chatid`。`cid` = `chatid`。
+*   **发送 (回复)**:
+    *   **交互回复**: 使用回调中的 `response_url`。支持 `markdown`, `template_card`。**不支持文件/视频**。
+    *   **主动推送**: 使用 Webhook Key。
+
+#### B. Agent (自建应用)
+*   **接收 (回调)**:
+    *   **格式**: XML。
+    *   **结构**: `<ToUserName>`, `<FromUserName>`, `<MsgType>`, `<Content>`。
+*   **发送 (推送)**:
+    *   **API**: `message/send`。
+    *   **能力**: 支持所有媒体类型 (文件, 视频, 语音, 文本, 卡片)。
+    *   **对象**: 用户 (`touser`), 部门 (`toparty`), 标签 (`totag`)。
+
+---
+
+## 核心策略：机器人优先，智能体兜底 (接近 6 分钟切换)
+
+### 目标
+*   **默认**: 用户在 Bot 会话触发，结果在 Bot 会话内完成回复（含流式）。
+*   **兜底**: 当 Bot 因超时（接近 6 分钟限制）、异常或流式窗口结束无法完成交付时，若配置了 Agent，则由 Agent 私信触发用户发送最终结果。
+
+### 关键约束
+*   **6 分钟窗口**: 企业微信智能机器人流式链路最多维持 6 分钟。超过后连接断开。
+
+### 流程详解
+
+#### 1. 启动阶段 (Bot)
+1.  **接收消息**: 解析 JSON 回调。
+2.  **生成 StreamID**: 确定性生成 `streamId = hash(accountId + aibotid + msgid)`，防止并发重试导致重复创建流。
+3.  **快速响应**: 立即返回“已接收，处理中”或流式首包，建立连接。
+
+#### 2. 执行阶段 (Worker)
+4.  **异步处理**: 任务入队执行。
+5.  **流式刷新**: 当收到企微的“流式消息刷新”回调时，根据 `streamId` 返回最新生成的内容。
+
+#### 3. 正常交付 (Bot)
+6.  **完成**: 任务在 6 分钟内完成，发送 `finish=true` 信号结束流式消息。
+
+#### 4. 异常切换 (Agent 兜底)
+7.  **触发条件**:
+    *   **超时临界**: `now >= createdAt + 6min - 安全阈值(30s)`。
+    *   **链路中断**: Bot 刷新回调长时间未到达 (如 > 60s)。
+    *   **发送异常**: Bot 接口报错。
+8.  **切换动作**:
+    *   **状态标记**: 将任务标记为 `agent_fallback`。
+    *   **用户提示**: (可选) Bot 在群内尝试发送“结果将私信送达”。
+    *   **私信推送**: Agent 调用 `message/send` 接口，将最终结果（文本/文件）推送给触发者 `userId`。
+    *   **注意**: 即使原会话是群聊，兜底结果通常通过 Agent **私信** 发送给触发者，因为 Agent 难以直接向普通群推送消息。
+
+### 总结
+该策略确保了用户体验（首选流式）和交付可靠性（超时/发文件走 Agent）的平衡。

package/README.md

@@ -338,6 +338,14 @@ 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，减少大文件因超限导致的“下载/保存失败”。

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@yanhaidao/wecom",
-  "version": "2.2.5",
+  "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/src/agent/handler.ts

@@ -17,6 +17,7 @@ import { getWecomRuntime } from "../runtime.js";
 import type { WecomAgentInboundMessage } from "../types/index.js";
 import { buildWecomUnauthorizedCommandPrompt, resolveWecomCommandAuthorization } from "../shared/command-auth.js";
 import { resolveWecomMediaMaxBytes } from "../config/index.js";
+import { generateAgentId, shouldUseDynamicAgent, ensureDynamicAgentListed } from "../dynamic-agent.js";
 
 /** 错误提示信息 */
 const ERROR_HELP = "\n\n遇到问题？联系作者: YanHaidao (微信: YanHaidao)";
@@ -442,6 +443,26 @@ async function processAgentMessage(params: {
         peer: { kind: isGroup ? "group" : "dm", id: peerId },
     });
 
+    // ===== 动态 Agent 路由注入 =====
+    const useDynamicAgent = shouldUseDynamicAgent({
+        chatType: isGroup ? "group" : "dm",
+        senderId: fromUser,
+        config,
+    });
+
+    if (useDynamicAgent) {
+        const targetAgentId = generateAgentId(
+            isGroup ? "group" : "dm",
+            peerId
+        );
+        route.agentId = targetAgentId;
+        route.sessionKey = `agent:${targetAgentId}:${isGroup ? "group" : "dm"}:${peerId}`;
+        // 异步添加到 agents.list（不阻塞）
+        ensureDynamicAgentListed(targetAgentId, core).catch(() => {});
+        log?.(`[wecom-agent] dynamic agent routing: ${targetAgentId}, sessionKey=${route.sessionKey}`);
+    }
+    // ===== 动态 Agent 路由注入结束 =====
+
     // 构建上下文
     const fromLabel = isGroup ? `group:${peerId}` : `user:${fromUser}`;
     const storePath = core.channel.session.resolveStorePath(config.session?.store, {

package/src/config/schema.ts

@@ -92,6 +92,22 @@ const agentSchema = z.object({
     dm: dmSchema,
 }).optional();
 
+/**
+ * **dynamicAgentsSchema (动态 Agent 配置)**
+ *
+ * 控制是否按用户/群组自动创建独立 Agent 实例。
+ * @property enabled - 是否启用动态 Agent
+ * @property dmCreateAgent - 私聊是否为每个用户创建独立 Agent
+ * @property groupEnabled - 群聊是否启用动态 Agent
+ * @property adminUsers - 管理员列表（绕过动态路由）
+ */
+const dynamicAgentsSchema = z.object({
+    enabled: z.boolean().optional(),
+    dmCreateAgent: z.boolean().optional(),
+    groupEnabled: z.boolean().optional(),
+    adminUsers: z.array(z.string()).optional(),
+}).optional();
+
 /** 顶层 WeCom 配置 Schema */
 export const WecomConfigSchema = z.object({
     enabled: z.boolean().optional(),
@@ -99,6 +115,7 @@ export const WecomConfigSchema = z.object({
     agent: agentSchema,
     media: mediaSchema,
     network: networkSchema,
+    dynamicAgents: dynamicAgentsSchema,
 });
 
 export type WecomConfigInput = z.infer<typeof WecomConfigSchema>;

package/src/dynamic-agent.ts

@@ -0,0 +1,178 @@
+/**
+ * **动态 Agent 路由模块**
+ *
+ * 为每个用户/群组自动生成独立的 Agent ID，实现会话隔离。
+ * 参考: openclaw-plugin-wecom/dynamic-agent.js
+ */
+
+import type { OpenClawConfig } from "openclaw/plugin-sdk";
+
+export interface DynamicAgentConfig {
+    enabled: boolean;
+    dmCreateAgent: boolean;
+    groupEnabled: boolean;
+    adminUsers: string[];
+}
+
+/**
+ * **getDynamicAgentConfig (读取动态 Agent 配置)**
+ *
+ * 从全局配置中读取动态 Agent 配置，提供默认值。
+ */
+export function getDynamicAgentConfig(config: OpenClawConfig): DynamicAgentConfig {
+    const dynamicAgents = (config as { channels?: { wecom?: { dynamicAgents?: Partial<DynamicAgentConfig> } } })?.channels?.wecom?.dynamicAgents;
+    return {
+        enabled: dynamicAgents?.enabled ?? false,
+        dmCreateAgent: dynamicAgents?.dmCreateAgent ?? true,
+        groupEnabled: dynamicAgents?.groupEnabled ?? true,
+        adminUsers: dynamicAgents?.adminUsers ?? [],
+    };
+}
+
+/**
+ * **generateAgentId (生成动态 Agent ID)**
+ *
+ * 根据聊天类型和对端 ID 生成确定性的 Agent ID。
+ * 格式: wecom-{type}-{sanitizedPeerId}
+ * - type: dm | group
+ * - sanitizedPeerId: 小写，非字母数字下划线横线替换为下划线
+ *
+ * @example
+ * generateAgentId("dm", "ZhangSan") // "wecom-dm-zhangsan"
+ * generateAgentId("group", "wr123456") // "wecom-group-wr123456"
+ */
+export function generateAgentId(chatType: "dm" | "group", peerId: string): string {
+    const sanitized = String(peerId)
+        .toLowerCase()
+        .replace(/[^a-z0-9_-]/g, "_");
+    return `wecom-${chatType}-${sanitized}`;
+}
+
+/**
+ * **shouldUseDynamicAgent (检查是否使用动态 Agent)**
+ *
+ * 根据配置和发送者信息判断是否应使用动态 Agent。
+ * 管理员（adminUsers）始终绕过动态路由，使用主 Agent。
+ */
+export function shouldUseDynamicAgent(params: {
+    chatType: "dm" | "group";
+    senderId: string;
+    config: OpenClawConfig;
+}): boolean {
+    const { chatType, senderId, config } = params;
+    const dynamicConfig = getDynamicAgentConfig(config);
+
+    if (!dynamicConfig.enabled) {
+        return false;
+    }
+
+    // 管理员绕过动态路由
+    const sender = String(senderId).trim().toLowerCase();
+    const isAdmin = dynamicConfig.adminUsers.some(
+        (admin) => admin.trim().toLowerCase() === sender
+    );
+    if (isAdmin) {
+        return false;
+    }
+
+    if (chatType === "group") {
+        return dynamicConfig.groupEnabled;
+    }
+    return dynamicConfig.dmCreateAgent;
+}
+
+/**
+ * 内存中已确保的 Agent ID（避免重复写入）
+ */
+const ensuredDynamicAgentIds = new Set<string>();
+
+/**
+ * 写入队列（避免并发冲突）
+ */
+let ensureDynamicAgentWriteQueue: Promise<void> = Promise.resolve();
+
+/**
+ * 将 Agent ID 插入 agents.list（如果不存在）
+ */
+function upsertAgentIdOnlyEntry(cfg: Record<string, unknown>, agentId: string): boolean {
+    if (!cfg.agents || typeof cfg.agents !== "object") {
+        cfg.agents = {};
+    }
+
+    const agentsObj = cfg.agents as Record<string, unknown>;
+    const currentList: Array<{ id: string }> = Array.isArray(agentsObj.list) ? agentsObj.list as Array<{ id: string }> : [];
+    const existingIds = new Set(
+        currentList
+            .map((entry) => entry?.id?.trim().toLowerCase())
+            .filter((id): id is string => Boolean(id))
+    );
+
+    let changed = false;
+    const nextList = [...currentList];
+
+    // 首次创建时保留 main 作为默认
+    if (nextList.length === 0) {
+        nextList.push({ id: "main" });
+        existingIds.add("main");
+        changed = true;
+    }
+
+    if (!existingIds.has(agentId.toLowerCase())) {
+        nextList.push({ id: agentId });
+        changed = true;
+    }
+
+    if (changed) {
+        agentsObj.list = nextList;
+    }
+
+    return changed;
+}
+
+/**
+ * **ensureDynamicAgentListed (确保动态 Agent 已添加到 agents.list)**
+ *
+ * 将动态生成的 Agent ID 添加到 OpenClaw 配置中的 agents.list。
+ * 特性：
+ * - 幂等：使用内存 Set 避免重复写入
+ * - 串行：使用 Promise 队列避免并发冲突
+ * - 异步：不阻塞消息处理流程
+ */
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+export async function ensureDynamicAgentListed(agentId: string, runtime: any): Promise<void> {
+    const normalizedId = String(agentId).trim().toLowerCase();
+    if (!normalizedId) return;
+    if (ensuredDynamicAgentIds.has(normalizedId)) return;
+
+    const configRuntime = runtime?.config;
+    if (!configRuntime?.loadConfig || !configRuntime?.writeConfigFile) return;
+
+    ensureDynamicAgentWriteQueue = ensureDynamicAgentWriteQueue
+        .then(async () => {
+            if (ensuredDynamicAgentIds.has(normalizedId)) return;
+
+            const latestConfig = configRuntime.loadConfig!();
+            if (!latestConfig || typeof latestConfig !== "object") return;
+
+            const changed = upsertAgentIdOnlyEntry(latestConfig as Record<string, unknown>, normalizedId);
+            if (changed) {
+                await configRuntime.writeConfigFile!(latestConfig as unknown);
+            }
+
+            ensuredDynamicAgentIds.add(normalizedId);
+        })
+        .catch((err) => {
+            console.warn(`[wecom] 动态 Agent 添加失败: ${normalizedId}`, err);
+        });
+
+    await ensureDynamicAgentWriteQueue;
+}
+
+/**
+ * **resetEnsuredCache (重置已确保缓存)**
+ *
+ * 主要用于测试场景，重置内存中的缓存状态。
+ */
+export function resetEnsuredCache(): void {
+    ensuredDynamicAgentIds.clear();
+}

package/src/monitor.ts

@@ -28,6 +28,7 @@ import axios from "axios";
 import type { WecomRuntimeEnv, WecomWebhookTarget, StreamState, PendingInbound, ActiveReplyState } from "./monitor/types.js";
 import { monitorState, LIMITS } from "./monitor/state.js";
 import { buildWecomUnauthorizedCommandPrompt, resolveWecomCommandAuthorization } from "./shared/command-auth.js";
+import { generateAgentId, shouldUseDynamicAgent, ensureDynamicAgentListed } from "./dynamic-agent.js";
 
 // Global State
 monitorState.streamStore.setFlushHandler((pending) => void flushPending(pending));
@@ -927,6 +928,26 @@ async function startAgentForStream(params: {
     peer: { kind: chatType === "group" ? "group" : "dm", id: chatId },
   });
 
+  // ===== 动态 Agent 路由注入 =====
+  const useDynamicAgent = shouldUseDynamicAgent({
+    chatType: chatType === "group" ? "group" : "dm",
+    senderId: userid,
+    config,
+  });
+
+  if (useDynamicAgent) {
+    const targetAgentId = generateAgentId(
+      chatType === "group" ? "group" : "dm",
+      chatId
+    );
+    route.agentId = targetAgentId;
+    route.sessionKey = `agent:${targetAgentId}:${chatType === "group" ? "group" : "dm"}:${chatId}`;
+    // 异步添加到 agents.list（不阻塞）
+    ensureDynamicAgentListed(targetAgentId, core).catch(() => {});
+    logVerbose(target, `dynamic agent routing: ${targetAgentId}, sessionKey=${route.sessionKey}`);
+  }
+  // ===== 动态 Agent 路由注入结束 =====
+
   logVerbose(target, `starting agent processing (streamId=${streamId}, agentId=${route.agentId}, peerKind=${chatType}, peerId=${chatId})`);
   logVerbose(target, `启动 Agent 处理: streamId=${streamId} 路由=${route.agentId} 类型=${chatType} ID=${chatId}`);
 

package/src/types/config.ts

@@ -70,6 +70,18 @@ export type WecomAgentConfig = {
     dm?: WecomDmConfig;
 };
 
+/** 动态 Agent 配置 */
+export type WecomDynamicAgentsConfig = {
+    /** 是否启用动态 Agent */
+    enabled?: boolean;
+    /** 私聊：是否为每个用户创建独立 Agent */
+    dmCreateAgent?: boolean;
+    /** 群聊：是否启用动态 Agent */
+    groupEnabled?: boolean;
+    /** 管理员列表（绕过动态路由，使用主 Agent） */
+    adminUsers?: string[];
+};
+
 /**
  * 顶层 WeCom 配置
  * 通过 bot / agent 字段隐式指定模式
@@ -85,4 +97,6 @@ export type WecomConfig = {
     media?: WecomMediaConfig;
     /** 网络配置 */
     network?: WecomNetworkConfig;
+    /** 动态 Agent 配置 */
+    dynamicAgents?: WecomDynamicAgentsConfig;
 };

package//345/212/250/346/200/201Agent/350/267/257/347/224/261.md

@@ -0,0 +1,360 @@
+# 动态 Agent 路由实施方案
+
+参考 `openclaw-plugin-wecom/dynamic-agent.js` 实现，为 `@yanhaidao/wecom` 添加按用户/群隔离的动态 Agent 功能。
+
+## 1. 目标
+
+- 每个用户/群组使用独立的 Agent 实例
+- 自动将动态 Agent 添加到 `agents.list`
+- 完全向后兼容（默认关闭）
+
+## 2. 配置设计
+
+### 2.1 类型定义 (src/types/config.ts)
+
+```typescript
+/** 动态 Agent 配置 */
+export type WecomDynamicAgentsConfig = {
+    /** 是否启用动态 Agent */
+    enabled?: boolean;
+    /** 私聊：是否为每个用户创建独立 Agent */
+    dmCreateAgent?: boolean;
+    /** 群聊：是否启用动态 Agent */
+    groupEnabled?: boolean;
+    /** 管理员列表（绕过动态路由，使用主 Agent） */
+    adminUsers?: string[];
+};
+
+export type WecomConfig = {
+    enabled?: boolean;
+    bot?: WecomBotConfig;
+    agent?: WecomAgentConfig;
+    media?: WecomMediaConfig;
+    network?: WecomNetworkConfig;
+    dynamicAgents?: WecomDynamicAgentsConfig;  // 新增
+};
+```
+
+### 2.2 Schema 定义 (src/config/schema.ts)
+
+```typescript
+const dynamicAgentsSchema = z.object({
+    enabled: z.boolean().optional(),
+    dmCreateAgent: z.boolean().optional(),
+    groupEnabled: z.boolean().optional(),
+    adminUsers: z.array(z.string()).optional(),
+}).optional();
+
+export const WecomConfigSchema = z.object({
+    enabled: z.boolean().optional(),
+    bot: botSchema,
+    agent: agentSchema,
+    media: mediaSchema,
+    network: networkSchema,
+    dynamicAgents: dynamicAgentsSchema,  // 新增
+});
+```
+
+## 3. 核心实现 (src/dynamic-agent.ts)
+
+```typescript
+import type { OpenClawConfig } from "openclaw/plugin-sdk";
+
+export interface DynamicAgentConfig {
+    enabled: boolean;
+    dmCreateAgent: boolean;
+    groupEnabled: boolean;
+    adminUsers: string[];
+}
+
+/**
+ * 读取动态 Agent 配置（带默认值）
+ */
+export function getDynamicAgentConfig(config: OpenClawConfig): DynamicAgentConfig {
+    const dynamicAgents = (config as any)?.channels?.wecom?.dynamicAgents;
+    return {
+        enabled: dynamicAgents?.enabled ?? false,
+        dmCreateAgent: dynamicAgents?.dmCreateAgent ?? true,
+        groupEnabled: dynamicAgents?.groupEnabled ?? true,
+        adminUsers: dynamicAgents?.adminUsers ?? [],
+    };
+}
+
+/**
+ * 生成动态 Agent ID
+ * 算法：wecom-{type}-{sanitizedPeerId}
+ * type: dm | group
+ */
+export function generateAgentId(chatType: "dm" | "group", peerId: string): string {
+    const sanitized = String(peerId)
+        .toLowerCase()
+        .replace(/[^a-z0-9_-]/g, "_");
+    return `wecom-${chatType}-${sanitized}`;
+}
+
+/**
+ * 检查是否应该使用动态 Agent
+ */
+export function shouldUseDynamicAgent(params: {
+    chatType: "dm" | "group";
+    senderId: string;
+    config: OpenClawConfig;
+}): boolean {
+    const { chatType, senderId, config } = params;
+    const dynamicConfig = getDynamicAgentConfig(config);
+
+    if (!dynamicConfig.enabled) {
+        return false;
+    }
+
+    // 管理员绕过动态路由
+    const sender = String(senderId).trim().toLowerCase();
+    const isAdmin = dynamicConfig.adminUsers.some(
+        admin => admin.trim().toLowerCase() === sender
+    );
+    if (isAdmin) {
+        return false;
+    }
+
+    if (chatType === "group") {
+        return dynamicConfig.groupEnabled;
+    }
+    return dynamicConfig.dmCreateAgent;
+}
+
+/**
+ * 内存中已确保的 Agent ID（避免重复写入）
+ */
+const ensuredDynamicAgentIds = new Set<string>();
+
+/**
+ * 写入队列（避免并发冲突）
+ */
+let ensureDynamicAgentWriteQueue: Promise<void> = Promise.resolve();
+
+/**
+ * 将动态 Agent 添加到 agents.list
+ */
+export async function ensureDynamicAgentListed(
+    agentId: string,
+    runtime: { config?: { loadConfig?: () => any; writeConfigFile?: (cfg: any) => Promise<void> } }
+): Promise<void> {
+    const normalizedId = String(agentId).trim().toLowerCase();
+    if (!normalizedId) return;
+    if (ensuredDynamicAgentIds.has(normalizedId)) return;
+
+    const configRuntime = runtime?.config;
+    if (!configRuntime?.loadConfig || !configRuntime?.writeConfigFile) return;
+
+    ensureDynamicAgentWriteQueue = ensureDynamicAgentWriteQueue
+        .then(async () => {
+            if (ensuredDynamicAgentIds.has(normalizedId)) return;
+
+            const latestConfig = configRuntime.loadConfig!();
+            if (!latestConfig || typeof latestConfig !== "object") return;
+
+            const changed = upsertAgentIdOnlyEntry(latestConfig, normalizedId);
+            if (changed) {
+                await configRuntime.writeConfigFile!(latestConfig);
+                console.log(`[wecom] 动态 Agent 已添加: ${normalizedId}`);
+            }
+
+            ensuredDynamicAgentIds.add(normalizedId);
+        })
+        .catch((err) => {
+            console.warn(`[wecom] 动态 Agent 添加失败: ${normalizedId}`, err);
+        });
+
+    await ensureDynamicAgentWriteQueue;
+}
+
+/**
+ * 将 Agent ID 插入 agents.list（如果不存在）
+ */
+function upsertAgentIdOnlyEntry(cfg: any, agentId: string): boolean {
+    if (!cfg.agents || typeof cfg.agents !== "object") {
+        cfg.agents = {};
+    }
+
+    const currentList: Array<{ id: string }> = Array.isArray(cfg.agents.list) ? cfg.agents.list : [];
+    const existingIds = new Set(
+        currentList
+            .map((entry) => entry?.id?.trim().toLowerCase())
+            .filter(Boolean)
+    );
+
+    let changed = false;
+    const nextList = [...currentList];
+
+    // 首次创建时保留 main 作为默认
+    if (nextList.length === 0) {
+        nextList.push({ id: "main" });
+        existingIds.add("main");
+        changed = true;
+    }
+
+    if (!existingIds.has(agentId.toLowerCase())) {
+        nextList.push({ id: agentId });
+        changed = true;
+    }
+
+    if (changed) {
+        cfg.agents.list = nextList;
+    }
+
+    return changed;
+}
+```
+
+## 4. 路由拦截点修改
+
+### 4.1 Bot 模式 (src/monitor.ts)
+
+在 `startAgentForStream` 函数中，路由解析后注入动态 Agent：
+
+```typescript
+// 约第 923 行，路由解析后
+const route = core.channel.routing.resolveAgentRoute({
+    cfg: config,
+    channel: "wecom",
+    accountId: account.accountId,
+    peer: { kind: chatType === "group" ? "group" : "dm", id: chatId },
+});
+
+// ===== 动态 Agent 注入开始 =====
+import { shouldUseDynamicAgent, generateAgentId, ensureDynamicAgentListed } from "./dynamic-agent.js";
+
+const useDynamicAgent = shouldUseDynamicAgent({
+    chatType: chatType === "group" ? "group" : "dm",
+    senderId: userid,
+    config,
+});
+
+if (useDynamicAgent) {
+    const targetAgentId = generateAgentId(
+        chatType === "group" ? "group" : "dm",
+        chatId
+    );
+
+    // 覆盖路由
+    route.agentId = targetAgentId;
+    route.sessionKey = `agent:${targetAgentId}:${chatType === "group" ? "group" : "dm"}:${chatId}`;
+
+    // 异步添加到 agents.list（不阻塞）
+    ensureDynamicAgentListed(targetAgentId, core).catch(() => {});
+}
+// ===== 动态 Agent 注入结束 =====
+```
+
+### 4.2 Agent 模式 (src/agent/handler.ts)
+
+在 `processAgentMessage` 函数中，路由解析后注入动态 Agent：
+
+```typescript
+// 约第 438 行，路由解析后
+const route = core.channel.routing.resolveAgentRoute({
+    cfg: config,
+    channel: "wecom",
+    accountId: agent.accountId,
+    peer: { kind: isGroup ? "group" : "dm", id: peerId },
+});
+
+// ===== 动态 Agent 注入开始 =====
+import { shouldUseDynamicAgent, generateAgentId, ensureDynamicAgentListed } from "../dynamic-agent.js";
+
+const useDynamicAgent = shouldUseDynamicAgent({
+    chatType: isGroup ? "group" : "dm",
+    senderId: fromUser,
+    config,
+});
+
+if (useDynamicAgent) {
+    const targetAgentId = generateAgentId(
+        isGroup ? "group" : "dm",
+        peerId
+    );
+
+    // 覆盖路由
+    route.agentId = targetAgentId;
+    route.sessionKey = `agent:${targetAgentId}:${isGroup ? "group" : "dm"}:${peerId}`;
+
+    // 异步添加到 agents.list
+    ensureDynamicAgentListed(targetAgentId, core).catch(() => {});
+}
+// ===== 动态 Agent 注入结束 =====
+```
+
+## 5. 配置示例
+
+```bash
+# 启用动态 Agent
+openclaw config set channels.wecom.dynamicAgents.enabled true
+
+# 私聊为每个用户创建独立 Agent（默认 true）
+openclaw config set channels.wecom.dynamicAgents.dmCreateAgent true
+
+# 群聊启用动态 Agent（默认 true）
+openclaw config set channels.wecom.dynamicAgents.groupEnabled true
+
+# 设置管理员（管理员使用主 Agent）
+openclaw config set channels.wecom.dynamicAgents.adminUsers '["admin1","admin2"]'
+```
+
+生成的配置结构：
+
+```json
+{
+  "channels": {
+    "wecom": {
+      "enabled": true,
+      "bot": { ... },
+      "agent": { ... },
+      "dynamicAgents": {
+        "enabled": true,
+        "dmCreateAgent": true,
+        "groupEnabled": true,
+        "adminUsers": ["admin1"]
+      }
+    }
+  },
+  "agents": {
+    "list": [
+      { "id": "main" },
+      { "id": "wecom-dm-zhangsan" },
+      { "id": "wecom-group-wr123456" }
+    ]
+  }
+}
+```
+
+## 6. Agent ID 生成规则
+
+| 场景 | Peer ID | 生成的 Agent ID |
+|------|---------|-----------------|
+| 私聊 | zhangsan | `wecom-dm-zhangsan` |
+| 群聊 | wr123456 | `wecom-group-wr123456` |
+| 特殊字符 | zhang.san | `wecom-dm-zhang_san` |
+| 大写 | ZhangSan | `wecom-dm-zhangsan` |
+
+## 7. 实现步骤
+
+1. **新增文件**
+   - `src/dynamic-agent.ts` - 核心逻辑
+
+2. **修改文件**
+   - `src/types/config.ts` - 添加 `WecomDynamicAgentsConfig` 类型
+   - `src/config/schema.ts` - 添加 `dynamicAgentsSchema`
+   - `src/monitor.ts` - Bot 模式路由拦截
+   - `src/agent/handler.ts` - Agent 模式路由拦截
+
+3. **测试验证**
+   - 未启用时行为不变
+   - 启用后每个用户有独立会话
+   - 管理员正确使用主 Agent
+   - 自动写入 agents.list
+
+## 8. 向后兼容性
+
+- `dynamicAgents.enabled` 默认为 `false`，不启用功能
+- 未配置时保持原有行为（所有用户使用同一 Agent）
+- 管理员可继续使用 `main` Agent