会话恢复、分叉与格式迁移
本页界定会话恢复、分叉与格式迁移的已核实入口和版本管理约束。当前可取得的源码证据主要是 CLI 帮助文本、构建脚本、工作区配置及仓库维护约定；恢复和分叉的实际执行实现尚未得到验证。
目的与范围
面向需要定位会话恢复入口或评估格式升级风险的开发者。本页只记录有来源支持的命令转发、格式包的工作区位置及迁移约束；不将启动器参数转发误写为恢复算法，也不把格式包的存在误写为已经验证的迁移调用链。有关持久化类型变更的评审，参见 reviewing-persistence-type-changes.md；格式版本状态参见 session-format-status.md。具体恢复、分叉行为和版本转换函数的实现细节未能从已读取源码确认，应由对应实现页面补充。
概述
CLI 启动器帮助文本说明：启动器不识别的 token 开始内部应用参数；示例将 --resume abc 传给 tui profile。这只能证明参数的转交边界，不能证明 tui 如何选择、加载或恢复会话。构建配置列出了 session-format、各相邻版本转换包与 session-format-catalog；仓库维护约定要求采用相邻迁移，且保留已提交的历史代际。现有证据中未找到分叉入口或实际数据复制策略。
架构
下面展示工作区层面已经验证的关系，不是运行时函数调用图：
Sources: args.ts, tsconfig.host.json
tsconfig.host.json 中的项目引用证明这些包被纳入构建；它们之间的运行时依赖和迁移顺序不能仅由项目引用推出。args.ts 不与格式包画连接，避免把未经验证的调用关系画进架构图。
已验证的入口与控制边界
启动器参数与恢复参数
启动器参数说明明确指出：解析器不认识的 token 开始内部应用参数；dsh --profile tui --resume abc 将 --resume abc 交给 tui profile。帮助示例另列 dsh tui --resume <session>。因此调试时先区分“启动器把参数交出去”和“下游应用已恢复持久化会话”两个事件。现有证据未验证会话标识的解析方式、路径选择、加载事务、权限校验或恢复后的 UI 状态。
Sources: args.ts, tsconfig.host.json, package.json
图中仅表达文档示例、项目引用和脚本定义；没有把它们串成一个未经证实的运行时恢复流程。
格式迁移的版本边界
仓库维护约定称公开 API 尚未稳定，修改时应更新所有使用方；相邻迁移可以添加带版本名的后继格式，但不能移动、覆盖或删除已经提交的代际；前代格式的存在既不意味着回退支持，也不意味着降级支持。该约定同时指出 SQLite 使用单调递增的 SCHEMA_VERSION。这是一组变更约束，并非某个迁移函数实现或数据安全的实测保证。构建配置中可见 v0→v1、v1→v2、v2→v3、v3→v4 包的项目引用；具体转换步骤、字段映射和执行时机尚未从实现确认。
生成与验证
根 package.json提供 verify-persistence-formats、gen-session-format-catalog 和 verify-session-format-catalog 脚本入口。其中后两者调用同一个目录生成脚本，检查模式额外传入 --check。脚本内部的检测逻辑未读取，不应声称它检查了某种特定文件内容或自动执行数据库升级。
用法示例（仓库原文）
以下是启动器帮助中的真实命令示例；它只说明参数如何抵达 profile，并不构成恢复成功的断言：
dsh tui --resume <session> arguments after the launcher flags reach the appSource: args.ts
以下是已有脚本的原始配置片段；检查脚本以 --check 调用目录生成器：
"gen-session-format-catalog": "tsx scripts/gen-session-format-catalog.ts",
"verify-session-format-catalog": "tsx scripts/gen-session-format-catalog.ts --check",Source: package.json
另一个版本边界的真实工作区配置片段：
1{ "path": "./packages/session/session-format" },
2{ "path": "./packages/session/session-format-v0-to-v1" },
3{ "path": "./packages/session/session-format-v1-to-v2" },
4{ "path": "./packages/session/session-format-v2-to-v3" },
5{ "path": "./packages/session/session-format-v3-to-v4" },
6{ "path": "./packages/session/session-format-catalog" },Source: tsconfig.host.json
配置与接口边界
| 可见入口 | 类型 | 已验证的行为或默认值 | 注意 |
|---|---|---|---|
--resume <session> | CLI profile 参数示例 | 帮助文本给出转交示例；默认值未确认 | 不能据此推断 session 的格式或解析规则。 |
--check | 目录生成脚本的参数 | 验证脚本显式传入；生成脚本调用不带该参数 | 参数内部语义与错误退出码未核实。 |
SCHEMA_VERSION | SQLite 版本约定 | AGENTS.md规定单调递增；具体数值未确认 | 不能从约定推断已安装数据库的版本。 |
API 参考的限制
已获得的证据不包含恢复、分叉或迁移函数的定义或调用实现，因此没有可核实的 API 签名、参数类型、返回值或异常清单。Implementation details not found in source：本次受限取证未读取对应实现文件，故不提供猜测的伪接口。需要扩展此页时，应先核对 session-format-catalog 与实际会话持久化实现，再补充签名与调用关系。
故障边界、并发与运维
- 版本兼容性： 维护约定明确：存在前代并不保证回退或降级。不要在升级操作手册中把“保留前代”解释为“可自动降级”。相邻版本后继不得改写已提交的代际。
- 恢复与分叉： 当前证据未显示无效 session ID、文件损坏、部分迁移失败、分叉冲突、并发读写如何处理；也未确认任何重试、锁或事务边界。实施变更前必须检查实际读写实现和测试，不能将未见到的保护机制当作保证。
- 验证入口： package.json列有持久化格式验证和目录检查脚本；是否在 CI 中运行、覆盖哪些错误仍需查验脚本及工作流。
- 扩展方向： 添加格式后继时遵循 AGENTS.md 的相邻迁移和保留历史代际约束，并同步更新受影响的使用方；具体扩展点与迁移注册机制尚未核实。
相关链接
- 会话格式状态：版本与状态的维护入口。
- 持久化类型变更评审：类型变更的关联指南。
- 已实现的格式迁移说明：由仓库维护约定指向的相邻迁移背景；其具体内容未在本次取证中核实。
- CLI 参数帮助和目录脚本入口：定位已验证的入口。