DSH Session 使用与恢复指南：事件日志、Fork 与 Compaction

升级后已有会话打不开时，按会话迁移失败与未知事件排查先保留副本并分流错误；列表可见不代表正文恢复成功。

0.1.7-rc.1：归档、置顶与停止有什么区别

2026-09-24 固定源码复核：本节仅适用于 0.1.7-rc.1（46a7f68b0922371ce7144b668b90e377d8e799f4），主要依据上游实现记录；本站没有运行 DSH，也没有实际操作侧栏。2026-09-26 按 0.1.7-rc.2（477b4f420553e8a52c2fbccc464d7561b239c443）复核，rc.2 的差异已并入本节：归档筛选的界面文案，以及归档时对定时任务的处理。

删除会话的行为本站尚未核验，本节不写。

需要注意的几点：

• "停止并归档"和停止按钮不完全一样。 两者都按用户停止处理回合，但"停止并归档"会丢弃排队中的输入，停止按钮会保留。撤销"停止并归档"只恢复会话，不会让被停止的工作继续。
• 归档后不再执行任何模型步。 包括它的子代理：迟到的唤醒、排队的后续任务都会被拦下。要继续使用这个会话，先取消归档，子代理链会一起解除限制。
• 置顶和归档互斥。 归档会清除置顶标记，取消归档也不会恢复置顶。
• 归档筛选移到了侧栏。 界面文案随版本不同：rc.1 是"显示已归档""仅显示已归档"，默认隐藏已归档会话；rc.2 改为"隐藏已归档""全部对话（显示已归档）""仅显示已归档"，只看归档时还会隐藏没有归档对话的工作区。筛选同时作用于列表和搜索；原来设置页里的归档列表已经移除。已归档的行显示为灰色，不能直接打开。
• "停止并归档"会删除该会话的提醒和定时任务。 rc.1 删除的是会话的活动提醒；rc.2 起删除该会话已存储的全部定时任务，而且即使会话当前没有在运行，只要存有定时任务，归档时也会先弹出确认。这是删除而不是暂停，撤销只恢复会话本身。
• 多个实例同时运行时，同一个会话同一时间只能由一个进程写入。遇到"当前会话已被占用"的提示，见会话排障的 0.1.7-rc.1 小节。

依据：置顶与侧栏归档 ↗（外部链接，在新标签页打开）、归档运行中的会话 ↗（外部链接，在新标签页打开）、Session Controller 说明 ↗（外部链接，在新标签页打开）、0.1.7-rc.1 发行说明 ↗（外部链接，在新标签页打开）；rc.2 依据：界面文案 ↗（外部链接，在新标签页打开）、归档运行中的会话（rc.2 版） ↗（外部链接，在新标签页打开）、0.1.7-rc.2 发行说明 ↗（外部链接，在新标签页打开）。

0.1.5-rc.1：生命周期、锁与子代理操作

本节汇总当前候选版行为，原有历史版本说明保留。Session 持久化采用生命周期持有的 SessionHandle，agentLoop.create() 为异步，同一 Session 至多由一个进程持有。不能把关闭浏览器当作 Host 已释放 Session，也不要在另一进程里绕过锁同时恢复同一数据。

只读准备和写入迁移仍要区分：应用层“打开”可能包含写入；V3 不能交给旧程序降级读取。遇到占用先核对持有进程并正常停止，不把删除锁文件当作默认解决方法。

可续聊子代理在发行说明中支持排队、编辑、删除、单条或全部 Steer 与停止；消息发送中不可编辑、删除或 Steer。排队用于等待投递，Steer 用于插话控制，不应重复点击造成重复任务。该说明针对宿主可续聊子代理，不是本站社区 Agent Teams 插件的兼容证明。具体界面随配置而异，本站未执行消息投递验收。

来源：固定持久化文档 ↗（外部链接，在新标签页打开）、候选版说明 ↗（外部链接，在新标签页打开）。升级背景见新版专题。

2026-09-09：Session V3 与旧版示例的边界

