zclaw_openfang/docs/knowledge-base/openmaic-analysis.md

# OpenMAIC 深度分析报告

> **来源**: https://github.com/THU-MAIC/OpenMAIC
> **分析日期**: 2026-03-22
> **许可证**: AGPL-3.0

## 1. 项目概述

### 1.1 项目定位

**OpenMAIC** (Open Multi-Agent Interactive Classroom) 是由清华大学 MAIC 团队开发的开源 AI 互动课堂平台。它能够将任何主题或文档转化为丰富的互动学习体验，核心特点是**多智能体协作**驱动的教育场景生成。

- **在线演示**: https://open.maic.chat/
- **学术论文**: 发表于 JCST'26 (Journal of Computer Science and Technology)

### 1.2 主要功能和特性

| 功能模块 | 描述 |
|---------|------|
| **一键课堂生成** | 输入主题或上传文档，自动生成完整课堂 |
| **多智能体课堂** | AI 老师和 AI 同学实时授课、讨论、互动 |
| **丰富场景类型** | 幻灯片、测验、HTML 交互式模拟、项目制学习 (PBL) |
| **白板 & 语音** | 智能体实时绘制图表、书写公式、语音讲解 |
| **导出功能** | 支持导出 `.pptx` 幻灯片或交互式 `.html` 网页 |
| **OpenClaw 集成** | 可从飞书、Slack、Telegram 等聊天应用中直接生成课堂 |

### 1.3 目标用户群体

- **教育工作者**: 快速创建互动课程内容
- **学生**: 获得沉浸式、个性化的学习体验
- **企业培训**: 自动化培训材料生成
- **内容创作者**: 将文档转化为互动演示

---

## 2. 技术架构

### 2.1 项目结构

```
OpenMAIC/
├── app/                        # Next.js App Router
│   ├── api/                    # 服务端 API 路由 (~18 个端点)
│   │   ├── generate/           # 场景生成流水线
│   │   ├── generate-classroom/ # 异步课堂生成提交与轮询
│   │   ├── chat/               # 多智能体讨论 (SSE 流式传输)
│   │   ├── pbl/                # 项目制学习端点
│   │   └── ...                 # quiz-grade, parse-pdf, web-search 等
│   ├── classroom/[id]/         # 课堂回放页面
│   └── page.tsx                # 首页
├── lib/                        # 核心业务逻辑
│   ├── generation/             # 两阶段课堂生成流水线
│   ├── orchestration/          # LangGraph 多智能体编排
│   ├── playback/               # 回放状态机
│   ├── action/                 # 动作执行引擎
│   ├── ai/                     # LLM 服务商抽象层
│   ├── api/                    # Stage API 门面
│   ├── store/                  # Zustand 状态管理
│   └── types/                  # TypeScript 类型定义
├── components/                 # React UI 组件
│   ├── slide-renderer/         # Canvas 幻灯片编辑器
│   ├── scene-renderers/        # Quiz/Interactive/PBL 场景渲染器
│   ├── generation/             # 课堂生成工具栏
│   ├── chat/                   # 聊天区域和会话管理
│   ├── settings/               # 设置面板
│   ├── whiteboard/             # SVG 白板绘图
│   ├── agent/                  # 智能体头像、配置
│   └── ui/                     # 基础 UI 组件 (shadcn/ui)
├── packages/                   # 工作区子包
│   ├── pptxgenjs/              # 定制化 PowerPoint 生成
│   └── mathml2omml/            # MathML → Office Math 转换
└── skills/openmaic/            # OpenClaw Skill 定义
```

### 2.2 技术栈

| 层级 | 技术 |
|------|------|
| **前端框架** | Next.js 16 + React 19 |
| **状态管理** | Zustand 5 |
| **样式方案** | Tailwind CSS 4 |
| **LLM SDK** | Vercel AI SDK + LangGraph |
| **类型系统** | TypeScript 5 |
| **Canvas 渲染** | @napi-rs/canvas |
| **幻灯片渲染** | 基于 PPTist 的 Canvas 引擎 |
| **存储** | IndexedDB (Dexie) |
| **富文本编辑** | ProseMirror |

