Engine Messages And Projections

目标

为 runtime 建立稳定的内部消息管理方案，明确消息从存储到模型输入之间的分层边界。

当前推荐理解方式是五层：

Persisted Message → EngineMessage → Projected Message → ChatMessage → AI SDK Message

解决的核心问题：

• 持久化历史与模型上下文构建解耦
• API 传输模型与 engine 内部语义模型解耦
• compact / prune / handoff / resume 成为一等能力
• transcript、debug、model-context 共享同一份底层消息真相
• AI SDK 适配与上下文裁剪解耦

---

五层定义

层	职责	特点
Persisted Messages	存储与 API 传输真相	稳定、通用、可持久化；不直接承担完整 runtime 语义
Engine Messages	runtime 语义层	由 Persisted Message 提升得到；显式携带 kind
Projected Messages	面向特定消费目标的视图	可过滤、裁剪、重排、补充 synthetic 消息
Chat Messages	通用模型输入格式	role/content 结构，脱离 session/run 存储语义
AI SDK Messages	最终请求格式	满足 provider/SDK 格式要求，只负责最后一跳序列化

关系：

• EngineMessage 来源于 Persisted Message
• ModelMessage 是 ProjectedMessage 中面向模型的一种视图
• ChatMessage 是投影结果序列化后的通用输入格式
• AI SDK / provider message 是再下一层的适配结果

flowchart LR
  PM0["Persisted Messages"]
  EM["Engine Messages"]
  PM["Projected Messages"]
  CM["Chat Messages"]
  SDK["AI SDK Messages"]

  PM0 --> EM
  EM --> PM
  PM --> CM
  CM --> SDK

---

为什么需要分层

• 数据库存档需要稳定，runtime 语义需要可演进
• UI transcript 要完整过程，模型上下文必须裁剪
• compact 后需保留 summary artifact，同时可回看完整历史
• tool result 过长时，模型用 stub，调试界面看原文
• hook/system reminder/handoff summary 不适合与用户消息混为一体
• 不同 provider 的 content part 支持不同，消息模型不应与 SDK 结构绑死

---

运行时主链路

1. 读取持久化历史
2. 将 Message 提升为 EngineMessage
3. 应用 projection，得到 transcript / model / compact / debug 等视图
4. 将 model view 序列化为 ChatMessage
5. 适配为 AI SDK / provider message
6. 传给模型运行时 / AI SDK

关键代码位置：

• 持久化消息定义：packages/api-contracts/src/messages.ts
• EngineMessage 提升：packages/engine-core/src/engine/engine-messages.ts
• 历史读取：packages/engine-core/src/engine/session-history.ts
• Projection：packages/engine-core/src/engine/message-projections.ts
• ChatMessage 序列化：packages/engine-core/src/engine/ai-sdk-message-serializer.ts
• 上下文构建：packages/engine-core/src/engine-service.ts
• Provider 适配：packages/model-runtime/src/runtime-helpers.ts

---

三个最容易混淆的核心类型

团队日常讨论里，最值得优先区分的是这三层：

• Message
• EngineMessage
• ChatMessage

1. Persisted Message

Message 定义在 packages/api-contracts/src/messages.ts，它是：

• 数据库存储层的原始会话消息
• GET /sessions/:id/messages 这类 API 返回值
• session 时间线的事实记录

它负责表达：

• 发生了什么
• 这条消息属于哪个 session / run
• 消息原始 role / content / metadata

它不负责直接表达：

• 这条消息在 engine 看来到底属于哪种 runtime 语义
• 这条消息最终是否应该进入模型上下文
• compact / pruning / projection 后的上下文窗口

一句话：Message 是存储与 API 层的 canonical fact model。

2. EngineMessage

EngineMessage 定义在 packages/engine-core/src/engine/engine-messages.ts，它是：

• engine 内部运行时语义层
• 由持久化 Message 推导 / 提升得到的对象
• projection 的统一输入

相比 Message，它新增的关键能力是：

• 显式的 kind
• 更适合 runtime 的 metadata 解释

