@imweapp/openclaw-imwe 2026.4.12-alpha.1

package/src/proto/codec.ts

@@ -0,0 +1,54 @@
+/**
+ * codec.ts — Protobuf 编解码统一入口
+ *
+ * 基于 protobufjs 运行时动态加载 .proto 文件，无需代码生成步骤。
+ * .proto 文件（proto/ 目录）是唯一的结构定义来源，修改后重启进程即生效。
+ *
+ * 入站（inbound）解包链路：
+ *   decodeInboundPacket(packetBytes)
+ *     → PbPacket → PbRequest.body → PbChatMsgDeliverBody
+ *     → PbChatMsgEnvelope → PbChatTextContent
+ *     → InboundTextMessage（OpenClaw ctx 所需格式）
+ *
+ * 出站（outbound）编码链路：
+ *   encodeSendRequest(to, text)
+ *     → PbChatTextContent → PbChatMsgEnvelope → PbSingleChatMsgReqBody
+ *     → PbRequest → PbPacket → Uint8Array
+ *
+ * 所有公开函数均为 async，首次调用时触发 .proto 文件加载（约几毫秒），
+ * 后续调用使用缓存，无额外开销。
+ */
+
+// ── 入站：完整四层解包 ────────────────────────────────────────────────────────
+export { decodeInboundPacket } from './inbound.codec.js';
+export type {
+  InboundTextMessage,
+  InboundDecodeResult,
+  InboundDecodeSkip,
+  InboundAttachment,
+} from './inbound.codec.js';
+
+// ── 出站：发送消息编码 + 发送响应解码 ────────────────────────────────────────
+export {
+  genClientMsgId,
+  encodeSendRequest,
+  encodeTypingSignalRequest,
+  encodeMediaSendRequest,
+  encodeMarkdownSendRequest,
+  decodeSendResponse,
+} from './send.codec.js';
+export type { OutboundMediaParams, OutboundMarkdownParams } from './send.codec.js';
+
+// ── 类型注册表（供高级用途，如自定义解码场景） ────────────────────────────────
+export { getRegistry } from './registry.js';
+export type { ProtoRegistry } from './registry.js';
+
+// ── Proto 字段类型接口（供测试和类型断言使用） ────────────────────────────────
+export type {
+  DecodedPbPacket,
+  DecodedPbRequest,
+  DecodedDeliverBody,
+  DecodedChatMsgEnvelope,
+  DecodedTextContent,
+  DecodedBodyRange,
+} from './proto-types.js';

package/src/proto/inbound.codec.ts

