@imweapp/openclaw-imwe 2026.4.12-alpha.1

package/src/monitor.ts

@@ -0,0 +1,838 @@
+/**
+ * monitor.ts — 事件箱轮询消息监听器
+ *
+ * 职责（仅轮询，不负责初始化）：
+ *   - 接收 startAccount 传入的 botInfo（已通过 getMe 获取）
+ *   - 通过短轮询定期向平台拉取新消息（PbBoxPullReq 事件箱模式）
+ *   - 将收到的消息通过 channelRuntime.reply 交给 OpenClaw core 处理
+ *   - 监听 abortSignal，在 gateway.stopAccount() 时优雅退出
+ *
+ * 初始化职责（由 channel.ts startAccount 负责）：
+ *   - 调用 getMe 获取 botInfo
+ *   - 缓存 botInfo 到 bot-info-cache
+ *   - 清理缓存（stopAccount）
+ *
+ * 事件箱拉取工作原理（对应文档 §二）：
+ *   ┌──────────────────────────────────────────────────────────────────┐
+ *   │  POST /pullMessages { boxId, startSeq }                         │
+ *   │    ↓ 平台立即返回（有消息返回列表，无消息 endSeq=0）              │
+ *   │  处理消息                                                        │
+ *   │  milestone=true → 落库 endSeq，下次从 endSeq+1 开始             │
+ *   │  hasMore=true → 立即继续拉取；否则等待 pollIntervalMs            │
+ *   └──────────────────────────────────────────────────────────────────┘
+ *
+ * ctx 字段命名规则：
+ *   OpenClaw core 的 dispatchReplyWithBufferedBlockDispatcher 期望 PascalCase 字段名：
+ *     Body / BodyForAgent / RawBody / CommandBody — 消息文本
+ *     From / To / SenderId / SenderName           — 发送方/接收方
+ *     SessionKey / AccountId / ChatType            — 路由和会话
+ *     MessageSid / Provider / Surface              — 消息标识和渠道
+ *   参考：extensions/twitch/src/monitor.ts、extensions/googlechat/src/monitor.ts
+ *
+ * 错误处理策略：
+ *   - 401 Unauthorized：签名验证失败，停止监听并标记账号未配置
+ *   - 其他错误：指数退避重试（1s → 2s → 4s → ... → 最多 30s）
+ */
+
+import * as fs from 'fs';
+import * as path from 'path';
+import type { ChannelGatewayContext } from 'openclaw/plugin-sdk/channel-contract';
+import { createTypingCallbacks } from 'openclaw/plugin-sdk/channel-reply-pipeline';
+import type { OpenClawConfig } from 'openclaw/plugin-sdk/config-runtime';
+import { resolveStateDir } from 'openclaw/plugin-sdk/state-paths';
+import { pullMessages } from './api-client.js';
+import type { BotInfo, PullState } from './api-client.js';
+import type { E2eeService } from './e2ee/index.js';
+import { downloadAndDecryptFile } from './file-transfer/index.js';
+import { isMarkdownContent, extractMarkdownDigest } from './markdown-detect.js';
+import { uploadEncryptedFile } from './file-transfer/index.js';
+import { inferMediaType, inferMediaTypeFromMime } from './media-utils.js';
+import type { E2eeDecryptFn } from './proto/inbound.codec.js';
+import { rememberRecentMessage, resolveQuotedMessage } from './recent-message-cache.js';
+import { sendTextToPeer, sendMarkdownToPeer, sendMediaToPeer, sendMsgReadToPeer } from './send.js';
+import type { OutboundContext } from './send.js';
+import type { ImweInboundMessage, ResolvedImweAccount } from './types.js';
+
+// ─────────────────────────────────────────────────────────────────────────────
+// channelRuntime 的最小类型定义
+// ─────────────────────────────────────────────────────────────────────────────
+// ChannelRuntimeSurface 是 { [key: string]: unknown }，运行时注入完整的
+// createPluginRuntime().channel 对象。这里只声明插件实际用到的方法签名。
+
+type ChannelReplyRuntime = {
+  /** 将入站消息分发给 AI agent，通过 deliver 回调发送回复 */
+  dispatchReplyWithBufferedBlockDispatcher: (params: {
+    ctx: Record<string, unknown>;
+    cfg: OpenClawConfig;
+    dispatcherOptions: {
+      deliver: (payload: unknown) => Promise<void>;
+      onError?: (err: unknown, info: { kind: string }) => void;
+      typingCallbacks?: {
+        onReplyStart: () => Promise<void>;
+        onIdle?: () => void;
+        onCleanup?: () => void;
+      };
+    };
+  }) => Promise<unknown>;
+
+  /**
+   * 格式化入站消息的 agent 信封（添加发送者、时间戳等上下文信息）。
+   * 返回格式化后的字符串，作为 Body 字段传给 dispatchReply。
+   */
+  formatAgentEnvelope: (params: {
+    channel: string;
+    from: string;
+    timestamp?: number;
+    envelope: unknown;
+    body: string;
+  }) => string;
+
+  /** 获取信封格式化选项（从 cfg 中读取用户配置） */
+  resolveEnvelopeFormatOptions: (cfg: OpenClawConfig) => unknown;
+
+  /**
+   * 对入站 ctx 做最终处理（注入默认字段、规范化等）。
+   * 必须在传给 dispatchReply 之前调用。
+   */
+  finalizeInboundContext: <T extends Record<string, unknown>>(ctx: T) => T;
+};
+
+type ChannelRoutingRuntime = {
+  /** 根据渠道、账号、对端信息解析 agent 路由（agentId + sessionKey） */
+  resolveAgentRoute: (params: {
+    cfg: OpenClawConfig;
+    channel: string;
+    accountId: string;
+    peer: { kind: string; id: string };
+  }) => { agentId: string; sessionKey: string; accountId: string };
+};
+
+type ChannelSessionRuntime = {
+  /** 解析会话存储路径 */
+  resolveStorePath: (store: string | undefined, params: { agentId: string }) => string;
+  /** 记录入站会话元数据（发送者信息、时间戳等） */
+  recordInboundSession: (params: {
+    storePath: string;
+    sessionKey: string;
+    ctx: Record<string, unknown>;
+    onRecordError?: (err: unknown) => void;
+  }) => Promise<void>;
+};
+
+/** 短轮询默认间隔（毫秒），也作为自适应策略的初始间隔 */
+const DEFAULT_POLL_INTERVAL_MS = 10_000;
+
+/** 自适应轮询参数：有消息时使用最小间隔，空闲时逐步退避到最大间隔 */
+const MIN_POLL_INTERVAL_MS = 2_000;
+const MAX_POLL_INTERVAL_MS = 15_000;
+const POLL_GROW_FACTOR = 1.5;
+
+// ─────────────────────────────────────────────────────────────────────────────
+// pullState 持久化（按账号隔离）
+// 存储路径：~/.openclaw/channel-data/imwe/<accountId>/pull-state.json
+// ─────────────────────────────────────────────────────────────────────────────
+
+function resolvePullStatePath(boxId: string): string {
+  const stateDir = resolveStateDir();
+  return path.join(stateDir, 'channel-data', 'imwe', boxId, 'pull-state.json');
+}
+
+/** 从磁盘读取持久化的 pullState，不存在或解析失败时返回默认值 */
+function loadPullState(boxId: string, log?: ChannelGatewayContext['log']): PullState {
+  const filePath = resolvePullStatePath(boxId);
+  try {
+    const raw = fs.readFileSync(filePath, 'utf-8');
+    const data = JSON.parse(raw) as { nextStartSeq?: number };
+    if (typeof data.nextStartSeq === 'number' && data.nextStartSeq > 0) {
+      log?.info?.(`[${boxId}] 从 ${filePath} 恢复 pullState: nextStartSeq=${data.nextStartSeq}`);
+      return { nextStartSeq: data.nextStartSeq };
+    }
+  } catch {
+    // 文件不存在或解析失败，使用默认值
+  }
+  return { nextStartSeq: 0 };
+}
+
+/** 将 pullState 持久化到磁盘 */
+function savePullState(boxId: string, state: PullState, log?: ChannelGatewayContext['log']): void {
+  const filePath = resolvePullStatePath(boxId);
+  try {
+    const dir = path.dirname(filePath);
+    fs.mkdirSync(dir, { recursive: true });
+    fs.writeFileSync(filePath, JSON.stringify(state), 'utf-8');
+  } catch (err) {
+    log?.warn?.(`[${boxId}] pullState 持久化失败：${String(err)}`);
+  }
+}
+
+// ─────────────────────────────────────────────────────────────────────────────
+// 主入口
+// ─────────────────────────────────────────────────────────────────────────────
+
+/**
+ * 启动 imwe 账号的事件箱轮询循环。
+ *
+ * 前置条件（由 channel.ts startAccount 保证）：
+ *   - 凭证已检查（appKey/appSecret 非空）
+ *   - getMe 已调用成功，botInfo 已缓存到 bot-info-cache
+ *
+ * @param ctx     ChannelGatewayContext，包含账号信息、配置、日志、abortSignal 等
+ * @param botInfo getMe 返回的机器人信息（由 startAccount 传入）
+ */
+export async function monitorImweAccount(
+  ctx: ChannelGatewayContext<ResolvedImweAccount>,
+  botInfo: BotInfo,
+  opts?: { e2eeService?: E2eeService },
+): Promise<void> {
+  const { account, cfg, abortSignal, log } = ctx;
+  const { apiBaseUrl, appKey, appSecret, accountId } = account;
+
+  const auth = { apiKey: appKey, apiSecret: appSecret };
+  const basePollIntervalMs = account.config.pollIntervalMs ?? DEFAULT_POLL_INTERVAL_MS;
+
+  // boxId = 机器人的 botAcctId，用于事件箱拉取
+  const boxId = botInfo.botAcctId;
+
+  // 构造 e2eeDecrypt 回调（若注入了 e2eeService）
+  const e2eeService = opts?.e2eeService;
+
+  // 一次性构造 OutboundContext，供 deliver 回调使用基础层发送
+  const outbound: OutboundContext = {
+    apiBaseUrl,
+    auth,
+    accountId,
+    fromId: botInfo.botAcctId,
+    e2eeService,
+    log,
+  };
+  const e2eeDecrypt: E2eeDecryptFn | undefined = e2eeService
+    ? async (params) => {
+        const result = await e2eeService.decryptSingle(params);
+        // envelopeType=2 解密成功后由 service.dispatchOperation 内部处理
+        if (result !== null && params.envelopeType === 2) {
+          await e2eeService.dispatchOperation({
+            fromId: params.fromId,
+            fromE2eeId: params.fromE2eeId,
+            plainBytes: result,
+          });
+        }
+        return result;
+      }
+    : undefined;
+
+  log?.info?.(
+    `[${accountId}] imwe 事件箱轮询启动，boxId=${boxId}，初始间隔=${basePollIntervalMs}ms（自适应 ${MIN_POLL_INTERVAL_MS}~${MAX_POLL_INTERVAL_MS}ms）`,
+  );
+
+  // ── 步骤3：进入轮询循环 ────────────────────────────────────────────────────
+  let pullState: PullState = loadPullState(boxId, log);
+  let errorCount = 0;
+  let currentIntervalMs = basePollIntervalMs;
+
+  while (!abortSignal.aborted) {
+    try {
+      const result = await pullMessages(apiBaseUrl, auth, boxId, pullState, { e2eeDecrypt });
+
+      log?.info?.(`[${accountId}] imwe pullMessages 成功，内容： ${JSON.stringify(result)}`);
+
+      // 重置错误计数器
+      errorCount = 0;
+      pullState = result.state;
+
+      // 持久化 pullState，防止重启后重复处理已拉取的消息
+      savePullState(boxId, pullState, log);
+
+      // 测试只取第一条消息
+      // result.messages = result.messages.slice(0, 1);
+
+      for (const msg of result.messages) {
+        if (abortSignal.aborted) {
+          break;
+        }
+        await handleInboundMessage(ctx, msg, botInfo, outbound);
+      }
+
+      // hasMore=true 时立即继续拉取，不等待间隔
+      if (result.hasMore && !abortSignal.aborted) {
+        continue;
+      }
+
+      // 自适应间隔：有消息时恢复最小间隔，无消息时逐步退避
+      if (result.messages.length > 0) {
+        currentIntervalMs = MIN_POLL_INTERVAL_MS;
+      } else {
+        currentIntervalMs = Math.min(currentIntervalMs * POLL_GROW_FACTOR, MAX_POLL_INTERVAL_MS);
+      }
+      // Jitter：在 75%~125% 范围内随机抖动，防止多账号同时请求（雷群效应）
+      const jitteredMs = currentIntervalMs * (0.75 + Math.random() * 0.5);
+      await sleep(jitteredMs, abortSignal);
+    } catch (err) {
+      if (abortSignal.aborted) {
+        break;
+      }
+
+      if (isUnauthorizedError(err)) {
+        log?.error?.(`[${accountId}] imwe 签名验证失败（401），请检查 AppKey/AppSecret`);
+        ctx.setStatus({
+          accountId,
+          enabled: true,
+          configured: false,
+          lastError: '签名验证失败，请检查 AppKey/AppSecret',
+        });
+        return;
+      }
+
+      errorCount++;
+      const backoffMs = Math.min(1000 * Math.pow(2, errorCount - 1), 30_000);
+      log?.warn?.(
+        `[${accountId}] pullMessages 出错（第 ${errorCount} 次）：${String(err)}，${backoffMs}ms 后重试`,
+      );
+      await sleep(backoffMs, abortSignal);
+      continue;
+    }
+  }
+
+  log?.info(`[${accountId}] imwe 事件箱轮询已停止`);
+}
+
+// ─────────────────────────────────────────────────────────────────────────────
+// 内部：处理单条入站消息
+// ─────────────────────────────────────────────────────────────────────────────
+
+/**
+ * 将解包后的入站消息分发给 OpenClaw core 处理，并通过 deliver 回调发送回复。
+ *
+ * ctx 字段命名遵循 OpenClaw core 的 PascalCase 约定：
+ *   Body / BodyForAgent / RawBody / CommandBody — 消息文本（core 从 Body 读取内容）
+ *   From / To / SenderId / SenderName           — 发送方/接收方标识
+ *   SessionKey / AccountId / ChatType            — 路由和会话类型
+ *   MessageSid / Provider / Surface              — 消息 ID 和渠道标识
+ *
+ * @param ctx     ChannelGatewayContext
+ * @param msg     解包后的文本消息
+ * @param botInfo getMe 返回的机器人信息
+ */
+async function handleInboundMessage(
+  ctx: ChannelGatewayContext<ResolvedImweAccount>,
+  msg: ImweInboundMessage,
+  botInfo: BotInfo,
+  outbound: OutboundContext,
+): Promise<void> {
+  const { account, cfg, log, channelRuntime } = ctx;
+
+  if (!channelRuntime) {
+    log?.warn?.(`[${account.accountId}] channelRuntime 不可用，跳过消息 ${msg.msgId}`);
+    return;
+  }
+
+  // msg.content = '今天天气怎么样？'
+  log?.info?.(
+    `[${account.accountId}] 收到消息 from=${msg.senderId} content="${msg.content.slice(0, 50)}"` +
+      (msg.attachments?.length
+        ? ` attachments=${msg.attachments.length} [${msg.attachments.map((a) => `${a.type}:${a.url?.slice(0, 60)}`).join(', ')}]`
+        : ''),
+  );
+
+  // 获取 channelRuntime 上的各子模块
+  const replyRuntime = channelRuntime.reply as ChannelReplyRuntime;
+  const routingRuntime = channelRuntime.routing as ChannelRoutingRuntime;
+  const sessionRuntime = channelRuntime.session as ChannelSessionRuntime;
+
+  try {
+    // ── 1. 解析 agent 路由 ──────────────────────────────────────────────────
+    const route = routingRuntime.resolveAgentRoute({
+      cfg,
+      channel: 'imwe',
+      accountId: account.accountId,
+      peer: { kind: 'direct', id: msg.senderId },
+    });
+
+    // ── 2. 格式化消息文本（添加发送者、时间戳等上下文信封） ──────────────────
+    const rawBody = msg.content;
+    const body = replyRuntime.formatAgentEnvelope({
+      channel: 'imwe',
+      from: msg.senderId,
+      timestamp: msg.timestampMs,
+      envelope: replyRuntime.resolveEnvelopeFormatOptions(cfg),
+      body: rawBody,
+    });
+
+    // ── 3. 处理入站多媒体附件 ──────────────────────────────────────────────
+    const mediaFields: Record<string, unknown> = {};
+    if (msg.attachments && msg.attachments.length > 0) {
+      const { saveMediaSource } = await import('openclaw/plugin-sdk/media-runtime');
+      const { buildMediaPayload } = await import('openclaw/plugin-sdk/reply-payload');
+
+      const mediaInputs: Array<{ path: string; contentType?: string }> = [];
+      for (const attachment of msg.attachments) {
+        try {
+          // 加密文件：通过 downloadAndDecryptFile 分片下载并解密
+          if (attachment.fileKey) {
+            log?.info?.(
+              `[${account.accountId}] 下载加密附件: type=${attachment.type}, url=${attachment.url?.slice(0, 80)}`,
+            );
+            const stateDir = resolveStateDir();
+            const savePath = path.join(
+              stateDir,
+              'channel-data',
+              'imwe',
+              botInfo.botAcctId,
+              'file-transfer',
+              'download',
+              `${msg.msgId}-${attachment.fileName ?? 'file'}`,
+            );
+            const downloadResult = await downloadAndDecryptFile(
+              {
+                url: attachment.url,
+                key: attachment.fileKey,
+                iv: attachment.fileIv!,
+                digest: attachment.fileDigest!,
+                plaintextLength: attachment.plaintextLength!,
+                opCreds: attachment.opCreds,
+                savePath,
+                messageContext: {
+                  msgId: msg.msgId,
+                  senderId: msg.senderId,
+                  content: msg.content,
+                  timestampMs: msg.timestampMs,
+                },
+              },
+              outbound.auth,
+              outbound.apiBaseUrl,
+            );
+            const saved = await saveMediaSource(downloadResult.localPath);
+            log?.info?.(
+              `[${account.accountId}] 加密附件下载解密成功: path=${saved.path}, contentType=${saved.contentType ?? attachment.mimeType ?? '(unknown)'}`,
+            );
+            mediaInputs.push({
+              path: saved.path,
+              contentType: saved.contentType ?? attachment.mimeType,
+            });
+          } else {
+            // 明文文件：走现有下载路径（向后兼容）
+            log?.info?.(
+              `[${account.accountId}] 下载附件: type=${attachment.type}, url=${attachment.url?.slice(0, 80)}`,
+            );
+            const saved = await saveMediaSource(attachment.url);
+            log?.info?.(
+              `[${account.accountId}] 附件下载成功: path=${saved.path}, contentType=${saved.contentType ?? attachment.mimeType ?? '(unknown)'}`,
+            );
+            mediaInputs.push({
+              path: saved.path,
+              contentType: saved.contentType ?? attachment.mimeType,
+            });
+          }
+        } catch (err) {
+          log?.warn?.(
+            `[${account.accountId}] 下载附件失败: type=${attachment.type}, url=${attachment.url?.slice(0, 80)}, error=${String(err)}`,
+          );
+        }
+      }
+
+      if (mediaInputs.length > 0) {
+        const mediaPayload = buildMediaPayload(mediaInputs);
+        log?.info?.(
+          `[${account.accountId}] 媒体 payload 构造完成: ${mediaInputs.length}/${msg.attachments.length} 个附件`,
+        );
+        Object.assign(mediaFields, mediaPayload);
+      }
+    }
+
+    // ── 4. 构造 PascalCase ctx 并通过 finalizeInboundContext 规范化 ─────────
+    const cacheScopeKey = botInfo.botMainAcctId;
+    const replyToId = msg.referenceClientMsgId ?? undefined;
+    const quotedMessage = resolveQuotedMessage(cacheScopeKey, replyToId);
+    if (replyToId) {
+      if (quotedMessage) {
+        log?.info?.(
+          `[${account.accountId}] 引用消息命中缓存: ref=${replyToId}, sender=${quotedMessage.senderId}`,
+        );
+      } else {
+        log?.warn?.(`[${account.accountId}] 引用消息未命中缓存: ref=${replyToId}`);
+      }
+    }
+    // 先解析引用，再写入当前消息，避免当前消息错误覆盖引用目标。
+    rememberRecentMessage(cacheScopeKey, {
+      msgId: msg.msgId,
+      body: msg.content,
+      senderId: msg.senderId,
+      timestampMs: msg.timestampMs,
+    });
+    const ctxPayload = replyRuntime.finalizeInboundContext({
+      Body: body,
+      BodyForAgent: rawBody,
+      RawBody: rawBody,
+      CommandBody: rawBody,
+      From: `imwe:${msg.senderId}`,
+      To: `imwe:${msg.senderId}`,
+      SessionKey: route.sessionKey,
+      AccountId: route.accountId,
+      ChatType: 'direct',
+      SenderName: msg.senderId,
+      SenderId: msg.senderId,
+      Provider: 'imwe',
+      Surface: 'imwe',
+      // imwe 当前仅支持私聊；消息进入这里说明已通过渠道级接入，
+      // 需要显式标记为可处理的文本命令上下文，否则 /skill 会被 core 静默判为未授权。
+      CommandAuthorized: true,
+      CommandSource: 'text',
+      MessageSid: msg.msgId,
+      OriginatingChannel: 'imwe',
+      OriginatingTo: `imwe:${msg.senderId}`,
+      ReplyToId: replyToId,
+      ReplyToBody: quotedMessage?.body,
+      ReplyToSender: quotedMessage?.senderId,
+      ReplyToIsQuote: quotedMessage ? true : undefined,
+      ...mediaFields,
+    });
+
+    log?.info?.(`[${account.accountId}] reply ctx: ${JSON.stringify(ctxPayload)}`);
+
+    // ── 5. 记录入站会话元数据 ───────────────────────────────────────────────
+    const storePath = sessionRuntime.resolveStorePath(
+      (cfg as Record<string, unknown> & { session?: { store?: string } }).session?.store,
+      { agentId: route.agentId },
+    );
+    await sessionRuntime.recordInboundSession({
+      storePath,
+      sessionKey: (ctxPayload.SessionKey as string) ?? route.sessionKey,
+      ctx: ctxPayload,
+      onRecordError: (err) => {
+        log?.warn?.(`[${account.accountId}] 更新会话元数据失败：${String(err)}`);
+      },
+    });
+
+    // ── 5.5 创建 typing callbacks ──────────────────────────────────────────
+    const typingCallbacks = createTypingCallbacks({
+      start: async () => {
+        const { sendImweTypingSignal } = await import('./send.js');
+        await sendImweTypingSignal({
+          to: msg.senderId,
+          status: 1,
+          accountId: account.accountId,
+          cfg,
+        });
+      },
+      stop: async () => {
+        const { sendImweTypingSignal } = await import('./send.js');
+        await sendImweTypingSignal({
+          to: msg.senderId,
+          status: 2,
+          accountId: account.accountId,
+          cfg,
+        });
+      },
+      onStartError: (err) => {
+        log?.warn?.(`[${account.accountId}] typing start 失败：${String(err)}`);
+      },
+      onStopError: (err) => {
+        log?.warn?.(`[${account.accountId}] typing stop 失败：${String(err)}`);
+      },
+    });
+
+    // ── 6. 分发给 AI agent 处理 ─────────────────────────────────────────────
+    await replyRuntime.dispatchReplyWithBufferedBlockDispatcher({
+      ctx: ctxPayload,
+      cfg,
+      dispatcherOptions: {
+        deliver: async (payload: unknown) => {
+          const text = extractTextFromPayload(payload);
+          const mediaUrls = extractMediaUrlsFromPayload(payload);
+          const payloadReplyToId = extractReplyToIdFromPayload(payload);
+
+          log?.info?.(
+            `[${account.accountId}] 收到回复消息，文本长度：${text.length}，媒体数量：${mediaUrls.length}${mediaUrls.length > 0 ? ` [${mediaUrls.map((u) => u.slice(0, 60)).join(', ')}]` : ''}，replyToId=${payloadReplyToId ?? 'none'}`,
+          );
+          // 有媒体 → 逐个上传并通过基础层发送，第一个媒体附带文本作为 caption
+          if (mediaUrls.length > 0) {
+            for (let i = 0; i < mediaUrls.length; i++) {
+              try {
+                log?.info?.(
+                  `[${account.accountId}] 发送媒体回复 (${i + 1}/${mediaUrls.length}): url=${mediaUrls[i].slice(0, 80)}, caption=${i === 0 && text ? 'yes' : 'no'}`,
+                );
+                // 使用 E2EE 加密分片上传
+                const uploadResult = await uploadEncryptedFile(
+                  mediaUrls[i],
+                  outbound.auth,
+                  outbound.apiBaseUrl,
+                  {
+                    imMainAccId: msg.senderId,
+                    config: {
+                      stateDir: path.join(
+                        resolveStateDir(),
+                        'channel-data',
+                        'imwe',
+                        outbound.fromId,
+                        'file-transfer',
+                      ),
+                    },
+                    sendContext: {
+                      to: msg.senderId,
+                      fromId: outbound.fromId,
+                      mediaType: inferMediaType(mediaUrls[i]),
+                      caption: i === 0 ? text : undefined,
+                    },
+                    log,
+                  },
+                );
+                await sendMediaToPeer(outbound, {
+                  to: msg.senderId,
+                  url: uploadResult.url,
+                  mediaType: uploadResult.contentType
+                    ? inferMediaTypeFromMime(uploadResult.contentType)
+                    : inferMediaType(mediaUrls[i]),
+                  fileKey: uploadResult.fileKey,
+                  fileIv: uploadResult.fileIv,
+                  fileDigest: uploadResult.fileDigest,
+                  plaintextLength: uploadResult.plaintextLength,
+                  fileSize: uploadResult.plaintextLength,
+                  mimeType: uploadResult.contentType,
+                  caption: i === 0 ? text : undefined,
+                  blurHash: uploadResult.blurHash,
+                  width: uploadResult.width,
+                  height: uploadResult.height,
+                  expireTime: uploadResult.expireTime,
+                  opCreds: uploadResult.opCreds,
+                  length: uploadResult.plaintextLength,
+                });
+                log?.info?.(
+                  `[${account.accountId}] 媒体回复发送成功 (${i + 1}/${mediaUrls.length})`,
+                );
+              } catch (err) {
+                log?.warn?.(
+                  `[${account.accountId}] 媒体发送失败 (${i + 1}/${mediaUrls.length}, ${mediaUrls[i].slice(0, 60)}): ${String(err)}`,
+                );
+              }
+            }
+            // 发送已读操作消息（不阻断主流程）
+            try {
+              await sendMsgReadToPeer(outbound, {
+                to: msg.senderId,
+                targetClientMsgIds: [msg.msgId],
+                readStamp: Math.floor(Date.now() / 1000),
+              });
+            } catch {
+              // sendMsgReadToPeer 内部已处理错误
+            }
+
+            return;
+          }
+
+          // markdown 文本：命中 markdown 特征时走 sendMarkdownToPeer
+          if (text && isMarkdownContent(text)) {
+            const digest = extractMarkdownDigest(text);
+            try {
+              await sendMarkdownToPeer(outbound, {
+                to: msg.senderId,
+                markdown: text,
+                replyToId: payloadReplyToId,
+                digest: digest || undefined,
+              });
+            } catch (err) {
+              log?.warn?.(`[${account.accountId}] imwe markdown reply 发送失败：${String(err)}`);
+            }
+            // 发送已读操作消息（不阻断主流程）
+            try {
+              await sendMsgReadToPeer(outbound, {
+                to: msg.senderId,
+                targetClientMsgIds: [msg.msgId],
+                readStamp: Math.floor(Date.now() / 1000),
+              });
+            } catch {
+              // sendMsgReadToPeer 内部已处理错误
+            }
+
+            return;
+          }
+
+          // 纯文本
+          if (!text) {
+            return;
+          }
+          await sendTextToPeer(outbound, {
+            to: msg.senderId,
+            text,
+            replyToId: payloadReplyToId,
+          });
+          // 发送已读操作消息（不阻断主流程）
+          try {
+            await sendMsgReadToPeer(outbound, {
+              to: msg.senderId,
+              targetClientMsgIds: [msg.msgId],
+              readStamp: Math.floor(Date.now() / 1000),
+            });
+          } catch {
+            // sendMsgReadToPeer 内部已处理错误
+          }
+        },
+        onError: (err, info) => {
+          log?.error?.(`[${account.accountId}] imwe ${info.kind} reply 发送失败：${String(err)}`);
+        },
+        typingCallbacks,
+      },
+    });
+  } catch (err) {
+    log?.error?.(`[${account.accountId}] 处理消息失败：${String(err)}`);
+  }
+}
+
+// ─────────────────────────────────────────────────────────────────────────────
+// 工具函数
+// ─────────────────────────────────────────────────────────────────────────────
+
+/** 判断错误是否为 401 鉴权失败 */
+function isUnauthorizedError(err: unknown): boolean {
+  const msg = String(err);
+  return msg.includes('401') || msg.toLowerCase().includes('unauthorized');
+}
+
+/**
+ * 从 OpenClaw reply payload 中提取纯文本内容。
+ * payload 可能是 content block 数组（type=text）或直接的 text 字段。
+ */
+function extractTextFromPayload(payload: unknown): string {
+  if (!payload || typeof payload !== 'object') {
+    return '';
+  }
+  const p = payload as Record<string, unknown>;
+  if (Array.isArray(p.content)) {
+    return p.content
+      .filter(
+        (b): b is { type: string; text: string } =>
+          typeof b === 'object' && b !== null && (b as Record<string, unknown>).type === 'text',
+      )
+      .map((b) => b.text)
+      .join('\n');
+  }
+  if (typeof p.text === 'string') {
+    return p.text;
+  }
+  return '';
+}
+
+/**
+ * 从 block content 中提取图片 URL。
+ * 兼容 OpenAI 风格的 image_url block，以及本地 image block。
+ */
+function extractMediaUrlsFromContentBlocks(content: unknown): string[] {
+  if (!Array.isArray(content)) {
+    return [];
+  }
+
+  const urls: string[] = [];
+  for (const block of content) {
+    if (!block || typeof block !== 'object') {
+      continue;
+    }
+    const item = block as Record<string, unknown>;
+
+    if (item.type === 'image_url') {
+      const imageUrl = item.image_url;
+      if (imageUrl && typeof imageUrl === 'object') {
+        const url = (imageUrl as Record<string, unknown>).url;
+        if (typeof url === 'string' && url.trim()) {
+          urls.push(url.trim());
+        }
+      }
+      continue;
+    }
+
+    if (item.type === 'image') {
+      const source = item.source;
+      if (source && typeof source === 'object') {
+        const sourceRecord = source as Record<string, unknown>;
+        if (typeof sourceRecord.data === 'string' && sourceRecord.data.trim()) {
+          const mimeType =
+            typeof sourceRecord.media_type === 'string' && sourceRecord.media_type.trim()
+              ? sourceRecord.media_type.trim()
+              : 'image/png';
+          const raw = sourceRecord.data.trim();
+          urls.push(raw.startsWith('data:') ? raw : `data:${mimeType};base64,${raw}`);
+          continue;
+        }
+      }
+      if (typeof item.url === 'string' && item.url.trim()) {
+        urls.push(item.url.trim());
+      }
+    }
+  }
+
+  return urls;
+}
+
+/**
+ * 检测纯文本是否其实是本地媒体路径。
+ * 当前仅兼容图片路径，避免 qwen-image 一类 skill 返回本地文件路径时被吞掉。
+ */
+function detectLocalImagePath(text: string): string | null {
+  const raw = text.trim();
+  if (!raw || /\s/.test(raw)) {
+    return null;
+  }
+  if (/^(https?:\/\/|data:|file:\/\/)/i.test(raw)) {
+    return null;
+  }
+  const ext = path.extname(raw).toLowerCase();
+  if (
+    !['.jpg', '.jpeg', '.png', '.gif', '.webp', '.bmp', '.ico', '.tiff', '.heic', '.heif'].includes(
+      ext,
+    )
+  ) {
+    return null;
+  }
+  return raw;
+}
+
+/**
+ * 从 OpenClaw reply payload 中提取媒体 URL 列表。
+ * 兼容 mediaUrls / mediaUrl，以及 content 里的图片 block。
+ */
+export function extractMediaUrlsFromPayload(payload: unknown): string[] {
+  if (!payload || typeof payload !== 'object') return [];
+  const p = payload as Record<string, unknown>;
+
+  const urls: string[] = [];
+
+  if (Array.isArray(p.mediaUrls)) {
+    urls.push(
+      ...p.mediaUrls.filter((u): u is string => typeof u === 'string' && u.trim().length > 0),
+    );
+  }
+  if (typeof p.mediaUrl === 'string' && p.mediaUrl.length > 0) {
+    urls.push(p.mediaUrl);
+  }
+  urls.push(...extractMediaUrlsFromContentBlocks(p.content));
+
+  const localImagePath = typeof p.text === 'string' ? detectLocalImagePath(p.text) : null;
+  if (localImagePath) {
+    urls.push(localImagePath);
+  }
+
+  return [...new Set(urls.map((url) => url.trim()).filter(Boolean))];
+}
+
+/**
+ * 从 OpenClaw reply payload 中提取 replyToId。
+ * core 根据 replyToMode 决定是否在 payload 中携带 replyToId。
+ */
+function extractReplyToIdFromPayload(payload: unknown): string | undefined {
+  if (!payload || typeof payload !== 'object') return undefined;
+  const p = payload as Record<string, unknown>;
+  if (typeof p.replyToId === 'string' && p.replyToId) return p.replyToId;
+  return undefined;
+}
+
+/** 可中断的 sleep，abortSignal 触发时提前 resolve */
+function sleep(ms: number, signal?: AbortSignal): Promise<void> {
+  return new Promise((resolve) => {
+    const timer = setTimeout(resolve, ms);
+    signal?.addEventListener(
+      'abort',
+      () => {
+        clearTimeout(timer);
+        resolve();
+      },
+      { once: true },
+    );
+  });
+}