首页 > 专题 > Agent教程 > 文章详情
返回 Agent教程

写小说 Multi-Agent 系统 — 技术架构设计（Spring AI Alibaba）

2026年04月18日 1 阅读 Agent教程

本文详细描述了基于 Spring Boot + Spring AI Alibaba 的多 Agent 写小说系统的完整技术架构，包括 Agent 设计、状态机、多租户、流式输出等核心能力。

一、技术栈总览

| 层级 | 技术选型 | 说明 |
|------|----------|------|
| 前端 | React 18 + Vite + TypeScript | 流式写作界面 |
| Web 框架 | Spring Boot 3.3 WebFlux | SSE 流式推送 |
| Agent 编排 | Spring AI Alibaba Agent Framework | SupervisorAgent 模式 |
| Graph 引擎 | spring-ai-alibaba-graph-core | StateGraph / Checkpoint |
| LLM | 通义千问 Qwen (Spring AI Alibaba) | 流式输出 + 工具调用 |
| 多租户 | 行级隔离 + ThreadLocal | AOP 自动注入 tenant_id |
| 持久化 | MySQL 8.0 + Spring Data JPA | Flyway 数据库迁移 |

二、系统架构图

2.1 整体分层架构

┌────────────────────────────────────────────────────────────────────────────────┐
│                              用户层 (User Layer)                                │
│   ┌─────────────────────────┐          ┌─────────────────────────┐             │
│   │     Web 浏览器           │          │   Admin Studio (Web)    │             │
│   │   (React / Vue)        │          │   (可视化工作流设计)       │             │
│   └──────────┬─────────────┘          └──────────┬─────────────┘             │
└──────────────┼────────────────────────────────┼──────────────────────────────┘
               │ SSE / HTTP                           │ Studio
┌──────────────▼────────────────────────────────────▼──────────────────────────┐
│                            网关层 (Gateway Layer)                             │
│   ┌─────────────┐  ┌─────────────┐  ┌─────────────┐  ┌─────────────┐        │
│   │ AuthCtrl   │  │ProjectCtrl │  │ChapterCtrl │  │ StreamCtrl  │        │
│   │ /api/auth  │  │/api/project│  │/api/chapter│  │/api/stream │        │
│   └─────────────┘  └─────────────┘  └─────────────┘  └─────────────┘        │
│                    JWT Security + CORS + Rate Limiter                           │
└─────────────────────────────────────┼─────────────────────────────────────────┘
                                      │
┌─────────────────────────────────────┼─────────────────────────────────────────┐
│                          多租户隔离层 (Multi-Tenant Layer)                     │
│   HTTP Request → JWT Token → Extract tenant_id → ThreadLocal                   │
└─────────────────────────────────────┼─────────────────────────────────────────┘
                                      │
┌─────────────────────────────────────┼─────────────────────────────────────────┐
│                    Agent 编排层 (Agent Orchestration Layer)                     │
│   ┌────────────────────────────────────────────────────────────────────────┐ │
│   │             Spring AI Alibaba Agent Framework                            │ │
│   │   ┌─────────────────────────────────────────────────────────────────┐  │ │
│   │   │              ReactAgent (Supervisor 模式)                        │  │ │
│   │   │   tools: AgentTool.of(planner/writer/editor/reviewer)         │  │ │
│   │   │   maxLoop: 5   ← 最多返工 5 次                                │  │ │
│   │   └─────────────────────────────────────────────────────────────────┘  │ │
│   │   ┌──────────────┐ ┌──────────────┐ ┌──────────────┐ ┌──────────────┐  │ │
│   │   │ PlannerAgent│ │ WriterAgent  │ │ EditorAgent  │ │ReviewerAgent │  │ │
│   │   │ ReactAgent  │ │ ReactAgent   │ │ ReactAgent   │ │ ReactAgent  │  │ │
│   │   │             │ │ (流式)       │ │              │ │             │  │ │
│   │   │ • 大纲生成  │ │ • 章节写作   │ │ • 润色       │ │ • 质量评估   │  │ │
│   │   │ • 章节规划  │ │ • 场景描写   │ │ • 文风统一   │ │ • APPROVED  │  │ │
│   │   │ • 人物设定  │ │ • 对话生成   │ │ • 语法修正   │ │ • REVISION  │  │ │
│   │   │ • 世界观    │ │ • 情节展开   │ │ • 句式优化   │ │   _NEEDED   │  │ │
│   │   └──────────────┘ └──────┬───────┘ └──────────────┘ └──────────────┘  │ │
│   └─────────────────────────────────────────────────────────────────────┘ │
└─────────────────────────────────────┼─────────────────────────────────────────┘
                                      │
┌─────────────────────────────────────┼─────────────────────────────────────────┐
│                    Graph 执行引擎层 (Graph Execution Layer)                     │
│   StateGraph / CompiledGraph / NodeExecutor / Checkpoint                        │
│   支持: 条件边 / 并行节点 / 流式输出 / 断点持久化                                │
└─────────────────────────────────────┼─────────────────────────────────────────┘
                                      │
