muse-agent-example/docs/系统架构/新版设计/改造计划/总计划.md

新版 agent-example 完整改造计划

本计划把已定义的新版设计落实为 32 个有依赖的工作包。目标仍是 Python 模块化单体、React/TypeScript 作者工作台、持久化任务与 PostgreSQL，完整承接元数据、创作、研究、质量、经验和交付能力。实施状态与证据随工作包记录；正式迁移、发布与生产切换遵循单独授权。

执行入口与权威

工作包、依赖和文件/功能/用例分配以工作包清单为准；分阶段页面与分配索引是可读投影。业务目标、文件职责、用例内容和旧文件处置分别引用上层设计，不在计划另造一套定义。

实施从 W00、W01 开始，再按依赖推进。首批交付的是可复现基线、隔离方式、接口与逐用例验收安排；不能直接批量搬目录或删除旧脚本。已有未提交修改和已删除文件均属于基线，单独的 HEAD 不能代表当前工作树。

范围

覆盖十个业务模块、四个支撑模块、全部 129 项功能，以及前后端、Skill、资源、迁移、测试、构建和部署。元数据类型与字段扩展保留，实例仍由业务模块拥有；测试按用例重写；旧 PG、SQLite、参考原文、私人探索稿和原文归档分别处理。

正式内容以 PG 为权威。新实现先运行于隔离工作树、开发库和验收库；当前旧服务继续使用旧库。计划不把开发演示数据当正式作品，不把浏览器缓冲或 SQLite 人审记录提升为正式正文。多租户、计费、市场和额外叙事产品不进入本改造依赖。

阶段与里程碑

阶段	工作包	可交付结果	阶段验收
P0 基线与合同	W00—W01	工作树与资产基线、逐例工作单、接口和环境边界	基线可重建；没有遗漏已有改动、私人资料或关键反例
P1 安装与运行底座	W02—W08	可安装包、隔离数据库、元数据、任务、宿主、接入和原文保护	任意 cwd 启动；范围/权限/预算/原文保护可独立验证
P2 人工编辑与正式提交	W09—W11	新作品手写、动态表单、版本保存、候选审阅与冲突处理	浏览器连真后端验证人工编辑与当前可用提交范围；不宣称尚未接入的完整事实链通过
P3 通用创作主链	W12—W16	渐进探索、规划、事实、受限上下文、生成、采纳和章后恢复	至少两部不同题材作品各连续两章；真实消费者的 CAS/正文/事实/派生事务用例通过
P4 研究与知识资产	W17—W21	原文/榜单、拆书、世界维护、方法复用和迁移分流框架	资料到方法实际消费可追踪；抽取失败和旧数据歧义不被吞掉
P5 质量与经验评测	W22—W26	全文报告、声音、受控修订、案例、逐例评测和改进启用	保护反例、独立评测、六个行为场景与同版本启用分别验证
P6 交付与全量恢复	W27—W29	定稿连载、发布包、完整数据迁移演练及恢复证据	完整空库基线、全对象对账、真实宿主和浏览器旅程达到切换条件
P7 切换与退出	W30—W31	新唯一写入口、可解释的观察结果及旧实现收尾	旧新无双写；新增内容可保全；逐项退出与全功能证据对账

两个作品两章用于证明工程泛化，不证明文学质量或所有题材效果。每项功能继续按自身规格收集实现、自动化与适用的真实使用证据；阶段表不以包数、文件数或测试数量计算完成率。

依赖与并行

flowchart LR
  B[P0 基线与合同] --> F[P1 安装与运行底座]
  F --> E[P2 人工编辑与正式提交]
  E --> C[P3 通用创作主链]
  E --> S[W17 资料与来源]
  C --> K[P4 拆书 世界 方法 分流]
  S --> K
  K --> Q[P5 审校 修订 评测 经验]
  Q --> D[P6 交付与全量恢复]
  D --> X[P7 切换与退出]

这是阶段视图，具体依赖以各包 depends_on 为准。W17 可在其 P2 依赖满足后与创作主链并行；同阶段中没有依赖关系的工作也可以分工。共用接口、启动装配、迁移和生成文件不能由多个执行者无协调修改；文件归属包协调变更，其他包只补充登记的职责。

制定执行安排时先核对各任务的输入、修改边界、前置能力、维护者与验收方式；前置满足、互不影响且有实际收益的任务应分工并发实现、验证和交付。依赖任务在所需能力验证通过后衔接，不等待整个前置包完成；共享修改和连续决策由唯一维护者协调。各线使用包含所需当前改动的同一可核验基线及隔离工作区，主代理负责集成顺序；人员、工具或环境不足时说明具体限制并按依赖串行，不虚构并发能力和完成日期。通用纪律见计划与提交，本改造的批次与整体验收见执行与验收。

文件与用例安排

每个目标路径有维护包及后续补全包。生成目录、私人数据占位和历史材料明确区别于手写源码；不得为满足清单而创建空文件或虚构数据。共用接口可以先实现本阶段稳定部分，后续功能继续补全，但不能把首次创建视作最终职责完成。

每个 TC 用例有具体实施包、原条件和指定环境；旧 LC 记录仅解释来源及退役。完整提交用例安排在 W16 等真实消费者齐备的工作包，机制测试不能替代它们。新增功能所需用例由所属包在编码前补齐，不假设现有旧用例清单已经覆盖全部新功能。

旧实现只有在全部承接包、对应用例及数据条件满足后才可退出。隔离工作树中无运行依赖的已替代辅助文件可以随包清理；活跃旧服务与旧数据写路径须经过 W30 切换。W31 完成最终扫描，而不是按目录名批量删除。

数据基线策略

开发库只含合成或可重放数据，可以按已完成的迁移集合重建；不将真实作者新增内容放入可随意重建的开发库。验收库中的真实来源副本、人工试用输入或归档要保全后才能重建。

最终新库基线以磁盘、发布包与数据库账本共同核验的完整迁移清单为准，不要求版本号连续。原计划 V0017/V0018/V0019 已分别由 V0050/V0051/V0049 承接，不补录低版本。各模块完成后在 W29 从空库按顺序执行全部迁移、引用约束、用途授权和种子导入，重新验证真实约束与恢复，然后冻结。冻结之前的开发子集不能当作正式升级历史；冻结之后不可修改旧迁移，只追加新版本。

代码换版、数据转换、角色权限和入口切换的具体步骤见切换与回退。不承诺切回旧程序就能保住新架构下产生的稿件。

完整交付条件

所有功能、文件职责、用例、旧记录、原文和权限均有明确结果；缺证据部分保持未验收。真实模型、浏览器、数据库并发、完整恢复和文学判断分别出结果。交付包含可运行发布包、受控配置引用、实际验证证据、完整恢复材料和准确使用说明。

验证方式、每包交付格式、状态与阻塞处理见执行与验收。