zclaw_openfang/docs/knowledge-base/openmaic-zclaw-comparison.md

# OpenMAIC vs ZCLAW 功能对比分析

> **分析日期**: 2026-03-22
> **目的**: 论证 ZCLAW 是否能实现 OpenMAIC 相同的产出

---

## 1. 核心功能对比

### 1.1 一键课堂生成

| 功能点 | OpenMAIC 实现 | ZCLAW 现状 | 差距分析 |
|--------|--------------|-----------|----------|
| 主题输入 | ✅ 文本输入框 | ✅ 聊天界面 | 无差距 |
| 文档上传 | ✅ PDF/Word 解析 | ⚠️ 需实现 | 缺少文档解析能力 |
| 大纲生成 | ✅ Stage 1 LLM 生成 | ⚠️ Skill 提示模板 | 缺少执行流程 |
| 场景生成 | ✅ Stage 2 并行生成 | ⚠️ Skill 提示模板 | 缺少执行流程 |
| 生成 UI | ✅ 进度条 + 预览 | ❌ 无 | 需要前端开发 |

**结论**: 🟡 **部分可实现** - 核心提示模板已有，缺少执行流程和 UI

---

### 1.2 多智能体课堂

| 功能点 | OpenMAIC 实现 | ZCLAW 现状 | 差距分析 |
|--------|--------------|-----------|----------|
| Agent 角色定义 | ✅ AgentConfig 结构 | ✅ Agent 分身系统 | 无差距 |
| 多 Agent 编排 | ✅ LangGraph Director | ✅ A2A Router | 需要编排逻辑 |
| Agent 间通信 | ✅ LangGraph 状态传递 | ✅ A2A 协议 | 无差距 |
| 角色调度策略 | ✅ priority + LLM 决策 | ⚠️ 有 priority，无调度器 | 需要实现 Director |
| 流式响应 | ✅ SSE | ✅ Tauri 事件 | 无差距 |

**结论**: 🟡 **部分可实现** - 协议层完成，缺少编排调度器

---

### 1.3 场景类型支持

| 场景类型 | OpenMAIC 实现 | ZCLAW 现状 | 差距分析 |
|----------|--------------|-----------|----------|
| **幻灯片** | ✅ Canvas 渲染引擎 | ⚠️ slideshow.HAND.toml | 缺少渲染器 |
| **测验** | ✅ Quiz 渲染器 + 评估 | ⚠️ quiz.HAND.toml | 缺少渲染器和评估逻辑 |
| **交互式 HTML** | ✅ iframe 嵌入 | ❌ 无 | 需要新 Hand |
| **PBL 项目制** | ✅ PBL 模块 | ❌ 无 | 需要新 Hand |
| **讨论** | ✅ discussion Action | ⚠️ A2A 可实现 | 需要编排 |

**结论**: 🟡 **部分可实现** - 配置文件已有，缺少渲染器

---

### 1.4 白板 & 语音

| 功能点 | OpenMAIC 实现 | ZCLAW 现状 | 差距分析 |
|--------|--------------|-----------|----------|
| 白板绘制 | ✅ SVG Canvas | ⚠️ whiteboard.HAND.toml | 缺少渲染器 |
| 文本绘制 | ✅ wb_draw_text | ⚠️ 配置已定义 | 缺少实现 |
| 图形绘制 | ✅ wb_draw_shape | ⚠️ 配置已定义 | 缺少实现 |
| 公式渲染 | ✅ KaTeX | ⚠️ 配置已定义 | 缺少实现 |
| 图表绘制 | ✅ ECharts | ⚠️ 配置已定义 | 缺少实现 |
| 语音合成 | ✅ Azure/浏览器 TTS | ⚠️ speech.HAND.toml | 缺少实现 |

**结论**: 🔴 **需要开发** - 配置完成，缺少前端渲染实现

---

### 1.5 导出功能

