ChatGPTClaudeGrok / X / CursorGemini

DSH plugin Conversation 组装:target 激活与 window 更新怎么算

插件开发发布于 2026-11-12作者: DeepSeek Plugin 插件市场
DSH pluginDeepSeek HarnessConversationtarget 激活window 更新
会话切换或回放后,窗口内容重复或缺失,不知道更新路径。本文讲事件窗口的所有权、target 的首次激活与 replace、prepend 与 append 的差异、predecessor 依赖重跑,以及分组校验与发布节奏。

“回放后内容重复”和“只看到一半”往往不是渲染 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。(来源)

  1. Event Definition — 业务包一次匹配一个持久或瞬态事件,以稳定 (kind, id) 关联输入、折叠确定性 State,并可选 materialize 一个 target node。
  2. Context — 引擎为一个 (kind, id) 拥有的有序 Match 与当前 State;持久与瞬态事件都可以作为 start;最早 start 初始化 State,后续 Match 更新它;只有 update 的证据保持 pending,直到其 start 加载。
  3. Location — 引擎根据持久 boundary event 推导的 Session、Turn 或 Step 坐标;Definition 可以向一个 Turn 或 Step 发布类型化数据。
  4. View Definition — Target 包为每个 Session 创建一个增量 builder,并拥有该 target 的最终 snapshot 类型。
  5. Group Definition — 业务包从物化后的 Node 派生根引用与组快照,拥有成员归属、分段、摘要与增量缓存。
  6. 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 与回放

验证要证明三条路径收敛到同一结果。(来源) 六步:

  1. 对一个完整窗口执行 replace,断言最终 State、Location data、Node payload 与 anchorSeq 符合预期。
  2. 只给尾部 update,断言 Context 保持 pending;prepend 其 start 后,断言结果与完整 replace 相同。
  3. 初始历史后继续实时 append,断言与回放合并后的完整窗口结果一致。
  4. prepend 更早分页,断言只增加更早的行,数据未变化的既有 keyed Node value 不被替换。
  5. 重复可见 delta,断言 context.key 不变,且每帧最多发布一次。
  6. 让某个 Definition 在增量 flush 中抛错,断言每个 active target 都显示完整重建结果,后续事件继续更新它。

如果第 2 步 pending 的 Context 直接渲染了部分结果,说明你在 start 未加载时强行构造了 State——官方要求由 terminal 或 checkpoint 事件携带完整 fallback,而不是扫描无关事件。

节点匹配与注册的完整流程,可以对照Conversation 节点;客户端分层见Web Client 架构。

一句话收束: window 归 Controller、读不激活、replace 重建而 prepend 与 append 增量、前序依赖会重跑、组只持引用、发布节奏只影响频率不改结果。

ChatGPTClaudeGrok / X / CursorGemini

常见问题

DSH plugin 创建 target source 会触发构建吗?

不会,DSH plugin 明确说创建或读取 target source 不激活它。DSH plugin 只在显式选择 View 或 target source 的首个订阅时做一次完整 replace。

DSH plugin 的 prepend 会重建全部 Node 吗?

不会,DSH plugin 只匹配新增的更早输入。DSH plugin 保留现有 keyed node,并只重放受影响的 Context 与依赖。

DSH plugin 的 reader.previous 能改别的 Context 吗?

不能,DSH plugin 的 Reader 只返回只读数据。DSH plugin 不提供业务专用查询方法,也不授予修改其他 Context 的权限。

DSH plugin 的增量 flush 抛错之后,视图会变成什么样?

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 组装

来源