会话持久化
DotCraft 会把每段对话保存为可以跨客户端、跨进程重启继续使用的线程。本页面向集成方和贡献者，说明存储权威、恢复路径和生命周期边界。
存储模型
| 数据 | 位置 | 作用 |
|---|---|---|
| 线程记录 | .craft/threads/active/ 或 .craft/threads/archived/ | 对话时间线和模型可见历史的权威来源 |
| 工作区状态 | .craft/state.db | 业务状态、运行连续性、诊断数据和查询投影 |
| 线程配套文件 | .craft/tool-results/、.craft/attachments/ 和 .craft/terminals/ | 线程引用的大型工具结果、附件内容和终端记录 |
线程记录同时包含客户端可见的 Thread → Turn → Item 历史，以及继续对话所需的精确模型历史。大型结果可以独立保存，线程记录中只保留有界预览和引用。
state.db 不能替代线程记录。DotCraft 可以从线程记录重建部分线程元数据和附件引用，但目标、计划、关系图、邮箱状态等业务数据无法全部恢复。因此，丢失 state.db 仍然属于部分数据丢失。
写入与恢复
每轮对话期间，DotCraft 会向线程记录追加内容，并更新相关工作区状态。恢复线程时，它会：
- 校验线程身份和来源；
- 重放仍然有效的线程记录；
- 恢复最新可用的上下文压缩检查点；
- 接上检查点之后仍然有效的轮次；并
- 重建运行时会话。
可以恢复的异常记录会被跳过。如果被拒绝的精确历史记录能够关联到某个 Turn，DotCraft 会从该 Turn 仍然有效的 Session Items 重建它对模型可见历史的完整贡献，而不会把部分精确历史与回退结果混在一起。存在不安全或冲突的线程头、来源身份时，恢复会失败，避免在错误身份下继续执行。
如果线程记录存在，但查询投影缺失或过期，文件优先的读取流程可以修复 state.db 中可重建的投影。修复不会覆盖无关的业务或诊断状态。
线程生命周期
| 操作 | 持久化结果 |
|---|---|
| 活跃 | 线程记录保留在 threads/active/，可以继续接收新轮次。 |
| 归档 | 阻止新 Turn，停止或失效活跃后台终端，并把线程记录移到 threads/archived/；对话历史继续保留。 |
| 恢复 | 线程记录回到活跃集合。只有父子 edge 仍为 open 的 SubAgent 后代会随之恢复。 |
| 删除 | 从持久化线程状态中永久移除该线程及其 SubAgent 后代。线程专属文件采用 best effort 清理，失败后可以重试。 |
归档不会取消已经在执行的主 Turn。它会阻止新 Turn，并停止或失效活跃后台终端。归档不等于删除：它会保留对话历史，也不会删除仍被有效线程记录引用的独立工具结果。
已完成和丢失的终端元数据与日志会在归档时保留，但仍受 Tools.Shell.Background.OutputRetentionDays 约束，默认保留 7 天。正在运行的终端不会被该过期清理删除；正常关闭进程只会停止终端，不会把线程视为已删除。
备份与恢复工作区
Git 克隆只包含已经跟踪的文件。自动生成的 .craft/.gitignore 会排除本地数据库和多个配套文件目录，因此单独使用 Git 并不是完整的会话备份。
如需保留完整本地状态，请先停止该工作区的 AppServer，确保线程写入器和工作区状态已经落盘，再复制整个项目文件夹，包括 .craft/ 下隐藏的、被忽略的文件。线程记录会保留工作区的绝对路径，因此受支持的会话恢复要求使用相同绝对路径；当前不支持在不同路径打开副本来迁移会话。全局 Provider 凭据独立存储，可能需要重新配置。用户操作流程见项目工作区。
支持的集成边界
线程 JSONL 是内部持久化格式，不是公开交换协议。集成应使用：
- DotCraft 内部的
ISessionService； - AppServer 协议；
- 受支持的 SDK；或
- 用于只读交接的
dotcraft context search和dotcraft context export。
这样，集成不会依赖内部记录版本、上下文压缩细节和恢复行为。