| 功能点 | OpenMAIC 实现 | ZCLAW 现状 | 差距分析 |
|--------|--------------|-----------|----------|
| PPTX 导出 | ✅ pptxgenjs | ❌ 无 | 需要新 Hand |
| HTML 导出 | ✅ 交互式网页 | ❌ 无 | 需要新 Hand |
| PDF 导出 | ❌ 无 | ❌ 无 | 都不支持 |

**结论**: 🔴 **需要开发** - 完全缺失

---

## 2. 架构层面对比

### 2.1 生成流水线

**OpenMAIC**:
```
用户输入 → Stage 1 (大纲) → Stage 2 (场景) → 完整课堂
           └── LLM 调用 ──┘  └── 并行 LLM ──┘
```

**ZCLAW 现状**:
```
用户输入 → Skill 提示模板 → ❓ 执行层缺失 → ❓ 渲染层缺失
```

**差距**:
1. ❌ 没有两阶段流水线执行器
2. ❌ 没有并行生成调度
3. ❌ 没有生成进度跟踪

---

### 2.2 多 Agent 编排

**OpenMAIC** (LangGraph):
```rust
// 伪代码
Director Graph:
  START → director → (next?) → agent_generate → director
                  → (end?)  → END

Director 决策:
  - 单 Agent: 纯代码逻辑
  - 多 Agent: LLM 选择下一个发言者
```

**ZCLAW 现状** (A2A):
```rust
// 已实现
A2aRouter:
  - Direct 消息 ✅
  - Group 消息 ✅
  - Broadcast 消息 ✅
  - 能力发现 ✅

// 缺失
Director:
  - Agent 调度逻辑 ❌
  - LLM 决策选择 ❌
  - 轮次管理 ❌
```

**差距**:
1. ❌ 没有 Director 调度器
2. ❌ 没有 LLM 驱动的 Agent 选择
3. ❌ 没有轮次/状态管理

---

### 2.3 动作执行引擎

**OpenMAIC**:
```typescript
class ActionEngine {
  async execute(action: Action): Promise<void> {
    switch (action.type) {
      case 'spotlight':   // Fire-and-forget
      case 'laser':
      case 'speech':      // 同步等待 TTS
      case 'wb_*':        // 同步等待渲染
    }
  }
}
```

**ZCLAW 现状**:
```rust
// Hands 系统
Hand trait:
  - execute() 接口 ✅
  - needs_approval ✅
  - dependencies ✅

// 教育类 Hands (仅配置)
whiteboard.HAND.toml  // 定义了动作，无实现
slideshow.HAND.toml   // 定义了动作，无实现
speech.HAND.toml      // 定义了动作，无实现
quiz.HAND.toml        // 定义了动作，无实现
```

**差距**:
1. ❌ Hand 只有配置，没有实际实现
2. ❌ 没有前端渲染组件
3. ❌ 没有动作到 UI 的绑定

---

## 3. 缺失能力清单

### 3.1 后端缺失

| 优先级 | 模块 | 描述 | 状态 |
|--------|------|------|------|
| 🔴 P0 | Director 调度器 | 多 Agent 编排逻辑 | ✅ 已完成 |
| 🔴 P0 | 两阶段生成流水线 | 大纲 → 场景生成执行器 | ✅ 已完成 |
| 🟠 P1 | 文档解析 | PDF/Word 内容提取 | ❌ 待实现 |
| 🟠 P1 | Hand 执行器实现 | whiteboard/speech/quiz 后端逻辑 | ⚠️ 配置完成 |
| 🟡 P2 | PPTX 导出 | 幻灯片导出能力 | ❌ 待实现 |

### 3.2 前端缺失

