muse-agent-example/docs/系统架构/新版设计/迁移与验收.md

迁移与验收

本文保留数据迁移、唯一写入切换及备份恢复的长期安全合同，不是 R2 当前执行计划或验收回执。历史见R2 改造历史留痕。

数据转换遵守旧知识记录分流与原文证据生命周期，不能用路径映射或行数相等证明语义承接。正文、原文、历史候选、审查理由、事实、方法、声音、偏好和有效测试不得因换存储丢失；旧库与备份按保留和恢复要求处理。

功能承接

功能组	新增的业务语义	保留并完善的基础
创作管理	多作品入口、状态与计划、逐步探索页面、近期滚动规划	现有阶段 0 方法、规划结构与书/章责任区分
故事世界	图谱、时间线、人物成长、知情范围、设定使用与修改影响交互	现有实体、关系、事实、伏笔与抽取能力
扫榜与资料	真实榜单快照、选题依据、通用研究资料、私人素材与冲突来源	参考书导入、拆解、分窗、来源、范式抽取
正文共创	完整编辑器、手写保存、自动保存、候选比较、选段和部分采纳	两阶段写手、候选、质量检查与正式写入保护
上下文	混合检索、实际材料展示、统一范围校验、全部读取留档	已有冻结、active/绑定过滤及范式版本引用
审校去味	报告长期保留、版本陈旧、问题单、长文覆盖、有限返修与误杀反馈	声音、诊断、授权范围、patch、保真和原文胜出
作者经验	跨书偏好、冲突撤回、完整方法启用与效果追踪	lesson 观察、修改对、方法案例与已有评测合同
交付连载	全书定稿、四类文稿导出、存稿、发布版本及读者反馈	现有文本、备份、记录和作者决定基础
运行数据	任务恢复、断线重连、迁移恢复、查询导航和完整数据带走	现有事件、raw、回执、预算和角色策略

功能广度通过现有十个模块扩大。短篇缩短规划粒度与任务步骤；节点视图编辑同一套规划依赖；二者不新增第二个写作引擎、正文权威或候选状态机。

数据迁移及切换

1. 对旧 PG、SQLite、受控 raw/参考文件及私人草稿分别建清单，记录快照与内容校验和；不按表名相似就合并记录。
2. 在新 schema 或隔离库导入，保存旧系统、旧类型、旧 ID 到新 ID 的映射。PG 正式版本不被 SQLite review 覆盖；SQLite 独有的审查/反馈/经验必须迁入对应历史对象。
3. 逐类核对正文、原文、类型与字段、结构版本和投影策略、关系、候选、决策、raw、绑定、任务和实验；孤儿引用或无法解释的冲突进入差异报告，不能静默丢弃。
4. 初次批量导入后，在切换窗口停止旧写入口，迁入增量并核对；启用新版唯一写入，旧系统作为只读回查或保留快照。
5. 回退必须包含切换后产生的新数据。若未实现反向迁移，就明确只能在新版尚未接受新写入的窗口快速回退；不能承诺切回旧程序自然保住新增稿件。
6. 只有新旧数据对账、完整恢复和关键旅程通过后，才退出旧写代码；物理删除旧库另按保留与恢复要求处理。

验证合同

验证面	必须保护的行为
包与依赖	安装产物能在无 .git、任意 cwd 中启动；移动 Skill 不影响业务；导入不连接网络/数据库
模块职责	接入不直写正文；模块不导入他模块私有存储；模型工具不能调用正式提交；生产不读取评测配置
数据提交	过期 revision、源变化、改候选、同命令异参数拒绝；重复请求回同回执；批准增量失败整包回滚
分支与快照	分支不改主分支事实；合并重验当前版本；跨章快照固定清单，回滚后新增内容和历史证据仍可查
上下文	其他作品、目标答案、未来章、未确认内容、撤回来源在预组装/探索/回放均受约束
任务运行	断流无完成信号、结构错误、预算耗尽、取消、重启、租约过期、迟到结果与未知调用结果
章后处理	正文成功而抽取失败仍可见；重试不重复；旧 revision 不覆盖新投影；事实须另行确认
中文编辑	输入法组合、表情/组合字符、引号/空行、选段与往返；断网和快速切章不丢稿、不错章
拆书与方法	原文到结论有版本定位；分窗失败续跑；别名冲突不误合并；绑定改变使旧候选失效
审校与去味	报告来源漂移、长文覆盖、保护区、数字/引文、声音/视角、不应修改的反例和原文胜出
作者经验	推断偏好待确认、局部要求不全局化、撤回停止新消费、改进启用必须有目标与验证
元数据演进	新类型贯通、只增不改、结构/投影/数据版本竞争、必填升级、历史读取、字段用途及备份往返
数据演进	升级、旧数据映射、完整备份与恢复、切换后新数据的回退条件
产品旅程	新 UI 和 CLI 调用真后端、隔离 PG；另做真实模型与宿主验证，明确与替身测试的区别