### 2.3 核心模块和组件

#### A. 生成流水线 (`lib/generation/`)

**两阶段生成架构**:
1. **大纲生成** (Stage 1): 分析用户输入，生成结构化课堂大纲
2. **场景生成** (Stage 2): 每个大纲条目生成为丰富的场景

```
用户输入 → 大纲生成器 → 场景生成器 → 完整课堂
              ↓              ↓
         SceneOutline[]  Scene[] (含 Actions)
```

#### B. 多智能体编排 (`lib/orchestration/`)

**LangGraph 状态机拓扑**:
```
START → director ──(end)──→ END
           │
           └─(next)→ agent_generate ──→ director (loop)
```

**Director 策略**:
- **单智能体**: 纯代码逻辑，无 LLM 调用
- **多智能体**: LLM 决定下一个发言的智能体

#### C. 回放引擎 (`lib/playback/engine.ts`)

**状态机**:
```
            start()                  pause()
idle ──────────────────→ playing ──────────────→ paused
  ▲                         ▲                       │
  │                         │  resume()             │
  │                         └───────────────────────┘
  │
  │  handleEndDiscussion()
  │                         confirmDiscussion()
  │                         / handleUserInterrupt()
  │                              │
  │                              ▼         pause()
  └──────────────────────── live ──────────────→ paused
```

#### D. 动作引擎 (`lib/action/engine.ts`)

**支持 28+ 种动作类型**:

| 类别 | 动作 |
|------|------|
| **视觉特效** (Fire-and-forget) | `spotlight`, `laser` |
| **语音** | `speech` (带 TTS) |
| **白板** | `wb_open`, `wb_close`, `wb_draw_text`, `wb_draw_shape`, `wb_draw_chart`, `wb_draw_latex`, `wb_draw_table`, `wb_draw_line`, `wb_clear`, `wb_delete` |
| **视频** | `play_video` |
| **讨论** | `discussion` |

### 2.4 数据流和通信机制

**核心数据流**:
```
用户操作 → React UI → Zustand Store → Next.js API → LangGraph → LLM
                ↓                              ↓
           SSE Stream ← StatelessEvent ← Agent Response
```

**SSE 事件类型** (`StatelessEvent`):
- `agent_start` / `agent_end`: 智能体开始/结束
- `text_delta`: 文本增量
- `action`: 动作执行
- `thinking`: 思考状态
- `cue_user`: 提示用户发言
- `done` / `error`: 完成/错误

---

## 3. 核心能力

### 3.1 Agent 架构设计

**智能体配置结构** (`AgentConfig`):
```typescript
interface AgentConfig {
  id: string;              // 唯一 ID
  name: string;            // 显示名称
  role: string;            // 角色: teacher, assistant, student
  persona: string;         // 完整系统提示词
  avatar: string;          // 头像 URL 或 emoji
  color: string;           // UI 主题色
  allowedActions: string[]; // 允许的动作类型
  priority: number;        // Director 选择优先级 (1-10)
  isDefault: boolean;      // 是否默认模板
  isGenerated?: boolean;   // 是否由 LLM 生成
}
```

**默认智能体**:

| ID | 名称 | 角色 | 优先级 |
|----|------|------|--------|
| default-1 | AI teacher | teacher | 10 |
| default-2 | AI助教 | assistant | 7 |
| default-3 | 显眼包 | student | 4 |
| default-4 | 好奇宝宝 | student | 5 |
| default-5 | 笔记员 | student | 5 |
| default-6 | 思考者 | student | 6 |

