# 新版 agent-example 完整改造计划

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

## 执行入口与权威

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

实施从 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 | 新唯一写入口、可解释的观察结果及旧实现收尾 | 旧新无双写；新增内容可保全；逐项退出与全功能证据对账 |

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

## 依赖与并行

```mermaid
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 依赖满足后与创作主链并行；同阶段中没有依赖关系的工作也可以分工。共用接口、启动装配、迁移和生成文件不能由多个执行者无协调修改；文件归属包协调变更，其他包只补充登记的职责。

并行只用于独立输入、独立文件和明确合同的工作，不要求使用子 Agent。单人实施可以按清单拓扑顺序串行推进。计划不虚构人员容量和完成日期；W00—W02 获得环境与首包实测耗时后排日历，每包以实际结果而非预估时间退出。

## 文件与用例安排

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

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

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

## 数据基线策略

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

目标 V0001—V0019 表示最终新库基线。各模块完成后在 W29 从空库按顺序执行全部迁移、引用约束、用途授权和种子导入，重新验证真实约束与恢复，然后冻结。冻结之前的开发子集不能当作正式升级历史；冻结之后不可修改旧迁移，只追加新版本。

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

## 完整交付条件

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

验证方式、每包交付格式、状态与阻塞处理见[执行与验收](执行与验收.md)。