0.1.5-alpha.1 的固定 catalog 已到 V3；本站默认安装仍为 rc.1，下方基础事件示例继续适用于原标注的 0.1.1-rc.2，不能直接当作 V3 磁盘结构。新版系统提示词进入消息历史，迁移会插入事件并重映射受支持引用；自定义读取器需按格式版本处理。

新版 JSONL 的只读 open 准备和校验历史逻辑结果，不发布后继文件；写 open 才发布新 generation，保留原始文件。stat/list 只看头部。下文 9 月 5 日关于 read 也可能发布文件的说明属于 0.1.3-alpha.1，不能套用到本版；界面“查看”也不能一概等同底层 read。

受支持的 V0/V1 需通过相邻迁移到 V2 再到 V3，未知扩展事件或不符合规范的内容可能被拒绝，并非任意日志或旧 SQLite 都支持。失败时保留源文件与脱敏诊断，不删除事件强行迁移。

旧程序不支持降级读取 V3。 迁移后新增的对话不因保留旧文件而自动拥有旧版副本；回退应恢复旧程序对应的数据和配置，不改 generation 文件名。完整选择见0.1.5-alpha.1 专题，操作见升级与回退。本节仅固定来源复核，未运行迁移。

2026-09-05：Session v2 与历史版本怎样分开阅读

npm 默认版已切换为 0.1.2-rc.1，GitHub 最新预发布为 0.1.3-alpha.1。下文事件示例与基础解释保留 0.1.1-rc.2 的历史适用范围；本节基于 alpha.1 固定提交补充新版持久化变化，未执行运行或迁移实测。

• SessionHandle：持久化的 create／open 返回句柄，日志读取、追加、flush 和 close 经句柄执行；不能把旧的按 ID 读写接口原样搬到新版。
• 异步创建与写所有权：agentLoop.create() 变成异步。JSONL 后端通过进程内所有权及平台锁防止多个写入者同时持有同一 Session；读取句柄和写句柄的权限不同，不应以删除锁文件解决占用错误。
• Session format v2：固定 catalog 包含 v0 → v1 → v2 的相邻转换链。JSONL 后端选择最高规范 generation，在打开受支持旧日志时发布并列的新格式，源文件保持不变。read 模式打开旧日志也可能创建迁移产物；stat／list 仅处理 header，不发布迁移输出。因此“只打开看一眼”也应使用数据副本。
• 回退不等于降版本号：旧程序可能拒绝较新 generation；保留旧日志不意味着旧程序会自动选择它。回退必须恢复与旧程序对应的完整数据和配置副本，不能自行删除或改名 generation。

官方同时提示部分历史 Session 加载存在性能回退。加载变慢与日志损坏不是同一个结论；保留版本、日志路径、症状与脱敏错误，按更新回退指南和alpha.1 专题判断，不清空 DSH Home。

固定证据：JSONL 读取与迁移 ↗（外部链接，在新标签页打开）、当前格式 catalog ↗（外部链接，在新标签页打开）、句柄约定 ↗（外部链接，在新标签页打开）。

先看结论

DSH Session 不是一份简单聊天记录，而是一条由类型化事件组成的仅追加日志。用户消息、模型输出、工具调用、工具结果、轮次边界和运行时请求状态都从这条日志形成可回放历史；LLM 消息不是另外保存的一份副本。

恢复、Fork 和 Compaction 解决三个不同问题：恢复让持久化会话重新变成可运行 Agent；Fork 从已完成轮次的稳定前缀创建子会话；Compaction 用摘要替换模型当前可见的旧上下文，但不删除底层事件，也不会撤销外部副作用。本文依据官方 dsh-v0.1.1-rc.2 源码复核。

一次任务怎样写进 Session

DSH 把一次用户任务称为一个 turn，一个 turn 可以包含多个 step。每个 step 包含一次模型请求，以及该请求触发的工具执行。常见事件顺序可简化为：

turn/start
→ user/message
→ step/start
→ request/header
→ assistant/message 或 tool/call
→ tool/result
→ step/end
→ 需要时进入下一 step
→ turn/end