**角色-动作映射**:
```typescript
const ROLE_ACTIONS = {
  teacher: [...SLIDE_ACTIONS, ...WHITEBOARD_ACTIONS],  // 全部能力
  assistant: [...WHITEBOARD_ACTIONS],                   // 仅白板
  student: [...WHITEBOARD_ACTIONS],                     // 仅白板
};
```

### 3.2 工具/能力系统

**动作执行架构**:
```typescript
class ActionEngine {
  async execute(action: Action): Promise<void> {
    // 1. 自动打开白板 (如果需要)
    // 2. 根据动作类型执行
    switch (action.type) {
      case 'spotlight': // Fire-and-forget
      case 'laser':
      case 'speech':    // 同步等待 TTS
      case 'wb_*':      // 同步等待渲染
    }
  }
}
```

**结构化输出格式** (LLM 生成):
```json
[
  {"type": "action", "name": "spotlight", "params": {"elementId": "img_1"}},
  {"type": "text", "content": "Hello students..."},
  {"type": "action", "name": "wb_draw_text", "params": {...}}
]
```

### 3.3 记忆/上下文管理

**无状态架构设计**:
- 后端完全无状态，所有状态由客户端维护
- 每次请求携带完整上下文 (`StatelessChatRequest`)

**DirectorState (跨轮次传递)**:
```typescript
interface DirectorState {
  turnCount: number;                    // 当前轮次
  agentResponses: AgentTurnSummary[];   // 智能体响应历史
  whiteboardLedger: WhiteboardActionRecord[]; // 白板操作记录
}
```

**存储层**:
- **IndexedDB** (Dexie): 课堂数据、大纲、生成的智能体
- **localStorage**: 智能体注册表、用户配置
- **持久化策略**: Zustand persist middleware + debounce 保存

### 3.4 多模态支持

| 模态 | 实现 |
|------|------|
| **文本** | 流式生成 + SSE |
| **语音** | Azure TTS / 浏览器 TTS |
| **图像** | 多服务商 (Kling, Qwen, Seedance 等) |
| **视频** | Kling, Veo, Seedance |
| **LaTeX** | KaTeX 渲染 |
| **图表** | ECharts |

---

## 4. 代码质量评估

### 4.1 代码组织方式

**优点**:
- 清晰的模块划分
- 类型集中管理 (`lib/types/`)
- API 门面模式 (`lib/api/stage-api.ts`)
- 关注点分离 (生成/播放/动作)

**文件规模**:
- 核心文件 200-800 行
- 最大文件 `director-graph.ts` 约 450 行

### 4.2 测试覆盖

**未发现测试文件** - 这是项目的明显短板。建议添加:
- 单元测试: 生成流水线、动作解析
- 集成测试: API 端点
- E2E 测试: 课堂生成流程

### 4.3 文档完善度

**优点**:
- 详细的 README (中英双语)
- 内联注释丰富
- SKILL.md 示例展示了 Skill 系统用法

**不足**:
- 缺少 API 文档
- 缺少架构图 (除 README 中的文字描述)
- 无贡献指南细节

### 4.4 可扩展性设计

**良好实践**:
- **Provider 抽象**: 统一的 LLM 服务商接口
- **Action 插件化**: 易于添加新动作类型
- **Scene 类型扩展**: 支持 slide/quiz/interactive/pbl
- **Agent 注册表**: 支持动态添加智能体

**扩展点**:
```typescript
// 添加新 Provider
PROVIDERS['new-provider'] = { ... };

// 添加新 Action 类型
type Action = ... | NewAction;

// 添加新 Scene 类型
type SceneContent = ... | NewContent;
```

---

## 5. 与 ZCLAW 的整合分析

### 5.1 可复用的组件

