zclaw_openfang/plans/encapsulated-beaming-clover.md

# OpenMAIC 功能借鉴与 ZCLAW 实现计划

## Context

用户希望借鉴 [OpenMAIC](https://github.com/THU-MAIC/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 配置**:
```toml
# 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

**设计方案**:
```rust
// 工作流定义
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**:
```markdown
# 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 通信测试**
   ```bash
   cargo test -p zclaw-protocols a2a
   ```

2. **Hand 调用测试**
   ```bash
   # 启动桌面端，测试白板 Hand
   pnpm desktop
   ```

3. **Skill 生成测试**
   ```bash
   # 在聊天中输入: "生成一个关于 Rust 所有权的课堂"
   ```

4. **工作流执行测试**
   ```bash
   # 定义工作流并手动触发
   ```

---

## 7. 风险与缓解

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

---

## 8. 总结

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

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

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