@yanhaidao/wecom 2.3.150 → 2.3.180

package/src/agent/handler.ts

@@ -3,29 +3,42 @@
  * 处理 XML 格式回调
  */
 
-import { pathToFileURL } from "node:url";
-import path from "node:path";
 import type { IncomingMessage, ServerResponse } from "node:http";
+import path from "node:path";
+import { pathToFileURL } from "node:url";
 import type { OpenClawConfig, PluginRuntime } from "openclaw/plugin-sdk";
-import type { ResolvedAgentAccount, UnifiedInboundEvent, WecomInboundKind } from "../types/index.js";
+import type { WecomAccountRuntime } from "../app/account-runtime.js";
+import { resolveWecomMediaMaxBytes, shouldRejectWecomDefaultRoute } from "../config/index.js";
+import {
+  buildAgentSessionTarget,
+  generateAgentId,
+  shouldUseDynamicAgent,
+  ensureDynamicAgentListed,
+} from "../dynamic-agent.js";
+import { getWecomRuntime } from "../runtime.js";
+import { registerWecomSourceSnapshot } from "../runtime/source-registry.js";
 import {
-    extractMsgType,
-    extractFromUser,
-    extractContent,
-    extractChatId,
-    extractMediaId,
-    extractMsgId,
-    extractFileName,
-    extractAgentId,
+  buildWecomUnauthorizedCommandPrompt,
+  resolveWecomCommandAuthorization,
+} from "../shared/command-auth.js";
+import {
+  extractMsgType,
+  extractFromUser,
+  extractContent,
+  extractChatId,
+  extractMediaId,
+  extractMsgId,
+  extractFileName,
+  extractAgentId,
 } from "../shared/xml-parser.js";
 import { downloadAgentApiMedia, sendAgentApiText } from "../transport/agent-api/client.js";
-import { getWecomRuntime } from "../runtime.js";
+import type {
+  ResolvedAgentAccount,
+  UnifiedInboundEvent,
+  WecomInboundKind,
+} from "../types/index.js";
 import type { WecomAgentInboundMessage } from "../types/index.js";
 import type { TransportSessionPatch } from "../types/index.js";
-import type { WecomAccountRuntime } from "../app/account-runtime.js";
-import { buildWecomUnauthorizedCommandPrompt, resolveWecomCommandAuthorization } from "../shared/command-auth.js";
-import { resolveWecomMediaMaxBytes, shouldRejectWecomDefaultRoute } from "../config/index.js";
-import { buildAgentSessionTarget, generateAgentId, shouldUseDynamicAgent, ensureDynamicAgentListed } from "../dynamic-agent.js";
 import type { WecomRuntimeAuditEvent } from "../types/runtime-context.js";
 
 /** 错误提示信息 */
@@ -38,81 +51,81 @@ const recentAgentMsgIds = new Map<string, number>();
 
 // Event deduplication (e.g. for ENTER_AGENT/subscribe welcome messages)
 // We only want to send a welcome message once every 5 minutes per user
-const RECENT_EVENT_TTL_MS =3 * 60 * 1000;
+const RECENT_EVENT_TTL_MS = 3 * 60 * 1000;
 const recentAgentEvents = new Map<string, number>();
 
 function rememberAgentEvent(key: string): boolean {
-    const now = Date.now();
-    const existing = recentAgentEvents.get(key);
-    if (existing && now - existing < RECENT_EVENT_TTL_MS) return false;
-    recentAgentEvents.set(key, now);
-    // Prune expired
-    for (const [k, ts] of recentAgentEvents) {
-        if (now - ts >= RECENT_EVENT_TTL_MS) recentAgentEvents.delete(k);
-    }
-    return true;
+  const now = Date.now();
+  const existing = recentAgentEvents.get(key);
+  if (existing && now - existing < RECENT_EVENT_TTL_MS) return false;
+  recentAgentEvents.set(key, now);
+  // Prune expired
+  for (const [k, ts] of recentAgentEvents) {
+    if (now - ts >= RECENT_EVENT_TTL_MS) recentAgentEvents.delete(k);
+  }
+  return true;
 }
 
 function rememberAgentMsgId(msgId: string): boolean {
-    const now = Date.now();
-    const existing = recentAgentMsgIds.get(msgId);
-    if (existing && now - existing < RECENT_MSGID_TTL_MS) return false;
-    recentAgentMsgIds.set(msgId, now);
-    // 简单清理：只在写入时做一次线性 prune，避免无界增长
-    for (const [k, ts] of recentAgentMsgIds) {
-        if (now - ts >= RECENT_MSGID_TTL_MS) recentAgentMsgIds.delete(k);
-    }
-    return true;
+  const now = Date.now();
+  const existing = recentAgentMsgIds.get(msgId);
+  if (existing && now - existing < RECENT_MSGID_TTL_MS) return false;
+  recentAgentMsgIds.set(msgId, now);
+  // 简单清理：只在写入时做一次线性 prune，避免无界增长
+  for (const [k, ts] of recentAgentMsgIds) {
+    if (now - ts >= RECENT_MSGID_TTL_MS) recentAgentMsgIds.delete(k);
+  }
+  return true;
 }
 
 function looksLikeTextFile(buffer: Buffer): boolean {
-    const sampleSize = Math.min(buffer.length, 4096);
-    if (sampleSize === 0) return true;
-    let bad = 0;
-    for (let i = 0; i < sampleSize; i++) {
-        const b = buffer[i]!;
-        const isWhitespace = b === 0x09 || b === 0x0a || b === 0x0d; // \t \n \r
-        const isPrintable = b >= 0x20 && b !== 0x7f;
-        if (!isWhitespace && !isPrintable) bad++;
-    }
-    // 非可打印字符占比太高，基本可判断为二进制
-    return bad / sampleSize <= 0.02;
+  const sampleSize = Math.min(buffer.length, 4096);
+  if (sampleSize === 0) return true;
+  let bad = 0;
+  for (let i = 0; i < sampleSize; i++) {
+    const b = buffer[i]!;
+    const isWhitespace = b === 0x09 || b === 0x0a || b === 0x0d; // \t \n \r
+    const isPrintable = b >= 0x20 && b !== 0x7f;
+    if (!isWhitespace && !isPrintable) bad++;
+  }
+  // 非可打印字符占比太高，基本可判断为二进制
+  return bad / sampleSize <= 0.02;
 }
 
