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

迁移与验收

本文定义主体替换的顺序、资产承接和退出判据。设计落盘不触发实施、正式数据迁移、旧库删除或部署。

具体文件范围以现有文件处置及其逐项清单为准，包含旧路径、源内容基线、替代位置、保留行为和验收入口。下列增改删编号用于解释迁移主题，不代替逐文件清单，也不授权按目录通配删除。实施前源哈希或运行引用发生变化时，必须重新核对该条承接关系。

测试以独立用例为重写单位，允许拆分、合并及有理由退役；旧测试文件只作来源索引。数据转换分别遵守旧知识记录分流与原文证据生命周期，不能用路径映射或行数相等证明语义承接。

增改删清单

新增

编号	新增项	具体落点与意义
A01	可安装应用包与唯一启动装配	pyproject.toml、src/muse/启动.py，统一依赖与资源发现
A02	类型化业务命令与查询接口	接入/模块公开接口；HTTP、CLI、Skill 共用行为
A03	统一正式变更机制	必需审阅身份、CAS、幂等、依赖复检、回执和派生登记
A04	持久化任务执行	步骤、租约、检查点、取消、恢复、事件重连与预算
A05	完整任务范围与依赖模型	预组装、工具、回放、采纳共用可检验范围
A06	新版独立数据模型与迁移层	承接旧 PG/SQLite 内容，退出主仓列结构的长期捆绑
A07	正文结构及选段协议	段落身份、中文位置口径、编辑往返、保护范围
A08	来源及派生影响索引	正文、事实、规划、方法、报告和投影的版本依赖
A09	作者工作台与服务端查询视图	承接 StoryForge 交互、任务状态与统一写入
A10	可恢复的数据演进与验证入口	升级、备份、隔离恢复、数据对账及全旅程验证
A11	元数据能力在新版的完整承接	S04 类型与字段、结构版本、作品扩展、动态表单、用途投影和升级检查；不是新造第二套实例库

修改 / 重写

编号	现有对象	新形态
R01	framework/、runtime/、分散 LLM 脚本	保留协议与适配代码，收进运行和基础设施职责；不让业务直接构造 Pi
R02	muse/flow/dispatch.py	任务执行、治理、证据分别内聚，编排只组合公开接口
R03	produce_next_chapter.py	通用写作任务，生产与评测分开配置，按明确规则选择必要步骤
R04	write_canonical.py 与各决策 HTTP 入口	完整正文提交用例，共用强制合同，各入口行为一致
R05	规划与知识确认	从“翻状态”改为“重验版本、依赖、结构和明确作者选择后提交”
R06	read_tools.py 与检索组装	输入范围不可放宽，记录真实读取与来源版本
R07	拆书/抽取 upgrade.py	拆为输入分窗、提取、别名/关系归并、持久化、恢复与维护，保留原有互斥和补偿行为
R08	去味脚本群	保留纯规则与 patch，重写入口、报告持久化、任务/经验接线
R09	经验的 PG/SQLite 两路	统一提案、实验、目标变更、启用与退役
R10	现有表与 JSON 字段口径	稳定业务骨架与动态内容分开；S04 维护类型、字段及结构版本，业务模块拥有实例；旧字段和别名显式映射
R11	原只读看板与分散表单	新工作台 + 只读审计查询，独立保留只读职责但不保留多份页面实现
R12	Skill 实现与目录	方法/操作清晰，代码包独立，清单单源生成
R13	测试清单与门禁	依赖显式、离线默认禁外部连接、行为反例覆盖所有实际入口
R14	文档事实源	按架构/领域/数据/契约归位；现状、目标、历史与个人草稿清楚区分

替换完成后删除或退出

编号	删除 / 退出对象	为什么	必需承接条件
D01	跨 Skill 的 sys.path、父目录猜测与裸文件名导入	依赖受物理路径和导入顺序影响	任意 cwd 的安装包入口与独立调用通过
D02	作品/章节专用生产门锚、从回放配置读生产设置	生产无法泛化且混用评测条件	多作品通用链与明确内容门合同通过；样本移入评测
D03	SQLite 重复运行/经验/审查写入口及向量镜像逻辑	形成两套状态、确认语义和恢复路径	数据逐类迁移、仅本地数据保留、历史映射可查、旧写入关闭
D04	旧 web/app.py、重复看板模板和候选/lesson 表单路由	工作台覆盖后重复维护	同一操作的新 UI/CLI/HTTP 行为及审计查询验收
D05	Skill 内复制的 SQL、模型重试、预算、raw 写入辅助脚本	同一保护在多处漂移	共用实现及其真实调用路径覆盖
D06	不再需要的主仓租户、管理、市场列依赖及重复平台治理实现	精简单用户不需要的平台机制，保留元数据能力	类型、字段、结构版本、动态表单及用途投影由 S04 和各消费模块完整承接；M01—M08 通过，历史映射可查
D07	StoryForge 的 Dexie 正式库、独立 AI 调度与浏览器采纳链	与新版权威重复	这些部分不迁入；必要交互与规则由新主体承接
D08	榜单“最近一次 run”效果归因	时间接近不证明因果	真实榜单快照与稿件/反馈版本关联替代
D09	只改经验状态但显示“改进已生效”的路径	状态无法证明目标已修改且被消费	目标 diff/版本、实验、启用与消费记录齐全
D10	运行期读取评测夹具或配置的依赖	生产与评测相互污染	公共合同放代码，条件与材料保持隔离
D11	源码中连接凭据与隐式正式库默认连接	配置不能审计且测试容易误触运行数据	受控持久配置、无值示例、测试配置强制独立；实施时核查既有凭据并处理
D12	仅验证文件形状、字符串和固定完成数量的旧测试	重构易误报且不能保护业务	对应行为测试承接；安全、事务、恢复反例保留
D13	被新文档承接的重复 SoT 正文及失效链接	多套现行规则互相覆盖	权威文档与上下级目录同步，历史用途已标明
D14	无调用方的空适配器、无实际场景的通用插件骨架	增加理解成本而无可观察能力	依赖扫描与功能覆盖确认；有对照测试用途的实现移入相应验证目录

删除对象是被替代实现。正文、原文、历史候选、审查理由、事实、方法、声音、偏好和有效测试不会因改名或换存储丢失。旧库和备份在迁移与回退验证前保留。

功能承接

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

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

实施顺序与退出条件

具体执行排程以完整改造计划及工作包清单为准。32 个工作包分别定义依赖、文件范围、功能与逐例测试安排、验收和回退；分配索引可查询每个目标与旧路径的归属。

完整终态一次定义，代码按可验收旅程替换。旧实现退出仍须满足本文件与逐项处置的内容/数据条件；计划不授权批量删目录。活跃旧写路径在唯一写入切换后退出，测试按用例判定，W31 进行最终对账。

“两部作品各连续两章”是去掉样本依赖的最低工程证据，不是文学质量、多题材效果或规模性能证明。实施顺序不缩小全部 129 项功能范围。

数据迁移及切换

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 或其他历史测试数量只属于对应参考代码与日期。