@mocrane/wecom 2026.2.5 → 2026.3.4

package/changelog/v2.2.28.md

@@ -0,0 +1,70 @@
+# 🚀 OpenClaw 企业微信 (WeCom) 插件 v2.2.28 - 多账号隔离与稳定性增强
+
+本次 v2.2.28 版本是 **OpenClaw 企业微信 (WeCom) 插件** 的一次重大里程碑更新。我们深度优化了 **微信 / 企业微信** 办公场景下的多智能体隔离逻辑，并修复了生命周期、XML 数据保真等多个生产环境的核心痛点。
+
+本次更新让 **OpenClaw** 在处理企业级复杂 **插件** 配置时更加得心应手，完美解决大模型接入 **WeCom** 的所有阻碍。
+
+---
+
+### 🌟 版本亮点 (Release Highlights)
+
+*   🎯 **多账号矩阵支持**：支持按 `accountId` 进行组内会话隔离。不同部门、不同业务的 **企业微信** 机器人可并行运行，互不干扰，彻底解决跨账号串会话问题。
+*   🔐 **数据保真解析**：针对 **WeCom** 的 XML 消息解析进行了重构。关闭了自动数值化，保留 `FromUserName` 前导 `0`，并完美解决 64 位 `MsgId` 精度风险。
+*   🔁 **Gateway 生命周期适配**：完美兼容最新版 **OpenClaw** Gateway 的生命周期管理，修复了在高频心跳监测下的重启循环问题，运行更稳健。
+*   🧹 **入站消息过滤**：优化了 **微信** 与 **企业微信** 的事件过滤逻辑，避免系统事件、缺失发送者等无效消息进入 AI 会话，防止“误回复”。
+*   🧱 **配置安全护栏**：新增 **企业微信** 账号冲突检测。自动拦截重复的 `bot.token` 或 `agentId` 配置，并提供友好的中文错误提示。
+
+---
+
+### 📝 详细更新日志 (Changelog)
+
+#### 【重磅更新】🎯 多账号/多智能体可用性增强
+- 支持按 `accountId` 做组内隔离（Bot + Agent + 路由绑定同组生效）。
+- 动态 Agent 与会话键增加 `accountId` 维度，避免跨账号串会话。
+
+#### 【稳定性】🔁 生命周期兼容修复
+- 适配新版 **OpenClaw** Gateway 生命周期，`startAccount` 改为长生命周期运行。
+- 修复了“几秒一次重启 + health-monitor 二次重启”的循环问题。
+
+#### 【准确性】🔐 XML 字段保真修复
+- **WeCom** Agent XML 解析关闭自动数值化，保留发送者原始 ID。
+- 避免 `MsgId` (64bit) 精度损失，确保回复目标不被误改。
+
+#### 【准确性】🧹 误回复修复
+- Bot/Agent 入站均增加事件过滤，避免处理 `event`、`sys` 及缺失发送者的消息。
+- 修复群聊缺失 `chatid` 时仍进入 AI 会话的问题，避免“一个消息触发多人误回复”。
+
+#### 【可控性】🧱 配置安全护栏
+- 新增多账号冲突检测，自动拦截重复 Token 或 Agent ID 的配置。
+- **账号管理修复**：`deleteAccount` 现在仅删除目标账号，不再误删整个 **插件** 的 `channels.wecom` 配置。
+
+#### 【质量保障】✅ 自动化回归
+- 新增账号解析、冲突检测、动态路由隔离、生命周期与入站过滤的多项自动化测试。
+- **文档优化**：README 快速开始文档更新，优先展示“多账号 + 多 Agent”矩阵配置。
+
+---
+
+### 💾 安装与升级 (Install & Update)
+
+使用 **OpenClaw** CLI 即可一键升级 **插件**：
+
+```bash
+openclaw plugins upgrade wecom
+```
+
+或手动更新配置：
+```bash
+openclaw config set channels.wecom.enabled true
+```
+
+---
+
+### 🔍 SEO 关键词 (Keywords)
+**openclaw** | **企业微信** | **微信** | **wecom** | **插件** | **AI 机器人** | **大模型网关** | **流式响应** | **多账号隔离** | **WeCom Plugin**
+
+---
+
+### 📮 联系我们
+如果您在 **企业微信 / 微信** 接入过程中遇到任何问题，欢迎提交 Issue 或加入我们的交流群。
+
+> **提示**：建议 **OpenClaw** 主程序版本保持在 **2026.2.24+** 以获得最佳体验。

