58 lines
5.2 KiB
Markdown
58 lines
5.2 KiB
Markdown
# 新版 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)和[功能覆盖矩阵](功能覆盖矩阵.md)：具体旧路径、替代位置、保留内容、退出条件和验证。
|
||
7. [研究依据目录](研究依据/目录.md)：46 个参考项目、主体评估、历史方案和证据范围。
|
||
8. [完整改造计划](改造计划/总计划.md)：32 个工作包的依赖、文件/功能/用例分配、阶段验收及切换回退；实施从 W00、W01 开始。
|
||
|
||
测试重写按[验证设计](验证设计/目录.md)中的独立用例推进，旧文件只作来源索引；原文授权与数据转换分别见[生命周期合同](接口契约/原文证据生命周期.md)及[知识记录分流](数据模型/旧知识记录分流.md)。
|
||
|
||
## 文档权威分工
|
||
|
||
| 内容 | 当前定义位置 |
|
||
|------|--------------|
|
||
| 功能定义 | 业务需求/目标系统完整功能清单.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 或类型身份。实施状态依据真实检查报告记录，不能用本目录的覆盖数量表示产品完成度。
|