外观
系统架构与设计依据
本系统让不确定的模型输出进入受限、可追踪的业务流程。两类Agent是不同上下文、Schema与工具权限下的模型调用函数；外层流程由LangGraph控制。没有自治模型管理数据库或执行任意脚本。
文档网站不在这个运行拓扑中。VitePress构建后只有HTML/CSS/JS和本地搜索索引，Cloudflare Pages不运行此Python应用。
谁负责什么
| 组件 | 职责 | 不负责 |
|---|---|---|
| API/工作台 | 输入校验、任务创建、审核、版本对比、恢复、下载 | 在HTTP请求中等待完整教材制作 |
| LangGraph | 节点、条件分支、修订循环、人工interrupt、checkpoint | 外部服务exactly-once；教材版本业务事务 |
| Provider + ToolSession | 构建独立角色上下文、请求模型、校验函数名和参数、限制工具 | 相信模型自报权限；把检索指令当系统指令 |
| PostgreSQL | 版本、来源、规则快照、评审、任务、事件；pgvector距离计算 | 自动判断内容文化质量 |
| Worker | SKIP LOCKED领取、租约续期、重试上限、依赖与回执核对 | 猜测超时调用一定失败 |
| 媒体卷/FFmpeg | 原子文件落盘、校验和、回执、图片+音频+字幕合成 | 云存储复制；强制语音时间对齐 |
状态与分支
图中退回也可提交人工编辑后重新评审；无资料时退回会重新检索。不可局部修复的结构/引用问题直接转人工，不无限循环。终止后恢复开启新epoch；失败流程优先恢复原checkpoint。
持久化模型
jobs记录当前版本与epoch；versions是不可变教材快照并保存来源/规则；reviews与教材版本一一对应。documents/chunks按资料版本和embedding namespace分隔；资料更新停用旧资料但保留旧片段供审计。node_results缓存已完成节点输出，减轻重放产生的重复写入；LangGraph checkpoint保存流程执行位置。tasks/assets/events分别记录调度、媒体回执和观察信息。
人工编辑的版本保存、epoch更新与新流程入队在同一事务；同书审核还通过book锁串行核对已批准角色事实。生成节点追加检索得到的资料会合并到教材来源快照，工具输出保存在事件中。
业务表与checkpoint并不共享一笔事务。节点可能已提交业务版本但尚未写checkpoint，因此save_version()使用唯一node_key复用结果。模型请求在回包与缓存落库之间仍可能重复，成本也可能重复：这属于已明确保留的边界。
选型与规模
选择同步psycopg+独立worker，让HTTP和耗时任务分离；PostgreSQL任务表减少Redis组件。当前每个worker一次执行一个任务，支持多个进程领取不同任务，单个教材通过advisory lock串行推进。不是高吞吐生产基准。检索使用过滤后的精确余弦搜索；ANN/HNSW属于规模上升后的实验，而非隐藏默认参数。
生产扩展优先顺序：认证/租户隔离与审计策略 → 对象存储与备份 → 外部服务回执能力 → 队列监控与容量验证 → 检索索引和重排评测。不要先把所有框架都装进去。