package/changelog/v2.3.2.md

@@ -0,0 +1,28 @@
+# OpenClaw WeCom 插件 v2.3.2 变更简报
+
+> [!WARNING]
+> **OpenClaw 3.1+ 升级必读**：升级到 OpenClaw `3.1` 及以上版本的用户务必同步升级本插件，并将企业微信回调 URL 更新为 OpenClaw 推荐路径：`/plugins/wecom/bot/{accountId}` 与 `/plugins/wecom/agent/{accountId}`（旧 `/wecom/*` 仍兼容但不再维护）。
+
+## 2026-03-03（今日）
+- 【路由兼容】🧩 修复 OpenClaw 3.1 下 Control UI fallback 可能抢占 `/wecom/*` webhook 的路由冲突问题。  
+- 【引导收敛】🧭 将 WeCom onboarding 统一为账号化配置写入 `channels.wecom.accounts.<accountId>`，不再引导单账号旧结构。  
+- 【回调路径】🔁 将 WeCom 回调路径的推荐方案统一为 `/plugins/wecom/bot/{accountId}` 与 `/plugins/wecom/agent/{accountId}`。  
+- 【兼容策略】🔁 保留 `/wecom/*` 历史回调路径兼容能力，但不再维护旧路径分支。  
+- 【分流稳定】🧭 将 monitor 分流升级为按插件命名空间账号路径识别，确保 Bot/Agent 稳定命中。  
+- 【链路一致】🔒 将 Bot 上下文 `Surface` 对齐为 `wecom`，避免核心误判后错误走到 Agent outbound。  
+- 【账号必填】🧱 在 matrix 模式下对无 accountId 的基础路径返回 `wecom_matrix_path_required`，强制使用账号化回调路径。  
+- 【文档同步】📘 将回调地址文档与 onboarding 提示统一为 `/plugins/wecom/*/{accountId}` 唯一推荐路径。  
+
+## 2026-03-02（v2.3.2 主体）
+- 【交付收口】🔄 修复 Bot 结果回写后“正在搜索相关内容”不收口的问题，并在可用时推送最终流帧结束思考态。  
+- 【媒体兜底】📎 统一非图片文件、媒体失败和超时场景为“Bot 提示 + Agent 私信兜底”闭环，保证结果可达。  
+- 【工具治理】🛡 修复 WeCom Bot 会话中 `message` 工具禁用位置，避免模型绕过 Bot 交付链路直接主动发送。  
+- 【类型兼容】🧠 扩展本地与远端文件 MIME 识别覆盖 `txt/docx/xlsx/pptx/csv/zip` 等常见类型，并保留 `octet-stream` 重试兜底。  
+- 【判定增强】🔍 将入站文件类型推断升级为“文件头特征 + 响应头 + 文件名后缀”多层判定，提升无后缀和异常 URL 的识别准确率。  
+
+## 验证结果
+- WeCom 插件测试通过 `10` 个测试文件共 `41` 条用例，覆盖 webhook 生命周期、路径分流、媒体兜底与回归场景。  
+
+## 升级提示
+- 推荐在企业微信后台使用 `https://<your-domain>/plugins/wecom/bot/{accountId}` 与 `https://<your-domain>/plugins/wecom/agent/{accountId}` 作为回调地址。  
+- 旧地址 `/wecom/bot/{accountId}` 与 `/wecom/agent/{accountId}` 仍兼容但不再维护，建议尽快迁移到 `/plugins/wecom/*/{accountId}`。  

package/changelog/v2.3.4.md

