@yanhaidao/wecom 2.2.7 → 2.3.2

package/changelog/v2.3.2.md

@@ -0,0 +1,70 @@
+# 🚀 OpenClaw 企业微信 (WeCom) 插件 v2.3.2 - Bot/Agent 交付收口与文件发送兼容性增强
+
+本次 v2.3.2 版本聚焦修复企业微信 Bot 模式在复杂交付场景下的稳定性问题，重点解决：
+- Bot 已收到文件但界面仍停留在“正在搜索相关内容”不结束。
+- 本地文件下发时，`txt`、`docx` 以及更多文件类型发送不稳定的问题。
+
+---
+
+### 🌟 版本亮点 (Release Highlights)
+
+* ✅ **修复“正在搜索相关内容”不收口**：Agent 链路执行完成后，Bot 会主动推送最终流帧，确保企微思考态正确结束。
+* 🔒 **修复消息工具绕过链路问题**：在 WeCom Bot 会话中正确禁用顶层 `message` 工具，避免模型绕开 Bot 流式交付导致链路错位。
+* 📁 **本地路径下发能力增强**：支持识别 `/root`、`/home` 等 Linux 常见路径，减少文件请求误分流。
+* 📄 **文件类型兼容大幅提升**：补齐 `txt`、`docx`、`xlsx`、`pptx`、`csv`、`zip` 等常见类型 MIME，并增强入站媒体类型推断准确率。
+* 🛟 **未知类型自动兜底**：上传失败时自动回退到 `application/octet-stream` 重试，提高“能发出去”的成功率。
+
+---
+
+### 📝 详细更新日志 (Changelog)
+
+#### 【交付稳定性】🔄 Bot/Agent 链路收口修复
+- 增加统一“最终流帧”主动推送逻辑，确保 `response_url` 可用时会主动收口。
+- 当回复内容为空时增加最终可见兜底文案，避免企微前端悬空态。
+- 非图片文件、媒体处理失败、超时切换等场景统一走“Bot 提示 + Agent 私信兜底”闭环。
+
+#### 【链路一致性】🧭 工具策略修复
+- 在 WeCom Bot 会话中将 `message` 工具写入 `tools.deny`（并同步 sandbox deny），修复错误禁用位置造成的链路绕过。
+- 避免“文件已发出但 Bot 思考流未结束”的链路错位。
+
+#### 【文件兼容性】📎 MIME 与上传兜底增强
+- 扩展本地文件 MIME 推断覆盖：`txt/csv/tsv/md/json/xml/yaml/yml/pdf/doc/docx/xls/xlsx/ppt/pptx/zip/rar/7z/tar/gz/tgz/rtf/odt`。
+- 上传 multipart 时增加文件名规范化，降低特殊文件名导致的兼容性问题。
+- 新增“首选 MIME 失败 -> octet-stream 自动重试”机制，提升未知/边缘类型上传成功率。
+
+#### 【类型识别优化】🧠 入站文件名与后缀判定更准确
+- 下载并解密媒体时保留源信息（`content-type`、`content-disposition`、最终 URL），用于后续精确判断。
+- 新增三层文件类型判定策略（按优先级）：
+  - 二进制内容特征（Magic Number / 文件头）
+  - 非泛型响应头 `content-type`
+  - 文件名后缀映射
+- 文件名确定策略（按优先级）：
+  - 回调体显式文件名字段
+  - 下载响应 `content-disposition` 文件名
+  - URL 路径 basename（仅在看起来是有效文件名时采用）
+  - 兜底默认名（自动补扩展名）
+- 对 OOXML（`docx/xlsx/pptx`）增加 ZIP 内容探测，降低仅靠 URL 无后缀时误判为 `zip/bin` 的概率。
+
+#### 【质量保障】✅ 回归测试补充
+- 新增上传链路单测，覆盖：
+  - `.txt` 使用 `text/plain`
+  - `.docx` 使用官方 MIME
+  - 首次 MIME 失败时自动回退重试
+- 同步通过 WeCom monitor/outbound 相关回归测试，确保无行为回退。
+
+---
+
+### 💾 安装与升级 (Install & Update)
+
+使用 **OpenClaw** CLI 一键升级 **插件**：
+
+```bash
+openclaw plugins upgrade wecom
+```
+
+或手动更新版本至 `v2.3.2`。
+
+---
+
+### 📮 联系我们
+如果您在 **企业微信 / 微信** 接入过程中遇到任何问题，欢迎提交 Issue 反馈日志与复现场景。

