MAGI系统的设想3：一个用于长篇叙事生成的协作式多智能体框架

MAGI 系统架构蓝图 (SAB v2.1)

版本历史:

v2.0: 提出了一个理想化的、面向服务的微服务架构。
v2.1: 在 v2.0 的基础上，根据工程实践进行修正。引入了务实的、从单体到微服务的演进路线图，明确了 LLM 网关和 Embedding 的核心设计，并修正了工作流。

一、核心设计哲学

AI 即服务 (Agent-as-a-Service): 每个 AI 功能单元（引擎）都被视为一个独立的“专家服务”，拥有清晰的职责边界。
中心化状态与无状态代理 (Centralized State & Stateless Agents): AI 代理本身不存储长期记忆。所有项目数据、世界观、故事内容等“状态”由一个共享状态管理器统一维护，代理在执行任务时按需获取上下文。
务实演进 (Pragmatic Evolution): 系统架构并非一成不变。我们将从一个功能完备的单体应用 (Monolith) 开始，快速验证核心价值，然后根据业务增长和性能需求，逐步、平滑地将关键模块重构为微服务 (Microservices)。

二、架构演进路线图

我们不一步到位实现最终架构，而是分阶段演进。

阶段一：脊梁 (The Spine - V0.1)
此阶段的目标是最快速度打通核心功能闭环。我们采用单体应用架构，所有逻辑都在一个服务中。

架构图 V0.1: 单体优先

描述: 一个基于 Python FastAPI 的后端服务。内部模块化，但部署在一起。
- API Layer: 负责接收前端HTTP请求。
- Orchestrator Logic: 简单的函数调用，负责串联 Engines 和 Database。
- LLM Gateway: 内部模块，负责与外部AI API通信。
- Engines: 以 Python 类的形式存在。
- Database: 使用本地 SQLite 文件进行快速启动，并内嵌一个本地向量数据库（如 ChromaDB）。

阶段二：愿景 (The Vision - V2.0+)
当系统经过验证、用户量增长、功能变得复杂时，我们将向 v2.0 的微服务架构迁移。

架构图 V2.0+: 理想微服务架构

三、核心组件详细设计

LLM 网关 (LLM Gateway)
- 职责: 作为系统与所有外部大语言模型（LLM）API通信的唯一出口。
- 实现模式: 适配器模式 (Adapter Pattern)。定义一个统一的内部接口（LLMProvider），然后为每个外部服务（OpenAI, Gemini, Anthropic等）实现一个具体的适配器类。
- 核心功能:
  - 统一接口: 提供 generate(prompt) 和 embed(text) 等标准方法，上层业务逻辑无需关心底层模型的差异。
  - 凭证管理: 集中、安全地管理所有 API 密钥。
  - 模型切换: 可以通过配置轻松切换默认模型，或为不同任务指定不同模型。
  - 成本与监控: 统一记录调用日志、计算 token 消耗，为成本控制和性能监控提供数据。
  - 重试与回退: 内置请求重试和熔断机制。例如，当一个模型API失败时，可以自动尝试另一个备用模型。
共享状态管理器 & Embedding
- 职责: 系统的“记忆中枢”，负责所有数据的持久化存储和检索。
- 组件:
  - 关系型数据库 (PostgreSQL/SQLite): 存储结构化数据，如项目信息、用户账户、故事章节的元数据、角色卡片等。
  - 向量数据库 (ChromaDB/Faiss/Pinecone): 【核心组件】 存储通过 Embedding 生成的向量数据。
- Embedding 的核心作用 (RAG): 这是 MAGI 实现智能的关键。
  - 写入时: 当任何“知识”被添加到系统时（如世界观条目、故事段落），会立即通过 LLM 网关的 embed() 方法将其转换为向量，并存入向量数据库。
  - 读取/生成时: 当AI需要生成内容时，系统会执行以下 RAG (Retrieval-Augmented Generation) 流程：
    1. 检索 (Retrieve): 将用户的当前指令或问题进行 Embedding，然后在向量数据库中进行语义搜索，找出最相关的 N 条“知识”（可能是世界观、可能是过去的情节）。
    2. 增强 (Augment): 将检索到的这些知识片段，格式化后作为“上下文”插入到最终要发送给 LLM 的 Prompt 中。
    3. 生成 (Generate): LLM 基于这个被“增强”了的、信息丰富的 Prompt 生成内容，从而保证了内容的一致性和深度。
