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

description, kind

description	kind
持久会话数据平面的包映射：持久化 seam 及其后端、检查点策略、投影、基于日志的标题与外发会话遥测。	package-group

session/ — 持久会话数据平面

English | 中文

概述

session 组让 agent（智能体）的对话在实时 loop 之外持久可复用：持久化 seam 存储事件日志并在恢复时还原，检查点策略让请求、工具副作用与已完成步骤在下一步动作前持久化，投影向客户端载体提供日志派生的完整值，标题根据会话内容为其命名，遥测则向外上报会话活动。先选持久化后端——JSONL 是随产品交付的默认项，SQLite 是可选启用、单库的后端——再按部署需要挂载检查点策略以及投影、标题或遥测包。本页是组的映射；每个包 README 负责各自的约定，session-query/ 是同级独立组，其读取／工具接口独立消费持久化。

目录

• 包
• 相关文档
• 开发备注

---

包

本组分为四个家族：持久存储（持久化 seam、后端、检查点策略）、投影、标题与遥测。每个包 README 负责各自的约定与配置。

持久化

包	职责	ctx key
session-persistence/	定义持久会话存储服务，以及每个后端组合的共享写入协调机制	ctx.sessionPersistence
session-persistence-jsonl/	随产品交付的后端：每会话一份仅追加 JSONL 日志，可选 Zstandard 压缩	注册到 ctx.sessionPersistence
session-persistence-sqlite/	可选后端：所有会话日志存入一个带物理打包行的 SQLite 数据库	注册到 ctx.sessionPersistence
session-checkpoint-policy/	让模型请求、顶层工具副作用与已完成步骤在下一步动作前持久化	包装 ctx.llm 与 ctx.tools
session-log-deepseek/	把增量规范日志作为可选的官方 DeepSeek 请求元数据上传	贡献 dsh_session_log

投影

包	职责	ctx key
session-projection/	定义并驱动把已提交事件折叠为完整当前值的投影单元	ctx.sessionProjections
session-projection-cache/	持久化投影检查点，使冷读跳过全量日志加载	ctx.sessionProjectionCache
session-stats/	通过 sessionStats 单元提供全日志会话计数与墙钟时间	注册到 ctx.sessionProjections

标题

包	职责	ctx key
session-title/	基于日志的会话标题，带确定性回退与一个可选提供方	ctx.sessionTitle
session-title-llm/	供提供方包共享的模型标题生成策略	库，不使用 ctx key
session-title-first-prompt-llm/	根据第一条合格的人类消息为会话生成标题	注册到 ctx.sessionTitle
session-title-all-prompts-llm/	根据所有合格的人类消息为会话生成标题	注册到 ctx.sessionTitle

遥测

包	职责	ctx key
session-telemetry/	捕获会话活动并把记录交给配置的上报后端	ctx.sessionTelemetry
session-telemetry-otel/	通过 OpenTelemetry 日志以 FULL、FEEDBACK_ONLY 或 DISABLED 模式投递遥测	注册到 ctx.sessionTelemetry

同一时间只允许一个标题提供方注册；未注册时，标题服务保留其确定性回退。下面的子系统页面是各家族后端无关的参考资料。

---

相关文档

• 会话持久化子系统——后端无关的服务语义、flush 检查点与崩溃恢复。
• 会话投影子系统——投影单元约定与驱动语义。
• 会话标题子系统——标题资格、回退与提供方流程。
• 会话遥测子系统——捕获、脱敏与投递模式。
• 会话子系统——本组每个包持久化或派生的实时事件日志。

开发备注

无。