DSH plugin Conversation 组装:target 激活与 window 更新怎么算
“回放后内容重复”和“只看到一半”往往不是渲染 bug,而是更新路径不同:replace 重建、prepend 只增量、append 只碰命中 Context。 DSH plugin 的 Conversation 组装把这三条路径写得很清楚,选错就会得到两套结果。 DSH插件 回放后内容重复,先分清 replace、prepend 与 append 三条路径。
window 归 Session Controller
assembler 直接吃 entry,不再开第二条历史流。(来源)
Session Controller 拥有连续的已加载逻辑 event window。每个 SessionEventLikeEntry 要么是表示持久事件的 { type: 'event', event },要么是表示 Client-only assistant/live-chunk 呈现的 { type: 'transient', event };两种内部 event 都公开 type、seq、time 与 data。
ui-conversation 把这些 entry 直接交给 assembler,不另开 history stream。每个 Session 对应一个 ConversationNodeAssembler,它应用所有已注册 Definition,并为每个已注册 view target 发布独立 source。
六种概念的分工
共享的只有机制,State 与最终 payload 都归各自 target。(来源)
- Event Definition — 业务包一次匹配一个持久或瞬态事件,以稳定
(kind, id)关联输入、折叠确定性 State,并可选 materialize 一个 target node。 - Context — 引擎为一个
(kind, id)拥有的有序 Match 与当前 State;持久与瞬态事件都可以作为 start;最早 start 初始化 State,后续 Match 更新它;只有 update 的证据保持 pending,直到其 start 加载。 - Location — 引擎根据持久 boundary event 推导的 Session、Turn 或 Step 坐标;Definition 可以向一个 Turn 或 Step 发布类型化数据。
- View Definition — Target 包为每个 Session 创建一个增量 builder,并拥有该 target 的最终 snapshot 类型。
- Group Definition — 业务包从物化后的 Node 派生根引用与组快照,拥有成员归属、分段、摘要与增量缓存。
- View — Chat 或 Trajectory 等 Slot entry 只读取自身 target snapshot,并渲染 target 自有 node。
Chat 与 Trajectory 可以识别同一个持久 event family,但各自保留自己的 Definition State 与最终 node payload。共享的 target-neutral 机制只包括 identity routing、有序 replay、Location data、predecessor dependency 与 publication cadence。
Target 激活:读不激活,订阅才激活
assembler 只接收解析后的 target id,不自己挑默认值。(来源)
每个 Session 都保留单调增长的 active target 集合。创建或读取 target source 不会激活它。shell 会显式激活持久化选择或新选择的 View,其他消费者则通过 target source 的首个订阅激活 target。
首次激活会创建该 target 的 builder,并从当前按 target 索引的 Context 调用一次 replace()。后续 flush 对每个 active target 调用 apply(),取消订阅不会移除 target。
shell 拥有 View 选择,并在 binding 创建、被选为 current 或 View roster 变化时,于渲染前解析已注册的偏好 View 或 Chat fallback。assembler 只接收解析后的 target id,不自行选择 Chat 或其他默认 target。第三方 View 使用相同的选择与激活操作。
三条 window 更新路径
只有 replace 是重建,prepend 与 append 都是增量的。(来源)
历史可能从尾部开始一页一页向前请求。Session journal 先校验互不重叠的逻辑 seq range,Assembler 再按每个已接受 input 的首 seq 排序并进入 State 回放。
| 路径 | 引擎行为 |
|---|---|
replace(open、resync、gap repair) | 重建已加载窗口,每条标准 event 或 packed run 对每个 Definition 匹配一次,再回放每个已有 start 的 Context:先 start,再按逻辑 seq 升序执行 update;只有 update 的 pending Context 仍没有 State |
prepend 一页更早历史 | 只匹配新增的更早 input,按 (kind, id) 合并进 Context,保留现有 keyed node,并只重放受影响的 Context 与依赖 |
append 一条实时事件 | 每个 Definition 各调用一次 match,按 key 查找命中的 Context,只更新该 Context,不扫描已有 Context |
| 增量 flush 失败 | 把已加载的完整窗口回放到新的 Context,替换每个 active view,然后抛出 rebuilt: true 的 ConversationUpdateError;重建也失败时抛 rebuilt: false,并在下一次 flush 重试 |
复杂度约束要写进你的 Definition:注册 D 个 Definition 时,一条新 scalar event 或 packed run 会进行 D 次仅当前 input 匹配;命中后的 Context key 查询是常数时间。正常 append 热路径不得遍历完整事件窗口、所有 Context、context.matches 或已渲染 Node 集合。累计事实放进 State,同 Turn 或 Step 共享的信息放进 Location data,有索引的前序依赖用 reader.previous()。
认领机制也值得单独记住:match 结果带 exclusive: true 时,即在该 Definition 的 target 上认领这个事件。Assembler 先求出该事件的全部 match,再逐个接收,因此结果与注册顺序无关;同一 target 被认领两次,或没有 target 的 Definition 发起认领,都会在分发时抛错。
Predecessor read 与前序依赖
前序依赖会被记录,并在前置信息变化时重跑。(来源)
有些 Definition 需要另一个业务 kind 在当前位置之前的最新 State。start 会收到 ConversationContextReader:应在这里调用 reader.previous<State>(kind),不要接收 Context 集合或扫描事件。Reader 返回当前 start seq 之前最近一个已启动 Context 的只读数据。
Assembler 会记录这项依赖。如果后续 older prepend 带来了更近的前序 Context、补齐了原先未知的窗口缺口,或者前序 State 被修订,引擎会从 start 重新运行依赖方 Context,并按 seq 升序回放其 update。
被查询的 Definition 仍负责把有用信息写入自身 State;Reader 不提供业务专用查询方法,也不授予修改其他 Context 的权限。
Group Definition 与发布节奏
组是引用与数据的组合,不拥有 Node 内容。(来源)
可选的 ctx.uiConversation.groups.register(definition) 沿用事件与视图注册的 effect 生命周期。它要求已有 View 目标,拒绝重复目标注册,不构造 Builder。每个 Session 仅在目标激活时创建自己的 Group 上下文;注册替换会丢弃旧上下文并清空其被观察的组。
注册分组时 Builder 必须提供 groupInput(),缺少输入方法在首次激活时报错。安装前会校验完整提交结果:根 Group 引用与记录一一对应,引用的 Node 全部存在,每个 (NodeKey, groupPart) 在根与成员位置中最多占位一次;整 Node 不能与自身任一部分共存;重复 upsert、重复删除以及同时 upsert 和删除一个组都会报错。
仅数据 upsert 保留根与成员数组、不读取 Node,并只通知变化组的来源;完整替换重新校验全部引用。渲染器按两种引用 kind 切换,由所属 View 选择组件,不通过组数据里的 renderer 字段选择。
发布节奏按内容变化选:结构或 terminal 变化使用 immediate,高频可见 delta 使用 animation-frame,只为后续发布积累 State 时使用 none。引擎按日志顺序应用每条 scalar update,并用一次 batch update 应用一个 packed run——这个选项只合并视图发布频率,不改变回放结果。
验证:切换 target 与回放
验证要证明三条路径收敛到同一结果。(来源) 六步:
- 对一个完整窗口执行 replace,断言最终 State、Location data、Node payload 与
anchorSeq符合预期。 - 只给尾部 update,断言 Context 保持 pending;prepend 其 start 后,断言结果与完整 replace 相同。
- 初始历史后继续实时 append,断言与回放合并后的完整窗口结果一致。
- prepend 更早分页,断言只增加更早的行,数据未变化的既有 keyed Node value 不被替换。
- 重复可见 delta,断言
context.key不变,且每帧最多发布一次。 - 让某个 Definition 在增量 flush 中抛错,断言每个 active target 都显示完整重建结果,后续事件继续更新它。
如果第 2 步 pending 的 Context 直接渲染了部分结果,说明你在 start 未加载时强行构造了 State——官方要求由 terminal 或 checkpoint 事件携带完整 fallback,而不是扫描无关事件。
节点匹配与注册的完整流程,可以对照Conversation 节点;客户端分层见Web Client 架构。
一句话收束: window 归 Controller、读不激活、replace 重建而 prepend 与 append 增量、前序依赖会重跑、组只持引用、发布节奏只影响频率不改结果。
常见问题
不会,DSH plugin 明确说创建或读取 target source 不激活它。DSH plugin 只在显式选择 View 或 target source 的首个订阅时做一次完整 replace。
不会,DSH plugin 只匹配新增的更早输入。DSH plugin 保留现有 keyed node,并只重放受影响的 Context 与依赖。
不能,DSH plugin 的 Reader 只返回只读数据。DSH plugin 不提供业务专用查询方法,也不授予修改其他 Context 的权限。
DSH plugin 回放已加载的完整窗口并替换每个 active view。DSH plugin 抛出 rebuilt 为 true 的 ConversationUpdateError;重建也失败时为 false,并在下一次 flush 重试。
相关术语
- SessionEventLikeEntry
- SessionEventLikeEntry 是已加载窗口的一项,或为持久 event,或为 Client-only 的 transient assistant/live-chunk。— DeepSeek Harness 官方参考 - Conversation 组装
- Context
- Context 是引擎为一个 (kind, id) 拥有的有序 Match 与当前 State,最早 start 初始化它。— DeepSeek Harness 官方参考 - Conversation 组装
- Location
- Location 是引擎由持久 boundary event 推导出的 Session、Turn 或 Step 坐标,可承载类型化数据。— DeepSeek Harness 官方参考 - Conversation 组装
- ConversationContextReader
- ConversationContextReader 在 start 中提供 reader.previous(kind),返回当前 start 之前最近一个已启动 Context 的只读数据。— DeepSeek Harness 官方参考 - Conversation 组装
来源
- DeepSeek Harness 官方参考 - Conversation 组装· deepseek-ai
- packages/client/ui-conversation/src/client/index.ts· deepseek-ai