zclaw_openfang/plans/encapsulated-beaming-clover.md

OpenMAIC 功能借鉴与 ZCLAW 实现计划

Context

用户希望借鉴 OpenMAIC 的多智能体课堂功能，但该项目采用 AGPL-3.0 许可证，直接整合有法律风险。

关键决策: 不整合 OpenMAIC 代码，而是借鉴架构思想，利用 ZCLAW 现有的 workflow、协作、Hands、Skills 等能力实现类似功能。

---

1. AGPL-3.0 风险分析

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

结论: ❌ 不直接整合代码，✅ 仅借鉴架构思想和设计模式

---

2. ZCLAW 现有能力 vs OpenMAIC 功能

2.1 能力对照表

OpenMAIC 功能	ZCLAW 对应	成熟度	差距
多 Agent 编排 (Director Graph)	A2A 协议 + Kernel Registry	框架完成	需实现实际通信
Agent 角色配置	Skills + Agent 分身	完成	需扩展角色定义
动作执行引擎 (28+ Actions)	Hands 能力系统	完成	需补充教育类动作
工作流编排	Trigger + EventBus	基础完成	缺 DAG 编排
状态管理	MemoryStore (SQLite)	完成	无需改动
多模态支持	依赖 LLM Provider	完成	需补充 TTS/白板
外部集成	Channels (Telegram/Discord/Slack)	框架完成	无需改动

2.2 ZCLAW 已有的核心能力

┌─────────────────────────────────────────────────────────────┐
│                    ZCLAW 现有能力架构                        │
├─────────────────────────────────────────────────────────────┤
│  A2A 协议        │ Direct/Group/Broadcast 路由              │
│  EventBus        │ 发布订阅，1000 条消息容量                 │
│  Trigger 系统    │ Schedule/Event/Webhook/FileSystem/Manual │
│  Hands 系统      │ 7 个自主能力 (browser/researcher/...)    │
│  Skills 系统     │ 12+ 技能 (code-review/translation/...)   │
│  Registry        │ Agent 注册、状态管理、持久化恢复         │
│  Channels        │ Telegram/Discord/Slack/Console 适配器    │
└─────────────────────────────────────────────────────────────┘

---

3. 实现方案：基于 ZCLAW 现有能力

3.1 多 Agent 协作（替代 Director Graph）

利用: A2A 协议 + Trigger 系统

设计方案:

用户请求 → Orchestrator Agent
                ↓
         Trigger 触发 (Event 模式)
                ↓
    ┌──────────┼──────────┐
    ↓          ↓          ↓
 Agent A    Agent B    Agent C
 (老师)     (助教)     (学生)
    ↓          ↓          ↓
    └──────────┼──────────┘
               ↓
         结果聚合 → 响应用户

实现要点:

1. 使用 A2A Group 路由实现组播
2. 使用 EventBus 实现异步消息传递
3. 定义 Agent 角色 (teacher/assistant/student)

3.2 动作执行引擎（替代 OpenMAIC Actions）

利用: Hands 能力系统

新增 Hand 类型:

Hand	功能	对应 OpenMAIC Action
whiteboard	白板绘制	wb_draw_text/shape/chart
slideshow	幻灯片控制	spotlight/laser/next_slide
speech	语音合成	speech (TTS)
quiz	测验生成	quiz_generate/grade

扩展 Hand 配置:

# hands/whiteboard.HAND.toml
[hand]
id = "whiteboard"
name = "白板能力"
description = "绘制图表、公式、文本"
needs_approval = false

[capabilities]
actions = ["draw_text", "draw_shape", "draw_chart", "draw_latex", "clear"]

3.3 工作流编排（替代 LangGraph）

利用: Trigger + EventBus + Skills

设计方案:

// 工作流定义
struct Workflow {
    id: String,
    stages: Vec<WorkflowStage>,
    transitions: Vec<Transition>,
}

struct WorkflowStage {
    id: String,
    agent_role: String,      // 执行的 Agent 角色
    skill: Option<String>,   // 使用的 Skill
    hand: Option<String>,    // 使用的 Hand
}

struct Transition {
    from: String,
    to: String,
    condition: Option<String>,  // 条件表达式
}

触发方式:

• Schedule - 定时课堂
• Event - 用户提问触发
• Manual - 手动开始

3.4 场景生成（替代两阶段生成）

利用: Skills 系统 + LLM

新增 Skill:

# skills/classroom-generator/SKILL.md
---
name: classroom-generator
description: 根据主题生成互动课堂
mode: prompt-only
---

## 输入
- topic: 课堂主题
- document: 可选参考文档
- style: 教学风格 (lecture/discussion/pbl)

## 输出
- 大纲 JSON
- 场景列表 (每个场景包含内容 + 动作)

## 提示模板
...

---

4. 实施路径

Phase 1: 完善 A2A 通信 ✅ (已完成)

实现内容:

• 重写 crates/zclaw-protocols/src/a2a.rs
• 实现 A2aRouter 消息路由器
• 支持 Direct/Group/Broadcast 三种路由模式
• 实现能力发现和索引机制
• 添加 5 个单元测试（全部通过）

Phase 2: 扩展 Hands 能力 ✅ (已完成)

新增文件:

• hands/whiteboard.HAND.toml - 白板绘制（8 种动作）
• hands/slideshow.HAND.toml - 幻灯片控制（8 种动作）
• hands/speech.HAND.toml - 语音合成（6 种动作）
• hands/quiz.HAND.toml - 测验系统（8 种动作）

Phase 3: 创建课堂生成 Skill ✅ (已完成)

新增文件:

• skills/classroom-generator/SKILL.md - 课堂生成技能

Phase 4: 工作流编排增强 📋 (后续迭代)

当前 Trigger + EventBus 已提供基础能力，DAG 编排可在后续迭代中实现。

---

5. 关键文件

需要修改的文件

文件	改动
crates/zclaw-protocols/src/a2a.rs	实现消息路由
crates/zclaw-kernel/src/workflow.rs	新增工作流引擎
crates/zclaw-hands/src/hand.rs	扩展 Hand 类型

需要新增的文件

文件	用途
hands/whiteboard.HAND.toml	白板能力配置
hands/slideshow.HAND.toml	幻灯片能力配置
hands/speech.HAND.toml	语音能力配置
hands/quiz.HAND.toml	测验能力配置
skills/classroom-generator/SKILL.md	课堂生成技能

---

6. 验证方式

1. A2A 通信测试

   cargo test -p zclaw-protocols a2a
   

2. Hand 调用测试

   # 启动桌面端，测试白板 Hand
   pnpm desktop
   

3. Skill 生成测试

   # 在聊天中输入: "生成一个关于 Rust 所有权的课堂"
   

4. 工作流执行测试

   # 定义工作流并手动触发
   

---

7. 风险与缓解

风险	缓解措施
A2A 实现复杂度高	先实现 Direct 模式，再扩展 Group/Broadcast
TTS 依赖外部服务	支持多种 TTS Provider，优先浏览器原生
白板渲染复杂	先实现基础功能，渐进增强

---

8. 总结

策略: ❌ 不整合 AGPL-3.0 代码 → ✅ 借鉴架构 + 利用现有能力

优势:

• 无许可证风险
• 复用 ZCLAW 成熟基础设施
• 保持代码库一致性
• 更好的桌面端适配

核心价值: 将 OpenMAIC 的多智能体协作思想融入 ZCLAW，而非复制代码。