例如持久化层只是一个 role: "system" 的消息；到了 EngineMessage 层，它才会被明确识别成：

• compact_boundary
• compact_summary
• system_note

一句话：EngineMessage 不是 Message 的简化版，而是对 Message 的 runtime 语义解释。

3. ChatMessage

ChatMessage 同样来自 @oah/api-contracts，但它不再是“会话存档消息”，而是：

• 面向模型输入的通用消息格式
• 更接近 provider request 的 role/content 结构
• 不再关心 sessionId、runId、createdAt 这类存储字段

它负责表达：

• 模型这一轮到底看到哪些消息
• 这些消息最终用什么 role/content 形式传给网关

一句话：ChatMessage 是模型输入层，不是存档层。

---

为什么 Persisted Message 不应该直接等于 EngineMessage

很多人第一次看会直觉觉得：

• Message 是不是就是 EngineMessage 的简化版？
• 能不能合并？

当前设计里，不建议这样理解。

更准确的边界是：

• Message 是原始事实
• EngineMessage 是 runtime 解释

这么分的原因：

• 持久化 / API 合同需要稳定
• engine 内部语义需要可演进
• projection 需要面向运行时语义工作，而不是直接读存储模型
• compact / resume / handoff 这类能力会持续增加内部语义类型

如果把两者合并：

• 持久化合同会被 runtime 内部语义污染
• API 返回会暴露过多 engine 内部概念
• kind 的演进会变成存储迁移问题
• 外部调用方会被迫理解内部执行语义

所以推荐方式是：

• Message 保持轻量稳定
• metadata.runtimeKind 作为持久化到 runtime 的桥
• EngineMessage.kind 作为内部语义标准

---

在当前实现里，Persisted Message 如何得到 EngineMessage

核心入口在：

• packages/engine-core/src/engine/engine-messages.ts

提升逻辑大致是：

1. 读取持久化 Message
2. 解析 metadata
3. 如果 metadata.runtimeKind 存在且合法，直接用它作为 EngineMessage.kind
4. 否则根据 role + content 推断

例如：

• system → system_note
• user → user_input
• assistant + tool-call part → tool_call
• assistant + reasoning part → assistant_reasoning
• tool → tool_result

compact 是典型例子：

• 落库时仍然是普通 Message
• 通过 metadata.runtimeKind 记录它是 compact_boundary 或 compact_summary
• engine 读取后再提升为对应的 EngineMessage.kind

---

Projection Layer 的职责

Projection layer 不直接操作存储模型，而是尽量操作 EngineMessage。

原因是：

• EngineMessage.kind 已经表达了 runtime 语义
• 可以避免在多个地方反复猜 metadata
• compact / transcript / debug / model context 可以共享同一套语义输入

推荐原则：

• Projection 输入：EngineMessage[]
• Projection 逻辑：尽量依赖 EngineMessage.kind
• 持久化桥接：只在 Message -> EngineMessage 这一层读 metadata.runtimeKind

对 compact 来说，关键语义是：

• compact_boundary 负责切历史
• compact_summary 负责承接旧上下文

例如 projectToModel() 的语义是：

• 找最近的 compact_boundary
• boundary 本身不进模型
• 找关联的 compact_summary
• 把 summary 放到裁切后窗口最前面
• 再拼上 boundary 之后的 recent messages

---

当前实现里的五层对应关系

概念	当前实现中的主要类型	主要代码位置
Persisted Message	Message	packages/api-contracts/src/messages.ts
Runtime semantic message	EngineMessage	packages/engine-core/src/engine/engine-messages.ts
Projection result	TranscriptMessage / ModelMessage / CompactMessage / DebugMessage	packages/engine-core/src/engine/message-projections.ts
Provider-neutral model input	ChatMessage	packages/engine-core/src/engine/ai-sdk-message-serializer.ts
Provider/SDK input	AI SDK ModelMessage 等	packages/model-runtime/src/runtime-helpers.ts

---

与 Claude Code 的关系

Claude Code 的思路是同向的，但分层更隐式。