事件带有连续的 seq 和时间戳。tool/call 与 tool/result 通过 callId 配对；模型流式分片也会保留，以支持逐步回放。插件可以增加自己的事件类型，因此 Session 同时也是审批、压缩、Hook 等子系统的审计载体。

“唯一真源”对用户意味着什么

模型下一次请求看到的历史是由 Session 的可见 surface 派生出来的。请求配置、模型、系统提示和工具 schema 则以完整的 request/header 快照记录。这样恢复或回放时不需要猜测当时模型看到了什么。

但“日志完整”不等于“世界状态可逆”。命令已经改过的文件、发出的网络请求、数据库更新和外部消息不会因为回放旧事件而自动回滚。对这些副作用仍应使用 Git、备份、事务、测试环境和审批策略。

持久化和恢复如何工作

内存 Session 与持久化是两个子系统。持久化后端订阅事件并批量写入；显式 flush 会取消等待并排空待写数据，dispose 时也会执行最终排空。

如果进程在一个 turn 中途崩溃，冷加载不会截断已经落盘的事件。后端会追加一个合成的 turn/end，原因标记为 interrupted，把遗留轮次配平后再供恢复使用。活跃会话不会被另一个加载流程擅自修复；若当前 turn 仍开放，加载会拒绝操作。

恢复持久化会话与简单读取日志不同。官方接口通过 ctx.agents.resume({ resumeSessionId }) 恢复可运行 Agent；恢复时还要使用 Session header 中的工作目录、血统、Agent preset 和格式版本等元数据。

Resume、Replay 和 Fork 的区别

普通 Fork 默认复制到源 Session 当前最后一条事件，也可以显式指定包含边界。被选择的前缀必须结束在没有开放 turn 的位置；如果边界落在进行中的轮次里，API 会拒绝，而不是悄悄截断。子会话会继承 cwd，并记录 parentSession 与 seedLength。

因此，想比较两个实现方案时，先让当前 turn 完整结束，再从对应 turn/end 位置 Fork。不要把复制工作目录、复制 Session 历史和回滚文件状态混为一谈：Fork 继承事件上下文，不会替你创建独立 Git 分支或文件快照。

alpha.3 为什么要单独核对 SQLite Session

0.1.2-alpha.3 删除了可选的 SQLite 权威 Session 持久化后端，JSONL 成为唯一第一方 Session 持久化实现。这个变化不表示 Session 功能被删除，也不表示项目中所有 SQLite 用途都消失；可重建查询索引和通用存储与权威 Session 日志不是同一数据角色。

风险在于旧数据：alpha.3 当前构建不会打开或自动迁移由已移除后端创建的数据库。曾启用 SQLite Session 持久化的维护者应暂停直接升级，保留旧程序、原数据库、配置和依赖环境，在仍包含旧提供者的版本中确认重要 Session 能被读取并按可靠流程处置，然后才在副本上评估新版。alpha.3 版本变化与升级判断

不要把 Web Session Header 的下载按钮或 /export 想当然地当作旧 SQLite 迁移工具。alpha.3 的固定导出文档依赖 JSONL 后端的每 Session 原始产物，没有提供从旧 SQLite 数据库直接导出的通用步骤。官方证据不足时，应保留数据并暂停操作，而不是编造转换命令。

Compaction 是否会删除历史

不会。Compaction 的目标是缩小模型可见上下文：它选出一段平衡的 surface，把摘要作为新的可见节点替换那段内容，同时在仅追加日志中记录开始、摘要和结束事件。原始事件仍保留在底层日志里。

选择范围时必须保持工具调用与结果成对，避免摘要后只剩一半工具语义。自动压缩可由上下文压力或模型确认的上下文溢出触发；手动压缩也可能因为 Session 忙碌、范围变化、摘要失败、持久化失败或取消而停止。

压缩有三个重要限制：

1. 摘要是有损表示，后续模型看到的是摘要而非全部旧 surface；
2. 压缩不会删除审计日志，也不是隐私擦除功能；
3. 压缩不会撤销工具已经产生的文件或外部系统副作用。

升级时为什么要关注 Session 格式

