当你已经确定要做一个“技术 / AI 写作”的多 Agent 产品后，接下来很自然会面临一个选择：

第一版要不要直接上完整前后端分离、消息队列、正式数据库、Worker 和云部署？

当前项目给出的答案是：

不要。

第一版最重要的不是“架构豪华”，而是：

  • 能快
  • 能稳
  • 能持续迭代
  • 能让你把真正的 Agent 问题先跑出来

为什么当前项目选 FastAPI + Jinja2 + SQLite

当前仓库最后落地的技术组合非常朴素：

  • FastAPI
  • Jinja2
  • SQLite

看起来不炫，但很适合这个阶段。

1. FastAPI：把后端逻辑先跑顺

这个项目需要的不只是“调模型”，还包括：

  • 页面路由
  • 表单提交
  • 任务创建
  • 后台动作
  • SSE 实时事件
  • 后台任务调度

FastAPI 恰好能把这些都放在一个简单、清晰的 Python 应用里。

对当前项目来说，它的价值主要体现在：

  • 很适合和模型调用、Agent 逻辑放在同一语言栈
  • 路由层简单清楚
  • 对后续扩展也足够友好

2. Jinja2：先把产品跑起来，而不是先做前端工程

很多人做 Agent 产品，一开始就把大量精力花在 React / Next.js / 状态管理上。
这不是不行，但对第一版来说，往往不是最关键的问题。

当前项目直接用模板渲染页面，目的很明确：

  • 先把任务工作台做出来
  • 先把调试区做出来
  • 先把模型配置、任务详情、审批页面做出来

这样注意力就能放在真正重要的地方：

  • Agent 执行流
  • 状态持久化
  • 调试信息
  • HITL 流程

3. SQLite：先降低启动成本

第一版最怕的是“环境复杂到自己都不想继续维护”。

用 SQLite 的好处非常直接：

  • 不需要单独启动数据库服务
  • 本地开发成本低
  • 演示和迁移方便
  • 很适合单机产品和个人项目

当前项目很多核心状态都已经能稳定存下来了，比如：

  • writing_tasks
  • task_steps
  • task_context_snapshots
  • task_approvals
  • model_configs

这些对单机 MVP 来说已经完全够用了。

当前项目的目录结构为什么这样拆

当前仓库大致可以理解成下面这几层：

app/
src/
data/
doc/
requirements.txt

这套结构不复杂，但已经足够清晰。

app/：应用入口

这里放的是 Web 应用真正启动的地方。

当前核心入口是：

  • app/main.py

这里负责：

  • 注册路由
  • 初始化模板
  • 启动数据库初始化
  • 提供任务页面、模型页面、Agent 页面
  • 提供审批、重试、中断、导出等接口

也就是说，app/ 更像最外层的“壳”。

src/：主要业务逻辑

项目真正的核心都在这里。

里面最关键的目录包括：

  • src/agents/
  • src/services/
  • src/templates/
  • src/static/

可以把它理解成：

  • agents/ 负责角色行为
  • services/ 负责流程、数据、模型、规则、上下文
  • templates/ 负责页面展示
  • static/ 负责样式和静态资源

data/：运行时数据

这个目录主要放两类东西：

  • app.db
  • 导出文件

它的价值是把“代码”和“运行时产物”分开，这样本地维护会轻松很多。

doc/：文档体系

当前项目的文档并不是附属品，而是持续维护的一部分。

里面已经包括：

  • 项目概览
  • 系统设计
  • 运行部署文档
  • Agent 入门教程

这对一个教学型项目很重要，因为它能帮助后续维护时保持认知一致。

src/ 下面为什么还要继续分层

当项目从“一次模型调用”变成“真实系统”后，单文件结构很快就会失控。
所以当前项目做了比较清晰的职责拆分。

src/agents/：定义每个 Agent 怎么工作

这里放的是具体角色的行为实现，比如：

  • dispatcher.py
  • research.py
  • writer.py
  • reviewer.py

这些文件的职责不是控制全局流程，而是：

  • 接收已经准备好的上下文
  • 调用模型
  • 解析结果
  • 返回结构化产物

src/services/：把“系统能力”集中起来

这是当前项目最核心的目录。

里面包括很多真正的系统能力，例如：

  • article_pipeline.py：主流程控制
  • task_service.py：任务与状态管理
  • model_service.py：模型配置和绑定
  • llm.py：模型调用封装
  • quality_gate.py：一致性检查、质量闸门

这层的价值在于：

  • Agent 不需要知道数据库细节
  • 页面不需要知道流程细节
  • 每类系统能力都能集中演进

src/templates/ 和 src/static/：先把产品可视化

很多 Agent 项目在这个阶段只停留在终端输出。
当前项目则进一步把它做成了浏览器工作台。

这让很多系统能力更容易落地：

  • 任务中心
  • 任务详情
  • 审批区
  • 调试信息
  • 质量闸门

为什么这套结构适合教学，也适合迭代

当前这个结构的好处在于，它既足够简单，又能容纳真实问题。

比如最近几轮演进里，项目新增了不少能力：

  • Dispatcher 一致性检查
  • Reviewer 结构化质量闸门
  • 自动回炉 Writer
  • 多轮 reject 的 issue_board
  • 冲突确认与 effective_feedback
  • Context Breakdown
  • 自动化测试

这些能力都没有逼着项目推倒重来，而是自然被安放到了已有结构里：

  • 流程逻辑进 article_pipeline.py
  • 质量检查进 quality_gate.py
  • 数据持久化进 task_service.py / db.py
  • 页面展示进 task_detail.html

这说明“简单结构”不等于“没法演进”。

什么时候才需要更重的架构

当前项目当然不是终点。

如果以后任务量、并发量、协作规模上来，完全可能继续升级成：

  • PostgreSQL
  • 独立 Worker
  • 任务队列
  • 更正式的部署方式
  • 前后端分离

但这些都应该建立在一个前提上：

你已经确认这个产品真的值得继续做。

在此之前，先让当前结构把真实业务问题跑清楚，通常是更划算的选择。

这一章的结论

第一版 Agent 产品的技术栈，最重要的不是“先进”，而是：

  • 能快速启动
  • 能稳定迭代
  • 能容纳真实业务问题

当前项目选择 FastAPI + Jinja2 + SQLite，就是为了把精力留给真正重要的东西：

  • Agent 角色
  • 执行流
  • 上下文
  • 审批
  • 调试
  • 容错

下一章看什么

有了场景和技术栈之后，真正的核心问题来了：

一个多 Agent 系统最小要有哪些执行部件，才能真正跑起来？

下一章我们就进入当前项目的第一条主线：任务、Agent、执行流。