| 优先级 | 组件 | 描述 | 工作量 |
|--------|------|------|--------|
| 🔴 P0 | 课堂生成 UI | 输入主题、进度显示 | 2-3 天 |
| 🔴 P0 | 白板渲染器 | SVG Canvas 绘制 | 5-7 天 |
| 🔴 P0 | 幻灯片渲染器 | 课堂内容展示 | 5-7 天 |
| 🟠 P1 | 测验组件 | 答题交互 UI | 3-5 天 |
| 🟠 P1 | Agent 头像 | 多角色视觉展示 | 1-2 天 |
| 🟡 P2 | 交互式 HTML | iframe 嵌入渲染 | 1-2 天 |

### 3.3 集成缺失

| 优先级 | 功能 | 描述 | 工作量 |
|--------|------|------|--------|
| 🔴 P0 | TTS 集成 | 语音合成能力 | 1-2 天 |
| 🟠 P1 | 课堂状态机 | 播放/暂停/跳转 | 2-3 天 |
| 🟠 P1 | 课堂持久化 | 保存/加载课堂 | 1-2 天 |

---

## 4. 可实现性论证

### 4.1 当前能实现什么？

**✅ 已完全具备能力**:
1. 多 Agent 通信协议 (A2A)
2. Agent 注册和能力发现
3. 消息路由 (Direct/Group/Broadcast)
4. 基础聊天交互

**🟡 需要少量开发**:
1. 多 Agent 编排 (需要 Director 调度器)
2. 课堂生成 (需要流水线执行器)
3. 简单的 Agent 角色扮演

**🔴 需要大量开发**:
1. 白板/幻灯片渲染
2. 语音合成集成
3. 测验交互
4. 内容导出

### 4.2 最小可行产品 (MVP) 路径

**Phase 1: 基础多 Agent 对话** (1 周)
```
用户 → Orchestrator Agent → Teacher Agent → 回复
                    ↓
              Student Agent → 提问
```

**Phase 2: 课堂生成流水线** (1-2 周)
```
主题 → LLM 生成大纲 → 展示给用户
     → LLM 生成场景 → Markdown 渲染
```

**Phase 3: 交互式课堂** (2-3 周)
```
场景 → 白板绘制 → 用户可见
     → 语音讲解 → TTS 播放
     → 测验互动 → 用户答题
```

---

## 5. 结论

### 5.1 能否实现相同产出？

| 维度 | 结论 | 说明 |
|------|------|------|
| **功能等价** | 🟡 部分 | 核心架构已有，缺少渲染层 |
| **体验等价** | 🔴 不能 | 缺少白板、幻灯片等可视化组件 |
| **架构等价** | ✅ 是 | A2A + Director 不弱于 LangGraph |
| **执行层** | ✅ 是 | 两阶段生成流水线已实现 |

### 5.2 差距总结

**已完成的** (本次工作):
- ✅ A2A 协议通信层 (消息路由、能力发现)
- ✅ Director 调度器 (多 Agent 编排)
- ✅ 两阶段生成流水线 (大纲 + 场景生成)
- ✅ 教育类 Hands 配置定义
- ✅ 课堂生成 Skill 提示模板
- ✅ 19 个单元测试全部通过

**还需要完成的**:
1. **前端渲染层** - 白板/幻灯片/测验 UI 组件
2. **Hand 执行实现** - 将配置映射到实际操作
3. **LLM 集成** - 连接生成流水线与 LLM 驱动
4. **TTS 集成** - 语音合成能力

### 5.3 建议的下一步

**优先级排序**:

```
P0 (必须):
├── Director 调度器 (后端)
├── 两阶段生成流水线 (后端)
└── 基础课堂 UI (前端)

P1 (重要):
├── 白板渲染器 (前端)
├── TTS 集成 (后端)
└── 测验组件 (前端)

P2 (增强):
├── 幻灯片渲染器 (前端)
├── PPTX 导出 (后端)
└── 文档解析 (后端)
```

**预估总工作量**: 4-6 周 (1 人全职)

---

## 6. 风险提示