┌─────────────────────────────────────┼─────────────────────────────────────────┐
│                       LLM 调用层 (LLM Provider Layer)                         │
│   Spring AI Alibaba (通义千问 Qwen)                                            │
│   支持模型: qwen-turbo / qwen-plus / qwen-max / qwen-coder                    │
└─────────────────────────────────────┼─────────────────────────────────────────┘
                                      │
┌─────────────────────────────────────┼─────────────────────────────────────────┐
│                         数据持久层 (Data Layer)                               │
│   MySQL 8.0: tenants / users / projects / chapters / agent_executions /      │
│              chat_sessions / llm_usage                                        │
└───────────────────────────────────────────────────────────────────────────────┘

2.2 核心数据流

用户输入: "写第三章"
       │
       ▼
① HTTP 请求入口 (POST /api/v1/projects/{pid}/stream/write)
       │
       ▼
② 租户隔离校验 (JWT → tenant_id → ThreadLocal)
       │
       ▼
③ SupervisorAgent 调度
       │
       ├──▶ ④ PlannerAgent → 大纲生成
       │         └── 每个 token → SSE → 前端
       │
       ├──▶ ⑤ WriterAgent → 章节写作 (流式) ★
       │         └── 每个 token → SSE → 前端
       │         └── 保存章节到 MySQL
       │
       ├──▶ ⑥ EditorAgent → 润色
       │
       └──▶ ⑦ ReviewerAgent → 审阅
              │
              ├── [APPROVED] → 结束
              └── [REVISION_NEEDED] → 回 Editor (循环，最多5次)

三、Agent 设计

3.1 SupervisorAgent 模式

SupervisorAgent 是整个系统的核心调度器。它通过将子 Agent 包装成 @Tool，让 LLM 自主决定调用顺序。

// SupervisorAgent 配置
ReactAgent novelSupervisor = ReactAgent.builder()
    .name("novel-supervisor")
    .systemPrompt("你是小说写作监督者，协调 Planner→Writer→Editor→Reviewer")
    .model(chatModel)
    .tools(
        AgentTool.of(plannerAgent),
        AgentTool.of(writerAgent),
        AgentTool.of(editorAgent),
        AgentTool.of(reviewerAgent)
    )
    .maxLoop(5)  // 最多返工 5 次
    .build();

3.2 四个子 Agent

| Agent | 职责 | Prompt 策略 |
|-------|------|-------------|
| PlannerAgent | 生成大纲、章节目录、人物设定 | 结构化输出 JSON |
| WriterAgent | 按章节写作，描述场景、对话 | 长文本流式生成 |
| EditorAgent | 语言润色、文风统一、语法检查 | 改写而非重写 |
| ReviewerAgent | 质量评估，决定是否返工 | 二元决策 (APPROVED / REVISION_NEEDED) |

3.3 StateGraph 编排

// StateGraph 定义
var graph = new StateGraph<>(NovelState.SCHEMA, NovelState::new)
    .addNode("planner", node_async(plannerNode))
    .addNode("writer", node_async(writerNode))
    .addNode("editor", node_async(editorNode))
    .addNode("reviewer", node_async(reviewerNode))

    .addEdge(START, "planner")
    .addEdge("planner", "writer")
    .addEdge("writer", "editor")
    .addEdge("editor", "reviewer")

    // 条件边：Reviewer 通过 → 结束，不通过 → 回 Editor
    .addConditionalEdges("reviewer",
        state -> state.approved() ? END : "editor"
    )
    .compile();

四、Mermaid 架构图

4.1 系统架构

