@imweapp/openclaw-imwe 2026.4.12-alpha.1

package/src/proto/proto-types.ts

@@ -0,0 +1,291 @@
+/**
+ * proto-types.ts — Protobuf 消息的 TypeScript 类型接口
+ *
+ * protobufjs 运行时 decode 返回 Message<{}> 类型，需要通过类型断言
+ * 才能访问具体字段。本文件定义与 .proto 字段严格对应的接口，
+ * 仅用于 codec 内部的 `as unknown as XxxMsg` 断言，不参与运行时逻辑。
+ *
+ * 字段名规则：
+ *   protobufjs 加载 .proto 时，会将 camelCase 字段名原样保留。
+ *   例如 PbRequest.reqId → decoded.reqId（不转换）。
+ *
+ * 维护规则：
+ *   当 .proto 文件字段发生变化时，同步更新对应接口。
+ *   接口只需包含插件实际访问的字段，不需要穷举所有字段。
+ */
+
+// ─────────────────────────────────────────────────────────────────────────────
+// 传输层（PbPacket.proto）
+// ─────────────────────────────────────────────────────────────────────────────
+
+/** PbRequest 解码后的字段（插件关注的部分） */
+export interface DecodedPbRequest {
+  path: string;
+  reqId: string;
+  reqStamp: number | bigint;
+  /** body 字节，需按 path 二次反序列化 */
+  body?: Uint8Array;
+  /**
+   * 业务字段 / 元信息，命名约定 x-<module>-<key>。
+   * 原 imAcctId/boxId/boxSeq 已迁移至此：
+   *   x-im-acct-id  : IM 账号 ID（分身场景传递）
+   *   x-im-box-id   : IM 事件箱 ID
+   *   x-im-box-seq  : IM 事件箱序列号（用于同步）
+   */
+  headers: Record<string, string>;
+}
+
+/** PbPacket 解码后的字段 */
+export interface DecodedPbPacket {
+  /** PbType 枚举值：0=CLIENT_REQ, 1=SERVER_RSP, 2=SERVER_REQ, 3=CLIENT_RSP */
+  type: number;
+  request?: DecodedPbRequest;
+}
+
+// ─────────────────────────────────────────────────────────────────────────────
+// 投递层（PbChatDeliverMsg.proto）
+// ─────────────────────────────────────────────────────────────────────────────
+
+/** PbChatMsgDeliverBody 解码后的字段（插件关注的部分） */
+export interface DecodedDeliverBody {
+  convType: number;
+  fromId: string;
+  toId: string;
+  toAcctId: string;
+  winId?: string;
+  /** 信封类型：1=聊天, 2=操作, 3=支付, 4=服务号通知 */
+  envelopeType: number | bigint;
+  clientMsgId: string;
+  clientStamp: number | bigint;
+  serverMsgId: string;
+  serverStamp: number | bigint;
+  e2eeFlag: boolean;
+  /** 发送方设备 e2eeId（e2eeFlag=true 时必填） */
+  fromE2eeId?: string;
+  /** 接收方设备 e2eeId（e2eeFlag=true 时必填，应 == 本端 local.e2eeId） */
+  toE2eeId?: string;
+  /** 发送方使用的 Session.sessionId()（e2eeFlag=true 时必填） */
+  e2eeSid?: string;
+  /** 信封内容字节，需按 envelopeType 二次反序列化 */
+  envelope: Uint8Array;
+}
+
+// ─────────────────────────────────────────────────────────────────────────────
+// 文件元数据层（PbChatFileMeta.proto）
+// ─────────────────────────────────────────────────────────────────────────────
+
+/** PbChatFileMeta 解码后的字段 */
+export interface DecodedFileMeta {
+  url: string;
+  key?: Uint8Array;
+  iv?: Uint8Array;
+  fileType: string;
+  digest?: string;
+  length?: number | bigint;
+  plaintextLength?: number | bigint;
+  expireTime?: number | bigint;
+  attachmentId?: string;
+  /** PbChatFileMetaType 枚举值：0=UNKNOWN, 1=IMAGE, 2=VIDEO, 3=AUDIO, 4=FILE */
+  mediaType: number;
+  /** 操作凭证（下载回调用） */
+  opCreds?: string;
+}
+
+// ─────────────────────────────────────────────────────────────────────────────
+// 富媒体内容层（PbChatRichMediaContent.proto）
+// ─────────────────────────────────────────────────────────────────────────────
+
+/** PbChatRichMediaContent.AttachmentMeta 解码后的字段 */
+export interface DecodedAttachmentMeta {
+  attachmentId: string;
+  /** PbChatFileMetaType 枚举值 */
+  mediaType: number;
+  fileMeta?: DecodedFileMeta;
+  width?: number | bigint;
+  height?: number | bigint;
+  blurHash?: string;
+  duration?: number | bigint;
+  snapshot?: DecodedAttachmentMeta;
+  caption?: string;
+  fileName?: string;
+  fileSize?: number | bigint;
+}
+
+/** PbChatRichMediaContent 解码后的字段 */
+export interface DecodedRichMediaContent {
+  meta: DecodedAttachmentMeta[];
+  caption?: string;
+}
+
+// ─────────────────────────────────────────────────────────────────────────────
+// 音频内容层（PbChatAudioContent.proto）
+// ─────────────────────────────────────────────────────────────────────────────
+
+/** PbChatAudioContent.AttachmentMeta 解码后的字段 */
+export interface DecodedAudioAttachmentMeta {
+  attachmentId: string;
+  duration: number | bigint;
+  fileMeta?: DecodedFileMeta;
+}
+
+/** PbChatAudioContent 解码后的字段 */
+export interface DecodedAudioContent {
+  meta?: DecodedAudioAttachmentMeta;
+  speech?: string;
+}
+
+// ─────────────────────────────────────────────────────────────────────────────
+// Markdown 内容层（PbMarkdownContent.proto）
+// ─────────────────────────────────────────────────────────────────────────────
+
+/** PbMarkdownContent 解码后的字段 */
+export interface DecodedMarkdownContent {
+  /** 摘要标题（可空） */
+  digest: string;
+  /** markdown 正文 */
+  markdown: string;
+}
+
+// ─────────────────────────────────────────────────────────────────────────────
+// 信封层（PbChatMsg.proto）
+// ─────────────────────────────────────────────────────────────────────────────
+
+/** PbChatMsgEnvelope 解码后的字段 */
+export interface DecodedChatMsgEnvelope {
+  senderKey?: Uint8Array;
+  autoDeleteType?: number;
+  /**
+   * oneof envelope 中的文本消息内容（字段3）。
+   * 当消息为文本类型时有值，其他类型（音频/图片等）时为 undefined。
+   */
+  textContent?: DecodedTextContent;
+  /** 图片/视频混合消息（oneof 字段 9） */
+  richMediaContent?: DecodedRichMediaContent;
+  /** 文件消息（oneof 字段 13，结构同 richMediaContent） */
+  fileContent?: DecodedRichMediaContent;
+  /** 音频消息（oneof 字段 4） */
+  audioContent?: DecodedAudioContent;
+  /** Markdown 消息（oneof 字段 16） */
+  markdownContent?: DecodedMarkdownContent;
+}
+
+// ─────────────────────────────────────────────────────────────────────────────
+// 内容层（PbChatTextContent.proto）
+// ─────────────────────────────────────────────────────────────────────────────
+
+/** BodyRange 解码后的字段 */
+export interface DecodedBodyRange {
+  /** 0=UNKNOWN, 1=AT_USER, 2=LINK */
+  key: number;
+  /** AT_USER 时为被@者的 acctId */
+  payload: string;
+  /** 起始位置（UTF-16 单位） */
+  start?: number;
+  /** 长度（UTF-16 单位） */
+  length?: number;
+}
+
+/** PbChatTextContent 解码后的字段 */
+export interface DecodedTextContent {
+  text: string;
+  bodyRanges: DecodedBodyRange[];
+  referenceClientMsgId?: string;
+}
+
+// ─────────────────────────────────────────────────────────────────────────────
+// E2EE 单聊装箱层（PbSingleChatMsg.proto）
+// ─────────────────────────────────────────────────────────────────────────────
+
+/** PbSingleChatDeviceMsg 解码后的字段（单台对端设备的密文条目） */
+export interface DecodedSingleChatDeviceMsg {
+  /** 接收方设备 e2eeId（= 对端 Account.curve25519Key()） */
+  toE2eeId: string;
+  /** 发送本条消息时使用的 Session.sessionId() */
+  e2eeSid: string;
+  /** vodozemac EncryptedMessage.body（OlmMessage JSON bytes） */
+  envelope: Uint8Array;
+  /** 提醒加粗（透传 PbSingleChatMsgReqBody.boldNotify 语义） */
+  boldNotify?: boolean;
+}
+
+/** PbSingleChatMsgRecipient 解码后的字段（同一对端 imAcctId 的多设备分发） */
+export interface DecodedSingleChatMsgRecipient {
+  /** 对端 imAcctId */
+  acctId: string;
+  /** 该联系人下每台活跃设备一份密文 */
+  msgs: DecodedSingleChatDeviceMsg[];
+}
+
+/** PbSingleChatMsgRecipients 解码后的字段（所有联系人的设备分发集合） */
+export interface DecodedSingleChatMsgRecipients {
+  recipients: DecodedSingleChatMsgRecipient[];
+}
+
+// ─────────────────────────────────────────────────────────────────────────────
+// 操作信封层（PbChatMsg.proto — PbChatOperationEnvelope）
+// ─────────────────────────────────────────────────────────────────────────────
+
+/**
+ * PbMessageDecryptErrorSendContent 解码后的字段。
+ *
+ * 信令由"解密失败方"发回给"原发送方"，字段方向语义为：
+ *   - e2eeId：信令发送方自己的 e2eeId（= 解密失败消息的接收者设备）
+ *   - otherE2eeId：失败消息的原发送方 e2eeId（= 信令接收方，应 == 本端 local.e2eeId）
+ */
+export interface DecodedDecryptErrorContent {
+  /** 失败的那条消息的 clientMsgId */
+  clientMsgId: string;
+  /** 信令发送方自己的 e2eeId */
+  e2eeId: string;
+  /** 失败消息的原发送方 e2eeId */
+  otherE2eeId: string;
+}
+
+/** PbMsgReadStampSendContent 解码后的字段 */
+export interface DecodedMsgReadStampSendContent {
+  /** 已读消息的 clientMsgId 列表 */
+  clientMsgIds: string[];
+  /** 已读时间戳（Unix 秒） */
+  readStamp: number | bigint;
+}
+
+/** PbBotThinkingSignal 解码后的字段 */
+export interface DecodedBotThinkingSignal {
+  /** 1=begin（开始输入），2=end（结束输入） */
+  status: number;
+  /** Bot 的 imAcctId */
+  botImAcctId: string;
+}
+
+/**
+ * PbChatOperationEnvelope 解码后的字段。
+ *
+ * `content` 是 oneof，protobufjs decode 后仅会填充命中的那一个字段，
+ * 未命中的字段为 `undefined`。插件目前仅处理 `decryptError`、`botThinking` 与 `msgRead`
+ * 三种类型，其余 oneof case 以 `Uint8Array` 占位。
+ */
+export interface DecodedChatOperationEnvelope {
+  /** 消息撤回（占位，不解析） */
+  msgRecall?: Uint8Array;
+  /** 双向删除（占位，不解析） */
+  bidirectionalDelete?: Uint8Array;
+  /** 双向删除回复（占位，不解析） */
+  bidirectionalDeleteAnswer?: Uint8Array;
+  /** 群公告（占位，不解析） */
+  announcement?: Uint8Array;
+  /** 单聊解密失败回执信令（插件处理） */
+  decryptError?: DecodedDecryptErrorContent;
+  /** 群聊解密失败（占位，不解析） */
+  groupDecryptError?: Uint8Array;
+  /** 消息已读 */
+  msgRead?: DecodedMsgReadStampSendContent;
+  /** 消息已送达（占位，不解析） */
+  msgArrived?: Uint8Array;
+  /** Bot thinking 信号（插件处理） */
+  botThinking?: DecodedBotThinkingSignal;
+}
+
+// ─────────────────────────────────────────────────────────────────────────────
+// 插件自定义（send.proto 已移除，响应走 PbPacket(SERVER_RSP) 解包）
+// ─────────────────────────────────────────────────────────────────────────────
+// SendResponse 已不再使用，响应体通过 PbMsgRspBody 解析 serverMsgId。

