Session zh

会话

上游事件溯源会话日志在 Edge 中的适配。

上游参考：会话文档

上游提供了什么

Session 是一个追加式的类型化事件日志——所有 Agent 交互历史的唯一 source of truth。LLM 消息历史从此日志派生，不单独存储。核心概念：

• SessionEventMap — 可合并扩展的事件词汇表：turn/step 边界、用户/助手消息、工具调用/结果、请求头、goal 变更等。
• Surface 事件 — 三种事件类型（user/message、assistant/message、tool/result）携带 surfaceOp 元数据声明它们如何进入派生消息历史。
• deriveMessages() — 从事件日志到模型可见 Message[] 的缓存投影。Surface 重写时重建；消息被冻结。
• 持久化契约 — 事件必须可无损 JSON 序列化、seq 连续、完整（含原始 chunk）。后端可自由编码；加载必须返回相同事件。
• Cordis API（ctx.sessions）— 创建、fork、flush、dispose 生命周期。事件通过 session/event 广播。

Edge 改了什么

直接复用 SessionStore 插件

SessionStore 原封安装。事件日志、追加验证、surface 管理、消息派生、fork 逻辑和 flush 契约完全是上游代码。

替换件 持久化后端

上游将 session 持久化为本地文件系统的 JSONL 文件。Edge 用基于 DO SQL 表的 DurableObjectSessionPersistence 替换。详见 会话持久化 页面。

传输桥 事件推送

上游客户端通过 ctx.on('session/event') 在进程内观察事件。Edge 通过同一个 cordis 钩子捕获事件，以 session/event WebSocket 帧推送给浏览器。

Edge 没有改什么

• 事件类型、schema 和 SessionEventMap 词汇表
• Surface 事件语义和消息派生逻辑
• Session fork 边界和 seed 处理
• 追加验证（JSON 可序列化性、seq 连续性、surface 约束）
• Flush/checkpoint 契约

性能特征

事件追加

session.append() 是同步的——验证、推入内存日志、广播给 cordis 监听者。持久化写入在 flush() 时异步发生。这符合上游的契约：追加很快，持久性是独立的检查点。

消息派生

deriveMessages() 从 surface 投影重建消息数组。结果被缓存，仅在 surface 重写（compaction）时失效。对大多数事件（chunk、工具调用），缓存不受影响。代价：首次调用或重写后 O(surface 事件数)；后续读取 O(1)。

事件广播扇出

每个追加的事件同步通知所有 session/event 监听者：SessionProjectionRegistry.drive()、onChanged 投影缓冲、GoalRoundDriver 和 Edge 自己的 publishSessionEvent 推送链。所有监听者都是同步的且每个事件常量时间。

架构总结

| 组件 | 分类 | Edge 代码 |

|---|---|---|

| SessionStore | 复用 | 一行 ctx.plugin() 调用 |

| 持久化后端 | 替换 | DurableObjectSessionPersistence |

| 事件推送 | 桥接 | publishSessionEvent → WebSocket |

关键观察：Session 是整个系统的基础数据结构——每个（goal、title、projection、compaction）都建立在它的事件日志上。Edge 把它当黑盒：安装插件、替换存储后端、桥接事件推送。事件模型本身零修改。