可以粗略对照为：

OAH	Claude Code 中更接近的层
Message	Message
EngineMessage	NormalizedMessage + 一部分消息语义工具函数
Projection layer	getMessagesAfterCompactBoundary()、normalizeMessagesForAPI() 等消息处理链
ChatMessage / provider input	最终 API-bound messages

参考位置：

• normalizeMessages()：references/claude-code-source-code/src/utils/messages.ts
• normalizeMessagesForAPI()：references/claude-code-source-code/src/utils/messages.ts
• getMessagesAfterCompactBoundary()：references/claude-code-source-code/src/utils/messages.ts
• buildPostCompactMessages()：references/claude-code-source-code/src/services/compact/compact.ts

结论：

• Claude Code 也不是“只有一层消息模型”
• 它同样把“会话消息”“规范化消息”“API 输入消息”分开处理
• OAH 单独抽出 EngineMessage，是更显式、更工程化的实现

---

一个更准确的心智模型

推荐团队内部统一使用下面这组表述：

• Message：数据库里的原始会话消息
• EngineMessage：engine 对原始消息的 runtime 解释
• ProjectedMessage：面向某个消费目标的投影视图
• ChatMessage：真正送往模型的一般化输入消息

最简记忆法：

• Message 记录事实
• EngineMessage 解释语义
• Projection 选择视图
• ChatMessage 进入模型

---

Engine Messages 类型

export type EngineMessageRole = "system" | "user" | "assistant" | "tool";

export type EngineMessageKind =
  | "system_note"
  | "user_input"
  | "assistant_text"
  | "assistant_reasoning"
  | "tool_call"
  | "tool_result"
  | "tool_approval_request"
  | "tool_approval_response"
  | "compact_boundary"
  | "compact_summary"
  | "runtime_reminder"
  | "handoff_summary"
  | "agent_switch_note";

export interface EngineMessageBase {
  id: string;
  sessionId: string;
  runId?: string;
  role: EngineMessageRole;
  kind: EngineMessageKind;
  createdAt: string;
  metadata?: {
    agentName?: string;
    effectiveAgentName?: string;
    synthetic?: boolean;
    visibleInTranscript?: boolean;
    eligibleForModelContext?: boolean;
    compactedAt?: string;
    compactBoundaryId?: string;
    summaryForBoundaryId?: string;
    source?: "user" | "engine" | "hook" | "tool" | "system";
    tags?: string[];
    extra?: Record<string, unknown>;
  };
}

设计约束：

• role 对齐外部生态
• kind 表达 runtime 内部语义
• compact_boundary / compact_summary 必须显式建模，不用普通 system 文本冒充

分类

一等类型（必须）： user_input、assistant_text、tool_call、tool_result、compact_boundary、compact_summary

逐步引入： assistant_reasoning、runtime_reminder、handoff_summary、agent_switch_note

继续用 metadata 表达： 调试标签、审计附加字段、UI 提示性状态

经验：一旦某语义会被 projection / compact / resume 依赖，就应升级为明确 kind。

---

Projected Messages 类型

export type ProjectionView =
  | "transcript" | "model" | "compact" | "debug" | "export";

export interface ProjectedMessageBase {
  view: ProjectionView;
  role: "system" | "user" | "assistant" | "tool";
  semanticType: string;
  sourceMessageIds: string[];
  content: unknown;
  metadata?: {
    hiddenFromTranscript?: boolean;
    hiddenFromModel?: boolean;
    truncated?: boolean;
    compacted?: boolean;
    notes?: string[];
  };
}

sourceMessageIds 用于 debug 反查来源、compact 诊断追踪、UI "展开原始消息"。

---

Model Messages 类型

export interface ModelMessage extends ProjectedMessageBase {
  view: "model";
  semanticType:
    | "system_note" | "runtime_reminder" | "user_input"
    | "assistant_text" | "assistant_reasoning"
    | "tool_call" | "tool_result"
    | "compact_summary" | "handoff_summary";
  content: string | ModelMessagePart[];
}

