深入理解 DSH plugin 会话投影单元:纯折叠、快照与变更流、摘要读取到底该怎么选才稳妥
投影单元最常见的事故不是算错,而是把“读状态”和“订阅变更”混成一条路径。 DSH plugin 的会话投影是一条能力 seam:注册表负责驱动,领域只负责计算。理解这句分工,才知道该用 snapshot()、stateOf() 还是 onChanged()。 DSH插件 里读摘要还是订阅变更流,取决于你要的是水位线,还是一帧帧的增量。
三方分工:注册表驱动,领域计算
框架负责驱动,领域负责计算,客户端只收成品值。(来源) 三方各归其位:
- Service Definition 与注册表 —
ctx.sessionProjections,只订阅一次session/event,把每个已提交事件折叠进每个单元; - 领域贡献方 — 每个领域注册一个纯单元,自己不持有任何订阅;
- 载体 —
dsh-session-controller的历史尾页与session/projection推送帧。
这条分工直接排除了一种常见写法:插件自己去监听会话事件、自己维护一份派生状态、再和注册表的结果对账。领域不该有订阅,客户端也从不折叠领域事件——它收到的是成品值。Host 状态读取方在激活期间要求注册表存在,因此 sessionProjections 应当作为必需注入声明。
一个单元必须满足三条硬约束
纯、同步、可 JSON 化,是单元能被驱动的三个前提。(来源) ProjectionDefinition 的说明写得很直接:
- 纯同步折叠 — 它是一次同步 fold 加声明,再加可选客户端视图,永远不是一个不透明 getter。所有函数必须同步,异步单元会撕开载体的取数一致性切面。
- 状态必须是普通 JSON — 这是持久化缓存的前置条件,不是风格建议。
- 不关心的事件返回同一引用 —
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,领域在激活期间必须等注册完成再发布消费者,因为注册本身可能做异步工作。三条生命周期规则:
- 同 key 共享 — 同 key、同 stateVersion 的注册者共享一个单元,并被计数;版本不兼容时注册直接失败。
- 最后一次释放才移除 — 最后一次释放会把该 key 从全局驱动、恢复与客户端快照中移除;检查点仍保留每个会话里它的最后状态,直到该 key 再次注册并由新单元重新折叠日志。
- 句柄保留读取能力 —
ProjectionHandle注销后仍保留同步 reader。stateOf(session)用原有单元折叠新提交事件,不会重新加入全局快照或通知;readerFor(session)返回同一规则的同步回调,且不拥有销毁。
缓存单元是惰性构建的:如果单元在事件产生后才注册,或会话早于注册表存在,第一次访问(事件或读取)会从 init 开始折叠内存日志。这解释了“新插件刚装上时读到完整历史”的行为——不是预加载,而是首次访问补齐。
持久化侧还有两个读取面值得知道。checkpoint(session) 给每个已注册 key 一行,值是与活单元分离的结构化克隆,绝不返回活引用;restoreFloor(checkpoint) 指出后缀重读的起点,一行版本不匹配时会把起点拉回 0,强制该 key 全量重折,这样崩溃导致的日志截断不会被当作“缓存仍有效”。
零 I/O 的 viewCheckpoint(rows, keys) 则只读行、不读日志:值可能与行一样旧,但永不出错。它适合列表与冷启动,不适合做“当前是否最新”的判断。
验证:同一会话分别走快照与变更流
两条读取路径必须收敛到同一个水位线,否则你读到的是两份真相。(来源) 六步:
- 注册一个带
wire的单元,apply对无关事件返回同引用,断言不会触发变更。 - 提交一个相关事件,用
onChanged收一次回调,记录其seq。 - 同一 tick 内调
snapshot(session),断言asOfSeq等于上一步的seq。 - 注册一个宿主专用单元(不带
wire),断言snapshot的values里没有它。 - 调
summaryKeys()两次,断言是同一实例;再用snapshot(session, keys)只取摘要 key。 - 注销该单元,调
stateOf(session)继续读新事件,断言仍能折叠且不再进全局快照。
如果第 3 步对不上,先确认事件是否真的提交完成——变更流只在提交后触发,asOfSeq 也只在读取时反映已提交水位。跨窗口的折叠行为与替换代次,可以对照会话派生消息与会话日志。
一句话收束: 单元要纯要同步,wire 管可见不管渲染,快照看水位线、变更流看粒度,摘要 key 只从 summaryKeys() 来。
常见问题
不能,DSH plugin 要求所有单元函数同步。DSH plugin 的单元契约写明异步单元会撕开载体的取数一致性切面,所以 apply、init 与 view 都必须是同步纯函数。
原样返回同一个 state 引用,DSH plugin 靠引用相等判断下游是否要工作。DSH plugin 用 Object.is 比较,未变化的引用不会产生任何下游计算与发布。
不会,DSH plugin 只计算被选中的客户端可见单元。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
来源
- DeepSeek Harness 官方参考 - 会话投影· deepseek-ai
- packages/session/session-projection/src/index.ts· deepseek-ai