@yanhaidao/wecom 2.3.270 → 2.4.120

package/src/agent/event-router.test.ts

@@ -0,0 +1,421 @@
+import path from "node:path";
+import { describe, expect, it } from "vitest";
+
+import { routeAgentInboundEvent } from "./event-router.js";
+import type { ResolvedAgentAccount, WecomAgentInboundMessage } from "../types/index.js";
+import type { WecomRuntimeAuditEvent } from "../types/runtime-context.js";
+
+function createAgent(overrides?: Partial<ResolvedAgentAccount>): ResolvedAgentAccount {
+  return {
+    accountId: "default",
+    configured: true,
+    callbackConfigured: true,
+    apiConfigured: true,
+    corpId: "corp-1",
+    corpSecret: "secret",
+    agentId: 1001,
+    token: "token",
+    encodingAESKey: "aes",
+    eventEnabled: true,
+    allowedEventTypes: ["click", "change_contact"],
+    config: {
+      corpId: "corp-1",
+      corpSecret: "secret",
+      agentId: 1001,
+      token: "token",
+      encodingAESKey: "aes",
+    },
+    ...overrides,
+  };
+}
+
+describe("routeAgentInboundEvent", () => {
+  it("ignores unmatched events when unmatchedAction is ignore", async () => {
+    const agent = createAgent({
+      config: {
+        corpId: "corp-1",
+        corpSecret: "secret",
+        agentId: 1001,
+        token: "token",
+        encodingAESKey: "aes",
+        eventRouting: {
+          unmatchedAction: "ignore",
+          routes: [],
+        },
+      },
+    });
+
+    const result = await routeAgentInboundEvent({
+      agent,
+      msgType: "event",
+      eventType: "click",
+      fromUser: "zhangsan",
+      msg: { MsgType: "event", Event: "click", EventKey: "MENU_X" },
+    });
+
+    expect(result.handled).toBe(true);
+    expect(result.chainToAgent).toBe(false);
+    expect(result.reason).toBe("unmatched_event_ignored");
+  });
+
+  it("proxies unmatched events to agent when unmatchedAction is forwardToAgent", async () => {
+    const agent = createAgent({
+      config: {
+        corpId: "corp-1",
+        corpSecret: "secret",
+        agentId: 1001,
+        token: "token",
+        encodingAESKey: "aes",
+        eventRouting: {
+          unmatchedAction: "forwardToAgent",
+          routes: [],
+        },
+      },
+    });
+
+    const result = await routeAgentInboundEvent({
+      agent,
+      msgType: "event",
+      eventType: "click",
+      fromUser: "zhangsan",
+      msg: { MsgType: "event", Event: "click", EventKey: "MENU_X" },
+    });
+
+    expect(result.handled).toBe(false);
+    expect(result.chainToAgent).toBe(true);
+  });
+
+  it("matches builtin echo routes using eventKey", async () => {
+    const agent = createAgent({
+      config: {
+        corpId: "corp-1",
+        corpSecret: "secret",
+        agentId: 1001,
+        token: "token",
+        encodingAESKey: "aes",
+        eventRouting: {
+          routes: [
+            {
+              id: "menu-help",
+              when: { eventType: "click", eventKey: "MENU_HELP" },
+              handler: { type: "builtin", name: "echo" },
+            },
+          ],
+        },
+      },
+    });
+
+    const result = await routeAgentInboundEvent({
+      agent,
+      msgType: "event",
+      eventType: "click",
+      fromUser: "zhangsan",
+      msg: { MsgType: "event", Event: "click", EventKey: "MENU_HELP" },
+    });
+
+    expect(result.handled).toBe(true);
+    expect(result.replyText).toContain("event=click");
+    expect(result.replyText).toContain("eventKey=MENU_HELP");
+    expect(result.matchedRouteId).toBe("menu-help");
+  });
+
+  it("matches change_contact routes using changeType", async () => {
+    const agent = createAgent({
+      config: {
+        corpId: "corp-1",
+        corpSecret: "secret",
+        agentId: 1001,
+        token: "token",
+        encodingAESKey: "aes",
+        eventRouting: {
+          routes: [
+            {
+              id: "contact-create-user",
+              when: { eventType: "change_contact", changeType: "create_user" },
+              handler: { type: "builtin", name: "echo" },
+            },
+          ],
+        },
+      },
+    });
+
+    const msg: WecomAgentInboundMessage = {
+      MsgType: "event",
+      Event: "change_contact",
+      ChangeType: "create_user",
+    };
+    const result = await routeAgentInboundEvent({
+      agent,
+      msgType: "event",
+      eventType: "change_contact",
+      fromUser: "sys",
+      msg,
+    });
+
+    expect(result.handled).toBe(true);
+    expect(result.replyText).toContain("changeType=create_user");
+  });
+
+  it("passes full event params to node scripts", async () => {
+    const fixturePath = path.resolve("src/agent/test-fixtures/reply-event-script.mjs");
+    const agent = createAgent({
+      config: {
+        corpId: "corp-1",
+        corpSecret: "secret",
+        agentId: 1001,
+        token: "token",
+        encodingAESKey: "aes",
+        eventRouting: {
+          routes: [
+            {
+              id: "script-click",
+              when: { eventType: "click", eventKeyPrefix: "MENU_" },
+              handler: { type: "node_script", entry: fixturePath },
+            },
+          ],
+        },
+        scriptRuntime: {
+          enabled: true,
+          allowPaths: [path.resolve("src/agent/test-fixtures")],
+          nodeCommand: process.execPath,
+        },
+      },
+    });
+
+    const result = await routeAgentInboundEvent({
+      agent,
+      msgType: "event",
+      eventType: "click",
+      fromUser: "zhangsan",
+      msg: {
+        ToUserName: "corp-1",
+        FromUserName: "zhangsan",
+        MsgType: "event",
+        Event: "click",
+        EventKey: "MENU_HELP",
+        AgentID: 1001,
+      },
+    });
+
+    expect(result.handled).toBe(true);
+    expect(result.replyText).toBe("script:click:MENU_HELP:");
+  });
+
+  it("supports scripts that explicitly continue the default pipeline", async () => {
+    const fixturePath = path.resolve("src/agent/test-fixtures/reply-event-script.mjs");
+    const agent = createAgent({
+      config: {
+        corpId: "corp-1",
+        corpSecret: "secret",
+        agentId: 1001,
+        token: "token",
+        encodingAESKey: "aes",
+        eventRouting: {
+          routes: [
+            {
+              id: "script-click-pass",
+              when: { eventType: "click", eventKey: "PASS_TO_DEFAULT" },
+              handler: { type: "node_script", entry: fixturePath },
+            },
+          ],
+        },
+        scriptRuntime: {
+          enabled: true,
+          allowPaths: [path.resolve("src/agent/test-fixtures")],
+          nodeCommand: process.execPath,
+        },
+      },
+    });
+
+    const result = await routeAgentInboundEvent({
+      agent,
+      msgType: "event",
+      eventType: "click",
+      fromUser: "zhangsan",
+      msg: {
+        MsgType: "event",
+        Event: "click",
+        EventKey: "PASS_TO_DEFAULT",
+      },
+    });
+
+    expect(result.handled).toBe(true);
+    expect(result.chainToAgent).toBe(true);
+    expect(result.replyText).toBeUndefined();
+  });
+
+  it("passes full event params to python scripts", async () => {
+    const fixturePath = path.resolve("src/agent/test-fixtures/reply-event-script.py");
+    const agent = createAgent({
+      config: {
+        corpId: "corp-1",
+        corpSecret: "secret",
+        agentId: 1001,
+        token: "token",
+        encodingAESKey: "aes",
+        eventRouting: {
+          routes: [
+            {
+              id: "script-python-click",
+              when: { eventType: "click", eventKey: "MENU_PY" },
+              handler: { type: "python_script", entry: fixturePath },
+            },
+          ],
+        },
+        scriptRuntime: {
+          enabled: true,
+          allowPaths: [path.resolve("src/agent/test-fixtures")],
+          pythonCommand: "python3",
+        },
+      },
+    });
+
+    const result = await routeAgentInboundEvent({
+      agent,
+      msgType: "event",
+      eventType: "click",
+      fromUser: "zhangsan",
+      msg: {
+        MsgType: "event",
+        Event: "click",
+        EventKey: "MENU_PY",
+      },
+    });
+
+    expect(result.handled).toBe(true);
+    expect(result.replyText).toBe("python:click:MENU_PY:");
+  });
+
+  it("records audit events for successful script execution", async () => {
+    const fixturePath = path.resolve("src/agent/test-fixtures/reply-event-script.mjs");
+    const auditEvents: WecomRuntimeAuditEvent[] = [];
+    const agent = createAgent({
+      config: {
+        corpId: "corp-1",
+        corpSecret: "secret",
+        agentId: 1001,
+        token: "token",
+        encodingAESKey: "aes",
+        eventRouting: {
+          routes: [
+            {
+              id: "script-audit-success",
+              when: { eventType: "click", eventKey: "MENU_AUDIT" },
+              handler: { type: "node_script", entry: fixturePath },
+            },
+          ],
+        },
+        scriptRuntime: {
+          enabled: true,
+          allowPaths: [path.resolve("src/agent/test-fixtures")],
+          nodeCommand: process.execPath,
+        },
+      },
+    });
+
+    await routeAgentInboundEvent({
+      agent,
+      msgType: "event",
+      eventType: "click",
+      fromUser: "zhangsan",
+      msg: {
+        MsgType: "event",
+        Event: "click",
+        EventKey: "MENU_AUDIT",
+      },
+      auditSink: (event) => auditEvents.push(event),
+    });
+
+    expect(auditEvents).toHaveLength(1);
+    expect(auditEvents[0]?.category).toBe("inbound");
+    expect(auditEvents[0]?.summary).toContain("event route script ok");
+  });
+
+  it("captures invalid script output as a routed error and audits it", async () => {
+    const fixturePath = path.resolve("src/agent/test-fixtures/invalid-json-script.mjs");
+    const auditEvents: WecomRuntimeAuditEvent[] = [];
+    const agent = createAgent({
+      config: {
+        corpId: "corp-1",
+        corpSecret: "secret",
+        agentId: 1001,
+        token: "token",
+        encodingAESKey: "aes",
+        eventRouting: {
+          routes: [
+            {
+              id: "script-invalid-json",
+              when: { eventType: "click", eventKey: "MENU_BAD_JSON" },
+              handler: { type: "node_script", entry: fixturePath },
+            },
+          ],
+        },
+        scriptRuntime: {
+          enabled: true,
+          allowPaths: [path.resolve("src/agent/test-fixtures")],
+          nodeCommand: process.execPath,
+        },
+      },
+    });
+
+    const result = await routeAgentInboundEvent({
+      agent,
+      msgType: "event",
+      eventType: "click",
+      fromUser: "zhangsan",
+      msg: {
+        MsgType: "event",
+        Event: "click",
+        EventKey: "MENU_BAD_JSON",
+      },
+      auditSink: (event) => auditEvents.push(event),
+    });
+
+    expect(result.handled).toBe(true);
+    expect(result.chainToAgent).toBe(false);
+    expect(result.reason).toBe("script_node_script_error");
+    expect(result.error).toContain("not valid JSON");
+    expect(auditEvents).toHaveLength(1);
+    expect(auditEvents[0]?.category).toBe("runtime-error");
+  });
+
+  it("treats invalid eventKeyPattern as non-match instead of throwing", async () => {
+    const auditEvents: WecomRuntimeAuditEvent[] = [];
+    const agent = createAgent({
+      config: {
+        corpId: "corp-1",
+        corpSecret: "secret",
+        agentId: 1001,
+        token: "token",
+        encodingAESKey: "aes",
+        eventRouting: {
+          unmatchedAction: "ignore",
+          routes: [
+            {
+              id: "invalid-pattern",
+              when: { eventType: "click", eventKeyPattern: "(*" },
+              handler: { type: "builtin", name: "echo" },
+            },
+          ],
+        },
+      },
+    });
+
+    const result = await routeAgentInboundEvent({
+      agent,
+      msgType: "event",
+      eventType: "click",
+      fromUser: "zhangsan",
+      msg: { MsgType: "event", Event: "click", EventKey: "MENU_X" },
+      auditSink: (event) => auditEvents.push(event),
+    });
+
+    expect(result.handled).toBe(true);
+    expect(result.chainToAgent).toBe(false);
+    expect(result.reason).toBe("unmatched_event_ignored");
+    expect(auditEvents).toHaveLength(1);
+    expect(auditEvents[0]?.category).toBe("runtime-error");
+    expect(auditEvents[0]?.summary).toContain("invalid route eventKeyPattern");
+    expect(auditEvents[0]?.error).toContain("routeId=invalid-pattern");
+  });
+});