| 组件 | 来源路径 | ZCLAW 适用场景 |
|------|---------|---------------|
| **LLM Provider 抽象** | `lib/ai/providers.ts` | 统一多模型支持 |
| **结构化输出解析** | `lib/orchestration/stateless-generate.ts` | Tool Call 解析 |
| **Action 系统** | `lib/types/action.ts` + `lib/action/engine.ts` | Agent 能力定义 |
| **智能体注册表** | `lib/orchestration/registry/` | Agent 配置管理 |
| **Zustand Store 模式** | `lib/store/` | 状态管理参考 |
| **SKILL.md 格式** | `skills/openmaic/SKILL.md` | Skill 系统设计 |

### 5.2 架构参考价值

#### A. 无状态后端设计

OpenMAIC 的无状态架构非常适合 ZCLAW 参考:

```typescript
// StatelessChatRequest - 所有状态由客户端传递
interface StatelessChatRequest {
  messages: UIMessage[];      // 对话历史
  storeState: { ... };        // 应用状态
  config: { agentIds, ... };  // 智能体配置
  directorState?: DirectorState; // 跨轮次状态
}
```

ZCLAW 可采用类似模式，避免服务端状态管理复杂性。

#### B. LangGraph 多智能体编排

```typescript
// Director Graph - 智能体调度状态机
const graph = new StateGraph(OrchestratorState)
  .addNode('director', directorNode)
  .addNode('agent_generate', agentGenerateNode)
  .addEdge(START, 'director')
  .addConditionalEdges('director', directorCondition, {...})
  .addEdge('agent_generate', 'director');
```

ZCLAW 的多 Agent 协作可参考此模式。

#### C. Action 执行引擎

```typescript
// 统一的动作执行入口
class ActionEngine {
  async execute(action: Action): Promise<void> {
    // Fire-and-forget vs Synchronous
  }
}
```

ZCLAW 的 Hands 系统可采用类似架构。

### 5.3 潜在的整合方式

#### 方式 1: 作为 ZCLAW 的 Skill

OpenMAIC 可作为 ZCLAW 的一个 Skill 集成:

```markdown
# skills/openmaic/SKILL.md
---
name: openmaic
description: 生成互动课堂
---
```

用户可通过 ZCLAW 调用 OpenMAIC 的课堂生成能力。

#### 方式 2: 共享组件库

抽取共享组件:
- `zclaw-shared-types`: Action 类型、Provider 接口
- `zclaw-action-engine`: 通用动作执行引擎
- `zclaw-llm-adapter`: LLM 服务商适配器

#### 方式 3: 架构借鉴

| OpenMAIC 特性 | ZCLAW 对应 |
|--------------|-----------|
| Director Graph | zclaw-kernel 调度器 |
| Agent Registry | Agent 分身管理 |
| Action Engine | Hands 能力系统 |
| Stage/Scene | 会话/任务管理 |

### 5.4 需要适配的部分

| 差异点 | OpenMAIC | ZCLAW | 适配建议 |
|--------|----------|-------|---------|
| **运行时** | Next.js (服务端) | Tauri (桌面端) | 重构为 Rust 调用 |
| **状态存储** | IndexedDB | SQLite | 保持数据结构，换存储后端 |
| **通信协议** | SSE over HTTP | gRPC / Tauri Commands | 适配流式响应 |
| **UI 框架** | React + Next.js | React + Tauri | 组件可复用 |
| **部署模式** | Web / Vercel | 桌面应用 | 需本地 LLM 支持 |

---

## 6. 总结与建议

### 6.1 OpenMAIC 的优势

1. **成熟的多智能体编排**: LangGraph 状态机设计精良
2. **丰富的场景类型**: 幻灯片、测验、交互、PBL 全覆盖
3. **完善的多模态支持**: 文本、语音、图像、视频、白板
4. **无状态架构**: 易于扩展和维护
5. **学术论文支撑**: 有理论基础

### 6.2 OpenMAIC 的不足

1. **缺少测试**: 无单元测试、集成测试
2. **Web-only**: 无桌面端支持
3. **依赖外部服务**: 需要多个 API Key
4. **文档分散**: 缺少集中式 API 文档