@@ -0,0 +1,20 @@
+# OpenClaw WeCom 插件 v2.3.4 变更简报
+
+> [!WARNING]
+> **可用性热修复版本**：`v2.3.4` 重点修复 OpenClaw 3.1+ 下 WeCom webhook 路由兼容与可达性问题，保障历史配置可继续使用。
+
+## 2026-03-03（v2.3.4 热修复）
+- 【SDK适配】♻️ 插件入口从 `registerHttpHandler` 迁移为 `registerHttpRoute`（`/plugins/wecom` + `match=prefix` + `auth=plugin`），兼容 OpenClaw 新版插件 HTTP 注册模型。  
+- 【兼容修复】🔁 补回旧路径入口注册：新增 `/wecom` 前缀路由注册，确保历史 Bot/Agent webhook 继续可达。  
+- 【模式兼容】🧭 保持 legacy 单账号配置可运行，并明确 matrix 模式必须使用带 `accountId` 的回调路径。  
+
+## 影响说明
+- WeCom Bot/Agent 业务链路保持兼容；核心变化为插件 HTTP 注册 API 的升级适配与旧路径可达性恢复。  
+
+## 兼容矩阵（单账号/多账号）
+| 场景 | 配置形态 | 回调地址 | 兼容状态 | 说明 |
+|---|---|---|---|---|
+| 历史单账号（legacy） | `channels.wecom.bot/agent` | Bot: `/wecom`（默认）或 `/wecom/bot`；Agent: `/wecom/agent` | ✅ 兼容保留 | 适用于存量部署，不作为新引导方案。 |
+| 多账号（matrix）错误用法 | `channels.wecom.accounts.*` | `/wecom/bot`、`/wecom/agent`（无 accountId） | ❌ 不可用 | 会返回 `wecom_matrix_path_required`。 |
+| 多账号（matrix）兼容路径 | `channels.wecom.accounts.*` | `/wecom/bot/{accountId}`、`/wecom/agent/{accountId}` | ✅ 兼容保留 | 历史路径可用，但不再维护。 |
+| 多账号（matrix）推荐路径 | `channels.wecom.accounts.*` | `/plugins/wecom/bot/{accountId}`、`/plugins/wecom/agent/{accountId}` | ✅ 推荐 | 当前主维护路径。 |

package/index.ts

@@ -12,16 +12,24 @@ const plugin = {
   configSchema: emptyPluginConfigSchema(),
   /**
    * **register (注册插件)**
-   * 
+   *
    * OpenClaw 插件入口点。
    * 1. 注入 Runtime 环境 (api.runtime)。
    * 2. 注册 WeCom 渠道插件 (ChannelPlugin)。
-   * 3. 注册 Webhook HTTP 处理器 (handleWecomWebhookRequest)。
+   * 3. 注册 Webhook HTTP 路由（推荐 /plugins/wecom/*，兼容 /wecom*）。
    */
   register(api: OpenClawPluginApi) {
     setWecomRuntime(api.runtime);
     api.registerChannel({ plugin: wecomPlugin });
-    api.registerHttpHandler(handleWecomWebhookRequest);
+    const routes = ["/plugins/wecom", "/wecom"];
+    for (const path of routes) {
+      api.registerHttpRoute({
+        path,
+        handler: handleWecomWebhookRequest,
+        auth: "plugin",
+        match: "prefix",
+      });
+    }
   },
 };
 

package/package.json

