deepseek-harness/packages/session/session-projection/README.zh.md

description, kind

description	kind
面向开发者与维护者的会话投影注册表说明，用于向客户端载体提供日志派生逐会话状态的完整当前值，或维护驱动约定。	package-reference

@deepseek-ai/dsh-session-projection

English | 中文

概述

当客户端需要当前的逐会话状态（例如待办事项、目标或对话统计）而不应自行重放原始事件日志时，使用 dsh-session-projection。领域根据已提交的会话事件定义同步投影，客户端则通过快照与变更通知接收经过 schema 校验的完整 JSON 值。快照标明所有返回值共同反映到的最后一个事件，因此载体可以把状态与对应的历史切面配对。投影状态可以通过检查点加快冷读，而仅供 host 使用的投影不会暴露给客户端。

目录

• 使用本包
• 理解实现
• 进一步探索
• 模型体验
• 已知限制与延期工作
• 开发备注

---

使用本包

在客户端载体需要日志派生会话状态的当前值处挂载 dsh-session-projection。领域插件注册单元；载体读取快照并订阅变更流；两侧互不相识。

何时选择

当领域保存客户端应看到、但不应自行重新派生的状态——todo 清单、goal 快照、对话统计——时选择本包。注册表在已提交事件上主动驱动单元，因此任何已注册单元的值按构造即为当前值。当维护的是无客户端读取的 host-only 记账时跳过：不带 wire 块的单元保持 host-only。host 读取方要么在插件 inject 中声明 sessionProjections，要么在注册表或必需 key 缺席时明确失败。贡献方可以继续通过 ctx.inject(['sessionProjections'], ...) 保持可选注册。

定义投影单元

领域为每个状态键贡献一个 ProjectionDefinition：一个 key、状态 schema、初始状态、同步折叠 apply(state, event)、可选的 wire 块（把状态投影为客户端视图），以及状态字段或折叠语义变化时递增的 stateVersion：

const definition = {
  key: 'todo',
  stateSchema: todoStateSchema,
  stateVersion: 1,
  init: (_header, _inheritedEventCount) => ({ items: [] }),
  apply: (state, event) => event.type === 'todo/upsert'
    ? { items: event.data.items }
    : state,
  wire: {
    viewSchema: todoViewSchema,
    view: state => ({ items: state.items }),
  },
}

init(header, inheritedEventCount) 同时接收轻量元数据与精确的 fork 继承切点；它不得从 firstLiveSeq 或 session/end-seed 推断该切点。apply 必须同步，且对与单元无关的事件必须返回同一个状态引用——引用不变意味着零下游工作。注册表用 Object.is 比较相邻的 wire.view 原始结果；对象或数组 view 若要在仅内部 state 变化时抑制发布，就必须复用引用，结构相同的新对象仍算变化。携带状态的日志事件必须携带变更后的完整状态，绝不携带裸增量。

注册与读取

register(definition) 安装单元；具有相同 key 和 stateVersion 的注册方共享其 cell，版本不兼容或 stateVersion 非法时会 throw。注册是挂在调用方 fiber 上的 effect，因此最后一个注册方卸载后会移除 key 及其缓存 cell。返回的 disposer 可以 yield 到同一 fiber 上的复合 ctx.effect() 中，使单元在依赖它的清理完成前保持可用。载体用 snapshot(session) 对每个客户端可见单元读取一致的同步切面——{ asOfSeq, values }，其中 asOfSeq 是所有值共同反映到的最后一个事件的 seq——并用 onChanged(listener) 订阅逐变更通知。stateOf(session, key) 读取一个单元的实时只读 host 状态，不计算无关视图。

const dispose = ctx.sessionProjections.register(definition)
const { asOfSeq, values } = ctx.sessionProjections.snapshot(session)

必须使用投影状态的领域把 sessionProjections 声明为 Cordis 服务依赖；可选贡献方可以在 ctx.inject(['sessionProjections'], …) 下注册。载体使用 ctx.get('sessionProjections')，注册表缺席时省略自己的块或帧。

持久检查点

系统通过 checkpoint(session) 为每个单元的状态创建检查点，client-visible 与 host-only 一视同仁；同级包 session-projection-cache 持久化这些检查点，使冷读跳过全量日志加载。检查点水位使用 SessionSeqCursor（空日志为 -1），回放起点使用 SessionLogOffset；restoreFloor 与 restore 实现读取流程，且不会混淆已有事件与日志间隙。

Session 摘要

Session 摘要包含每个已注册客户端视图，但排除 SessionProjectionMap 条目（非空值）带 SessionProjectionSummaryExcluded<T> 标记的 key。summaryKeys() 返回该集合，从实时注册派生；在注册或注销改变 key 表之前，它保持同一实例。摘要消费方把它传给既有的带 key 读取面 —— 实时 cell 用 cachedSnapshot(session, keys)，checkpoint 行用 viewCheckpoint(rows, keys)，持久化缓存用 cachedSnapshot(header, keys) —— 这些读取面把 Set 视为已选好的集合，因此不存在摘要专用读取面、每次读取无需复制，集合也只有一处定义。由于集合由注册表派生，摘要消费方无法通过该集合请求被排除的 key；完整读取面仍会按显式命名的 key 提供值，打开的 Session 因此保留全部取值。列表行携带的是摘要投影，绝不是全量投影。

