0260bcd8e2
- 新版设计各域 SoT 按本轮实现同步：总体架构、模块设计、接口契约、数据模型、功能规格、文件设计与决策记录。 - 接口契约生成物重新导出（openapi 与前端客户端随契约一致）。 - 实现回顾与专项检查台账保留历史结论；本轮收尾发现另见 .agents.local 下的收尾报告与审查处置。
56 lines
4.9 KiB
Markdown
56 lines
4.9 KiB
Markdown
<!-- 导航元信息: {"内容描述": "新版 agent-example 设计阅读指南", "使用场景": "设计、实现或评审对应主题", "使用要求": "与阅读指南的主题权威分工一致"} -->
|
||
# 新版 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 或类型身份。实施状态依据真实检查报告记录，不能用本目录的覆盖数量表示产品完成度。
|