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

OpenMAIC vs ZCLAW 功能对比分析

分析日期: 2026-03-22 (初版) / 2026-03-26 (深度分析) 目的: 论证 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):

// 伪代码
Director Graph:
  START → director → (next?) → agent_generate → director
                  → (end?)  → END

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

ZCLAW 现状 (A2A):

// 已实现
A2aRouter:
  - Direct 消息 ✅
  - Group 消息 ✅
  - Broadcast 消息 ✅
  - 能力发现 ✅

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

差距:

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

---

2.3 动作执行引擎

OpenMAIC:

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

ZCLAW 现状:

// 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 - 完整的技能定义

---

7. 深度架构对比 (2026-03-26 补充)

7.1 流式响应处理对比

维度	OpenMAIC	ZCLAW
传输协议	SSE (Server-Sent Events)	gRPC Stream / Tauri Events
节奏控制	StreamBuffer (中间层)	无统一控制
打字机效果	单层 (StreamBuffer tick)	可能双层 (LLM + 前端)
暂停/恢复	StreamBuffer.pause/resume	需实现
刷新	StreamBuffer.flush	需实现

OpenMAIC StreamBuffer 优势:

• 统一的内容展示节奏控制
• 避免 LLM 流式输出和前端打字机的双重效果
• 精确控制 Action 触发时机
• 支持 Roundtable 实时语音显示

7.2 多 Agent 编排对比

维度	OpenMAIC	ZCLAW
编排引擎	LangGraph StateGraph	自定义 Director
单 Agent 优化	纯代码逻辑，无 LLM	需实现
多 Agent 决策	LLM + 快速路径	A2A Router
状态传递	OrchestratorState Annotation	DirectorState struct
轮次管理	turnCount + maxTurns	需实现

OpenMAIC Director 策略:

// 单 Agent: 纯代码逻辑
if (isSingleAgent) {
  if (turnCount === 0) return { currentAgentId: agentId };
  return { cueUser: true };
}

// 多 Agent: 快速路径
if (turnCount === 0 && triggerAgentId) {
  return { currentAgentId: triggerAgentId };
}

// 多 Agent: LLM 决策
const decision = await llm.decide(agents, context);
return { currentAgentId: decision.nextAgentId };

7.3 工具/动作执行对比

维度	OpenMAIC	ZCLAW
执行引擎	ActionEngine (统一类)	Hands (Trait)
动作数量	28+ 种	8 个 Hand
执行模式	Fire-and-forget / Synchronous	needs_approval
前置条件	自动处理 (如白板)	dependencies
动画协调	delay 等待	无

OpenMAIC Action 分类:

// Fire-and-forget: 立即返回
case 'spotlight':
case 'laser':
  executeImmediate(action);
  return;

// Synchronous: 等待完成
case 'speech':
  await playTTS(action);
  return;
case 'wb_draw_text':
  await drawOnWhiteboard(action);
  await delay(800);  // 等待动画
  return;

7.4 状态管理对比

维度	OpenMAIC	ZCLAW
后端状态	无状态	SQLite Session
客户端状态	Zustand + IndexedDB	Tauri 前端
持久化	persist middleware	需实现
版本迁移	migrate 函数	需实现
服务器配置合并	fetchServerProviders	需实现

OpenMAIC 无状态设计:

• 所有状态由客户端维护
• 每次请求携带完整上下文
• 后端只做生成，不存储会话
• 便于水平扩展

7.5 提示词管理对比

维度	OpenMAIC	ZCLAW
Agent 提示词	persona 字段	SKILL.md
系统提示词构建	prompt-builder.ts	需实现
上下文注入	结构化 (scene, whiteboard, etc.)	需实现
Director 提示词	director-prompt.ts	无

7.6 媒体生成对比

维度	OpenMAIC	ZCLAW
图像生成	多 Provider (Seedream, Qwen, etc.)	无
视频生成	多 Provider (Seedance, Kling, etc.)	无
TTS	多 Provider (OpenAI, Azure, GLM, etc.)	speech.HAND.toml
ASR	多 Provider (OpenAI, Qwen, etc.)	无

---

8. ZCLAW 优化建议 (基于深度分析)

8.1 优先级 P0: StreamBuffer 实现

目标: 统一内容展示节奏控制

实现步骤:

1. 创建 StreamBuffer 类
2. 定义缓冲项类型
3. 实现 tick 循环
4. 连接到 Tauri 事件系统

预期效果:

• 消除双重打字机效果
• 支持暂停/恢复/刷新
• 精确控制 Action 触发

8.2 优先级 P1: Director 快速路径

目标: 优化单 Agent 场景性能

实现步骤:

1. 检测 Agent 数量
2. 单 Agent 场景跳过 LLM 决策
3. 触发 Agent 场景直接调度
4. 仅复杂场景使用 LLM

预期效果:

• 减少不必要的 LLM 调用
• 降低延迟
• 节省成本

8.3 优先级 P1: Action 引擎增强

目标: 统一动作执行接口

实现步骤:

1. 创建 ActionEngine 类
2. 区分 Fire-and-forget / Synchronous
3. 实现自动前置条件处理
4. 添加动画协调

预期效果:

• 统一的执行接口
• 更好的动画协调
• 更清晰的动作分类

8.4 优先级 P2: 设置版本迁移

目标: 支持配置升级不丢失

实现步骤:

1. 实现 Zustand persist migrate
2. 实现 merge 函数
3. 测试版本升级场景

预期效果:

• 配置升级无损
• 新默认值自动合并

---

9. 代码参考: StreamBuffer 核心实现

// lib/buffer/stream-buffer.ts (OpenMAIC)

export class StreamBuffer {
  private items: BufferItem[] = [];
  private readIndex = 0;
  private charCursor = 0;
  private _paused = false;
  private timer: ReturnType<typeof setInterval> | null = null;

  constructor(
    private cb: StreamBufferCallbacks,
    private options?: StreamBufferOptions,
  ) {
    this.tickMs = options?.tickMs ?? 30;
    this.charsPerTick = options?.charsPerTick ?? 1;
  }

  start(): void {
    if (this.timer) return;
    this.timer = setInterval(() => this.tick(), this.tickMs);
  }

  pause(): void { this._paused = true; }
  resume(): void { this._paused = false; }

  flush(): void {
    while (this.readIndex < this.items.length) {
      // 立即处理所有项
    }
  }

  private tick(): void {
    if (this._paused) return;

    const item = this.items[this.readIndex];
    if (!item) return;

    if (item.kind === 'text') {
      this.charCursor = Math.min(this.charCursor + this.charsPerTick, item.text.length);
      const revealed = item.text.slice(0, this.charCursor);
      this.cb.onTextReveal(item.messageId, item.partId, revealed, ...);

      if (this.charCursor >= item.text.length && item.sealed) {
        this.readIndex++;
        this.charCursor = 0;
      }
    }
    // ... 其他类型
  }
}

---

10. 总结

10.1 OpenMAIC 的核心优势

1. StreamBuffer - 统一的内容展示节奏控制
2. Director 优化 - 单 Agent 场景无 LLM 调用
3. 无状态设计 - 易于水平扩展
4. Action 引擎 - 统一的执行接口
5. 多 Provider - 灵活的服务集成

10.2 ZCLAW 可直接借鉴

功能	复杂度	价值
StreamBuffer	中	高
Director 快速路径	低	高
设置迁移	低	中
Action 模式分类	低	中

10.3 ZCLAW 需要自研

功能	原因
Tauri 事件集成	OpenMAIC 是 Web
SQLite 状态管理	OpenMAIC 无状态
Hands 执行实现	OpenMAIC 有完整实现