f76c3cd04a
- 归档并收敛 R2 历史留痕至 docs/实现回顾/R2改造历史留痕.md，删除已退出生命周期的改造计划、旧文件处置及验证过程文档 - 现行测试用例身份收敛至 tests/用例清单.json（1358条扁平登记），适配 conftest、索引维护与测试执行验证 - 清理源码、配置、SQL迁移头、测试夹具及规则文档中的 Wxx 实施分期标签与过时过程描述 - 同步重新打包构建资源清单，通过全量离线测试、模块边界、类型检查与索引双向强核验
4.7 KiB
新版 agent-example 设计阅读指南
本目录定义新版 agent-example 的目标设计及其研究依据，适用于日常维护和设计评审。当前运行行为仍由项目现行入口、合同和实测证据说明；目标设计不代表相关能力已经实现。
设计主张
采用 Python 模块化单体、React/TypeScript 作者工作台、PostgreSQL 持久化任务与业务数据。十个业务模块拥有各自实例和行为，元数据模块提供版本化内容结构。正式变更、任务运行和工作台使用共同接口；私人探索稿保持独立生命周期。
元数据保留类型和字段扩展、结构合成、动态表单、字段用途投影及版本演进。固定身份、版本、授权和提交机制由代码保护。动态结构和可替换能力都不能绕过作者确认、来源范围与事务约束。
阅读顺序
- 目标系统完整功能清单：作者要完成什么。
- 总体架构与术语表：职责、数据归属与概念。
- 元数据与结构演进：动态类型、字段和版本合同。
- 项目目录与文件职责与逐文件设计目录：完整总树、各部分文件树，以及逐文件意图、职责、边界和目标。
- 模块设计目录、接口契约目录和功能规格目录：实现入口、失败后果与验收。
- 迁移与验收和功能覆盖矩阵：长期数据安全合同与功能—规格—测试映射。
- 研究依据目录：46 个参考项目、主体评估、历史方案和证据范围。
- R2 改造历史留痕：主体交付脉络、原证据摘要和验证边界；R2 过程管理已经结束。
现行测试身份见 tests/用例清单.json，行为评测合同见验证设计；原文授权与数据转换分别见生命周期合同及知识记录分流。
文档权威分工
| 内容 | 当前定义位置 |
|---|---|
| 功能定义 | 业务需求/目标系统完整功能清单.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 或类型身份。实施状态依据真实检查报告记录，不能用本目录的覆盖数量表示产品完成度。