@yanhaidao/wecom 2.4.120 → 2.5.110

package/src/agent/event-router.ts

@@ -1,272 +0,0 @@
-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,
-    };
-  }
-}

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

@@ -1,135 +0,0 @@
-import { describe, expect, it } from "vitest";
-
-import { shouldProcessAgentInboundMessage, shouldSuppressAgentReplyText } from "./handler.js";
-
-describe("shouldProcessAgentInboundMessage", () => {
-    it("allows enter_agent/subscribe through the filter (handled earlier by static welcome)", () => {
-        const enterAgent = shouldProcessAgentInboundMessage({
-            msgType: "event",
-            eventType: "enter_agent",
-            fromUser: "zhangsan",
-        });
-        expect(enterAgent.shouldProcess).toBe(true);
-        expect(enterAgent.reason).toBe("allowed_event:enter_agent");
-
-        const subscribe = shouldProcessAgentInboundMessage({
-            msgType: "event",
-            eventType: "subscribe",
-            fromUser: "lisi",
-        });
-        expect(subscribe.shouldProcess).toBe(true);
-        expect(subscribe.reason).toBe("allowed_event:subscribe");
-    });
-
-    it("skips unknown event callbacks so they do not create sessions", () => {
-        const unknown = shouldProcessAgentInboundMessage({
-            msgType: "event",
-            eventType: "some_random_event",
-            fromUser: "zhangsan",
-        });
-        expect(unknown.shouldProcess).toBe(false);
-        expect(unknown.reason).toBe("event:some_random_event");
-    });
-
-    it("blocks event processing when eventEnabled is false", () => {
-        const disabled = shouldProcessAgentInboundMessage({
-            msgType: "event",
-            eventType: "click",
-            fromUser: "zhangsan",
-            eventEnabled: false,
-        });
-        expect(disabled.shouldProcess).toBe(false);
-        expect(disabled.reason).toBe("event_disabled");
-    });
-
-    it("allows configured custom event types", () => {
-        const custom = shouldProcessAgentInboundMessage({
-            msgType: "event",
-            eventType: "click",
-            fromUser: "zhangsan",
-            eventEnabled: true,
-            allowedEventTypes: ["click"],
-        });
-        expect(custom.shouldProcess).toBe(true);
-        expect(custom.reason).toBe("allowed_event:click");
-    });
-
-    it("normalizes configured event type values before matching", () => {
-        const custom = shouldProcessAgentInboundMessage({
-            msgType: "event",
-            eventType: "view_miniprogram",
-            fromUser: "zhangsan",
-            eventEnabled: true,
-            allowedEventTypes: [" VIEW_MINIPROGRAM "],
-        });
-        expect(custom.shouldProcess).toBe(true);
-        expect(custom.reason).toBe("allowed_event:view_miniprogram");
-    });
-
-    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 group chat messages when sender id is missing", () => {
-        const groupWithoutSender = shouldProcessAgentInboundMessage({
-            msgType: "file",
-            fromUser: "   ",
-            chatId: "wrbchat_123",
-        });
-        expect(groupWithoutSender.shouldProcess).toBe(true);
-        expect(groupWithoutSender.reason).toBe("missing_sender_but_group_chat");
-    });
-
-    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");
-    });
-});
-
-describe("shouldSuppressAgentReplyText", () => {
-    it("keeps plain text replies when no media reply has been seen", () => {
-        expect(
-            shouldSuppressAgentReplyText({
-                text: "这里是正常文本",
-                mediaReplySeen: false,
-            }),
-        ).toBe(false);
-    });
-
-    it("suppresses companion text once the reply flow includes media", () => {
-        expect(
-            shouldSuppressAgentReplyText({
-                text: "文件已发送，请查收",
-                mediaReplySeen: true,
-            }),
-        ).toBe(true);
-    });
-
-    it("does not suppress empty text even after media replies", () => {
-        expect(
-            shouldSuppressAgentReplyText({
-                text: "   ",
-                mediaReplySeen: true,
-            }),
-        ).toBe(false);
-    });
-});