### 6.3 对 ZCLAW 的建议

1. **借鉴无状态设计**: 将状态管理收敛到客户端
2. **采用 Action 系统模式**: 统一 Hands 能力接口
3. **参考 LangGraph 编排**: 实现多 Agent 协作
4. **复用 Provider 抽象**: 统一 LLM 服务商管理
5. **保持桌面端优势**: OpenMAIC 的 Web 限制是 ZCLAW 的机会

---

## 7. 关键代码参考

### 7.1 Provider 抽象接口

```typescript
// lib/ai/providers.ts
export type ProviderId = 'openai' | 'anthropic' | 'google' | ...;

export const PROVIDERS: Record<ProviderId, ProviderConfig> = {
  openai: {
    name: 'OpenAI',
    models: ['gpt-4o', 'gpt-4o-mini', ...],
    defaultModel: 'gpt-4o-mini',
  },
  // ...
};
```

### 7.2 Action 类型定义

```typescript
// lib/types/action.ts
export type Action =
  | SpotlightAction
  | LaserAction
  | SpeechAction
  | WhiteboardAction
  | VideoAction
  | DiscussionAction;

export interface ActionBase {
  type: string;
  id?: string;
}
```

### 7.3 Agent 配置结构

```typescript
// lib/types/agent.ts
export interface AgentConfig {
  id: string;
  name: string;
  role: 'teacher' | 'assistant' | 'student';
  persona: string;
  avatar: string;
  color: string;
  allowedActions: string[];
  priority: number;
  isDefault: boolean;
}
```

---

## 8. AGPL-3.0 许可证风险分析

### 8.1 风险评估

| 风险点 | 影响 | 严重程度 |
|--------|------|----------|
| **Copyleft 传染** | 整合代码可能要求 ZCLAW 也开源 | 🔴 高 |
| **网络条款** | AGPL-3.0 的网络使用条款比 GPL 更严格 | 🔴 高 |
| **商业影响** | 可能影响 ZCLAW 的商业化能力 | 🔴 高 |

### 8.2 决策

❌ **不直接整合 OpenMAIC 代码**
✅ **仅借鉴架构思想和设计模式**

---

## 9. 基于 ZCLAW 现有能力的实现方案

### 9.1 ZCLAW 已有能力对照

| OpenMAIC 功能 | ZCLAW 对应 | 成熟度 |
|---------------|------------|--------|
| 多 Agent 编排 (Director Graph) | A2A 协议 + Kernel Registry | 框架完成 |
| Agent 角色配置 | Skills + Agent 分身 | 完成 |
| 动作执行引擎 (28+ Actions) | Hands 能力系统 | 完成 |
| 工作流编排 | Trigger + EventBus | 基础完成 |
| 状态管理 | MemoryStore (SQLite) | 完成 |
| 外部集成 | Channels | 框架完成 |

### 9.2 实现路径

1. **完善 A2A 通信** - 实现 `crates/zclaw-protocols/src/a2a.rs` 中的 TODO
2. **扩展 Hands** - 添加 whiteboard/slideshow/speech/quiz 能力
3. **创建 Skill** - classroom-generator 课堂生成技能
4. **工作流增强** - DAG 编排、条件分支、并行执行

### 9.3 需要新增的文件

```
hands/whiteboard.HAND.toml   # 白板能力
hands/slideshow.HAND.toml    # 幻灯片能力
hands/speech.HAND.toml       # 语音能力
hands/quiz.HAND.toml         # 测验能力
skills/classroom-generator/SKILL.md  # 课堂生成
```

---

## 10. 后续行动项

- [ ] 完善 A2A 协议实现（消息路由、能力发现）
- [ ] 创建教育类 Hands（whiteboard、slideshow、speech、quiz）
- [ ] 开发 classroom-generator Skill
- [ ] 增强工作流编排能力（DAG、条件分支）