@@ -0,0 +1,624 @@
+/**
+ * inbound.codec.ts — 入站消息完整解包
+ *
+ * 使用 protobufjs 运行时动态加载 .proto 文件进行解码，
+ * .proto 文件是唯一的结构定义来源（proto/ 目录）。
+ *
+ * 四层解包链路：
+ *
+ *   第1层  PbPacket（传输容器，PbPacket.proto）
+ *            ↓ type=SERVER_REQ(2) → request
+ *   第2层  PbRequest（请求体，PbPacket.proto）
+ *            ↓ body[bytes] 按 path 反序列化
+ *   第3层  PbChatMsgDeliverBody（统一投递体，PbChatDeliverMsg.proto）
+ *            ↓ envelope[bytes] 按 envelopeType 反序列化
+ *   第4层  PbChatMsgEnvelope（信封，PbChatMsg.proto）
+ *            ↓ oneof textContent（字段3）
+ *          PbChatTextContent（文本内容，PbChatTextContent.proto）
+ *
+ * 当前处理：
+ *   - envelopeType=1（聊天消息信封）
+ *   - textContent（文本消息，oneof 字段 3）
+ *   - richMediaContent（图片/视频消息，oneof 字段 9）
+ *   - fileContent（文件消息，oneof 字段 13）
+ *   - audioContent（音频消息，oneof 字段 4）
+ * 其他类型返回 skip，由 monitor.ts 跳过。
+ */
+
+import { getRegistry } from './registry.js';
+import type {
+  DecodedPbPacket,
+  DecodedDeliverBody,
+  DecodedChatMsgEnvelope,
+  DecodedBodyRange,
+  DecodedRichMediaContent,
+  DecodedAudioContent,
+  DecodedFileMeta,
+} from './proto-types.js';
+import type { ImweInboundMessage } from '../types.js';
+
+// ─────────────────────────────────────────────────────────────────────────────
+// 常量
+// ─────────────────────────────────────────────────────────────────────────────
+
+/** PbType 枚举值（对应 PbPacket.proto） */
+const PB_TYPE_SERVER_REQ = 2;
+
+/** 信封类型枚举值（对应 PbChatDeliverMsg.proto envelopeType 字段注释） */
+const ENVELOPE_TYPE_CHAT = 1;
+
+// ─────────────────────────────────────────────────────────────────────────────
+// 附件类型
+// ─────────────────────────────────────────────────────────────────────────────
+
+/** 入站消息附件（从 protobuf 解码后的标准化结构） */
+export type InboundAttachment = {
+  /** 附件类型：image / video / audio / file */
+  type: 'image' | 'video' | 'audio' | 'file';
+  /** 文件下载 URL（来自 PbChatFileMeta.url） */
+  url: string;
+  /** 文件 MIME 类型（从 fileType 推断） */
+  mimeType?: string;
+  /** 文件名 */
+  fileName?: string;
+  /** 文件大小（字节） */
+  fileSize?: number;
+  /** 图片/视频宽度（像素） */
+  width?: number;
+  /** 图片/视频高度（像素） */
+  height?: number;
+  /** 音频/视频时长（秒） */
+  duration?: number;
+  /** 图片/视频文字描述 */
+  caption?: string;
+  /** AES-256 文件加密密钥（32 字节，E2EE 文件传输时存在） */
+  fileKey?: Uint8Array;
+  /** AES-CTR 初始向量（16 字节，E2EE 文件传输时存在） */
+  fileIv?: Uint8Array;
+  /** SHA256(plaintext) 小写十六进制摘要 */
+  fileDigest?: string;
+  /** 明文长度（字节） */
+  plaintextLength?: number;
+  /** 操作凭证（下载回调用） */
+  opCreds?: string;
+};
+
+// ─────────────────────────────────────────────────────────────────────────────
+// PbChatFileMetaType 枚举映射
+// ─────────────────────────────────────────────────────────────────────────────
+
+/**
+ * 将 PbChatFileMetaType 枚举值映射为 TypeScript 字符串类型。
+ * 0=UNKNOWN→file, 1=IMAGE→image, 2=VIDEO→video, 3=AUDIO→audio, 4=FILE→file
+ * 未知值安全回退为 'file'。
+ */
+export function mapFileMetaType(protoType: number): 'image' | 'video' | 'audio' | 'file' {
+  switch (protoType) {
+    case 1:
+      return 'image';
+    case 2:
+      return 'video';
+    case 3:
+      return 'audio';
+    default:
+      return 'file';
+  }
+}
+
+// ─────────────────────────────────────────────────────────────────────────────
+// 解包结果类型
+// ─────────────────────────────────────────────────────────────────────────────
+
+/** 解包成功，得到文本消息 */
+export type InboundTextMessage = ImweInboundMessage & {
+  /** 服务端消息 ID（用于 ACK） */
+  serverMsgId: string;
+  /** 会话类型：1=P2P 单聊，2=CHATROOM 群聊（对应 PbContactType） */
+  convType: number;
+  /** 接收方 ID（单聊=账户ID，群聊=群组ID） */
+  toId: string;
+};
+
+/** 解包失败或不支持的消息类型，由调用方决定是否记录日志 */
+export type InboundDecodeSkip = {
+  reason:
+    | 'not-server-req' // PbPacket.type 不是 SERVER_REQ
+    | 'no-body' // PbRequest.body 为空
+    | 'unsupported-envelope-type' // envelopeType 不是 1（聊天消息）
+    | 'unsupported-content-type' // oneof 不是 textContent（非文本消息）
+    | 'empty-envelope'; // envelope 字节为空
+  detail?: string;
+};
+
+export type InboundDecodeResult =
+  | { ok: true; message: InboundTextMessage }
+  | { ok: false; skip: InboundDecodeSkip };
+
+// ─────────────────────────────────────────────────────────────────────────────
+// 多媒体内容解码辅助函数
+// ─────────────────────────────────────────────────────────────────────────────
+
+/**
+ * 当 fileMeta.mediaType 为 UNKNOWN(0) 或缺失时，从 MIME type 或 URL 后缀辅助判断媒体类型。
+ * 无法判断时回退到调用方指定的 defaultType。
+ */
+function guessMediaTypeFallback(
+  fileMeta: DecodedFileMeta,
+  defaultType: 'image' | 'video' | 'file',
+): 'image' | 'video' | 'audio' | 'file' {
+  // MIME type 辅助判断
+  if (fileMeta.fileType) {
+    if (fileMeta.fileType.startsWith('video/')) return 'video';
+    if (fileMeta.fileType.startsWith('image/')) return 'image';
+    if (fileMeta.fileType.startsWith('audio/')) return 'audio';
+  }
+  // URL 后缀辅助判断
+  if (fileMeta.url) {
+    const lower = fileMeta.url.toLowerCase().split('?')[0];
+    if (/\.(mp4|mov|avi|mkv|webm|flv)$/.test(lower)) return 'video';
+    if (/\.(jpe?g|png|gif|webp|bmp|svg|heic|heif)$/.test(lower)) return 'image';
+    if (/\.(mp3|wav|ogg|aac|m4a|flac|opus|amr)$/.test(lower)) return 'audio';
+  }
+  return defaultType;
+}
+
+/**
+ * 从 DecodedFileMeta 中提取 E2EE 文件加密相关字段。
+ * key/iv 为空（长度为 0）时视为不存在，返回 undefined（向后兼容）。
+ */
+function extractFileEncryptionFields(
+  fileMeta: DecodedFileMeta,
+): Pick<InboundAttachment, 'fileKey' | 'fileIv' | 'fileDigest' | 'plaintextLength' | 'opCreds'> {
+  const fileKey = fileMeta.key && fileMeta.key.length > 0 ? fileMeta.key : undefined;
+  const fileIv = fileMeta.iv && fileMeta.iv.length > 0 ? fileMeta.iv : undefined;
+  const fileDigest = fileMeta.digest || undefined;
+  const plaintextLength =
+    fileMeta.plaintextLength != null && Number(fileMeta.plaintextLength) > 0
+      ? Number(fileMeta.plaintextLength)
+      : undefined;
+  const opCreds = fileMeta.opCreds || undefined;
+
+  return {
+    ...(fileKey ? { fileKey } : {}),
+    ...(fileIv ? { fileIv } : {}),
+    ...(fileDigest ? { fileDigest } : {}),
+    ...(plaintextLength != null ? { plaintextLength } : {}),
+    ...(opCreds ? { opCreds } : {}),
+  };
+}
+
+/**
+ * 从 DecodedRichMediaContent 提取 InboundAttachment 数组。
+ * 过滤掉无 fileMeta 或 fileMeta.url 为空的条目。
+ *
+ * @param content 解码后的富媒体内容
+ * @param defaultType 默认附件类型（当 fileMeta.mediaType 为 0/UNKNOWN 时使用）
+ */
+function decodeRichMediaContent(
+  content: DecodedRichMediaContent,
+  defaultType: 'image' | 'video' | 'file',
+): InboundAttachment[] {
+  const attachments: InboundAttachment[] = [];
+  for (const meta of content.meta) {
+    if (!meta.fileMeta || !meta.fileMeta.url) continue;
+
+    const mapped = mapFileMetaType(meta.fileMeta.mediaType);
+    // 当映射结果为 'file'（即 UNKNOWN/FILE）时，尝试从 MIME type 或 URL 后缀辅助判断
+    const type = mapped === 'file' ? guessMediaTypeFallback(meta.fileMeta, defaultType) : mapped;
+
+    attachments.push({
+      type,
+      url: meta.fileMeta.url,
+      ...(meta.fileMeta.fileType ? { mimeType: meta.fileMeta.fileType } : {}),
+      ...(meta.fileName ? { fileName: meta.fileName } : {}),
+      ...(meta.fileSize != null ? { fileSize: Number(meta.fileSize) } : {}),
+      ...(meta.width != null ? { width: Number(meta.width) } : {}),
+      ...(meta.height != null ? { height: Number(meta.height) } : {}),
+      ...(meta.duration != null ? { duration: Number(meta.duration) } : {}),
+      ...((meta.caption ?? content.caption) ? { caption: meta.caption ?? content.caption } : {}),
+      ...extractFileEncryptionFields(meta.fileMeta),
+    });
+  }
+  return attachments;
+}
+
+/**
+ * 从 DecodedAudioContent 提取单个 InboundAttachment。
+ * 若 meta 或 fileMeta.url 为空则返回 null。
+ */
+function decodeAudioContent(content: DecodedAudioContent): InboundAttachment | null {
+  if (!content.meta?.fileMeta?.url) return null;
+
+  return {
+    type: 'audio',
+    url: content.meta.fileMeta.url,
+    ...(content.meta.fileMeta.fileType ? { mimeType: content.meta.fileMeta.fileType } : {}),
+    ...(content.meta.duration != null ? { duration: Number(content.meta.duration) } : {}),
+    ...extractFileEncryptionFields(content.meta.fileMeta),
+  };
+}
+
+// ─────────────────────────────────────────────────────────────────────────────
+// 主解包函数
+// ─────────────────────────────────────────────────────────────────────────────
+
+/**
+ * 将平台推送的 PbPacket 二进制四层解包为 OpenClaw 可用的消息对象。
+ *
+ * 首次调用时会触发 .proto 文件加载（约几毫秒），后续调用使用缓存。
+ *
+ * @param packetBytes 平台推送的原始 protobuf 二进制（最外层 PbPacket）
+ * @returns 解包结果：成功返回 InboundTextMessage，失败返回跳过原因
+ */
+export async function decodeInboundPacket(packetBytes: Uint8Array): Promise<InboundDecodeResult> {
+  const reg = await getRegistry();
+
+  // ── 第1层：PbPacket.decode() ──────────────────────────────────────────────
+  const packet = reg.PbPacket.decode(packetBytes) as unknown as DecodedPbPacket;
+
+  if (packet.type !== PB_TYPE_SERVER_REQ || !packet.request) {
+    return {
+      ok: false,
+      skip: { reason: 'not-server-req', detail: `type=${packet.type}` },
+    };
+  }
+
+  // ── 第2层：PbChatMsgDeliverBody.decode(PbRequest.body) ───────────────────
+  const body = packet.request.body;
+  if (!body || body.length === 0) {
+    return {
+      ok: false,
+      skip: { reason: 'no-body', detail: `path=${packet.request.path}` },
+    };
+  }
+
+  const deliver = reg.PbChatMsgDeliverBody.decode(body) as unknown as DecodedDeliverBody;
+
+  // 只处理聊天消息信封（envelopeType=1）
+  if (Number(deliver.envelopeType) !== ENVELOPE_TYPE_CHAT) {
+    return {
+      ok: false,
+      skip: {
+        reason: 'unsupported-envelope-type',
+        detail: `envelopeType=${deliver.envelopeType}`,
+      },
+    };
+  }
+
+  // ── 第3层：PbChatMsgEnvelope.decode(envelope) ────────────────────────────
+  if (!deliver.envelope || deliver.envelope.length === 0) {
+    return { ok: false, skip: { reason: 'empty-envelope' } };
+  }
+
+  const envelope = reg.PbChatMsgEnvelope.decode(
+    deliver.envelope,
+  ) as unknown as DecodedChatMsgEnvelope;
+
+  // ── 第4层：oneof 内容分支 ─────────────────────────────────────────────────
+  // protobufjs 对 oneof 的处理：只有当前激活的字段有值，其余为 undefined
+
+  if (envelope.textContent) {
+    // ── 文本消息（字段3）────────────────────────────────────────────────────
+    const textContent = envelope.textContent;
+    const bodyRanges = textContent.bodyRanges ?? [];
+
+    const message: InboundTextMessage = {
+      msgId: deliver.clientMsgId,
+      senderId: deliver.fromId,
+      content: textContent.text,
+      timestampMs: Number(deliver.serverStamp),
+      serverMsgId: deliver.serverMsgId,
+      convType: deliver.convType,
+      toId: deliver.toId,
+      ...(bodyRanges.length > 0
+        ? {
+            bodyRanges: bodyRanges.map((r) => ({
+              key: r.key as 0 | 1 | 2,
+              payload: r.payload,
+              ...(r.start !== undefined ? { start: r.start } : {}),
+              ...(r.length !== undefined ? { length: r.length } : {}),
+            })),
+          }
+        : {}),
+      ...(textContent.referenceClientMsgId
+        ? { referenceClientMsgId: textContent.referenceClientMsgId }
+        : {}),
+    };
+
+    return { ok: true, message };
+  }
+
+  if (envelope.richMediaContent) {
+    // ── 图片/视频消息（字段9）──────────────────────────────────────────────
+    const attachments = decodeRichMediaContent(envelope.richMediaContent, 'image');
+    const message: InboundTextMessage = {
+      msgId: deliver.clientMsgId,
+      senderId: deliver.fromId,
+      content: envelope.richMediaContent.caption ?? '',
+      timestampMs: Number(deliver.serverStamp),
+      serverMsgId: deliver.serverMsgId,
+      convType: deliver.convType,
+      toId: deliver.toId,
+      ...(attachments.length > 0 ? { attachments } : {}),
+    };
+    return { ok: true, message };
+  }
+
+  if (envelope.fileContent) {
+    // ── 文件消息（字段13，结构同 richMediaContent）─────────────────────────
+    const attachments = decodeRichMediaContent(envelope.fileContent, 'file');
+    const message: InboundTextMessage = {
+      msgId: deliver.clientMsgId,
+      senderId: deliver.fromId,
+      content: envelope.fileContent.caption ?? '',
+      timestampMs: Number(deliver.serverStamp),
+      serverMsgId: deliver.serverMsgId,
+      convType: deliver.convType,
+      toId: deliver.toId,
+      ...(attachments.length > 0 ? { attachments } : {}),
+    };
+    return { ok: true, message };
+  }
+
+  if (envelope.audioContent) {
+    // ── 音频消息（字段4）──────────────────────────────────────────────────
+    const attachment = decodeAudioContent(envelope.audioContent);
+    const attachments = attachment ? [attachment] : [];
+    const message: InboundTextMessage = {
+      msgId: deliver.clientMsgId,
+      senderId: deliver.fromId,
+      content: envelope.audioContent.speech ?? '',
+      timestampMs: Number(deliver.serverStamp),
+      serverMsgId: deliver.serverMsgId,
+      convType: deliver.convType,
+      toId: deliver.toId,
+      ...(attachments.length > 0 ? { attachments } : {}),
+    };
+    return { ok: true, message };
+  }
+
+  return {
+    ok: false,
+    skip: {
+      reason: 'unsupported-content-type',
+      detail: 'no known oneof field present in envelope',
+    },
+  };
+}
+
+// ─────────────────────────────────────────────────────────────────────────────
+// E2EE 分叉：decodeInboundPacketWithE2ee（task 6.3 / 6.4）
+//
+// 在原 decodeInboundPacket 基础上追加 e2eeFlag 的分叉处理：
+//   - e2eeFlag=false → 走原明文路径
+//   - e2eeFlag=true  → 校验 toE2eeId == local.e2eeId，然后调 e2eeDecrypt 回调；
+//     回调返回明文字节后替换 deliver.envelope 再走原解码流程；返回 null →
+//     skip: 'decrypt-failed'；envelopeType=2 的操作消息由 service 内部分发 →
+//     skip: 'operation-consumed'
+//
+// 模块边界约束（requirement R12）：
+//   本文件顶层不得 import `../vodozemackit` 或 `src/e2ee/*`，只通过注入的
+//   e2eeDecrypt 回调访问 E2EE 能力。
+// ─────────────────────────────────────────────────────────────────────────────
+
+/** e2eeDecrypt 回调的入参，由 E2eeService 在 monitor 层注入 */
+export interface E2eeDecryptParams {
+  fromId: string;
+  fromE2eeId: string;
+  toE2eeId: string;
+  e2eeSid: string;
+  encryptedBody: Uint8Array;
+  clientMsgId: string;
+  envelopeType: number;
+}
+
+/** e2eeDecrypt 回调：成功返回明文字节，失败返回 null（由 service 内部处理反向信令） */
+export type E2eeDecryptFn = (params: E2eeDecryptParams) => Promise<Uint8Array | null>;
+
+/** E2EE 分叉特有的 skip 原因 */
+export type InboundE2eeSkipReason =
+  | 'decrypt-failed' // e2eeDecrypt 回调返回 null
+  | 'toE2eeId-mismatch' // 目标设备不是本端
+  | 'operation-consumed' // envelopeType=2 的操作消息，由 service 内部消费
+  | 'missing-e2ee-fields'; // e2eeFlag=true 但缺 fromE2eeId/toE2eeId/e2eeSid
+
+/** 带 E2EE 解密回调的解包结果 */
+export type InboundE2eeDecodeResult =
+  | { ok: true; message: InboundTextMessage }
+  | { ok: false; skip: InboundDecodeSkip | { reason: InboundE2eeSkipReason; detail?: string } };
+
+const ENVELOPE_TYPE_OPERATION = 2;
+
+/**
+ * 将平台推送的 PbPacket 二进制四层解包（E2EE 版）。
+ *
+ * 与 decodeInboundPacket 的差异：
+ *   - 在 decoding deliver body 后按 `deliver.e2eeFlag` 分叉
+ *   - e2eeFlag=true 时注入的 `e2eeDecrypt` 回调返回明文字节后继续走原解码流程
+ *
+ * @param packetBytes 平台推送的原始 protobuf 二进制
+ * @param opts.e2eeDecrypt 必填回调；由 E2eeService.decryptSingle 适配
+ */
+export async function decodeInboundPacketWithE2ee(
+  packetBytes: Uint8Array,
+  opts: { e2eeDecrypt: E2eeDecryptFn },
+): Promise<InboundE2eeDecodeResult> {
+  const reg = await getRegistry();
+
+  // ── 第1层：PbPacket.decode() ──────────────────────────────────────────────
+  const packet = reg.PbPacket.decode(packetBytes) as unknown as DecodedPbPacket;
+
+  if (packet.type !== PB_TYPE_SERVER_REQ || !packet.request) {
+    return { ok: false, skip: { reason: 'not-server-req', detail: `type=${packet.type}` } };
+  }
+
+  // ── 第2层：PbChatMsgDeliverBody.decode(PbRequest.body) ───────────────────
+  const body = packet.request.body;
+  if (!body || body.length === 0) {
+    return { ok: false, skip: { reason: 'no-body', detail: `path=${packet.request.path}` } };
+  }
+
+  const deliver = reg.PbChatMsgDeliverBody.decode(body) as unknown as DecodedDeliverBody;
+
+  // ── E2EE 分叉：e2eeFlag=false 走原路径 ───────────────────────────────────
+  if (!deliver.e2eeFlag) {
+    // 明文路径：等同于 decodeInboundPacket 的后续流程
+    return decodeInboundPacketPlaintextTail(reg, deliver);
+  }
+
+  // ── E2EE 分叉：e2eeFlag=true ────────────────────────────────────────────
+  // 校验必需字段
+  if (!deliver.fromE2eeId || !deliver.toE2eeId || !deliver.e2eeSid) {
+    return {
+      ok: false,
+      skip: {
+        reason: 'missing-e2ee-fields',
+        detail: `fromE2eeId=${!!deliver.fromE2eeId}, toE2eeId=${!!deliver.toE2eeId}, e2eeSid=${!!deliver.e2eeSid}`,
+      },
+    };
+  }
+
+  if (!deliver.envelope || deliver.envelope.length === 0) {
+    return { ok: false, skip: { reason: 'empty-envelope' } };
+  }
+
+  // 调用注入的 e2eeDecrypt 回调；回调内部负责：
+  //   - toE2eeId 与 local.e2eeId 的匹配校验
+  //   - 解密失败时构造 decryptError 信令、打标 session.staleAt
+  //   - 解密成功返回明文字节；失败返回 null
+  const plainBytes = await opts.e2eeDecrypt({
+    fromId: deliver.fromId,
+    fromE2eeId: deliver.fromE2eeId,
+    toE2eeId: deliver.toE2eeId,
+    e2eeSid: deliver.e2eeSid,
+    encryptedBody: deliver.envelope,
+    clientMsgId: deliver.clientMsgId,
+    envelopeType: Number(deliver.envelopeType),
+  });
+
+  if (plainBytes === null) {
+    return { ok: false, skip: { reason: 'decrypt-failed' } };
+  }
+
+  // envelopeType=2：操作信令（如 decryptError / botThinking），由 E2eeService
+  // 的 dispatchOperation 内部消费（service 会从回调内部调用 dispatchOperation
+  // 或上层再分派）；codec 层返回 operation-consumed。
+  if (Number(deliver.envelopeType) === ENVELOPE_TYPE_OPERATION) {
+    return { ok: false, skip: { reason: 'operation-consumed' } };
+  }
+
+  // 将解密后的明文字节替换 deliver.envelope，走原明文解码尾部流程
+  const decryptedDeliver: DecodedDeliverBody = { ...deliver, envelope: plainBytes };
+  return decodeInboundPacketPlaintextTail(reg, decryptedDeliver);
+}
+
+/**
+ * 从 DecodedDeliverBody 继续 `decodeInboundPacket` 的第 3~4 层解码流程。
+ *
+ * 明文路径与 E2EE 解密后复用同一尾部：envelopeType=1 → PbChatMsgEnvelope
+ * → oneof 分支 → InboundTextMessage；其他 envelopeType / oneof 返回 skip。
+ */
+async function decodeInboundPacketPlaintextTail(
+  reg: Awaited<ReturnType<typeof getRegistry>>,
+  deliver: DecodedDeliverBody,
+): Promise<InboundDecodeResult> {
+  if (Number(deliver.envelopeType) !== ENVELOPE_TYPE_CHAT) {
+    return {
+      ok: false,
+      skip: {
+        reason: 'unsupported-envelope-type',
+        detail: `envelopeType=${deliver.envelopeType}`,
+      },
+    };
+  }
+
+  if (!deliver.envelope || deliver.envelope.length === 0) {
+    return { ok: false, skip: { reason: 'empty-envelope' } };
+  }
+
+  const envelope = reg.PbChatMsgEnvelope.decode(
+    deliver.envelope,
+  ) as unknown as DecodedChatMsgEnvelope;
+
+  if (envelope.textContent) {
+    const textContent = envelope.textContent;
+    const bodyRanges = textContent.bodyRanges ?? [];
+    const message: InboundTextMessage = {
+      msgId: deliver.clientMsgId,
+      senderId: deliver.fromId,
+      content: textContent.text,
+      timestampMs: Number(deliver.serverStamp),
+      serverMsgId: deliver.serverMsgId,
+      convType: deliver.convType,
+      toId: deliver.toId,
+      ...(bodyRanges.length > 0
+        ? {
+            bodyRanges: bodyRanges.map((r) => ({
+              key: r.key as 0 | 1 | 2,
+              payload: r.payload,
+              ...(r.start !== undefined ? { start: r.start } : {}),
+              ...(r.length !== undefined ? { length: r.length } : {}),
+            })),
+          }
+        : {}),
+      ...(textContent.referenceClientMsgId
+        ? { referenceClientMsgId: textContent.referenceClientMsgId }
+        : {}),
+    };
+    return { ok: true, message };
+  }
+
+  if (envelope.richMediaContent) {
+    const attachments = decodeRichMediaContent(envelope.richMediaContent, 'image');
+    const message: InboundTextMessage = {
+      msgId: deliver.clientMsgId,
+      senderId: deliver.fromId,
+      content: envelope.richMediaContent.caption ?? '',
+      timestampMs: Number(deliver.serverStamp),
+      serverMsgId: deliver.serverMsgId,
+      convType: deliver.convType,
+      toId: deliver.toId,
+      ...(attachments.length > 0 ? { attachments } : {}),
+    };
+    return { ok: true, message };
+  }
+
+  if (envelope.fileContent) {
+    const attachments = decodeRichMediaContent(envelope.fileContent, 'file');
+    const message: InboundTextMessage = {
+      msgId: deliver.clientMsgId,
+      senderId: deliver.fromId,
+      content: envelope.fileContent.caption ?? '',
+      timestampMs: Number(deliver.serverStamp),
+      serverMsgId: deliver.serverMsgId,
+      convType: deliver.convType,
+      toId: deliver.toId,
+      ...(attachments.length > 0 ? { attachments } : {}),
+    };
+    return { ok: true, message };
+  }
+
+  if (envelope.audioContent) {
+    const attachment = decodeAudioContent(envelope.audioContent);
+    const attachments = attachment ? [attachment] : [];
+    const message: InboundTextMessage = {
+      msgId: deliver.clientMsgId,
+      senderId: deliver.fromId,
+      content: envelope.audioContent.speech ?? '',
+      timestampMs: Number(deliver.serverStamp),
+      serverMsgId: deliver.serverMsgId,
+      convType: deliver.convType,
+      toId: deliver.toId,
+      ...(attachments.length > 0 ? { attachments } : {}),
+    };
+    return { ok: true, message };
+  }
+
+  return {
+    ok: false,
+    skip: {
+      reason: 'unsupported-content-type',
+      detail: 'no known oneof field present in envelope',
+    },
+  };
+}