package/src/agent/event-router.ts

@@ -0,0 +1,272 @@
+import { extractAgentId, extractMsgId } from "../shared/xml-parser.js";
+import type {
+  ResolvedAgentAccount,
+  WecomAgentEventRouteConfig,
+  WecomAgentInboundMessage,
+} from "../types/index.js";
+import type { WecomRuntimeAuditEvent } from "../types/runtime-context.js";
+import { runAgentEventScript, type AgentEventScriptEnvelope } from "./script-runner.js";
+
+export type AgentInboundEventRouteResult = {
+  handled: boolean;
+  chainToAgent: boolean;
+  replyText?: string;
+  matchedRouteId?: string;
+  reason: string;
+  error?: string;
+};
+
+// 统一比较口径：事件类型按小写处理
+function normalizeLower(value: unknown): string {
+  return String(value ?? "").trim().toLowerCase();
+}
+
+// 事件键值按原大小写保留，仅做首尾清理
+function normalizeText(value: unknown): string {
+  return String(value ?? "").trim();
+}
+
+function testPatternSafe(params: {
+  pattern: string;
+  value: string;
+  onInvalidPattern?: (errorMessage: string) => void;
+}): boolean {
+  try {
+    return new RegExp(params.pattern).test(params.value);
+  } catch (err) {
+    const message = err instanceof Error ? err.message : String(err);
+    params.onInvalidPattern?.(message);
+    // 配置了非法正则时按“不匹配”处理，避免中断 webhook 主流程
+    return false;
+  }
+}
+
+function matchesRoute(params: {
+  route: WecomAgentEventRouteConfig;
+  eventType: string;
+  changeType: string;
+  eventKey: string;
+  onInvalidPattern?: (errorMessage: string) => void;
+}): boolean {
+  // 三层匹配：eventType -> changeType/eventKey（含 prefix/regex）
+  const when = params.route.when ?? {};
+
+  if (when.eventType && normalizeLower(when.eventType) !== params.eventType) return false;
+  if (when.changeType && normalizeLower(when.changeType) !== params.changeType) return false;
+  if (when.eventKey && normalizeText(when.eventKey) !== params.eventKey) return false;
+  if (when.eventKeyPrefix && !params.eventKey.startsWith(normalizeText(when.eventKeyPrefix))) return false;
+  if (when.eventKeyPattern && !testPatternSafe({
+    pattern: when.eventKeyPattern,
+    value: params.eventKey,
+    onInvalidPattern: params.onInvalidPattern,
+  })) return false;
+
+  return true;
+}
+
+function buildScriptEnvelope(params: {
+  accountId: string;
+  msgType: string;
+  eventType: string;
+  eventKey: string;
+  changeType: string;
+  fromUser: string;
+  toUser?: string;
+  chatId?: string;
+  msg: WecomAgentInboundMessage;
+  matchedRuleId: string;
+  handlerType: "node_script" | "python_script";
+}): AgentEventScriptEnvelope {
+  // 透传给外部脚本：标准化字段 + 原始 XML 解析对象 raw
+  const rawAgentId = extractAgentId(params.msg);
+  const numericAgentId = typeof rawAgentId === "number"
+    ? rawAgentId
+    : Number.isFinite(Number(rawAgentId)) ? Number(rawAgentId) : null;
+
+  return {
+    version: "1.0",
+    channel: "wecom",
+    accountId: params.accountId,
+    receivedAt: Date.now(),
+    message: {
+      msgType: params.msgType,
+      eventType: params.eventType,
+      eventKey: params.eventKey || null,
+      changeType: params.changeType || null,
+      fromUser: params.fromUser,
+      toUser: params.toUser ?? null,
+      chatId: params.chatId ?? null,
+      agentId: numericAgentId,
+      createTime: typeof params.msg.CreateTime === "number" ? params.msg.CreateTime : Number.isFinite(Number(params.msg.CreateTime)) ? Number(params.msg.CreateTime) : null,
+      msgId: extractMsgId(params.msg) ?? null,
+      raw: { ...(params.msg as Record<string, unknown>) },
+    },
+    route: {
+      matchedRuleId: params.matchedRuleId,
+      handlerType: params.handlerType,
+    },
+  };
+}
+
+export async function routeAgentInboundEvent(params: {
+  agent: ResolvedAgentAccount;
+  msgType: string;
+  eventType: string;
+  fromUser: string;
+  chatId?: string;
+  msg: WecomAgentInboundMessage;
+  log?: (msg: string) => void;
+  auditSink?: (event: WecomRuntimeAuditEvent) => void;
+}): Promise<AgentInboundEventRouteResult> {
+  if (normalizeLower(params.msgType) !== "event") {
+    return {
+      handled: false,
+      chainToAgent: false,
+      reason: "not_event",
+    };
+  }
+
+  const routing = params.agent.config.eventRouting;
+  const routes = routing?.routes ?? [];
+  const changeType = normalizeLower(params.msg.ChangeType);
+  const eventKey = normalizeText(params.msg.EventKey);
+  // 路由采用“首个命中即执行”策略
+  const matchedRoute = routes.find((route) => matchesRoute({
+    route,
+    eventType: params.eventType,
+    changeType,
+    eventKey,
+    onInvalidPattern: (errorMessage) => {
+      const routeId = route.id?.trim() || "anonymous";
+      params.log?.(
+        `[wecom-agent] invalid eventKeyPattern in route routeId=${routeId} pattern=${route.when?.eventKeyPattern ?? ""} error=${errorMessage}`,
+      );
+      params.auditSink?.({
+        transport: "agent-callback",
+        category: "runtime-error",
+        messageId: extractMsgId(params.msg) ?? undefined,
+        summary: `invalid route eventKeyPattern routeId=${routeId}`,
+        raw: {
+          transport: "agent-callback",
+          envelopeType: "xml",
+          body: params.msg,
+        },
+        error: `routeId=${routeId} pattern=${route.when?.eventKeyPattern ?? ""} error=${errorMessage}`,
+      });
+    },
+  }));
+
+  if (!matchedRoute) {
+    // 未命中时由 unmatchedAction 决定：忽略 or 继续默认 AI 流程
+    if (routing?.unmatchedAction === "forwardToAgent") {
+      return {
+        handled: false,
+        chainToAgent: true,
+        reason: "unmatched_event_forwardToAgent",
+      };
+    }
+    return {
+      handled: true,
+      chainToAgent: false,
+      reason: "unmatched_event_ignored",
+    };
+  }
+
+  const matchedRouteId = matchedRoute.id?.trim() || `${params.eventType || "event"}:${eventKey || "default"}`;
+  params.log?.(`[wecom-agent] event route matched routeId=${matchedRouteId} event=${params.eventType} eventKey=${eventKey || "N/A"}`);
+
+  if (matchedRoute.handler.type === "builtin") {
+    // 内置 handler：当前仅实现 echo，用于联调和最小可用场景
+    if ((matchedRoute.handler.name ?? "echo") === "echo") {
+      const replyText = [`event=${params.eventType}`,
+        eventKey ? `eventKey=${eventKey}` : "",
+        changeType ? `changeType=${changeType}` : "",
+      ].filter(Boolean).join(" ");
+      return {
+        handled: true,
+        chainToAgent: matchedRoute.handler.chainToAgent === true,
+        replyText,
+        matchedRouteId,
+        reason: "builtin_echo",
+      };
+    }
+  }
+
+  if (matchedRoute.handler.type !== "node_script" && matchedRoute.handler.type !== "python_script") {
+    return {
+      handled: true,
+      chainToAgent: false,
+      matchedRouteId,
+      reason: "unsupported_handler",
+    };
+  }
+
+  try {
+    // 外部脚本 handler：通过 stdin 输入 envelope，stdout 返回 JSON 协议
+    const { response: scriptResponse, meta } = await runAgentEventScript({
+      runtime: params.agent.config.scriptRuntime,
+      handler: matchedRoute.handler,
+      envelope: buildScriptEnvelope({
+        accountId: params.agent.accountId,
+        msgType: params.msgType,
+        eventType: params.eventType,
+        eventKey,
+        changeType,
+        fromUser: params.fromUser,
+        toUser: typeof params.msg.ToUserName === "string" ? params.msg.ToUserName : undefined,
+        chatId: params.chatId,
+        msg: params.msg,
+        matchedRuleId: matchedRouteId,
+        handlerType: matchedRoute.handler.type,
+      }),
+    });
+
+    params.auditSink?.({
+      transport: "agent-callback",
+      category: "inbound",
+      messageId: extractMsgId(params.msg) ?? undefined,
+      summary:
+        `event route script ok routeId=${matchedRouteId} handler=${matchedRoute.handler.type} ` +
+        `event=${params.eventType} durationMs=${meta.durationMs} exitCode=${meta.exitCode ?? "null"}`,
+      raw: {
+        transport: "agent-callback",
+        envelopeType: "xml",
+        body: params.msg,
+      },
+    });
+
+    return {
+      handled: true,
+      chainToAgent:
+        scriptResponse.chainToAgent === true || matchedRoute.handler.chainToAgent === true,
+      replyText: scriptResponse.action === "reply_text" ? scriptResponse.reply?.text : undefined,
+      matchedRouteId,
+      reason: `script_${matchedRoute.handler.type}`,
+    };
+  } catch (err) {
+    // 脚本失败时不抛出到上层，转为“已处理 + 审计错误”，避免中断 webhook 主流程
+    const message = err instanceof Error ? err.message : String(err);
+    params.log?.(
+      `[wecom-agent] event route script failed routeId=${matchedRouteId} handler=${matchedRoute.handler.type} error=${message}`,
+    );
+    params.auditSink?.({
+      transport: "agent-callback",
+      category: "runtime-error",
+      messageId: extractMsgId(params.msg) ?? undefined,
+      summary: `event route script failed routeId=${matchedRouteId} handler=${matchedRoute.handler.type} event=${params.eventType}`,
+      raw: {
+        transport: "agent-callback",
+        envelopeType: "xml",
+        body: params.msg,
+      },
+      error: message,
+    });
+    return {
+      handled: true,
+      chainToAgent: false,
+      matchedRouteId,
+      reason: `script_${matchedRoute.handler.type}_error`,
+      error: message,
+    };
+  }
+}