@@ -1,12 +1,14 @@
 {
   "name": "@mocrane/wecom",
-  "version": "2026.2.5",
+  "version": "2026.3.4",
   "type": "module",
   "description": "OpenClaw WeCom (WeChat Work) intelligent bot channel plugin",
   "main": "index.ts",
   "files": [
     "index.ts",
     "src/",
+    "assets/",
+    "changelog/",
     "openclaw.plugin.json",
     "clawdbot.plugin.json",
     "README.md",
@@ -45,7 +47,7 @@
     "zod": "^4.3.6"
   },
   "peerDependencies": {
-    "openclaw": ">=2026.1.26"
+    "openclaw": ">=2026.2.24"
   },
   "devDependencies": {
     "@types/node": "^25.2.0",

package/src/accounts.ts

@@ -1,72 +1,34 @@
 import type { OpenClawConfig } from "openclaw/plugin-sdk";
-import { DEFAULT_ACCOUNT_ID, normalizeAccountId } from "openclaw/plugin-sdk";
-
-import type { ResolvedWecomAccount, WecomAccountConfig, WecomConfig } from "./types.js";
-
-function listConfiguredAccountIds(cfg: OpenClawConfig): string[] {
-  const accounts = (cfg.channels?.wecom as WecomConfig | undefined)?.accounts;
-  if (!accounts || typeof accounts !== "object") return [];
-  return Object.keys(accounts).filter(Boolean);
-}
 
+import type { ResolvedWecomAccount } from "./types/index.js";
+import {
+  listWecomAccountIds as listWecomAccountIdsFromConfig,
+  resolveDefaultWecomAccountId as resolveDefaultWecomAccountIdFromConfig,
+  resolveWecomAccount as resolveWecomAccountFromConfig,
+} from "./config/accounts.js";
+
+/**
+ * Backward-compatible re-export layer.
+ * Keep this file as a thin wrapper so older imports continue to work,
+ * while all account logic stays single-sourced in `src/config/accounts.ts`.
+ */
 export function listWecomAccountIds(cfg: OpenClawConfig): string[] {
-  const ids = listConfiguredAccountIds(cfg);
-  if (ids.length === 0) return [DEFAULT_ACCOUNT_ID];
-  return ids.sort((a, b) => a.localeCompare(b));
+  return listWecomAccountIdsFromConfig(cfg);
 }
 
 export function resolveDefaultWecomAccountId(cfg: OpenClawConfig): string {
-  const wecomConfig = cfg.channels?.wecom as WecomConfig | undefined;
-  if (wecomConfig?.defaultAccount?.trim()) return wecomConfig.defaultAccount.trim();
-  const ids = listWecomAccountIds(cfg);
-  if (ids.includes(DEFAULT_ACCOUNT_ID)) return DEFAULT_ACCOUNT_ID;
-  return ids[0] ?? DEFAULT_ACCOUNT_ID;
-}
-
-function resolveAccountConfig(
-  cfg: OpenClawConfig,
-  accountId: string,
-): WecomAccountConfig | undefined {
-  const accounts = (cfg.channels?.wecom as WecomConfig | undefined)?.accounts;
-  if (!accounts || typeof accounts !== "object") return undefined;
-  return accounts[accountId] as WecomAccountConfig | undefined;
-}
-
-function mergeWecomAccountConfig(cfg: OpenClawConfig, accountId: string): WecomAccountConfig {
-  const raw = (cfg.channels?.wecom ?? {}) as WecomConfig;
-  const { accounts: _ignored, defaultAccount: _ignored2, ...base } = raw;
-  const account = resolveAccountConfig(cfg, accountId) ?? {};
-  return { ...base, ...account };
+  return resolveDefaultWecomAccountIdFromConfig(cfg);
 }
 
 export function resolveWecomAccount(params: {
   cfg: OpenClawConfig;
   accountId?: string | null;
 }): ResolvedWecomAccount {
-  const accountId = normalizeAccountId(params.accountId);
-  const baseEnabled = (params.cfg.channels?.wecom as WecomConfig | undefined)?.enabled !== false;
-  const merged = mergeWecomAccountConfig(params.cfg, accountId);
-  const enabled = baseEnabled && merged.enabled !== false;
-
-  const token = merged.token?.trim() || undefined;
-  const encodingAESKey = merged.encodingAESKey?.trim() || undefined;
-  const receiveId = merged.receiveId?.trim() ?? "";
-  const configured = Boolean(token && encodingAESKey);
-
-  return {
-    accountId,
-    name: merged.name?.trim() || undefined,
-    enabled,
-    configured,
-    token,
-    encodingAESKey,
-    receiveId,
-    config: merged,
-  };
+  return resolveWecomAccountFromConfig(params);
 }
 
 export function listEnabledWecomAccounts(cfg: OpenClawConfig): ResolvedWecomAccount[] {
-  return listWecomAccountIds(cfg)
-    .map((accountId) => resolveWecomAccount({ cfg, accountId }))
+  return listWecomAccountIdsFromConfig(cfg)
+    .map((accountId) => resolveWecomAccountFromConfig({ cfg, accountId }))
     .filter((account) => account.enabled);
 }

package/src/agent/api-client.ts

@@ -25,6 +25,48 @@ type TokenCache = {
 
 const tokenCaches = new Map<string, TokenCache>();
 
+function normalizeUploadFilename(filename: string): string {
+    const trimmed = filename.trim();
+    if (!trimmed) return "file.bin";
+    const ext = trimmed.includes(".") ? `.${trimmed.split(".").pop()!.toLowerCase()}` : "";
+    const base = ext ? trimmed.slice(0, -ext.length) : trimmed;
+    const sanitizedBase = base
+        .replace(/[^\x20-\x7e]/g, "_")
+        .replace(/["\\\/;=]/g, "_")
+        .replace(/\s+/g, "_")
+        .replace(/_+/g, "_")
+        .replace(/^_+|_+$/g, "");
+    const safeBase = sanitizedBase || "file";
+    const safeExt = ext.replace(/[^a-z0-9.]/g, "");
+    return `${safeBase}${safeExt || ".bin"}`;
+}
+
+function guessUploadContentType(filename: string): string {
+    const ext = filename.split(".").pop()?.toLowerCase() || "";
+    const contentTypeMap: Record<string, string> = {
+        // image
+        jpg: "image/jpg", jpeg: "image/jpeg", png: "image/png", gif: "image/gif", webp: "image/webp", bmp: "image/bmp",
+        // audio / video
+        amr: "voice/amr", mp3: "audio/mpeg", wav: "audio/wav", m4a: "audio/mp4", ogg: "audio/ogg", mp4: "video/mp4", mov: "video/quicktime",
+        // documents
+        txt: "text/plain", md: "text/markdown", csv: "text/csv", tsv: "text/tab-separated-values", json: "application/json",
+        xml: "application/xml", yaml: "application/yaml", yml: "application/yaml",
+        pdf: "application/pdf", doc: "application/msword", docx: "application/vnd.openxmlformats-officedocument.wordprocessingml.document",
+        xls: "application/vnd.ms-excel", xlsx: "application/vnd.openxmlformats-officedocument.spreadsheetml.sheet",
+        ppt: "application/vnd.ms-powerpoint", pptx: "application/vnd.openxmlformats-officedocument.presentationml.presentation",
+        rtf: "application/rtf", odt: "application/vnd.oasis.opendocument.text",
+        // archives
+        zip: "application/zip", rar: "application/vnd.rar", "7z": "application/x-7z-compressed",
+        gz: "application/gzip", tgz: "application/gzip", tar: "application/x-tar",
+    };
+    return contentTypeMap[ext] || "application/octet-stream";
+}
+
+function requireAgentId(agent: ResolvedAgentAccount): number {
+    if (typeof agent.agentId === "number" && Number.isFinite(agent.agentId)) return agent.agentId;
+    throw new Error(`wecom agent account=${agent.accountId} missing agentId; sending via cgi-bin/message/send requires agentId`);
+}
+
 /**
  * **getAccessToken (获取 AccessToken)**
  * 
@@ -35,7 +77,7 @@ const tokenCaches = new Map<string, TokenCache>();
  * @returns 有效的 AccessToken
  */
 export async function getAccessToken(agent: ResolvedAgentAccount): Promise<string> {
-    const cacheKey = `${agent.corpId}:${agent.agentId}`;
+    const cacheKey = `${agent.corpId}:${String(agent.agentId ?? "na")}`;
     let cache = tokenCaches.get(cacheKey);
 
     if (!cache) {
@@ -109,7 +151,7 @@ export async function sendText(params: {
             toparty: toParty,
             totag: toTag,
             msgtype: "text",
-            agentid: agent.agentId,
+            agentid: requireAgentId(agent),
             text: { content: text }
         };
 
@@ -158,48 +200,53 @@ export async function uploadMedia(params: {
     filename: string;
 }): Promise<string> {
     const { agent, type, buffer, filename } = params;
+    const safeFilename = normalizeUploadFilename(filename);
     const token = await getAccessToken(agent);
+    const proxyUrl = resolveWecomEgressProxyUrlFromNetwork(agent.network);
     // 添加 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",
+    console.log(`[wecom-upload] Uploading media: type=${type}, filename=${safeFilename}, size=${buffer.length} bytes`);
+
+    const uploadOnce = async (fileContentType: string) => {
+        // 手动构造 multipart/form-data 请求体
+        // 企业微信要求包含 filename 和 filelength
+        const boundary = `----WebKitFormBoundary${crypto.randomBytes(16).toString("hex")}`;
+
+        const header = Buffer.from(
+            `--${boundary}\r\n` +
+            `Content-Disposition: form-data; name="media"; filename="${safeFilename}"; 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 wecomFetch(url, {
+            method: "POST",
+            headers: {
+                "Content-Type": `multipart/form-data; boundary=${boundary}`,
+                "Content-Length": String(body.length),
+            },
+            body: body,
+        }, { proxyUrl, timeoutMs: LIMITS.REQUEST_TIMEOUT_MS });
+        const json = await res.json() as { media_id?: string; errcode?: number; errmsg?: string };
+        console.log(`[wecom-upload] Response:`, JSON.stringify(json));
+        return json;
     };
-    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]);
+    const preferredContentType = guessUploadContentType(safeFilename);
+    let json = await uploadOnce(preferredContentType);
 
-    console.log(`[wecom-upload] Multipart body size=${body.length}, boundary=${boundary}, fileContentType=${fileContentType}`);
-
-    const res = await wecomFetch(url, {
-        method: "POST",
-        headers: {
-            "Content-Type": `multipart/form-data; boundary=${boundary}`,
-            "Content-Length": String(body.length),
-        },
-        body: body,
-    }, { proxyUrl: resolveWecomEgressProxyUrlFromNetwork(agent.network), timeoutMs: 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 && preferredContentType !== "application/octet-stream") {
+        console.warn(
+            `[wecom-upload] Upload failed with ${preferredContentType}, retrying as application/octet-stream: ${json?.errcode} ${json?.errmsg}`,
+        );
+        json = await uploadOnce("application/octet-stream");
+    }
 
     if (!json?.media_id) {
         throw new Error(`upload failed: ${json?.errcode} ${json?.errmsg}`);
@@ -252,7 +299,7 @@ export async function sendMedia(params: {
             toparty: toParty,
             totag: toTag,
             msgtype: mediaType,
-            agentid: agent.agentId,
+            agentid: requireAgentId(agent),
             [mediaType]: mediaPayload
         };
 

package/src/agent/api-client.upload.test.ts

@@ -0,0 +1,110 @@
+import { beforeEach, describe, expect, it, vi } from "vitest";
+import type { ResolvedAgentAccount } from "../types/index.js";
+
+const { wecomFetchMock, resolveProxyMock } = vi.hoisted(() => ({
+  wecomFetchMock: vi.fn(),
+  resolveProxyMock: vi.fn(() => undefined),
+}));
+
+vi.mock("../http.js", () => ({
+  wecomFetch: wecomFetchMock,
+  readResponseBodyAsBuffer: vi.fn(),
+}));
+
+vi.mock("../config/index.js", () => ({
+  resolveWecomEgressProxyUrlFromNetwork: resolveProxyMock,
+}));
+
+import { uploadMedia } from "./api-client.js";
+
+function createAgent(agentId: number): ResolvedAgentAccount {
+  return {
+    accountId: `acct-${agentId}`,
+    enabled: true,
+    configured: true,
+    corpId: "corp",
+    corpSecret: "secret",
+    agentId,
+    token: "token",
+    encodingAESKey: "aes",
+    config: {} as any,
+  };
+}
+
+function jsonResponse(body: unknown): Response {
+  return new Response(JSON.stringify(body), {
+    status: 200,
+    headers: { "Content-Type": "application/json" },
+  });
+}
+
+describe("wecom agent uploadMedia", () => {
+  beforeEach(() => {
+    wecomFetchMock.mockReset();
+    resolveProxyMock.mockReset();
+    resolveProxyMock.mockReturnValue(undefined);
+  });
+
+  it("uses text/plain for .txt uploads", async () => {
+    wecomFetchMock.mockResolvedValueOnce(jsonResponse({ access_token: "token-1", expires_in: 7200 }));
+    wecomFetchMock.mockResolvedValueOnce(jsonResponse({ errcode: 0, errmsg: "ok", media_id: "m-1" }));
+
+    const mediaId = await uploadMedia({
+      agent: createAgent(10001),
+      type: "file",
+      buffer: Buffer.from("hello txt"),
+      filename: "note.txt",
+    });
+
+    expect(mediaId).toBe("m-1");
+    const [, init] = wecomFetchMock.mock.calls[1] as [string, RequestInit];
+    const body = init.body as Buffer;
+    const bodyText = body.toString("utf8");
+    expect(bodyText).toContain('filename="note.txt"');
+    expect(bodyText).toContain("Content-Type: text/plain");
+  });
+
+  it("uses docx mime and normalizes non-ascii filename", async () => {
+    wecomFetchMock.mockResolvedValueOnce(jsonResponse({ access_token: "token-2", expires_in: 7200 }));
+    wecomFetchMock.mockResolvedValueOnce(jsonResponse({ errcode: 0, errmsg: "ok", media_id: "m-2" }));
+
+    const mediaId = await uploadMedia({
+      agent: createAgent(10002),
+      type: "file",
+      buffer: Buffer.from("docx bytes"),
+      filename: "需求文档.docx",
+    });
+
+    expect(mediaId).toBe("m-2");
+    const [, init] = wecomFetchMock.mock.calls[1] as [string, RequestInit];
+    const body = init.body as Buffer;
+    const bodyText = body.toString("utf8");
+    expect(bodyText).toContain('filename="file.docx"');
+    expect(bodyText).toContain(
+      "Content-Type: application/vnd.openxmlformats-officedocument.wordprocessingml.document",
+    );
+  });
+
+  it("retries with octet-stream when preferred mime upload fails", async () => {
+    wecomFetchMock.mockResolvedValueOnce(jsonResponse({ access_token: "token-3", expires_in: 7200 }));
+    wecomFetchMock.mockResolvedValueOnce(jsonResponse({ errcode: 40005, errmsg: "invalid media type" }));
+    wecomFetchMock.mockResolvedValueOnce(jsonResponse({ errcode: 0, errmsg: "ok", media_id: "m-3" }));
+
+    const mediaId = await uploadMedia({
+      agent: createAgent(10003),
+      type: "file",
+      buffer: Buffer.from("yaml bytes"),
+      filename: "config.yaml",
+    });
+
+    expect(mediaId).toBe("m-3");
+    expect(wecomFetchMock).toHaveBeenCalledTimes(3);
+
+    const [, firstUploadInit] = wecomFetchMock.mock.calls[1] as [string, RequestInit];
+    const [, retryUploadInit] = wecomFetchMock.mock.calls[2] as [string, RequestInit];
+    const firstUploadBody = (firstUploadInit.body as Buffer).toString("utf8");
+    const retryUploadBody = (retryUploadInit.body as Buffer).toString("utf8");
+    expect(firstUploadBody).toContain("Content-Type: application/yaml");
+    expect(retryUploadBody).toContain("Content-Type: application/octet-stream");
+  });
+});

package/src/agent/handler.event-filter.test.ts

@@ -0,0 +1,50 @@
+import { describe, expect, it } from "vitest";
+
+import { shouldProcessAgentInboundMessage } from "./handler.js";
+
+describe("shouldProcessAgentInboundMessage", () => {
+    it("skips event callbacks so they do not create sessions", () => {
+        const enterAgent = shouldProcessAgentInboundMessage({
+            msgType: "event",
+            eventType: "enter_agent",
+            fromUser: "zhangsan",
+        });
+        expect(enterAgent.shouldProcess).toBe(false);
+        expect(enterAgent.reason).toBe("event:enter_agent");
+
+        const subscribe = shouldProcessAgentInboundMessage({
+            msgType: "event",
+            eventType: "subscribe",
+            fromUser: "lisi",
+        });
+        expect(subscribe.shouldProcess).toBe(false);
+        expect(subscribe.reason).toBe("event:subscribe");
+    });
+
+    it("skips system sender callbacks", () => {
+        const systemSender = shouldProcessAgentInboundMessage({
+            msgType: "text",
+            fromUser: "sys",
+        });
+        expect(systemSender.shouldProcess).toBe(false);
+        expect(systemSender.reason).toBe("system_sender");
+    });
+
+    it("skips messages with missing sender id", () => {
+        const missingSender = shouldProcessAgentInboundMessage({
+            msgType: "text",
+            fromUser: "   ",
+        });
+        expect(missingSender.shouldProcess).toBe(false);
+        expect(missingSender.reason).toBe("missing_sender");
+    });
+
+    it("allows normal user text message processing", () => {
+        const normalMessage = shouldProcessAgentInboundMessage({
+            msgType: "text",
+            fromUser: "wangwu",
+        });
+        expect(normalMessage.shouldProcess).toBe(true);
+        expect(normalMessage.reason).toBe("user_message");
+    });
+});