openbird 1.0.0

package/src/core/builders/proto.js

@@ -0,0 +1,4432 @@
+/**
+ * Protocol Buffers builder for Feishu API
+ * Uses pre-generated code from protoc-gen-es
+ */
+
+import logger from '../../logger.js';
+
+import {
+  FrameSchema,
+  PacketSchema,
+  PushMessagesRequestSchema,
+  PutMessageRequestSchema,
+  PutChatRequestSchema,
+  PutChatResponseSchema,
+  UniversalSearchRequestSchema,
+  UniversalSearchResponseSchema,
+  ContentSchema,
+  TextPropertySchema,
+  entities_MessageSchema,
+  ImageContentSchema,
+  ImageSetSchema,
+  ImageSetV2Schema,
+  ImageSchema,
+  CryptoSchema,
+  CipherSchema,
+  RichTextSchema,
+  RichTextElementsSchema,
+  RichTextElementSchema,
+  GetChatHistoryRequestSchema,
+  GetChatHistoryResponseSchema,
+  ChatSchema,
+  PushGroupMessageReadStateNoticeSchema,
+  PushDeviceOnlineStatusSchema,
+  DeviceOnlineStatus_TerminalType,
+  DeviceOnlineStatus_OnlineStatus,
+} from '../proto/proto_pb.js';
+import { create, protoInt64, toBinary, fromBinary } from '@bufbuild/protobuf';
+import { generateRequestCid } from '../utils/encryption.js';
+import { buildRichText, hasMarkdownFormatting } from './richtext.js';
+import { pushVarintLength } from '../utils/varint.js';
+
+// 消息类型常量 (aligned with entities.Message.Type enum in proto)
+export const MESSAGE_TYPES = {
+  2: 'POST',              // 富文本/图文混合
+  3: 'FILE',              // 文件
+  4: 'TEXT',              // 纯文本
+  5: 'IMAGE',             // 图片
+  6: 'SYSTEM',            // 系统消息
+  7: 'AUDIO',             // 音频
+  8: 'EMAIL',             // 邮件
+  9: 'SHARE_GROUP_CHAT',  // 分享群聊
+  10: 'STICKER',          // 表情
+  11: 'MERGE_FORWARD',    // 合并转发
+  12: 'CALENDAR',         // 日历
+  13: 'CLOUD_FILE',       // 云文件
+  14: 'CARD',             // 卡片消息
+  15: 'MEDIA',            // 媒体
+  16: 'SHARE_CALENDAR_EVENT',
+  17: 'HONGBAO',          // 红包
+  18: 'GENERAL_CALENDAR',
+  19: 'VIDEO_CHAT',       // 视频通话
+  20: 'LOCATION',         // 位置
+  22: 'COMMERCIALIZED_HONGBAO',
+  23: 'SHARE_USER_CARD',  // 名片分享
+  24: 'TODO',             // 待办
+  25: 'FOLDER',           // 文件夹
+};
+
+// 发送者类型常量 (entities.FromType)
+export const FROM_TYPES = {
+  0: 'UNKNOWN',
+  1: 'USER',      // 真人用户
+  2: 'BOT',       // 机器人
+};
+
+// 聊天类型常量 (entities.ChatType)
+export const CHAT_TYPES = {
+  0: 'UNKNOWN',
+  1: 'P2P',           // 私聊/单聊
+  2: 'GROUP',         // 普通群聊
+  3: 'TOPIC_GROUP',   // 话题群聊
+};
+
+// WS 推送事件 cmd 类型
+export const PUSH_CMD_TYPES = {
+  6: 'PUSH_MESSAGE',
+  48: 'PUSH_CHAT_CHATTERS',
+  49: 'PUSH_CHAT_MUTABLE_INFO',
+  74: 'PUSH_GROUP_READ_STATE',
+  77: 'MULTI_PACKETS',
+  8106: 'PUSH_THREAD_READ_STATE',
+  7001: 'PUSH_DEVICE_ONLINE_STATUS',
+  7017: 'PUSH_DEVICE_NETWORK_EVENT',
+  7032: 'PUSH_THREE_COLUMNS_SETTING',
+};
+
+/**
+ * 获取发送者类型名称
+ * @param {number} type - 发送者类型数字
+ * @returns {string} 类型名称
+ */
+export function getFromTypeName(type) {
+  return FROM_TYPES[type] || `UNKNOWN(${type})`;
+}
+
+/**
+ * 获取聊天类型名称
+ * @param {number} type - 聊天类型数字
+ * @returns {string} 类型名称
+ */
+export function getChatTypeName(type) {
+  return CHAT_TYPES[type] || `UNKNOWN(${type})`;
+}
+
+/**
+ * 获取消息类型名称
+ * @param {number} type - 消息类型数字
+ * @returns {string} 类型名称
+ */
+export function getMessageTypeName(type) {
+  return MESSAGE_TYPES[type] || `UNKNOWN(${type})`;
+}
+
+// 图片加密信息缓存 (imageKey -> cryptoInfo)
+const imageCryptoCache = new Map();
+
+// 缓存过期时间 (24小时)
+const CACHE_EXPIRY_MS = 24 * 60 * 60 * 1000;
+
+/**
+ * 获取缓存的图片加密信息
+ * @param {string} imageKey - 图片 key
+ * @returns {Object|null} 加密信息 { secret, nonce, additionalData, type } 或 null
+ */
+export function getImageCryptoInfo(imageKey) {
+  const cached = imageCryptoCache.get(imageKey);
+  if (cached && Date.now() - cached.timestamp < CACHE_EXPIRY_MS) {
+    return cached.cryptoInfo;
+  }
+  // 清除过期缓存
+  if (cached) {
+    imageCryptoCache.delete(imageKey);
+  }
+  return null;
+}
+
+/**
+ * 缓存图片加密信息
+ * @param {string} imageKey - 图片 key
+ * @param {Object} cryptoInfo - 加密信息 { secret, nonce, additionalData, type }
+ */
+function cacheImageCryptoInfo(imageKey, cryptoInfo) {
+  imageCryptoCache.set(imageKey, {
+    cryptoInfo,
+    timestamp: Date.now()
+  });
+}
+
+class ProtoBuilder {
+  /**
+   * Build protobuf message for sending text
+   * @param {string} text - Text content to send
+   * @param {string} requestId - Request ID
+   * @param {string} chatId - Chat ID
+   * @returns {Buffer} Serialized protobuf message
+   */
+  static buildSendMessageRequest(text, requestId, chatId) {
+    const cid1 = generateRequestCid();
+    const cid2 = generateRequestCid();
+
+    // Build TextProperty
+    const textProperty = create(TextPropertySchema, {
+      content: text
+    });
+
+    // Build Content with RichText (嵌套消息对象，不要序列化)
+    const content = create(ContentSchema, {
+      text: text,
+      richText: {
+        elementIds: [cid2],
+        innerText: text,
+        elements: {
+          dictionary: {
+            [cid2]: {
+              tag: 1, // TEXT
+              property: toBinary(TextPropertySchema, textProperty)
+            }
+          }
+        }
+      }
+    });
+
+    // Build PutMessageRequest
+    // 注意：content 是 Content 类型的嵌套消息，直接传对象，不要序列化为 bytes
+    const payload = create(PutMessageRequestSchema, {
+      type: 4, // TEXT
+      chatId: chatId,
+      cid: cid1,
+      isNotified: true,
+      version: 1,
+      content: content  // 直接传 Content 对象，不是 toBinary(...)
+    });
+
+    // Build outer Packet
+    const packet = create(PacketSchema, {
+      payloadType: 1, // PB2
+      cmd: 5,
+      cid: requestId,
+      payload: toBinary(PutMessageRequestSchema, payload)
+    });
+
+    return Buffer.from(toBinary(PacketSchema, packet));
+  }
+
+  /**
+   * Build protobuf message for sending rich text (Markdown supported)
+   * @param {string} text - Text content with optional Markdown formatting
+   * @param {string} requestId - Request ID
+   * @param {string} chatId - Chat ID
+   * @param {Object} options - Options
+   * @param {boolean} options.parseMarkdown - Whether to parse Markdown (default: true)
+   * @returns {Buffer} Serialized protobuf message
+   */
+  static buildRichMessageRequest(text, requestId, chatId, options = {}) {
+    const { parseMarkdown = true } = options;
+    const cid1 = generateRequestCid();
+
+    let richTextResult;
+    let innerText;
+    let isBlockLevel = false;
+
+    if (parseMarkdown && hasMarkdownFormatting(text)) {
+      richTextResult = buildRichText(text);
+      innerText = richTextResult.innerText;
+      isBlockLevel = richTextResult.isBlockLevel || false;
+    } else {
+      // Plain text - use manual building too for consistency
+      richTextResult = buildRichText(text);
+      innerText = richTextResult.innerText;
+    }
+
+    // Build Content bytes manually for block-level elements
+    // to ensure proper dictionary serialization
+    const contentBytes = this.buildContentBytes(
+      isBlockLevel ? '' : innerText,
+      richTextResult.elementIds,
+      innerText,
+      richTextResult.dictionaryBytes
+    );
+
+    // Build PutMessageRequest manually
+    const payloadBytes = this.buildPutMessageRequestBytes(
+      isBlockLevel ? 2 : 4,
+      chatId,
+      cid1,
+      contentBytes
+    );
+
+    // Build outer Packet
+    const packet = create(PacketSchema, {
+      payloadType: 1, // PB2
+      cmd: 5,
+      cid: requestId,
+      payload: payloadBytes
+    });
+
+    return Buffer.from(toBinary(PacketSchema, packet));
+  }
+
+  /**
+   * Build Content bytes manually
+   */
+  static buildContentBytes(textField, elementIds, innerText, dictionaryBytes) {
+    const parts = [];
+
+    // Field 1: text (string)
+    if (textField) {
+      const textBytes = new TextEncoder().encode(textField);
+      parts.push(0x0a); // field 1, wire type 2
+      pushVarintLength(parts, textBytes.length);
+      parts.push(...textBytes);
+    } else {
+      // Empty text field - must include for block elements
+      parts.push(0x0a, 0x00);
+    }
+
+    // Field 14: richText
+    const richTextBytes = this.buildRichTextBytes(elementIds, innerText, dictionaryBytes);
+    parts.push(0x72); // field 14, wire type 2 (14 << 3 | 2 = 114 = 0x72)
+    // Length encoding for richText
+    const rtLen = richTextBytes.length;
+    pushVarintLength(parts, rtLen);
+    parts.push(...richTextBytes);
+
+    return new Uint8Array(parts);
+  }
+
+  /**
+   * Build RichText bytes manually
+   */
+  static buildRichTextBytes(elementIds, innerText, dictionaryBytes) {
+    const parts = [];
+
+    // Field 1: elementIds (repeated string)
+    for (const id of elementIds) {
+      const idBytes = new TextEncoder().encode(id);
+      parts.push(0x0a); // field 1, wire type 2
+      pushVarintLength(parts, idBytes.length);
+      parts.push(...idBytes);
+    }
+
+    // Field 2: innerText (string)
+    const innerTextBytes = new TextEncoder().encode(innerText);
+    parts.push(0x12); // field 2, wire type 2
+    pushVarintLength(parts, innerTextBytes.length);
+    parts.push(...innerTextBytes);
+
+    // Field 3: elements (RichTextElements containing dictionary)
+    // Wrap dictionary in elements message
+    const elementsBytes = this.buildRichTextElementsBytes(dictionaryBytes);
+    parts.push(0x1a); // field 3, wire type 2
+    const elemLen = elementsBytes.length;
+    pushVarintLength(parts, elemLen);
+    parts.push(...elementsBytes);
+
+    return new Uint8Array(parts);
+  }
+
+  /**
+   * Build RichTextElements bytes (wrapper for dictionary)
+   */
+  static buildRichTextElementsBytes(dictionaryBytes) {
+    // dictionary is field 1 in RichTextElements
+    // The dictionaryBytes already contains the map entries
+    return dictionaryBytes;
+  }
+
+  /**
+   * Build PutMessageRequest bytes manually
+   */
+  static buildPutMessageRequestBytes(type, chatId, cid, contentBytes) {
+    const parts = [];
+
+    // Field 1: type (int32)
+    parts.push(0x08); // field 1, wire type 0
+    parts.push(type);
+
+    // Field 2: content (bytes)
+    parts.push(0x12); // field 2, wire type 2
+    const contentLen = contentBytes.length;
+    pushVarintLength(parts, contentLen);
+    parts.push(...contentBytes);
+
+    // Field 3: chatId (string)
+    const chatIdBytes = new TextEncoder().encode(chatId);
+    parts.push(0x1a); // field 3, wire type 2 (3 << 3 | 2 = 26 = 0x1a)
+    pushVarintLength(parts, chatIdBytes.length);
+    parts.push(...chatIdBytes);
+
+    // Field 4: rootId (string) - empty
+    parts.push(0x22, 0x00); // field 4, empty string
+
+    // Field 5: parentId (string) - empty
+    parts.push(0x2a, 0x00); // field 5, empty string
+
+    // Field 6: cid (string)
+    const cidBytes = new TextEncoder().encode(cid);
+    parts.push(0x32); // field 6, wire type 2 (6 << 3 | 2 = 50 = 0x32)
+    pushVarintLength(parts, cidBytes.length);
+    parts.push(...cidBytes);
+
+    // Field 7: isNotified (bool) = true
+    parts.push(0x38); // field 7, wire type 0 (7 << 3 | 0 = 56 = 0x38)
+    parts.push(0x01);
+
+    // Field 9: version (int32) = 1 (optional)
+
+    return new Uint8Array(parts);
+  }
+
+  /**
+   * Build protobuf message for search
+   * @param {string} requestId - Request ID
+   * @param {string} query - Search query
+   * @returns {Buffer} Serialized protobuf message
+   */
+  static buildSearchRequest(requestId, query) {
+    const searchSession = generateRequestCid();
+
+    // Build UniversalSearchRequest
+    const payload = create(UniversalSearchRequestSchema, {
+      header: {
+        searchSession: searchSession,
+        sessionSeqId: 1,
+        query: query,
+        searchContext: {
+          tagName: 'SMART_SEARCH',
+          entityItems: [
+            { type: 1 }, // USER
+            { type: 3 }, // GROUP_CHAT
+            { type: 2 }  // BOT
+          ]
+        },
+        commonFilter: {
+          includeOuterTenant: true
+        },
+        sourceKey: 'messenger',
+        locale: 'zh_CN'
+      }
+    });
+
+    // Build outer Packet
+    const packet = create(PacketSchema, {
+      payloadType: 1, // PB2
+      cmd: 11021,
+      cid: requestId,
+      payload: toBinary(UniversalSearchRequestSchema, payload)
+    });
+
+    return Buffer.from(toBinary(PacketSchema, packet));
+  }
+
+  /**
+   * Build protobuf message for creating chat
+   * @param {string} requestId - Request ID
+   * @param {string} userId - User ID to create chat with
+   * @returns {Buffer} Serialized protobuf message
+   */
+  static buildCreateChatRequest(requestId, userId) {
+    // Build PutChatRequest
+    const payload = create(PutChatRequestSchema, {
+      type: 1, // P2P
+      chatterIds: [userId]
+    });
+
+    // Build outer Packet
+    const packet = create(PacketSchema, {
+      payloadType: 1, // PB2
+      cmd: 13,
+      cid: requestId,
+      payload: toBinary(PutChatRequestSchema, payload)
+    });
+
+    return Buffer.from(toBinary(PacketSchema, packet));
+  }
+
+  /**
+   * Decode search response protobuf
+   * @param {Buffer} buffer - Response buffer
+   * @returns {Object} Decoded search results
+   */
+  static decodeSearchResponse(buffer) {
+    const packet = fromBinary(PacketSchema, buffer);
+
+    if (!packet.payload) {
+      return [];
+    }
+
+    const response = fromBinary(UniversalSearchResponseSchema, packet.payload);
+
+    return (response.results || []).map(result => ({
+      type: result.type === 1 ? 'user' : result.type === 3 ? 'group' : 'unknown',
+      id: result.id,
+      rawType: result.type,
+      titleHighlighted: result.titleHighlighted,
+      avatarKey: result.avatarKey
+    }));
+  }
+
+  /**
+   * Decode create chat response protobuf
+   * @param {Buffer} buffer - Response buffer
+   * @returns {string|null} Chat ID
+   */
+  static decodeCreateChatResponse(buffer) {
+    const packet = fromBinary(PacketSchema, buffer);
+
+    if (!packet.payload) {
+      return null;
+    }
+
+    const response = fromBinary(PutChatResponseSchema, packet.payload);
+
+    return response.chat?.id || null;
+  }
+
+  /**
+   * Decode received WebSocket message
+   * @param {Buffer} buffer - Message buffer
+   * @returns {Object} Decoded message data
+   */
+  static decodeReceiveMessage(buffer) {
+    const frame = fromBinary(FrameSchema, buffer);
+
+    if (!frame.payload) {
+      return { fromId: null, chatId: null, content: '', sid: null, type: null };
+    }
+
+    const packet = fromBinary(PacketSchema, frame.payload);
+
+    if (!packet.payload) {
+      return { fromId: null, chatId: null, content: '', sid: packet.sid, type: null, command: packet.cmd };
+    }
+
+    // cmd=77 (PROCESS_MULTI_PACKETS): 会下发图片资源及 crypto 信息
+    if (packet.cmd === 77) {
+      const cachedCount = this.cacheImageCryptoFromCmd77Payload(packet.payload);
+      if (cachedCount > 0) {
+        logger.log('[Proto] ✅ 从 cmd=77 缓存了 ' + cachedCount + ' 条图片加密信息');
+      }
+
+      return { fromId: null, chatId: null, content: '', sid: packet.sid, type: null, command: packet.cmd };
+    }
+
+    // cmd=74: 群消息已读状态推送
+    if (packet.cmd === 74) {
+      return this.decodeGroupReadState(packet);
+    }
+
+    // cmd=8106: 话题已读状态推送
+    if (packet.cmd === 8106) {
+      return this.decodeThreadReadState(packet);
+    }
+
+    // cmd=7001: 设备在线状态推送
+    if (packet.cmd === 7001) {
+      return this.decodeDeviceOnlineStatus(packet);
+    }
+
+    // cmd=48, 49, 7032, 7017: 其他推送事件，返回基本信息 + raw payload
+    if (packet.cmd === 48 || packet.cmd === 49 || packet.cmd === 7032 || packet.cmd === 7017) {
+      return {
+        fromId: null, chatId: null, content: '', sid: packet.sid,
+        command: packet.cmd, event: PUSH_CMD_TYPES[packet.cmd] || 'unknown',
+        payloadLength: packet.payload?.length || 0, type: null
+      };
+    }
+
+    // Try to decode PushMessagesRequest
+    let pushRequest;
+    try {
+      pushRequest = fromBinary(PushMessagesRequestSchema, packet.payload);
+    } catch (error) {
+      // If parsing fails, try to manually parse the messages map
+      logger.error('[Proto] Failed to decode PushMessagesRequest with schema, trying manual parse:', error.message);
+
+      // Manual parse: decode as raw message and extract messages
+      try {
+        const payload = packet.payload;
+        const messages = {};
+
+        // Parse the messages map manually
+        let offset = 0;
+        while (offset < payload.length) {
+          const tag = payload[offset];
+          if (tag === undefined) break;
+
+          const wireType = tag & 0x07;
+          const fieldNo = tag >> 3;
+
+          offset++;
+
+          if (fieldNo === 1) { // messages field
+            if (wireType === 2) { // length-delimited (map entry)
+              const length = this.readVarint(payload, offset);
+              offset += this.varintLength(payload, offset);
+
+              const entryData = payload.subarray(offset, offset + length);
+              offset += length;
+
+              // Parse map entry: string key, bytes value
+              let entryOffset = 0;
+              let key = null;
+              let value = null;
+
+              while (entryOffset < entryData.length) {
+                const entryTag = entryData[entryOffset];
+                if (entryTag === undefined) break;
+                const entryWireType = entryTag & 0x07;
+                const entryFieldNo = entryTag >> 3;
+                entryOffset++;
+
+                if (entryFieldNo === 1) { // key (string)
+                  const strLen = this.readVarint(entryData, entryOffset);
+                  entryOffset += this.varintLength(entryData, entryOffset);
+                  key = entryData.subarray(entryOffset, entryOffset + strLen).toString('utf8');
+                  entryOffset += strLen;
+                } else if (entryFieldNo === 2) { // value (bytes/message)
+                  const msgLen = this.readVarint(entryData, entryOffset);
+                  entryOffset += this.varintLength(entryData, entryOffset);
+                  value = entryData.subarray(entryOffset, entryOffset + msgLen);
+                  entryOffset += msgLen;
+                } else {
+                  // Skip unknown field
+                  if (entryWireType === 2) {
+                    const len = this.readVarint(entryData, entryOffset);
+                    entryOffset += this.varintLength(entryData, entryOffset) + len;
+                  } else if (entryWireType === 0) {
+                    entryOffset += this.varintLength(entryData, entryOffset);
+                  } else {
+                    entryOffset++; // Skip invalid
+                  }
+                }
+              }
+
+              if (key && value) {
+                messages[key] = value;
+              }
+            }
+          } else {
+            // Skip non-map fields
+            if (wireType === 2) {
+              const len = this.readVarint(payload, offset);
+              offset += this.varintLength(payload, offset) + len;
+            } else if (wireType === 0) {
+              offset += this.varintLength(payload, offset);
+            } else {
+              offset++;
+            }
+          }
+        }
+
+        // Parse the first message
+        const messageKey = Object.keys(messages)[0];
+        if (!messageKey) {
+          return { fromId: null, chatId: null, content: '', sid: packet.sid, type: null };
+        }
+
+        // Try to parse the message bytes using entities_MessageSchema
+        try {
+          const message = fromBinary(entities_MessageSchema, messages[messageKey]);
+          return this.parseMessageContent(message, packet.sid);
+        } catch (msgError) {
+          logger.error('[Proto] Failed to decode individual message:', msgError.message);
+          return { fromId: null, chatId: null, content: '', sid: packet.sid, type: null };
+        }
+      } catch (manualError) {
+        logger.error('[Proto] Manual parse also failed:', manualError.message);
+        return { fromId: null, chatId: null, content: '', sid: packet.sid, parseError: error.message, type: null };
+      }
+    }
+
+    // Get first message from the map
+    const messages = pushRequest.messages || {};
+    const messageKey = Object.keys(messages)[0];
+
+    if (!messageKey) {
+      return { fromId: null, chatId: null, content: '', sid: packet.sid, type: null };
+    }
+
+    const message = messages[messageKey];
+    return this.parseMessageContent(message, packet.sid);
+  }
+
+  /**
+   * Parse message content based on type
+   * @param {Object} message - Decoded entities.Message
+   * @param {string} sid - Packet sid
+   * @returns {Object} Parsed message data
+   */
+  static parseMessageContent(message, sid) {
+    const baseResult = {
+      fromId: String(message.fromId || ''),
+      chatId: String(message.chatId || ''),
+      messageId: String(message.id || ''),
+      type: message.type,
+      fromType: message.fromType,      // 发送者类型: USER=1, BOT=2
+      chatType: message.chatType,      // 聊天类型: P2P=1, GROUP=2, TOPIC_GROUP=3
+      threadId: String(message.threadId || ''),  // 话题ID
+      sid: sid,
+      content: '',
+      imageKey: null,
+      imageKeys: [],  // 支持多图片
+      cryptoInfo: null,
+      cryptoInfos: []  // 支持多图片的加密信息
+    };
+
+    // POST = 2 (富文本，图文混合消息)
+    if (message.type === 2 && message.content) {
+      try {
+        const content = fromBinary(ContentSchema, message.content);
+        const postResult = this.parsePostContent(content);
+
+        // 缓存所有图片的加密信息
+        for (const imgInfo of postResult.images) {
+          if (imgInfo.imageKey && imgInfo.cryptoInfo) {
+            cacheImageCryptoInfo(imgInfo.imageKey, imgInfo.cryptoInfo);
+          }
+        }
+
+        return {
+          ...baseResult,
+          content: postResult.text,
+          imageKey: postResult.images[0]?.imageKey || null,
+          imageKeys: postResult.images.map(img => img.imageKey).filter(Boolean),
+          cryptoInfo: postResult.images[0]?.cryptoInfo || null,
+          cryptoInfos: postResult.images.map(img => img.cryptoInfo).filter(Boolean)
+        };
+      } catch (e) {
+        logger.error('[Proto] Failed to decode POST content:', e.message);
+        return baseResult;
+      }
+    }
+
+    // TEXT = 4
+    if (message.type === 4 && message.content) {
+      try {
+        // 直接从原始字节解析，避免字符串编码问题
+        const text = this.parseTextMessageContent(message.content);
+        return { ...baseResult, content: text };
+      } catch (e) {
+        logger.error('[Proto] Failed to decode TEXT content:', e.message);
+        return baseResult;
+      }
+    }
+
+    // CARD = 14 (卡片消息)
+    // Some web protocol variants may deliver CARD as 13; only treat it as card
+    // when card JSON can be extracted.
+    if ((message.type === 14 || message.type === 13) && message.content) {
+      try {
+        const cardResult = this.parseCardContent(message.content);
+        const hasCardJson = Boolean(cardResult?.json || cardResult?.rawJson);
+        if (message.type !== 14 && !hasCardJson) {
+          return baseResult;
+        }
+        return {
+          ...baseResult,
+          content: cardResult.summary || '[卡片消息]',
+          card: cardResult
+        };
+      } catch (e) {
+        logger.error('[Proto] Failed to decode CARD content:', e.message);
+        return { ...baseResult, content: '[卡片消息]' };
+      }
+    }
+
+    // IMAGE = 5
+    if (message.type === 5 && message.content) {
+      try {
+        const imageContent = fromBinary(ImageContentSchema, message.content);
+        const imageInfo = this.extractImageInfo(imageContent);
+
+        if (imageInfo.imageKey && imageInfo.cryptoInfo) {
+          // 缓存加密信息
+          cacheImageCryptoInfo(imageInfo.imageKey, imageInfo.cryptoInfo);
+        }
+
+        return {
+          ...baseResult,
+          content: '[图片]',
+          imageKey: imageInfo.imageKey,
+          cryptoInfo: imageInfo.cryptoInfo,
+          fsUnit: imageInfo.fsUnit
+        };
+      } catch (e) {
+        logger.error('[Proto] Failed to decode IMAGE content:', e.message);
+        return { ...baseResult, content: '[图片解析失败]' };
+      }
+    }
+
+    // Other message types
+    return baseResult;
+  }
+
+  /**
+   * Decode cmd=74 群消息已读状态推送
+   * @param {Object} packet - Decoded Packet
+   * @returns {Object} Parsed read state event
+   */
+  static decodeGroupReadState(packet) {
+    try {
+      const notice = fromBinary(PushGroupMessageReadStateNoticeSchema, packet.payload);
+
+      // Convert readTimes map (string->bigint) to plain object (string->number)
+      const readTimes = {};
+      if (notice.readTimes) {
+        for (const [key, value] of Object.entries(notice.readTimes)) {
+          readTimes[key] = Number(value);
+        }
+      }
+
+      return {
+        command: 74,
+        event: 'readState',
+        sid: packet.sid,
+        groupId: notice.groupId,
+        readPosition: notice.readPosition,
+        lastMessagePosition: notice.lastMessagePosition,
+        readTimes,
+        readPositionBadgeCount: notice.readPositionBadgeCount,
+        lastMessageId: notice.lastMessageId,
+        messageIds: notice.messageIds || [],
+        fromId: null,
+        chatId: notice.groupId,
+        content: '',
+        type: null,
+      };
+    } catch (error) {
+      logger.error('[Proto] Failed to decode cmd=74 PushGroupMessageReadStateNotice:', error.message);
+      return { fromId: null, chatId: null, content: '', sid: packet.sid, command: 74, type: null };
+    }
+  }
+
+  /**
+   * Decode cmd=7001 设备在线状态推送
+   * @param {Object} packet - Decoded Packet
+   * @returns {Object} Parsed device status event
+   */
+  static decodeDeviceOnlineStatus(packet) {
+    try {
+      const push = fromBinary(PushDeviceOnlineStatusSchema, packet.payload);
+      const status = push.deviceOnlineStatus;
+
+      return {
+        command: 7001,
+        event: 'deviceStatus',
+        sid: packet.sid,
+        deviceId: status?.deviceId || '',
+        terminalType: status?.terminalType ?? 0,
+        onlineStatus: status?.onlineStatus ?? 0,
+        fromId: null,
+        chatId: null,
+        content: '',
+        type: null,
+      };
+    } catch (error) {
+      logger.error('[Proto] Failed to decode cmd=7001 PushDeviceOnlineStatus:', error.message);
+      return { fromId: null, chatId: null, content: '', sid: packet.sid, command: 7001, type: null };
+    }
+  }
+
+  /**
+   * Decode cmd=8106 话题已读状态推送 (proto 定义缺失，手动解析)
+   * @param {Object} packet - Decoded Packet
+   * @returns {Object} Parsed thread read state event
+   */
+  static decodeThreadReadState(packet) {
+    try {
+      const fields = this.roughProtobufParse(packet.payload);
+
+      return {
+        command: 8106,
+        event: 'readState',
+        sid: packet.sid,
+        chatId: fields[1] || null,
+        readPosition: fields[8] != null ? Number(fields[8]) : undefined,
+        lastMessagePosition: fields[4] != null ? Number(fields[4]) : undefined,
+        updateTime: fields[12] != null ? Number(fields[12]) : undefined,
+        fromId: null,
+        content: '',
+        type: null,
+      };
+    } catch (error) {
+      logger.error('[Proto] Failed to decode cmd=8106 thread read state:', error.message);
+      return { fromId: null, chatId: null, content: '', sid: packet.sid, command: 8106, type: null };
+    }
+  }
+
+  /**
+   * Rough protobuf parser — extracts top-level fields as field_number -> value
+   * Strings/bytes are decoded as UTF-8 strings, varints as numbers
+   * @param {Uint8Array|Buffer} data - protobuf bytes
+   * @returns {Object} field_number -> value
+   */
+  static roughProtobufParse(data) {
+    const buffer = data instanceof Buffer ? data : Buffer.from(data);
+    const fields = {};
+    let offset = 0;
+
+    while (offset < buffer.length) {
+      const { value: tag, bytesRead: tagBytes } = this.readVarintWithLength(buffer, offset);
+      if (!tagBytes) break;
+      offset += tagBytes;
+
+      const wireType = tag & 0x07;
+      const fieldNo = tag >> 3;
+
+      if (wireType === 0) { // varint
+        const { value, bytesRead } = this.readVarintWithLength(buffer, offset);
+        offset += bytesRead;
+        fields[fieldNo] = value;
+      } else if (wireType === 2) { // length-delimited
+        const { value: len, bytesRead } = this.readVarintWithLength(buffer, offset);
+        offset += bytesRead;
+        if (offset + len > buffer.length) break;
+        const chunk = buffer.subarray(offset, offset + len);
+        offset += len;
+        // Attempt to decode as UTF-8 string; keep as-is if it looks like text
+        try {
+          const str = chunk.toString('utf8');
+          if (!/[\x00-\x08\x0B\x0C\x0E-\x1F]/.test(str)) {
+            fields[fieldNo] = str;
+          } else {
+            fields[fieldNo] = chunk;
+          }
+        } catch {
+          fields[fieldNo] = chunk;
+        }
+      } else if (wireType === 1) { // 64-bit
+        offset += 8;
+      } else if (wireType === 5) { // 32-bit
+        offset += 4;
+      } else {
+        break;
+      }
+    }
+
+    return fields;
+  }
+
+  /**
+   * Extract image key and crypto info from ImageContent
+   * @param {Object} imageContent - Decoded ImageContent
+   * @returns {Object} { imageKey, cryptoInfo, fsUnit }
+   */
+  static extractImageInfo(imageContent) {
+    let imageKey = null;
+    let cryptoInfo = null;
+    let fsUnit = null;
+
+    // Try ImageSetV2 first (newer format)
+    if (imageContent.imageV2) {
+      const imageV2 = imageContent.imageV2;
+      imageKey = imageV2.imageKey;
+      fsUnit = imageV2.fsUnit;
+
+      if (imageV2.crypto) {
+        cryptoInfo = this.extractCryptoInfo(imageV2.crypto);
+      }
+    }
+
+    // Fallback to ImageSet (older format)
+    if (!imageKey && imageContent.image) {
+      const imageSet = imageContent.image;
+
+      // Try origin, then middle, then thumbnail
+      const sources = [imageSet.origin, imageSet.middle, imageSet.thumbnail];
+      for (const img of sources) {
+        if (img?.key) {
+          imageKey = img.key;
+          fsUnit = img.fsUnit;
+
+          if (img.crypto) {
+            cryptoInfo = this.extractCryptoInfo(img.crypto);
+          }
+          break;
+        }
+      }
+    }
+
+    return { imageKey, cryptoInfo, fsUnit };
+  }
+
+  /**
+   * Extract crypto info from Crypto message
+   * @param {Object} crypto - Decoded Crypto message
+   * @returns {Object|null} { secret, nonce, additionalData, type }
+   */
+  static extractCryptoInfo(crypto) {
+    if (!crypto.cipher) {
+      return null;
+    }
+
+    const cipher = crypto.cipher;
+
+    // Convert Uint8Array to Buffer
+    return {
+      secret: cipher.secret ? Buffer.from(cipher.secret) : null,
+      nonce: cipher.nonce ? Buffer.from(cipher.nonce) : null,
+      additionalData: cipher.additionalData ? Buffer.from(cipher.additionalData) : Buffer.alloc(0),
+      type: crypto.type // 1=AES_256_GCM, 6=SM4_128
+    };
+  }
+
+  /**
+   * Parse POST (richtext) content to extract text and images
+   * @param {Object} content - Decoded Content message
+   * @returns {Object} { text: string, images: Array<{imageKey, cryptoInfo}> }
+   */
+  static parsePostContent(content) {
+    const result = {
+      text: '',
+      images: []
+    };
+
+    if (!content.richText) {
+      // Fallback to simple text
+      result.text = content.text || '';
+      return result;
+    }
+
+    const richText = content.richText;
+    const texts = [];
+
+    // Parse elements dictionary to extract text and images
+    if (richText.elements?.dictionary) {
+      for (const [key, element] of Object.entries(richText.elements.dictionary)) {
+        // tag = 1 means TEXT element
+        if (element.tag === 1 && element.property) {
+          const textContent = this.parseTextProperty(element.property);
+          if (textContent) {
+            texts.push(textContent);
+          }
+        }
+        // tag = 2 means IMG element
+        else if (element.tag === 2 && element.property) {
+          const imageInfo = this.parseImageProperty(element.property);
+          if (imageInfo.imageKey) {
+            result.images.push(imageInfo);
+          }
+        }
+      }
+    }
+
+    // Combine extracted texts, or use innerText as fallback
+    result.text = texts.join('') || richText.innerText || '';
+
+    return result;
+  }
+
+  /**
+   * Parse CARD message content bytes
+   * Card content is typically JSON wrapped in a protobuf structure.
+   * The content bytes contain a protobuf with field 1 = JSON string of the card.
+   * @param {Uint8Array} bytes - Raw content bytes
+   * @returns {Object} { summary, title, json, rawJson }
+   */
+  static parseCardContent(bytes) {
+    if (!bytes || bytes.length === 0) {
+      return { summary: '[空卡片]' };
+    }
+
+    // Strategy 1: Try to extract JSON string from protobuf wrapper
+    // The content is likely a protobuf message with a string field containing JSON
+    const jsonStr = this.extractCardJson(bytes);
+    if (jsonStr) {
+      try {
+        const cardJson = JSON.parse(jsonStr);
+        return this.parseCardJson(cardJson, jsonStr);
+      } catch (e) {
+        // JSON parse failed, try other approaches
+      }
+    }
+
+    // Strategy 2: Try raw bytes as UTF-8 JSON directly
+    try {
+      const rawStr = Buffer.from(bytes).toString('utf8');
+      if (rawStr.startsWith('{')) {
+        const cardJson = JSON.parse(rawStr);
+        return this.parseCardJson(cardJson, rawStr);
+      }
+    } catch (e) {
+      // Not raw JSON
+    }
+
+    // Strategy 3: Scan for JSON-like content in the bytes
+    const buffer = Buffer.from(bytes);
+    const jsonStart = buffer.indexOf('{');
+    if (jsonStart >= 0) {
+      // Find matching closing brace
+      let depth = 0;
+      let jsonEnd = -1;
+      for (let i = jsonStart; i < buffer.length; i++) {
+        if (buffer[i] === 0x7b) depth++; // '{'
+        if (buffer[i] === 0x7d) depth--; // '}'
+        if (depth === 0) {
+          jsonEnd = i;
+          break;
+        }
+      }
+      if (jsonEnd > jsonStart) {
+        try {
+          const extracted = buffer.slice(jsonStart, jsonEnd + 1).toString('utf8');
+          const cardJson = JSON.parse(extracted);
+          return this.parseCardJson(cardJson, extracted);
+        } catch (e) {
+          // Not valid JSON
+        }
+      }
+    }
+
+    return {
+      summary: '[卡片消息]',
+      rawContentBase64: Buffer.from(bytes).toString('base64')
+    };
+  }
+
+  /**
+   * Extract JSON string from card content protobuf bytes
+   * Iterates protobuf fields looking for length-delimited string fields
+   * that start with '{' (JSON object)
+   * @param {Uint8Array} bytes - Raw protobuf bytes
+   * @returns {string|null} JSON string or null
+   */
+  static extractCardJson(bytes) {
+    const buffer = Buffer.from(bytes);
+    let offset = 0;
+
+    while (offset < buffer.length) {
+      const { value: tag, bytesRead: tagBytes } = this.readVarintWithLength(buffer, offset);
+      if (tagBytes === 0) break;
+      offset += tagBytes;
+
+      const wireType = tag & 0x07;
+      const fieldNo = tag >> 3;
+
+      if (wireType === 2) { // Length-delimited
+        const { value: len, bytesRead } = this.readVarintWithLength(buffer, offset);
+        offset += bytesRead;
+
+        if (offset + len > buffer.length) break;
+
+        const data = buffer.subarray(offset, offset + len);
+        offset += len;
+
+        // Check if this field contains JSON
+        if (len > 2 && data[0] === 0x7b) { // starts with '{'
+          try {
+            const str = data.toString('utf8');
+            JSON.parse(str); // validate it's JSON
+            return str;
+          } catch (e) {
+            // Not JSON, continue
+          }
+        }
+
+        // Recurse into nested messages to find JSON
+        if (len > 10) {
+          const nested = this.extractCardJson(data);
+          if (nested) return nested;
+        }
+      } else if (wireType === 0) { // Varint
+        const { bytesRead } = this.readVarintWithLength(buffer, offset);
+        offset += bytesRead;
+      } else if (wireType === 5) { // 32-bit
+        offset += 4;
+      } else if (wireType === 1) { // 64-bit
+        offset += 8;
+      } else {
+        break;
+      }
+    }
+
+    return null;
+  }
+
+  /**
+   * Parse card JSON to extract summary info
+   * @param {Object} cardJson - Parsed card JSON object
+   * @param {string} rawJson - Original JSON string
+   * @returns {Object} { summary, title, json, rawJson }
+   */
+  static parseCardJson(cardJson, rawJson) {
+    const result = {
+      json: cardJson,
+      rawJson: rawJson,
+      title: null,
+      summary: null,
+    };
+
+    // Extract title from multiple schema variants
+    result.title = this.pickFirstText([
+      cardJson.header?.title?.content,
+      cardJson.header?.property?.title?.content,
+      cardJson.header?.property?.title?.property?.content,
+      cardJson.header?.property?.mainTitle?.content,
+      cardJson.header?.property?.mainTitle?.property?.content,
+      cardJson.header?.property?.subtitle?.content,
+      cardJson.header?.property?.subtitle?.property?.content,
+    ]);
+
+    // Extract summary from known summary fields
+    result.summary = this.pickFirstText([
+      cardJson.config?.summary?.content,
+      cardJson.config?.summary,
+      cardJson.summary?.content,
+      cardJson.summary,
+    ]);
+
+    // Build summary: prefer explicit summary, fallback to title
+    if (!result.summary) {
+      if (result.title) {
+        result.summary = `[卡片] ${result.title}`;
+      } else {
+        // Try to extract text from body elements
+        const bodyText = this.extractCardBodyText(cardJson);
+        result.summary = bodyText
+          ? `[卡片] ${bodyText.substring(0, 50)}`
+          : '[卡片消息]';
+      }
+    }
+
+    return result;
+  }
+
+  /**
+   * Extract text content from card body elements
+   * @param {Object} cardJson - Card JSON
+   * @returns {string} Extracted text
+   */
+  static extractCardBodyText(cardJson) {
+    const texts = [];
+    const seen = new Set();
+
+    const addText = (value) => {
+      if (typeof value !== 'string') return;
+      const normalized = value.replace(/\s+/g, ' ').trim();
+      if (!normalized) return;
+
+      // Skip low-signal tokens and metadata values
+      if (/^https?:\/\//.test(normalized)) return;
+      if (/^#[0-9a-fA-F]{6,8}$/.test(normalized)) return;
+      if (/^(default|normal|small|medium|large)$/i.test(normalized)) return;
+
+      if (!seen.has(normalized)) {
+        seen.add(normalized);
+        texts.push(normalized);
+      }
+    };
+
+    const walk = (node, depth = 0) => {
+      if (!node || depth > 10 || texts.length >= 8) return;
+
+      if (typeof node === 'string') {
+        addText(node);
+        return;
+      }
+
+      if (Array.isArray(node)) {
+        for (const item of node) {
+          walk(item, depth + 1);
+          if (texts.length >= 8) break;
+        }
+        return;
+      }
+
+      if (typeof node !== 'object') return;
+
+      // Common card text slots
+      addText(node.content);
+      addText(node.text);
+      addText(node.title);
+      addText(node.subtitle);
+
+      if (node.text && typeof node.text === 'object') {
+        addText(node.text.content);
+        addText(node.text.text);
+      }
+
+      if (node.property && typeof node.property === 'object') {
+        addText(node.property.content);
+        addText(node.property.text);
+        addText(node.property.title);
+        addText(node.property.subtitle);
+      }
+
+      // Traverse likely nested containers first
+      walk(node.newBody, depth + 1);
+      walk(node.body, depth + 1);
+      walk(node.elements, depth + 1);
+      walk(node.fields, depth + 1);
+      walk(node.columns, depth + 1);
+      walk(node.actions, depth + 1);
+      walk(node.header, depth + 1);
+      walk(node.property, depth + 1);
+      walk(node.text, depth + 1);
+      walk(node.title, depth + 1);
+      walk(node.subtitle, depth + 1);
+    };
+
+    walk(cardJson);
+
+    return texts.slice(0, 3).join(' ');
+  }
+
+  /**
+   * Pick first non-empty text value
+   * @param {Array<any>} values - candidate values
+   * @returns {string|null}
+   */
+  static pickFirstText(values) {
+    for (const value of values) {
+      if (typeof value !== 'string') continue;
+      const text = value.trim();
+      if (text) return text;
+    }
+    return null;
+  }
+
+  /**
+   * Parse TEXT element property to extract text content
+   * @param {Uint8Array} propertyBytes - The property bytes from RichTextElement
+   * @returns {string} Extracted text content
+   */
+  static parseTextProperty(propertyBytes) {
+    if (!propertyBytes || propertyBytes.length === 0) {
+      return '';
+    }
+
+    try {
+      const textProp = fromBinary(TextPropertySchema, propertyBytes);
+      return textProp.content || '';
+    } catch (e) {
+      // Fallback: try to extract string manually
+      const buffer = Buffer.from(propertyBytes);
+      let offset = 0;
+
+      while (offset < buffer.length) {
+        const tag = buffer[offset];
+        if (tag === undefined) break;
+
+        const wireType = tag & 0x07;
+        const fieldNo = tag >> 3;
+        offset++;
+
+        if (wireType === 2) {
+          const { value: len, bytesRead } = this.readVarintWithLength(buffer, offset);
+          offset += bytesRead;
+
+          // field 1 = content (string)
+          if (fieldNo === 1) {
+            return buffer.subarray(offset, offset + len).toString('utf8');
+          }
+
+          offset += len;
+        } else if (wireType === 0) {
+          const { bytesRead } = this.readVarintWithLength(buffer, offset);
+          offset += bytesRead;
+        } else {
+          break;
+        }
+      }
+
+      return '';
+    }
+  }
+
+  /**
+   * Parse IMG element property to extract imageKey and crypto info
+   * @param {Uint8Array} propertyBytes - The property bytes from RichTextElement
+   * @returns {Object} { imageKey, cryptoInfo }
+   */
+  static parseImageProperty(propertyBytes) {
+    const result = {
+      imageKey: null,
+      cryptoInfo: null
+    };
+
+    if (!propertyBytes || propertyBytes.length === 0) {
+      return result;
+    }
+
+    const buffer = Buffer.from(propertyBytes);
+    let offset = 0;
+
+    while (offset < buffer.length) {
+      if (offset >= buffer.length) break;
+
+      // 读取 tag (可能是 multi-byte varint)
+      const { value: tag, bytesRead: tagBytes } = this.readVarintWithLength(buffer, offset);
+      if (tagBytes === 0) break;
+      offset += tagBytes;
+
+      const wireType = tag & 0x07;
+      const fieldNo = tag >> 3;
+
+      if (wireType === 2) { // Length-delimited
+        const { value: len, bytesRead } = this.readVarintWithLength(buffer, offset);
+        offset += bytesRead;
+
+        const data = buffer.subarray(offset, offset + len);
+        offset += len;
+
+        // field 2 = imageKey (string)
+        if (fieldNo === 2) {
+          result.imageKey = data.toString('utf8');
+        }
+        // field 17 = 嵌套消息（可能包含 ImageSetV2）
+        else if (fieldNo === 17) {
+          try {
+            const imageV2 = fromBinary(ImageSetV2Schema, data);
+            if (imageV2.crypto) {
+              result.cryptoInfo = this.extractCryptoInfo(imageV2.crypto);
+            }
+          } catch (e) {
+            // 尝试从嵌套结构中提取 crypto
+            const cryptoInfo = this.extractCryptoFromBytes(data);
+            if (cryptoInfo) {
+              result.cryptoInfo = cryptoInfo;
+            }
+          }
+        }
+
+        // 尝试在各种可能的字段中查找 crypto 信息
+        if (len > 10 && fieldNo !== 17) {
+          // 尝试解析为 ImageSetV2
+          try {
+            const imageV2 = fromBinary(ImageSetV2Schema, data);
+            if (imageV2.crypto) {
+              result.cryptoInfo = this.extractCryptoInfo(imageV2.crypto);
+            }
+          } catch (e) {
+            // 尝试解析嵌套结构中的 crypto
+            const cryptoInfo = this.extractCryptoFromBytes(data);
+            if (cryptoInfo) {
+              result.cryptoInfo = cryptoInfo;
+            }
+          }
+        }
+      } else if (wireType === 0) { // Varint
+        const { bytesRead } = this.readVarintWithLength(buffer, offset);
+        offset += bytesRead;
+      } else {
+        break;
+      }
+    }
+
+    if (!result.imageKey) {
+      const text = buffer.toString('utf8');
+      const fallbackKeys = this.extractImageKeysFromString(text);
+      if (fallbackKeys.length > 0) {
+        result.imageKey = fallbackKeys[0];
+      }
+    }
+
+    if (!result.cryptoInfo) {
+      result.cryptoInfo = this.extractCryptoFromBytes(buffer);
+    }
+
+    return result;
+  }
+
+  /**
+   * 直接从原始字节解析 TEXT 消息内容
+   * Content 结构:
+   *   field 1 (text): string
+   *   field 3 (title): 嵌套的 RichText 结构
+   * @param {Uint8Array} bytes - 原始消息内容字节
+   * @returns {string} 解析出的文本
+   */
+  static parseTextMessageContent(bytes) {
+    const buffer = Buffer.from(bytes);
+    let offset = 0;
+    let textField = '';
+    let titleBytes = null;
+
+    // 解析 Content 结构
+    while (offset < buffer.length) {
+      if (offset >= buffer.length) break;
+
+      const { value: tag, bytesRead: tagBytes } = this.readVarintWithLength(buffer, offset);
+      if (tagBytes === 0) break;
+      offset += tagBytes;
+
+      const wireType = tag & 0x07;
+      const fieldNo = tag >> 3;
+
+      if (wireType === 2) { // Length-delimited
+        const { value: len, bytesRead } = this.readVarintWithLength(buffer, offset);
+        offset += bytesRead;
+
+        if (offset + len > buffer.length) break;
+
+        const data = buffer.subarray(offset, offset + len);
+        offset += len;
+
+        // field 1 = text
+        if (fieldNo === 1 && len > 0) {
+          textField = data.toString('utf8');
+        }
+        // field 3 = title (嵌套的 RichText)
+        else if (fieldNo === 3) {
+          titleBytes = data;
+        }
+      } else if (wireType === 0) { // Varint
+        const { bytesRead } = this.readVarintWithLength(buffer, offset);
+        offset += bytesRead;
+      } else {
+        break;
+      }
+    }
+
+    // 优先使用 text 字段
+    if (textField) {
+      return textField;
+    }
+
+    // 否则从 title (嵌套 RichText) 中提取
+    if (titleBytes) {
+      return this.parseRichTextFromBytes(titleBytes);
+    }
+
+    return '';
+  }
+
+  /**
+   * 从 RichText 字节中解析文本
+   * RichText 结构:
+   *   field 1 (elementIds): repeated string
+   *   field 2 (innerText): string
+   *   field 3 (elements): RichTextElements
+   * @param {Buffer} buffer - RichText 字节
+   * @returns {string} 解析出的文本
+   */
+  static parseRichTextFromBytes(buffer) {
+    let offset = 0;
+    let innerText = '';
+    let elementsBytes = null;
+
+    while (offset < buffer.length) {
+      if (offset >= buffer.length) break;
+
+      const { value: tag, bytesRead: tagBytes } = this.readVarintWithLength(buffer, offset);
+      if (tagBytes === 0) break;
+      offset += tagBytes;
+
+      const wireType = tag & 0x07;
+      const fieldNo = tag >> 3;
+
+      if (wireType === 2) { // Length-delimited
+        const { value: len, bytesRead } = this.readVarintWithLength(buffer, offset);
+        offset += bytesRead;
+
+        if (offset + len > buffer.length) break;
+
+        const data = buffer.subarray(offset, offset + len);
+        offset += len;
+
+        // field 2 = innerText
+        if (fieldNo === 2 && len > 0) {
+          innerText = data.toString('utf8');
+        }
+        // field 3 = elements
+        else if (fieldNo === 3) {
+          elementsBytes = data;
+        }
+      } else if (wireType === 0) { // Varint
+        const { bytesRead } = this.readVarintWithLength(buffer, offset);
+        offset += bytesRead;
+      } else {
+        break;
+      }
+    }
+
+    // 优先使用 innerText
+    if (innerText) {
+      return innerText;
+    }
+
+    // 否则从 elements 中提取
+    if (elementsBytes) {
+      return this.extractTextFromElementsBytes(elementsBytes);
+    }
+
+    return '';
+  }
+
+  /**
+   * 从 RichTextElements 字节中提取文本
+   * RichTextElements 结构:
+   *   field 1 (dictionary): map<string, RichTextElement>
+   * @param {Buffer} buffer - RichTextElements 字节
+   * @returns {string} 解析出的文本
+   */
+  static extractTextFromElementsBytes(buffer) {
+    const texts = [];
+    let offset = 0;
+
+    while (offset < buffer.length) {
+      if (offset >= buffer.length) break;
+
+      const { value: tag, bytesRead: tagBytes } = this.readVarintWithLength(buffer, offset);
+      if (tagBytes === 0) break;
+      offset += tagBytes;
+
+      const wireType = tag & 0x07;
+      const fieldNo = tag >> 3;
+
+      if (wireType === 2) { // Length-delimited
+        const { value: len, bytesRead } = this.readVarintWithLength(buffer, offset);
+        offset += bytesRead;
+
+        if (offset + len > buffer.length) break;
+
+        const data = buffer.subarray(offset, offset + len);
+        offset += len;
+
+        // field 1 = dictionary entry (map entry)
+        if (fieldNo === 1) {
+          const text = this.extractTextFromMapEntry(data);
+          if (text) {
+            texts.push(text);
+          }
+        }
+      } else if (wireType === 0) {
+        const { bytesRead } = this.readVarintWithLength(buffer, offset);
+        offset += bytesRead;
+      } else {
+        break;
+      }
+    }
+
+    return texts.join('');
+  }
+
+  /**
+   * 从 map entry 中提取文本
+   * Map entry 结构:
+   *   field 1 (key): string (element ID)
+   *   field 2 (value): RichTextElement
+   * RichTextElement 结构:
+   *   field 1 (tag): int32 (1=TEXT, 2=IMG, ...)
+   *   field 3 (property): bytes (TextProperty for TEXT)
+   * @param {Buffer} buffer - map entry 字节
+   * @returns {string} 解析出的文本
+   */
+  static extractTextFromMapEntry(buffer) {
+    let offset = 0;
+    let valueBytes = null;
+
+    while (offset < buffer.length) {
+      if (offset >= buffer.length) break;
+
+      const { value: tag, bytesRead: tagBytes } = this.readVarintWithLength(buffer, offset);
+      if (tagBytes === 0) break;
+      offset += tagBytes;
+
+      const wireType = tag & 0x07;
+      const fieldNo = tag >> 3;
+
+      if (wireType === 2) { // Length-delimited
+        const { value: len, bytesRead } = this.readVarintWithLength(buffer, offset);
+        offset += bytesRead;
+
+        if (offset + len > buffer.length) break;
+
+        const data = buffer.subarray(offset, offset + len);
+        offset += len;
+
+        // field 2 = value (RichTextElement)
+        if (fieldNo === 2) {
+          valueBytes = data;
+        }
+      } else if (wireType === 0) {
+        const { bytesRead } = this.readVarintWithLength(buffer, offset);
+        offset += bytesRead;
+      } else {
+        break;
+      }
+    }
+
+    if (valueBytes) {
+      return this.extractTextFromRichTextElement(valueBytes);
+    }
+
+    return '';
+  }
+
+  /**
+   * 从 RichTextElement 中提取文本
+   * RichTextElement 结构:
+   *   field 1 (tag): int32 (1=TEXT, 2=IMG)
+   *   field 3 (property): bytes
+   * @param {Buffer} buffer - RichTextElement 字节
+   * @returns {string} 解析出的文本
+   */
+  static extractTextFromRichTextElement(buffer) {
+    let offset = 0;
+    let elementTag = 0;
+    let propertyBytes = null;
+
+    while (offset < buffer.length) {
+      if (offset >= buffer.length) break;
+
+      const { value: tag, bytesRead: tagBytes } = this.readVarintWithLength(buffer, offset);
+      if (tagBytes === 0) break;
+      offset += tagBytes;
+
+      const wireType = tag & 0x07;
+      const fieldNo = tag >> 3;
+
+      if (wireType === 0) { // Varint
+        const { value, bytesRead } = this.readVarintWithLength(buffer, offset);
+        offset += bytesRead;
+        // field 1 = tag
+        if (fieldNo === 1) {
+          elementTag = value;
+        }
+      } else if (wireType === 2) { // Length-delimited
+        const { value: len, bytesRead } = this.readVarintWithLength(buffer, offset);
+        offset += bytesRead;
+
+        if (offset + len > buffer.length) break;
+
+        const data = buffer.subarray(offset, offset + len);
+        offset += len;
+
+        // field 3 = property
+        if (fieldNo === 3) {
+          propertyBytes = data;
+        }
+      } else {
+        break;
+      }
+    }
+
+    // tag = 1 表示 TEXT 元素
+    if (elementTag === 1 && propertyBytes) {
+      return this.parseTextPropertyBytes(propertyBytes);
+    }
+
+    return '';
+  }
+
+  /**
+   * 从 TextProperty 字节中解析文本
+   * TextProperty 结构:
+   *   field 1 (content): string
+   * @param {Buffer} buffer - TextProperty 字节
+   * @returns {string} 解析出的文本
+   */
+  static parseTextPropertyBytes(buffer) {
+    let offset = 0;
+
+    while (offset < buffer.length) {
+      if (offset >= buffer.length) break;
+
+      const { value: tag, bytesRead: tagBytes } = this.readVarintWithLength(buffer, offset);
+      if (tagBytes === 0) break;
+      offset += tagBytes;
+
+      const wireType = tag & 0x07;
+      const fieldNo = tag >> 3;
+
+      if (wireType === 2) { // Length-delimited
+        const { value: len, bytesRead } = this.readVarintWithLength(buffer, offset);
+        offset += bytesRead;
+
+        if (offset + len > buffer.length) break;
+
+        const data = buffer.subarray(offset, offset + len);
+        offset += len;
+
+        // field 1 = content
+        if (fieldNo === 1) {
+          return data.toString('utf8');
+        }
+      } else if (wireType === 0) {
+        const { bytesRead } = this.readVarintWithLength(buffer, offset);
+        offset += bytesRead;
+      } else {
+        break;
+      }
+    }
+
+    return '';
+  }
+
+  /**
+   * 尝试从原始字节中解码文本内容
+   * @param {Uint8Array} bytes - 原始字节
+   * @returns {string} 解码的文本，如果失败则返回空字符串
+   */
+  static tryDecodeTextFromBytes(bytes) {
+    if (!bytes || bytes.length === 0) {
+      return '';
+    }
+
+    const buffer = Buffer.from(bytes);
+    let offset = 0;
+
+    // 遍历 protobuf 字段，查找字符串类型的字段
+    while (offset < buffer.length) {
+      if (offset >= buffer.length) break;
+
+      const { value: tag, bytesRead: tagBytes } = this.readVarintWithLength(buffer, offset);
+      if (tagBytes === 0) break;
+      offset += tagBytes;
+
+      const wireType = tag & 0x07;
+      const fieldNo = tag >> 3;
+
+      if (wireType === 2) { // Length-delimited (string/bytes/message)
+        const { value: len, bytesRead } = this.readVarintWithLength(buffer, offset);
+        offset += bytesRead;
+
+        if (offset + len > buffer.length) break;
+
+        const data = buffer.subarray(offset, offset + len);
+        offset += len;
+
+        // field 1 通常是 text 字段
+        if (fieldNo === 1 && len > 0) {
+          try {
+            const text = data.toString('utf8');
+            // 验证是否为有效的 UTF-8 文本（不包含控制字符）
+            if (text && !/[\x00-\x08\x0B\x0C\x0E-\x1F]/.test(text)) {
+              return text;
+            }
+          } catch {
+            // 继续尝试其他字段
+          }
+        }
+
+        // field 14 可能是 richText，尝试递归解析
+        if (fieldNo === 14 && len > 0) {
+          const innerText = this.tryExtractInnerText(data);
+          if (innerText) {
+            return innerText;
+          }
+        }
+      } else if (wireType === 0) { // Varint
+        const { bytesRead } = this.readVarintWithLength(buffer, offset);
+        offset += bytesRead;
+      } else {
+        break;
+      }
+    }
+
+    return '';
+  }
+
+  /**
+   * 尝试从 richText 结构中提取 innerText
+   * @param {Buffer} buffer - richText 字节
+   * @returns {string} innerText 或空字符串
+   */
+  static tryExtractInnerText(buffer) {
+    let offset = 0;
+
+    while (offset < buffer.length) {
+      if (offset >= buffer.length) break;
+
+      const { value: tag, bytesRead: tagBytes } = this.readVarintWithLength(buffer, offset);
+      if (tagBytes === 0) break;
+      offset += tagBytes;
+
+      const wireType = tag & 0x07;
+      const fieldNo = tag >> 3;
+
+      if (wireType === 2) {
+        const { value: len, bytesRead } = this.readVarintWithLength(buffer, offset);
+        offset += bytesRead;
+
+        if (offset + len > buffer.length) break;
+
+        const data = buffer.subarray(offset, offset + len);
+        offset += len;
+
+        // field 2 是 innerText
+        if (fieldNo === 2 && len > 0) {
+          try {
+            const text = data.toString('utf8');
+            if (text && !/[\x00-\x08\x0B\x0C\x0E-\x1F]/.test(text)) {
+              return text;
+            }
+          } catch {
+            // 继续
+          }
+        }
+      } else if (wireType === 0) {
+        const { bytesRead } = this.readVarintWithLength(buffer, offset);
+        offset += bytesRead;
+      } else {
+        break;
+      }
+    }
+
+    return '';
+  }
+
+  /**
+   * Read varint and return both value and bytes read
+   */
+  static readVarintWithLength(buffer, offset) {
+    let value = 0;
+    let shift = 0;
+    let bytesRead = 0;
+    let byte;
+
+    do {
+      byte = buffer[offset + bytesRead];
+      value |= (byte & 0x7F) << shift;
+      bytesRead++;
+      shift += 7;
+    } while (byte & 0x80);
+
+    return { value, bytesRead };
+  }
+
+  /**
+   * Extract crypto info from raw bytes (fallback method)
+   */
+  static extractCryptoFromBytes(buffer, depth = 0) {
+    if (!buffer || buffer.length === 0 || depth > 6) {
+      return null;
+    }
+
+    const bytes = Buffer.from(buffer);
+
+    // 1) 直接尝试按 Crypto 解析
+    try {
+      const crypto = fromBinary(CryptoSchema, bytes);
+      const cryptoInfo = this.extractCryptoInfo(crypto);
+      if (cryptoInfo?.secret && cryptoInfo?.nonce) {
+        return cryptoInfo;
+      }
+    } catch {
+      // ignore
+    }
+
+    // 2) 尝试按 ImageSetV2 解析
+    try {
+      const imageV2 = fromBinary(ImageSetV2Schema, bytes);
+      if (imageV2?.crypto) {
+        const cryptoInfo = this.extractCryptoInfo(imageV2.crypto);
+        if (cryptoInfo?.secret && cryptoInfo?.nonce) {
+          return cryptoInfo;
+        }
+      }
+    } catch {
+      // ignore
+    }
+
+    // 3) 尝试按 Image 解析
+    try {
+      const image = fromBinary(ImageSchema, bytes);
+      if (image?.crypto) {
+        const cryptoInfo = this.extractCryptoInfo(image.crypto);
+        if (cryptoInfo?.secret && cryptoInfo?.nonce) {
+          return cryptoInfo;
+        }
+      }
+    } catch {
+      // ignore
+    }
+
+    // 4) 递归扫描 length-delimited 子字段
+    let offset = 0;
+    while (offset < bytes.length) {
+      const { value: tag, bytesRead: tagBytes } = this.readVarintWithLength(bytes, offset);
+      if (!tagBytes) break;
+      offset += tagBytes;
+
+      const wireType = tag & 0x07;
+
+      if (wireType === 2) {
+        const { value: len, bytesRead } = this.readVarintWithLength(bytes, offset);
+        offset += bytesRead;
+
+        if (len < 0 || offset + len > bytes.length) {
+          break;
+        }
+
+        const data = bytes.subarray(offset, offset + len);
+        offset += len;
+
+        const nestedCrypto = this.extractCryptoFromBytes(data, depth + 1);
+        if (nestedCrypto?.secret && nestedCrypto?.nonce) {
+          return nestedCrypto;
+        }
+      } else if (wireType === 0) {
+        const { bytesRead } = this.readVarintWithLength(bytes, offset);
+        offset += bytesRead;
+      } else if (wireType === 1) {
+        offset += 8;
+      } else if (wireType === 5) {
+        offset += 4;
+      } else {
+        break;
+      }
+    }
+
+    return null;
+  }
+
+  /**
+   * 检查 cryptoInfo 是否满足图片解密要求
+   * @param {Object|null} cryptoInfo
+   * @returns {boolean}
+   */
+  static isValidImageCryptoInfo(cryptoInfo) {
+    if (!cryptoInfo?.secret || !cryptoInfo?.nonce) {
+      return false;
+    }
+
+    const secretLength = Buffer.from(cryptoInfo.secret).length;
+    const nonceLength = Buffer.from(cryptoInfo.nonce).length;
+
+    return secretLength === 32 && nonceLength === 12;
+  }
+
+  /**
+   * 生成 crypto 信息指纹（用于聚合）
+   * @param {Object|null} cryptoInfo
+   * @returns {string}
+   */
+  static getCryptoFingerprint(cryptoInfo) {
+    if (!this.isValidImageCryptoInfo(cryptoInfo)) {
+      return '';
+    }
+
+    const secretHex = Buffer.from(cryptoInfo.secret).toString('hex');
+    const nonceHex = Buffer.from(cryptoInfo.nonce).toString('hex');
+    return secretHex.slice(0, 16) + ':' + nonceHex.slice(0, 8);
+  }
+
+  /**
+   * 仅尝试把当前 bytes 直接解码为 Crypto（不递归）
+   * @param {Uint8Array|Buffer} bytes
+   * @returns {Object|null}
+   */
+  static extractDirectCryptoInfo(bytes) {
+    if (!bytes || bytes.length === 0) {
+      return null;
+    }
+
+    try {
+      const crypto = fromBinary(CryptoSchema, bytes);
+      const cryptoInfo = this.extractCryptoInfo(crypto);
+      if (this.isValidImageCryptoInfo(cryptoInfo)) {
+        return cryptoInfo;
+      }
+    } catch {
+      // ignore
+    }
+
+    return null;
+  }
+
+  /**
+   * 深度遍历 payload，收集可能的 Crypto block
+   * @param {Uint8Array|Buffer} payload
+   * @param {number} baseOffset
+   * @param {number} depth
+   * @param {number} maxDepth
+   * @param {Array} blocks
+   * @returns {Array<{offset:number,end:number,cryptoInfo:Object,fingerprint:string}>}
+   */
+  static collectCryptoBlocksFromPayload(payload, baseOffset = 0, depth = 0, maxDepth = 10, blocks = []) {
+    if (!payload || depth > maxDepth) {
+      return blocks;
+    }
+
+    const buffer = payload instanceof Buffer ? payload : Buffer.from(payload);
+    if (buffer.length === 0) {
+      return blocks;
+    }
+
+    let offset = 0;
+    while (offset < buffer.length) {
+      const { value: tag, bytesRead: tagBytes } = this.readVarintWithLength(buffer, offset);
+      if (!tagBytes) {
+        break;
+      }
+      offset += tagBytes;
+
+      const wireType = tag & 0x07;
+
+      if (wireType === 2) {
+        const { value: len, bytesRead } = this.readVarintWithLength(buffer, offset);
+        offset += bytesRead;
+
+        if (len < 0 || offset + len > buffer.length) {
+          break;
+        }
+
+        const valueStart = offset;
+        const valueEnd = offset + len;
+        const data = buffer.subarray(valueStart, valueEnd);
+
+        const directCryptoInfo = this.extractDirectCryptoInfo(data);
+        if (directCryptoInfo) {
+          blocks.push({
+            offset: baseOffset + valueStart,
+            end: baseOffset + valueEnd,
+            cryptoInfo: directCryptoInfo,
+            fingerprint: this.getCryptoFingerprint(directCryptoInfo),
+          });
+        }
+
+        this.collectCryptoBlocksFromPayload(data, baseOffset + valueStart, depth + 1, maxDepth, blocks);
+
+        offset = valueEnd;
+      } else if (wireType === 0) {
+        const { bytesRead } = this.readVarintWithLength(buffer, offset);
+        if (!bytesRead) {
+          break;
+        }
+        offset += bytesRead;
+      } else if (wireType === 1) {
+        offset += 8;
+      } else if (wireType === 5) {
+        offset += 4;
+      } else {
+        break;
+      }
+    }
+
+    return blocks;
+  }
+
+  /**
+   * 在二进制 buffer 中查找 imageKey 出现位置
+   * @param {Buffer} buffer
+   * @param {string[]} imageKeys
+   * @returns {Array<{imageKey:string,offset:number,end:number}>}
+   */
+  static findImageKeyOccurrencesInBuffer(buffer, imageKeys) {
+    const occurrences = [];
+
+    for (const imageKey of imageKeys) {
+      let startOffset = 0;
+      while (startOffset < buffer.length) {
+        const index = buffer.indexOf(imageKey, startOffset, 'utf8');
+        if (index === -1) {
+          break;
+        }
+
+        occurrences.push({
+          imageKey,
+          offset: index,
+          end: index + Buffer.byteLength(imageKey, 'utf8'),
+        });
+
+        startOffset = index + 1;
+      }
+    }
+
+    return occurrences.sort((left, right) => left.offset - right.offset);
+  }
+
+  /**
+   * 从 cmd=77 响应 payload 中解析并缓存图片加密信息
+   * @param {Uint8Array|Buffer} payload
+   * @returns {number} 缓存条目数
+   */
+  static cacheImageCryptoFromCmd77Payload(payload) {
+    if (!payload || payload.length === 0) {
+      return 0;
+    }
+
+    const buffer = payload instanceof Buffer ? payload : Buffer.from(payload);
+    const imageKeys = this.extractImageKeysFromString(buffer.toString('utf8'));
+    if (imageKeys.length === 0) {
+      return 0;
+    }
+
+    const imageKeyOccurrences = this.findImageKeyOccurrencesInBuffer(buffer, imageKeys);
+    if (imageKeyOccurrences.length === 0) {
+      return 0;
+    }
+
+    const rawCryptoBlocks = this.collectCryptoBlocksFromPayload(buffer);
+    if (rawCryptoBlocks.length === 0) {
+      return 0;
+    }
+
+    // 去重（避免递归扫描时重复记录）
+    const dedupedBlockMap = new Map();
+    for (const block of rawCryptoBlocks) {
+      const dedupeKey = block.offset + ':' + block.fingerprint;
+      if (!dedupedBlockMap.has(dedupeKey)) {
+        dedupedBlockMap.set(dedupeKey, block);
+      }
+    }
+    const cryptoBlocks = Array.from(dedupedBlockMap.values());
+
+    const votesByImageKey = new Map();
+
+    for (const occurrence of imageKeyOccurrences) {
+      const forwardCandidates = cryptoBlocks.filter((block) => {
+        const distance = block.offset - occurrence.end;
+        return distance >= 0 && distance <= 2048;
+      });
+
+      const candidateBlocks = forwardCandidates.length > 0
+        ? forwardCandidates
+        : cryptoBlocks.filter((block) => Math.abs(block.offset - occurrence.end) <= 512);
+
+      if (candidateBlocks.length === 0) {
+        continue;
+      }
+
+      let bestCandidate = null;
+      for (const block of candidateBlocks) {
+        const distance = Math.abs(block.offset - occurrence.end);
+        const aheadPenalty = block.offset >= occurrence.end ? 0 : 256;
+        const score = distance + aheadPenalty;
+
+        if (!bestCandidate || score < bestCandidate.score) {
+          bestCandidate = { block, score };
+        }
+      }
+
+      if (!bestCandidate) {
+        continue;
+      }
+
+      const fingerprint = bestCandidate.block.fingerprint;
+      if (!fingerprint) {
+        continue;
+      }
+
+      let voteMap = votesByImageKey.get(occurrence.imageKey);
+      if (!voteMap) {
+        voteMap = new Map();
+        votesByImageKey.set(occurrence.imageKey, voteMap);
+      }
+
+      const existingVote = voteMap.get(fingerprint) || {
+        count: 0,
+        bestScore: Number.MAX_SAFE_INTEGER,
+        cryptoInfo: bestCandidate.block.cryptoInfo,
+      };
+
+      existingVote.count += 1;
+      existingVote.bestScore = Math.min(existingVote.bestScore, bestCandidate.score);
+      voteMap.set(fingerprint, existingVote);
+    }
+
+    let cachedCount = 0;
+
+    for (const [imageKey, voteMap] of votesByImageKey.entries()) {
+      const voteEntries = Array.from(voteMap.entries());
+      if (voteEntries.length === 0) {
+        continue;
+      }
+
+      voteEntries.sort((left, right) => {
+        const [, leftVote] = left;
+        const [, rightVote] = right;
+        if (rightVote.count !== leftVote.count) {
+          return rightVote.count - leftVote.count;
+        }
+        return leftVote.bestScore - rightVote.bestScore;
+      });
+
+      const [, bestVote] = voteEntries[0];
+      if (!this.isValidImageCryptoInfo(bestVote.cryptoInfo)) {
+        continue;
+      }
+
+      cacheImageCryptoInfo(imageKey, bestVote.cryptoInfo);
+      cachedCount += 1;
+    }
+
+    return cachedCount;
+  }
+
+  /**
+   * 从网关响应包中解析并缓存图片加密信息
+   * @param {Buffer|Uint8Array} buffer - 完整响应包（二进制）
+   * @returns {number} 缓存条目数
+   */
+  static cacheImageCryptoFromGatewayResponseBuffer(buffer) {
+    if (!buffer || buffer.length === 0) {
+      return 0;
+    }
+
+    try {
+      const bytes = buffer instanceof Uint8Array ? buffer : new Uint8Array(buffer);
+      const packet = fromBinary(PacketSchema, bytes);
+
+      if (!packet.payload || packet.payload.length === 0) {
+        return 0;
+      }
+
+      return this.cacheImageCryptoFromCmd77Payload(packet.payload);
+    } catch {
+      return 0;
+    }
+  }
+
+  /**
+   * 从 cmd=77 的完整响应包中解析并缓存图片加密信息
+   * @param {Buffer|Uint8Array} buffer - 完整响应包（二进制）
+   * @returns {number} 缓存条目数
+   */
+  static cacheImageCryptoFromCmd77ResponseBuffer(buffer) {
+    return this.cacheImageCryptoFromGatewayResponseBuffer(buffer);
+  }
+
+  /**
+   * Read varint from buffer at offset
+   */
+  static readVarint(buffer, offset) {
+    let value = 0;
+    let shift = 0;
+    let byte;
+
+    do {
+      byte = buffer[offset];
+      value |= (byte & 0x7F) << shift;
+      offset++;
+      shift += 7;
+    } while (byte & 0x80);
+
+    return value;
+  }
+
+  /**
+   * Get length of varint at offset
+   */
+  static varintLength(buffer, offset) {
+    let length = 0;
+    while (buffer[offset + length] & 0x80) {
+      length++;
+    }
+    return length + 1;
+  }
+
+  /**
+   * Build protobuf message for reply/回复消息
+   * @param {string} text - Text content to send
+   * @param {string} requestId - Request ID
+   * @param {string} chatId - Chat ID
+   * @param {Object} options - Options
+   * @param {string} options.rootId - 回复的根消息ID
+   * @param {string} options.parentId - 被回复的消息ID
+   * @returns {Buffer} Serialized protobuf message
+   */
+  static buildReplyRequest(text, requestId, chatId, options = {}) {
+    const { rootId, parentId } = options;
+    const cid1 = generateRequestCid();
+    const cid2 = generateRequestCid();
+
+    // Build TextProperty
+    const textProperty = create(TextPropertySchema, {
+      content: text
+    });
+
+    // Build Content with RichText
+    const content = create(ContentSchema, {
+      text: text,
+      richText: {
+        elementIds: [cid2],
+        innerText: text,
+        elements: {
+          dictionary: {
+            [cid2]: {
+              tag: 1, // TEXT
+              property: toBinary(TextPropertySchema, textProperty)
+            }
+          }
+        }
+      }
+    });
+
+    // Build PutMessageRequest with thread support
+    const payload = create(PutMessageRequestSchema, {
+      type: 4, // TEXT
+      chatId: chatId,
+      rootId: rootId || '',
+      parentId: parentId || '',
+      cid: cid1,
+      isNotified: true,
+      sendToChat: false,  // 话题评论不发送到主聊天
+      version: 1,
+      isThreadGroupTopic: false,  // 话题群话题标志
+      content: content
+    });
+
+    // Build outer Packet
+    const packet = create(PacketSchema, {
+      payloadType: 1, // PB2
+      cmd: 5,
+      cid: requestId,
+      payload: toBinary(PutMessageRequestSchema, payload)
+    });
+
+    return Buffer.from(toBinary(PacketSchema, packet));
+  }
+
+  /**
+   * Build ACK packet for WebSocket
+   * @param {string} sid - Packet sid to acknowledge
+   * @returns {Buffer} ACK protobuf message
+   */
+  static buildAckPacket(sid) {
+    const current = Date.now();
+
+    // Build inner Packet
+    const packet = create(PacketSchema, {
+      payloadType: 1, // PB2
+      cmd: 1, // ACK
+      sid: sid
+    });
+
+    // Build Frame
+    const frame = create(FrameSchema, {
+      seqid: protoInt64.parse(current),
+      logid: protoInt64.parse(current),
+      service: 1,
+      method: 1,
+      headers: [
+        { key: 'x-request-time', value: `${current}000` }
+      ],
+      payloadType: 'pb',
+      payload: toBinary(PacketSchema, packet)
+    });
+
+    return Buffer.from(toBinary(FrameSchema, frame));
+  }
+
+  /**
+   * Build protobuf message for getting user profile (cmd=5031)
+   * @param {string} requestId - Request ID
+   * @param {string} userId - User ID to get profile for
+   * @returns {Buffer} Serialized protobuf message
+   */
+  static buildGetUserProfileRequest(requestId, userId) {
+    // Build payload manually based on captured request:
+    // field 1 = 1 (fixed)
+    // field 2 = userId (string)
+    // field 5 = 2
+    // field 11 = 1
+    // field 12 = 1
+    // field 14 = 1
+    const parts = [];
+
+    // field 1: int32 = 1
+    parts.push(0x08, 0x01); // field 1, wire type 0, value 1
+
+    // field 2: string = userId
+    const userIdBytes = new TextEncoder().encode(userId);
+    parts.push(0x12); // field 2, wire type 2
+    pushVarintLength(parts, userIdBytes.length);
+    parts.push(...userIdBytes);
+
+    // field 5: int32 = 2
+    parts.push(0x28, 0x02); // field 5, wire type 0, value 2
+
+    // field 11: int32 = 1
+    parts.push(0x58, 0x01); // field 11 (11 << 3 | 0 = 88 = 0x58), value 1
+
+    // field 12: int32 = 1
+    parts.push(0x60, 0x01); // field 12 (12 << 3 | 0 = 96 = 0x60), value 1
+
+    // field 14: int32 = 1
+    parts.push(0x70, 0x01); // field 14 (14 << 3 | 0 = 112 = 0x70), value 1
+
+    const payload = new Uint8Array(parts);
+
+    // Build outer Packet
+    const packet = create(PacketSchema, {
+      payloadType: 1, // PB2
+      cmd: 5031,
+      cid: requestId,
+      payload: payload
+    });
+
+    return Buffer.from(toBinary(PacketSchema, packet));
+  }
+
+  /**
+   * Decode user profile response (cmd=5031)
+   * @param {Buffer} buffer - Response buffer
+   * @returns {Object} User profile info
+   */
+  static decodeGetUserProfileResponse(buffer) {
+    const packet = fromBinary(PacketSchema, buffer);
+
+    if (!packet.payload) {
+      return null;
+    }
+
+    // Parse the response payload to extract user info
+    const payload = Buffer.from(packet.payload);
+    return this.parseUserProfilePayload(payload);
+  }
+
+  /**
+   * Parse user profile payload
+   * @param {Buffer} buffer - Payload buffer
+   * @returns {Object} User profile info
+   */
+  static parseUserProfilePayload(buffer) {
+    const result = {
+      userId: null,
+      name: null,
+      enName: null,
+      avatarUrl: null,
+      avatarKey: null,
+      tenantId: null
+    };
+
+    // Structure:
+    // 1. Early in response: FROM_ID:userId - just reference
+    // 2. Later: 0a 13 + userId (19 bytes) + 12 09 + name (9 bytes) - actual profile
+    // 3. After that: 0x3a + len + enName
+
+    const str = buffer.toString('utf8');
+
+    // Find all 19-digit userIds
+    const userIdMatch = str.match(/\d{19}/g);
+    if (userIdMatch) {
+      result.userId = userIdMatch[0];
+    }
+
+    // Find the user profile section - look for userId followed by name
+    // Pattern: 0a 13 (field 1, len 19) + userId + 12 xx (field 2) + name
+    if (result.userId) {
+      const userIdBuf = Buffer.from(result.userId);
+      let idx = 0;
+      let searchStart = 0;
+
+      // Find the second occurrence (the real profile, not FROM_ID reference)
+      while ((idx = buffer.indexOf(userIdBuf, searchStart)) !== -1) {
+        // Check if this is preceded by 0a 13 (field 1, length 19)
+        if (idx >= 2 && buffer[idx - 2] === 0x0a && buffer[idx - 1] === 0x13) {
+          // This is the profile section!
+          const afterUserId = idx + userIdBuf.length;
+
+          // Look for name field: 12 xx (field 2, length)
+          if (afterUserId < buffer.length && buffer[afterUserId] === 0x12) {
+            const nameLen = buffer[afterUserId + 1];
+            if (nameLen > 0 && nameLen <= 30 && afterUserId + 2 + nameLen <= buffer.length) {
+              const nameBytes = buffer.subarray(afterUserId + 2, afterUserId + 2 + nameLen);
+              try {
+                const name = nameBytes.toString('utf8');
+                if (/^[\u4e00-\u9fa5]{2,10}$/.test(name) || /^[a-zA-Z\s]+$/.test(name)) {
+                  result.name = name;
+                }
+              } catch (e) {
+                // ignore
+              }
+            }
+          }
+          break;
+        }
+        searchStart = idx + 1;
+      }
+    }
+
+    // Find English name - near the profile section
+    // It appears at field 7 (tag 0x3a) within the user profile section
+    if (result.userId) {
+      const userIdBuf = Buffer.from(result.userId);
+      const profileStart = buffer.lastIndexOf(userIdBuf);
+      if (profileStart > 0) {
+        // Search within the profile section (profileStart to +2000 bytes)
+        const profileEnd = Math.min(buffer.length, profileStart + 2000);
+        const profileSlice = buffer.subarray(profileStart, profileEnd);
+        const profileStr = profileSlice.toString('utf8');
+
+        // Look for field 7 (0x3a) in the profile section - contains pinyin name
+        const enNameMatch = profileStr.match(/([a-z]+(?: [a-z]+)+)/);
+        if (enNameMatch && enNameMatch[0].length < 30) {
+          result.enName = enNameMatch[0];
+        }
+      }
+    }
+
+    // Extract avatar URL - look for feishucdn.com URLs
+    const avatarMatch = str.match(/https:\/\/s\d-imfile\.feishucdn\.com\/static-resource\/v\d\/[^\s~?]+/);
+    if (avatarMatch) {
+      result.avatarUrl = avatarMatch[0];
+    }
+
+    // Extract avatar key (v3_xxxx pattern)
+    const avatarKeyMatch = str.match(/v3_[a-z0-9]{4}_[a-f0-9-]+/i);
+    if (avatarKeyMatch) {
+      result.avatarKey = avatarKeyMatch[0];
+    }
+
+    return result;
+  }
+
+  // ==================== Get User Info By ID API (cmd=46) ====================
+
+  /**
+   * Build protobuf message for getting user info by ID (cmd=46)
+   * This API can query both regular users and bots
+   * @param {string} requestId - Request ID
+   * @param {string} userId - User ID to get info for
+   * @returns {Buffer} Serialized protobuf message
+   */
+  static buildGetUserInfoByIdRequest(requestId, userId) {
+    // Payload structure (inner message):
+    // field 1 = userId (string)
+    // field 2 = 1 (varint)
+    const parts = [];
+
+    // field 1 = userId (string)
+    const userIdBytes = Buffer.from(userId, 'utf-8');
+    parts.push(0x0a, userIdBytes.length, ...userIdBytes);
+
+    // field 2 = 1
+    parts.push(0x10, 0x01);
+
+    const payload = new Uint8Array(parts);
+
+    const packet = create(PacketSchema, {
+      payloadType: 1,
+      cmd: 46,
+      cid: requestId,
+      payload: payload
+    });
+
+    return Buffer.from(toBinary(PacketSchema, packet));
+  }
+
+  /**
+   * Decode user info response (cmd=46)
+   * @param {Buffer} buffer - Response buffer
+   * @returns {Object} User info including isBot flag
+   *   - userId: string
+   *   - name: string (Chinese name)
+   *   - isBot: boolean (true if this is a bot/app)
+   *   - userType: number (1=user, 2=bot)
+   *   - avatarKey: string
+   */
+  static decodeGetUserInfoByIdResponse(buffer) {
+    const packet = fromBinary(PacketSchema, buffer);
+
+    if (!packet.payload) {
+      return { success: false, error: 'No payload in response' };
+    }
+
+    const payload = Buffer.from(packet.payload);
+    return this.parseUserInfoPayload(payload);
+  }
+
+  // ==================== Get User Profile Card API (cmd=5017) ====================
+
+  /**
+   * Build protobuf message for getting user profile card (cmd=5017)
+   *
+   * Payload structure:
+   *   field 1 = userId (varint)
+   *
+   * @param {string} requestId - Request ID
+   * @param {string} userId - User ID to get profile card for
+   * @returns {Buffer} Serialized protobuf message
+   */
+  static buildGetUserProfileCardRequest(requestId, userId) {
+    const numericUserId = BigInt(userId);
+    const innerParts = [0x08]; // field 1, varint
+    this.pushVarintBigInt(innerParts, numericUserId);
+
+    const payload = new Uint8Array(innerParts);
+
+    const packet = create(PacketSchema, {
+      payloadType: 1,
+      cmd: 5017,
+      cid: requestId,
+      payload
+    });
+
+    return Buffer.from(toBinary(PacketSchema, packet));
+  }
+
+  /**
+   * Decode user profile card response (cmd=5017)
+   * @param {Buffer} buffer - Response buffer
+   * @returns {Object} Decoded profile card
+   */
+  static decodeGetUserProfileCardResponse(buffer) {
+    const packet = fromBinary(PacketSchema, buffer);
+
+    if (!packet.payload) {
+      return {
+        success: false,
+        error: 'No payload in response'
+      };
+    }
+
+    if (packet.status && packet.status !== 0) {
+      return {
+        success: false,
+        error: `Packet status: ${packet.status}`
+      };
+    }
+
+    const payload = Buffer.from(packet.payload);
+    return this.parseUserProfileCardPayload(payload);
+  }
+
+  /**
+   * Parse user profile card payload from cmd=5017 response
+   *
+   * Known top-level fields (inferred from recordings):
+   *   - field 2: org/tenant display name
+   *   - field 3: description (profile signature)
+   *   - field 5: email
+   *   - field 7: display name
+   *   - field 11: localized display name
+   *   - field 19: avatar key
+   *   - field 22: profile user ID (string)
+   *   - field 24: alias / extra name
+   *   - field 50(repeated): profile field policy entries
+   *
+   * @param {Buffer} buffer - Payload buffer
+   * @returns {Object} Parsed result
+   */
+  static parseUserProfileCardPayload(buffer) {
+    const result = {
+      success: true,
+      orgName: null,
+      description: null,
+      email: null,
+      displayName: null,
+      displayNameLocalized: null,
+      avatarKey: null,
+      profileUserId: null,
+      alias: null,
+      profileFieldPolicies: [],
+      raw: buffer
+    };
+
+    let offset = 0;
+
+    while (offset < buffer.length) {
+      const { value: tag, bytesRead: tagBytes } = this.readVarintWithLength(buffer, offset);
+      if (!tagBytes) {
+        break;
+      }
+      offset += tagBytes;
+
+      const wireType = tag & 0x07;
+      const fieldNo = tag >> 3;
+
+      if (wireType === 2) {
+        const { value: len, bytesRead } = this.readVarintWithLength(buffer, offset);
+        offset += bytesRead;
+
+        if (offset + len > buffer.length) {
+          break;
+        }
+
+        const data = buffer.subarray(offset, offset + len);
+        offset += len;
+
+        if (fieldNo === 2) {
+          result.orgName = data.toString('utf8');
+        } else if (fieldNo === 3) {
+          result.description = data.toString('utf8');
+        } else if (fieldNo === 5) {
+          result.email = data.toString('utf8');
+        } else if (fieldNo === 7) {
+          result.displayName = data.toString('utf8');
+        } else if (fieldNo === 11) {
+          result.displayNameLocalized = data.toString('utf8');
+        } else if (fieldNo === 19) {
+          result.avatarKey = data.toString('utf8');
+        } else if (fieldNo === 22) {
+          result.profileUserId = data.toString('utf8');
+        } else if (fieldNo === 24) {
+          result.alias = data.toString('utf8');
+        } else if (fieldNo === 50) {
+          const policy = this.parseUserProfileFieldPolicy(data);
+          if (policy) {
+            result.profileFieldPolicies.push(policy);
+          }
+        }
+      } else if (wireType === 0) {
+        const { bytesRead } = this.readVarintWithLength(buffer, offset);
+        offset += bytesRead;
+      } else if (wireType === 1) {
+        offset += 8;
+      } else if (wireType === 5) {
+        offset += 4;
+      } else {
+        break;
+      }
+    }
+
+    return result;
+  }
+
+  /**
+   * Parse user profile field policy entry (field 50 in cmd=5017 response)
+   * @param {Buffer} buffer - Policy entry buffer
+   * @returns {Object|null} Parsed policy
+   */
+  static parseUserProfileFieldPolicy(buffer) {
+    const policy = {
+      key: null,
+      locale: null,
+      visible: null,
+      editable: null,
+      mode: null
+    };
+
+    let offset = 0;
+
+    while (offset < buffer.length) {
+      const { value: tag, bytesRead: tagBytes } = this.readVarintWithLength(buffer, offset);
+      if (!tagBytes) {
+        break;
+      }
+      offset += tagBytes;
+
+      const wireType = tag & 0x07;
+      const fieldNo = tag >> 3;
+
+      if (wireType === 2) {
+        const { value: len, bytesRead } = this.readVarintWithLength(buffer, offset);
+        offset += bytesRead;
+
+        if (offset + len > buffer.length) {
+          break;
+        }
+
+        const data = buffer.subarray(offset, offset + len);
+        offset += len;
+
+        if (fieldNo === 1) {
+          policy.key = data.toString('utf8');
+        } else if (fieldNo === 5) {
+          policy.locale = data.toString('utf8');
+        }
+      } else if (wireType === 0) {
+        const { value, bytesRead } = this.readVarintWithLength(buffer, offset);
+        offset += bytesRead;
+
+        if (fieldNo === 3) {
+          policy.visible = value;
+        } else if (fieldNo === 4) {
+          policy.editable = value;
+        } else if (fieldNo === 6) {
+          policy.mode = value;
+        }
+      } else if (wireType === 1) {
+        offset += 8;
+      } else if (wireType === 5) {
+        offset += 4;
+      } else {
+        break;
+      }
+    }
+
+    if (!policy.key) {
+      return null;
+    }
+
+    return policy;
+  }
+
+  /**
+   * Parse user info payload from cmd=46 response
+   * @param {Buffer} buffer - Payload buffer
+   * @returns {Object} User info
+   */
+  static parseUserInfoPayload(buffer) {
+    const result = {
+      userId: null,
+      name: null,
+      isBot: false,
+      userType: 1,  // 1=user, 2=bot
+      avatarKey: null
+    };
+
+    // Parse the protobuf structure to find key fields:
+    // - field 1 > field 2 > field 1: userId (string)
+    // - field 1 > field 2 > field 2: name (bytes, UTF-8)
+    // - field 1 > field 2 > field 9: userType (varint, 1=user, 2=bot)
+    // - field 1 > field 2 > field 17: bot info (message with field 1 = "bot")
+
+    try {
+      // Simple approach: search for key patterns in the buffer
+      const str = buffer.toString('utf8');
+
+      // Extract userId (19-digit number)
+      const userIdMatch = str.match(/\d{19}/);
+      if (userIdMatch) {
+        result.userId = userIdMatch[0];
+      }
+
+      // Check for "bot" string which indicates this is a bot
+      // The pattern is: field 17 contains a message with field 1 = "bot"
+      // In hex: 8a 01 09 0a 03 62 6f 74 (field 17, len 9, field 1, len 3, "bot")
+      const botMarker = Buffer.from([0x0a, 0x03, 0x62, 0x6f, 0x74]); // field 1, len 3, "bot"
+      if (buffer.includes(botMarker)) {
+        result.isBot = true;
+        result.userType = 2;
+      }
+
+      // Extract name - look for UTF-8 Chinese characters after userId
+      // Pattern: userId bytes followed by 0x12 (field 2) + length + name bytes
+      if (result.userId) {
+        const userIdBuf = Buffer.from(result.userId);
+        let idx = buffer.indexOf(userIdBuf);
+        while (idx !== -1) {
+          const afterUserId = idx + userIdBuf.length;
+          if (afterUserId < buffer.length && buffer[afterUserId] === 0x12) {
+            const nameLen = buffer[afterUserId + 1];
+            if (nameLen > 0 && nameLen <= 50 && afterUserId + 2 + nameLen <= buffer.length) {
+              const nameBytes = buffer.subarray(afterUserId + 2, afterUserId + 2 + nameLen);
+              try {
+                const name = nameBytes.toString('utf8');
+                // Accept Chinese characters or ASCII text
+                if (name.length > 0 && name.length <= 30) {
+                  result.name = name;
+                  break;
+                }
+              } catch (e) {
+                // ignore decoding errors
+              }
+            }
+          }
+          idx = buffer.indexOf(userIdBuf, idx + 1);
+        }
+      }
+
+      // Extract avatar key (pattern: v3_xxxx_xxx... or just alphanumeric key)
+      const avatarKeyMatch = str.match(/v3_[a-z0-9]{4}_[a-f0-9-]+/i);
+      if (avatarKeyMatch) {
+        result.avatarKey = avatarKeyMatch[0];
+      } else {
+        // Try simpler pattern for bot avatars
+        const simpleKeyMatch = str.match(/[a-f0-9]{20,}/);
+        if (simpleKeyMatch) {
+          result.avatarKey = simpleKeyMatch[0];
+        }
+      }
+
+    } catch (e) {
+      return { success: false, error: e.message };
+    }
+
+    return { success: true, ...result };
+  }
+
+  // ==================== Calendar Event API ====================
+
+  /**
+   * RSVP status constants for calendar events
+   */
+  static RSVP_STATUS = {
+    ACCEPT: 1,     // 接受
+    DECLINE: 2,    // 拒绝
+    TENTATIVE: 3   // 待定
+  };
+
+  /**
+   * Build protobuf message for calendar event RSVP (cmd=1020002)
+   * @param {string} requestId - Request ID
+   * @param {string} eventId - Calendar event ID (UUID format)
+   * @param {string} userId - Current user ID
+   * @param {number} rsvpStatus - RSVP status: 1=accept, 2=decline, 3=tentative
+   * @returns {Buffer} Serialized protobuf message
+   */
+  static buildCalendarRsvpRequest(requestId, eventId, userId, rsvpStatus) {
+    const parts = [];
+
+    // Inner payload structure:
+    // field 1: nested message with eventId, userId
+    //   field 1: eventId (string)
+    //   field 2: userId (string)
+    //   field 3: 0
+    // field 2: rsvpStatus (varint)
+    // field 5: 1
+    // field 6: 1
+
+    // Build inner nested message (field 1)
+    const innerParts = [];
+
+    // field 1: eventId
+    const eventIdBytes = new TextEncoder().encode(eventId);
+    innerParts.push(0x0a); // field 1, wire type 2
+    pushVarintLength(innerParts, eventIdBytes.length);
+    innerParts.push(...eventIdBytes);
+
+    // field 2: userId
+    const userIdBytes = new TextEncoder().encode(userId);
+    innerParts.push(0x12); // field 2, wire type 2
+    pushVarintLength(innerParts, userIdBytes.length);
+    innerParts.push(...userIdBytes);
+
+    // field 3: 0
+    innerParts.push(0x18, 0x00); // field 3, wire type 0, value 0
+
+    const innerMessage = new Uint8Array(innerParts);
+
+    // Build payload
+    // field 1: inner message
+    parts.push(0x0a); // field 1, wire type 2
+    pushVarintLength(parts, innerMessage.length);
+    parts.push(...innerMessage);
+
+    // field 2: rsvpStatus
+    parts.push(0x10); // field 2, wire type 0
+    parts.push(rsvpStatus);
+
+    // field 5: 1
+    parts.push(0x28, 0x01); // field 5, wire type 0, value 1
+
+    // field 6: 1
+    parts.push(0x30, 0x01); // field 6, wire type 0, value 1
+
+    const payload = new Uint8Array(parts);
+
+    // Build outer Packet
+    const packet = create(PacketSchema, {
+      payloadType: 1, // PB2
+      cmd: 1020002,
+      cid: requestId,
+      payload: payload
+    });
+
+    return Buffer.from(toBinary(PacketSchema, packet));
+  }
+
+  /**
+   * Build protobuf message for getting calendar event detail (cmd=1010048)
+   * @param {string} requestId - Request ID
+   * @param {string} userId - Current user ID
+   * @param {number} timestamp - Timestamp for version/cursor (optional, use 0 or current timestamp)
+   * @returns {Buffer} Serialized protobuf message
+   */
+  static buildCalendarEventDetailRequest(requestId, userId, timestamp = 0) {
+    const parts = [];
+
+    // Inner payload structure (from recording):
+    // field 1: nested message
+    //   field 1: userId (string)
+    //   field 2: timestamp (varint, signed)
+    //   field 4: 0
+    //   field 5: 1
+    //   field 6: 3
+
+    // Build inner nested message
+    const innerParts = [];
+
+    // field 1: userId
+    const userIdBytes = new TextEncoder().encode(userId);
+    innerParts.push(0x0a); // field 1, wire type 2
+    pushVarintLength(innerParts, userIdBytes.length);
+    innerParts.push(...userIdBytes);
+
+    // field 2: timestamp (signed varint) - using zigzag encoding for negative values
+    // From hex: 10b9b8da86ddb59203 = field 2, value = negative number
+    // We'll use 0 or a positive timestamp for simplicity
+    if (timestamp !== 0) {
+      innerParts.push(0x10); // field 2, wire type 0
+      // Encode as zigzag for negative support
+      const zigzag = (timestamp << 1) ^ (timestamp >> 31);
+      this.pushVarint(innerParts, zigzag);
+    }
+
+    // field 4: 0
+    innerParts.push(0x20, 0x00); // field 4, wire type 0, value 0
+
+    // field 5: 1
+    innerParts.push(0x28, 0x01); // field 5, wire type 0, value 1
+
+    // field 6: 3
+    innerParts.push(0x30, 0x03); // field 6, wire type 0, value 3
+
+    const innerMessage = new Uint8Array(innerParts);
+
+    // Build payload
+    // field 1: inner message
+    parts.push(0x0a); // field 1, wire type 2
+    pushVarintLength(parts, innerMessage.length);
+    parts.push(...innerMessage);
+
+    const payload = new Uint8Array(parts);
+
+    // Build outer Packet
+    const packet = create(PacketSchema, {
+      payloadType: 1, // PB2
+      cmd: 1010048,
+      cid: requestId,
+      payload: payload
+    });
+
+    return Buffer.from(toBinary(PacketSchema, packet));
+  }
+
+  /**
+   * Push varint bytes to array
+   * @param {Array} arr - Target array
+   * @param {number} value - Value to encode
+   */
+  static pushVarint(arr, value) {
+    while (value > 127) {
+      arr.push((value & 0x7f) | 0x80);
+      value >>>= 7;
+    }
+    arr.push(value);
+  }
+
+  /**
+   * Push bigint varint bytes to array
+   * @param {Array} arr - Target array
+   * @param {bigint} value - BigInt value
+   */
+  static pushVarintBigInt(arr, value) {
+    let current = BigInt(value);
+
+    while (current > 127n) {
+      arr.push(Number((current & 0x7fn) | 0x80n));
+      current >>= 7n;
+    }
+
+    arr.push(Number(current));
+  }
+
+  /**
+   * Decode calendar event RSVP response (cmd=1020002)
+   * @param {Buffer} buffer - Response buffer
+   * @returns {Object} { success: boolean, error?: string }
+   */
+  static decodeCalendarRsvpResponse(buffer) {
+    try {
+      const packet = fromBinary(PacketSchema, buffer);
+
+      // Check status
+      if (packet.status && packet.status !== 0) {
+        // 尝试从 payload 中提取错误消息
+        if (packet.payload && packet.payload.length > 0) {
+          const errorMsg = this.extractErrorMessage(packet.payload);
+          if (errorMsg) {
+            return { success: false, error: errorMsg };
+          }
+        }
+        return { success: false, error: `Status: ${packet.status}` };
+      }
+
+      return { success: true };
+    } catch (e) {
+      // 如果 protobuf 解析失败，尝试直接从 buffer 提取错误消息
+      const errorMsg = this.extractErrorMessage(buffer);
+      if (errorMsg) {
+        return { success: false, error: errorMsg };
+      }
+      return { success: false, error: e.message };
+    }
+  }
+
+  /**
+   * 从 protobuf payload 中提取错误消息字符串
+   * @param {Uint8Array|Buffer} payload
+   * @returns {string|null}
+   */
+  static extractErrorMessage(payload) {
+    try {
+      // 错误响应格式: 0a <len> <error_string> ...
+      // field 1, wire type 2 (length-delimited string)
+      if (payload[0] === 0x0a && payload.length > 2) {
+        const len = payload[1];
+        if (len > 0 && len < payload.length - 2) {
+          const msg = Buffer.from(payload.slice(2, 2 + len)).toString('utf8');
+          // 只返回看起来像错误消息的字符串
+          if (/^[A-Za-z][A-Za-z0-9_]+$/.test(msg)) {
+            return msg;
+          }
+        }
+      }
+    } catch (e) {
+      // ignore
+    }
+    return null;
+  }
+
+  /**
+   * Decode calendar event detail response (cmd=1010048)
+   * @param {Buffer} buffer - Response buffer
+   * @returns {Object} Calendar event details
+   */
+  static decodeCalendarEventDetailResponse(buffer) {
+    try {
+      const packet = fromBinary(PacketSchema, buffer);
+
+      if (!packet.payload || packet.payload.length < 10) {
+        return { success: false, error: 'Empty payload', events: [] };
+      }
+
+      const events = this.parseCalendarEventPayload(Buffer.from(packet.payload));
+
+      return {
+        success: true,
+        events: events
+      };
+    } catch (e) {
+      return { success: false, error: e.message, events: [] };
+    }
+  }
+
+  /**
+   * Parse calendar event payload to extract event details
+   * @param {Buffer} buffer - Payload buffer
+   * @returns {Array} Array of calendar events
+   */
+  static parseCalendarEventPayload(buffer) {
+    const events = [];
+    let offset = 0;
+
+    // Skip outer wrapper fields to find event data
+    // Structure: field 1 (user info), field 2 (events repeated)
+
+    while (offset < buffer.length) {
+      const { value: tag, bytesRead: tagBytes } = this.readVarintWithLength(buffer, offset);
+      if (tagBytes === 0) break;
+      offset += tagBytes;
+
+      const wireType = tag & 0x07;
+      const fieldNo = tag >> 3;
+
+      if (wireType === 2) { // Length-delimited
+        const { value: len, bytesRead } = this.readVarintWithLength(buffer, offset);
+        offset += bytesRead;
+
+        if (offset + len > buffer.length) break;
+
+        const data = buffer.subarray(offset, offset + len);
+        offset += len;
+
+        // field 2 contains the event data
+        if (fieldNo === 2) {
+          const event = this.parseCalendarEvent(data);
+          if (event) {
+            events.push(event);
+          }
+        }
+      } else if (wireType === 0) { // Varint
+        const { bytesRead } = this.readVarintWithLength(buffer, offset);
+        offset += bytesRead;
+      } else {
+        break;
+      }
+    }
+
+    return events;
+  }
+
+  /**
+   * Parse a single calendar event from protobuf bytes
+   * @param {Buffer} buffer - Event data buffer
+   * @returns {Object} Calendar event object
+   */
+  static parseCalendarEvent(buffer) {
+    const event = {
+      userId: null,
+      eventId: null,
+      title: null,
+      startTime: null,
+      endTime: null,
+      timezone: null,
+      organizer: null,
+      attendees: [],
+      meetingUrl: null,
+      rsvpStatus: null // 当前用户的回复状态
+    };
+
+    let offset = 0;
+
+    while (offset < buffer.length) {
+      const { value: tag, bytesRead: tagBytes } = this.readVarintWithLength(buffer, offset);
+      if (tagBytes === 0) break;
+      offset += tagBytes;
+
+      const wireType = tag & 0x07;
+      const fieldNo = tag >> 3;
+
+      if (wireType === 2) { // Length-delimited
+        const { value: len, bytesRead } = this.readVarintWithLength(buffer, offset);
+        offset += bytesRead;
+
+        if (offset + len > buffer.length) break;
+
+        const data = buffer.subarray(offset, offset + len);
+        offset += len;
+
+        // field 1: userId
+        if (fieldNo === 1) {
+          event.userId = data.toString('utf8');
+        }
+        // field 2: eventId (UUID)
+        else if (fieldNo === 2) {
+          event.eventId = data.toString('utf8');
+        }
+        // field 4: nested event details
+        else if (fieldNo === 4) {
+          this.parseEventDetails(data, event);
+        }
+        // field 5: user RSVP info
+        else if (fieldNo === 5) {
+          const rsvp = this.parseRsvpInfo(data);
+          if (rsvp) {
+            event.rsvpStatus = rsvp.status;
+          }
+        }
+        // field 20: attendee info (repeated)
+        else if (fieldNo === 20) {
+          const attendee = this.parseAttendeeInfo(data);
+          if (attendee) {
+            event.attendees.push(attendee);
+          }
+        }
+      } else if (wireType === 0) { // Varint
+        const { value, bytesRead } = this.readVarintWithLength(buffer, offset);
+        offset += bytesRead;
+      } else {
+        break;
+      }
+    }
+
+    // Only return if we have meaningful data
+    if (event.eventId || event.title) {
+      return event;
+    }
+
+    return null;
+  }
+
+  /**
+   * Parse nested event details (field 4 in event)
+   * @param {Buffer} buffer - Event details buffer
+   * @param {Object} event - Event object to populate
+   */
+  static parseEventDetails(buffer, event) {
+    let offset = 0;
+
+    while (offset < buffer.length) {
+      const { value: tag, bytesRead: tagBytes } = this.readVarintWithLength(buffer, offset);
+      if (tagBytes === 0) break;
+      offset += tagBytes;
+
+      const wireType = tag & 0x07;
+      const fieldNo = tag >> 3;
+
+      if (wireType === 2) { // Length-delimited (string)
+        const { value: len, bytesRead } = this.readVarintWithLength(buffer, offset);
+        offset += bytesRead;
+
+        if (offset + len > buffer.length) break;
+
+        const data = buffer.subarray(offset, offset + len);
+        offset += len;
+
+        // field 8: title
+        if (fieldNo === 8) {
+          event.title = data.toString('utf8');
+        }
+        // field 12: startTimezone
+        else if (fieldNo === 12) {
+          event.timezone = data.toString('utf8');
+        }
+        // field 14: endTimezone (usually same as start)
+        // Skip for now
+      } else if (wireType === 0) { // Varint
+        const { value, bytesRead } = this.readVarintWithLength(buffer, offset);
+        offset += bytesRead;
+
+        // field 11: startTime (Unix timestamp)
+        if (fieldNo === 11) {
+          event.startTime = value;
+        }
+        // field 13: endTime (Unix timestamp)
+        else if (fieldNo === 13) {
+          event.endTime = value;
+        }
+      } else {
+        break;
+      }
+    }
+  }
+
+  /**
+   * Parse RSVP info (field 5 in event)
+   * @param {Buffer} buffer - RSVP buffer
+   * @returns {Object} { userId, status }
+   */
+  static parseRsvpInfo(buffer) {
+    const result = { userId: null, status: null };
+    let offset = 0;
+
+    while (offset < buffer.length) {
+      const { value: tag, bytesRead: tagBytes } = this.readVarintWithLength(buffer, offset);
+      if (tagBytes === 0) break;
+      offset += tagBytes;
+
+      const wireType = tag & 0x07;
+      const fieldNo = tag >> 3;
+
+      if (wireType === 2) { // Length-delimited
+        const { value: len, bytesRead } = this.readVarintWithLength(buffer, offset);
+        offset += bytesRead;
+
+        if (offset + len > buffer.length) break;
+
+        const data = buffer.subarray(offset, offset + len);
+        offset += len;
+
+        // field 2: userId
+        if (fieldNo === 2) {
+          result.userId = data.toString('utf8');
+        }
+      } else if (wireType === 0) { // Varint
+        const { value, bytesRead } = this.readVarintWithLength(buffer, offset);
+        offset += bytesRead;
+
+        // field 3: status (2 = pending response, etc.)
+        if (fieldNo === 3) {
+          result.status = value;
+        }
+      } else {
+        break;
+      }
+    }
+
+    return result;
+  }
+
+  /**
+   * Parse attendee info (field 20 in event, repeated)
+   * @param {Buffer} buffer - Attendee buffer
+   * @returns {Object} { name, userId, rsvpStatus, type }
+   */
+  static parseAttendeeInfo(buffer) {
+    const attendee = { name: null, userId: null, rsvpStatus: null, type: null };
+    let offset = 0;
+
+    while (offset < buffer.length) {
+      const { value: tag, bytesRead: tagBytes } = this.readVarintWithLength(buffer, offset);
+      if (tagBytes === 0) break;
+      offset += tagBytes;
+
+      const wireType = tag & 0x07;
+      const fieldNo = tag >> 3;
+
+      if (wireType === 2) { // Length-delimited
+        const { value: len, bytesRead } = this.readVarintWithLength(buffer, offset);
+        offset += bytesRead;
+
+        if (offset + len > buffer.length) break;
+
+        const data = buffer.subarray(offset, offset + len);
+        offset += len;
+
+        // field 1: name
+        if (fieldNo === 1) {
+          attendee.name = data.toString('utf8');
+        }
+        // field 2: userId
+        else if (fieldNo === 2) {
+          attendee.userId = data.toString('utf8');
+        }
+        // field 11: nested type info
+        else if (fieldNo === 11) {
+          // Parse nested to get type string (e.g., "INDIVIDUAL")
+          const typeStr = this.extractTypeFromNested(data);
+          if (typeStr) {
+            attendee.type = typeStr;
+          }
+        }
+      } else if (wireType === 0) { // Varint
+        const { value, bytesRead } = this.readVarintWithLength(buffer, offset);
+        offset += bytesRead;
+
+        // field 3: rsvpStatus (0=not responded, 1=accepted, etc.)
+        if (fieldNo === 3) {
+          attendee.rsvpStatus = value;
+        }
+      } else {
+        break;
+      }
+    }
+
+    return attendee.name || attendee.userId ? attendee : null;
+  }
+
+  /**
+   * Extract type string from nested message
+   * @param {Buffer} buffer - Nested buffer
+   * @returns {string|null} Type string
+   */
+  static extractTypeFromNested(buffer) {
+    let offset = 0;
+
+    while (offset < buffer.length) {
+      const { value: tag, bytesRead: tagBytes } = this.readVarintWithLength(buffer, offset);
+      if (tagBytes === 0) break;
+      offset += tagBytes;
+
+      const wireType = tag & 0x07;
+      const fieldNo = tag >> 3;
+
+      if (wireType === 2) { // Length-delimited
+        const { value: len, bytesRead } = this.readVarintWithLength(buffer, offset);
+        offset += bytesRead;
+
+        if (offset + len > buffer.length) break;
+
+        const data = buffer.subarray(offset, offset + len);
+        offset += len;
+
+        // field 2 is usually the type string
+        if (fieldNo === 2) {
+          return data.toString('utf8');
+        }
+      } else if (wireType === 0) {
+        const { bytesRead } = this.readVarintWithLength(buffer, offset);
+        offset += bytesRead;
+      } else {
+        break;
+      }
+    }
+
+    return null;
+  }
+
+  // ==================== Smart Reply Resource (cmd=77 wrapper) ====================
+
+  /**
+   * Build office_ai.PullSmartReplyResourceRequest payload (inner cmd=1105047)
+   *
+   * message PullSmartReplyResourceRequest {
+   *   repeated string image_keys = 1;
+   * }
+   *
+   * @param {string[]} imageKeys - Image keys (img_v2/img_v3)
+   * @returns {Uint8Array} Encoded protobuf payload
+   */
+  static buildPullSmartReplyResourceRequestPayload(imageKeys) {
+    const keys = [...new Set((imageKeys || [])
+      .map(key => String(key || '').trim())
+      .filter(key => /^img_v[23]_/.test(key)))];
+
+    const parts = [];
+
+    for (const imageKey of keys) {
+      const keyBytes = Buffer.from(imageKey, 'utf8');
+      parts.push(0x0a); // field 1, wire type 2
+      pushVarintLength(parts, keyBytes.length);
+      parts.push(...keyBytes);
+    }
+
+    return new Uint8Array(parts);
+  }
+
+  /**
+   * Build cmd=77 wrapper request for pulling smart-reply image resources
+   *
+   * Wrapper entry shape (inferred):
+   *   field 2 = payloadType (1)
+   *   field 3 = inner command (1105047)
+   *   field 5 = inner payload bytes
+   *   field 6 = inner request id (string)
+   *
+   * @param {string} requestId - Outer request ID (x-request-id)
+   * @param {string[]} imageKeys - Image keys to fetch resource crypto for
+   * @param {Object} [options]
+   * @param {string} [options.subRequestId] - Inner request ID
+   * @returns {Buffer} Encoded cmd=77 packet
+   */
+  static buildCmd77PullSmartReplyResourceRequest(requestId, imageKeys, options = {}) {
+    const payload = this.buildPullSmartReplyResourceRequestPayload(imageKeys);
+    const subRequestId = typeof options.subRequestId === 'string' && options.subRequestId.trim()
+      ? options.subRequestId.trim()
+      : ((globalThis.crypto?.randomUUID?.() || generateRequestCid()).toUpperCase());
+
+    const entryParts = [];
+
+    // field 2: payloadType = 1
+    entryParts.push(0x10, 0x01);
+
+    // field 3: inner command = 1105047
+    entryParts.push(0x18);
+    pushVarintLength(entryParts, 1105047);
+
+    // field 5: inner payload bytes
+    entryParts.push(0x2a);
+    pushVarintLength(entryParts, payload.length);
+    entryParts.push(...payload);
+
+    // field 6: inner request id
+    const subRequestIdBytes = Buffer.from(subRequestId, 'utf8');
+    entryParts.push(0x32);
+    pushVarintLength(entryParts, subRequestIdBytes.length);
+    entryParts.push(...subRequestIdBytes);
+
+    // outer field 1: repeated wrapped packets
+    const outerParts = [0x0a];
+    pushVarintLength(outerParts, entryParts.length);
+    outerParts.push(...entryParts);
+
+    const packet = create(PacketSchema, {
+      payloadType: 1, // PB2
+      cmd: 77,
+      cid: requestId,
+      payload: new Uint8Array(outerParts)
+    });
+
+    return Buffer.from(toBinary(PacketSchema, packet));
+  }
+
+  /**
+   * Build direct cmd=1105047 request packet
+   *
+   * @param {string} requestId - Request ID
+   * @param {string[]} imageKeys - Image keys
+   * @returns {Buffer} Encoded cmd=1105047 packet
+   */
+  static buildPullSmartReplyResourceRequest(requestId, imageKeys) {
+    const payload = this.buildPullSmartReplyResourceRequestPayload(imageKeys);
+
+    const packet = create(PacketSchema, {
+      payloadType: 1, // PB2
+      cmd: 1105047,
+      cid: requestId,
+      payload
+    });
+
+    return Buffer.from(toBinary(PacketSchema, packet));
+  }
+
+  // ==================== Chat History (cmd=43) ====================
+
+  /**
+   * Build request to get chat history by message positions
+   * @param {string} requestId - Request ID
+   * @param {string} chatId - Chat ID (19-digit number string)
+   * @param {number[]} positions - Array of message position numbers to fetch
+   * @returns {Buffer} Encoded packet
+   */
+  static buildGetChatHistoryRequest(requestId, chatId, positions) {
+    const payload = create(GetChatHistoryRequestSchema, {
+      chatId: chatId,
+      positions: positions,
+      flag1: 1,
+      flag2: 1,
+      flag3: 2,
+      flag4: 1
+    });
+
+    const packet = create(PacketSchema, {
+      payloadType: 1, // PB2
+      cmd: 43,
+      cid: requestId,
+      payload: toBinary(GetChatHistoryRequestSchema, payload)
+    });
+
+    return Buffer.from(toBinary(PacketSchema, packet));
+  }
+
+  /**
+   * Build emoji reaction request (cmd=25)
+   *
+   * Inner payload structure:
+   *   field 1 (string): messageId
+   *   field 2 (string): emoji type (e.g., "THUMBSUP", "SMILE", "HEART")
+   *   field 3 (varint): action type (1=add)
+   *
+   * @param {string} requestId - Request ID
+   * @param {string} messageId - Message ID to react to
+   * @param {string} emojiType - Emoji type string (e.g., "THUMBSUP")
+   * @returns {Buffer} Serialized packet
+   */
+  static buildEmojiReactionRequest(requestId, messageId, emojiType) {
+    const messageIdBytes = Buffer.from(messageId, 'utf-8');
+    const emojiTypeBytes = Buffer.from(emojiType, 'utf-8');
+
+    const innerParts = [];
+    // field 1 (string): messageId
+    innerParts.push(0x0a);
+    pushVarintLength(innerParts, messageIdBytes.length);
+    innerParts.push(...messageIdBytes);
+    // field 2 (string): emoji type
+    innerParts.push(0x12);
+    pushVarintLength(innerParts, emojiTypeBytes.length);
+    innerParts.push(...emojiTypeBytes);
+    // field 3 (varint): action = 1 (add)
+    innerParts.push(0x18, 0x01);
+
+    const packet = create(PacketSchema, {
+      payloadType: 1,
+      cmd: 25,
+      cid: requestId,
+      payload: new Uint8Array(innerParts)
+    });
+
+    return Buffer.from(toBinary(PacketSchema, packet));
+  }
+
+  /**
+   * Decode emoji reaction response (cmd=25)
+   *
+   * Response payload structure:
+   *   field 1 (varint): result code (1=success)
+   *
+   * @param {Buffer} buffer - Response buffer
+   * @returns {Object} { success: boolean, error?: string }
+   */
+  static decodeEmojiReactionResponse(buffer) {
+    try {
+      const packet = fromBinary(PacketSchema, buffer);
+
+      if (packet.status && packet.status !== 0) {
+        return {
+          success: false,
+          error: `Packet status: ${packet.status}`
+        };
+      }
+
+      return { success: true };
+    } catch (error) {
+      return {
+        success: false,
+        error: error.message
+      };
+    }
+  }
+
+  /**
+   * Build remove emoji reaction request (cmd=26)
+   *
+   * Inner payload structure (identical to cmd=25):
+   *   field 1 (string): messageId
+   *   field 2 (string): emojiType
+   *   field 3 (varint): action = 1
+   *
+   * @param {string} requestId - Request ID
+   * @param {string} messageId - Message ID to remove reaction from
+   * @param {string} emojiType - Emoji type string (e.g., "THUMBSUP")
+   * @returns {Buffer} Serialized packet
+   */
+  static buildRemoveEmojiReactionRequest(requestId, messageId, emojiType) {
+    const messageIdBytes = Buffer.from(messageId, 'utf-8');
+    const emojiTypeBytes = Buffer.from(emojiType, 'utf-8');
+
+    const innerParts = [];
+    // field 1 (string): messageId
+    innerParts.push(0x0a);
+    pushVarintLength(innerParts, messageIdBytes.length);
+    innerParts.push(...messageIdBytes);
+    // field 2 (string): emoji type
+    innerParts.push(0x12);
+    pushVarintLength(innerParts, emojiTypeBytes.length);
+    innerParts.push(...emojiTypeBytes);
+    // field 3 (varint): action = 1
+    innerParts.push(0x18, 0x01);
+
+    const packet = create(PacketSchema, {
+      payloadType: 1,
+      cmd: 26,
+      cid: requestId,
+      payload: new Uint8Array(innerParts)
+    });
+
+    return Buffer.from(toBinary(PacketSchema, packet));
+  }
+
+  /**
+   * Decode remove emoji reaction response (cmd=26)
+   *
+   * Response payload is empty for delete operations.
+   * Only checks packet.status === 0 for success.
+   *
+   * @param {Buffer} buffer - Response buffer
+   * @returns {Object} { success: boolean, error?: string }
+   */
+  static decodeRemoveEmojiReactionResponse(buffer) {
+    try {
+      const packet = fromBinary(PacketSchema, buffer);
+
+      if (packet.status && packet.status !== 0) {
+        return {
+          success: false,
+          error: `Packet status: ${packet.status}`
+        };
+      }
+
+      return { success: true };
+    } catch (error) {
+      return {
+        success: false,
+        error: error.message
+      };
+    }
+  }
+
+  /**
+   * Build request to get chat meta by chatId (cmd=64)
+   *
+   * Payload structure:
+   *   field 1 = chatId (string)
+   *
+   * @param {string} requestId - Request ID
+   * @param {string} chatId - Chat ID (19-digit number string)
+   * @returns {Buffer} Encoded packet
+   */
+  static buildGetChatMetaRequest(requestId, chatId) {
+    const chatIdBytes = Buffer.from(chatId, 'utf-8');
+    const innerParts = [0x0a]; // field 1 (length-delimited)
+    pushVarintLength(innerParts, chatIdBytes.length);
+    innerParts.push(...chatIdBytes);
+
+    const packet = create(PacketSchema, {
+      payloadType: 1, // PB2
+      cmd: 64,
+      cid: requestId,
+      payload: new Uint8Array(innerParts)
+    });
+
+    return Buffer.from(toBinary(PacketSchema, packet));
+  }
+
+  /**
+   * Decode chat meta response (cmd=64)
+   *
+   * Response payload structure (inferred):
+   *   field 1 (message)
+   *     - field 1: chatId (string)
+   *     - field 2: Chat message bytes
+   *
+   * @param {Buffer} buffer - Response buffer
+   * @returns {Object} Decoded chat meta result
+   */
+  static decodeGetChatMetaResponse(buffer) {
+    try {
+      const packet = fromBinary(PacketSchema, buffer);
+
+      if (!packet.payload || packet.payload.length === 0) {
+        return {
+          success: false,
+          error: 'Empty payload'
+        };
+      }
+
+      const payloadBuffer = Buffer.from(packet.payload);
+      const outerEntry = this.extractLengthDelimitedField(payloadBuffer, 1);
+
+      if (!outerEntry) {
+        return {
+          success: false,
+          error: 'No chat meta entry in payload'
+        };
+      }
+
+      const entryBuffer = Buffer.from(outerEntry);
+      const chatIdBytes = this.extractLengthDelimitedField(entryBuffer, 1);
+      const chatBytes = this.extractLengthDelimitedField(entryBuffer, 2);
+
+      if (!chatBytes) {
+        return {
+          success: false,
+          error: 'No chat bytes in chat meta entry'
+        };
+      }
+
+      const chat = fromBinary(ChatSchema, chatBytes);
+
+      return {
+        success: true,
+        chat: {
+          id: chat.id || (chatIdBytes ? Buffer.from(chatIdBytes).toString('utf8') : ''),
+          type: chat.type,
+          name: chat.name || '',
+          ownerId: chat.ownerId || '',
+          lastMessageId: chat.lastMessageId || '',
+          lastVisibleMessageId: chat.lastVisibleMessageId || '',
+          lastMessagePosition: chat.lastMessagePosition || 0,
+          lastVisibleMessagePosition: chat.lastVisibleMessagePosition || 0,
+          readPosition: chat.readPosition || 0,
+          readPositionBadgeCount: chat.readPositionBadgeCount || 0,
+          lastMessagePositionBadgeCount: chat.lastMessagePositionBadgeCount || 0,
+          newMessageCount: chat.newMessageCount || 0,
+          noBadgedNewMessageCount: chat.noBadgedNewMessageCount || 0,
+          firstChatMessagePosition: chat.firstChatMessagePosition || 0,
+          updateTime: Number(chat.updateTime || 0n),
+          updateTimeMs: Number(chat.updateTimeMs || 0n),
+          createTime: Number(chat.createTime || 0n),
+          memberCount: chat.memberCount || 0,
+          userCount: chat.userCount || 0,
+          role: chat.role,
+          status: chat.status,
+          chatMode: chat.chatMode,
+          allowPost: chat.allowPost,
+        }
+      };
+    } catch (error) {
+      return {
+        success: false,
+        error: error.message
+      };
+    }
+  }
+
+  /**
+   * Extract first length-delimited field bytes by field number
+   * @param {Buffer} buffer - Protobuf message buffer
+   * @param {number} targetFieldNo - Target field number
+   * @returns {Uint8Array|null} Field bytes or null
+   */
+  static extractLengthDelimitedField(buffer, targetFieldNo) {
+    let offset = 0;
+
+    while (offset < buffer.length) {
+      const { value: tag, bytesRead: tagBytes } = this.readVarintWithLength(buffer, offset);
+      if (!tagBytes) break;
+      offset += tagBytes;
+
+      const wireType = tag & 0x07;
+      const fieldNo = tag >> 3;
+
+      if (wireType === 2) {
+        const { value: len, bytesRead } = this.readVarintWithLength(buffer, offset);
+        offset += bytesRead;
+
+        if (offset + len > buffer.length) {
+          break;
+        }
+
+        const data = buffer.subarray(offset, offset + len);
+        offset += len;
+
+        if (fieldNo === targetFieldNo) {
+          return data;
+        }
+      } else if (wireType === 0) {
+        const { bytesRead } = this.readVarintWithLength(buffer, offset);
+        offset += bytesRead;
+      } else if (wireType === 1) {
+        offset += 8;
+      } else if (wireType === 5) {
+        offset += 4;
+      } else {
+        break;
+      }
+    }
+
+    return null;
+  }
+
+  /**
+   * Try to decode bytes as UTF-8 string.
+   * Returns the string if it looks like valid text (no replacement chars), or empty string.
+   * @param {Uint8Array|Buffer|null|undefined} bytes
+   * @returns {string}
+   */
+  static tryDecodeAsUtf8(bytes) {
+    if (!bytes || bytes.length === 0) return '';
+    try {
+      const str = Buffer.from(bytes).toString('utf8');
+      // If the result contains the UTF-8 replacement character, it's likely binary data
+      if (str.includes('\ufffd')) return '';
+      return str;
+    } catch {
+      return '';
+    }
+  }
+
+  /**
+   * 从文本中提取飞书图片 key（支持 img_v2/img_v3）
+   * @param {string} value
+   * @returns {string[]}
+   */
+  static extractImageKeysFromString(value) {
+    const source = String(value || '');
+
+    const strictV3 = source.match(/img_v3_[a-z0-9]{4}_[a-z0-9]{8}-[a-z0-9]{4}-[a-z0-9]{4}-[a-z0-9]{4}-[a-z0-9]{12}/gi) || [];
+    const strictV2 = source.match(/img_v2_[a-z0-9]{8}-[a-z0-9]{4}-[a-z0-9]{4}-[a-z0-9]{4}-[a-z0-9]{12}/gi) || [];
+    const strictMatches = [...strictV3, ...strictV2];
+
+    // 优先使用严格格式，避免把相邻 key 粘连成一个
+    if (strictMatches.length > 0) {
+      return [...new Set(strictMatches)];
+    }
+
+    // 回退：按 img_v2_/img_v3_ 起始切分，逐段提取
+    const parts = source.split(/(?=img_v[23]_)/g).filter(part => /^img_v[23]_/.test(part));
+    const keys = [];
+
+    for (const part of parts) {
+      const strictPart = part.match(/^(img_v3_[a-z0-9]{4}_[a-z0-9]{8}-[a-z0-9]{4}-[a-z0-9]{4}-[a-z0-9]{4}-[a-z0-9]{12}|img_v2_[a-z0-9]{8}-[a-z0-9]{4}-[a-z0-9]{4}-[a-z0-9]{4}-[a-z0-9]{12})/i);
+      if (strictPart) {
+        keys.push(strictPart[1]);
+        continue;
+      }
+
+      const match = part.match(/^img_v[23]_[a-zA-Z0-9_-]+/);
+      if (!match) continue;
+
+      const candidate = match[0];
+      if (candidate.length < 20 || candidate.length > 80) continue;
+      keys.push(candidate);
+    }
+
+    return [...new Set(keys)];
+  }
+
+  /**
+   * 尝试从 chat history content 的 bytes 中解析图片信息
+   * @param {Uint8Array|Buffer|null|undefined} payload
+   * @param {(imageInfo: {imageKey: string, cryptoInfo?: object|null}) => void} addImageInfo
+   */
+  static tryDecodeChatHistoryImagePayload(payload, addImageInfo) {
+    if (!payload || payload.length === 0) {
+      return;
+    }
+
+    const bytes = payload instanceof Uint8Array ? payload : new Uint8Array(payload);
+
+    // 1) 直接按 ImageSetV2 解析（chat history 中 IMAGE 消息的 field 2）
+    try {
+      const imageV2 = fromBinary(ImageSetV2Schema, bytes);
+      if (imageV2.imageKey) {
+        const imageInfo = {
+          imageKey: imageV2.imageKey,
+          cryptoInfo: imageV2.crypto ? this.extractCryptoInfo(imageV2.crypto) : null,
+          fsUnit: imageV2.fsUnit || null,
+        };
+        addImageInfo(imageInfo);
+      }
+    } catch {
+      // ignore
+    }
+
+    // 2) 按 ImageContent 解析（图片消息）
+    try {
+      const imageContent = fromBinary(ImageContentSchema, bytes);
+      const imageInfo = this.extractImageInfo(imageContent);
+      if (imageInfo?.imageKey) {
+        addImageInfo(imageInfo);
+      }
+    } catch {
+      // ignore
+    }
+
+    // 3) 按 Content 解析（富文本/混合消息）
+    try {
+      const content = fromBinary(ContentSchema, bytes);
+
+      if (content.imageKey) {
+        addImageInfo({ imageKey: content.imageKey, cryptoInfo: null });
+      }
+
+      if (content.richText) {
+        const postResult = this.parsePostContent(content);
+        for (const imageInfo of postResult.images || []) {
+          if (imageInfo?.imageKey) {
+            addImageInfo(imageInfo);
+          }
+        }
+      }
+    } catch {
+      // ignore
+    }
+
+    // 4) 按 RichText 直接解析（某些历史消息会把 richText 放在 bytes 字段）
+    try {
+      const richText = fromBinary(RichTextSchema, bytes);
+      const postResult = this.parsePostContent({ richText, text: richText.innerText || '' });
+      for (const imageInfo of postResult.images || []) {
+        if (imageInfo?.imageKey) {
+          addImageInfo(imageInfo);
+        }
+      }
+    } catch {
+      // ignore
+    }
+
+    // 5) 按 RichTextElements 直接解析（再下一层）
+    try {
+      const elements = fromBinary(RichTextElementsSchema, bytes);
+      if (elements?.dictionary) {
+        for (const element of Object.values(elements.dictionary)) {
+          if (element?.tag === 2 && element.property) {
+            const imageInfo = this.parseImageProperty(element.property);
+            if (imageInfo?.imageKey) {
+              addImageInfo(imageInfo);
+            }
+          }
+        }
+      }
+    } catch {
+      // ignore
+    }
+  }
+
+  /**
+   * 从 chat history content 中提取图片 key/crypto
+   * @param {object} content
+   * @returns {Array<{imageKey: string, cryptoInfo?: object|null}>}
+   */
+  static collectImageInfosFromChatHistoryContent(content = {}) {
+    const imageInfos = [];
+    const seenKeys = new Set();
+
+    const addImageInfo = (imageInfo) => {
+      const imageKey = imageInfo?.imageKey ? String(imageInfo.imageKey).trim() : '';
+      if (!imageKey || seenKeys.has(imageKey)) {
+        return;
+      }
+
+      seenKeys.add(imageKey);
+      imageInfos.push({
+        imageKey,
+        cryptoInfo: imageInfo?.cryptoInfo || null,
+      });
+    };
+
+    // 从 bytes 字段中解析（可能包含 crypto）
+    this.tryDecodeChatHistoryImagePayload(content?.richTextOrImageBytes, addImageInfo);
+    this.tryDecodeChatHistoryImagePayload(content?.richTextBytes, addImageInfo);
+    this.tryDecodeChatHistoryImagePayload(content?.richTextData, addImageInfo);
+
+    // 从 text/html 回退提取 key（无 crypto）
+    const htmlText = content?.htmlText || this.tryDecodeAsUtf8(content?.richTextOrImageBytes) || '';
+    const fallbackKeys = this.extractImageKeysFromString(`${content?.text || ''}
+${htmlText}`);
+    for (const imageKey of fallbackKeys) {
+      addImageInfo({ imageKey, cryptoInfo: null });
+    }
+
+    return imageInfos;
+  }
+
+  /**
+   * Decode chat history response
+   * @param {Buffer} buffer - Response buffer
+   * @returns {Object} Decoded response with messages array
+   */
+  static decodeGetChatHistoryResponse(buffer) {
+    try {
+      const packet = fromBinary(PacketSchema, buffer);
+
+      if (!packet.payload || packet.payload.length === 0) {
+        return {
+          success: false,
+          error: 'Empty payload',
+          messages: []
+        };
+      }
+
+      // Try to decode using the schema
+      try {
+        const response = fromBinary(GetChatHistoryResponseSchema, packet.payload);
+        const messages = (response.entries || []).map(entry => {
+          const msg = entry.message || {};
+          const content = msg.content || {};
+
+          const imageInfos = this.collectImageInfosFromChatHistoryContent(content);
+          const imageKeys = imageInfos.map(info => info.imageKey).filter(Boolean);
+
+          for (const imageInfo of imageInfos) {
+            if (imageInfo.imageKey && imageInfo.cryptoInfo) {
+              cacheImageCryptoInfo(imageInfo.imageKey, imageInfo.cryptoInfo);
+            }
+          }
+
+          // Derive htmlText: field 2 is now bytes, try UTF-8 decode for POST messages
+          const htmlText = this.tryDecodeAsUtf8(content.richTextOrImageBytes) || '';
+
+          return {
+            position: entry.position,
+            messageId: msg.messageId || '',
+            type: msg.type || 0,
+            typeName: getMessageTypeName(msg.type),
+            fromId: msg.fromId || '',
+            fromType: msg.fromType || 0,
+            fromTypeName: getFromTypeName(msg.fromType),
+            chatId: msg.chatId || '',
+            cid: msg.cid || '',
+            createTime: Number(msg.createTime) || 0,
+            text: content.text || '',
+            htmlText,
+            imageKey: imageKeys[0] || '',
+            imageKeys,
+            language: msg.language || '',
+            replyCount: msg.replyCount || '0',
+            parentMsgId: msg.parentMsgId || ''
+          };
+        });
+
+        return {
+          success: true,
+          messages
+        };
+      } catch (schemaError) {
+        // Schema decode failed, try manual parsing
+        return this.manualDecodeGetChatHistoryResponse(packet.payload);
+      }
+    } catch (error) {
+      return {
+        success: false,
+        error: error.message,
+        messages: []
+      };
+    }
+  }
+
+  /**
+   * Manual decode for chat history response when schema fails
+   * @param {Uint8Array} payload - Payload bytes
+   * @returns {Object} Decoded response
+   */
+  static manualDecodeGetChatHistoryResponse(payload) {
+    const messages = [];
+    const buffer = Buffer.from(payload);
+    let offset = 0;
+
+    while (offset < buffer.length) {
+      const { value: tag, bytesRead: tagBytes } = this.readVarintWithLength(buffer, offset);
+      if (tagBytes === 0) break;
+      offset += tagBytes;
+
+      const wireType = tag & 0x07;
+      const fieldNo = tag >> 3;
+
+      if (wireType === 2) { // Length-delimited
+        const { value: len, bytesRead } = this.readVarintWithLength(buffer, offset);
+        offset += bytesRead;
+
+        if (offset + len > buffer.length) break;
+
+        const data = buffer.subarray(offset, offset + len);
+        offset += len;
+
+        // field 1 = entries (ChatMessageEntry)
+        if (fieldNo === 1) {
+          const entry = this.parseMessageEntry(data);
+          if (entry) {
+            messages.push(entry);
+          }
+        }
+      } else if (wireType === 0) {
+        const { bytesRead } = this.readVarintWithLength(buffer, offset);
+        offset += bytesRead;
+      } else {
+        break;
+      }
+    }
+
+    return {
+      success: true,
+      messages
+    };
+  }
+
+  /**
+   * Parse a single message entry from raw bytes
+   * @param {Buffer} buffer - Entry bytes
+   * @returns {Object|null} Parsed message entry
+   */
+  static parseMessageEntry(buffer) {
+    let offset = 0;
+    let position = 0;
+    let messageBytes = null;
+
+    while (offset < buffer.length) {
+      const { value: tag, bytesRead: tagBytes } = this.readVarintWithLength(buffer, offset);
+      if (tagBytes === 0) break;
+      offset += tagBytes;
+
+      const wireType = tag & 0x07;
+      const fieldNo = tag >> 3;
+
+      if (wireType === 0) { // Varint
+        const { value, bytesRead } = this.readVarintWithLength(buffer, offset);
+        offset += bytesRead;
+        if (fieldNo === 1) {
+          position = value;
+        }
+      } else if (wireType === 2) { // Length-delimited
+        const { value: len, bytesRead } = this.readVarintWithLength(buffer, offset);
+        offset += bytesRead;
+
+        if (offset + len > buffer.length) break;
+
+        const data = buffer.subarray(offset, offset + len);
+        offset += len;
+
+        if (fieldNo === 2) {
+          messageBytes = data;
+        }
+      } else {
+        break;
+      }
+    }
+
+    if (!messageBytes) {
+      return null;
+    }
+
+    // Parse the message
+    const msg = this.parseChatMessage(messageBytes);
+    return {
+      position,
+      ...msg
+    };
+  }
+
+  /**
+   * Parse a chat message from raw bytes
+   * @param {Buffer} buffer - Message bytes
+   * @returns {Object} Parsed message
+   */
+  static parseChatMessage(buffer) {
+    let offset = 0;
+    const result = {
+      messageId: '',
+      type: 0,
+      typeName: 'UNKNOWN',
+      fromId: '',
+      fromType: 0,
+      fromTypeName: 'UNKNOWN',
+      chatId: '',
+      cid: '',
+      createTime: 0,
+      text: '',
+      htmlText: '',
+      imageKey: '',
+      imageKeys: [],
+      language: '',
+      replyCount: '0',
+      parentMsgId: ''
+    };
+
+    while (offset < buffer.length) {
+      const { value: tag, bytesRead: tagBytes } = this.readVarintWithLength(buffer, offset);
+      if (tagBytes === 0) break;
+      offset += tagBytes;
+
+      const wireType = tag & 0x07;
+      const fieldNo = tag >> 3;
+
+      if (wireType === 0) { // Varint
+        const { value, bytesRead } = this.readVarintWithLength(buffer, offset);
+        offset += bytesRead;
+
+        switch (fieldNo) {
+          case 2: result.type = value; result.typeName = getMessageTypeName(value); break;
+          case 4: result.createTime = value; break;
+          case 6: /* status */ break;
+          case 7: result.fromType = value; result.fromTypeName = getFromTypeName(value); break;
+        }
+      } else if (wireType === 2) { // Length-delimited
+        const { value: len, bytesRead } = this.readVarintWithLength(buffer, offset);
+        offset += bytesRead;
+
+        if (offset + len > buffer.length) break;
+
+        const data = buffer.subarray(offset, offset + len);
+        offset += len;
+
+        switch (fieldNo) {
+          case 1: result.messageId = data.toString('utf8'); break;
+          case 3: result.fromId = data.toString('utf8'); break;
+          case 5: // content
+            const content = this.parseChatMessageContent(data);
+            result.text = content.text;
+            result.htmlText = content.htmlText;
+
+            const imageInfos = content.imageInfos || [];
+            const imageKeys = imageInfos.map(info => info.imageKey).filter(Boolean);
+            result.imageKey = imageKeys[0] || '';
+            result.imageKeys = imageKeys;
+
+            for (const imageInfo of imageInfos) {
+              if (imageInfo.imageKey && imageInfo.cryptoInfo) {
+                cacheImageCryptoInfo(imageInfo.imageKey, imageInfo.cryptoInfo);
+              }
+            }
+            break;
+          case 10: result.chatId = data.toString('utf8'); break;
+          case 12: result.cid = data.toString('utf8'); break;
+          case 16: result.replyCount = data.toString('utf8'); break;
+          case 18: result.parentMsgId = data.toString('utf8'); break;
+          case 39: result.language = data.toString('utf8'); break;
+        }
+      } else {
+        // Skip other wire types
+        break;
+      }
+    }
+
+    return result;
+  }
+
+  /**
+   * Parse message content from raw bytes (for chat history)
+   * @param {Buffer} buffer - Content bytes
+   * @returns {Object} Parsed content with text and htmlText
+   */
+  static parseChatMessageContent(buffer) {
+    let offset = 0;
+    const result = {
+      text: '',
+      htmlText: '',
+      richTextOrImageBytes: new Uint8Array(),
+      richTextBytes: new Uint8Array(),
+      richTextData: new Uint8Array(),
+      imageInfos: []
+    };
+
+    while (offset < buffer.length) {
+      const { value: tag, bytesRead: tagBytes } = this.readVarintWithLength(buffer, offset);
+      if (tagBytes === 0) break;
+      offset += tagBytes;
+
+      const wireType = tag & 0x07;
+      const fieldNo = tag >> 3;
+
+      if (wireType === 2) { // Length-delimited
+        const { value: len, bytesRead } = this.readVarintWithLength(buffer, offset);
+        offset += bytesRead;
+
+        if (offset + len > buffer.length) break;
+
+        const data = buffer.subarray(offset, offset + len);
+        offset += len;
+
+        switch (fieldNo) {
+          case 1: result.text = data.toString('utf8'); break;
+          case 2:
+            result.richTextOrImageBytes = data;
+            result.htmlText = this.tryDecodeAsUtf8(data) || '';
+            break;
+          case 3: result.richTextBytes = data; break;
+          case 6: result.richTextData = data; break;
+        }
+      } else if (wireType === 0) {
+        const { bytesRead } = this.readVarintWithLength(buffer, offset);
+        offset += bytesRead;
+      } else {
+        break;
+      }
+    }
+
+    result.imageInfos = this.collectImageInfosFromChatHistoryContent(result);
+    return result;
+  }
+}
+
+export default ProtoBuilder;