DSH plugin 会话事件怎么变成消息:deriveMessages、Surface 与结束原因
日志里事件一条不少,取消息时却少了几条或多出空消息,问题几乎都出在派生规则上。 DSH plugin 的会话只存 SessionEvent,模型看到的消息是投影出来的。把投影当存储读,就会反复怀疑日志写漏了。 无论你写的是 DSH插件 还是 DeepSeek插件,只要从日志派生消息,这套规则都一字不改。
会话是日志,消息是投影
唯一真源是仅追加的事件日志,Message[] 只是它的一种读出方式。(来源) 三句话概括这个模型:
Session是一份类型化SessionEvent组成的仅追加日志,记录 agent 的完整交互历史;- LLM 消息历史从日志派生,从不单独存储;
- 回放就是从同一组事件重新派生,而不是读另一份快照。
这条设计决定了一个排查习惯:遇到消息异常,先去日志里看事件序列,而不是先怀疑派生缓存。缓存只会放大错误,不会凭空造出事件。
Surface 决定了哪些事件能变成消息
只有 SurfaceEventType 子集会产生消息,其余事件全是结构信息。(来源) 五个成员:
system/messagedeveloper/messageuser/messageassistant/messagetool/result
每个产生消息的事件都必须声明 surfaceOp,这是它加入有序派生 surface 的唯一方式。SurfaceOp 只有两种取值:
type SurfaceOp = 'append' | { op: 'replace'; startSeq: SessionSeq; endSeq: SessionSeq }
append 是常规尾部追加。replace 恰好包含 op、startSeq、endSeq 三个键,不接受别名或额外键;它遮蔽这两个当前 surface 事件序号之间的闭区间,并在原位置插入新事件,相同端点只替换一个条目。
这里有一个反直觉的约束:端点必须早于替换事件,但它们的相对顺序按 surface 顺序而非数值序号顺序确定。压缩替换之所以能遮蔽早期节点,正是靠这套 surface 顺序语义,而不是靠 seq 大小比较。
非 surface 事件不允许携带这套元数据,编译期就会拒绝。所以如果你给一个纯日志事件传了 surfaceOp,问题不在运行时,而在类型层。
deriveMessages 的六条投影规则
六条规则逐条对上,才能解释“为什么这条没出现、那条出现了两次”。(来源)
user/message— 投影成一条携带确切content的 user 消息;可选 envelope 只作为日志展示元数据保留,不进消息体。assistant/message— 投影成一条 assistant 消息,包含生成它的提供方与模型,以及可选的适配器私有回放状态。内嵌紧凑 stream 是回放、usage 与 UI 的证据,不是第二条消息。- 空内容
assistant/message— 跳过。因 max-tokens 截断且无内容的步骤仍会记录一条assistant/message来保存 stream、usage、提供方与模型,但无内容轮次不得进入提供方 transcript。 tool/result— 投影成一条一等 tool-role 消息,携带结果内容与工具调用标识。- 注入的
user/message— 非 user 来源的注入上下文按时间顺序在相应位置生成 user-role 消息,原样承载 content,其类型化source标明生产方并携带生产方专用数据。 - 其余事件 —
turn/*、step/*、assistant/attempt、插件所属的llm/retry都只提供结构信息,不投影为消息。
第 2 条与第 3 条合起来解释了一个常见现象:日志里有一条 assistant/message,派生结果里却没有。先看内容是否为空,再看是否有 interrupted: true。被取消的轮次会把已交付文本前缀落成该事件并标记 interrupted,未派发的工具调用不存在。
token 记账也走这条路径:它会展开每个 assistant/message 或 assistant/attempt 的内嵌 stream,但消息顶层 usage 存在时,顶层仍是已提交消息的权威。失败的 attempt 因此可以保留提供方 usage,而不必虚构一条 assistant 消息。
缓存与冻结:为什么改历史编译不过
deriveMessages() 既缓存又冻结,两个性质分别解决性能与安全。(来源)
缓存口径是:每个 surface 节点在首次出现时投影一次,surface 重写触发重建。所以正常追加只投影新增节点,而一次 replace 会让受影响的部分重算。你看到“派生变慢”,先确认是不是有插件频繁做替换。
冻结口径是:每次调用返回一个新数组,数组里引用共享的深冻结消息。这个设计让“通过投影改已记录历史”在类型上不可表达——不是运行时抛错,而是你根本写不出来。
deriveEventMessage(event) 是折叠所应用的逐节点纯函数,官方把它公开出来,是为了让外部重建器用完全相同的规则投影日志前缀,避免与内部缓存产生分歧。你要在离线工具里重建一段历史,就该用它,而不是自己复制一份规则。
实时读取还有第三个入口:Session.surface 返回稳定的 SessionSurface 视图,你能观察 nodes、replaceGeneration 与 contentGeneration,但不能调用校验。replaceGeneration 只统计位置替换,contentGeneration 还统计插件拥有的消息内容变更,两者用途不同。
TurnEndReasonMap:结束原因改变读法
同一条 assistant/message,在不同结束原因下应有不同解读。(来源) turn/end 携带的 reason 是可合并扩展的联合类型:
| 原因 | 含义 |
|---|---|
completed | 正常完成 |
aborted | 取消请求中断实时轮次,携带 TurnEndCancelCause |
blocked | 被阻塞 |
error | 失败,error 始终是结构化的 LlmFailure |
max-tokens | 至少一个步骤到达输出上限 |
interrupted | 崩溃遗留轮次事后关闭 |
forked | fork 种子构造关闭了源会话中仍打开的轮次 |
三个细节值得记住:
aborted的原因里可能出现{ kind: 'legacy' },那只是导入的粗粒度记录没有保存调用方,不代表当时没有取消者。error若来自非 LLM 错误,会被压平成{ message, code },其中工具条件失败用TOOL_ACTIVATION_FAILED,其余为UNKNOWN。max-tokens是整轮判定:轮次内任何步骤以它结束,整轮就以它结束,即使之后继续执行,截断事实仍优先。
interrupted 与 forked 都不会由 loop 实时发出,前者由崩溃恢复或冷读合成,后者只出现在 fork 种子里。看到这两个原因,不要去找“哪段代码触发的”,要去看恢复或 fork 路径。
验证:用固定事件序列跑派生
固定序列比随机回放可靠,因为每条断言都能指到具体规则。(来源) 六步:
- 追加
turn/start、user/message、step/start,调deriveMessages(),断言只有一条 user 消息。 - 追加
assistant/message(带 stream 与 usage),断言多出一条 assistant 消息,且 usage 来自顶层。 - 追加一条内容为空的
assistant/message,断言消息条数不变,但日志条目数增加。 - 在
turn/end与下一条turn/start之间插入一条纯日志事件,断言它不产生消息,只占用 seq。 - 让某个 step 以 max-tokens 结束,断言整轮
turn/end的 reason 是max-tokens而非completed。 - 对同一段前缀调用
deriveEventMessage()逐节点重建,断言与deriveMessages()结果逐条一致。
如果第 6 步对不上,通常是你在重建时自己处理了 surfaceOp 的替换语义。让 foldSurface 与 deriveEventMessage() 一起工作,比自己写一遍折叠更稳。事件词汇的完整清单与持久化细节,可以对照会话日志与会话查询 API。
一句话收束: 只有 surface 事件产消息,deriveMessages() 只是投影,空内容与结构事件都不进历史,结束原因要按整轮读。
常见问题
不存在单独的表,DSH plugin 的模型消息历史从会话日志派生。DSH plugin 只持久化类型化的 SessionEvent,deriveMessages() 与 deriveEventMessage() 负责把事件投影成 Message[],回放就是拿同一组事件重新派生。
因为它保存了 stream、usage 与路由证据,但不会进入提供方 transcript。DSH plugin 对因 max-tokens 截断且内容为空的步骤仍记录一条 assistant/message,投影时跳过它,避免无内容轮次污染模型历史。
不能只靠单个 step,DSH plugin 按整轮判定。DSH plugin 只要轮次内有任何步骤以 max-tokens 结束,整个轮次就以 max-tokens 而不是 completed 结束,即使插件之后继续执行,截断事实仍然优先。
不是,DSH plugin 的 loop 不会实时发出这个标记。DSH plugin 的 interrupted 由崩溃恢复在事后补齐,或者在冷读时由 session-query 合成,崩溃前已记录的事件保持完整。
相关术语
- SurfaceEventType
- SurfaceEventType 是会产消息的事件子集,包含 system/message、developer/message、user/message、assistant/message 与 tool/result,携带 surface 元数据。— packages/core/session/src/types.ts
- surfaceOp
- surfaceOp 声明事件如何进入有序派生 surface,只有 append 与 replace 两种,replace 用 startSeq 与 endSeq 遮蔽闭区间。— packages/core/session/src/types.ts
- deriveEventMessage
- deriveEventMessage 是 surface 折叠所应用的逐节点纯函数,公开暴露给外部重建器,用来投影日志前缀且不与缓存分歧。— packages/core/session/src/types.ts
- TurnEndReasonMap
- TurnEndReasonMap 是可合并扩展的结束原因联合类型,覆盖 completed、aborted、blocked、error、max-tokens、interrupted 与 forked。— packages/core/session/src/types.ts
来源
- DeepSeek Harness 官方参考 - 会话· deepseek-ai
- packages/core/session/src/types.ts· deepseek-ai