# OpenMAIC

**Repository Path**: agents-system/OpenMAIC

## Basic Information

- **Project Name**: OpenMAIC
- **Description**: Open Multi-Agent Interactive Classroom — Get an immersive, multi-agent learning experience in just one click
- **Primary Language**: Unknown
- **License**: AGPL-3.0
- **Default Branch**: main
- **Homepage**: https://github.com/THU-MAIC/OpenMAIC
- **GVP Project**: No

## Statistics

- **Stars**: 2
- **Forks**: 1
- **Created**: 2026-03-16
- **Last Updated**: 2026-03-17

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

<!-- <p align="center">
  <img src="assets/logo-horizontal.png" alt="OpenMAIC" width="420"/>
</p> -->

<p align="center">
  <img src="assets/banner.png" alt="OpenMAIC Banner" width="680"/>
</p>

<p align="center">
  一键生成沉浸式多智能体互动课堂。
</p>

<p align="center">
  <a href="https://jcst.ict.ac.cn/en/article/doi/10.1007/s11390-025-6000-0"><img src="https://img.shields.io/badge/Paper-JCST'26-blue?style=flat-square" alt="Paper"/></a>
  <a href="LICENSE"><img src="https://img.shields.io/badge/License-AGPL--3.0-blue.svg?style=flat-square" alt="License: AGPL-3.0"/></a>
  <a href="https://open.maic.chat/"><img src="https://img.shields.io/badge/Demo-Live-brightgreen?style=flat-square" alt="Live Demo"/></a>
  <a href="https://vercel.com/new/clone?repository-url=https%3A%2F%2Fgithub.com%2FTHU-MAIC%2FOpenMAIC&envDescription=Configure%20at%20least%20one%20LLM%20provider%20API%20key%20(e.g.%20OPENAI_API_KEY%2C%20ANTHROPIC_API_KEY).%20All%20providers%20are%20optional.&envLink=https%3A%2F%2Fgithub.com%2FTHU-MAIC%2FOpenMAIC%2Fblob%2Fmain%2F.env.example&project-name=openmaic&framework=nextjs"><img src="https://vercel.com/button" alt="Deploy with Vercel" height="20"/></a>
  <a href="#-openclaw-集成"><img src="https://img.shields.io/badge/OpenClaw-集成-F4511E?style=flat-square" alt="OpenClaw 集成"/></a>
  <a href="https://github.com/THU-MAIC/OpenMAIC/stargazers"><img src="https://img.shields.io/github/stars/THU-MAIC/OpenMAIC?style=flat-square" alt="Stars"/></a>
  <br/>
  <a href="https://discord.gg/PtZaaTbH"><img src="https://img.shields.io/badge/Discord-Join_Community-5865F2?style=for-the-badge&logo=discord&logoColor=white" alt="Discord"/></a>
  &nbsp;
  <a href="community/feishu.md"><img src="https://img.shields.io/badge/Feishu-飞书交流群-00D6B9?style=for-the-badge&logo=bytedance&logoColor=white" alt="飞书群"/></a>
  <br/>
  <img src="https://img.shields.io/badge/Next.js-16-black?style=flat-square&logo=next.js" alt="Next.js"/>
  <img src="https://img.shields.io/badge/React-19-61DAFB?style=flat-square&logo=react&logoColor=white" alt="React"/>
  <img src="https://img.shields.io/badge/TypeScript-5-3178C6?style=flat-square&logo=typescript&logoColor=white" alt="TypeScript"/>
  <img src="https://img.shields.io/badge/LangGraph-1.1-purple?style=flat-square" alt="LangGraph"/>
  <img src="https://img.shields.io/badge/Tailwind_CSS-4-06B6D4?style=flat-square&logo=tailwindcss&logoColor=white" alt="Tailwind CSS"/>
</p>

<p align="center">
  <a href="./README.md">English</a> | <a href="./README-zh.md">简体中文</a>
  <br/>
  <a href="https://open.maic.chat/">在线体验</a> · <a href="#-快速开始">快速开始</a> · <a href="#-功能特性">功能特性</a> · <a href="#-使用场景">使用场景</a> · <a href="#-openclaw-集成">OpenClaw</a>
