ChatGPTClaudeGrok / X / CursorGemini

DSH plugin 会话事件怎么变成消息:deriveMessages、Surface 与结束原因

插件开发发布于 2026-11-12作者: DeepSeek Plugin 插件市场
DSH pluginDeepSeek HarnessderiveMessagesSurfaceTurnEndReason
日志里事件齐全,取消息却顺序不对或边界错位。本文讲 SessionEventMap 中哪些事件产生消息、surfaceOp 如何进入派生 surface、deriveMessages 的六条规则,以及 TurnEndReasonMap 对读取的影响。

日志里事件一条不少,取消息时却少了几条或多出空消息,问题几乎都出在派生规则上。 DSH plugin 的会话只存 SessionEvent,模型看到的消息是投影出来的。把投影当存储读,就会反复怀疑日志写漏了。 无论你写的是 DSH插件 还是 DeepSeek插件,只要从日志派生消息,这套规则都一字不改。

会话是日志,消息是投影

唯一真源是仅追加的事件日志,Message[] 只是它的一种读出方式。(来源) 三句话概括这个模型:

  1. Session 是一份类型化 SessionEvent 组成的仅追加日志,记录 agent 的完整交互历史;
  2. LLM 消息历史从日志派生,从不单独存储;
  3. 回放就是从同一组事件重新派生,而不是读另一份快照。

这条设计决定了一个排查习惯:遇到消息异常,先去日志里看事件序列,而不是先怀疑派生缓存。缓存只会放大错误,不会凭空造出事件。

Surface 决定了哪些事件能变成消息

只有 SurfaceEventType 子集会产生消息,其余事件全是结构信息。(来源) 五个成员:

  • system/message
  • developer/message
  • user/message
  • assistant/message
  • tool/result

每个产生消息的事件都必须声明 surfaceOp,这是它加入有序派生 surface 的唯一方式。SurfaceOp 只有两种取值:

ts
type SurfaceOp = 'append' | { op: 'replace'; startSeq: SessionSeq; endSeq: SessionSeq }

append 是常规尾部追加。replace 恰好包含 op、startSeq、endSeq 三个键,不接受别名或额外键;它遮蔽这两个当前 surface 事件序号之间的闭区间,并在原位置插入新事件,相同端点只替换一个条目。

这里有一个反直觉的约束:端点必须早于替换事件,但它们的相对顺序按 surface 顺序而非数值序号顺序确定。压缩替换之所以能遮蔽早期节点,正是靠这套 surface 顺序语义,而不是靠 seq 大小比较。

非 surface 事件不允许携带这套元数据,编译期就会拒绝。所以如果你给一个纯日志事件传了 surfaceOp,问题不在运行时,而在类型层。

deriveMessages 的六条投影规则

六条规则逐条对上,才能解释“为什么这条没出现、那条出现了两次”。(来源)

  1. user/message — 投影成一条携带确切 content 的 user 消息;可选 envelope 只作为日志展示元数据保留,不进消息体。
  2. assistant/message — 投影成一条 assistant 消息,包含生成它的提供方与模型,以及可选的适配器私有回放状态。内嵌紧凑 stream 是回放、usage 与 UI 的证据,不是第二条消息。
  3. 空内容 assistant/message — 跳过。因 max-tokens 截断且无内容的步骤仍会记录一条 assistant/message 来保存 stream、usage、提供方与模型,但无内容轮次不得进入提供方 transcript。
  4. tool/result — 投影成一条一等 tool-role 消息,携带结果内容与工具调用标识。
  5. 注入的 user/message — 非 user 来源的注入上下文按时间顺序在相应位置生成 user-role 消息,原样承载 content,其类型化 source 标明生产方并携带生产方专用数据。
  6. 其余事件 — 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崩溃遗留轮次事后关闭
forkedfork 种子构造关闭了源会话中仍打开的轮次

三个细节值得记住:

  • aborted 的原因里可能出现 { kind: 'legacy' },那只是导入的粗粒度记录没有保存调用方,不代表当时没有取消者。
  • error 若来自非 LLM 错误,会被压平成 { message, code },其中工具条件失败用 TOOL_ACTIVATION_FAILED,其余为 UNKNOWN。
  • max-tokens 是整轮判定:轮次内任何步骤以它结束,整轮就以它结束,即使之后继续执行,截断事实仍优先。

interrupted 与 forked 都不会由 loop 实时发出,前者由崩溃恢复或冷读合成,后者只出现在 fork 种子里。看到这两个原因,不要去找“哪段代码触发的”,要去看恢复或 fork 路径。

验证:用固定事件序列跑派生

固定序列比随机回放可靠,因为每条断言都能指到具体规则。(来源) 六步:

  1. 追加 turn/start、user/message、step/start,调 deriveMessages(),断言只有一条 user 消息。
  2. 追加 assistant/message(带 stream 与 usage),断言多出一条 assistant 消息,且 usage 来自顶层。
  3. 追加一条内容为空的 assistant/message,断言消息条数不变,但日志条目数增加。
  4. 在 turn/end 与下一条 turn/start 之间插入一条纯日志事件,断言它不产生消息,只占用 seq。
  5. 让某个 step 以 max-tokens 结束,断言整轮 turn/end 的 reason 是 max-tokens 而非 completed。
  6. 对同一段前缀调用 deriveEventMessage() 逐节点重建,断言与 deriveMessages() 结果逐条一致。

如果第 6 步对不上,通常是你在重建时自己处理了 surfaceOp 的替换语义。让 foldSurface 与 deriveEventMessage() 一起工作,比自己写一遍折叠更稳。事件词汇的完整清单与持久化细节,可以对照会话日志与会话查询 API。

一句话收束: 只有 surface 事件产消息,deriveMessages() 只是投影,空内容与结构事件都不进历史,结束原因要按整轮读。

ChatGPTClaudeGrok / X / CursorGemini

常见问题

DSH plugin 里消息历史存在哪张表,还是每次都从日志派生?

不存在单独的表,DSH plugin 的模型消息历史从会话日志派生。DSH plugin 只持久化类型化的 SessionEvent,deriveMessages() 与 deriveEventMessage() 负责把事件投影成 Message[],回放就是拿同一组事件重新派生。

DSH plugin 的空 assistant/message 为什么还留在日志里?

因为它保存了 stream、usage 与路由证据,但不会进入提供方 transcript。DSH plugin 对因 max-tokens 截断且内容为空的步骤仍记录一条 assistant/message,投影时跳过它,避免无内容轮次污染模型历史。

DSH plugin 的 turn 结束原因能靠轮次内某个 step 推断吗?

不能只靠单个 step,DSH plugin 按整轮判定。DSH plugin 只要轮次内有任何步骤以 max-tokens 结束,整个轮次就以 max-tokens 而不是 completed 结束,即使插件之后继续执行,截断事实仍然优先。

DSH plugin 的 interrupted 结束原因是 loop 实时发的吗?

不是,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

来源