保留 semanticType 和 sourceMessageIds，便于 runtime 调试和 provider 兼容。

---

Projection Views

View	用途	特点
Transcript	前端聊天窗口、CLI、历史页	保留完整过程，显示 compact boundary
Model	构造模型输入上下文	应用 compact boundary、tool-result pruning、runtime reminder
Compact	供 compact 逻辑自身使用	专注"哪些历史需要被总结"
Debug	开发调试和问题排查	保留更多 metadata，标出被过滤/截断的消息
Export	导出对话、分享、生成 report	去掉 runtime 噪声，允许脱敏

---

Projection API

export interface ProjectionContext {
  sessionId: string;
  activeAgentName: string;
  modelRef?: string;
  provider?: string;
  includeReasoning?: boolean;
  includeToolResults?: boolean;
  toolResultSoftLimitChars?: number;
  applyCompactBoundary?: boolean;
  injectRuntimeReminder?: boolean;
}

export interface ProjectionResult<TMessage> {
  messages: TMessage[];
  diagnostics: {
    hiddenMessageIds: string[];
    truncatedMessageIds: string[];
    appliedCompactBoundaryId?: string;
    injectedNotes: string[];
  };
}

export interface EngineMessageProjector {
  projectToTranscript(msgs: EngineMessage[], ctx: ProjectionContext): ProjectionResult<TranscriptMessage>;
  projectToModel(msgs: EngineMessage[], ctx: ProjectionContext): ProjectionResult<ModelMessage>;
  projectToDebug(msgs: EngineMessage[], ctx: ProjectionContext): ProjectionResult<DebugMessage>;
  projectToCompact(msgs: EngineMessage[], ctx: ProjectionContext): ProjectionResult<CompactMessage>;
}

---

projectToModel() 规则

基础

1. 仅保留 eligibleForModelContext !== false 的消息
2. 启用 compact 时，只取最近 compact_boundary 之后的窗口
3. compact_boundary 本身不进入 model view
4. compact_summary 进入 model view
5. runtime_reminder 可按策略注入

Tool 相关

• tool_call 默认保留
• tool_result 标记 compactedAt 时降级为 stub
• 超长 tool_result 在 projection 层截断
• provider 不支持某类附件时降级为文本提示

Agent / Handoff

• handoff_summary 默认进入 model view
• agent_switch_note 默认不发给模型（除非承担 system reminder 语义）

最小 compact 规则

1. 找到最近 compact_boundary
2. 若有 compact_summary，作为压缩上下文起点
3. 保留 boundary 之后的 recent messages
4. 更老的长 tool_result 仅保留 stub

Compact 触发窗口优先级

compact 是否触发，首先要先得到当前模型的上下文窗口大小。这里采用两级优先级：

1. 优先使用模型 API /v1/models 返回的 max_model_len
2. 若没有该值，再回退到模型 metadata 中配置的 contextWindowTokens

如果两者都缺失，runtime 会保留完整 Engine Messages，不执行基于 context window 的自动 compact。

---

Prompt 选择与 AI SDK 序列化边界

• projectToModel() 决定"给模型看什么"
• toAiSdkMessages() 决定"按 SDK 要求怎么表示"

不要把裁剪逻辑塞进 serializer。

被 prune 的 tool result 示例：

// Engine Message
{ kind: "tool_result", metadata: { compactedAt: "2026-04-08T10:00:00Z" } }

// Model projection
{ view: "model", semanticType: "tool_result",
  content: [{ type: "tool-result", toolCallId: "call_1",
    output: { type: "text", value: "[Old tool result content cleared]" } }] }

Serializer 再将其转为 AI SDK payload。

---

AI SDK Adapter

export interface ModelMessageSerializer {
  toAiSdkMessages(
    messages: ModelMessage[],
    options?: { workspace?: WorkspaceRecord }
  ): Promise<ChatMessage[]>;
}

只负责：role/content 格式转换、system message 合并、provider 兼容、非法组合兜底。不负责 compact 决策或裁剪。

---

Compact 设计