</p>


## 📖 项目简介

**OpenMAIC**（Open Multi-Agent Interactive Classroom）是一个开源的 AI 互动课堂平台，能够将任何主题或文档转化为丰富的互动学习体验。基于多智能体协作引擎，它可以自动生成演示幻灯片、测验、交互式模拟实验和项目制学习活动——由 AI 教师和 AI 同学进行语音讲解、白板绘图，并与你展开实时讨论。内置 [OpenClaw](https://github.com/openclaw/openclaw) 集成，你还可以直接在飞书、Slack、Telegram 等聊天应用中生成课堂。

<video src="https://file.maic.chat/videos/openmaic-promo-cn.mp4" width="100%" autoplay loop muted></video>

### 核心亮点

- **一键生成课堂** — 描述一个主题或附上学习材料，AI 几分钟内构建完整课堂
- **多智能体课堂** — AI 老师和智能体同学实时授课、讨论、互动
- **丰富的场景类型** — 幻灯片、测验、HTML 交互式模拟、项目制学习（PBL）
- **白板 & 语音** — 智能体实时绘制图表、书写公式、语音讲解
- **灵活导出** — 下载可编辑的 `.pptx` 幻灯片或交互式 `.html` 网页
- **[OpenClaw 集成](#-openclaw-集成)** — 通过 AI 助手在飞书、Slack、Telegram 等 20+ 聊天应用中直接生成课堂

---

> [!TIP]
> ### <img src="https://cdn.jsdelivr.net/gh/homarr-labs/dashboard-icons/png/openclaw.png" height="20" align="top"/> 在聊天应用中使用 OpenMAIC — 零配置
>
> 通过 [OpenClaw](https://github.com/openclaw/openclaw)，你可以直接在飞书、Slack、Discord、Telegram 等 20+ 聊天应用中生成课堂。两种方式：
>
> **方式 A：托管模式**（无需本地部署）
> 1. 在 [open.maic.chat](https://open.maic.chat/) 获取访问码
> 2. `clawhub install openmaic`
> 3. 告诉你的助手 *"教我量子物理"* — 搞定！
>
> **方式 B：本地部署** — Skill 会引导你逐步完成 clone、配置和启动。
>
> [了解更多 →](#-openclaw-集成)

---

## 🚀 快速开始

### 环境要求

- **Node.js** >= 18
- **pnpm** >= 10

### 1. 克隆 & 安装

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

### 2. 配置

```bash
cp .env.example .env.local
```

至少填写一个 LLM 服务商的 API Key：

```env
OPENAI_API_KEY=sk-...
ANTHROPIC_API_KEY=sk-ant-...
GOOGLE_API_KEY=...
```

也可以通过 `server-providers.yml` 配置服务商：

```yaml
providers:
  openai:
    apiKey: sk-...
  anthropic:
    apiKey: sk-ant-...
```

支持的服务商：**OpenAI**、**Anthropic**、**Google Gemini**、**DeepSeek** 以及任何兼容 OpenAI API 的服务。

> **推荐模型：** **Gemini 3 Flash** — 效果与速度的最佳平衡。追求最高质量可选 **Gemini 3.1 Pro**（速度较慢）。
>
> 如果希望 OpenMAIC 服务端默认走 Gemini，还需要额外设置 `DEFAULT_MODEL=google:gemini-3-flash-preview`。

### 3. 启动

```bash
pnpm dev
```

打开 **http://localhost:3000** 开始学习！

### 4. 生产环境构建

```bash
pnpm build && pnpm start
```

### Vercel 部署

[![Deploy with Vercel](https://vercel.com/button)](https://vercel.com/new/clone?repository-url=https%3A%2F%2Fgithub.com%2FTHU-MAIC%2FOpenMAIC&envDescription=Configure%20at%20least%20one%20LLM%20provider%20API%20key%20(e.g.%20OPENAI_API_KEY%2C%20ANTHROPIC_API_KEY).%20All%20providers%20are%20optional.&envLink=https%3A%2F%2Fgithub.com%2FTHU-MAIC%2FOpenMAIC%2Fblob%2Fmain%2F.env.example&project-name=openmaic&framework=nextjs)

或者手动部署：

1. Fork 本仓库
2. 导入到 [Vercel](https://vercel.com/new)
3. 配置环境变量（至少一个 LLM API Key）
4. 部署

### Docker 部署

```bash
cp .env.example .env.local
# 编辑 .env.local 填入你的 API Key，然后：
docker compose up --build
```

### 可选：MinerU（增强文档解析）

[MinerU](https://github.com/opendatalab/MinerU) 提供更强的表格、公式和 OCR 解析能力。你可以使用 [MinerU 官方 API](https://mineru.net/) 或[自行部署](https://opendatalab.github.io/MinerU/quick_start/docker_deployment/)。

在 `.env.local` 中设置 `PDF_MINERU_BASE_URL`（如需认证则同时设置 `PDF_MINERU_API_KEY`）。

---

## ✨ 功能特性

### 课堂生成

描述你想学习的内容，或附上参考材料。OpenMAIC 的两阶段流水线自动完成剩余工作：

| 阶段 | 说明 |
|------|------|
| **大纲生成** | AI 分析你的输入，生成结构化的课堂大纲 |
| **场景生成** | 每个大纲条目生成为丰富的场景——幻灯片、测验、交互模块或 PBL 活动 |

<!-- PLACEHOLDER: 生成流水线 GIF -->
<!-- <img src="assets/generation-pipeline.gif" width="100%"/> -->

### 课堂组件

<table>
<tr>
<td width="50%" valign="top">

**🎓 幻灯片（Slides）**

AI 老师配合聚光灯和激光笔动作进行语音讲解——如同真实课堂。

<img src="assets/slides.gif" width="100%"/>

</td>
<td width="50%" valign="top">

**🧪 测验（Quiz）**

交互式测验（单选 / 多选 / 简答），支持 AI 实时判分和反馈。

<img src="assets/quiz.gif" width="100%"/>

</td>
</tr>
<tr>
<td width="50%" valign="top">

**🔬 交互式模拟（Interactive）**

基于 HTML 的交互实验，用于可视化、动手学习——物理模拟器、流程图等。

<img src="assets/interactive.gif" width="100%"/>

</td>
<td width="50%" valign="top">

**🏗️ 项目制学习（PBL）**

选择一个角色，与 AI 智能体协作完成结构化项目，包含里程碑和交付物。

<img src="assets/pbl.gif" width="100%"/>

</td>
</tr>
</table>

### 多智能体互动

<table>
<tr>
<td valign="top">

- **课堂讨论** — 智能体主动发起讨论话题，你可以随时加入或被点名互动
- **圆桌辩论** — 多个不同人设的智能体围绕话题展开讨论，配合白板讲解
- **自由问答** — 随时提问，AI 老师通过幻灯片、图表或白板进行解答
- **白板** — AI 智能体在共享白板上实时绘图——逐步推导方程、绘制流程图、直观讲解概念

</td>
<td width="360" valign="top">

<img src="assets/discussion.gif" width="340"/>

</td>
</tr>
</table>

### <img src="https://cdn.jsdelivr.net/gh/homarr-labs/dashboard-icons/png/openclaw.png" height="22" align="top"/> OpenClaw 集成

<table>
<tr>
<td valign="top">

OpenMAIC 集成了 [OpenClaw](https://github.com/openclaw/openclaw)——一个连接你日常使用的消息平台（飞书、Slack、Discord、Telegram、WhatsApp 等）的个人 AI 助手。通过这个集成，你可以**直接在聊天应用中生成和查看互动课堂**，无需碰命令行。

</td>
<td width="360" valign="top">

<img src="assets/openclaw-feishu-demo.gif" width="340"/>

</td>
</tr>
</table>

只需告诉你的 OpenClaw 助手你想学什么——剩下的它来搞定：

- **托管模式** — 在 [open.maic.chat](https://open.maic.chat/) 获取访问码，保存到配置文件，即可直接生成课堂——无需本地部署
- **本地部署模式** — clone、安装依赖、配置 API Key、启动服务——Skill 逐步引导你完成
- **跟踪进度** — 自动轮询异步生成任务，完成后把链接发给你

每一步都会先征求你的确认，不会黑盒执行。

<table><tr><td>

**已上架 ClawHub** — 一行命令安装：

```bash
clawhub install openmaic
```

或手动复制：

```bash
mkdir -p ~/.openclaw/skills
cp -R /path/to/OpenMAIC/skills/openmaic ~/.openclaw/skills/openmaic
```

</td></tr></table>

<details>
<summary>配置与详情</summary>

| 阶段 | skill 会做什么 |
|------|------|
| **Clone** | 检测现有仓库，或在执行 clone / 安装依赖前征求确认 |
| **启动** | 在 `pnpm dev`、`pnpm build && pnpm start`、Docker 之间选择 |
| **Provider Key** | 推荐配置路径，引导你自己编辑 `.env.local` |
| **生成** | 提交异步生成任务，轮询进度直到完成 |

可选配置 `~/.openclaw/openclaw.json`：

```jsonc
{
  "skills": {
    "entries": {
      "openmaic": {
        "config": {
          // 托管模式：粘贴从 open.maic.chat 获取的访问码
          "accessCode": "sk-xxx",
          // 本地部署模式：本地仓库路径和地址
          "repoDir": "/path/to/OpenMAIC",
          "url": "http://localhost:3000"
        }
      }
    }
  }
}
```

</details>

### 导出

| 格式 | 说明 |
|------|------|
| **PowerPoint (.pptx)** | 可编辑的幻灯片，包含图片、图表和 LaTeX 公式 |
| **交互式 HTML** | 自包含的网页，包含交互式模拟实验 |

### 更多功能

- **语音合成（TTS）** — 多种语音服务商，支持自定义音色
- **语音识别** — 通过麦克风与 AI 老师对话
- **网络搜索** — 智能体在课堂中搜索网络获取最新信息
- **国际化** — 界面支持中文和英文
- **暗色模式** — 深夜学习更护眼

---

## 💡 使用场景

<table>
<tr>
<td width="50%" valign="top">

> *"零基础文科生，30 分钟学会 Python"*

<img src="assets/python.gif" width="100%"/>

</td>
<td width="50%" valign="top">

> *"如何上手阿瓦隆桌游"*

<img src="assets/avalon.gif" width="100%"/>

</td>
</tr>
<tr>
<td width="50%" valign="top">

> *"分析一下智谱和 MiniMax 的股价"*

<img src="assets/zhipu-minimax.gif" width="100%"/>

</td>
<td width="50%" valign="top">

> *"DeepSeek 最新论文解析"*

<img src="assets/deepseek.gif" width="100%"/>

</td>
</tr>
</table>

---

## 🤝 参与贡献

我们欢迎社区的贡献！无论是 Bug 报告、功能建议还是 Pull Request，都非常感谢。

### 项目结构

```
OpenMAIC/
├── app/                        # Next.js App Router
│   ├── api/                    #   服务端 API 路由（约 18 个端点）
│   │   ├── generate/           #     场景生成流水线（大纲、内容、图片、TTS…）
│   │   ├── generate-classroom/ #     异步课堂生成提交与轮询
│   │   ├── chat/               #     多智能体讨论（SSE 流式传输）
│   │   ├── pbl/                #     项目制学习端点
│   │   └── ...                 #     quiz-grade, parse-pdf, web-search, transcription 等
│   ├── classroom/[id]/         #   课堂回放页面
│   └── page.tsx                #   首页（生成输入）
│
├── lib/                        # 核心业务逻辑
│   ├── generation/             #   两阶段课堂生成流水线
│   ├── orchestration/          #   LangGraph 多智能体编排（导演图）
│   ├── playback/               #   回放状态机（idle → playing → live）
│   ├── action/                 #   动作执行引擎（语音、白板、特效）
│   ├── ai/                     #   LLM 服务商抽象层
│   ├── api/                    #   Stage API 门面（幻灯片/画布/场景操作）
│   ├── store/                  #   Zustand 状态管理
│   ├── types/                  #   集中式 TypeScript 类型定义
│   ├── audio/                  #   TTS & ASR 服务商
│   ├── media/                  #   图片 & 视频生成服务商
│   ├── export/                 #   PPTX & HTML 导出
│   ├── hooks/                  #   React 自定义 Hooks（55+）
│   ├── i18n/                   #   国际化（zh-CN, en-US）
│   └── ...                     #   prosemirror, storage, pdf, web-search, utils
│
├── components/                 # React UI 组件
│   ├── slide-renderer/         #   基于 Canvas 的幻灯片编辑器和渲染器
│   │   ├── Editor/Canvas/      #     交互式编辑画布
│   │   └── components/element/ #     元素渲染器（文本、图片、形状、表格、图表…）
│   ├── scene-renderers/        #   测验、交互、PBL 场景渲染器
│   ├── generation/             #   课堂生成工具栏和进度
│   ├── chat/                   #   聊天区域和会话管理
│   ├── settings/               #   设置面板（服务商、TTS、ASR、媒体…）
│   ├── whiteboard/             #   基于 SVG 的白板绘图
│   ├── agent/                  #   智能体头像、配置、信息栏
│   ├── ui/                     #   基础 UI 组件（shadcn/ui + Radix）
│   └── ...                     #   audio, roundtable, stage, ai-elements
│
├── packages/                   # 工作区子包
│   ├── pptxgenjs/              #   定制化 PowerPoint 生成
│   └── mathml2omml/            #   MathML → Office Math 转换
│
├── skills/                     # OpenClaw / ClawHub skills
│   └── openmaic/               #   OpenMAIC 引导式 SOP skill
│       ├── SKILL.md            #   轻量路由层 + 确认规则
│       └── references/         #   按需加载的 SOP 分段
│
├── configs/                    # 共享常量（形状、字体、快捷键、主题…）
└── public/                     # 静态资源（logo、头像）
```

### 核心架构

- **生成流水线** (`lib/generation/`) — 两阶段：大纲生成 → 场景内容生成
- **多智能体编排** (`lib/orchestration/`) — 基于 LangGraph 的状态机，管理智能体轮次和讨论
- **回放引擎** (`lib/playback/`) — 驱动课堂回放和实时互动的状态机
- **动作引擎** (`lib/action/`) — 执行 28+ 种动作类型（语音、白板绘图/文字/形状/图表、聚光灯、激光笔…）

### 贡献流程

1. Fork 本仓库
2. 创建你的功能分支 (`git checkout -b feature/amazing-feature`)
3. 提交你的更改 (`git commit -m 'Add amazing feature'`)
4. 推送到分支 (`git push origin feature/amazing-feature`)
5. 提交 Pull Request

---

## 💼 商业合作

本项目基于 AGPL-3.0 协议开源。商业授权合作请联系：**thu_maic@tsinghua.edu.cn**

---

## 📝 引用

如果 OpenMAIC 对您的研究有帮助，请考虑引用：

```bibtex
@Article{JCST-2509-16000,
  title = {From MOOC to MAIC: Reimagine Online Teaching and Learning through LLM-driven Agents},
  journal = {Journal of Computer Science and Technology},
  volume = {},
  number = {},
  pages = {},
  year = {2026},
  issn = {1000-9000(Print) /1860-4749(Online)},
  doi = {10.1007/s11390-025-6000-0},
  url = {https://jcst.ict.ac.cn/en/article/doi/10.1007/s11390-025-6000-0},
  author = {Ji-Fan Yu and Daniel Zhang-Li and Zhe-Yuan Zhang and Yu-Cheng Wang and Hao-Xuan Li and Joy Jia Yin Lim and Zhan-Xin Hao and Shang-Qing Tu and Lu Zhang and Xu-Sheng Dai and Jian-Xiao Jiang and Shen Yang and Fei Qin and Ze-Kun Li and Xin Cong and Bin Xu and Lei Hou and Man-Li Li and Juan-Zi Li and Hui-Qin Liu and Yu Zhang and Zhi-Yuan Liu and Mao-Song Sun}
}
```

---

## 📄 许可证

本项目基于 [GNU Affero General Public License v3.0](LICENSE) 开源。