标记决定客户端视图类型，wire.summary 决定运行时键集合，省略即 true。map 条目带标记的 key 应声明 wire.summary: false 以保持一致；该字段就是普通布尔值，而不是类型层的互锁。可空条目把 null 放在包装之外（SessionProjectionSummaryExcluded<TodoItem[]> | null），以便首次写入前的值仍可表达。当前被标记的 key 是 turnOutline、sessionStats、todos 和 imageLimits：outline 随整份日志增长，列表行不渲染统计或 todo 清单，而图片上限是每个 Session 共享的同一个宿主级启动常量。

摘要服务于 Session 列表行，列表无需打开 Session。@ 引用同样以列表方式枚举 Session，但只通过带 key 的 snapshot(session, keys) 与 cachedSnapshot(header, keys) 读取其 title 和 subagent 标签 key。snapshot、cachedSnapshot 和 viewCheckpoint 在不传 key 子集时仍返回每个 wire key，因此打开的 Session 仍会收到全部投影值。

---

理解实现

实现细节——点击展开

本节说明驱动机制与单元约定；可观察约定已在使用本包中说明。

设计理念

本包是能力 seam 的 Service Definition 与驱动角色：框架负责驱动，领域负责计算。注册表只订阅一次 session/event；每个已提交事件都会主动经过每个已注册单元的 apply（cell 在首次触达时惰性构建）。第一层 Object.is 闸门在 state 引用不变时跳过 view 工作；live drive 的双槽缓存复用前一个原始 view，第二层 Object.is 闸门在原始 view 引用不变时抑制发布。载体在切出页面切片的同一 tick 内读取 snapshot()，asOfSeq 之所以是一个一致切面正系于此；误写成异步的 view 会返回 Promise，并被 wire.viewSchema.parse 拒绝。

源码地图

文件	职责
src/index.ts	插件入口：SessionProjectionRegistry 服务、ProjectionDefinition、快照与检查点机制
src/types.ts	可合并扩展的 SessionProjectionMap 与 SessionProjectionStateMap 类型表，以及摘要排除标记及其派生的视图与摘要类型

驱动与检查点流程

一个已提交事件按注册顺序驱动每个已注册单元；原始 view 通过 Object.is 判定为变化的客户端可见单元会以经 schema 校验的视图与致因 seq 通知变更流。live drive 保留前后两个原始 view；snapshot 与冷读仍是彼此独立的完整读取。checkpoint(session) 为持久缓存返回每个单元一份独立的 (key → {ver, seq, val}) 行；restoreFloor 把尾部读取锚定在最低可用水位之前一个事件处，使缩短的日志可被检出；restore 把持久行在存储后缀上重新折叠，丢弃任何 ver 不匹配或声称越过存储末尾的行。

---

进一步探索

当包级约定不够用时阅读以下页面。它们从单元约定逐步进入读模型子系统与持久缓存。

• 会话投影子系统——投影单元约定、驱动语义与生成的服务 API。
• 会话持久化子系统——投影折叠其上的事件日志。
• 会话投影缓存——让冷读跳过全量日志加载的持久检查点。
• 会话包映射——相邻的持久化、标题与遥测包。
• 会话投影 RFC——投影与命令日志的设计理由。

---

模型体验

无——注册表只为已入日志的会话状态提供面向客户端的读模型，不注册任何模型可见内容。

KV Cache 影响

无；投影从不组装或发送提供方请求。

已知限制与延期工作

这些限制说明投影注册表在大规模下何时需要特别处理。它们是当前包约束，不是任务积压。

• 只有带 key 子集的读取才省略 key；尾页仍携带每个客户端可见 key，也不存在惰性逐值请求——摘要只省略那些 SessionProjectionMap 条目带有 SessionProjectionSummaryExcluded<T> 且注册声明了 wire.summary: false 的 key。该 opt-out 按 key 生效，不按值生效：没有任何读取会延后加载单个大值。
• 单元表是进程级的，因此 key 是否存在不能当作逐会话的能力信号——任何 agent preset 注册的 key 都会出现在每个会话的快照里；客户端必须读值，不能把 key 缺席当作功能缺席。
• 主动驱动逐事件触达每个单元——按构造开销很低（全量值规则与 state/view 引用闸门），但若出现热点路径，可加按单元的事件类型预过滤。
• 注册表 cell 只活在内存里——重启后首次触达时靠折叠日志重建；挂载了 dsh-session-projection-cache 的组合改由持久行播种该折叠。
• 单元同步纪律只有部分可机械把关——wire.viewSchema.parse 能拒绝返回 Promise 的 view，但阻塞的 apply、或读取撕裂的非会话状态的 apply，只能靠评审把关。

开发备注

维护者的工作上下文——点击展开

无。