@yanhaidao/wecom 2.3.270 → 2.4.160

package/src/transport/bot-ws/inbound.ts

@@ -22,6 +22,8 @@ function resolveInboundKind(message: BaseMessage | EventMessage): WecomInboundKi
       return "file";
     case "voice":
       return "voice";
+    case "video":
+      return "video";
     case "mixed":
       return "mixed";
     default:
@@ -29,6 +31,18 @@ function resolveInboundKind(message: BaseMessage | EventMessage): WecomInboundKi
   }
 }
 
+function pushAttachment(
+  list: NonNullable<UnifiedInboundEvent["attachments"]>,
+  name: "image" | "file" | "video",
+  remoteUrl?: string,
+  aesKey?: string,
+): void {
+  if (!remoteUrl) {
+    return;
+  }
+  list.push({ name, remoteUrl, aesKey });
+}
+
 function resolveEventText(message: BaseMessage | EventMessage, account: ResolvedBotAccount): string {
   if (message.msgtype !== "event") {
     return buildInboundBody(message as WecomBotInboundMessage);
@@ -56,27 +70,60 @@ export function mapBotWsFrameToInboundEvent(params: {
   const inboundKind = resolveInboundKind(body);
 
   let attachments: UnifiedInboundEvent["attachments"];
+  const collected: NonNullable<UnifiedInboundEvent["attachments"]> = [];
   if (body.msgtype === "image") {
-    attachments = [{ name: "image", remoteUrl: (body as any).image?.url, aesKey: (body as any).image?.aeskey }];
+    pushAttachment(collected, "image", (body as any).image?.url, (body as any).image?.aeskey);
   } else if (body.msgtype === "file") {
-    attachments = [{ name: "file", remoteUrl: (body as any).file?.url, aesKey: (body as any).file?.aeskey }];
+    pushAttachment(collected, "file", (body as any).file?.url, (body as any).file?.aeskey);
+  } else if (body.msgtype === "video") {
+    pushAttachment(collected, "video", (body as any).video?.url, (body as any).video?.aeskey);
   } else if (body.msgtype === "mixed") {
     const items = (body as any).mixed?.msg_item;
     if (Array.isArray(items)) {
-      attachments = [];
       for (const item of items) {
-        if (item.msgtype === "image" && item.image?.url) {
-          attachments.push({ name: "image", remoteUrl: item.image.url, aesKey: item.image.aeskey });
-        } else if (item.msgtype === "file" && item.file?.url) {
-          attachments.push({ name: "file", remoteUrl: item.file.url, aesKey: item.file.aeskey });
+        const itemType = String(item.msgtype ?? "").toLowerCase();
+        if (itemType === "image") {
+          pushAttachment(collected, "image", item.image?.url, item.image?.aeskey);
+        } else if (itemType === "file") {
+          pushAttachment(collected, "file", item.file?.url, item.file?.aeskey);
+        } else if (itemType === "video") {
+          pushAttachment(collected, "video", item.video?.url, item.video?.aeskey);
         }
       }
-      if (attachments.length === 0) {
-        attachments = undefined;
+    }
+  }
+
+  // 新增支持：如果没有顶层媒体，尝试从引用中提取媒体附件
+  // 优先级：quote.image/file/video 优先，其次 quote.mixed 中第一个图片
+  if (collected.length === 0) {
+    const quote = (body as any).quote;
+    if (quote) {
+      const quoteType = String(quote.msgtype ?? "").toLowerCase();
+      // 处理单个媒体类型的引用
+      if (quoteType === "image") {
+        pushAttachment(collected, "image", quote.image?.url, quote.image?.aeskey);
+      } else if (quoteType === "file") {
+        pushAttachment(collected, "file", quote.file?.url, quote.file?.aeskey);
+      } else if (quoteType === "video") {
+        pushAttachment(collected, "video", quote.video?.url, quote.video?.aeskey);
+      } 
+      // 处理图文混合类型：只提取第一个图片以保持与 webhook 一致
+      else if (quoteType === "mixed" && Array.isArray(quote.mixed?.msg_item)) {
+        for (const item of quote.mixed.msg_item) {
+          const itemType = String(item.msgtype ?? "").toLowerCase();
+          if (itemType === "image") {
+            pushAttachment(collected, "image", item.image?.url, item.image?.aeskey);
+            break;
+          }
+        }
       }
     }
   }
 
+  if (collected.length > 0) {
+    attachments = collected;
+  }
+
   return {
     accountId: account.accountId,
     capability: "bot",
@@ -111,6 +158,6 @@ export function mapBotWsFrameToInboundEvent(params: {
         envelopeType: "ws",
       },
     },
-    attachments,
+    ...(attachments && { attachments }),
   };
 }

package/src/types/config.ts

@@ -11,11 +11,14 @@ export type WecomMediaConfig = {
   retentionHours?: number;
   cleanupOnStart?: boolean;
   maxBytes?: number;
+  downloadTimeoutMs?: number;
   localRoots?: string[];
 };
 
 export type WecomNetworkConfig = {
   egressProxyUrl?: string;
+  timeoutMs?: number;
+  mediaDownloadTimeoutMs?: number;
 };
 
 export type WecomRoutingConfig = {
@@ -48,6 +51,16 @@ export type WecomBotConfig = {
   webhook?: WecomBotWebhookConfig;
 };
 
+/**
+ * 上下游企业配置
+ * 根据企业微信文档，只需要配置下游企业的 CorpID 和 AgentID
+ * 不需要下游企业的 agentSecret，使用主企业的 corpSecret 获取下游企业的 access_token
+ */
+export type WecomUpstreamCorpConfig = {
+  corpId: string;
+  agentId: number;
+};
+
 export type WecomAgentConfig = {
   corpId: string;
   agentSecret?: string;
@@ -61,6 +74,14 @@ export type WecomAgentConfig = {
   encodingAESKey: string;
   welcomeText?: string;
   dm?: WecomDmConfig;
+  /**
+   * 上下游企业配置映射
+   * key: 配置名称（可自定义）
+   * value: 下游企业的 CorpID 和 AgentID
+   * 
+   * 注意：不需要配置 agentSecret，使用主企业的 corpSecret 获取下游企业的 access_token
+   */
+  upstreamCorps?: Record<string, WecomUpstreamCorpConfig>;
 };
 
 export type WecomDynamicAgentsConfig = {
@@ -81,6 +102,7 @@ export type WecomAccountConfig = {
 export type WecomConfig = {
   enabled?: boolean;
   mediaMaxMb?: number;
+  mediaDownloadTimeoutMs?: number;
   bot?: WecomBotConfig;
   agent?: WecomAgentConfig;
   accounts?: Record<string, WecomAccountConfig>;

package/src/types/message.ts

@@ -59,14 +59,16 @@ export type WecomBotInboundEvent = WecomBotInboundBase & {
  * **WecomInboundQuote (引用消息)**
  * 
  * 消息中引用的原始内容（如回复某条消息）。
- * 支持引用文本、图片、混合类型、语音、文件等。
+ * 支持引用文本、图片、混合类型、语音、文件、视频等多种媒体类型。
+ * 
+ * 注意：引用中的媒体 URL 时效约 5 分钟，必须尽快下载和解密。
  */
 export type WecomInboundQuote = {
-    msgtype?: "text" | "image" | "mixed" | "voice" | "file";
+    msgtype?: "text" | "image" | "mixed" | "voice" | "file" | "video";
     /** 引用文本内容 */
     text?: { content?: string };
-    /** 引用图片 URL */
-    image?: { url?: string };
+    /** 引用图片 URL，可包含出现时的加密密钥 aeskey */
+    image?: { url?: string; aeskey?: string };
     /** 引用混合消息 (图文) */
     mixed?: {
         msg_item?: Array<{
@@ -75,10 +77,12 @@ export type WecomInboundQuote = {
             image?: { url?: string };
         }>;
     };
-    /** 引用语音 */
+    /** 引用语音 - 仅含转写文本，无 URL 需下载（按纯文本处理） */
     voice?: { content?: string };
-    /** 引用文件 */
-    file?: { url?: string };
+    /** 引用文件 URL 及其加密密钥 */
+    file?: { url?: string; aeskey?: string };
+    /** 引用视频 URL 及其加密密钥（新增支持） */
+    video?: { url?: string; aeskey?: string };
 };
 
 export type WecomBotInboundMessage =

package/src/upstream/index.ts

@@ -0,0 +1,150 @@
+/**
+ * 上下游企业支持模块
+ * 
+ * 根据企业微信文档：https://developer.work.weixin.qq.com/document/path/97213
+ * 
+ * 关键逻辑：
+ * 1. 上下游企业消息中的 ToUserName 是下游企业的 CorpID
+ * 2. 需要使用下游企业的 access_token 来发送消息
+ * 3. 获取下游企业 access_token 的接口：
+ *    POST https://qyapi.weixin.qq.com/cgi-bin/corpgroup/corp/gettoken?access_token=ACCESS_TOKEN
+ *    {
+ *      "corpid": "下游企业corpid",
+ *      "business_type": 1,  // 1 表示上下游企业
+ *      "agentid": 下游企业应用ID
+ *    }
+ * 4. 需要使用上游企业的 access_token 作为调用凭证
+ */
+
+import type { ResolvedAgentAccount } from "../types/index.js";
+
+export type UpstreamCorpConfig = {
+  corpId: string;
+  agentId: number;
+};
+
+/**
+ * 从消息中检测是否是上下游用户
+ * 通过比较消息中的 ToUserName（CorpID）与配置的 CorpID
+ */
+export function detectUpstreamUser(params: {
+  messageToUserName: string;
+  primaryCorpId: string;
+}): boolean {
+  const { messageToUserName, primaryCorpId } = params;
+  if (!messageToUserName?.trim() || !primaryCorpId?.trim()) {
+    return false;
+  }
+  const normalizedMessageCorpId = messageToUserName.trim().toLowerCase();
+  const normalizedPrimaryCorpId = primaryCorpId.trim().toLowerCase();
+
+  // 如果消息中的 CorpID 与主 CorpID 不同，则是上下游用户
+  return normalizedMessageCorpId !== normalizedPrimaryCorpId;
+}
+
+/**
+ * 为上下游用户创建临时的 Agent 配置
+ * 使用下游企业的 CorpID 和 AgentID，但保持主企业的 corpSecret
+ * 
+ * 注意：这个配置用于发送消息，但获取 access_token 时需要使用专门的
+ * corpgroup/corp/gettoken 接口
+ */
+export function createUpstreamAgentConfig(params: {
+  baseAgent: ResolvedAgentAccount;
+  upstreamCorpId: string;
+  upstreamAgentId: number;
+}): ResolvedAgentAccount {
+  const { baseAgent, upstreamCorpId, upstreamAgentId } = params;
+  
+  return {
+    ...baseAgent,
+    corpId: upstreamCorpId,
+    agentId: upstreamAgentId,
+    // corpSecret 保持主企业的，用于获取下游企业的 access_token
+    // token 和 encodingAESKey 保持主企业的，用于回调验证
+  };
+}
+
+/**
+ * 从配置中解析上下游企业映射
+ * 支持在 agent 配置中添加 upstreamCorps 字段
+ */
+export function resolveUpstreamCorpConfig(params: {
+  upstreamCorpId: string;
+  upstreamCorps?: Record<string, UpstreamCorpConfig> | UpstreamCorpConfig[];
+}): UpstreamCorpConfig | undefined {
+  const { upstreamCorpId, upstreamCorps } = params;
+
+  if (!upstreamCorps) {
+    return undefined;
+  }
+
+  // Normalize to array format (support both Record<string, ...> and array)
+  const entries: Array<[string, UpstreamCorpConfig]> = Array.isArray(upstreamCorps)
+    ? upstreamCorps.map((item, i) => [String(i), item])
+    : Object.entries(upstreamCorps);
+
+  // Find matching upstream config
+  const normalizedTargetCorpId = upstreamCorpId.trim().toLowerCase();
+
+  for (const [key, config] of entries) {
+    const normalizedConfigCorpId = config.corpId.trim().toLowerCase();
+
+    if (normalizedConfigCorpId === normalizedTargetCorpId) {
+      return config;
+    }
+  }
+
+  return undefined;
+}
+
+/**
+ * 构建上下游用户的回复目标
+ * 格式: wecom-agent-upstream:{accountId}:{corpId}:{userId}
+ */
+export function buildUpstreamAgentSessionTarget(
+  userId: string,
+  accountId: string,
+  upstreamCorpId: string,
+): string {
+  return `wecom-agent-upstream:${accountId}:${upstreamCorpId}:${userId}`;
+}
+
+/**
+ * 解析上下游用户的回复目标
+ */
+export function parseUpstreamAgentSessionTarget(
+  target: string,
+): { accountId: string; upstreamCorpId: string; userId: string } | undefined {
+  const prefix = "wecom-agent-upstream:";
+  if (target.startsWith(prefix)) {
+    const parts = target.slice(prefix.length).split(":");
+    if (parts.length !== 3) {
+      return undefined;
+    }
+
+    return {
+      accountId: parts[0]!,
+      upstreamCorpId: parts[1]!,
+      userId: parts[2]!,
+    };
+  }
+
+  // 兼容当前工作区里尚未持久化的新格式，避免旧会话目标失效。
+  const queryIndex = target.indexOf("?upstream_corp=");
+  if (queryIndex < 0 || !target.startsWith("wecom-agent:")) {
+    return undefined;
+  }
+  const pathPart = target.slice(0, queryIndex);
+  const upstreamCorpId = target.slice(queryIndex + "?upstream_corp=".length).trim();
+  const match = pathPart.match(/^wecom-agent:([^:]+):user:(.+)$/i);
+  if (!match || !upstreamCorpId) {
+    return undefined;
+  }
+
+  return {
+    accountId: match[1]!.trim(),
+    upstreamCorpId,
+    userId: match[2]!.trim(),
+  };
+}

package/src/upstream.test.ts

@@ -0,0 +1,84 @@
+import { describe, expect, it } from "vitest";
+
+import { resolveScopedWecomTarget } from "./target.js";
+import {
+  buildUpstreamAgentSessionTarget,
+  parseUpstreamAgentSessionTarget,
+} from "./upstream/index.js";
+
+describe("upstream target helpers", () => {
+  it("builds and parses the canonical upstream agent target", () => {
+    const target = buildUpstreamAgentSessionTarget("zhangsan", "acct-a", "corp-up");
+
+    expect(target).toBe("wecom-agent-upstream:acct-a:corp-up:zhangsan");
+    expect(parseUpstreamAgentSessionTarget(target)).toEqual({
+      accountId: "acct-a",
+      upstreamCorpId: "corp-up",
+      userId: "zhangsan",
+    });
+  });
+
+  it("keeps compatibility with legacy upstream-prefixed targets", () => {
+    expect(
+      parseUpstreamAgentSessionTarget("wecom-agent-upstream:acct-a:corp-up:zhangsan"),
+    ).toEqual({
+      accountId: "acct-a",
+      upstreamCorpId: "corp-up",
+      userId: "zhangsan",
+    });
+  });
+
+  it("keeps compatibility with query-style upstream targets", () => {
+    expect(
+      parseUpstreamAgentSessionTarget(
+        "wecom-agent:acct-a:user:zhangsan?upstream_corp=corp-up",
+      ),
+    ).toEqual({
+      accountId: "acct-a",
+      upstreamCorpId: "corp-up",
+      userId: "zhangsan",
+    });
+  });
+
+  it("resolves upstream-scoped targets to the real touser without leaking corp metadata", () => {
+    expect(
+      resolveScopedWecomTarget("wecom-agent-upstream:acct-a:corp-up:zhangsan", "default"),
+    ).toEqual({
+      accountId: "acct-a",
+      target: { touser: "zhangsan" },
+      rawTarget: "zhangsan",
+    });
+
+    expect(
+      resolveScopedWecomTarget(
+        "wecom-agent:acct-a:user:zhangsan?upstream_corp=corp-up",
+        "default",
+      ),
+    ).toEqual({
+      accountId: "acct-a",
+      target: { touser: "zhangsan" },
+      rawTarget: "zhangsan",
+    });
+  });
+
+  it("keeps normal users and upstream users distinguishable", () => {
+    // 普通用户目标：不带 upstream 标识，应按普通 agent target 解析
+    expect(resolveScopedWecomTarget("wecom-agent:acct-a:user:zhangsan", "default")).toEqual({
+      accountId: "acct-a",
+      target: { touser: "zhangsan" },
+      rawTarget: "user:zhangsan",
+    });
+
+    // 上下游用户目标：带 upstream_corp，应走 upstream 解析
+    expect(
+      resolveScopedWecomTarget(
+        "wecom-agent:acct-a:user:zhangsan?upstream_corp=corp-up",
+        "default",
+      ),
+    ).toEqual({
+      accountId: "acct-a",
+      target: { touser: "zhangsan" },
+      rawTarget: "zhangsan",
+    });
+  });
+});

package/vitest.config.ts

@@ -1,15 +1,26 @@
-import { defineConfig } from "vitest/config";
+import { existsSync } from "node:fs";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
 
-import baseConfig from "../../vitest.config.ts";
+import { defineConfig } from "vitest/config";
 
-const baseTest = (baseConfig as { test?: { exclude?: string[] } }).test ?? {};
+const currentDir = path.dirname(fileURLToPath(import.meta.url));
+const sharedConfigPath = path.resolve(currentDir, "../../vitest.config.ts");
+const sharedConfigModule = existsSync(sharedConfigPath)
+  ? await import(sharedConfigPath)
+  : undefined;
+const baseConfig = (sharedConfigModule?.default ?? {}) as { test?: { exclude?: string[] } };
+const baseTest = baseConfig.test ?? {};
 const exclude = baseTest.exclude ?? [];
+const include = sharedConfigModule
+  ? ["extensions/wecom/src/**/*.test.ts"]
+  : ["src/**/*.test.ts", "index.test.ts"];
 
 export default defineConfig({
   ...baseConfig,
   test: {
     ...baseTest,
-    include: ["extensions/wecom/src/**/*.test.ts"],
+    include,
     exclude,
   },
 });