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