-function analyzeTextHeuristic(buffer: Buffer): { sampleSize: number; badCount: number; badRatio: number } {
-    const sampleSize = Math.min(buffer.length, 4096);
-    if (sampleSize === 0) return { sampleSize: 0, badCount: 0, badRatio: 0 };
-    let badCount = 0;
-    for (let i = 0; i < sampleSize; i++) {
-        const b = buffer[i]!;
-        const isWhitespace = b === 0x09 || b === 0x0a || b === 0x0d;
-        const isPrintable = b >= 0x20 && b !== 0x7f;
-        if (!isWhitespace && !isPrintable) badCount++;
-    }
-    return { sampleSize, badCount, badRatio: badCount / sampleSize };
+function analyzeTextHeuristic(buffer: Buffer): {
+  sampleSize: number;
+  badCount: number;
+  badRatio: number;
+} {
+  const sampleSize = Math.min(buffer.length, 4096);
+  if (sampleSize === 0) return { sampleSize: 0, badCount: 0, badRatio: 0 };
+  let badCount = 0;
+  for (let i = 0; i < sampleSize; i++) {
+    const b = buffer[i]!;
+    const isWhitespace = b === 0x09 || b === 0x0a || b === 0x0d;
+    const isPrintable = b >= 0x20 && b !== 0x7f;
+    if (!isWhitespace && !isPrintable) badCount++;
+  }
+  return { sampleSize, badCount, badRatio: badCount / sampleSize };
 }
 
 function previewHex(buffer: Buffer, maxBytes = 32): string {
-    const n = Math.min(buffer.length, maxBytes);
-    if (n <= 0) return "";
-    return buffer
-        .subarray(0, n)
-        .toString("hex")
-        .replace(/(..)/g, "$1 ")
-        .trim();
+  const n = Math.min(buffer.length, maxBytes);
+  if (n <= 0) return "";
+  return buffer.subarray(0, n).toString("hex").replace(/(..)/g, "$1 ").trim();
 }
 
 function buildTextFilePreview(buffer: Buffer, maxChars: number): string | undefined {
-    if (!looksLikeTextFile(buffer)) return undefined;
-    const text = buffer.toString("utf8");
-    if (!text.trim()) return undefined;
-    const truncated = text.length > maxChars ? `${text.slice(0, maxChars)}\n…(已截断)` : text;
-    return truncated;
+  if (!looksLikeTextFile(buffer)) return undefined;
+  const text = buffer.toString("utf8");
+  if (!text.trim()) return undefined;
+  const truncated = text.length > maxChars ? `${text.slice(0, maxChars)}\n…(已截断)` : text;
+  return truncated;
 }
 
 /**
  * **AgentWebhookParams (Webhook 处理器参数)**
- * 
+ *
  * 传递给 Agent Webhook 处理函数的上下文参数集合。
  * @property req Node.js 原始请求对象
  * @property res Node.js 原始响应对象
@@ -123,32 +136,32 @@ function buildTextFilePreview(buffer: Buffer, maxChars: number): string | undefi
  * @property error 可选错误输出函数
  */
 export type AgentWebhookParams = {
-    req: IncomingMessage;
-    res: ServerResponse;
-    /**
-     * 上游已完成验签/解密时传入，避免重复协议处理。
-     * 仅用于 POST 消息回调流程。
-     */
-    verifiedPost?: {
-        timestamp: string;
-        nonce: string;
-        signature: string;
-        encrypted: string;
-        decrypted: string;
-        parsed: WecomAgentInboundMessage;
-    };
-    agent: ResolvedAgentAccount;
-    config: OpenClawConfig;
-    core: PluginRuntime;
-    log?: (msg: string) => void;
-    error?: (msg: string) => void;
-    auditSink?: (event: WecomRuntimeAuditEvent) => void;
-    touchTransportSession?: (patch: TransportSessionPatch) => void;
+  req: IncomingMessage;
+  res: ServerResponse;
+  /**
+   * 上游已完成验签/解密时传入，避免重复协议处理。
+   * 仅用于 POST 消息回调流程。
+   */
+  verifiedPost?: {
+    timestamp: string;
+    nonce: string;
+    signature: string;
+    encrypted: string;
+    decrypted: string;
+    parsed: WecomAgentInboundMessage;
+  };
+  agent: ResolvedAgentAccount;
+  config: OpenClawConfig;
+  core: PluginRuntime;
+  log?: (msg: string) => void;
+  error?: (msg: string) => void;
+  auditSink?: (event: WecomRuntimeAuditEvent) => void;
+  touchTransportSession?: (patch: TransportSessionPatch) => void;
 };
 
 export type AgentInboundProcessDecision = {
-    shouldProcess: boolean;
-    reason: string;
+  shouldProcess: boolean;
+  reason: string;
 };
 
 /**
@@ -158,213 +171,241 @@ export type AgentInboundProcessDecision = {
  * - 缺失发送者时默认丢弃，避免写入异常会话
  */
 export function shouldProcessAgentInboundMessage(params: {
-    msgType: string;
-    fromUser: string;
-    eventType?: string;
+  msgType: string;
+  fromUser: string;
+  chatId?: string;
+  eventType?: string;
 }): AgentInboundProcessDecision {
-    const msgType = String(params.msgType ?? "").trim().toLowerCase();
-    const fromUser = String(params.fromUser ?? "").trim();
-    const normalizedFromUser = fromUser.toLowerCase();
-    const eventType = String(params.eventType ?? "").trim().toLowerCase();
-
-    if (msgType === "event") {
-        const allowedEvents = [
-            "subscribe",
-            "enter_agent",
-            "batch_job_result",
-            // WeCom Doc events
-            "doc_create",
-            "doc_delete",
-            "doc_content_change",
-            "doc_member_change",
-            // WeCom Form events
-            "wedoc_collect_submit",
-            // SmartSheet events
-            "smartsheet_record_change",
-            "smartsheet_field_change",
-            "smartsheet_view_change"
-        ];
-        if (allowedEvents.includes(eventType) || eventType.startsWith("doc_") || eventType.startsWith("wedoc_") || eventType.startsWith("smartsheet_")) {
-            return {
-                shouldProcess: true,
-                reason: `allowed_event:${eventType}`,
-            };
-        }
-        return {
-            shouldProcess: false,
-            reason: `event:${eventType || "unknown"}`,
-        };
-    }
-
-    if (!fromUser) {
-        return {
-            shouldProcess: false,
-            reason: "missing_sender",
-        };
+  const msgType = String(params.msgType ?? "")
+    .trim()
+    .toLowerCase();
+  const fromUser = String(params.fromUser ?? "").trim();
+  const chatId = String(params.chatId ?? "").trim();
+  const normalizedFromUser = fromUser.toLowerCase();
+  const eventType = String(params.eventType ?? "")
+    .trim()
+    .toLowerCase();
+
+  if (msgType === "event") {
+    const allowedEvents = [
+      "subscribe",
+      "enter_agent",
+      "batch_job_result",
+      // WeCom Doc events
+      "doc_create",
+      "doc_delete",
+      "doc_content_change",
+      "doc_member_change",
+      // WeCom Form events
+      "wedoc_collect_submit",
+      // SmartSheet events
+      "smartsheet_record_change",
+      "smartsheet_field_change",
+      "smartsheet_view_change",
+    ];
+    if (
+      allowedEvents.includes(eventType) ||
+      eventType.startsWith("doc_") ||
+      eventType.startsWith("wedoc_") ||
+      eventType.startsWith("smartsheet_")
+    ) {
+      return {
+        shouldProcess: true,
+        reason: `allowed_event:${eventType}`,
+      };
     }
+    return {
+      shouldProcess: false,
+      reason: `event:${eventType || "unknown"}`,
+    };
+  }
 
-    if (normalizedFromUser === "sys") {
-        return {
-            shouldProcess: false,
-            reason: "system_sender",
-        };
+  if (!fromUser) {
+    if (chatId) {
+      return {
+        shouldProcess: true,
+        reason: "missing_sender_but_group_chat",
+      };
     }
+    return {
+      shouldProcess: false,
+      reason: "missing_sender",
+    };
+  }
 
+  if (normalizedFromUser === "sys") {
     return {
-        shouldProcess: true,
-        reason: "user_message",
+      shouldProcess: false,
+      reason: "system_sender",
     };
+  }
+
+  return {
+    shouldProcess: true,
+    reason: "user_message",
+  };
 }
 
 function normalizeAgentId(value: unknown): number | undefined {
-    if (typeof value === "number" && Number.isFinite(value)) return value;
-    const raw = String(value ?? "").trim();
-    if (!raw) return undefined;
-    const parsed = Number(raw);
-    return Number.isFinite(parsed) ? parsed : undefined;
+  if (typeof value === "number" && Number.isFinite(value)) return value;
+  const raw = String(value ?? "").trim();
+  if (!raw) return undefined;
+  const parsed = Number(raw);
+  return Number.isFinite(parsed) ? parsed : undefined;
 }
 
 /**
  * **resolveQueryParams (解析查询参数)**
- * 
+ *
  * 辅助函数：从 IncomingMessage 中解析 URL 查询字符串，用于获取签名、时间戳等参数。
  */
 function resolveQueryParams(req: IncomingMessage): URLSearchParams {
-    const url = new URL(req.url ?? "/", "http://localhost");
-    return url.searchParams;
+  const url = new URL(req.url ?? "/", "http://localhost");
+  return url.searchParams;
 }
 
 /**
  * 处理消息回调 (POST)
  */
 async function handleMessageCallback(params: AgentWebhookParams): Promise<boolean> {
-    const { req, res, verifiedPost, agent, config, core, log, error, auditSink } = params;
-
-    try {
-        if (!verifiedPost) {
-            error?.("[wecom-agent] inbound: missing preverified envelope");
-            res.statusCode = 400;
-            res.setHeader("Content-Type", "text/plain; charset=utf-8");
-            res.end(`invalid request - 缺少上游验签结果${ERROR_HELP}`);
-            return true;
-        }
-
-        log?.(`[wecom-agent] inbound: method=${req.method ?? "UNKNOWN"} remote=${req.socket?.remoteAddress ?? "unknown"}`);
-        const query = resolveQueryParams(req);
-        const querySignature = query.get("msg_signature") ?? "";
+  const { req, res, verifiedPost, agent, config, core, log, error, auditSink } = params;
+
+  try {
+    if (!verifiedPost) {
+      error?.("[wecom-agent] inbound: missing preverified envelope");
+      res.statusCode = 400;
+      res.setHeader("Content-Type", "text/plain; charset=utf-8");
+      res.end(`invalid request - 缺少上游验签结果${ERROR_HELP}`);
+      return true;
+    }
 
-        const encrypted = verifiedPost.encrypted;
-        const decrypted = verifiedPost.decrypted;
-        const msg = verifiedPost.parsed;
-        const timestamp = verifiedPost.timestamp;
-        const nonce = verifiedPost.nonce;
-        const signature = verifiedPost.signature || querySignature;
+    log?.(
+      `[wecom-agent] inbound: method=${req.method ?? "UNKNOWN"} remote=${req.socket?.remoteAddress ?? "unknown"}`,
+    );
+    const query = resolveQueryParams(req);
+    const querySignature = query.get("msg_signature") ?? "";
+
+    const encrypted = verifiedPost.encrypted;
+    const decrypted = verifiedPost.decrypted;
+    const msg = verifiedPost.parsed;
+    const timestamp = verifiedPost.timestamp;
+    const nonce = verifiedPost.nonce;
+    const signature = verifiedPost.signature || querySignature;
+    log?.(
+      `[wecom-agent] inbound: using preverified envelope timestamp=${timestamp ? "yes" : "no"} nonce=${nonce ? "yes" : "no"} msg_signature=${signature ? "yes" : "no"} encryptLen=${encrypted.length}`,
+    );
+
+    log?.(`[wecom-agent] inbound: decryptedBytes=${Buffer.byteLength(decrypted, "utf8")}`);
+
+    const inboundAgentId = normalizeAgentId(extractAgentId(msg));
+    if (
+      inboundAgentId !== undefined &&
+      typeof agent.agentId === "number" &&
+      Number.isFinite(agent.agentId) &&
+      inboundAgentId !== agent.agentId
+    ) {
+      error?.(
+        `[wecom-agent] inbound: agentId mismatch ignored expectedAgentId=${agent.agentId} actualAgentId=${String(extractAgentId(msg) ?? "")}`,
+      );
+    }
+    const msgType = extractMsgType(msg);
+    const fromUser = extractFromUser(msg);
+    const chatId = extractChatId(msg);
+    const msgId = extractMsgId(msg);
+    const eventType = String((msg as Record<string, unknown>).Event ?? "")
+      .trim()
+      .toLowerCase();
+
+    if (msgId) {
+      const ok = rememberAgentMsgId(msgId);
+      if (!ok) {
         log?.(
-            `[wecom-agent] inbound: using preverified envelope timestamp=${timestamp ? "yes" : "no"} nonce=${nonce ? "yes" : "no"} msg_signature=${signature ? "yes" : "no"} encryptLen=${encrypted.length}`,
+          `[wecom-agent] duplicate msgId=${msgId} from=${fromUser} chatId=${chatId ?? "N/A"} type=${msgType}; skipped`,
         );
-
-        log?.(`[wecom-agent] inbound: decryptedBytes=${Buffer.byteLength(decrypted, "utf8")}`);
-
-        const inboundAgentId = normalizeAgentId(extractAgentId(msg));
-        if (
-            inboundAgentId !== undefined &&
-            typeof agent.agentId === "number" &&
-            Number.isFinite(agent.agentId) &&
-            inboundAgentId !== agent.agentId
-        ) {
-            error?.(
-                `[wecom-agent] inbound: agentId mismatch ignored expectedAgentId=${agent.agentId} actualAgentId=${String(extractAgentId(msg) ?? "")}`,
-            );
-        }
-        const msgType = extractMsgType(msg);
-        const fromUser = extractFromUser(msg);
-        const chatId = extractChatId(msg);
-        const msgId = extractMsgId(msg);
-        const eventType = String((msg as Record<string, unknown>).Event ?? "").trim().toLowerCase();
-
-        if (msgId) {
-            const ok = rememberAgentMsgId(msgId);
-            if (!ok) {
-                log?.(`[wecom-agent] duplicate msgId=${msgId} from=${fromUser} chatId=${chatId ?? "N/A"} type=${msgType}; skipped`);
-                auditSink?.({
-                    transport: "agent-callback",
-                    category: "duplicate-reply",
-                    messageId: msgId,
-                    summary: `duplicate agent callback from=${fromUser} chatId=${chatId ?? "N/A"} type=${msgType}`,
-                    raw: {
-                        transport: "agent-callback",
-                        envelopeType: "xml",
-                        body: msg,
-                    },
-                });
-                res.statusCode = 200;
-                res.setHeader("Content-Type", "text/plain; charset=utf-8");
-                res.end("success");
-                return true;
-            }
-        }
-
-        // Agent 模式下 enter_agent / subscribe 不做任何处理，静默回 success
-        if (msgType === "event" && (eventType === "enter_agent" || eventType === "subscribe")) {
-            log?.(`[wecom-agent] ignoring ${eventType} from=${fromUser}; agent does not handle welcome events`);
-            res.statusCode = 200;
-            res.setHeader("Content-Type", "text/plain; charset=utf-8");
-            res.end("success");
-            return true;
-        }
-        const content = String(extractContent(msg) ?? "");
-
-        const preview = content.length > 100 ? `${content.slice(0, 100)}…` : content;
-        log?.(`[wecom-agent] ${msgType} from=${fromUser} chatId=${chatId ?? "N/A"} msgId=${msgId ?? "N/A"} content=${preview}`);
-
-        // 先返回 success (Agent 模式使用 API 发送回复，不用被动回复)
+        auditSink?.({
+          transport: "agent-callback",
+          category: "duplicate-reply",
+          messageId: msgId,
+          summary: `duplicate agent callback from=${fromUser} chatId=${chatId ?? "N/A"} type=${msgType}`,
+          raw: {
+            transport: "agent-callback",
+            envelopeType: "xml",
+            body: msg,
+          },
+        });
         res.statusCode = 200;
         res.setHeader("Content-Type", "text/plain; charset=utf-8");
         res.end("success");
+        return true;
+      }
+    }
 
-        const decision = shouldProcessAgentInboundMessage({
-            msgType,
-            fromUser,
-            eventType,
-        });
-        if (!decision.shouldProcess) {
-            log?.(
-                `[wecom-agent] skip processing: type=${msgType || "unknown"} event=${eventType || "N/A"} from=${fromUser || "N/A"} reason=${decision.reason}`,
-            );
-            return true;
-        }
+    // Agent 模式下 enter_agent / subscribe 不做任何处理，静默回 success
+    if (msgType === "event" && (eventType === "enter_agent" || eventType === "subscribe")) {
+      log?.(
+        `[wecom-agent] ignoring ${eventType} from=${fromUser}; agent does not handle welcome events`,
+      );
+      res.statusCode = 200;
+      res.setHeader("Content-Type", "text/plain; charset=utf-8");
+      res.end("success");
+      return true;
+    }
+    const content = String(extractContent(msg) ?? "");
+
+    const preview = content.length > 100 ? `${content.slice(0, 100)}…` : content;
+    log?.(
+      `[wecom-agent] ${msgType} from=${fromUser} chatId=${chatId ?? "N/A"} msgId=${msgId ?? "N/A"} content=${preview}`,
+    );
+
+    // 先返回 success (Agent 模式使用 API 发送回复，不用被动回复)
+    res.statusCode = 200;
+    res.setHeader("Content-Type", "text/plain; charset=utf-8");
+    res.end("success");
+
+    const decision = shouldProcessAgentInboundMessage({
+      msgType,
+      fromUser,
+      chatId,
+      eventType,
+    });
+    if (!decision.shouldProcess) {
+      log?.(
+        `[wecom-agent] skip processing: type=${msgType || "unknown"} event=${eventType || "N/A"} from=${fromUser || "N/A"} reason=${decision.reason}`,
+      );
+      return true;
+    }
 
-        // 异步处理消息
-        processAgentMessage({
-            agent,
-            config,
-            core,
-            fromUser,
-            chatId,
-            msgType,
-            content,
-            msg,
-            log,
-            error,
-            auditSink,
-            touchTransportSession: params.touchTransportSession,
-        }).catch((err) => {
-            error?.(`[wecom-agent] process failed: ${String(err)}`);
-        });
+    // 异步处理消息
+    processAgentMessage({
+      agent,
+      config,
+      core,
+      fromUser,
+      chatId,
+      msgType,
+      content,
+      msg,
+      log,
+      error,
+      auditSink,
+      touchTransportSession: params.touchTransportSession,
+    }).catch((err) => {
+      error?.(`[wecom-agent] process failed: ${String(err)}`);
+    });
 
-        return true;
-    } catch (err) {
-        error?.(`[wecom-agent] callback failed: ${String(err)}`);
-        res.statusCode = 400;
-        res.setHeader("Content-Type", "text/plain; charset=utf-8");
-        res.end(`error - 回调处理失败${ERROR_HELP}`);
-        return true;
-    }
+    return true;
+  } catch (err) {
+    error?.(`[wecom-agent] callback failed: ${String(err)}`);
+    res.statusCode = 400;
+    res.setHeader("Content-Type", "text/plain; charset=utf-8");
+    res.end(`error - 回调处理失败${ERROR_HELP}`);
+    return true;
+  }
 }
 
 /**
  * **processAgentMessage (处理 Agent 消息)**
- * 
+ *
  * 异步处理解密后的消息内容，并触发 OpenClaw Agent。
  * 流程：
  * 1. 路由解析：根据 userid或群ID 确定 Agent 路由。
@@ -374,279 +415,321 @@ async function handleMessageCallback(params: AgentWebhookParams): Promise<boolea
  * 5. 调度回复：将 Agent 的响应通过 `api-client` 发送回企业微信。
  */
 async function processAgentMessage(params: {
-    agent: ResolvedAgentAccount;
-    config: OpenClawConfig;
-    core: PluginRuntime;
-    fromUser: string;
-    chatId?: string;
-    msgType: string;
-    content: string;
-    msg: WecomAgentInboundMessage;
-    log?: (msg: string) => void;
-    error?: (msg: string) => void;
-    auditSink?: (event: WecomRuntimeAuditEvent) => void;
-    touchTransportSession?: (patch: TransportSessionPatch) => void;
+  agent: ResolvedAgentAccount;
+  config: OpenClawConfig;
+  core: PluginRuntime;
+  fromUser: string;
+  chatId?: string;
+  msgType: string;
+  content: string;
+  msg: WecomAgentInboundMessage;
+  log?: (msg: string) => void;
+  error?: (msg: string) => void;
+  auditSink?: (event: WecomRuntimeAuditEvent) => void;
+  touchTransportSession?: (patch: TransportSessionPatch) => void;
 }): Promise<void> {
-    const { agent, config, core, fromUser, chatId, content, msg, msgType, log, error, auditSink, touchTransportSession } = params;
-
-    const isGroup = Boolean(chatId);
-    const peerId = isGroup ? chatId! : fromUser;
-    const eventType = String(msg.Event ?? "").trim().toLowerCase();
-
-    const resolveInboundKind = (): WecomInboundKind => {
-        if (msgType === "event") {
-            if (eventType === "subscribe" || eventType === "enter_agent") return "welcome";
-            return "event";
-        }
-        if (msgType === "image") return "image";
-        if (msgType === "voice") return "voice";
-        if (msgType === "video") return "video";
-        if (msgType === "file") return "file";
-        if (msgType === "location") return "location";
-        if (msgType === "link") return "link";
-        return "text";
-    };
-
-    const inboundKind = resolveInboundKind();
-    const resolveEventText = (): string => {
-        if (inboundKind === "welcome" && agent.config.welcomeText) {
-            return agent.config.welcomeText;
-        }
-        if (msgType === "event") {
-            return `[event:${eventType || "unknown"}]`;
-        }
-        return content;
-    };
-    
-    // BUG FIX: 真正调用 resolveEventText() 获取欢迎语或事件描述
-    const resolvedContent = resolveEventText();
-    let finalContent = resolvedContent;
-
-    const mediaMaxBytes = resolveWecomMediaMaxBytes(config);
-
-    // 处理媒体文件
-    const attachments: NonNullable<UnifiedInboundEvent["attachments"]> = [];
-    let mediaPath: string | undefined;
-    let mediaType: string | undefined;
-
-    if (["image", "voice", "video", "file"].includes(msgType)) {
-        const mediaId = extractMediaId(msg);
-        if (mediaId) {
-            try {
-                log?.(`[wecom-agent] downloading media: ${mediaId} (${msgType})`);
-                const { buffer, contentType, filename: headerFileName } = await downloadAgentApiMedia({ agent, mediaId, maxBytes: mediaMaxBytes });
-                const xmlFileName = extractFileName(msg);
-                const originalFileName = (xmlFileName || headerFileName || `${mediaId}.bin`).trim();
-                const heuristic = analyzeTextHeuristic(buffer);
-
-                // 推断文件名后缀
-                const extMap: Record<string, string> = {
-                    "image/jpeg": "jpg", "image/png": "png", "image/gif": "gif",
-                    "audio/amr": "amr", "audio/speex": "speex", "video/mp4": "mp4",
-                };
-                const textPreview = msgType === "file" ? buildTextFilePreview(buffer, 12_000) : undefined;
-                const looksText = Boolean(textPreview);
-                const originalExt = path.extname(originalFileName).toLowerCase();
-                const normalizedContentType =
-                    looksText && originalExt === ".md" ? "text/markdown" :
-                        looksText && (!contentType || contentType === "application/octet-stream")
-                            ? "text/plain; charset=utf-8"
-                            : contentType;
-
-                const ext = extMap[normalizedContentType] || (looksText ? "txt" : "bin");
-                const filename = `${mediaId}.${ext}`;
+  const {
+    agent,
+    config,
+    core,
+    fromUser,
+    chatId,
+    content,
+    msg,
+    msgType,
+    log,
+    error,
+    auditSink,
+    touchTransportSession,
+  } = params;
+
+  const isGroup = Boolean(chatId);
+  const peerId = isGroup ? chatId! : fromUser;
+  const replyTarget = isGroup
+    ? ({ toUser: undefined, chatId: peerId } as const)
+    : ({ toUser: fromUser, chatId: undefined } as const);
+  const eventType = String(msg.Event ?? "")
+    .trim()
+    .toLowerCase();
+
+  const resolveInboundKind = (): WecomInboundKind => {
+    if (msgType === "event") {
+      if (eventType === "subscribe" || eventType === "enter_agent") return "welcome";
+      return "event";
+    }
+    if (msgType === "image") return "image";
+    if (msgType === "voice") return "voice";
+    if (msgType === "video") return "video";
+    if (msgType === "file") return "file";
+    if (msgType === "location") return "location";
+    if (msgType === "link") return "link";
+    return "text";
+  };
+
+  const inboundKind = resolveInboundKind();
+  const resolveEventText = (): string => {
+    if (inboundKind === "welcome" && agent.config.welcomeText) {
+      return agent.config.welcomeText;
+    }
+    if (msgType === "event") {
+      return `[event:${eventType || "unknown"}]`;
+    }
+    return content;
+  };
+
+  // BUG FIX: 真正调用 resolveEventText() 获取欢迎语或事件描述
+  const resolvedContent = resolveEventText();
+  let finalContent = resolvedContent;
+
+  const mediaMaxBytes = resolveWecomMediaMaxBytes(config);
+
+  // 处理媒体文件
+  const attachments: NonNullable<UnifiedInboundEvent["attachments"]> = [];
+  let mediaPath: string | undefined;
+  let mediaType: string | undefined;
+
+  if (["image", "voice", "video", "file"].includes(msgType)) {
+    const mediaId = extractMediaId(msg);
+    if (mediaId) {
+      try {
+        log?.(`[wecom-agent] downloading media: ${mediaId} (${msgType})`);
+        const {
+          buffer,
+          contentType,
+          filename: headerFileName,
+        } = await downloadAgentApiMedia({ agent, mediaId, maxBytes: mediaMaxBytes });
+        const xmlFileName = extractFileName(msg);
+        const originalFileName = (xmlFileName || headerFileName || `${mediaId}.bin`).trim();
+        const heuristic = analyzeTextHeuristic(buffer);
+
+        // 推断文件名后缀
+        const extMap: Record<string, string> = {
+          "image/jpeg": "jpg",
+          "image/png": "png",
+          "image/gif": "gif",
+          "audio/amr": "amr",
+          "audio/speex": "speex",
+          "video/mp4": "mp4",
+        };
+        const textPreview = msgType === "file" ? buildTextFilePreview(buffer, 12_000) : undefined;
+        const looksText = Boolean(textPreview);
+        const originalExt = path.extname(originalFileName).toLowerCase();
+        const normalizedContentType =
+          looksText && originalExt === ".md"
+            ? "text/markdown"
+            : looksText && (!contentType || contentType === "application/octet-stream")
+              ? "text/plain; charset=utf-8"
+              : contentType;
+
+        const ext = extMap[normalizedContentType] || (looksText ? "txt" : "bin");
+        const filename = `${mediaId}.${ext}`;
 
-                log?.(
-                    `[wecom-agent] file meta: msgType=${msgType} mediaId=${mediaId} size=${buffer.length} maxBytes=${mediaMaxBytes} ` +
-                    `contentType=${contentType} normalizedContentType=${normalizedContentType} originalFileName=${originalFileName} ` +
-                    `xmlFileName=${xmlFileName ?? "N/A"} headerFileName=${headerFileName ?? "N/A"} ` +
-                    `textHeuristic(sample=${heuristic.sampleSize}, bad=${heuristic.badCount}, ratio=${heuristic.badRatio.toFixed(4)}) ` +
-                    `headHex="${previewHex(buffer)}"`,
-                );
+        log?.(
+          `[wecom-agent] file meta: msgType=${msgType} mediaId=${mediaId} size=${buffer.length} maxBytes=${mediaMaxBytes} ` +
+            `contentType=${contentType} normalizedContentType=${normalizedContentType} originalFileName=${originalFileName} ` +
+            `xmlFileName=${xmlFileName ?? "N/A"} headerFileName=${headerFileName ?? "N/A"} ` +
+            `textHeuristic(sample=${heuristic.sampleSize}, bad=${heuristic.badCount}, ratio=${heuristic.badRatio.toFixed(4)}) ` +
+            `headHex="${previewHex(buffer)}"`,
+        );
 
-                // 使用 Core SDK 保存媒体文件
-                const saved = await core.channel.media.saveMediaBuffer(
-                    buffer,
-                    normalizedContentType,
-                    "inbound", // context/scope
-                    mediaMaxBytes, // limit
-                    originalFileName
-                );
+        // 使用 Core SDK 保存媒体文件
+        const saved = await core.channel.media.saveMediaBuffer(
+          buffer,
+          normalizedContentType,
+          "inbound", // context/scope
+          mediaMaxBytes, // limit
+          originalFileName,
+        );
 
-                log?.(`[wecom-agent] media saved to: ${saved.path}`);
-                mediaPath = saved.path;
-                mediaType = normalizedContentType;
+        log?.(`[wecom-agent] media saved to: ${saved.path}`);
+        mediaPath = saved.path;
+        mediaType = normalizedContentType;
 
-                // 构建附件
-                attachments.push({
-                    name: originalFileName,
-                    contentType: normalizedContentType,
-                    remoteUrl: pathToFileURL(saved.path).href, // 使用跨平台安全的文件 URL
-                });
+        // 构建附件
+        attachments.push({
+          name: originalFileName,
+          contentType: normalizedContentType,
+          remoteUrl: pathToFileURL(saved.path).href, // 使用跨平台安全的文件 URL
+        });
 
-                // 更新文本提示
-                if (textPreview) {
-                    finalContent = [
-                        content,
-                        "",
-                        "文件内容预览：",
-                        "```",
-                        textPreview,
-                        "```",
-                        `(已下载 ${buffer.length} 字节)`,
-                    ].join("\n");
-                } else {
-                    if (msgType === "file") {
-                        finalContent = [
-                            content,
-                            "",
-                            `已收到文件：${originalFileName}`,
-                            `文件类型：${normalizedContentType || contentType || "未知"}`,
-                            "提示：当前仅对文本/Markdown/JSON/CSV/HTML/PDF（可选）做内容抽取；其他二进制格式请转为 PDF 或复制文本内容。",
-                            `(已下载 ${buffer.length} 字节)`,
-                        ].join("\n");
-                    } else {
-                        finalContent = `${content} (已下载 ${buffer.length} 字节)`;
-                    }
-                }
-                log?.(`[wecom-agent] file preview: enabled=${looksText} finalContentLen=${finalContent.length} attachments=${attachments.length}`);
-            } catch (err) {
-                error?.(`[wecom-agent] media processing failed: ${String(err)}`);
-                auditSink?.({
-                    transport: "agent-callback",
-                    category: "runtime-error",
-                    messageId: extractMsgId(msg) ?? undefined,
-                    summary: `agent media processing failed mediaId=${mediaId}`,
-                    raw: {
-                        transport: "agent-callback",
-                        envelopeType: "xml",
-                        body: msg,
-                    },
-                    error: err instanceof Error ? err.message : String(err),
-                });
-                finalContent = [
-                    content,
-                    "",
-                    `媒体处理失败：${String(err)}`,
-                    `提示：可在 OpenClaw 配置中提高 channels.wecom.media.maxBytes（当前=${mediaMaxBytes}）`,
-                    `例如：openclaw config set channels.wecom.media.maxBytes ${50 * 1024 * 1024}`,
-                ].join("\n");
-            }
+        // 更新文本提示
+        if (textPreview) {
+          finalContent = [
+            content,
+            "",
+            "文件内容预览：",
+            "```",
+            textPreview,
+            "```",
+            `(已下载 ${buffer.length} 字节)`,
+          ].join("\n");
         } else {
-            const keys = Object.keys((msg as unknown as Record<string, unknown>) ?? {}).slice(0, 50).join(",");
-            error?.(`[wecom-agent] mediaId not found for ${msgType}; keys=${keys}`);
+          if (msgType === "file") {
+            finalContent = [
+              content,
+              "",
+              `已收到文件：${originalFileName}`,
+              `文件类型：${normalizedContentType || contentType || "未知"}`,
+              "提示：当前仅对文本/Markdown/JSON/CSV/HTML/PDF（可选）做内容抽取；其他二进制格式请转为 PDF 或复制文本内容。",
+              `(已下载 ${buffer.length} 字节)`,
+            ].join("\n");
+          } else {
+            finalContent = `${content} (已下载 ${buffer.length} 字节)`;
+          }
         }
-    }
-
-    // 解析路由
-    const route = core.channel.routing.resolveAgentRoute({
-        cfg: config,
-        channel: "wecom",
-        accountId: agent.accountId,
-        peer: { kind: isGroup ? "group" : "direct", id: peerId },
-    });
-
-    // ===== 动态 Agent 路由注入 =====
-    const useDynamicAgent = shouldUseDynamicAgent({
-        chatType: isGroup ? "group" : "dm",
-        senderId: fromUser,
-        config,
-    });
-
-    if (shouldRejectWecomDefaultRoute({ cfg: config, matchedBy: route.matchedBy, useDynamicAgent })) {
-        const prompt =
-            `当前账号（${agent.accountId}）未绑定 OpenClaw Agent，已拒绝回退到默认主智能体。` +
-            `请在 bindings 中添加：{"agentId":"你的Agent","match":{"channel":"wecom","accountId":"${agent.accountId}"}}`;
-        error?.(
-            `[wecom-agent] routing guard: blocked default fallback accountId=${agent.accountId} matchedBy=${route.matchedBy} from=${fromUser}`,
+        log?.(
+          `[wecom-agent] file preview: enabled=${looksText} finalContentLen=${finalContent.length} attachments=${attachments.length}`,
         );
-        try {
-            await sendAgentApiText({ agent, toUser: fromUser, chatId: undefined, text: prompt });
-            touchTransportSession?.({ lastOutboundAt: Date.now(), running: true });
-            log?.(`[wecom-agent] routing guard prompt delivered to ${fromUser}`);
-        } catch (err: unknown) {
-            error?.(`[wecom-agent] routing guard prompt failed: ${String(err)}`);
-            auditSink?.({
-                transport: "agent-callback",
-                category: "fallback-delivery-failed",
-                summary: `routing guard prompt failed user=${fromUser}`,
-                raw: {
-                    transport: "agent-callback",
-                    envelopeType: "xml",
-                    body: msg,
-                },
-                error: err instanceof Error ? err.message : String(err),
-            });
-        }
-        return;
+      } catch (err) {
+        error?.(`[wecom-agent] media processing failed: ${String(err)}`);
+        auditSink?.({
+          transport: "agent-callback",
+          category: "runtime-error",
+          messageId: extractMsgId(msg) ?? undefined,
+          summary: `agent media processing failed mediaId=${mediaId}`,
+          raw: {
+            transport: "agent-callback",
+            envelopeType: "xml",
+            body: msg,
+          },
+          error: err instanceof Error ? err.message : String(err),
+        });
+        finalContent = [
+          content,
+          "",
+          `媒体处理失败：${String(err)}`,
+          `提示：可在 OpenClaw 配置中提高 channels.wecom.media.maxBytes（当前=${mediaMaxBytes}）`,
+          `例如：openclaw config set channels.wecom.media.maxBytes ${50 * 1024 * 1024}`,
+        ].join("\n");
+      }
+    } else {
+      const keys = Object.keys((msg as unknown as Record<string, unknown>) ?? {})
+        .slice(0, 50)
+        .join(",");
+      error?.(`[wecom-agent] mediaId not found for ${msgType}; keys=${keys}`);
     }
-
-    if (useDynamicAgent) {
-        const targetAgentId = generateAgentId(
-            isGroup ? "group" : "dm",
-            peerId,
-            agent.accountId,
-        );
-        route.agentId = targetAgentId;
-        route.sessionKey = `agent:${targetAgentId}:wecom:${agent.accountId}:${isGroup ? "group" : "dm"}:${peerId}`;
-        // 异步添加到 agents.list（不阻塞）
-        ensureDynamicAgentListed(targetAgentId, core).catch(() => { });
-        log?.(`[wecom-agent] dynamic agent routing: ${targetAgentId}, sessionKey=${route.sessionKey}`);
+  }
+
+  // 解析路由
+  const route = core.channel.routing.resolveAgentRoute({
+    cfg: config,
+    channel: "wecom",
+    accountId: agent.accountId,
+    peer: { kind: isGroup ? "group" : "direct", id: peerId },
+  });
+
+  // ===== 动态 Agent 路由注入 =====
+  const useDynamicAgent = shouldUseDynamicAgent({
+    chatType: isGroup ? "group" : "dm",
+    senderId: fromUser,
+    config,
+  });
+
+  if (shouldRejectWecomDefaultRoute({ cfg: config, matchedBy: route.matchedBy, useDynamicAgent })) {
+    const prompt =
+      `当前账号（${agent.accountId}）未绑定 OpenClaw Agent，已拒绝回退到默认主智能体。` +
+      `请在 bindings 中添加：{"agentId":"你的Agent","match":{"channel":"wecom","accountId":"${agent.accountId}"}}`;
+    error?.(
+      `[wecom-agent] routing guard: blocked default fallback accountId=${agent.accountId} matchedBy=${route.matchedBy} from=${fromUser}`,
+    );
+    try {
+      await sendAgentApiText({ agent, ...replyTarget, text: prompt });
+      touchTransportSession?.({ lastOutboundAt: Date.now(), running: true });
+      log?.(`[wecom-agent] routing guard prompt delivered to ${fromUser}`);
+    } catch (err: unknown) {
+      error?.(`[wecom-agent] routing guard prompt failed: ${String(err)}`);
+      auditSink?.({
+        transport: "agent-callback",
+        category: "fallback-delivery-failed",
+        summary: `routing guard prompt failed user=${fromUser}`,
+        raw: {
+          transport: "agent-callback",
+          envelopeType: "xml",
+          body: msg,
+        },
+        error: err instanceof Error ? err.message : String(err),
+      });
     }
-    // ===== 动态 Agent 路由注入结束 =====
-
-    // 构建上下文
-    const fromLabel = isGroup ? `group:${peerId}` : `user:${fromUser}`;
-    const storePath = core.channel.session.resolveStorePath(config.session?.store, {
-        agentId: route.agentId,
-    });
-    const envelopeOptions = core.channel.reply.resolveEnvelopeFormatOptions(config);
-    const previousTimestamp = core.channel.session.readSessionUpdatedAt({
-        storePath,
-        sessionKey: route.sessionKey,
-    });
-    const body = core.channel.reply.formatAgentEnvelope({
-        channel: "WeCom",
-        from: fromLabel,
-        previousTimestamp,
-        envelope: envelopeOptions,
-        body: finalContent,
-    });
-
-    const authz = await resolveWecomCommandAuthorization({
-        core,
-        cfg: config,
-        // Agent 门禁应读取 channels.wecom.agent.dm（即 agent.config.dm），而不是 channels.wecom.dm（不存在）
-        accountConfig: agent.config,
-        rawBody: finalContent,
-        senderUserId: fromUser,
+    return;
+  }
+
+  if (useDynamicAgent) {
+    const targetAgentId = generateAgentId(isGroup ? "group" : "dm", peerId, agent.accountId);
+    route.agentId = targetAgentId;
+    route.sessionKey = `agent:${targetAgentId}:wecom:${agent.accountId}:${isGroup ? "group" : "dm"}:${peerId}`;
+    // 异步添加到 agents.list（不阻塞）
+    ensureDynamicAgentListed(targetAgentId, core).catch(() => {});
+    log?.(`[wecom-agent] dynamic agent routing: ${targetAgentId}, sessionKey=${route.sessionKey}`);
+  }
+  // ===== 动态 Agent 路由注入结束 =====
+
+  registerWecomSourceSnapshot({
+    accountId: agent.accountId,
+    source: "agent-callback",
+    messageId: extractMsgId(msg) ?? undefined,
+    sessionKey: route.sessionKey,
+  });
+
+  // 构建上下文
+  const fromLabel = isGroup ? `group:${peerId}` : `user:${fromUser}`;
+  const storePath = core.channel.session.resolveStorePath(config.session?.store, {
+    agentId: route.agentId,
+  });
+  const envelopeOptions = core.channel.reply.resolveEnvelopeFormatOptions(config);
+  const previousTimestamp = core.channel.session.readSessionUpdatedAt({
+    storePath,
+    sessionKey: route.sessionKey,
+  });
+  const body = core.channel.reply.formatAgentEnvelope({
+    channel: "WeCom",
+    from: fromLabel,
+    previousTimestamp,
+    envelope: envelopeOptions,
+    body: finalContent,
+  });
+
+  const authz = await resolveWecomCommandAuthorization({
+    core,
+    cfg: config,
+    // Agent 门禁应读取 channels.wecom.agent.dm（即 agent.config.dm），而不是 channels.wecom.dm（不存在）
+    accountConfig: agent.config,
+    rawBody: finalContent,
+    senderUserId: fromUser,
+  });
+  log?.(
+    `[wecom-agent] authz: dmPolicy=${authz.dmPolicy} shouldCompute=${authz.shouldComputeAuth} sender=${fromUser.toLowerCase()} senderAllowed=${authz.senderAllowed} authorizerConfigured=${authz.authorizerConfigured} commandAuthorized=${String(authz.commandAuthorized)}`,
+  );
+
+  // 命令门禁：未授权时必须明确回复（Agent 侧用私信提示）
+  if (authz.shouldComputeAuth && authz.commandAuthorized !== true) {
+    const prompt = buildWecomUnauthorizedCommandPrompt({
+      senderUserId: fromUser,
+      dmPolicy: authz.dmPolicy,
+      scope: "agent",
     });
-    log?.(`[wecom-agent] authz: dmPolicy=${authz.dmPolicy} shouldCompute=${authz.shouldComputeAuth} sender=${fromUser.toLowerCase()} senderAllowed=${authz.senderAllowed} authorizerConfigured=${authz.authorizerConfigured} commandAuthorized=${String(authz.commandAuthorized)}`);
-
-    // 命令门禁：未授权时必须明确回复（Agent 侧用私信提示）
-    if (authz.shouldComputeAuth && authz.commandAuthorized !== true) {
-        const prompt = buildWecomUnauthorizedCommandPrompt({ senderUserId: fromUser, dmPolicy: authz.dmPolicy, scope: "agent" });
-        try {
-            await sendAgentApiText({ agent, toUser: fromUser, chatId: undefined, text: prompt });
-            touchTransportSession?.({ lastOutboundAt: Date.now(), running: true });
-            log?.(`[wecom-agent] unauthorized command: replied via DM to ${fromUser}`);
-        } catch (err: unknown) {
-            error?.(`[wecom-agent] unauthorized command reply failed: ${String(err)}`);
-            auditSink?.({
-                transport: "agent-callback",
-                category: "fallback-delivery-failed",
-                summary: `unauthorized prompt failed user=${fromUser}`,
-                raw: {
-                    transport: "agent-callback",
-                    envelopeType: "xml",
-                    body: msg,
-                },
-                error: err instanceof Error ? err.message : String(err),
-            });
-        }
-        return;
+    try {
+      await sendAgentApiText({ agent, ...replyTarget, text: prompt });
+      touchTransportSession?.({ lastOutboundAt: Date.now(), running: true });
+      log?.(
+        `[wecom-agent] unauthorized command: replied to ${isGroup ? `chat:${peerId}` : fromUser}`,
+      );
+    } catch (err: unknown) {
+      error?.(`[wecom-agent] unauthorized command reply failed: ${String(err)}`);
+      auditSink?.({
+        transport: "agent-callback",
+        category: "fallback-delivery-failed",
+        summary: `unauthorized prompt failed user=${fromUser}`,
+        raw: {
+          transport: "agent-callback",
+          envelopeType: "xml",
+          body: msg,
+        },
+        error: err instanceof Error ? err.message : String(err),
+      });
     }
-const ctxPayload = core.channel.reply.finalizeInboundContext({
+    return;
+  }
+  const ctxPayload = core.channel.reply.finalizeInboundContext({
     Body: body,
     RawBody: finalContent,
     CommandBody: finalContent,
@@ -670,136 +753,142 @@ const ctxPayload = core.channel.reply.finalizeInboundContext({
     MediaPath: mediaPath,
     MediaType: mediaType,
     MediaUrl: mediaPath,
-});
-
-    // 记录会话
-    await core.channel.session.recordInboundSession({
-        storePath,
-        sessionKey: ctxPayload.SessionKey ?? route.sessionKey,
-        ctx: ctxPayload,
-        onRecordError: (err: unknown) => {
-            error?.(`[wecom-agent] session record failed: ${String(err)}`);
-        },
-    });
-
-    // 5秒无响应自动回复进度提示
-    let hasResponseSent = false;
-    const processingTimer = setTimeout(async () => {
-        if (hasResponseSent) return;
-        try {
-            await sendAgentApiText({ 
-                agent, 
-                toUser: fromUser, 
-                chatId: undefined, 
-                text: "正在处理中，请稍候..." 
-            });
-            log?.(`[wecom-agent] sent processing notification to ${fromUser}`);
-        } catch (err) {
-            error?.(`[wecom-agent] failed to send processing notification: ${String(err)}`);
-        }
-    }, 5000);
+  });
+
+  // 记录会话
+  await core.channel.session.recordInboundSession({
+    storePath,
+    sessionKey: ctxPayload.SessionKey ?? route.sessionKey,
+    ctx: ctxPayload,
+    onRecordError: (err: unknown) => {
+      error?.(`[wecom-agent] session record failed: ${String(err)}`);
+    },
+  });
+
+  // 5秒无响应自动回复进度提示
+  let hasResponseSent = false;
+  const processingTimer = setTimeout(async () => {
+    if (hasResponseSent) return;
+    try {
+      await sendAgentApiText({
+        agent,
+        ...replyTarget,
+        text: "正在处理中，请稍候...",
+      });
+      log?.(
+        `[wecom-agent] sent processing notification to ${isGroup ? `chat:${peerId}` : fromUser}`,
+      );
+    } catch (err) {
+      error?.(`[wecom-agent] failed to send processing notification: ${String(err)}`);
+    }
+  }, 5000);
+
+  // 发送队列锁：确保所有 deliver 调用（以及内部的分片发送）严格串行执行
+  let messageSendQueue = Promise.resolve();
+
+  try {
+    // 调度回复
+    await core.channel.reply.dispatchReplyWithBufferedBlockDispatcher({
+      ctx: ctxPayload,
+      cfg: config,
+      replyOptions: {
+        disableBlockStreaming: false,
+      },
+      dispatcherOptions: {
+        deliver: async (payload: { text?: string }, info: { kind: string }) => {
+          const text = payload.text ?? "";
+          // 忽略空文本消息
+          if (!text || !text.trim()) {
+            return;
+          }
+
+          // 标记已有回复，清除/失效定时器
+          hasResponseSent = true;
+          clearTimeout(processingTimer);
+
+          // 将本次发送任务加入队列
+          // 即使 deliver 被并发调用，队列中的任务也会按入队顺序串行执行
+          const currentTask = async () => {
+            const MAX_CHUNK_SIZE = 600;
+            // 确保分片顺序发送
+            for (let i = 0; i < text.length; i += MAX_CHUNK_SIZE) {
+              const chunk = text.slice(i, i + MAX_CHUNK_SIZE);
+
+              try {
+                await sendAgentApiText({ agent, ...replyTarget, text: chunk });
+                touchTransportSession?.({ lastOutboundAt: Date.now(), running: true });
+                log?.(
+                  `[wecom-agent] reply chunk delivered (${info.kind}) to ${isGroup ? `chat:${peerId}` : fromUser}, len=${chunk.length}`,
+                );
 
-    // 发送队列锁：确保所有 deliver 调用（以及内部的分片发送）严格串行执行
-    let messageSendQueue = Promise.resolve();
+                // 强制延时：确保企业微信有足够时间处理顺序（优化：200ms → 50ms）
+                if (i + MAX_CHUNK_SIZE < text.length) {
+                  await new Promise((resolve) => setTimeout(resolve, 50));
+                }
+              } catch (err: unknown) {
+                const message =
+                  err instanceof Error
+                    ? `${err.message}${err.cause ? ` (cause: ${String(err.cause)})` : ""}`
+                    : String(err);
+                error?.(`[wecom-agent] reply failed: ${message}`);
+                auditSink?.({
+                  transport: "agent-callback",
+                  category: "fallback-delivery-failed",
+                  summary: `agent callback reply failed user=${fromUser} kind=${info.kind}`,
+                  raw: {
+                    transport: "agent-callback",
+                    envelopeType: "xml",
+                    body: msg,
+                  },
+                  error: message,
+                });
+              }
+            }
 
-    try {
-        // 调度回复
-        await core.channel.reply.dispatchReplyWithBufferedBlockDispatcher({
-            ctx: ctxPayload,
-            cfg: config,
-            replyOptions: {
-                disableBlockStreaming: false,
-            },
-            dispatcherOptions: {
-                deliver: async (payload: { text?: string }, info: { kind: string }) => {
-                    const text = payload.text ?? "";
-                    // 忽略空文本消息
-                    if (!text || !text.trim()) {
-                        return;
-                    }
-
-                    // 标记已有回复，清除/失效定时器
-                    hasResponseSent = true;
-                    clearTimeout(processingTimer);
-
-                    // 将本次发送任务加入队列
-                    // 即使 deliver 被并发调用，队列中的任务也会按入队顺序串行执行
-                    const currentTask = async () => {
-                        const MAX_CHUNK_SIZE = 600;
-                        // 确保分片顺序发送
-                        for (let i = 0; i < text.length; i += MAX_CHUNK_SIZE) {
-                            const chunk = text.slice(i, i + MAX_CHUNK_SIZE);
-                            
-                            try {
-                                await sendAgentApiText({ agent, toUser: fromUser, chatId: undefined, text: chunk });
-                                touchTransportSession?.({ lastOutboundAt: Date.now(), running: true });
-                                log?.(`[wecom-agent] reply chunk delivered (${info.kind}) to ${fromUser}, len=${chunk.length}`);
-                                
-                                // 强制延时：确保企业微信有足够时间处理顺序（优化：200ms → 50ms）
-                                if (i + MAX_CHUNK_SIZE < text.length) {
-                                    await new Promise(resolve => setTimeout(resolve, 50));
-                                }
-                            } catch (err: unknown) {
-                                const message = err instanceof Error ? `${err.message}${err.cause ? ` (cause: ${String(err.cause)})` : ""}` : String(err);
-                                error?.(`[wecom-agent] reply failed: ${message}`);
-                                auditSink?.({
-                                    transport: "agent-callback",
-                                    category: "fallback-delivery-failed",
-                                    summary: `agent callback reply failed user=${fromUser} kind=${info.kind}`,
-                                    raw: {
-                                        transport: "agent-callback",
-                                        envelopeType: "xml",
-                                        body: msg,
-                                    },
-                                    error: message,
-                                });
-                            }
-                        }
-                        
-                        // 不同 Block 之间也增加一点间隔（优化：200ms → 50ms）
-                        if (info.kind !== "final") {
-                            await new Promise(resolve => setTimeout(resolve, 50));
-                        }
-                    };
-
-                    // 更新队列链
-                    // 使用 then 链接，并捕获前一个任务可能的错误，确保当前任务总能执行
-                    messageSendQueue = messageSendQueue
-                        .then(() => currentTask())
-                        .catch((err) => {
-                            error?.(`[wecom-agent] previous send task failed: ${String(err)}`);
-                            // 前一个失败不应阻止当前任务，继续尝试执行当前任务
-                            return currentTask();
-                        });
-
-                    // 等待当前任务完成（保持背压，虽然对于 http callback 模式这可能只是延迟了整体结束时间）
-                    await messageSendQueue;
-                },
-                onError: (err: unknown, info: { kind: string }) => {
-                    clearTimeout(processingTimer);
-                    error?.(`[wecom-agent] ${info.kind} reply error: ${String(err)}`);
-                },
+            // 不同 Block 之间也增加一点间隔（优化：200ms → 50ms）
+            if (info.kind !== "final") {
+              await new Promise((resolve) => setTimeout(resolve, 50));
             }
-        });
-    } finally {
-        clearTimeout(processingTimer);
-        // 确保所有排队的消息都发完了才退出（虽然对于 HTTP 响应来说，res.end 早就调用了）
-        await messageSendQueue;
-    }
+          };
+
+          // 更新队列链
+          // 使用 then 链接，并捕获前一个任务可能的错误，确保当前任务总能执行
+          messageSendQueue = messageSendQueue
+            .then(() => currentTask())
+            .catch((err) => {
+              error?.(`[wecom-agent] previous send task failed: ${String(err)}`);
+              // 前一个失败不应阻止当前任务，继续尝试执行当前任务
+              return currentTask();
+            });
+
+          // 等待当前任务完成（保持背压，虽然对于 http callback 模式这可能只是延迟了整体结束时间）
+          await messageSendQueue;
+        },
+        onError: (err: unknown, info: { kind: string }) => {
+          clearTimeout(processingTimer);
+          error?.(`[wecom-agent] ${info.kind} reply error: ${String(err)}`);
+        },
+      },
+    });
+  } finally {
+    clearTimeout(processingTimer);
+    // 确保所有排队的消息都发完了才退出（虽然对于 HTTP 响应来说，res.end 早就调用了）
+    await messageSendQueue;
+  }
 }
 
 /**
  * **handleAgentWebhook (Agent Webhook 入口)**
- * 
+ *
  * 统一处理 Agent 模式的 POST 消息回调请求。
  * URL 验证与验签/解密由 monitor 层统一处理后再调用本函数。
  */
 export async function handleAgentWebhook(params: AgentWebhookParams): Promise<boolean> {
-    const { req } = params;
+  const { req } = params;
 
-    if (req.method === "POST") {
-        return handleMessageCallback(params);
-    }
+  if (req.method === "POST") {
+    return handleMessageCallback(params);
+  }
 
-    return false;
+  return false;
 }