0260bcd8e2
- 新版设计各域 SoT 按本轮实现同步：总体架构、模块设计、接口契约、数据模型、功能规格、文件设计与决策记录。 - 接口契约生成物重新导出（openapi 与前端客户端随契约一致）。 - 实现回顾与专项检查台账保留历史结论；本轮收尾发现另见 .agents.local 下的收尾报告与审查处置。
83 lines
5.4 KiB
Markdown
83 lines
5.4 KiB
Markdown
<!-- 导航元信息: {"内容描述": "新版 agent-example 总体架构", "使用场景": "设计、实现或评审对应主题", "使用要求": "与阅读指南的主题权威分工一致"} -->
|
||
# 新版 agent-example 总体架构
|
||
|
||
系统服务单个作者、多部作品和不同小说题材。实现形态是一个 Python 业务包、一个 React 工作台，以及同包启动的 HTTP 与任务执行进程。PostgreSQL 保存服务端业务与运行状态；私人探索稿通过受控文件接口保存。
|
||
|
||
## 模块与对象归属
|
||
|
||
| 编号 | 模块 | 唯一维护的对象与行为 |
|
||
|------|------|--------------------|
|
||
| B01 | 作品规划 | 作品、系列、卷章目录、探索交接、分层规划、场景计划和规划版本 |
|
||
| B02 | 故事世界 | 本书实体、关系、规则、人物弧线、事件、知情状态、事实和伏笔 |
|
||
| B03 | 资料研究 | 资料原文、来源、榜单快照、参考书拆解及分析版本 |
|
||
| B04 | 知识方法 | 六类范式、方法版本、证据反例、固定绑定和实际消费 |
|
||
| B05 | 正文写作 | 正文结构、版本、分支、选段、候选及正文保存和确认 |
|
||
| B06 | 审校修订 | 问题单、声音、质量规则、诊断、受控修订和保真 |
|
||
| B07 | 作者经验 | 作者偏好、反馈对、观察、改进提案、批准与启用回执 |
|
||
| B08 | 交付连载 | 全书整理、定稿清单、导出、发布版本、日程与读者反馈 |
|
||
| B09 | 上下文 | 任务读取范围、来源装配、检索、冻结快照与消费清单 |
|
||
| B10 | 效果评测 | 数据集、隔离实验、逐例结果、盲评和版本启用判据 |
|
||
| S01 | 正式变更 | 审阅身份、命令幂等、版本与依赖保护、原子提交回执 |
|
||
| S02 | 任务运行 | 步骤、尝试、租约、调用、预算、工具事件、证据和恢复 |
|
||
| S03 | 工作台与系统管理 | 作者交互、跨页会话、查询展示及系统管理入口 |
|
||
| S04 | 元数据 | 类型、字段、结构版本、扩展合成、字段校验和用途投影 |
|
||
|
||
S04 拥有结构定义，各业务模块拥有实例值。相同类型可以在不同资料或作品用途下使用相同结构，不能因此合并其来源、生命周期或确认权限。
|
||
|
||
## 系统调用关系
|
||
|
||
```mermaid
|
||
flowchart TB
|
||
A[作者] --> UI[工作台]
|
||
A --> C[CLI 与主会话]
|
||
UI --> E[身份化业务接入]
|
||
C --> E
|
||
E --> O[应用编排]
|
||
E --> B[业务模块公开接口]
|
||
O --> B
|
||
O --> R[任务运行]
|
||
R --> H[宿主与模型适配]
|
||
H --> T[受限只读工具]
|
||
T --> X[上下文]
|
||
X --> B
|
||
B --> M[元数据校验与投影]
|
||
B --> S[正式变更]
|
||
B --> D[(PostgreSQL)]
|
||
S --> D
|
||
R --> D
|
||
M --> D
|
||
B --> F[受控私人草稿]
|
||
```
|
||
|
||
查询可以直接调用业务公开接口；跨模块长流程由编排协调。任务执行器恢复的是已登记流程及固定输入，而不是主会话的内存。角色输出默认是候选或检查产物。
|
||
|
||
## 依赖纪律
|
||
|
||
- 接入处理协议、身份、输入解析和序列化；不直写业务表。
|
||
- 编排调用各模块公开接口，管理步骤顺序、等待作者和允许的有限返修；业务模块不反向导入编排。
|
||
- 模块导入图不允许环。跨模块流程由编排传递不可变查询结果；需要持续读取能力时，消费方声明窄读取合同，由启动装配绑定实现。
|
||
- S01 只依赖共用提交合同和基础设施，不反向导入业务模块或 S04；各实例维护者提供公开的类型化参与者，负责本域校验和写入。
|
||
- 跨业务调用只穿过接口.py 暴露的合同；存储、内部对象和私有函数不跨模块使用。启动装配可以选择具体实现。
|
||
- 模块内 SQL 收在存储实现；共享事务传递同一个事务上下文，不强制为每次查询再制造透传层。
|
||
- S04 不访问其他模块的表、不接收任意物理表名和列名。native_column 只引用代码登记的业务字段绑定。
|
||
- 纯规则不依赖 HTTP、数据库或宿主 SDK。宿主只执行合同，不决定作品事实。
|
||
- 工作台仅保留交互状态、查询缓存和带基线版本的未提交缓冲；最终状态从后端回执读取。
|
||
- 生产读取不能访问评测答案。字段策略只能在已有授权内裁剪；任何元数据配置都不能扩大任务范围。
|
||
|
||
## 关键设计选择
|
||
|
||
- 持久化收敛到 PostgreSQL，迁移 SQLite 独有历史后退出重复业务写路径。
|
||
- 元数据保留开放类型和内容字段；稳定骨架与受保护行为由代码维护。
|
||
- 正文采用稳定段落 ID 的受限文档结构，场景计划与段落分开表达。
|
||
- 人工保存有并发和版本保护，不要求作者先通过模型评分。
|
||
- 事实提案、规划、方法和正文分别确认；明确批准的关联变更可以组成同一原子提交包。
|
||
- 方法、规则、偏好和运行资源分别由其所属模块维护生效版本，经验模块保存关联回执。
|
||
- 保留五类角色和两阶段写手；流程可组合已登记步骤与槽位，保护节点不可删除或绕行。
|
||
- 包安装和启动不依赖 cwd、父目录层数、tests 或 .git。运行资源随发布包冻结。
|
||
|
||
具体权衡见[决策目录](决策/目录.md)，字段和版本定义见[元数据与结构演进](数据模型/元数据与结构演进.md)。
|
||
|
||
## 产品边界
|
||
|
||
覆盖创作、研究拆书、方法复用、编辑、审校、反馈、评测和交付。短篇采用轻量流程；节点规划是已有规划的视图。多租户、计费、市场交易、跑团、漫画和剧本产品不成为小说主链的依赖。
|