揭秘 PenguinHarness 的 OmniMessage 协议：一个协议统一流式、存储与模型的完整指南

揭秘 PenguinHarness 的 OmniMessage 协议一个协议统一流式、存储与模型的完整指南【免费下载链接】penguin-harness Unified and Stable RSI Platform项目地址: https://gitcode.com/gh_mirrors/pe/penguin-harnessPenguinHarness 是一个开源的 Agent Harness 平台而它的底层基石是OmniMessage 协议——一套统一的消息协议SDK 产出它Trace 存储它Server 再经 SSE 原样推送它。这意味着流出去的、存下来的、以及模型看到的内容是同一种结构前端、后端与存储之间不存在第二套格式。这篇文章用通俗的方式带你完整看懂 OmniMessage它长什么样、有哪几类消息、如何做到流式即存储以及为什么它让 Agent 会话可以无损恢复。为什么一个协议如此重要 构建 AI Agent 应用时工程师常常要面对三套语言流式输出模型一边生成一边往外吐 token客户端要边收边渲染磁盘存储会话历史要落盘将来还要能完整回放、恢复模型上下文下一轮请求要把历史消息重新喂给模型。如果三者各用各的格式你就得写大量的转换代码把流式分片拼成完整消息、把完整消息转成存储格式、再把存储格式还原成模型能读的上下文。任何一处转换出错会话恢复就会出问题。OmniMessage 的解法很直接只定义一种结构所有环节共用它。整个系统的内核只认识 OmniMessage不做任何协议转换——供应商协议的差异被封装在模型网关一侧UI 的差异被封装在渲染层一侧。协议的类型定义集中在 packages/core/src/omnimessage/types.ts。统一的信封三类消息一个结构每条 OmniMessage 共用同一个信封只有payload不同时间戳、消息类型、消息体外加一个可选的origin字段。外层type只有三种取值消息类型含义出现规律session_meta一个模型上下文的完整运行时配置每个上下文恰好一条model_msg上下文内的内容文本、思考、工具调用与结果消息主体event_msg上下文之外的运行时事件审批、用量、压缩、中断、钩子回答伴随出现其中session_meta相当于开局记录它记下会话 ID、所用模型、完整装配好的系统提示词、Agent 状态与工作区路径。每个 Trace 文件都以一条session_meta开头会话内切换模型时会开启新上下文、写下一条新的 meta。恢复会话时引擎直接读最新文件里的 meta 就能还原运行时配置——这就是存储即恢复的基础。完整消息与流式分片流式如何做到零拼接model_msg里有两组 payload完整消息共七种用payload.type区分text普通文本区分 user / assistant 角色thinking/inline_thinking模型思考块tool_call/tool_call_output工具调用与结果通过tool_call_id严格配对image_url/inline_data图片与其他二进制内容。流式分片共四种partial_*payload与完整消息一一对应并带一个event_type标记所处阶段start→delta→stop。这里最优雅的地方是流式纪律每段流式内容都严格遵守同一时序规则——partial_text(start) → partial_text(delta) → … → partial_text(stop) → text (complete)所有 delta 拼接起来恰好等于完整消息且stop之后紧跟完整消息本身。因此渲染层可以边收 delta 边绘制、收到完整消息后原地替换而 Trace只记录完整消息不存分片。接口内部把结构闭合好从不向上层泄漏未闭合的分片使用方永远不需要自己拼接。event_msg把运行时的一切变成消息event_msg共十二种事件记录模型上下文之外的运行时事实例如事件记录的内容tool_list_ready实际发给模型的完整工具 schemarequest_begin/request_end一次模型请求的开始与终态含重试详情approval_decision一次工具审批决策allow / deny / forbiddentoken_usage会话累计与本次请求的 Token 用量compaction_begin/compaction_end上下文压缩的触发与结果abort一次用户中断及其原因码subagent父 Trace 中指向子会话的指针hook一次钩子回答钩子点、名称、决策凡是报告失败的事件都携带同一对错误字段error_code是稳定、机器可读的原因码渲染层据此做本地化error_message是原始失败文本。这个设计呼应了 PenguinHarness 的一条核心信条错误从不以异常形式穿过接口边界错误本身就是消息。stop_reason所有终止记录共用一套词汇所有带终止原因的记录——模型消息、工具结果、请求终态、压缩终态、MCP 连接终态——共用同一个四值枚举取值含义引擎反应completed正常完成继续aborted用户中断或取消停止产出abort事件交还用户retryable值得重试的失败超时、429/5xx、响应被截断等按退避阶梯自动重连fatal重试也无法修复凭据被拒、确定性 4xx 拒绝停止运行交还用户四值只回答一个问题要不要重试。失败属于哪一类看error_code细节看error_message。职责单一整个协议就不会出现十个地方十种错误语义的混乱。origin 与 fidelity路由子 Agent、保真供应商细节两个可选字段解决了两个看似无关的问题origin子 Agent 的消息路由。当 Agent 用run_subagent派生子会话时子会话的消息转发给父级每经过一层就在origin链首加一个子会话 ID由外到内。渲染层按这条链把消息归入对应的嵌套卡片而带origin的消息不写入父 Trace——子会话有自己的 Trace父 Trace 只保留一条subagent指针事件。fidelity供应商保真负载。一些模型回放历史时要求携带逐字节一致的供应商数据如思考签名、加密推理内容。fidelity是一个对 PenguinHarness完全不透明的 JSON 对象全链路原样透传、原样存储不改写、不丢失。这也是 Trace 能无损恢复会话的前提之一。同一协议贯穿三条通道 通道使用的子集SDK 边界session.run的输出完整model_msg 流式partial_* 全部event_msg落盘的 Tracesession_meta 完整model_msg 全部event_msg不存分片与origin消息Server 的 SSE 推送与 SDK 边界相同原样的单行 JSON每条消息在进入输出流的同时追加写入 Trace因此流序与 Trace 序天然一致。Trace 观测面板可以直接回放这些消息还原出每一轮的执行时间线消息如何在一轮的五个参与者Human、engine、LLM、Environment、Trace之间传递、哪些顺序有保证官方文档有专门一页梳理packages/docs/content/message-flow.zh.md。动手体验用 SDK 消费 OmniMessage 流想感受协议的统一性只需几行代码。prismshadow/penguin-core导出了协议的全部类型、构造函数builders和运行时判别函数完整用法见 packages/docs/content/quickstart-sdk.zh.md 与 packages/core/README.mdimport { createAgent, isCompleteModelMessage, userText } from prismshadow/penguin-core; const agent await createAgent({ agentId: default_agent }); const session await agent.createSession({ workspaceDir: process.cwd() }); for await (const output of session.run([userText(列出当前目录的文件)], { approve: async () allow, })) { if (isCompleteModelMessage(output) output.payload.type text) { console.log(output.payload.text); } }循环中你拿到的就是Trace 里存的内容、SSE 里推的内容——同一种结构。想深入协议逐字段定义官方文档是最佳入口packages/docs/content/omni-message.zh.md。写在最后OmniMessage 的哲学可以浓缩成一句话流出去的、存下来的和模型看到的是同一种结构。它用一个信封、三类消息、四值终止原因和不透明的保真字段同时解决了流式渲染、磁盘存储与会话恢复三个看似矛盾的需求也让一切可观测、Session 可从 Trace 完整恢复成了平台级的承诺。如果你想了解它如何与 ReAct 循环、压缩和重连协作可以继续阅读 packages/docs/content/architecture.zh.md 与 packages/docs/content/agent-loop.zh.md。【免费下载链接】penguin-harness Unified and Stable RSI Platform项目地址: https://gitcode.com/gh_mirrors/pe/penguin-harness创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考