OpenMAIC 技术深度解析：基于多智能体的沉浸式 AI 课堂

3.1 整体架构

OpenMAIC 采用模块化分层架构，确保各组件解耦且易于扩展：

• 数据层：PDF 解析（可选 MinerU）、存储
• 能力层：AI Provider 抽象、TTS/ASR、媒体生成
• 核心业务层：生成 Pipeline（两阶段课程生成）、编排层（LangGraph 多智能体）、播放引擎（状态机驱动）、动作引擎（28+ 动作类型）、导出引擎
• 前端层：Next.js App Router、React 组件、Zustand 状态管理

3.2 项目结构解析

OpenMAIC/
├── app/                     # Next.js App Router
│   ├── api/                 # 服务端 API 路由（18 个端点）
│   │   ├── generate/        # 场景生成 Pipeline
│   │   ├── generate-classroom/ # 异步课堂任务提交
│   │   ├── chat/            # 多智能体讨论（SSE 流式）
│   │   └── pbl/             # 项目式学习端点
│   ├── classroom/[id]/      # 课堂播放页面
│   └── page.tsx             # 首页（生成输入）
│   ├── lib/                 # 核心业务逻辑
│   │   ├── generation/      # 两阶段课程生成 Pipeline
│   │   ├── orchestration/   # LangGraph 多智能体编排
│   │   ├── playback/        # 播放状态机
│   │   ├── action/          # 动作执行引擎
│   │   ├── ai/              # LLM Provider 抽象
│   │   ├── store/           # Zustand 状态存储
│   │   └── types/           # TypeScript 类型定义
│   ├── components/          # React UI 组件
│   │   ├── slide-renderer/  # Canvas 幻灯片渲染器
│   │   ├── scene-renderers/ # 测验、互动、PBL 渲染器
│   │   └── whiteboard/      # SVG 白板绘图
│   ├── skills/              # OpenClaw 技能
│   └── openmaic/            # 引导式设置和生成 SOP
├── packages/                # 工作区包
├── pptxgenjs/               # 定制 PowerPoint 生成
└── mathml2omml/             # MathML → Office Math 转换

四、核心技术解析

4.1 两阶段生成 Pipeline

OpenMAIC 采用智能的两阶段课程生成流程，先规划后生成，确保逻辑连贯。

class TwoStageGenerationPipeline:
    """ 两阶段课程生成 Pipeline """
    def __init__(self):
        self.llm_provider = LLMProvider()
        self.content_generator = ContentGenerator()

    def generate_lesson(self, topic, materials=None):
        """ 生成完整课程 """
        # 阶段 1: 大纲生成
        outline = self.generate_outline(topic, materials)
        # 结构化课程大纲，包含学习目标、章节、要点
        
        # 阶段 2: 场景内容生成
        scenes = []
        for item in outline.items:
            scene = self.generate_scene(item)
            # 根据类型生成：幻灯片/测验/互动/PBL
            scenes.append(scene)
        return {'outline': outline, 'scenes': scenes}

    def generate_outline(self, topic, materials):
        """ 生成课程大纲 """
        prompt = f"""
        分析主题：{topic}
        参考材料：{materials}
        生成结构化课程大纲，包含：
         - 学习目标（3-5 个）
         - 章节划分（4-6 章）
         - 每章要点（2-4 个）
         - 建议场景类型（slide/quiz/interactive/pbl）
        """
        return self.llm_provider.generate(prompt)

    def generate_scene(self, outline_item):
        """ 生成场景内容 """
        scene_type = outline_item.get('scene_type', 'slide')
        if scene_type == 'slide':
            return self.generate_slide(outline_item)
        elif scene_type == 'quiz':
            return self.generate_quiz(outline_item)
        elif scene_type == 'interactive':
            return self.generate_interactive(outline_item)
        elif scene_type == 'pbl':
            return self.generate_pbl(outline_item)

Pipeline 优势：

• 结构化：先规划后生成，确保逻辑连贯
• 可扩展：易于添加新的场景类型
• 质量可控：每阶段独立验证和调整

4.2 多智能体编排（LangGraph）

这里我们利用 LangGraph 构建状态机来协调不同角色的智能体行为。注意 teacher_agent 负责核心讲解，而学生智能体则根据设定的人设进行提问或补充。

from langgraph.graph import StateGraph

