手册/第 06 章
会话:日志即真相,还带版本代际
在 dsh 里,会话不是「聊天的记录」,而是模型所见上下文的唯一来源。 这条规则被写成一句硬话,值得先看它,再看实现。
三句话讲完数据流
deriveMessages() 把模型历史从日志投影出来。历史不是被「维护」的,
是被「推导」的——所以不存在「内存和日志不一致」这种状态。
assistant/message 是成功落定,内嵌产生它的紧凑带时序流;
assistant/attempt 保留失败/重试/取消/流错误,但不进模型历史。
agent/assistant-stream 这条活的事件通道。
这也是为什么 dsh 敢说「硬死也不会留下半条 attempt 流」—— 落定之前,什么都不算数。
投影 seam:客户端看到的不是全部
dsh-session-projection 拥有 ctx.sessionProjections
(architecture.md:130)。注册进去的单元会增量折叠已提交事件,
载体再用 snapshot() 批量取裁剪后的客户端视图。
| 谁 | 职责 |
|---|---|
ctx.sessionProjections | 注册折叠单元;释放注册即退出全局参与,但已有句柄仍继续折叠。 |
AgentRegistry | 拥有 turn / step 状态,对外只给 turnBoundaryOf(session)。 |
AgentLoop | 拥有 modelSelection,并为每个 Agent 构造 model 实例与 inbox。 |
这个设计解决了一个具体问题:前端要的是裁剪过的视图,不是完整日志。 把「折叠」做成可注册的投影,前端就不需要理解每一种事件的语义。
代际迁移:格式如何演化而不丢历史
「Model-visible means logged」有一条硬推论:会话格式必须能变, 否则加一个新的模型可见输入,就等于把旧会话全废掉。dsh 的解法是代际:
| 代 | 文件名 | 说明 |
|---|---|---|
| v0 | session.jsonl[.zstd] | 无版本号的历史格式 |
| v1 及以后 | session.v<N>.jsonl[.zstd] | 小写 vN,代际显式入名 |
规则本身很短,但每条都有代价意识(architecture.md:126):
- 相邻两代恰好一个迁移包,每个包只负责
vN → vN+1一步——链式,不做笛卡尔积。 - 已提交的代际路径永不重命名、替换或删除(原文:"committed generation paths are never renamed, replaced, or deleted")。
- 写打开时先编码、校验,再独占发布一个版本命名的后继文件,源文件保持不动。
- 遇到未来版本直接拒绝,而不是猜着解析。
- 只读打开不发布后继,迁移结果只在内存里用一次。
顺手一个坑:中断的尾巴
进程被杀,日志末尾可能缺一条 turn/end。普通修复是 handle 消费方的责任;
迁移只在一种受限情形下补:那段被中断的 turn 已经被后来的 turn/start 封住了
(architecture.md:126)。这条边界划得很克制——不猜、不乱补。
architecture.md:128 · Model-visible means logged architecture.md:126 · 代际与迁移 session-projection/src/index.ts:252