OpenMAIC — 多智能体互动教室

技能由 ara.so 提供 — Daily 2026 Skills 系列。

OpenMAIC（开放多智能体互动教室）是一个基于 Next.js 16 / React 19 / TypeScript 的平台，可将任何主题或文档转换为完整的互动课程。多智能体管道（LangGraph 1.1）生成幻灯片、测验、HTML 模拟和基于项目的学习活动，由 AI 教师和 AI 同学通过语音（文本转语音）和白板支持进行授课。

项目技术栈

安装

git clone https://github.com/THU-MAIC/OpenMAIC.git
cd OpenMAIC
pnpm install

环境配置

cp .env.example .env.local

编辑 .env.local — 至少需要一个 LLM 提供商的密钥：

# LLM 提供商（至少配置一个）
OPENAI_API_KEY=$OPENAI_API_KEY
ANTHROPIC_API_KEY=$ANTHROPIC_API_KEY
GOOGLE_API_KEY=$GOOGLE_API_KEY

# 推荐的默认模型（Gemini 3 Flash = 最佳速度/质量平衡）
DEFAULT_MODEL=google:gemini-3-flash-preview

# 可选：用于高级 PDF/表格/公式解析的 MinerU
PDF_MINERU_BASE_URL=https://mineru.net
PDF_MINERU_API_KEY=$MINERU_API_KEY

# 可选：托管模式的访问码
ACCESS_CODE=$OPENMAIC_ACCESS_CODE

通过 YAML 配置提供商（环境变量的替代方案）

在项目根目录创建 server-providers.yml：

providers:
  openai:
    apiKey: $OPENAI_API_KEY
  anthropic:
    apiKey: $ANTHROPIC_API_KEY
  google:
    apiKey: $GOOGLE_API_KEY
  deepseek:
    apiKey: $DEEPSEEK_API_KEY
  # 任何 OpenAI 兼容的端点
  custom:
    baseURL: https://your-proxy.example.com/v1
    apiKey: $CUSTOM_API_KEY

运行应用

# 开发模式
pnpm dev
# → http://localhost:3000

# 生产构建
pnpm build && pnpm start

# 类型检查
pnpm tsc --noEmit

# 代码检查
pnpm lint

Docker 部署

cp .env.example .env.local
# 使用您的 API 密钥编辑 .env.local

docker compose up --build
# → http://localhost:3000

Vercel 部署

# 复刻仓库，然后在 https://vercel.com/new 导入
# 在 Vercel 仪表板中设置环境变量：
#   OPENAI_API_KEY 或 ANTHROPIC_API_KEY 或 GOOGLE_API_KEY
#   DEFAULT_MODEL（可选，例如 google:gemini-3-flash-preview）

README 中提供了一键部署按钮，它会自动预填环境变量描述。

课程生成流程

OpenMAIC 使用两阶段流程：

场景类型

API 使用 — 生成教室

REST：开始生成作业

// POST /api/generate
const response = await fetch('/api/generate', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({
    topic: '量子纠缠',
    // 可选：附加文档内容
    document: markdownString,
    // 可选：模型覆盖
    model: 'google:gemini-3-flash-preview',
  }),
});

const { jobId } = await response.json();

REST：轮询作业状态

// GET /api/generate/status?jobId=<jobId>
const poll = async (jobId: string) => {
  while (true) {
    const res = await fetch(`/api/generate/status?jobId=${jobId}`);
    const data = await res.json();

    if (data.status === 'completed') {
      console.log('教室链接：', data.classroomUrl);
      break;
    }
    if (data.status === 'failed') {
      throw new Error(data.error);
    }
    // status === 'pending' | 'running'
    await new Promise(r => setTimeout(r, 3000));
  }
};

REST：导出幻灯片

// GET /api/export/pptx?classroomId=<id>
const exportPptx = async (classroomId: string) => {
  const res = await fetch(`/api/export/pptx?classroomId=${classroomId}`);
  const blob = await res.blob();
  const url = URL.createObjectURL(blob);
  // 触发下载
  const a = document.createElement('a');
  a.href = url;
  a.download = 'lesson.pptx';
  a.click();
};

// GET /api/export/html?classroomId=<id>
const exportHtml = async (classroomId: string) => {
  const res = await fetch(`/api/export/html?classroomId=${classroomId}`);
  const html = await res.text();
  return html;
};

OpenClaw 集成

OpenMAIC 为 OpenClaw 提供了一个技能，支持从飞书、Slack、Discord、Telegram 等平台生成教室。

安装技能

# 通过 ClawHub 安装（推荐）
clawhub install openmaic

# 手动安装
mkdir -p ~/.openclaw/skills
cp -R /path/to/OpenMAIC/skills/openmaic ~/.openclaw/skills/openmaic

配置 OpenClaw

