Tianyi Cui
bf29247fad
V3 permits external event, source and content identities and additional request-tool fields. Copying those values into V4 can give an old plugin named tool a core source identity, turn old tool-addition content into a registry instruction, or activate formerly ignored deferLoading and delivery metadata. Rejecting such collisions would instead refuse valid source logs. Keep historical extensions in the existing extensible JSON representation. Prefix unknown content and ignorable event tags with plugin:, preserving all other content fields and opaque event payloads. Prefix external source identities with plugin:plugin: or plugin:source: so wrapper and direct kinds cannot collide even when original names already contain a category prefix. Known first-party mappings remain explicit and unchanged. Prefix extra request-tool field names and block-start field names with plugin:, retaining exact values and existing-prefix doubling. Core schema parameters, arguments, replay state and nested plugin data are not traversed. Keep future-generation delivery records inactive after header promotion. Pin the V3 event vocabulary independently of the current writer and provide an offline verifier against an explicitly selected historical source commit. Attachment authorization and export inspect declared event content only. Team checkpoints preserve all own keys of unknown JSON blocks while still rejecting malformed known content and retired core tool-result blocks. Exercise physical read/write/reopen, prefix injectivity, own __proto__ keys, provider opacity and retained source-identity snapshots. No generic extension block, metadata wrapper or new schema-tooling type is introduced. V4 type declarations, persistence schema, checkpoint and frozen V0-V3 codecs remain unchanged. Canonical tool-result lifting and incomplete child-catalog policy remain separate concerns. Adapted from the extension-preservation work in 7ba7e174dd1 by Tianyi Cui. Co-authored-by: Tianyi Cui <[email protected]>
5.8 KiB
description, kind
| description | kind |
|---|---|
| 供持久化读取方使用的构建期静态第一方 Session 格式编解码器与相邻迁移装配。 | package-library |
@deepseek-ai/dsh-session-format-catalog
English | 中文
概述
dsh-session-format-catalog 为持久化提供一个确定性的 Session 格式读取器，且无需查询已挂载插件。它装配从最早受支持格式到当前写入格式的编解码器与相邻迁移边，在模块初始化时校验完整且无缺口的迁移链，并通过 sessionFormatCatalog 暴露物理分派、仅 header 分类、单遍行还原和当前格式逐记录编码。
目录
使用本包
何时使用
当持久化与测试支持读取方需要在任何功能插件挂载前取得完整第一方已发布格式清单时，导入本库。功能组合不会注册或重排其条目。它不发布运行时不变式伴生入口，因为构造过程会拒绝无效静态清单，每次完成的还原也会校验结果；可变行 decoder 状态只属于一次由调用方持有的流式还原。
入口
const descriptor = sessionFormatCatalog.readHeader(physicalHeader)
const catalog = createSessionFormatCatalogWithChildren(childFacts)
const restore = catalog.createRestore(physicalHeader, { recovery: 'recoverable', validation: 'transformed' })
for (const row of physicalRows) restore.decodeRow(row)
const current = restore.finish()
const headerRecord = sessionFormatCatalog.encodeCurrentHeader(current.header, current.inheritedEventCount)
const eventRecords = current.events.map(sessionFormatCatalog.encodeCurrentEvent)
从包根导入 sessionFormatCatalog。JSONL 与 fixture（测试前置数据）读取方创建一次 restore，把每个已解析物理行传给 decodeRow()，再调用一次 finish()。Writer 通过 encodeCurrentHeader() 与 encodeCurrentEvent() 序列化返回的当前产物。列表读取调用 readHeader()，绝不打开事件正文。
Production 历史读取使用 { recovery: 'recoverable', validation: 'transformed' }。Worker 与 fixture 校验使用 { recovery: 'strict', validation: 'current' }。Transformed validation 会在迁移后执行已发布 current 规则，但对已经是 current 的输入有意跳过已安装语义校验。
该目录直接包含所有受支持的历史读取器。Profile 无法通过挂载功能插件来添加、移除或重新排列迁移边。它通过对 dsh-session 的对等依赖（peer dependency）获得已安装的当前事件词表与当前还原规则，而历史迁移边校验器保持冻结。浏览器安全的 ./message-projections 导出为独立构造函数和 surface 折叠装配当前插件拥有的处理器，不挂载恢复监听器。
createSessionFormatCatalogWithChildren(childFacts) 在组装时将显式的子 Session 证据绑定到 V3→V4，见目录补齐规范。historicalSessionFormatCatalog 使用固定的已发布 V3 事件词汇恢复 V0–V3，收集子日志前置事实而不递归补齐其目录。即使已安装写入方认识事件名，可忽略 V3 扩展仍保持不透明。独立转录回放显式提供空数组；持久化必须收集完整的可用直属子 Session 集合。在 catalog 的生命周期内保持传入证据不变。每次恢复各自拥有独立的 stage 状态。静态 sessionFormatCatalog 支持 header 和原生当前格式读取；历史正文读取必须使用已绑定子 Session 的 catalog。
理解实现
实现细节——点击展开
src/generated.ts 是编解码器与迁移边顺序的静态所有者。src/current.ts 把最终标头、事件信封、消息、表面、种子和当前请求标头校验委托给已安装的 Session 语义。底层构造函数会在开始读取任何 Session 之前拒绝重复编解码器、重复迁移边、缺口，以及超过当前版本的条目。
进一步探索
- 迁移机制——目录构造与分派行为。
- 已发布 v0 到 v1 迁移边——编解码器与校验器所有权。
- 已发布 v1 到 v2 迁移边——Assistant 流嵌入与基数变化引用重映射。
- 已发布 V2 到 V3 规范——转换、保留与拒绝。
- V3 到 V4 规范——恒等转换与 delivery generation 校验。
- JSONL 持久化——不可变 generation 命名与排他发布。
模型体验
目录分派
模型看到什么
没有直接内容。该目录只还原由请求重建逻辑消费的 SessionEvent 历史。
Token 影响
不直接产生 token。
KV Cache 影响
没有直接影响；还原后的历史在其消费方中决定缓存身份。
已知限制与延期工作
- 仅包含第一方构建清单——尚不支持外部迁移所有权与分发。
- 生成顺序封闭——运行时插件注册无法补充缺失的历史迁移边。
开发备注
维护者的工作上下文——点击展开
无。