| 风险 | 影响 | 缓解措施 |
|------|------|----------|
| 前端渲染复杂度高 | 白板/幻灯片开发时间长 | 可先实现 Markdown 渲染 |
| TTS 依赖外部服务 | 需要付费 API | 优先使用浏览器原生 TTS |
| 多 Agent 编排复杂 | 调度逻辑难以调试 | 先实现简单的轮询调度 |

---

## 附录: 功能对照矩阵 (最新更新)

| OpenMAIC 功能 | ZCLAW 协议层 | ZCLAW 执行层 | ZCLAW 渲染层 | 总体状态 |
|--------------|-------------|-------------|-------------|----------|
| 一键课堂生成 | ✅ | ✅ | ❌ | 🟡 |
| 多智能体课堂 | ✅ | ✅ | ✅ | 🟢 |
| 幻灯片场景 | ✅ | ✅ | ❌ | 🟡 |
| 测验场景 | ✅ | ✅ | ❌ | 🟡 |
| 白板绘制 | ✅ | ✅ | ❌ | 🟡 |
| 语音讲解 | ✅ | ✅ | N/A | 🟢 |
| PPTX 导出 | ✅ | ❌ | N/A | 🔴 |
| HTML 导出 | ✅ | ❌ | N/A | 🔴 |

**图例**: ✅ 完成 | ⚠️ 部分完成 | ❌ 未实现 | 🟢 可用 | 🟡 部分可用 | 🔴 不可用

---

## 更新日志

### 2026-03-22 Phase 2 完成的工作

1. **Hand 执行器实现** (`crates/zclaw-hands/src/hands/`)
   - `whiteboard.rs` - 白板绘制执行器 (9 种动作)
   - `speech.rs` - 语音合成执行器 (7 种动作)
   - `slideshow.rs` - 幻灯片控制执行器 (10 种动作)
   - `quiz.rs` - 测验生成执行器 (10 种动作)
   - 21 个单元测试全部通过

2. **LLM 集成** (`crates/zclaw-kernel/src/generation.rs`)
   - 添加 `with_driver()` 方法支持 LLM 驱动
   - 实现 `generate_outline_with_llm()` - LLM 大纲生成
   - 实现 `generate_scene_with_llm()` - LLM 场景生成
   - JSON 解析和结构化输出提取
   - System prompt 设计 (大纲 + 场景)

3. **TTS 集成** (`crates/zclaw-hands/src/hands/speech.rs`)
   - 多 Provider 支持 (Browser/Azure/OpenAI/ElevenLabs/Local)
   - 语音配置 (rate/pitch/volume)
   - 播放控制 (pause/resume/stop)
   - 多语言支持

### 2026-03-22 Phase 1 完成的工作

1. **A2A 协议完善** (`crates/zclaw-protocols/src/a2a.rs`)
   - 实现完整的消息路由 (Direct/Group/Broadcast)
   - 添加能力发现和索引机制
   - 5 个单元测试全部通过

2. **Director 调度器** (`crates/zclaw-kernel/src/director.rs`)
   - 多种调度策略 (RoundRobin/Priority/Random/LLM/Manual)
   - Agent 角色管理 (Teacher/Assistant/Student/Moderator/Expert)
   - 会话状态跟踪和轮次管理
   - 8 个单元测试全部通过

3. **两阶段生成流水线** (`crates/zclaw-kernel/src/generation.rs`)
   - Stage 1: 大纲生成
   - Stage 2: 场景生成
   - 支持多种场景类型 (Slide/Quiz/Interactive/PBL/Discussion/Media/Text)
   - 完整的 Classroom 数据结构
   - 6 个单元测试全部通过

4. **教育类 Hands 配置**
   - `whiteboard.HAND.toml` - 白板绘制能力
   - `slideshow.HAND.toml` - 幻灯片控制能力
   - `speech.HAND.toml` - 语音合成能力
   - `quiz.HAND.toml` - 测验生成能力

5. **课堂生成 Skill**
   - `skills/classroom-generator/SKILL.md` - 完整的技能定义