package/src/proto/registry.ts

@@ -0,0 +1,226 @@
+/**
+ * registry.ts — Protobuf 运行时类型注册表
+ *
+ * 使用 protobufjs 在运行时直接加载 .proto 文件，无需代码生成步骤。
+ * .proto 文件是唯一的结构定义来源，修改后重启进程即生效。
+ *
+ * 加载的 .proto 文件分两类：
+ *   规范文件（与 im_proto 保持一致，camelCase 字段名）：
+ *     PbPacket.proto          → PbPacket / PbRequest
+ *     PbChatDeliverMsg.proto  → PbChatMsgDeliverBody
+ *     PbChatFileMeta.proto    → PbChatFileMeta / PbChatFileMetaType
+ *     PbChatRichMediaContent.proto → PbChatRichMediaContent
+ *     PbChatAudioContent.proto → PbChatAudioContent
+ *     PbMarkdownContent.proto → PbMarkdownContent
+ *     PbChatMsg.proto         → PbChatMsgEnvelope / PbChatOperationEnvelope / PbBotThinkingSignal
+ *     PbChatTextContent.proto → PbChatTextContent / BodyRange
+ *     PbSingleChatMsg.proto   → PbSingleChatMsgReqBody
+ *     PbBoxPullProto.proto    → PbBoxPullReq / PbBoxPullRsp
+ *   插件自定义文件（独立定义，package imwe）：
+ *     send.proto              → SendResponse
+ *
+ * 单例模式：首次调用 getRegistry() 时触发文件加载，后续调用直接返回缓存。
+ * 并发安全：多个并发调用共享同一个 loadPromise，不会重复加载。
+ */
+
+import { load, type Root, type Type } from 'protobufjs';
+import { resolve, dirname } from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+// proto 文件所在目录（相对于本文件向上两级到插件根，再进入 proto/）
+const PROTO_DIR = resolve(dirname(fileURLToPath(import.meta.url)), '../../proto');
+
+// ─────────────────────────────────────────────────────────────────────────────
+// 类型注册表接口
+// ─────────────────────────────────────────────────────────────────────────────
+
+/**
+ * 插件所需的全部 protobuf 类型，按用途分组。
+ *
+ * 命名规则：
+ *   - 规范消息（package proto）：直接用消息名，如 PbPacket
+ *   - 插件自定义消息（package imwe）：加前缀区分，如 imwe.PollRequest
+ */
+export type ProtoRegistry = {
+  // ── 传输层（PbPacket.proto） ──────────────────────────────────────────────
+  /** 最外层传输容器，type=CLIENT_REQ(0) 或 SERVER_REQ(2) */
+  PbPacket: Type;
+  /** 请求体，body 字段按 path 二次反序列化 */
+  PbRequest: Type;
+  /** 响应体，statusCode=200 表示成功，body 按业务类型反序列化 */
+  PbResponse: Type;
+
+  // ── 投递层（PbChatDeliverMsg.proto） ─────────────────────────────────────
+  /** 服务端向客户端投递消息的统一载体，envelope 字段按 envelopeType 二次反序列化 */
+  PbChatMsgDeliverBody: Type;
+
+  // ── 信封层（PbChatMsg.proto） ─────────────────────────────────────────────
+  /** 聊天消息信封（envelopeType=1），oneof envelope 包含 13 种消息类型 */
+  PbChatMsgEnvelope: Type;
+  /**
+   * 发送消息响应体（PbResponse.body 按此类型反序列化）。
+   * 包含 serverMsgId / serverStamp，用于确认消息已被平台接收。
+   */
+  PbMsgRspBody: Type;
+
+  // ── 操作信封层（PbChatMsg.proto） ────────────────────────────────────────
+  /** 操作消息信封（envelopeType=2），oneof content 包含 botThinking 等操作类型 */
+  PbChatOperationEnvelope: Type;
+  /** Bot thinking 信号，status=1(begin)/2(end) */
+  PbBotThinkingSignal: Type;
+  /** 单聊解密失败回执信令（PbChatOperationEnvelope.content.decryptError） */
+  PbMessageDecryptErrorSendContent: Type;
+  /** 消息已读内容（PbChatOperationEnvelope.content.msgRead） */
+  PbMsgReadStampSendContent: Type;
+
+  // ── 内容层（PbChatTextContent.proto） ────────────────────────────────────
+  /** 文本消息内容，包含 text / bodyRanges / referenceClientMsgId */
+  PbChatTextContent: Type;
+
+  // ── 内容层（PbMarkdownContent.proto） ────────────────────────────────────
+  /** Markdown 消息内容（PbChatMsgEnvelope 字段 16），包含 digest / markdown */
+  PbMarkdownContent: Type;
+
+  // ── 多媒体内容层 ─────────────────────────────────────────────────────────
+  /** 图片/视频混合消息内容（PbChatMsgEnvelope 字段 9 和 13） */
+  PbChatRichMediaContent: Type;
+  /** 文件元数据（含 url、加密信息、文件类型等） */
+  PbChatFileMeta: Type;
+  /** 音频消息内容（PbChatMsgEnvelope 字段 4） */
+  PbChatAudioContent: Type;
+
+  // ── 发送层（PbSingleChatMsg.proto） ──────────────────────────────────────
+  /** 单聊消息请求体，作为 PbRequest.body 的内容 */
+  PbSingleChatMsgReqBody: Type;
+  /** E2EE 单设备密文条目（e2eeFlag=true 时装箱使用） */
+  PbSingleChatDeviceMsg: Type;
+  /** E2EE 同一对端 imAcctId 的多设备分发 */
+  PbSingleChatMsgRecipient: Type;
+  /** E2EE 所有联系人的设备分发集合，序列化后作为 PbSingleChatMsgReqBody.envelope */
+  PbSingleChatMsgRecipients: Type;
+
+  // ── 事件箱拉取（PbBoxPullProto.proto） ───────────────────────────────────
+  /** 事件箱拉取请求，POST /api/im/open/bot/pullMessages 的请求体 */
+  PbBoxPullReq: Type;
+  /** 事件箱拉取响应，POST /api/im/open/bot/pullMessages 的响应体 */
+  PbBoxPullRsp: Type;
+};
+
+// ─────────────────────────────────────────────────────────────────────────────
+// 单例状态
+// ─────────────────────────────────────────────────────────────────────────────
+
+/** 已初始化的注册表缓存，null 表示尚未加载 */
+let registry: ProtoRegistry | null = null;
+
+/**
+ * 进行中的加载 Promise，用于防止并发重复加载。
+ * 多个并发调用 getRegistry() 时，只有第一个触发 load()，其余等待同一个 Promise。
+ */
+let loadPromise: Promise<ProtoRegistry> | null = null;
+
+// ─────────────────────────────────────────────────────────────────────────────
+// 内部：从已加载的 Root 构建注册表
+// ─────────────────────────────────────────────────────────────────────────────
+
+/**
+ * 从 protobufjs Root 中按全限定名查找所有需要的类型，构建注册表。
+ *
+ * 全限定名规则：
+ *   - 规范文件 package=proto：  "proto.MessageName"
+ *   - 插件自定义 package=imwe： "imwe.MessageName"
+ */
+function buildRegistry(root: Root): ProtoRegistry {
+  return {
+    // 传输层
+    PbPacket: root.lookupType('proto.PbPacket'),
+    PbRequest: root.lookupType('proto.PbRequest'),
+    PbResponse: root.lookupType('proto.PbResponse'),
+    // 投递层
+    PbChatMsgDeliverBody: root.lookupType('proto.PbChatMsgDeliverBody'),
+    // 信封层
+    PbChatMsgEnvelope: root.lookupType('proto.PbChatMsgEnvelope'),
+    PbMsgRspBody: root.lookupType('proto.PbMsgRspBody'),
+    // 操作信封层
+    PbChatOperationEnvelope: root.lookupType('proto.PbChatOperationEnvelope'),
+    PbBotThinkingSignal: root.lookupType('proto.PbBotThinkingSignal'),
+    PbMessageDecryptErrorSendContent: root.lookupType('proto.PbMessageDecryptErrorSendContent'),
+    PbMsgReadStampSendContent: root.lookupType('proto.PbMsgReadStampSendContent'),
+    // 内容层
+    PbChatTextContent: root.lookupType('proto.PbChatTextContent'),
+    PbMarkdownContent: root.lookupType('proto.PbMarkdownContent'),
+    // 多媒体内容层
+    PbChatRichMediaContent: root.lookupType('proto.PbChatRichMediaContent'),
+    PbChatFileMeta: root.lookupType('proto.PbChatFileMeta'),
+    PbChatAudioContent: root.lookupType('proto.PbChatAudioContent'),
+    // 发送层
+    PbSingleChatMsgReqBody: root.lookupType('proto.PbSingleChatMsgReqBody'),
+    PbSingleChatDeviceMsg: root.lookupType('proto.PbSingleChatDeviceMsg'),
+    PbSingleChatMsgRecipient: root.lookupType('proto.PbSingleChatMsgRecipient'),
+    PbSingleChatMsgRecipients: root.lookupType('proto.PbSingleChatMsgRecipients'),
+    // 事件箱拉取
+    PbBoxPullReq: root.lookupType('proto.PbBoxPullReq'),
+    PbBoxPullRsp: root.lookupType('proto.PbBoxPullRsp'),
+  };
+}
+
+// ─────────────────────────────────────────────────────────────────────────────
+// 公开 API
+// ─────────────────────────────────────────────────────────────────────────────
+
+/**
+ * 获取 Protobuf 类型注册表。
+ *
+ * 首次调用时从磁盘加载所有 .proto 文件并解析，后续调用直接返回缓存。
+ * 加载耗时约几毫秒（本地文件 I/O + protobufjs 解析），仅发生一次。
+ *
+ * @returns 包含所有插件所需 protobuf 类型的注册表
+ * @throws 如果 .proto 文件不存在或语法错误，会抛出 Error
+ */
+export async function getRegistry(): Promise<ProtoRegistry> {
+  // 快速路径：已初始化，直接返回
+  if (registry) {
+    return registry;
+  }
+
+  // 并发安全：复用已有的加载 Promise，避免重复加载
+  if (!loadPromise) {
+    const protoFiles = [
+      // 规范文件（与 im_proto 保持一致）
+      resolve(PROTO_DIR, 'PbPacket.proto'),
+      resolve(PROTO_DIR, 'PbChatDeliverMsg.proto'),
+      resolve(PROTO_DIR, 'PbChatTextContent.proto'), // 需在 PbChatMsg.proto 之前加载（被 import）
+      resolve(PROTO_DIR, 'PbChatFileMeta.proto'), // 需在 PbChatRichMediaContent/PbChatAudioContent 之前加载（被 import）
+      resolve(PROTO_DIR, 'PbChatRichMediaContent.proto'), // 需在 PbChatMsg.proto 之前加载（被 import）
+      resolve(PROTO_DIR, 'PbChatAudioContent.proto'), // 需在 PbChatMsg.proto 之前加载（被 import）
+      resolve(PROTO_DIR, 'PbMarkdownContent.proto'), // 需在 PbChatMsg.proto 之前加载（被 import）
+      resolve(PROTO_DIR, 'PbMsgReadStampContent.proto'), // 需在 PbChatMsg.proto 之前加载（被 import）
+      resolve(PROTO_DIR, 'PbChatMsg.proto'),
+      resolve(PROTO_DIR, 'PbSingleChatMsg.proto'),
+      resolve(PROTO_DIR, 'PbBoxPullProto.proto'),
+    ];
+
+    loadPromise = load(protoFiles)
+      .then((root) => {
+        const reg = buildRegistry(root);
+        registry = reg; // 缓存，后续调用走快速路径
+        return reg;
+      })
+      .catch((err) => {
+        // 加载失败时清除 Promise，允许下次重试
+        loadPromise = null;
+        throw new Error(`imwe proto 加载失败：${String(err)}`);
+      });
+  }
+
+  return loadPromise;
+}
+
+/**
+ * 重置注册表缓存（仅供测试使用）。
+ * 生产代码不应调用此函数。
+ */
+export function _resetRegistryForTest(): void {
+  registry = null;
+  loadPromise = null;
+}