Session header 包含磁盘格式版本。0.1.1-rc.2 的持久化实现会拒绝无法可靠理解的更旧或更新格式，而不是猜测迁移。该历史版本中的 SQLite 后端也有独立 schema 版本，并明确拒绝旧 schema，而非自动迁移；到 alpha.3，这个可选权威持久化后端已被移除。

升级 DSH 前应：

1. 停止新任务并等待当前 turn 结束；
2. 正常关闭进程，让持久化队列完成 flush；
3. 备份 $DSH_HOME、项目工作区和重要 Session 数据；
4. 阅读目标 Release Notes 中的 Session、persistence、SQLite 与 compaction 变化，SQLite 用户先确认旧环境仍可用；
5. 先用副本验证能否列出、读取和恢复旧会话；
6. 保留原版本和回滚路径，不直接覆盖唯一数据副本。

alpha.4 的开发 API 不再把事件身份和日志偏移混成一个数字

对直接集成 Session API 的插件开发者，0.1.2-alpha.4 是另一项独立兼容变化：直接读取 Session.events 的模式改为使用 seq、eventAt()、snapshotEvents() 等按需接口。SessionSeq 表示一条已经存在的事件，SessionLogOffset 表示事件间隙、前缀长度或读取切点，后者可以等于事件总数。

最小迁移原则不是把新类型强制断言回 number，而是先确认变量究竟表示“某条事件”还是“读取到哪里”：需要单条事件时使用 eventAt(seq)；需要稳定数组快照时使用 snapshotEvents()；计数、前缀和读取起点保持 offset 语义。算术结果会回到普通数字，进入领域 API 前仍要通过对应验证构造。

这项 TypeScript 类型与读取 API 变化不改写普通用户对 Resume、Replay、Fork 或 Compaction 的概念，也不覆盖 alpha.3 删除 SQLite 权威 Session 后端的历史风险。磁盘 v0 JSONL 与公共 wire 仍使用普通数值，由边界适配器验证。本站未编译第三方 Session 插件，具体适配必须针对插件使用的固定 DSH 版本完成。alpha.5 页面汇总了本轮完整兼容范围。

alpha.5 另外修复了 rc.2／alpha.3 投影缓存升级兼容。Session 列表标题消失指向可重建投影，不等于权威 Session 正文删除；遇到异常仍应先备份，不能用清空整个数据目录代替诊断。

如何验证一次 Session 是否可复核

完成一个最小任务后，检查以下证据：

• 用户输入、模型结果和工具调用是否按顺序显示；
• 每个工具调用是否有对应结果或明确中断；
• turn 是否正常结束，崩溃恢复时是否标记 interrupted；
• 恢复后使用的工作目录和 Agent preset 是否仍正确；
• Fork 的子会话是否记录父会话血统，并从预期边界开始；
• Compaction 前后的当前上下文是否保持工具调用/结果配对；
• Session 日志中是否含有不应长期保留的敏感内容。

Session 可能保存用户输入、工具参数、输出片段和工作目录等信息。不要把含凭据或客户数据的原始 transcript 直接公开；用于排障时应先脱敏，并说明 DSH 版本、持久化后端和验证日期。

想理解 Session 在整体插件树中的位置，阅读DeepSeek Harness 架构解析；想控制工具执行范围，阅读DSH 权限与沙箱指南；第一次运行则从DeepSeek Harness 中文入门开始。

如果你关心一次性命令为什么仍会创建并 flush 持久化 Session，可继续阅读DSH Headless 一次性 Agent 教程。

常见问题

恢复 Session 会重新执行以前的工具吗

事件回放本身用于重建历史，不应被理解为重放外部副作用。后续 Agent 是否再次调用工具，取决于新的请求与执行流程。

Fork 会复制工作目录里的文件吗

不会。Fork 继承 Session 的 cwd 元数据和事件前缀，不等于复制目录或创建 Git 分支。

Compaction 能否用来删除敏感信息

不能。它替换模型可见 surface，但底层事件日志仍是仅追加记录。敏感信息处理需要凭据轮换、数据清理和存储层处置流程。