单元测试默认拒绝网络和数据库访问；集成测试只能使用显式隔离数据库与凭据；真实模型验收单独运行并记录成本。代码库各正式入口均要覆盖，不能只测试底层函数而漏掉作者实际点击的路径。

架构检查尽量用导入依赖和可观察行为，不以大文件行数、存在某个函数名或文档包含某个词替代正确性。有效的原子提交、范围拒绝、恢复和保真反例必须承接；仅复述旧实现结构的测试随实现替换退出。

旧结构资产的特别处理

原设计的 23 个基础类型、独立 fine_outline 合同、库内激活结构和作品扩展分别盘点。文件种子与库内版本不一致时记录差异，不用文件覆盖运行事实，也不将旧平台表结构照搬为新版设计。

字段 key、别名、原文位置、结构与实例版本都保存映射。旧 scene/Block 到新场景与正文段落的映射需保真核对；来源中的章号转稳定章节 ID 时保留旧顺序。保留字段级 AI 用途、演变历程与未来成长计划的区别。

证据级别

每项能力分别记录设计覆盖、实现入口、自动化验证和真实使用证据。离线规则测试、隔离 PG 集成、浏览器真后端旅程、真实模型及恢复演练各自有实际结果。设计文件数量、目录存在或功能矩阵已填不能提升成实现完成。

文学改进另需固定条件实验和作者或独立读者判断，不能由两部作品的工程旅程替代。研究材料记录的 56、40 或其他历史测试数量只属于对应参考代码与日期。

备份与恢复入口

完整备份由基础设施的备份恢复.py拥有，包含 PostgreSQL custom archive、原文/草稿字节与内容清单；不使用业务文稿导出来代替。备份清单固定程序/资源构建身份、迁移版本与校验和，以及表内容、关系、权限、序列和文件摘要；凭据值与来源绝对路径不进入清单。源表写锁忙时立即拒绝；固定PG快照期间核对文件前后状态，任一失败不生成成功备份。

恢复必须使用备份时的程序资源与迁移集，点名backup_id，维护角色连接已配置对应角色的新空库，文件根也必须全新。恢复命令不连接旧源、不启动服务、不重新发送模型请求。pg_restore以单事务执行；其失败回滚目标并清理本次文件。提交后的内容复验若失败，保留隔离目标供诊断，不允许将失败当作空库继续覆盖。恢复数据核对后还须运行实际业务旅程。

维护机的PATH须包含能读取源主版本的pg_dump及能读取归档格式的pg_restore；应用镜像本身不提供这两个数据库客户端。数据库用途配置、原文根和草稿根均显式给出，不从源码目录或旧默认连接猜测。

灾难维护命令独立于S02源库账本：muse 数据维护 备份 <维护配置> <新目录>、核对 <目录>、解包 <tar文件> <新目录> --预期备份ID <身份>、恢复 <目标维护配置> <备份目录> --预期备份ID <身份>。备份目录中的清单和归档是中断后重验输入；输出未完成时不会冒充可恢复备份。离线核对/解包无需数据库，恢复仅依赖新目标。

正常运行时的数据维护.yaml通过S02登记保护步骤“核对维护范围”与执行步骤，接受以下明确请求；CLI为muse 数据维护 计划 <作者配置> <请求JSON>，JSON包含非空command_id与request。推进命令为muse 数据维护 推进 <作者配置> <任务ID>；查询和暂停/取消/恢复仍走统一任务入口。

request.action	其他必填字段	所有者与结果
verify_backup	entry_id、backup_id	基础设施对已配置目录的具名备份核对字节；不认定已经恢复
recover_raw	target_task_id	S02只恢复本作者目标任务原文；有效租约保留，migrating先对账
clean_orphans	无	S02按数据库命名空间清理无租约托管对象；未知文件保留，保存清理回执

任务冻结动作和配置文件根哈希，不接受任意路径或脚本；跨作者、同命令换参数、恢复时目录变化均拒绝。原文归档/清理回执由既有owner保存，部分失败保留检查点并进入失败状态；恢复不重复批准。灾难备份时的表锁与源库停机条件决定其不能依赖被备份库中的S02心跳，因此不将其包装成会死锁的后台任务。

作者HTTP只读列出配置目录内备份、核对与下载，不接收任意文件路径或远程恢复请求。工作台明确区分“清单可读”“字节核对”“恢复核验”，下载tar经维护命令安全解包后再恢复。