graph TB
    subgraph FRONTEND["前端层"]
        FE["React SPA
流式写作界面"]
        STUDIO["Admin Studio"]
    end

    subgraph GATEWAY["网关层"]
        GW["Spring Boot WebFlux"]
        JWT["JWT Auth"]
    end

    subgraph TENANT["多租户隔离"]
        TI["TenantInterceptor"]
        TL["ThreadLocal"]
    end

    subgraph SERVICE["业务服务"]
        PS["ProjectService"]
        CS["ChapterService"]
        SS["StreamService"]
    end

    subgraph AGENT["Agent 编排层"]
        SUP["SupervisorAgent"]
        PL["PlannerAgent"]
        WR["WriterAgent ★流式"]
        ED["EditorAgent"]
        RV["ReviewerAgent"]
    end

    subgraph GRAPH["Graph 引擎"]
        SG["StateGraph"]
        CP["Checkpoint"]
    end

    subgraph LLM["LLM"]
        CH["通义千问 Qwen"]
    end

    subgraph DB["MySQL 8.0"]
        T["tenants"]
        P["projects"]
        CH["chapters"]
    end

    FE -->|"SSE"| GW
    GW --> JWT --> TI
    TI --> TL
    TL --> PS
    TL --> CS
    PS --> SUP
    SUP --> PL & WR & ED & RV
    PL & WR & ED & RV --> SG --> CP
    WR -->|"stream()"| CH
    PL & ED & RV --> CH
    PS --> P
    CS --> CH

4.2 Agent 执行时序

sequenceDiagram
    participant U as 👤 用户
    participant FE as React
    participant SUP as SupervisorAgent
    participant PL as PlannerAgent
    participant WR as WriterAgent
    participant ED as EditorAgent
    participant RV as ReviewerAgent
    participant LLM as 通义千问
    participant DB as MySQL

    U->>FE: 输入 "写第三章"
    FE->>SUP: POST /api/stream/write

    rect rgb(200, 230, 200)
        Note over SUP,RV: 🔄 Supervisor 调度循环

        SUP->>LLM: 调用 PlannerAgent Tool
        PL-->>SUP: {outline}
        PL-->>FE: 流式 token

        SUP->>LLM: 调用 WriterAgent Tool
        WR-->>FE: token (SSE)
        WR->>DB: 保存章节
        WR-->>SUP: {draft}

        SUP->>LLM: 调用 EditorAgent
        ED-->>SUP: {edited}

        SUP->>LLM: 调用 ReviewerAgent
        RV-->>SUP: [REVISION_NEEDED]
        
        alt 需要返工
            SUP->>LLM: 再次调用 EditorAgent
            ED-->>RV: 修订内容
            RV-->>SUP: [APPROVED]
        end
    end

    SUP-->>FE: done
    FE-->>U: 显示完成

4.3 Agent 状态机

stateDiagram-v2
    [*] --> IDLE
    IDLE --> PLANNING: 用户输入
    PLANNING --> WRITING: 完成
    WRITING --> EDITING: 完成
    EDITING --> REVIEWING: 完成
    REVIEWING --> COMPLETE: APPROVED
    REVIEWING --> EDITING: REVISION_NEEDED
    COMPLETE --> [*]

    Note right of PLANNING: 每个 token → SSE
    Note right of WRITING: 实时字数统计
    Note right of REVIEWING: 最多循环 5 次

五、多租户设计

5.1 隔离策略

  • 行级隔离：每个表都有 tenant_id 字段
  • 上下文传递：ThreadLocal → AOP 自动注入
  • 配额控制：按租户统计 LLM 使用量，超额返回 429

5.2 数据库表

tenants        -- 租户表
users          -- 用户表 (tenant_id)
projects       -- 小说项目 (tenant_id)
chapters       -- 章节 (tenant_id, project_id)
agent_executions -- Agent 执行记录 (tenant_id)
chat_sessions  -- 写作会话 (tenant_id)
llm_usage      -- LLM 使用统计 (tenant_id)

六、技术选型理由

6.1 为什么选 Spring AI Alibaba？

| 对比项 | Spring AI Alibaba | LangGraph4j |
|--------|------------------|-------------|
| StateGraph | ✅ 自有实现 | ✅ 有 |
| 多 Agent 模式 | ✅ 内置 5 种 | ❌ 需自己组合 |
| LLM 集成 | ✅ 通义千问原生 | ⚠️ 需适配器 |
| 国内合规 | ✅ 阿里云原生 | ❌ 无 |
| 可视化工具 | ✅ Admin Studio | ❌ 无 |
| 社区活跃度 | ⭐⭐⭐⭐ (阿里维护) | ⭐⭐ (社区驱动) |

6.2 为什么不选 LangGraph4j？

LangGraph4j 是独立项目，和 Spring AI Alibaba 的 Graph 是竞品关系，不是上下游关系。

Spring AI Alibaba 生态:
  spring-ai-alibaba-graph-core    ← StateGraph (自研)
  spring-ai-alibaba-agent-framework ← 多 Agent 模式 (自研)
  spring-ai-alibaba               ← LLM Provider (通义千问)

LangGraph4j 生态:
  langgraph4j-core               ← StateGraph (独立实现)
  langchain4j                    ← LLM 集成

两者可以共存，但 Spring AI Alibaba 全家桶已够用，无需额外引入。

七、API 设计

| 端点 | 方法 | 说明 |
|------|------|------|
| /api/auth/* | POST | 认证 |
| /api/projects/* | CRUD | 项目管理 |
| /api/projects/{id}/chapters/* | CRUD | 章节管理 |
| /api/projects/{id}/stream/write | POST (SSE) | 流式写作 |
| /api/projects/{id}/stream/cancel | POST | 取消任务 |

SSE 事件类型：

{"type": "token", "content": "某"}
{"type": "agent", "name": "writer", "status": "streaming"}
{"type": "chapter", "num": 3, "words": 2500}
{"type": "done", "final": true}

文档版本：v1.0
最后更新：2026-04-18

教程