@imweapp/openclaw-imwe 2026.4.12-alpha.1

package/src/send.ts

@@ -0,0 +1,792 @@
+/**
+ * send.ts — 发送消息（outbound / pairing / 主动投递 统一入口）
+ *
+ * 双层结构：
+ *   - 基础层（sendTextToPeer / sendMarkdownToPeer / sendMediaToPeer / sendTypingSignalToPeer）
+ *     接收已解析的 OutboundContext，负责 E2EE 加密 + HTTP 发送 + DEVICE_NOT_MATCH 重试 +
+ *     rememberRecentMessage 写入。
+ *   - 顶层（sendImweText / sendImweMarkdown / sendImweMedia / sendImweTypingSignal）
+ *     保留既有签名（{ ..., accountId?, cfg }），实现为 resolveImweAccount + resolveFromId +
+ *     账号未配置守卫 → 构造 OutboundContext → 委托基础层。顶层不再直接调 api-client.ts。
+ *
+ * fromId（机器人的 botAcctId）获取策略：
+ *   1. 优先从 bot-info-cache 读取（gateway 启动时 startAccount 已通过 getMe 缓存）
+ *   2. 缓存未命中时（如 gateway 未启动的主动投递场景），自动调用 getMe 获取并缓存
+ */
+
+import path from 'node:path';
+import type { OpenClawConfig } from 'openclaw/plugin-sdk/config-runtime';
+import { resolveStateDir } from 'openclaw/plugin-sdk/state-paths';
+import { z } from 'openclaw/plugin-sdk/zod';
+import { postProto } from './api-client.js';
+import {
+  buildChatEnvelopeBytes,
+  buildMarkdownEnvelopeBytes,
+  buildMediaEnvelopeBytes,
+  buildMsgReadEnvelopeBytes,
+  encodeSingleChatReqPacket,
+  encodeTypingSignalRequest,
+  decodeSendResponse,
+  genClientMsgId,
+} from './proto/send.codec.js';
+import { resolveImweAccount } from './accounts.js';
+import { getBotInfo, setBotInfo } from './bot-info-cache.js';
+import { uploadEncryptedFile } from './file-transfer/index.js';
+import { inferMediaType } from './media-utils.js';
+import { init as initRecentMessageCache, rememberRecentMessage } from './recent-message-cache.js';
+import type { E2eeService } from './e2ee/index.js';
+import { DeviceNotMatchError } from './e2ee/errors.js';
+import type { ImweSendResponse } from './types.js';
+import { extractMarkdownDigest } from './markdown-detect.js';
+
+// ─────────────────────────────────────────────────────────────────────────────
+// OutboundContext — 基础层入参
+// ─────────────────────────────────────────────────────────────────────────────
+
+/** 基础层发送所需的已解析上下文 */
+export type OutboundContext = {
+  apiBaseUrl: string;
+  auth: { apiKey: string; apiSecret: string };
+  accountId: string;
+  fromId: string;
+  e2eeService?: E2eeService;
+  log?: { info?: (...args: unknown[]) => void; warn?: (...args: unknown[]) => void };
+};
+
+// ─────────────────────────────────────────────────────────────────────────────
+// 内部工具
+// ─────────────────────────────────────────────────────────────────────────────
+
+function buildCachedOutboundBody(text: string | undefined, fallback: string): string {
+  const normalized = text?.trim();
+  return normalized || fallback;
+}
+
+function ensureRecentMessageCachePersistence(): void {
+  // 主动投递可能发生在 gateway 未启动时，这里 lazy init 确保出站缓存也能落盘。
+  initRecentMessageCache(resolveStateDir());
+}
+
+/**
+ * 获取机器人的 fromId（botAcctId）。
+ * 优先从缓存读取，未命中时 lazy 调用 getMe 获取并缓存。
+ * getMe 失败时返回空字符串，让平台尝试从 ApiKey 解析发送方身份。
+ */
+async function resolveFromId(
+  accountId: string,
+  apiBaseUrl: string,
+  auth: { apiKey: string; apiSecret: string },
+): Promise<string> {
+  let botInfo = getBotInfo(accountId);
+  if (!botInfo) {
+    try {
+      const { getMe } = await import('./api-client.js');
+      botInfo = await getMe(apiBaseUrl, auth);
+      setBotInfo(accountId, botInfo);
+    } catch {
+      return '';
+    }
+  }
+  return botInfo?.botAcctId ?? '';
+}
+
+/**
+ * 从 postProto 抛出的错误中检测 E2EE_DEVICE_NOT_MATCH 并转换为 DeviceNotMatchError。
+ * 服务端返回非 200 时，响应体为 JSON：{ code: "IM.IM_COM.E2EE_DEVICE_NOT_MATCH", data: {...} }
+ * postProto 会把响应文本拼入 Error.message，这里从中提取 JSON 并解析。
+ */
+function maybeThrowDeviceNotMatch(err: unknown): never {
+  if (!(err instanceof Error)) throw err;
+
+  const msg = err.message;
+  // postProto 格式："imwe API /path 返回 {status}: {responseText}"
+  if (!msg.includes('E2EE_DEVICE_NOT_MATCH')) throw err;
+
+  // 尝试从错误消息中提取 JSON 部分
+  const jsonStart = msg.indexOf('{');
+  if (jsonStart < 0) throw err;
+
+  try {
+    const jsonStr = msg.slice(jsonStart);
+    const parsed = JSON.parse(jsonStr) as {
+      code?: string;
+      data?: {
+        extraDevices?: Array<{ imAcctId: string; e2eeId: string }>;
+        missDevices?: Array<{ imAcctId: string; e2eeId: string }>;
+        extraImAcctIds?: string[];
+        missImAcctIds?: string[];
+      };
+    };
+
+    if (parsed.code?.includes('E2EE_DEVICE_NOT_MATCH') && parsed.data) {
+      throw new DeviceNotMatchError('服务端返回 E2EE_DEVICE_NOT_MATCH', {
+        extraDevices: parsed.data.extraDevices,
+        missDevices: parsed.data.missDevices,
+        extraImAcctIds: parsed.data.extraImAcctIds,
+        missImAcctIds: parsed.data.missImAcctIds,
+      });
+    }
+  } catch (parseErr) {
+    // 如果 parseErr 已经是 DeviceNotMatchError，直接抛出
+    if (parseErr instanceof DeviceNotMatchError) throw parseErr;
+  }
+
+  throw err;
+}
+
+/**
+ * 通过 E2EE 加密 + 发送消息的统一内部流程。
+ * 包含 DEVICE_NOT_MATCH 单次重试逻辑。
+ *
+ * @param outbound  已解析的出站上下文
+ * @param to        接收方 userId
+ * @param envelopeBytes  明文 envelope bytes（第 4 层）
+ * @param clientMsgId    客户端消息 ID
+ * @returns 发送结果
+ */
+async function encryptAndSend(
+  outbound: OutboundContext,
+  to: string,
+  envelopeBytes: Uint8Array,
+  clientMsgId: string,
+): Promise<ImweSendResponse> {
+  const { apiBaseUrl, auth, fromId, e2eeService } = outbound;
+  const prefix = `[send][${outbound.accountId}]`;
+
+  // E2EE 加密
+  outbound.log?.info?.(
+    `${prefix}: encryptAndSend E2EE 加密前, to=${to}, envelopeBytes.length=${envelopeBytes.length}`,
+  );
+  const { recipientsBytes, senderE2eeId } = await e2eeService!.encryptSingle({
+    to,
+    plainBytes: envelopeBytes,
+  });
+  outbound.log?.info?.(
+    `${prefix}: encryptAndSend E2EE 加密完成, recipientsBytes.length=${recipientsBytes.length}, senderE2eeId=${senderE2eeId}`,
+  );
+
+  // 包装为完整 PbPacket
+  const packetBytes = await encodeSingleChatReqPacket({
+    fromId,
+    to,
+    clientMsgId,
+    envelopeBytes: recipientsBytes,
+    e2eeFlag: true,
+    fromE2eeId: senderE2eeId,
+  });
+
+  // 发送（检测 E2EE_DEVICE_NOT_MATCH 并转换为 DeviceNotMatchError）
+  let responseBytes: Uint8Array;
+  try {
+    outbound.log?.info?.(
+      `${prefix}: encryptAndSend 发送请求, url=/api/im/open/bot/sendMessage, to=${to}, clientMsgId=${clientMsgId}`,
+    );
+    responseBytes = await postProto(apiBaseUrl, '/api/im/open/bot/sendMessage', packetBytes, auth);
+    outbound.log?.info?.(
+      `${prefix}: encryptAndSend 发送成功, to=${to}, clientMsgId=${clientMsgId}, responseBytes.length=${responseBytes.length}`,
+    );
+  } catch (err) {
+    maybeThrowDeviceNotMatch(err);
+  }
+
+  return { ...(await decodeSendResponse(responseBytes)), clientMsgId };
+}
+
+/**
+ * E2EE 加密 + 发送，含 DEVICE_NOT_MATCH 单次重试。
+ * 捕获 DeviceNotMatchError → handleDeviceNotMatch → 用同 clientMsgId 重新 encryptSingle + send 恰好一次。
+ * 两次都失败上抛。
+ */
+async function encryptAndSendWithRetry(
+  outbound: OutboundContext,
+  to: string,
+  envelopeBytes: Uint8Array,
+  clientMsgId: string,
+): Promise<ImweSendResponse> {
+  const prefix = `[send][${outbound.accountId}]`;
+  outbound.log?.info?.(
+    `${prefix}: encryptAndSendWithRetry 首次发送, to=${to}, clientMsgId=${clientMsgId}`,
+  );
+  try {
+    return await encryptAndSend(outbound, to, envelopeBytes, clientMsgId);
+  } catch (err) {
+    if (err instanceof DeviceNotMatchError && outbound.e2eeService) {
+      // DEVICE_NOT_MATCH 重试：handleDeviceNotMatch → 用同 clientMsgId 重发一次
+      outbound.log?.info?.(
+        `${prefix}: DEVICE_NOT_MATCH，执行单次重试, to=${to}, clientMsgId=${clientMsgId}, errData=${JSON.stringify(err.data)}`,
+      );
+      await outbound.e2eeService.handleDeviceNotMatch(err.data);
+      const result = await encryptAndSend(outbound, to, envelopeBytes, clientMsgId);
+      outbound.log?.info?.(
+        `${prefix}: DEVICE_NOT_MATCH 重试成功, to=${to}, clientMsgId=${clientMsgId}`,
+      );
+      return result;
+    }
+    throw err;
+  }
+}
+
+// ─────────────────────────────────────────────────────────────────────────────
+// 基础层：sendTextToPeer / sendMarkdownToPeer / sendMediaToPeer / sendTypingSignalToPeer
+// ─────────────────────────────────────────────────────────────────────────────
+
+/**
+ * 基础层：向对端发送文本消息。
+ * 有 e2eeService 时走 buildChatEnvelopeBytes → encryptSingle → encodeSingleChatReqPacket(e2eeFlag=true)。
+ * 无 e2eeService 时走明文路径（兼容 E2EE 未初始化场景）。
+ * rememberRecentMessage 仅在基础层写入。
+ */
+export async function sendTextToPeer(
+  outbound: OutboundContext,
+  params: { to: string; text: string; replyToId?: string; clientMsgId?: string },
+): Promise<ImweSendResponse> {
+  const clientMsgId = params.clientMsgId ?? genClientMsgId();
+  const { apiBaseUrl, auth, fromId, e2eeService } = outbound;
+
+  let result: ImweSendResponse;
+
+  if (e2eeService) {
+    // E2EE 路径：构造 envelope → 加密 → 发送（含 DEVICE_NOT_MATCH 重试）
+    const envelopeBytes = await buildChatEnvelopeBytes(params.text, {
+      referenceClientMsgId: params.replyToId,
+    });
+    result = await encryptAndSendWithRetry(outbound, params.to, envelopeBytes, clientMsgId);
+  } else {
+    // 明文路径（E2EE 未初始化时的兼容回退）
+    const { sendTextMessage } = await import('./api-client.js');
+    result = await sendTextMessage(apiBaseUrl, auth, fromId, params.to, params.text, {
+      replyToId: params.replyToId,
+      clientMsgId,
+    });
+  }
+
+  // 成功时写入 recent-message-cache
+  if (result.ok && result.clientMsgId) {
+    ensureRecentMessageCachePersistence();
+    rememberRecentMessage(params.to, {
+      msgId: result.clientMsgId,
+      body: params.text,
+      senderId: outbound.fromId,
+      timestampMs: Date.now(),
+    });
+  }
+
+  return result;
+}
+
+/**
+ * 基础层：向对端发送 markdown 消息。
+ * 有 e2eeService 时走 buildMarkdownEnvelopeBytes → encryptSingle → encodeSingleChatReqPacket(e2eeFlag=true)。
+ * 无 e2eeService 时走明文路径（兼容 E2EE 未初始化场景）。
+ * rememberRecentMessage 仅在基础层写入。
+ */
+export async function sendMarkdownToPeer(
+  outbound: OutboundContext,
+  params: {
+    to: string;
+    markdown: string;
+    digest?: string;
+    replyToId?: string;
+    clientMsgId?: string;
+  },
+): Promise<ImweSendResponse> {
+  const clientMsgId = params.clientMsgId ?? genClientMsgId();
+  const { apiBaseUrl, auth, fromId, e2eeService } = outbound;
+
+  let result: ImweSendResponse;
+
+  if (e2eeService) {
+    // E2EE 路径
+    const envelopeBytes = await buildMarkdownEnvelopeBytes({
+      markdown: params.markdown,
+      digest: params.digest,
+    });
+    result = await encryptAndSendWithRetry(outbound, params.to, envelopeBytes, clientMsgId);
+  } else {
+    // 明文路径（E2EE 未初始化时的兼容回退）
+    const { sendMarkdownMessage } = await import('./api-client.js');
+    result = await sendMarkdownMessage(apiBaseUrl, auth, {
+      fromId,
+      to: params.to,
+      markdown: params.markdown,
+      digest: params.digest,
+      clientMsgId,
+    });
+  }
+
+  // 成功时写入 recent-message-cache
+  if (result.ok && result.clientMsgId) {
+    ensureRecentMessageCachePersistence();
+    const preview = params.digest || params.markdown.slice(0, 120) || '[markdown]';
+    rememberRecentMessage(params.to, {
+      msgId: result.clientMsgId,
+      body: preview,
+      senderId: outbound.fromId,
+      timestampMs: Date.now(),
+    });
+  }
+
+  return result;
+}
+
+/**
+ * 基础层：向对端发送多媒体消息。
+ * 有 e2eeService 时走 buildMediaEnvelopeBytes → encryptSingle → encodeSingleChatReqPacket(e2eeFlag=true)。
+ * 无 e2eeService 时走明文路径（兼容 E2EE 未初始化场景）。
+ * rememberRecentMessage 仅在基础层写入。
+ *
+ * 注意：媒体上传（uploadEncryptedFile）由调用方在调用前完成，
+ * 基础层只负责已上传媒体的 envelope 构造 + 加密 + 发送。
+ */
+export async function sendMediaToPeer(
+  outbound: OutboundContext,
+  params: {
+    to: string;
+    url: string;
+    mediaType: 'image' | 'video' | 'audio' | 'file';
+    fileName?: string;
+    fileSize?: number;
+    mimeType?: string;
+    width?: number;
+    height?: number;
+    caption?: string;
+    blurHash?: string;
+    clientMsgId?: string;
+    /** E2EE 文件加密密钥（32 字节） */
+    fileKey?: Uint8Array;
+    /** E2EE 文件加密 IV（16 字节） */
+    fileIv?: Uint8Array;
+    /** SHA256(plaintext) 小写十六进制 */
+    fileDigest?: string;
+    /** 明文长度（字节） */
+    plaintextLength?: number;
+    /** 上传会话过期时间（毫秒时间戳） */
+    expireTime?: number;
+    /** 操作凭证（batchCompleteChunks 返回） */
+    opCreds?: string;
+    /** 密文长度（字节，AES-CTR 下等于 plaintextLength） */
+    length?: number;
+  },
+): Promise<ImweSendResponse> {
+  const clientMsgId = params.clientMsgId ?? genClientMsgId();
+  const { apiBaseUrl, auth, fromId, e2eeService } = outbound;
+
+  let result: ImweSendResponse;
+
+  if (e2eeService) {
+    // E2EE 路径
+    const envelopeBytes = await buildMediaEnvelopeBytes({
+      to: params.to,
+      fromId,
+      url: params.url,
+      mediaType: params.mediaType,
+      fileName: params.fileName,
+      fileSize: params.fileSize,
+      mimeType: params.mimeType,
+      width: params.width,
+      height: params.height,
+      caption: params.caption,
+      blurHash: params.blurHash,
+      fileKey: params.fileKey,
+      fileIv: params.fileIv,
+      fileDigest: params.fileDigest,
+      plaintextLength: params.plaintextLength,
+      expireTime: params.expireTime,
+      opCreds: params.opCreds,
+      length: params.length,
+      clientMsgId,
+    });
+    result = await encryptAndSendWithRetry(outbound, params.to, envelopeBytes, clientMsgId);
+  } else {
+    // 明文路径（E2EE 未初始化时的兼容回退）
+    const { sendMediaMessage } = await import('./api-client.js');
+    result = await sendMediaMessage(apiBaseUrl, auth, {
+      to: params.to,
+      fromId,
+      url: params.url,
+      mediaType: params.mediaType,
+      fileName: params.fileName,
+      fileSize: params.fileSize,
+      mimeType: params.mimeType,
+      width: params.width,
+      height: params.height,
+      caption: params.caption,
+      blurHash: params.blurHash,
+      clientMsgId,
+    });
+  }
+
+  // 成功时写入 recent-message-cache
+  if (result.ok && result.clientMsgId) {
+    ensureRecentMessageCachePersistence();
+    rememberRecentMessage(params.to, {
+      msgId: result.clientMsgId,
+      body: buildCachedOutboundBody(params.caption, '[media]'),
+      senderId: outbound.fromId,
+      timestampMs: Date.now(),
+    });
+  }
+
+  return result;
+}
+
+/**
+ * 基础层：向对端发送 typing signal。
+ * typing signal 按 R14 保持明文（不走 E2EE 加密），直接 encodeTypingSignalRequest + postProto。
+ */
+export async function sendTypingSignalToPeer(
+  outbound: OutboundContext,
+  params: { to: string; status: 1 | 2 },
+): Promise<ImweSendResponse> {
+  const { apiBaseUrl, auth, fromId } = outbound;
+  const botImAcctId = fromId; // botAcctId 同时用作 botImAcctId
+
+  // typing signal 保持明文，不走 E2EE
+  const requestBody = await encodeTypingSignalRequest(
+    params.to,
+    params.status,
+    botImAcctId,
+    fromId,
+  );
+
+  const responseBytes = await postProto(
+    apiBaseUrl,
+    '/api/im/open/bot/sendMessage',
+    requestBody,
+    auth,
+  );
+
+  return decodeSendResponse(responseBytes);
+}
+
+/**
+ * 基础层：向对端发送已读操作消息。
+ * 明文发送（e2eeFlag=false），envelopeType=2，与 typing signal 一致。
+ * 发送失败仅记录 warn 日志，不抛出异常（已读回执是辅助功能，丢失可接受）。
+ */
+export async function sendMsgReadToPeer(
+  outbound: OutboundContext,
+  params: { to: string; targetClientMsgIds: string[]; readStamp: number },
+): Promise<void> {
+  const { apiBaseUrl, auth, fromId, log } = outbound;
+  const prefix = `[send][${outbound.accountId}]`;
+
+  try {
+    const envelopeBytes = await buildMsgReadEnvelopeBytes({
+      targetClientMsgIds: params.targetClientMsgIds,
+      readStamp: params.readStamp,
+    });
+
+    const packetBytes = await encodeSingleChatReqPacket({
+      fromId,
+      to: params.to,
+      clientMsgId: genClientMsgId(),
+      envelopeBytes,
+      e2eeFlag: false,
+      envelopeType: 2,
+    });
+
+    await postProto(apiBaseUrl, '/api/im/open/bot/sendMessage', packetBytes, auth);
+    log?.info?.(
+      `${prefix}: msgRead 发送成功, to=${params.to}, clientMsgIds=${params.targetClientMsgIds.join(',')}`,
+    );
+  } catch (err) {
+    log?.warn?.(`${prefix}: msgRead 发送失败（不影响主流程）: ${String(err)}`);
+  }
+}
+
+// ─────────────────────────────────────────────────────────────────────────────
+// 顶层：sendImweText / sendImweMarkdown / sendImweMedia / sendImweTypingSignal
+// 保留既有签名，实现改为 resolveImweAccount + resolveFromId + 构造 OutboundContext → 委托基础层
+// ─────────────────────────────────────────────────────────────────────────────
+
+/**
+ * 构造 OutboundContext 的内部辅助。
+ * 解析账号 → 校验配置 → resolveFromId → 返回 OutboundContext 或错误。
+ */
+async function buildOutboundContext(params: {
+  accountId?: string;
+  cfg: OpenClawConfig;
+  log?: { info?: (...args: unknown[]) => void; warn?: (...args: unknown[]) => void };
+}): Promise<{ ctx?: OutboundContext; error?: string }> {
+  const account = resolveImweAccount({ cfg: params.cfg, accountId: params.accountId });
+
+  if (!account.appKey || !account.appSecret) {
+    return { error: 'imwe AppKey/AppSecret 未配置，请先运行 `openclaw setup imwe`。' };
+  }
+
+  if (!account.apiBaseUrl) {
+    return { error: 'imwe apiBaseUrl 未配置。' };
+  }
+
+  const auth = { apiKey: account.appKey, apiSecret: account.appSecret };
+  const fromId = await resolveFromId(account.accountId, account.apiBaseUrl, auth);
+
+  return {
+    ctx: {
+      apiBaseUrl: account.apiBaseUrl,
+      auth,
+      accountId: account.accountId,
+      fromId,
+      // e2eeService 由 channel.ts 在 startAccount 时注入到模块级缓存，
+      // 顶层入口通过 getE2eeServiceForAccount 获取（后续 9.2 任务实现）。
+      // 当前阶段先从全局缓存获取，若无则不走 E2EE。
+      e2eeService: getE2eeServiceForAccount(account.accountId),
+      log: params.log,
+    },
+  };
+}
+
+// ── E2EE Service 模块级缓存（由 channel.ts startAccount 注入） ──────────────
+
+const e2eeServiceCache = new Map<string, E2eeService>();
+
+/** 注册 E2EE Service 实例（由 channel.ts startAccount 调用） */
+export function registerE2eeService(accountId: string, service: E2eeService): void {
+  e2eeServiceCache.set(accountId, service);
+}
+
+/** 注销 E2EE Service 实例（由 channel.ts stopAccount 调用） */
+export function unregisterE2eeService(accountId: string): void {
+  e2eeServiceCache.delete(accountId);
+}
+
+/** 获取已注册的 E2EE Service 实例 */
+function getE2eeServiceForAccount(accountId: string): E2eeService | undefined {
+  return e2eeServiceCache.get(accountId);
+}
+
+export async function sendImweText(params: {
+  to: string;
+  text: string;
+  accountId?: string;
+  cfg: OpenClawConfig;
+  replyToId?: string;
+}): Promise<{ ok: boolean; messageId?: string; error?: string }> {
+  const { ctx, error } = await buildOutboundContext({
+    accountId: params.accountId,
+    cfg: params.cfg,
+  });
+  if (!ctx) return { ok: false, error };
+
+  try {
+    const result = await sendTextToPeer(ctx, {
+      to: params.to,
+      text: params.text,
+      replyToId: params.replyToId,
+    });
+    return { ok: result.ok, messageId: result.msgId, error: result.error };
+  } catch (err) {
+    return { ok: false, error: String(err) };
+  }
+}
+
+/**
+ * 发送 imwe typing signal 的统一入口。
+ *
+ * typing signal 发送失败不阻断主流程（由 createTypingCallbacks 的错误处理机制管理）。
+ */
+export async function sendImweTypingSignal(params: {
+  to: string;
+  status: 1 | 2;
+  accountId?: string;
+  cfg: OpenClawConfig;
+}): Promise<{ ok: boolean; error?: string }> {
+  const { ctx, error } = await buildOutboundContext({
+    accountId: params.accountId,
+    cfg: params.cfg,
+  });
+  if (!ctx) return { ok: false, error };
+
+  try {
+    const result = await sendTypingSignalToPeer(ctx, {
+      to: params.to,
+      status: params.status,
+    });
+    return { ok: result.ok, error: result.error };
+  } catch (err) {
+    return { ok: false, error: String(err) };
+  }
+}
+
+/**
+ * 发送已读操作消息的统一入口。
+ * 在插件回复用户消息成功后调用，标记用户原始消息为已读。
+ */
+export async function sendImweMsgRead(params: {
+  to: string;
+  targetClientMsgIds: string[];
+  readStamp: number;
+  accountId?: string;
+  cfg: OpenClawConfig;
+}): Promise<void> {
+  const { ctx, error } = await buildOutboundContext({
+    accountId: params.accountId,
+    cfg: params.cfg,
+  });
+  if (!ctx) {
+    return;
+  }
+
+  await sendMsgReadToPeer(ctx, {
+    to: params.to,
+    targetClientMsgIds: params.targetClientMsgIds,
+    readStamp: params.readStamp,
+  });
+}
+
+/**
+ * 发送 imwe 多媒体消息的统一入口。
+ *
+ * 顶层负责：解析账号 + 上传媒体 + 委托基础层发送。
+ */
+export async function sendImweMedia(params: {
+  to: string;
+  mediaUrl: string;
+  mediaType?: 'image' | 'video' | 'audio' | 'file';
+  fileName?: string;
+  caption?: string;
+  accountId?: string;
+  cfg: OpenClawConfig;
+  mediaAccess?: unknown;
+  mediaLocalRoots?: readonly string[];
+  mediaReadFile?: (filePath: string) => Promise<Buffer>;
+  /** 日志接口（可选，由调用方传入） */
+  log?: { info?: (...args: unknown[]) => void; warn?: (...args: unknown[]) => void };
+}): Promise<{ ok: boolean; messageId?: string; error?: string }> {
+  const { ctx, error } = await buildOutboundContext({
+    accountId: params.accountId,
+    cfg: params.cfg,
+    log: params.log,
+  });
+  if (!ctx) return { ok: false, error };
+
+  const log = params.log;
+  const tag = `[${ctx.accountId}]`;
+
+  log?.info?.(
+    `${tag} sendImweMedia 开始: to=${params.to}, mediaUrl=${params.mediaUrl}, mediaType=${params.mediaType ?? '(auto)'}`,
+  );
+
+  // 推断 mediaType（未指定时从 URL 后缀推断，默认 file）
+  const mediaType = params.mediaType ?? inferMediaType(params.mediaUrl);
+
+  // 使用 E2EE 加密分片上传
+  let uploadResult;
+  try {
+    uploadResult = await uploadEncryptedFile(params.mediaUrl, ctx.auth, ctx.apiBaseUrl, {
+      imMainAccId: params.to,
+      config: {
+        stateDir: path.join(resolveStateDir(), 'channel-data', 'imwe', ctx.fromId, 'file-transfer'),
+      },
+      sendContext: {
+        to: params.to,
+        fromId: ctx.fromId,
+        mediaType,
+        caption: params.caption,
+        fileName: params.fileName,
+      },
+      mediaLocalRoots: params.mediaLocalRoots,
+      mediaReadFile: params.mediaReadFile,
+      log,
+    });
+  } catch (err) {
+    log?.warn?.(`${tag} sendImweMedia 媒体上传失败: ${String(err)}`);
+    return { ok: false, error: `媒体上传失败: ${String(err)}` };
+  }
+
+  log?.info?.(
+    `${tag} sendImweMedia 上传完成, 准备发送: uploadUrl=${uploadResult.url}, mediaType=${mediaType}, fileSize=${uploadResult.plaintextLength}`,
+  );
+
+  try {
+    const result = await sendMediaToPeer(ctx, {
+      to: params.to,
+      url: uploadResult.url,
+      mediaType,
+      fileKey: uploadResult.fileKey,
+      fileIv: uploadResult.fileIv,
+      fileDigest: uploadResult.fileDigest,
+      plaintextLength: uploadResult.plaintextLength,
+      fileName: params.fileName,
+      fileSize: uploadResult.plaintextLength,
+      mimeType: uploadResult.contentType,
+      caption: params.caption,
+      blurHash: uploadResult.blurHash,
+      width: uploadResult.width,
+      height: uploadResult.height,
+      expireTime: uploadResult.expireTime,
+      opCreds: uploadResult.opCreds,
+      length: uploadResult.plaintextLength,
+    });
+    log?.info?.(
+      `${tag} sendImweMedia 发送完成: ok=${result.ok}, msgId=${result.msgId ?? '(none)'}`,
+    );
+    return { ok: result.ok, messageId: result.msgId, error: result.error };
+  } catch (err) {
+    log?.warn?.(`${tag} sendImweMedia 发送失败: ${String(err)}`);
+    return { ok: false, error: String(err) };
+  }
+}
+
+/**
+ * sendImweMarkdown 的入参校验 schema。
+ */
+export const MarkdownPayloadSchema = z.object({
+  to: z.string().trim().min(1, 'to 不能为空'),
+  markdown: z.string().min(1, 'markdown 内容不能为空'),
+  digest: z.string().max(256).optional(),
+});
+
+export type MarkdownPayload = z.infer<typeof MarkdownPayloadSchema>;
+
+/**
+ * 发送 imwe markdown 消息的统一入口。
+ *
+ * 与 sendImweText 行为对齐：
+ *   - 解析账号配置
+ *   - 获取 fromId
+ *   - 委托基础层 sendMarkdownToPeer 发送
+ *   - 支持 replyToId（与 sendImweText 对齐）
+ */
+export async function sendImweMarkdown(params: {
+  to: string;
+  markdown: string;
+  digest?: string;
+  replyToId?: string;
+  accountId?: string;
+  cfg: OpenClawConfig;
+}): Promise<{ ok: boolean; messageId?: string; error?: string }> {
+  // Step 1: zod 校验
+  const parsed = MarkdownPayloadSchema.safeParse({
+    to: params.to,
+    markdown: params.markdown,
+    digest: params.digest,
+  });
+  if (!parsed.success) {
+    const firstIssue = parsed.error.issues[0];
+    const errorMsg = firstIssue?.message ?? '参数校验失败';
+    return { ok: false, error: errorMsg };
+  }
+
+  // Step 2: 构造 OutboundContext
+  const { ctx, error } = await buildOutboundContext({
+    accountId: params.accountId,
+    cfg: params.cfg,
+  });
+  if (!ctx) return { ok: false, error };
+
+  // Step 3: 委托基础层
+  try {
+    const effectiveDigest = parsed.data.digest || extractMarkdownDigest(parsed.data.markdown);
+    const result = await sendMarkdownToPeer(ctx, {
+      to: parsed.data.to,
+      markdown: parsed.data.markdown,
+      replyToId: params.replyToId,
+      digest: effectiveDigest || undefined,
+    });
+    return { ok: result.ok, messageId: result.msgId, error: result.error };
+  } catch (err) {
+    return { ok: false, error: String(err) };
+  }
+}