# 新版 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)。 ## 产品边界 覆盖创作、研究拆书、方法复用、编辑、审校、反馈、评测和交付。短篇采用轻量流程；节点规划是已有规划的视图。多租户、计费、市场交易、跑团、漫画和剧本产品不成为小说主链的依赖。