class MultiAgentOrchestrator:
    """ 基于 LangGraph 的多智能体编排器 """
    def __init__(self):
        self.graph = self.build_director_graph()

    def build_director_graph(self):
        """ 构建导演图 """
        graph = StateGraph(AgentState)
        # 添加节点
        graph.add_node("teacher_agent", self.teacher_agent)
        graph.add_node("student_agent_1", self.student_agent)
        graph.add_node("student_agent_2", self.student_agent)
        graph.add_node("discussion_coordinator", self.coordinator)
        
        # 定义边
        graph.add_edge("teacher_agent", "student_agent_1")
        graph.add_edge("student_agent_1", "student_agent_2")
        graph.add_edge("student_agent_2", "discussion_coordinator")
        graph.add_edge("discussion_coordinator", END)
        return graph.compile()

    def teacher_agent(self, state: AgentState):
        """ AI 教师智能体 """
        # 角色设定：专业、引导性
        system_prompt = """
        你是一位经验丰富的教师，负责：
         - 讲授核心概念
         - 回答学生问题
         - 引导讨论方向
         - 在白板上绘图说明
        """
        action = self.decide_action(state)
        # 生成动作：speech/whiteboard/slide/highlight
        return {'agent': 'teacher', 'action': action, 'content': self.generate_content(state.context)}

    def student_agent(self, state: AgentState):
        """ AI 学生智能体（不同人设） """
        # 角色 1：好问型学生
        # 角色 2：实践型学生
        # 可以有更多人设...
        return {'agent': f'student_{state.student_id}', 'action': 'question', 'content': self.generate_question(state.context)}

智能体类型：

4.3 播放引擎

播放引擎基于状态机驱动，处理场景中的动作序列和用户互动。当检测到用户干预时，会切换到 Live 模式并路由给合适的智能体。

// 播放状态机
enum PlaybackState {
  Idle = 'idle',
  Playing = 'playing',
  Live = 'live'
}

class PlaybackEngine {
  private state: PlaybackState;
  private currentScene: Scene;
  private agents: Agent[];

  async playScene(scene: Scene) {
    this.state = PlaybackState.Playing;
    this.currentScene = scene;
    // 遍历场景中的动作序列
    for (const action of scene.actions) {
      await this.executeAction(action);
      // 检查用户互动
      if (this.hasUserInteraction()) {
        this.state = PlaybackState.Live;
        await this.handleInteraction();
        this.state = PlaybackState.Playing;
      }
    }
    this.state = PlaybackState.Idle;
  }

  private async executeAction(action: Action) {
    // 28+ 动作类型执行
    switch (action.type) {
      case 'speech':
        await this.tts.speak(action.content);
        break;
      case 'whiteboard_draw':
        await this.whiteboard.draw(action.content);
        break;
      case 'slide_highlight':
        await this.slideRenderer.highlight(action.target);
        break;
      case 'laser_pointer':
        await this.slideRenderer.laserPointer(action.position);
        break;
      // ... 更多动作类型
    }
  }

  private async handleInteraction() {
    // 实时用户互动处理
    const userMessage = await this.waitForUserMessage();
    // 通过 LangGraph 路由给合适的智能体
    const response = await this.orchestrator.route(userMessage, this.currentContext);
    await this.executeAction(response.action);
  }
}

4.4 动作执行引擎

系统内置了 28+ 种动作类型，涵盖了从语音播报到白板绘图的各类操作。

class ActionEngine {
  // 28+ 动作类型
  private actionHandlers: Map<ActionType, ActionHandler>;

  constructor() {
    this.actionHandlers = new Map([
      ['speech', new SpeechActionHandler()],
      ['whiteboard_draw', new WhiteboardDrawHandler()],
      ['whiteboard_text', new WhiteboardTextHandler()],
      ['whiteboard_shape', new WhiteboardShapeHandler()],
      ['whiteboard_chart', new WhiteboardChartHandler()],
      ['slide_show', new SlideShowHandler()],
      ['slide_highlight', new SlideHighlightHandler()],
      ['laser_pointer', new LaserPointerHandler()],
      ['spotlight', new SpotlightHandler()],
      // ... 更多动作类型
    ]);
  }

  async execute(action: Action): Promise<void> {
    const handler = this.actionHandlers.get(action.type);
    if (!handler) {
      throw new Error(`Unknown action type: ${action.type}`);
    }
    await handler.execute(action);
  }
}

五、LLM Provider 抽象层

5.1 多模型支持

为了保持灵活性，我们设计了统一的 LLM Provider 接口，支持接入多个大模型服务商。

interface LLMProvider {
  name: string;
  generate(prompt: string, options?: GenerateOptions): Promise<string>;
  stream(prompt: string): AsyncIterable<string>;
}