编辑 ~/.openclaw/openclaw.json：

{
  "skills": {
    "entries": {
      "openmaic": {
        "config": {
          // 托管模式 — 从 https://open.maic.chat/ 获取访问码
          "accessCode": "$OPENMAIC_ACCESS_CODE",

          // 自托管模式 — 本地仓库 + 服务器 URL
          "repoDir": "/path/to/OpenMAIC",
          "url": "http://localhost:3000"
        }
      }
    }
  }
}

OpenClaw 技能生命周期

自定义场景开发模式

场景是类型化的 React 组件。要添加新的场景类型：

// types/scene.ts
export type SceneType = 'slides' | 'quiz' | 'interactive' | 'pbl' | 'custom';

export interface CustomScene {
  type: 'custom';
  title: string;
  content: string;
  // 您的字段
  metadata: Record<string, unknown>;
}

// components/scenes/CustomScene.tsx
'use client';

import { type CustomScene } from '@/types/scene';

interface Props {
  scene: CustomScene;
  onComplete: () => void;
}

export function CustomSceneComponent({ scene, onComplete }: Props) {
  return (
    <div className="flex flex-col gap-4 p-6">
      <h2 className="text-2xl font-bold">{scene.title}</h2>
      <div dangerouslySetInnerHTML={{ __html: scene.content }} />
      <button
        className="mt-4 rounded-lg bg-blue-600 px-6 py-2 text-white"
        onClick={onComplete}
      >
        继续
      </button>
    </div>
  );
}

多智能体互动模式

MinerU 高级文档解析

对于包含表格、公式或扫描图像的复杂 PDF：

# 使用 MinerU 托管 API
PDF_MINERU_BASE_URL=https://mineru.net
PDF_MINERU_API_KEY=$MINERU_API_KEY

# 或自托管 MinerU 实例（Docker）
PDF_MINERU_BASE_URL=http://localhost:8888

如果没有 MinerU，OpenMAIC 会回退到标准的 PDF 文本提取。

支持的 LLM 提供商及模型字符串

// 模型字符串格式："provider:model-name"
const models = {
  // Google（推荐）
  geminiFlash: 'google:gemini-3-flash-preview',   // 最佳速度/质量平衡
  geminiPro: 'google:gemini-3.1-pro',             // 最高质量

  // OpenAI
  gpt4o: 'openai:gpt-4o',
  gpt4oMini: 'openai:gpt-4o-mini',

  // Anthropic
  claude4Sonnet: 'anthropic:claude-sonnet-4-5',
  claude4Haiku: 'anthropic:claude-haiku-4-5',

  // DeepSeek
  deepseekChat: 'deepseek:deepseek-chat',

  // OpenAI 兼容（自定义 base URL）
  custom: 'custom:your-model-name',
};

导出格式

常见模式

从文档字符串生成教室

const generateFromDocument = async (markdownContent: string, topic: string) => {
  const res = await fetch('/api/generate', {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify({
      topic,
      document: markdownContent,
      model: process.env.DEFAULT_MODEL ?? 'google:gemini-3-flash-preview',
    }),
  });

  const { jobId } = await res.json();

  // 轮询直至完成
  let classroomUrl: string | null = null;
  while (!classroomUrl) {
    await new Promise(r => setTimeout(r, 4000));
    const status = await fetch(`/api/generate/status?jobId=${jobId}`).then(r => r.json());
    if (status.status === 'completed') classroomUrl = status.classroomUrl;
    if (status.status === 'failed') throw new Error(status.error);
  }

  return classroomUrl;
};

检查提供商健康状态

// GET /api/providers
const checkProviders = async () => {
  const res = await fetch('/api/providers');
  const { providers } = await res.json();
  // providers: Array<{ name: string; available: boolean; models: string[] }>
  return providers.filter((p: { available: boolean }) => p.available);
};

故障排除

关键文件结构

OpenMAIC/
├── app/                    # Next.js App Router 页面及 API 路由
│   ├── api/
│   │   ├── generate/       # POST 课程生成，GET 状态
│   │   ├── export/         # pptx / html 导出端点
│   │   └── providers/      # LLM 提供商健康检查
│   └── classroom/          # 教室查看页面
├── components/
│   ├── scenes/             # 幻灯片、测验、互动、PBL 组件
│   ├── whiteboard/         # 实时白板渲染
│   └── agents/             # 智能体头像及文本转语音组件
├── lib/
│   ├── agents/             # LangGraph 智能体图定义
│   ├── providers/          # LLM 提供商抽象
│   └── generation/         # 大纲 + 场景生成流程
├── skills/
│   └── openmaic/           # OpenClaw 技能定义
├── server-providers.yml    # 可选的 YAML 提供商配置
├── .env.example            # 环境变量模板
└── docker-compose.yml      # Docker 部署配置