DeepSeek Harness 学习手册 第 06 / 11 章 总目录 单页全本 架构图 GitHub

手册/第 06 章

06

会话:日志即真相,还带版本代际

在 dsh 里,会话不是「聊天的记录」,而是模型所见上下文的唯一来源。 这条规则被写成一句硬话,值得先看它,再看实现。

"Model-visible means logged. Every model request must be reconstructable from the log. New model-visible inputs require session events."
模型看得见的,就必须被记录。每一次模型请求都必须能从日志重建;任何新的、模型可见的输入,都必须先成为会话事件。
— docs/architecture.md:128

三句话讲完数据流

Ⅰ日志 → 历史
deriveMessages() 把模型历史从日志投影出来。历史不是被「维护」的, 是被「推导」的——所以不存在「内存和日志不一致」这种状态。
Ⅱ两次落定,语义不同
assistant/message 是成功落定,内嵌产生它的紧凑带时序流; assistant/attempt 保留失败/重试/取消/流错误,但不进模型历史。
Ⅲ一切都从落定推导
fork、resume、transcript、telemetry、持久化全部由这些持久落定推导; 只有「UI 增量」走 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 的解法是代际:

代文件名说明
v0session.jsonl[.zstd]无版本号的历史格式
v1 及以后session.v<N>.jsonl[.zstd]小写 vN,代际显式入名

规则本身很短,但每条都有代价意识(architecture.md:126):

  1. 相邻两代恰好一个迁移包,每个包只负责 vN → vN+1 一步——链式,不做笛卡尔积。
  2. 已提交的代际路径永不重命名、替换或删除(原文:"committed generation paths are never renamed, replaced, or deleted")。
  3. 写打开时先编码、校验,再独占发布一个版本命名的后继文件,源文件保持不动。
  4. 遇到未来版本直接拒绝,而不是猜着解析。
  5. 只读打开不发布后继,迁移结果只在内存里用一次。
为什么值得单独一章 这是 dsh 与「一个 JSONL 一把梭」最实质的差别。两者都用 JSONL, 但 dsh 把它当成需要长期演进的协议:要有版本、要能前向拒绝、要能链式迁移、要保证已发布文件不可变。 这些东西在只服务自己的工具里是纯负担,在要活过多年的产品里是必需品。

顺手一个坑:中断的尾巴

进程被杀,日志末尾可能缺一条 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

本章学习记录

记录仅保存在当前浏览器。