5.2 KiB
新版 agent-example 设计阅读指南
本目录定义新版 agent-example 的目标设计及其研究依据，适用于主体重构、重写和实施评审。当前运行行为仍由项目现行入口、合同和实测证据说明；目标设计不代表相关能力已经实现。
设计主张
采用 Python 模块化单体、React/TypeScript 作者工作台、PostgreSQL 持久化任务与业务数据。十个业务模块拥有各自实例和行为，元数据模块提供版本化内容结构。正式变更、任务运行和工作台使用共同接口；私人探索稿保持独立生命周期。
元数据保留类型和字段扩展、结构合成、动态表单、字段用途投影及版本演进。固定身份、版本、授权和提交机制由代码保护。动态结构和可替换能力都不能绕过作者确认、来源范围与事务约束。
阅读顺序
- 目标系统完整功能清单：作者要完成什么。
- 总体架构与术语表：职责、数据归属与概念。
- 元数据与结构演进：动态类型、字段和版本合同。
- 项目目录与文件职责与逐文件设计目录：完整总树、各部分文件树，以及逐文件意图、职责、边界和目标。
- 模块设计目录、接口契约目录和功能规格目录：实现入口、失败后果与验收。
- 现有文件处置、迁移与验收和功能覆盖矩阵：具体旧路径、替代位置、保留内容、退出条件和验证。
- 研究依据目录：46 个参考项目、主体评估、历史方案和证据范围。
- 完整改造计划：32 个工作包的依赖、文件/功能/用例分配、阶段验收及切换回退；实施从 W00、W01 开始。
测试重写按验证设计中的独立用例推进，旧文件只作来源索引；原文授权与数据转换分别见生命周期合同及知识记录分流。
文档权威分工
| 内容 | 当前定义位置 |
|---|---|
| 功能定义 | 业务需求/目标系统完整功能清单.md |
| 领域术语 | 领域模型/术语表.md |
| 模块编号与实例归属 | 总体架构.md |
| 存储对象与引用 | 数据模型/存储与对象关系.md |
| 动态类型、字段及结构演进 | 数据模型/元数据与结构演进.md |
| 状态和来源有效性 | 数据模型/状态与来源有效性.md |
| 公开输入、输出和错误 | 接口契约/ |
| 模块内部职责与协作 | 模块设计/ |
| 作者旅程及行为验收 | 功能规格/ |
| 目标文件路径、意图、职责、边界和目标 | 目标文件清单.json；总树和文件设计各页由此投影 |
| 当前文件的替代、保留和退出 | 现有文件处置清单.json；现有文件处置与分类明细由此投影 |
| 测试用例重写、拆分与退役 | 验证设计/测试用例清单.json；用例页面由此投影，测试文件不作为迁移单位 |
| 原文授权、期限与归档恢复 | 接口契约/原文证据生命周期.md |
| 混合知识表的字段与业务分流 | 数据模型/旧知识记录分流.md |
| 实施工作包、依赖和各类分配 | 改造计划/工作包清单.json；阶段页与分配索引由此投影 |
| 工作包执行与切换回退 | 改造计划/执行与验收.md、改造计划/切换与回退.md |
| 设计权衡 | 决策/ |
| 外部项目与原实现证据 | 研究依据/；仅代表各自核对快照 |
目录、导航和概览引用这些定义。研究报告中的历史建议、旧存储方案和旧字段策略不作为新版目标合同。既有 129 项产品功能不因增加元数据支撑合同而重编号；元数据验收使用独立 M01—M08 编号。
文档包与实施产物
本目录只包含设计文档、研究材料和目标文件清单。清单中的 src、web、配置、数据库、Skill、测试和部署文件是目标位置，不表示已经创建。SQL 迁移编号是目标基线中的分组顺序；真正执行的迁移只能在实施阶段写出、审查和验证。
架构中的单作者身份、五类角色、强能力角色约束、五小时额度窗口、先审后入和私人探索边界均被承接。具体模型 ID、凭据、部署主机连接值、真实作品数据及实验 oracle 不写入本设计包。
维护方式
在同一主题定义文件修改目标行为，再同步受影响的接口、规格、覆盖矩阵与索引。目标路径或合同变化同步 JSON、Markdown 树和逐文件页面；旧文件变化复核处置清单的源哈希、承接与验收。目标清单的 legacy_sources 由旧文件处置反向生成，不独立维护第二份映射。不为路径改名改变稳定模块、角色、Skill 或类型身份。实施状态依据真实检查报告记录，不能用本目录的覆盖数量表示产品完成度。