| 1 | # 历史会话按需迁移 |
| 2 | |
| 3 | ## 范围 |
| 4 | |
| 5 | Desktop 启动不再转换所有旧版 transcript 或 canonical v4 目录。启动阶段 |
| 6 | 只恢复少量、非历史会话的生命周期保留记录。后台读取目录项、已发布的 head |
| 7 | 索引和持久化账本，发布元数据快照；普通列表只查询该快照，不重放历史正文。 |
| 8 | 旧版 transcript 和 canonical v4 来源同时出现在侧栏和历史搜索中，用户打开 |
| 9 | 某一行时才准备内容，提交成功后由原有导航流程激活准确的目标会话。 |
| 10 | |
| 11 | 重启恢复尚未准备的旧标签时，保留标题并显示“导入并打开”，不显示损坏提示， |
| 12 | 也不自动启动转换或控制器。明确点击后进入侧栏、历史搜索共用的导航流程。 |
| 13 | 空的 canonical 探测目录不作为历史会话展示；损坏但仍有会话产物的来源继续保留， |
| 14 | 供用户明确重试。 |
| 15 | |
| 16 | 批量准备入口位于“设置 → 存储 → 历史数据”；回收站只管理归档和删除。 |
| 17 | |
| 18 | ## 所有权与生命周期 |
| 19 | |
| 20 | - 导入获取按源隔离的跨进程锁；canonical 源在完整复制和提交期间持有共享目录 |
| 21 | 所有权锁。 |
| 22 | - 如果源正在被其他 CLI 或 runtime 使用，立即显示阻塞状态，不会排队等待 |
| 23 | Desktop runtime rebuild 锁。 |
| 24 | - 同一源的重复请求加入同一个带修订号的准备任务。交互请求和批量任务分别 |
| 25 | 持有需求；取消批次不会误伤仍被用户打开的会话。 |
| 26 | - 批量导入按顺序执行，支持取消和继续。关闭时先等待队列 worker 退出，保留 |
| 27 | 当前项和剩余选择；重启后暂停，等待手动继续。取消保留 `prepared`、 |
| 28 | `content_ready` 记录，下一次显式请求可以继续。 |
| 29 | - 已有 `content_ready` 的操作校验持久化目标和生命周期边界后直接提交，不要求 |
| 30 | 旧来源仍存在或能够获得其所有权锁，也不会再次转换成第二个会话。 |
| 31 | - 归档和删除状态具有最终权威性；目录重新扫描不会让会话复活。 |
| 32 | - 标题和置顶覆盖项在搜索、排序前生效，迁移提交时转移到目标。 |
| 33 | - 侧栏和历史共用准备入口；取消响应必须匹配导航意图、操作 ID 和修订号。 |
| 34 | 新分支准备期间切换页面，其完成结果不能抢回焦点。 |
| 35 | - 来源更新以真实内容版本为准；用户明确导入后创建独立分支，保留原映射。 |
| 36 | |
| 37 | 批量 worker 使用独占的跨进程租约；sidecar 的每次修改在写锁内读取最新值， |
| 38 | 只更新所属字段并原子替换。队列写入检查修订号，不允许旧快照覆盖其他实例 |
| 39 | 的更新。展示属性写入不覆盖队列，也不覆盖其他来源的标题和置顶。 |
| 40 | |
| 41 | ## 兼容性 |
| 42 | |
| 43 | 源文件保持不变。已有 source mapping、恢复记录、未知字段、展示信息和保留 |
| 44 | 产物都会保留。旧版按路径打开的入口仍是当前 DAG head 的别名；有效的 head |
| 45 | 索引会把其他 head 暴露为独立的按需源，但列目录时不会重放事件日志。 |
| 46 | |
| 47 | | 数据 | 兼容行为 | |
| 48 | | --- | --- | |
| 49 | | 生命周期账本 | 不新增操作类型和阶段；目标 ID 与提交映射仍由原账本决定。 | |
| 50 | | v1 调度 sidecar | 可选 `queueRevision` 缺失时按零处理；已有队列以暂停状态载入；保留根对象和展示项的未知字段。 | |
| 51 | | 回退至尚无 sidecar 的版本 | 调度暂不可用；原始来源和已提交会话仍可读取。 | |
| 52 | | 与旧 sidecar 写入器同时运行 | 旧实现不遵守新 worker 租约和修订号；应先升级所有 Desktop 实例，避免混版本批量写入。 | |
| 53 | |
| 54 | 准备状态不进入模型提示或 transcript 消息。 |
| 55 | |
| 56 | ## 验证 |
| 57 | |
| 58 | 已加入启动不迁移、跨进程冷导出争用、重复请求与取消、prepared/content_ready |
| 59 | 恢复、归档/删除隔离，以及列表、重试、提交后打开和批量控制的真实浏览器交互测试。 |
| 60 | 新增回归覆盖全局/项目来源在占用时仍可发现、普通列表中的标题和置顶、迁移去重、 |
| 61 | 提交期间退出并重启、双实例 sidecar 写入、未知字段保留、来源无关恢复，以及 |
| 62 | 取消和分支完成的迟到导航响应。测试使用一次性夹具，不修改个人历史数据。 |
| 63 |