class ProviderManager {
  private providers: Map<string, LLMProvider>;

  constructor() {
    this.providers = new Map([
      ['openai', new OpenAIProvider()],
      ['anthropic', new AnthropicProvider()],
      ['google', new GeminiProvider()],
      ['deepseek', new DeepSeekProvider()],
      // 支持任何 OpenAI 兼容 API
    ]);
  }

  getProvider(name?: string): LLMProvider {
    const providerName = name || this.getDefaultProvider();
    const provider = this.providers.get(providerName);
    if (!provider) {
      throw new Error(`Provider not found: ${providerName}`);
    }
    return provider;
  }

  private getDefaultProvider(): string {
    // 推荐：Gemini 3 Flash（质量与速度平衡）
    // 最高质量：Gemini 3.1 Pro
    return 'google';
  }
}

推荐模型：

• Gemini 3 Flash：质量与速度最佳平衡
• Gemini 3.1 Pro：最高质量（速度较慢）
• GPT-4o：稳定可靠
• Claude 3.5 Sonnet：长文本优秀

六、场景类型实现

6.1 幻灯片场景

class SlideSceneGenerator {
  async generate(outlineItem: OutlineItem): Promise<SlideScene> {
    const content = await this.llm.generate(`
      为以下主题生成幻灯片内容：${outlineItem.title}
      包含：
       - 标题（简洁有力）
       - 要点列表（3-5 个）
       - 配图描述（用于图像生成）
       - 动作序列（演讲者台词、高亮效果）
    `);
    return {
      type: 'slide',
      content: this.parseContent(content),
      actions: this.generateActions(content),
      metadata: {
        duration: this.estimateDuration(content),
        difficulty: outlineItem.difficulty
      }
    };
  }
}

6.2 测验场景

class QuizSceneGenerator {
  async generate(outlineItem: OutlineItem): Promise<QuizScene> {
    const quiz = await this.llm.generate(`
      为以下主题生成测验：${outlineItem.title}
      要求：
       - 3-5 道题
       - 混合题型（单选/多选/简答）
       - 包含正确答案和解析
       - 难度适中
    `);
    return {
      type: 'quiz',
      questions: this.parseQuiz(quiz),
      grading: 'auto', // AI 自动评分
      feedback: true // 提供反馈
    };
  }
}

6.3 互动模拟场景

class InteractiveSceneGenerator {
  async generate(outlineItem: OutlineItem): Promise<InteractiveScene> {
    const html = await this.llm.generate(`
      为以下主题生成 HTML 互动模拟：${outlineItem.title}
      要求：
       - 使用原生 HTML/CSS/JavaScript
       - 可视化展示概念
       - 支持用户交互
       - 代码简洁可维护
    `);
    return {
      type: 'interactive',
      html: html,
      sandboxed: true // 沙箱环境运行
    };
  }
}

6.4 项目式学习（PBL）

class PBLSceneGenerator {
  async generate(outlineItem: OutlineItem): Promise<PBLScene> {
    const project = await this.llm.generate(`
      为以下主题设计项目式学习：${outlineItem.title}
      包含：
       - 项目描述
       - 角色分配（学生扮演）
       - 里程碑（3-5 个）
       - 交付物
       - AI 助手支持计划
    `);
    return {
      type: 'pbl',
      roles: this.parseRoles(project),
      milestones: this.parseMilestones(project),
      collaboration: 'ai_peers', // AI 同学协作
      deliverables: this.parseDeliverables(project)
    };
  }
}

七、OpenClaw 集成

7.1 集成架构

OpenMAIC 深度集成 OpenClaw，实现从消息应用直接生成课堂：

• 托管模式：Feishu/Slack/Telegram -> OpenClaw 智能助手 -> 获取访问码 -> 生成课堂 -> 返回课堂链接
• 自托管：部署模式 -> 克隆配置启动 -> 生成课堂

7.2 技能配置

# ~/.openclaw/skills/openmaic/SKILL.md
name: openmaic
description: 从任何主题生成互动 AI 课堂
triggers:
  - "教我.*"
  - "学习.*"
  - "生成课堂.*"
phases:
  clone:
    detection: auto
    confirmation: true
  startup:
    modes:
      - pnpm dev
      - pnpm build && pnpm start
      - docker compose up
    selection: user_choice
  provider_keys:
    recommendation: gemini
    user_edit: true
  generation:
    async: true
    polling: true
  notification:
    link_ready: true

八、部署方案

8.1 本地开发

