ChatGPTClaudeGrok / X / CursorGemini

深入理解 DSH plugin 会话投影单元:纯折叠、快照与变更流、摘要读取到底该怎么选才稳妥

插件开发发布于 2026-11-12作者: DeepSeek Plugin 插件市场
DSH pluginDeepSeek Harness会话投影ProjectionSnapshot变更流
想在插件里读会话摘要,却不确定该订阅变更流还是直接读快照。本文讲投影单元的三条硬约束、wire 的发布条件、快照水位线与两类监听,以及摘要 key 集合的唯一来源。

投影单元最常见的事故不是算错,而是把“读状态”和“订阅变更”混成一条路径。 DSH plugin 的会话投影是一条能力 seam:注册表负责驱动,领域只负责计算。理解这句分工,才知道该用 snapshot()、stateOf() 还是 onChanged()。 DSH插件 里读摘要还是订阅变更流,取决于你要的是水位线,还是一帧帧的增量。

三方分工:注册表驱动,领域计算

框架负责驱动,领域负责计算,客户端只收成品值。(来源) 三方各归其位:

  1. Service Definition 与注册表 — ctx.sessionProjections,只订阅一次 session/event,把每个已提交事件折叠进每个单元;
  2. 领域贡献方 — 每个领域注册一个纯单元,自己不持有任何订阅;
  3. 载体 — dsh-session-controller 的历史尾页与 session/projection 推送帧。

这条分工直接排除了一种常见写法:插件自己去监听会话事件、自己维护一份派生状态、再和注册表的结果对账。领域不该有订阅,客户端也从不折叠领域事件——它收到的是成品值。Host 状态读取方在激活期间要求注册表存在,因此 sessionProjections 应当作为必需注入声明。

一个单元必须满足三条硬约束

纯、同步、可 JSON 化,是单元能被驱动的三个前提。(来源) ProjectionDefinition 的说明写得很直接:

  1. 纯同步折叠 — 它是一次同步 fold 加声明,再加可选客户端视图,永远不是一个不透明 getter。所有函数必须同步,异步单元会撕开载体的取数一致性切面。
  2. 状态必须是普通 JSON — 这是持久化缓存的前置条件,不是风格建议。
  3. 不关心的事件返回同一引用 — apply 对与本单位无关的事件必须返回同一个 state 引用,引用不变时下游工作量是零。

单元还有三个必填声明:key、stateSchema 与 stateVersion。stateSchema 用来在折叠前校验持久化状态;init 接收不可变的 SessionHeader 与精确的 inheritedEventCount,给出空日志的初始状态。

stateVersion 是一个非负的缓存失效版本。官方给的升级口径很细:状态字段或折叠语义变化时要升;但“可选新增、缺失时仍保留历史含义、且旧检查点后缀重放与完整重放等价”的改动可以保留版本。想省这次版本号,先测这个等价性——只通过 schema 校验不够。

wire 决定客户端可见性,渲染不归这层

单元有没有 wire,决定它是客户端可见还是宿主专用;wire 只影响发布,不影响渲染。(来源)

只有客户端可见的 key 会合并进 SessionProjectionMap,由它约束对应的全量值。wire 块包含三样东西:viewSchema、view(state) 与可选的 summary。viewSchema 在载荷离开宿主前校验;view 返回该 key 的完整当前值,即读侧投影。

发布判定依赖一个细节:实时驱动保留最近两次原始 view 结果并用 Object.is 比较。因此对象型 view 若想在“仅内部 state 变化”时抑制发布,就必须复用引用。这条约束常被忽略,结果是 UI 每次内部计数变化都收到一帧。

summary 默认 true。它决定运行时 key 集合,而客户端视图类型跟随 SessionProjectionSummaryExcluded 标记——两者要手动保持一致。渲染归 slot 体系管,永远不归这一层;wire 只让单元对客户端可见。

快照与变更流:一次读切与两类监听

快照保证“值都停在同一序号”,变更流保证“只告诉你变了什么”。(来源)

ProjectionSnapshot 只有两个字段:asOfSeq 与 values。asOfSeq 是共享水位线,表示所有值共同反映的最后一条事件序号,空日志为 -1。snapshot() 完全同步——载体在切出页面切片的同一 tick 内读取它,所以两次读取使用同一个序号,不会出现“值更新了但水位线没动”。

监听器有两类,区别在粒度:

  • onChanged(listener) — 某个单元的原始 view 结果按 Object.is 变化时,为那个会话、那个 key 调一次,带 value 与触发事件的 seq;
  • onEventChanged(listener) — 每个改变过至少一个客户端可见单元的事件调一次,changes 按注册顺序列出各 key 与校验后的 val。

时序上,onEventChanged 同步运行在已提交事件的 session/event 处理里,在所有单元驱动完、且该事件的所有 onChanged 调用之后。还有一个容错细节:如果某个单元或某个 onChanged 监听器在驱动中抛错,事件级监听器仍会收到抛错前已产生的变化。

读实时宿主状态时用 handle.stateOf(session),它不计算无关视图,返回的是借用引用,调用方不得修改。

摘要读取:key 集合只有一处定义

列表行拿的是摘要投影,不是全量投影,两者 key 集合不能混用。(来源)

摘要包含每个已注册客户端视图,但排除 SessionProjectionMap 条目带 SessionProjectionSummaryExcluded<T> 标记的 key。这个标记没有运行时表示:它决定客户端视图类型,运行时键集合由 wire.summary 决定,省略即 true。所以带标记的 key 应显式声明 wire.summary: false——类型层不强制,只能靠约定。