AI 代理服务 (AI Agent Services)
每个引擎都是一个拥有明确 API 的专家。在单体架构中是类，在微服务架构中是独立服务。
- 世界引擎: 提供 query(text) 和 check_consistency(text) 接口。其内部实现严重依赖向量数据库。
- 情节引擎: 提供 narrate(directive, context) 接口。它接收导演指令和 RAG 检索到的上下文，然后调用 LLM 网关生成场景。
- 角色引擎: 提供 act(character_id, situation, context) 接口。它会先从 SQL 数据库加载角色卡，结合 RAG 上下文，调用 LLM 网关进行角色扮演。
任务编排器 (Task Orchestrator)
- 职责: 业务逻辑的核心，负责响应 API 请求，并按照预定工作流调度其他组件。它是“导演的大脑”。
- 核心工作流示例 (/narrate 指令):
  1. 接收请求: API 层接收到 POST /project/123/narrate，请求体为 { "directive": "主角走进了酒吧" }。
  2. 上下文检索 (RAG):
    a. 调用 LLM 网关将 "主角走进了酒吧" 这句话 embed() 成向量。
    b. 使用该向量去向量数据库中查询最相关的3条世界观/记忆片段（例如：“这个酒吧叫‘锈蚀扳手’，是黑客的据点”、“主角正在被‘公司’追捕”）。
    c. 从 SQL 数据库中查询最近的5条故事记录。
  3. Prompt 组装: 将原始指令、检索到的世界观、最近的故事记录组合成一个高质量的 Prompt。
  4. 调用引擎: 调用情节引擎的 narrate 方法，传入组装好的 Prompt。
  5. 接收结果: 引擎通过 LLM 网关 返回生成的故事文本。
  6. 持久化状态:
    a. 将新生成的故事文本作为一个 StoryChunk 存入 SQL 数据库。
    b. （异步）将这个新的文本块进行 embed() 并存入向量数据库，使其成为未来可供检索的“记忆”。
  7. 返回响应: 将生成的故事文本返回给前端。

四、建设规划与线路图 (Actionable Roadmap)

Phase 1: 脊梁 (V0.1) - 目标：1周内上线可用原型
- 任务:
  - 使用 FastAPI 搭建单体应用框架。
  - 实现 LLM Gateway，至少支持 OpenAI 或 Gemini 两者之一。
  - 实现使用 SQLite 的 Database 模块（仅需 Project 和 StoryChunk 表）。
  - 实现一个基础的情节引擎。
  - 实现 /narrate 和 /story 两个核心 API。
  - 使用 React/Vue 搭建一个极简的前端页面，能调用上述 API 并展示结果。
- 验收标准: 用户可以在网页上输入指令，看到 AI 生成的故事，刷新页面后故事内容依然存在。
Phase 2: 大脑 (V0.2) - 目标：引入 RAG
- 任务:
  - 在项目中集成 ChromaDB（一个内嵌式向量数据库）。
  - 在 LLM Gateway 中完善 embed() 方法的实现。
  - 增加用于管理世界观的 API (/world_bible)。
  - 改造 /narrate 工作流，正式引入 RAG 流程：在生成前先从向量数据库检索上下文。
- 验收标准: 添加世界观设定后，AI 的生成内容能明显体现出这些设定，故事一致性显著提高。
Phase 3: 血肉 (V0.3+) - 目标：功能扩展
- 任务:
  - 实现角色引擎和相关的 API。
  - 实现润色引擎等辅助工具。
  - 优化前端界面，支持多项目管理、角色卡编辑等。
  - 根据性能瓶颈，考虑将 LLM 网关 或消耗最高的引擎作为第一个微服务拆分出去。
Phase 4: 愿景 (V2.0+) - 目标：全面微服务化
- 任务:
  - 将数据库迁移到独立的 PostgreSQL 和专用向量数据库服务。
  - 逐步将所有引擎拆分为独立的微服务。
  - 引入 API 网关和事件总线，实现最终的架构蓝图。