Protocol: Envelope

iframe 通信的包裹结构。

Schema

ts

interface Envelope<T = unknown> {
  version: string             // CONTRACT_VERSION,如 '1.1.0'
  id: string                  // 消息 ID
  timestamp: number           // Unix ms
  type: 'command' | 'event' | 'response' | 'error'
  payload: T
}

⚠️ 不是所有消息都走 Envelope

四种 type 里,目前只有 event 会真的出现在线上。

命令走 Penpal RPC 时传的是裸 Command,回执和失败由 Penpal 的 Promise resolve / reject 承担——command / response / error 三类包裹有构造函数和契约测试, 但没有生产代码调用。

因此 id 目前不承担 request-response 关联(那是 Penpal 内部的事), 事件的 id 只是进程内自增序号。

对接入方的影响:自己写 window.onmessage 监听器时只需处理 type === 'event', 其余三类不会到达。产出侧见 apps/embed-app/src/bridge.ts。

详细说明

权威来源：packages/protocol/src/envelope.ts 的 Zod schema。