| 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 | 新旧入口，回收站保留一条记录；恢复只返回新版入口。 |
| 34 | - 彻底删除保留迁移和主题移除记录，在删除正文之前持久化旧来源清理意图。 |
| 35 | 只有内容未变化、且没有活跃或已归档会话、待提交导入及未解决恢复记录引用的 |
| 36 | canonical 旧目录才会一起清理。共享来源、已变化内容、旧版多文件 DAG 原件和 |
| 37 | 共享内容池继续保留。旧历史目录缺失时，不阻止删除新版会话。 |
| 38 | - 标题和置顶覆盖项在搜索、排序前生效，迁移提交时转移到目标。 |
| 39 | - 侧栏和历史共用准备入口；取消响应必须匹配导航意图、操作 ID 和修订号。 |
| 40 | 新分支准备期间切换页面，其完成结果不能抢回焦点。 |
| 41 | - 来源更新以真实内容版本为准；用户明确导入后创建独立分支，保留原映射。 |
| 42 | |
| 43 | 批量 worker 使用独占的跨进程租约；sidecar 的每次修改在写锁内读取最新值， |
| 44 | 只更新所属字段并原子替换。队列写入检查修订号，不允许旧快照覆盖其他实例 |
| 45 | 的更新。展示属性写入不覆盖队列，也不覆盖其他来源的标题和置顶。 |
| 46 | |
| 47 | ## 兼容性 |
| 48 | |
| 49 | 发现、导入、归档和恢复不修改源文件；明确执行彻底删除时遵循上述清理条件。 |
| 50 | source mapping、恢复记录和未知字段继续保留；移除展示信息和成员关系前，会 |
| 51 | 保存阻止会话复活的最小迁移证据。路径规范化产生的旧、新来源键通过别名关联， |
| 52 | 不改写已有记录或待完成操作身份；独立 head 和明确导入的内容版本仍保持独立， |
| 53 | 存在歧义的来源归属会被拒绝。旧版按路径打开的入口仍是当前 DAG head 的别名；有效的 head |
| 54 | 索引会把其他 head 暴露为独立的按需源，但列目录时不会重放事件日志。 |
| 55 | |
| 56 | | 数据 | 兼容行为 | |
| 57 | | --- | --- | |
| 58 | | 生命周期账本 | 不新增操作类型和阶段；目标 ID 与提交映射仍由原账本决定。清理意图作为带版本的可选 purge request 保存。旧版本可能保留原件，但不能恢复已删除的新版会话；不含清理意图的旧删除记录也不会在升级后扩大删除范围。 | |
| 59 | | v1 调度 sidecar | 可选 `queueRevision` 缺失时按零处理；已有队列以暂停状态载入；保留根对象和展示项的未知字段。 | |
| 60 | | 回退至尚无 sidecar 的版本 | 调度暂不可用；保留下来的来源和未彻底删除的会话仍可读取。已彻底删除的内容不会因回退恢复。 | |
| 61 | | 与旧 sidecar 写入器同时运行 | 旧实现不遵守新 worker 租约和修订号；应先升级所有 Desktop 实例，避免混版本批量写入。 | |
| 62 | |
| 63 | 准备状态不进入模型提示或 transcript 消息。 |
| 64 | |
| 65 | ## 验证 |
| 66 | |
| 67 | 已加入启动不迁移、跨进程冷导出争用、重复请求与取消、prepared/content_ready |
| 68 | 恢复、归档/删除隔离，以及列表、重试、提交后打开和批量控制的真实浏览器交互测试。 |
| 69 | 新增回归覆盖全局/项目来源在占用时仍可发现、普通列表中的标题和置顶、迁移去重、 |
| 70 | 提交期间退出并重启、双实例 sidecar 写入、未知字段保留、来源无关恢复，以及 |
| 71 | 取消和分支完成的迟到导航响应。测试使用一次性夹具，不修改个人历史数据。 |
| 72 | 生命周期回归还覆盖旧来源键的重启兼容、回收站单条记录、独立分支、共享来源保护、 |
| 73 | 来源写入锁争用、历史目录缺失，以及清理旧来源前后进程退出的恢复。 |
| 74 |