Tianyi Cui
d58964a010
# Conflicts: # .agents/notes/implemented/architecture/2026-08-31-live-assistant-stream-frames.i18n.yaml # .agents/notes/implemented/architecture/2026-08-31-live-assistant-stream-frames.md # .agents/notes/implemented/architecture/2026-08-31-live-assistant-stream-frames.zh.md # docs/event-producer-consumer.i18n.yaml # docs/event-producer-consumer.md # docs/event-producer-consumer.zh.md # packages/api/session-controller/README.i18n.yaml # packages/api/session-controller/README.md # packages/api/session-controller/README.zh.md # packages/api/session-controller/src/assistant-stream.ts # packages/api/session-controller/src/client/sessions/assistant-stream.ts # packages/api/session-controller/src/types.ts # packages/api/session-controller/tests/assistant-stream.client.spec.ts # packages/api/session-controller/tests/session-history-journal.host.spec.ts # packages/api/session-controller/tests/sessions-service.client.spec.ts # packages/api/session-controller/tests/transport.client.spec.ts # packages/core/agent/README.i18n.yaml # packages/core/agent/README.md # packages/core/agent/README.zh.md # packages/extensions/tool-cordis/src/api-catalog.ts # scripts/package-dependency-policy.ts
4.5 KiB
description, kind
| description | kind |
|---|---|
| 纯函数式相邻 Session 格式规划、无损 JSON 快照、仅标头迁移与物理编解码分派。 | package-library |
@deepseek-ai/dsh-session-format
English | 中文
概述
dsh-session-format 让持久化代码可以直接还原当前 Session，或组合唯一的相邻全产物迁移序列。它会把每个持久化输入和输出快照为分离的无损 JSON，校验精确的版本推进，并把仅标头的列表读取与正文读取分开。物理分帧、压缩、不可变 generation 命名、排他发布和 Cordis 生命周期行为不属于这个纯函数库。
目录
使用本包
何时使用
当持久化或格式目录代码需要分类物理 Session header、还原当前逻辑值或组合已发布相邻迁移时，使用本库。它不是 Cordis 插件，也没有 profile 挂载行。它不发布运行时不变式伴生入口，因为每个操作都会在返回前校验借入的完整 artifact，且不保留跨调用的可变状态。
入口
const catalog = createSessionFormatCatalog({ currentVersion, codecs, encodeCurrentArtifact, migrations, restoreCurrent, restoreCurrentHeader })
const descriptor = catalog.readHeader(physicalHeader)
createSessionFormatCatalog() 接收每个受支持版本的一个冻结解码器、当前格式的编码器、每组相邻版本的一个迁移，以及当前产物与标头还原器。readHeader() 在不读取事件的情况下返回 current、migration-required、unsupported 或 malformed 描述符。每个迁移边会先校验自己的目标标头，然后再运行最终的当前标头还原器。正文读取方调用 decodeArtifact() 或 decodeRecoverableArtifact()，然后调用 migrate()；写入方只使用经过校验的当前产物调用 encodeCurrent()。冻结的 v0/v1 编解码器导出会保留其格式专用的 packChunks 选项，但不会把这项历史控制加入当前 writer 或通用解码器接口。
可恢复解码器返回已接受的逻辑前缀。编解码器可以丢弃一个格式错误或序号不连续的行及其未提交后缀，但后续成功解码的 turn/end 会使原始问题成为致命错误。
理解实现
实现细节——点击展开
迁移链在构造时校验唯一且无缺口的顺序。当前产物绕过所有迁移回调，只经过当前格式还原器。旧产物在内存中依次运行每个相邻的全产物函数；只有调用方决定是否发布最终结果以及如何发布。
| 文件 | 职责 |
|---|---|
src/chain.ts |
相邻计划构造与当前格式绕过 |
src/catalog.ts |
物理版本分派与标头分类 |
src/json.ts |
分离的无损 JSON 快照与通用坐标校验 |
src/filename.ts |
持久化、导出与 fixture 共用的规范 session[.vN].jsonl 文件名 |
进一步探索
- 已发布 v0 到 v1 迁移边——冻结的历史解码与恒等转换。
- 静态目录——第一方编解码器与迁移装配。
- JSONL 持久化——持久化分帧与代际发布。
模型体验
Session 还原
模型看到什么
没有直接内容。消费方通过 deriveMessages() 从经过校验的当前产物重建模型历史。
Token 影响
不直接产生 token。
KV Cache 影响
没有直接影响。迁移若改变当前历史，可能改变由请求重建逻辑拥有的缓存身份。
已知限制与延期工作
- 全产物内存占用——受支持的迁移会物化完整逻辑 Session；只有实测产物规模提出要求时，才会引入流式转换。
- 仅支持相邻整数版本——本库不暴露 span、稳定事件身份或通用引用重写代数。
开发备注
维护者的工作上下文——点击展开
无。