引入 Engine Messages 后，compact 升级为 message artifact：

• compact_boundary — 标记上下文边界
• compact_summary — 边界前历史的总结

效果：transcript view 看完整历史 + compact 事件，model view 从最近 boundary 后构建上下文，debug view 显示 compact 作用范围。

Tool-Result Pruning

原则：存储层保留原始结果，model view 降级为 stub，transcript view 显示完整值或懒加载，debug view 标出已 compacted。

最小实现：EngineMessage.metadata.compactedAt + projector 输出统一 stub。

---

模块划分

packages/engine-core/src/engine/ 下新增：

文件	职责
engine-messages.ts	Engine Message 类型 + 从持久化 Message 归一化
projections/types.ts	Projected / Model / Transcript / Debug 消息类型
projections/projector.ts	EngineMessageProjector 实现
ai-sdk-adapter.ts	ModelMessageSerializer

现有模块调整：

• session-history.ts — 历史读取、修复、转 Engine Messages
• engine-service.ts — orchestration，不直接承担 projection
• execution-message-content.ts — 底层 content 工具，逐步收缩直接拼模型消息的职责

---

贯穿示例

用户输入："帮我看看 src/auth.ts 为什么登录失败，并修一下。" 模型调用 Read(src/auth.ts)。

Engine Messages

[
  { id: "m1", kind: "system_note", role: "system", content: "Workspace root is /repo" },
  { id: "m2", kind: "user_input", role: "user", content: "帮我看看 src/auth.ts ..." },
  { id: "m3", kind: "tool_call", role: "assistant",
    content: [{ type: "tool-call", toolCallId: "call_1", toolName: "Read", input: { file_path: "src/auth.ts" } }] },
  { id: "m4", kind: "tool_result", role: "tool", metadata: { compactedAt: "2026-04-08T10:00:00Z" },
    content: [{ type: "tool-result", toolCallId: "call_1", output: { type: "text", value: "...长文件..." } }] },
  { id: "m5", kind: "assistant_text", role: "assistant", content: "我先定位问题，再修改登录逻辑。" }
]

Model Messages (after projectToModel)

[
  { view: "model", role: "system", semanticType: "system_note", sourceMessageIds: ["m1"], content: "Workspace root is /repo" },
  { view: "model", role: "user", semanticType: "user_input", sourceMessageIds: ["m2"], content: "帮我看看 src/auth.ts ..." },
  { view: "model", role: "assistant", semanticType: "tool_call", sourceMessageIds: ["m3"],
    content: [{ type: "tool-call", toolCallId: "call_1", toolName: "Read", input: { file_path: "src/auth.ts" } }] },
  { view: "model", role: "tool", semanticType: "tool_result", sourceMessageIds: ["m4"],
    metadata: { compacted: true },
    content: [{ type: "tool-result", toolCallId: "call_1", output: { type: "text", value: "[Old tool result content cleared]" } }] },
  { view: "model", role: "assistant", semanticType: "assistant_text", sourceMessageIds: ["m5"],
    content: "我先定位问题，再修改登录逻辑。" }
]

AI SDK Messages

[
  { role: "system", content: "Workspace root is /repo" },
  { role: "user", content: "帮我看看 src/auth.ts ..." },
  { role: "assistant", content: [{ type: "tool-call", toolCallId: "call_1", toolName: "Read", input: { file_path: "src/auth.ts" } }] },
  { role: "tool", content: [{ type: "tool-result", toolCallId: "call_1", output: { type: "text", value: "[Old tool result content cleared]" } }] },
  { role: "assistant", content: "我先定位问题，再修改登录逻辑。" }
]

---

迁移顺序

Phase	内容
1	引入 EngineMessage + projectToModel() 最小版本，不改外部 API 和持久化表
2	引入 compact artifacts（compact_boundary / compact_summary）
3	引入 tool-result pruning（compactedAt + model stub）
4	扩展 export / search / analytics 视图

非目标

当前不要求实现：session memory consolidation、reactive compact retry、context collapse、provider 专属 prompt cache 优化。