package/compat-single-account.md

@@ -0,0 +1,118 @@
+# 附录 A：WeCom 单账号兼容模式配置指南
+
+> 本文档用于历史部署或小规模场景。  
+> 新项目默认推荐多账号矩阵配置（`accounts + bindings.match.accountId`）。
+
+## A.1 适用场景
+
+- 已在线运行单账号配置，短期内不希望迁移。
+- 只有一个 Bot / Agent，不需要账号隔离。
+- 本地 PoC 或临时验证链路。
+
+## A.2 快速配置
+
+### A.2.1 仅 Bot（单智能体）
+
+```bash
+openclaw config set channels.wecom.enabled true
+openclaw config set channels.wecom.bot.token "YOUR_BOT_TOKEN"
+openclaw config set channels.wecom.bot.encodingAESKey "YOUR_BOT_AES_KEY"
+openclaw config set channels.wecom.bot.receiveId ""
+openclaw config set channels.wecom.bot.streamPlaceholderContent "正在思考..."
+openclaw config set channels.wecom.bot.welcomeText "你好！我是 AI 助手"
+
+# DM 门禁（推荐显式设置 policy）
+openclaw config set channels.wecom.bot.dm.policy "open"
+openclaw config set channels.wecom.bot.dm.allowFrom '["*"]'
+```
+
+### A.2.2 增加 Agent 兜底（可选）
+
+```bash
+openclaw config set channels.wecom.agent.corpId "YOUR_CORP_ID"
+openclaw config set channels.wecom.agent.corpSecret "YOUR_CORP_SECRET"
+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.policy "open"
+openclaw config set channels.wecom.agent.dm.allowFrom '["*"]'
+```
+
+### A.2.3 验证
+
+```bash
+openclaw gateway restart
+openclaw channels status
+```
+
+## A.3 完整单账号配置结构
+
+```jsonc
+{
+  "channels": {
+    "wecom": {
+      "enabled": true,
+
+      "bot": {
+        "aibotid": "BOT_ID_OPTIONAL",
+        "token": "YOUR_BOT_TOKEN",
+        "encodingAESKey": "YOUR_BOT_AES_KEY",
+        "botIds": ["BOT_ID_OPTIONAL"],
+        "receiveId": "",
+        "streamPlaceholderContent": "正在思考...",
+        "welcomeText": "你好！我是 AI 助手",
+        "dm": {
+          "policy": "open",
+          "allowFrom": ["*"]
+        }
+      },
+
+      "agent": {
+        "corpId": "YOUR_CORP_ID",
+        "corpSecret": "YOUR_CORP_SECRET",
+        "agentId": 1000001,
+        "token": "YOUR_CALLBACK_TOKEN",
+        "encodingAESKey": "YOUR_CALLBACK_AES_KEY",
+        "welcomeText": "欢迎使用智能助手",
+        "dm": {
+          "policy": "open",
+          "allowFrom": ["*"]
+        }
+      },
+
+      "media": {
+        "tempDir": "/tmp/openclaw-wecom-media",
+        "retentionHours": 24,
+        "cleanupOnStart": true,
+        "maxBytes": 26214400
+      },
+
+      "network": {
+        "timeoutMs": 15000,
+        "retries": 2,
+        "retryDelayMs": 500,
+        "egressProxyUrl": "http://proxy.company.local:3128"
+      },
+
+      "dynamicAgents": {
+        "enabled": false,
+        "dmCreateAgent": false,
+        "groupEnabled": false,
+        "adminUsers": []
+      }
+    }
+  }
+}
+```
+
+## A.4 Webhook 路径
+
+- Bot: `/wecom/bot`
+- Agent: `/wecom/agent`
+
+## A.5 迁移建议
+
+如果后续需要多 Bot / 多 Agent 隔离，建议迁移到多账号矩阵模式：
+- 在 `channels.wecom.accounts.<accountId>` 下拆分配置
+- 通过 `bindings[].match.accountId` 映射到对应 OpenClaw agent

package/package.json

@@ -1,8 +1,16 @@
 {
   "name": "@yanhaidao/wecom",
-  "version": "2.2.7",
+  "version": "2.3.2",
   "type": "module",
   "description": "OpenClaw WeCom (WeChat Work) intelligent bot channel plugin",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/YanHaidao/wecom.git"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "license": "ISC",
   "author": "YanHaidao (VX: YanHaidao)",
   "openclaw": {
     "extensions": [
@@ -37,7 +45,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");
+    });
+});