summaryKeys() 从实时注册派生集合,并在注册或注销改变 key 表之前持续返回同一实例。消费方把它传给既有的带 key 读取面:实时会话用 snapshot(session, keys),检查点行用 viewCheckpoint(rows, keys)。两者都直接使用 Set、不做复制,因此不存在摘要专用读取面,集合也只有一处定义。

cachedSnapshot() 已废弃,原因很实际:它只返回其他读取已经算好的值,可能缺 key。列表行只承诺摘要键集合,不承诺更多;打开会话后的全量快照才携带每个投影值。

注册生命周期:同 key 共享,最后一次释放才移除

注册归调用 fiber 所有,释放是引用计数语义,句柄在释放后仍能读。(来源)

register(definition) 返回可等待的 ProjectionHandle,领域在激活期间必须等注册完成再发布消费者,因为注册本身可能做异步工作。三条生命周期规则:

  1. 同 key 共享 — 同 key、同 stateVersion 的注册者共享一个单元,并被计数;版本不兼容时注册直接失败。
  2. 最后一次释放才移除 — 最后一次释放会把该 key 从全局驱动、恢复与客户端快照中移除;检查点仍保留每个会话里它的最后状态,直到该 key 再次注册并由新单元重新折叠日志。
  3. 句柄保留读取能力 — ProjectionHandle 注销后仍保留同步 reader。stateOf(session) 用原有单元折叠新提交事件,不会重新加入全局快照或通知;readerFor(session) 返回同一规则的同步回调,且不拥有销毁。

缓存单元是惰性构建的:如果单元在事件产生后才注册,或会话早于注册表存在,第一次访问(事件或读取)会从 init 开始折叠内存日志。这解释了“新插件刚装上时读到完整历史”的行为——不是预加载,而是首次访问补齐。

持久化侧还有两个读取面值得知道。checkpoint(session) 给每个已注册 key 一行,值是与活单元分离的结构化克隆,绝不返回活引用;restoreFloor(checkpoint) 指出后缀重读的起点,一行版本不匹配时会把起点拉回 0,强制该 key 全量重折,这样崩溃导致的日志截断不会被当作“缓存仍有效”。

零 I/O 的 viewCheckpoint(rows, keys) 则只读行、不读日志:值可能与行一样旧,但永不出错。它适合列表与冷启动,不适合做“当前是否最新”的判断。

验证:同一会话分别走快照与变更流

两条读取路径必须收敛到同一个水位线,否则你读到的是两份真相。(来源) 六步:

  1. 注册一个带 wire 的单元,apply 对无关事件返回同引用,断言不会触发变更。
  2. 提交一个相关事件,用 onChanged 收一次回调,记录其 seq。
  3. 同一 tick 内调 snapshot(session),断言 asOfSeq 等于上一步的 seq。
  4. 注册一个宿主专用单元(不带 wire),断言 snapshot 的 values 里没有它。
  5. 调 summaryKeys() 两次,断言是同一实例;再用 snapshot(session, keys) 只取摘要 key。
  6. 注销该单元,调 stateOf(session) 继续读新事件,断言仍能折叠且不再进全局快照。

如果第 3 步对不上,先确认事件是否真的提交完成——变更流只在提交后触发,asOfSeq 也只在读取时反映已提交水位。跨窗口的折叠行为与替换代次,可以对照会话派生消息与会话日志。

一句话收束: 单元要纯要同步,wire 管可见不管渲染,快照看水位线、变更流看粒度,摘要 key 只从 summaryKeys() 来。

ChatGPTClaudeGrok / X / CursorGemini

常见问题

DSH plugin 的投影单元可以写成 async 函数吗,为什么不行?

不能,DSH plugin 要求所有单元函数同步。DSH plugin 的单元契约写明异步单元会撕开载体的取数一致性切面,所以 apply、init 与 view 都必须是同步纯函数。

DSH plugin 的 apply 对不关心的事件要做什么?

原样返回同一个 state 引用,DSH plugin 靠引用相等判断下游是否要工作。DSH plugin 用 Object.is 比较,未变化的引用不会产生任何下游计算与发布。

DSH plugin 的 snapshot 会不会顺带算宿主专用单元?

不会,DSH plugin 只计算被选中的客户端可见单元。DSH plugin 不传 key 子集时计算每个客户端可见单元,宿主专用单元既不会被折叠也不会被推进。

DSH plugin 的摘要 key 集合每次调用都是新对象吗?

不是,DSH plugin 的 summaryKeys() 在注册表变化前返回同一实例。DSH plugin 允许你把集合跨行持有并直接传给 snapshot 或 viewCheckpoint,这两个读取面都不会复制它。

相关术语

ProjectionDefinition
ProjectionDefinition 是一个领域的状态驱动计算单元,包含 key、stateSchema、init、apply、可选 wire 与 stateVersion。— packages/session/session-projection/src/index.ts
ProjectionSnapshot
ProjectionSnapshot 是对某个会话所有已注册客户端可见单元的一次一致读切,含 asOfSeq 水位线与各 key 的当前值。— packages/session/session-projection/src/index.ts
asOfSeq
asOfSeq 是快照的共享水位线,表示所有值共同反映的最后一条事件序号,空日志为 -1。— packages/session/session-projection/src/index.ts
summaryKeys
summaryKeys 返回当前摘要携带的客户端可见 key 集合,在注册或注销改变 key 表前保持同一实例。— packages/session/session-projection/src/index.ts

来源