# 克隆项目
git clone https://github.com/THU-MAIC/OpenMAIC.git
cd OpenMAIC
# 安装依赖
pnpm install
# 配置环境变量
cp .env.example .env.local
# 编辑.env.local，添加 LLM API 密钥
# 启动开发服务器
pnpm dev
# 访问 http://localhost:3000

8.2 Docker 部署

# docker-compose.yml
version: '3.8'
services:
  openmaic:
    build: .
    ports:
      - "3000:3000"
    environment:
      - OPENAI_API_KEY=${OPENAI_API_KEY}
      - ANTHROPIC_API_KEY=${ANTHROPIC_API_KEY}
      - GOOGLE_API_KEY=${GOOGLE_API_KEY}
      - DEFAULT_MODEL=google:gemini-3-flash-preview
    volumes:
      - ./data:/app/data

# 配置环境变量
cp .env.example .env.local
# 编辑.env.local
# 启动服务
docker compose up --build

8.3 Vercel 部署

1. Fork 仓库
2. 在 Vercel 导入项目
3. 配置环境变量
4. 部署

环境变量配置：

# 必需：至少配置一个 LLM API 密钥
OPENAI_API_KEY=sk-...
ANTHROPIC_API_KEY=sk-ant-...
GOOGLE_API_KEY=...
# 可选：默认模型
DEFAULT_MODEL=google:gemini-3-flash-preview
# 可选：MinerU 增强文档解析
PDF_MINERU_BASE_URL=https://mineru.example.com
PDF_MINERU_API_KEY=your_api_key

九、技术亮点总结

9.1 创新点

9.2 核心优势

技术优势：

• 基于 LangGraph 的成熟多智能体编排
• 28+ 丰富动作类型，支持复杂交互
• 模块化架构，易于扩展新场景
• 完整的 TypeScript 类型系统

产品优势：

• 一键生成，零门槛使用
• 支持多种 LLM，灵活选择
• 可导出标准格式（PPTX/HTML）
• OpenClaw 集成，无缝对接消息应用

学术价值：

• 发表于 JCST（Journal of Computer Science and Technology）
• 从 MOOC 到 MAIC 的理论创新
• 开源 AGPL-3.0，推动社区发展

十、应用场景与案例

10.1 典型场景

10.2 使用示例

# 示例 1：编程教学
user_input = "教我 Python 从零开始"
output = {
  "outline": ["环境搭建", "基础语法", "数据结构", "函数编程"],
  "scenes": [
    {"type": "slide", "topic": "环境搭建"},
    {"type": "interactive", "topic": "代码练习"},
    {"type": "quiz", "topic": "语法测试"}
  ]
}

# 示例 2：论文解读
user_input = "解读 DeepSeek 最新论文"
output = {
  "outline": ["背景", "方法", "实验", "结论"],
  "scenes": [
    {"type": "slide", "content": "核心创新点"},
    {"type": "interactive", "content": "架构可视化"},
    {"type": "pbl", "content": "复现关键实验"}
  ]
}

十一、总结

OpenMAIC 代表了 AI 驱动教育的新范式，通过多智能体编排技术，实现了从被动观看到主动互动的转变。

技术贡献：

• 两阶段生成 Pipeline 确保内容质量
• LangGraph 实现复杂多智能体编排
• 28+ 动作类型支持丰富交互
• OpenClaw 集成降低使用门槛

未来方向：

• 更多场景类型支持
• 更智能的个性化适配
• 多语言支持扩展
• 移动端体验优化

适用对象：

• 教育机构：快速生成在线课程
• 企业培训：定制化培训内容
• 个人学习：自主学习助手
• 内容创作者：知识变现工具

掌握 OpenMAIC 的技术原理，将为 AI+ 教育领域提供强大支撑。

十二、快速参考

项目地址：

• GitHub：https://github.com/THU-MAIC/OpenMAIC
• 在线体验：https://open.maic.chat
• 论文：https://jcst.ict.ac.cn/en/article/doi/10.1007/s11390-025-6000-0

技术栈：

• Next.js + React
• TypeScript
• LangGraph
• Tailwind CSS
• Zustand

快速启动：

# 克隆
git clone https://github.com/THU-MAIC/OpenMAIC.git
cd OpenMAIC
# 安装
pnpm install
# 配置
cp .env.example .env.local
# 添加 API 密钥
# 运行
pnpm dev

参考资料：

1. OpenMAIC GitHub Repository
2. 'From MOOC to MAIC: Reimagine Online Teaching and Learning through LLM-driven Agents' (JCST 2026)
3. LangGraph Documentation
4. OpenClaw Documentation