遗留编排迁移¶

编排 v2 在首次启动开启可写持久化之前，将 state.sqlite 快照为 statev2.sqlite。只有副本会接收 v2 迁移；原文件仍保留给 v1 使用。后续启动会复用该副本，而不会从 v1 刷新它。编排 v2 首先创建 v2 线程外壳事件，并在客户端读取或继续线程时懒加载导入完整的用户和助手转录。v1 投影表仍然是导入来源，并在需要调查导入问题时提供只读恢复来源。

导入的数据¶

外壳导入会保留项目和线程标识符、标题、提供商和模型选择、运行时和交互模式、分支、工作树路径、创建和更新时间、归档和删除时间、结算覆盖及时间戳、延后时间戳、置顶时间戳和顺序，以及关联的拉取请求。元数据修复路径会为在这些字段被覆盖之前导入的线程填充延后、置顶顺序、unsettledAt 和关联的拉取请求字段。

转录导入从 projection_thread_messages 读取用户和助手行。它会保留消息标识符、文本、受支持的附件、时间戳、角色和顺序。仍在流式传输中的消息将变为中断的回合项。

导入器不会转换提供商会话标识、原生提供商运行、检查点和差异、活动和工具调用、审批或提议的计划。因此，V2 不得将这些记录呈现为已迁移的历史记录。

首次继续¶

已迁移的线程没有活动的提供商线程。其首次继续会创建新的提供商会话，并发送仅由用户和助手消息构建的旧版交接。交接会在 32,000 字符的预算内选择最新的转录后缀，包括章节标签和导入说明。该预算独立于可移植的提供商交接。

客户端与服务器切换¶

客户端和服务器必须就 ORCHESTRATION_PROTOCOL_VERSION（当前为 2）达成一致。客户端运行时会在 socket URL 上追加 orchestrationProtocol=2，而 /ws 路由会在任何 RPC 或认证工作开始之前，以 HTTP 426（orchestration_protocol_incompatible）拒绝缺失或不匹配的版本。客户端以相同方式检查环境描述符：缺失版本表示主机早于协议 2，而不同版本表示双方都需要更新。任一方向的失败都会将连接阻止为 unsupported，并附带一条指明需要更新哪台机器的消息，而不是在升级一半的状态下运行。参见 packages/client-runtime/src/connection/compatibility.ts 和 apps/server/src/ws.ts。

分歧的迁移 ID¶

effect_sql_migrations 记录 migration_id 和 name，但迁移器只比较 ID：不检查名称，直接跳过等于或低于已记录最大值的行。因此，如果某个数据库曾在一个 ID 下运行本地或分叉迁移，而本构建后来又把这个 ID 分配给另一个迁移，那么该数据库永远不会收到本构建在这个 ID 处的迁移。在修复受支持的 V2 预览账本后，runMigrations 会拒绝那些会在 ID 55 或更高 ID 处跳过所请求迁移且没有预期名称的历史记录。更早的名称冲突仍作为警告保留，以便与站点本地迁移兼容。此账本内不存在任何对分叉安全的 ID 范围：任何等于或低于未来上游 ID 的 ID 都会永远掩盖该 ID，因此分叉的 schema 变更应放在单独的迁移表中，或完全放在迁移器之外。

恢复¶

没有受支持的完整线程导出 API。恢复使用环境的 userdata 目录的未改动副本，并以 SQLite 的只读模式打开该副本。用户指南记录了针对 projection_threads 和 projection_thread_messages 的查询。切勿针对恢复副本启动服务器，因为启动过程可能会运行迁移并写入新状态。