release(v0.2.0): streaming, MCP protocol, Browser Hand, security enhancements

## Major Features ### Streaming Response System - Implement LlmDriver trait with `stream()` method returning async Stream - Add SSE parsing for Anthropic and OpenAI API streaming - Integrate Tauri event system for frontend streaming (`stream:chunk` events) - Add StreamChunk types: Delta, ToolStart, ToolEnd, Complete, Error ### MCP Protocol Implementation - Add MCP JSON-RPC 2.0 types (mcp_types.rs) - Implement stdio-based MCP transport (mcp_transport.rs) - Support tool discovery, execution, and resource operations ### Browser Hand Implementation - Complete browser automation with Playwright-style actions - Support Navigate, Click, Type, Scrape, Screenshot, Wait actions - Add educational Hands: Whiteboard, Slideshow, Speech, Quiz ### Security Enhancements - Implement command whitelist/blacklist for shell_exec tool - Add SSRF protection with private IP blocking - Create security.toml configuration file ## Test Improvements - Fix test import paths (security-utils, setup) - Fix vi.mock hoisting issues with vi.hoisted() - Update test expectations for validateUrl and sanitizeFilename - Add getUnsupportedLocalGatewayStatus mock ## Documentation Updates - Update architecture documentation - Improve configuration reference - Add quick-start guide updates Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
2026-03-24 03:24:24 +08:00
parent e49ba4460b
commit 3ff08faa56
78 changed files with 29575 additions and 1682 deletions
--- a/docs/knowledge-base/configuration.md
+++ b/docs/knowledge-base/configuration.md
@@ -1,302 +1,230 @@
-# OpenFang 配置指南
+# ZCLAW 模型配置指南

-> 记录 OpenFang 配置文件位置、格式和最佳实践。
+> 讌**重要变更**: ZCLAW 现在使用 UI 配置模型，不再需要编辑配置文件。

 ---

-## 1. 配置文件位置
+## 1. 配置方式
+
+### 1.1 UI 配置（推荐）
+
+在 ZCLAW 桌面应用中直接配置模型：
+
+1. 打开应用，点击设置图标 ⚙️
+2. 进入"模型与 API"页面
+3. 点击"添加自定义模型"
+4. 填写配置信息
+5. 点击"设为默认"
+
+### 1.2 配置存储位置
+
+配置保存在浏览器的 localStorage 中：

 ```
-~/.openfang/
-├── config.toml      # 主配置文件（启动时读取）
-├── .env             # API Key 环境变量
-├── secrets.env      # 敏感信息（可选）
-├── daemon.json      # 守护进程状态
-└── data/
-    └── openfang.db  # SQLite 数据库（持久化配置）
+localStorage Key: zclaw-custom-models
 ```

 ---

-## 2. 主配置文件 (config.toml)
+## 2. 支持的 Provider

-### 智谱 (Zhipu) 配置
+### 2.1 国内 Provider

-```toml
-[default_model]
-provider = "zhipu"
-model = "glm-4-flash"
-api_key_env = "ZHIPU_API_KEY"
+| Provider | 名称 | Base URL | 说明 |
+|----------|------|----------|------|
+| kimi | Kimi Code | `https://api.kimi.com/coding/v1` | Kimi 编程助手 |
+| qwen | 百炼/通义千问 | `https://dashscope.aliyuncs.com/compatible-mode/v1` | 阿里云百炼 |
+| deepseek | DeepSeek | `https://api.deepseek.com/v1` | DeepSeek |
+| zhipu | 智谱 GLM | `https://open.bigmodel.cn/api/paas/v4` | 智谱 AI |
+| minimax | MiniMax | `https://api.minimax.chat/v1` | MiniMax |

-[kernel]
-data_dir = "C:\\Users\\szend\\.openfang\\data"
+### 2.2 国际 Provider

-[memory]
-decay_rate = 0.05
-```
+| Provider | 名称 | Base URL | 说明 |
+|----------|------|----------|------|
+| openai | OpenAI | `https://api.openai.com/v1` | OpenAI GPT |
+| anthropic | Anthropic | `https://api.anthropic.com` | Anthropic Claude |
+| gemini | Google Gemini | `https://generativelanguage.googleapis.com` | Google Gemini |

-### 百炼 (Bailian) 配置
+### 2.3 本地 Provider

-```toml
-[default_model]
-provider = "bailian"
-model = "qwen3.5-plus"
-api_key_env = "BAILIAN_API_KEY"
-
-[kernel]
-data_dir = "C:\\Users\\szend\\.openfang\\data"
-
-[memory]
-decay_rate = 0.05
-```
-
-### 配置项说明
-
-| 配置项 | 说明 | 示例值 |
-|--------|------|--------|
-| `default_model.provider` | 默认 LLM 提供商 | `zhipu`, `bailian`, `gemini` |
-| `default_model.model` | 默认模型名称 | `glm-4-flash`, `qwen3.5-plus` |
-| `default_model.api_key_env` | API Key 环境变量名 | `ZHIPU_API_KEY` |
-| `kernel.data_dir` | 数据目录 | `~/.openfang/data` |
-| `memory.decay_rate` | 记忆衰减率 | `0.05` |
+| Provider | 名称 | Base URL | 说明 |
+|----------|------|----------|------|
+| local | Ollama | `http://localhost:11434/v1` | Ollama 本地 |
+| local | LM Studio | `http://localhost:1234/v1` | LM Studio 本地 |

 ---

-## 3. API Key 配置
+## 3. UI 配置步骤

-### 方式 1: .env 文件（推荐）
+### 3.1 添加模型

-```bash
-# ~/.openfang/.env
-ZHIPU_API_KEY=sk-sp-xxxxx
-BAILIAN_API_KEY=sk-sp-xxxxx
-GEMINI_API_KEY=your_gemini_key
-DEEPSEEK_API_KEY=your_deepseek_key
-OPENAI_API_KEY=your_openai_key
-GROQ_API_KEY=your_groq_key
-```
+在"模型与 API"页面：

-### 方式 2: secrets.env 文件
+1. **服务商**: 从下拉列表选择 Provider
+2. **模型 ID**: 填写模型标识符（如 `kimi-k2-turbo`、`qwen-plus`）
+3. **显示名称**: 可选，用于界面显示
+4. **API Key**: 填写你的 API 密钥
+5. **API 协议**: 选择 OpenAI（大多数 Provider）或 Anthropic
+6. **Base URL**: 可选，使用自定义 API 端点

-```bash
-# ~/.openfang/secrets.env
-ZHIPU_API_KEY=sk-sp-xxxxx
-BAILIAN_API_KEY=sk-sp-xxxxx
-```
+### 3.2 设为默认

-### 方式 3: 通过 API 设置
+点击模型列表中的"设为默认"按钮。

-```bash
-# 设置智谱密钥
-curl -X POST http://127.0.0.1:50051/api/providers/zhipu/key \
-  -H "Content-Type: application/json" \
-  -d '{"key":"your-zhipu-api-key"}'
+### 3.3 修改配置

-# 设置百炼密钥
-curl -X POST http://127.0.0.1:50051/api/providers/bailian/key \
-  -H "Content-Type: application/json" \
-  -d '{"key":"your-bailian-api-key"}'
-```
-
-### 方式 4: 启动时指定环境变量
-
-```bash
-# Windows PowerShell
-$env:ZHIPU_API_KEY = "your_key"
-./openfang.exe start
-
-# Linux/macOS
-ZHIPU_API_KEY=sk-sp-xxx ./openfang start
-```
+点击"编辑"按钮修改已有配置。

 ---

-## 4. 支持的 Provider
+## 4. 可用模型

-### 4.1 国内 Provider
+### 4.1 Kimi Code

-| Provider | 环境变量 | Base URL | 说明 |
-|----------|----------|----------|------|
-| zhipu | `ZHIPU_API_KEY` | `https://open.bigmodel.cn/api/paas/v4` | 智谱 GLM |
-| zhipu_coding | `ZHIPU_API_KEY` | `https://open.bigmodel.cn/api/coding/paas/v4` | 智谱 CodeGeeX |
-| bailian | `BAILIAN_API_KEY` | `https://coding.dashscope.aliyuncs.com/v1` | 百炼 Coding Plan |
-| qwen | `DASHSCOPE_API_KEY` | `https://dashscope.aliyuncs.com/compatible-mode/v1` | 通义千问 |
-| volcengine | `VOLCENGINE_API_KEY` | `https://ark.cn-beijing.volces.com/api/v3` | 火山引擎 Doubao |
-| moonshot | `MOONSHOT_API_KEY` | `https://api.moonshot.ai/v1` | Moonshot Kimi |
-| deepseek | `DEEPSEEK_API_KEY` | `https://api.deepseek.com/v1` | DeepSeek |
+| 模型 ID | 说明 | 适用场景 |
+|---------|------|----------|
+| kimi-k2-turbo | 快速模型 | 日常对话、快速响应 |
+| kimi-k2-pro | 高级模型 | 复杂推理、深度分析 |

-### 4.2 国际 Provider
+### 4.2 百炼/通义千问 (Qwen)

-| Provider | 环境变量 | Base URL | 说明 |
-|----------|----------|----------|------|
-| openai | `OPENAI_API_KEY` | `https://api.openai.com/v1` | OpenAI GPT |
-| anthropic | `ANTHROPIC_API_KEY` | `https://api.anthropic.com` | Anthropic Claude |
-| gemini | `GEMINI_API_KEY` | `https://generativelanguage.googleapis.com` | Google Gemini |
-| groq | `GROQ_API_KEY` | `https://api.groq.com/openai/v1` | Groq |
-| mistral | `MISTRAL_API_KEY` | `https://api.mistral.ai/v1` | Mistral AI |
-| xai | `XAI_API_KEY` | `https://api.x.ai/v1` | xAI Grok |
+| 模型 ID | 说明 | 适用场景 |
+|---------|------|----------|
+| qwen-turbo | 快速模型 | 日常对话 |
+| qwen-plus | 通用模型 | 复杂任务 |
+| qwen-max | 高级模型 | 深度分析 |
+| qwen-coder-plus | 编码专家 | 代码生成 |

-### 4.3 本地 Provider
+### 4.3 DeepSeek

-| Provider | 环境变量 | Base URL | 说明 |
-|----------|----------|----------|------|
-| ollama | - | `http://localhost:11434/v1` | Ollama 本地 |
-| vllm | - | `http://localhost:8000/v1` | vLLM 本地 |
-| lmstudio | - | `http://localhost:1234/v1` | LM Studio 本地 |
+| 模型 ID | 说明 | 适用场景 |
+|---------|------|----------|
+| deepseek-chat | 通用对话 | 日常对话 |
+| deepseek-coder | 编码专家 | 代码生成 |

---
-
-## 5. 可用模型
-
-### 智谱 (Zhipu)
+### 4.4 智谱 GLM (Zhipu)

 | 模型 ID | 说明 | 适用场景 |
 |---------|------|----------|
 | glm-4-flash | 快速模型 | 日常对话、快速响应 |
-| glm-4-plus | 高级模型 | 复杂推理、深度分析 |
-| glm-4 | 标准模型 | 通用场景 |
-| glm-4-air | 轻量模型 | 简单任务 |
-
-### 百炼 (Bailian)
-
-| 模型 ID | 说明 | 适用场景 |
-|---------|------|----------|
-| qwen3.5-plus | 通用对话 | 日常对话 |
-| qwen3-coder-next | 编码专家 | 代码生成 |
-| glm-5-bailian | GLM-5 | 通用场景 |
-| minimax-m2.5-bailian | 支持视觉 | 多模态任务 |
-| kimi-k2.5-bailian | Kimi K2.5 | 长文本处理 |
-
-### 其他推荐模型
-
-| Provider | 模型 ID | 适用场景 |
-|----------|---------|----------|
-| gemini | gemini-2.5-flash | 开发任务 |
-| deepseek | deepseek-chat | 快速响应 |
-| groq | llama-3.1-70b | 开源模型 |
+| glm-4-plus | 高级模型 | 复杂推理 |
+| glm-4-airx | 轻量模型 | 简单任务 |

 ---

-## 6. 快速切换 Provider
+## 5. 配置示例

-### 方法 A: 修改 config.toml
+### 5.1 Kimi Code 配置

-```toml
-# 切换到智谱
-[default_model]
-provider = "zhipu"
-model = "glm-4-flash"
-api_key_env = "ZHIPU_API_KEY"
-
-# 切换到百炼
-[default_model]
-provider = "bailian"
-model = "qwen3.5-plus"
-api_key_env = "BAILIAN_API_KEY"
+```
+服务商: kimi
+模型 ID: kimi-k2-turbo
+显示名称: Kimi K2 Turbo
+API Key: 你的 Kimi API Key
+API 协议: OpenAI
+Base URL: https://api.kimi.com/coding/v1
 ```

-**重要**: 修改后必须完全重启 OpenFang！
+### 5.2 百炼 Qwen 配置

-### 方法 B: 创建不同配置的 Agent
+```
+服务商: qwen
+模型 ID: qwen-plus
+显示名称: 通义千问 Plus
+API Key: 你的百炼 API Key
+API 协议: OpenAI
+Base URL: https://dashscope.aliyuncs.com/compatible-mode/v1
+```

-```bash
-# 创建使用智谱的 Agent
-curl -X POST http://127.0.0.1:50051/api/agents \
-  -H "Content-Type: application/json" \
-  -d '{"manifest_toml": "name = \"Zhipu Agent\"\nmodel_provider = \"zhipu\"\nmodel_name = \"glm-4-flash\""}'
+### 5.3 DeepSeek 配置

-# 创建使用百炼的 Agent
-curl -X POST http://127.0.0.1:50051/api/agents \
-  -H "Content-Type: application/json" \
-  -d '{"manifest_toml": "name = \"Bailian Agent\"\nmodel_provider = \"bailian\"\nmodel_name = \"qwen3.5-plus\""}'
+```
+服务商: deepseek
+模型 ID: deepseek-chat
+显示名称: DeepSeek Chat
+API Key: 你的 DeepSeek API Key
+API 协议: OpenAI
+Base URL: https://api.deepseek.com/v1
+```
+
+### 5.4 本地 Ollama 配置
+
+```
+服务商: local
+模型 ID: llama3.2
+显示名称: Llama 3.2 Local
+API Key: (留空)
+API 协议: OpenAI
+Base URL: http://localhost:11434/v1
 ```

 ---

-## 7. 配置验证
+## 6. 常见问题

-### 检查当前配置
+### Q: 如何获取 API Key？

-```bash
-# 检查 API 返回的配置
-curl -s http://127.0.0.1:50051/api/config
+| Provider | 获取方式 |
+|----------|----------|
+| Kimi | 访问 [kimi.com/code](https://kimi.com/code) 注册 |
+| Qwen | 访问 [百炼平台](https://bailian.console.aliyun.com/) |
+| DeepSeek | 访问 [platform.deepseek.com](https://platform.deepseek.com/) |
+| Zhipu | 访问 [open.bigmodel.cn](https://open.bigmodel.cn/) |
+| OpenAI | 访问 [platform.openai.com](https://platform.openai.com/) |

-# 检查状态
-curl -s http://127.0.0.1:50051/api/status | grep -E "default_provider|default_model"
+### Q: API Key 存储在哪里？

-# 检查所有 Provider 状态
-curl -s http://127.0.0.1:50051/api/providers | grep -E "id|auth_status"
-```
+API Key 存储在浏览器的 localStorage 中，不会上传到服务器。

-### 检查 Agent 配置
+### Q: 如何切换模型？

-```bash
-# 列出所有 Agent 及其 Provider
-curl -s http://127.0.0.1:50051/api/agents | grep -E "name|model_provider|ready"
-```
+在"模型与 API"页面，点击模型旁边的"设为默认"按钮。

-### 测试聊天
+### Q: 配置后没有生效？

-```bash
-# 测试 Agent 是否能正常响应
-curl -X POST "http://127.0.0.1:50051/api/agents/{agentId}/message" \
-  -H "Content-Type: application/json" \
-  -d '{"message":"Hello"}'
-```
+1. 确保点击了"设为默认"
+2. 检查 API Key 是否正确
+3. 重新连接（点击"重新连接"按钮）
+
+### Q: 显示"请先在模型与 API 设置页面配置模型"？
+
+你需要先添加至少一个自定义模型并设为默认，才能开始对话。

 ---

-## 8. 重要注意事项
+## 7. 架构说明

-### 8.1 配置热重载限制
+### 7.1 数据流

-**关键**: OpenFang 将配置持久化在 SQLite 数据库中，`config.toml` 只在启动时读取。
-
- `/api/config/reload` **不会**更新已持久化的默认模型配置
- 修改 `config.toml` 后必须**完全重启 OpenFang**
-
-```bash
-# 正确的重启方式
-curl -X POST http://127.0.0.1:50051/api/shutdown
-# 然后手动启动
-./openfang.exe start
+```
+UI 配置 (localStorage)
+        │
+        ▼
+connectionStore.getDefaultModelConfig()
+        │
+        ▼
+KernelClient.setConfig()
+        │
+        ▼
+Tauri 命令: kernel_init()
+        │
+        ▼
+zclaw-kernel::Kernel::boot()
+        │
+        ▼
+LLM Driver (Kimi/Qwen/DeepSeek/...)
 ```

-### 8.2 Agent 创建时的 Provider
+### 7.2 关键文件

-如果创建 Agent 时没有指定 Provider，OpenFang 会使用数据库中存储的默认配置，而不是 `config.toml` 中的配置。
-
-### 8.3 API Key 验证
-
-确保 API Key 格式正确：
- 智谱: `sk-sp-xxxxx` 或 `xxxxx.xxxxx.xxxxx`
- 百炼: `sk-xxxxx`
-
---
-
-## 9. 常见问题
-
-### Q: 修改 config.toml 后配置没有生效？
-
-**A**: 必须完全重启 OpenFang，热重载不会更新持久化配置。
-
-### Q: Agent 显示 ready: false？
-
-**A**: 检查 Agent 使用的 Provider 是否配置了 API Key：
-```bash
-curl -s http://127.0.0.1:50051/api/agents | grep -E "auth_status|ready"
-```
-
-### Q: 如何查看所有可用的 Provider？
-
-**A**:
-```bash
-curl -s http://127.0.0.1:50051/api/providers
-```
-
-### Q: 如何在不重启的情况下切换 Agent？
-
-**A**: 前端可以通过选择不同 Provider 的 Agent 来切换，无需重启。
+| 文件 | 职责 |
+|------|------|
+| `desktop/src/components/Settings/ModelsAPI.tsx` | UI 配置组件 |
+| `desktop/src/store/connectionStore.ts` | 读取配置并传递给 Kernel |
+| `desktop/src/lib/kernel-client.ts` | Tauri 命令客户端 |
+| `desktop/src-tauri/src/kernel_commands.rs` | Rust 命令实现 |
+| `crates/zclaw-kernel/src/config.rs` | Kernel 配置结构 |

 ---

@@ -304,4 +232,5 @@ curl -s http://127.0.0.1:50051/api/providers

 | 日期 | 变更 |
 |------|------|
-| 2026-03-17 | 初始版本，记录配置热重载限制 |
+| 2026-03-22 | 更新为 UI 配置方式，移除 TOML 文件配置 |
+| 2026-03-17 | 初始版本 |
--- a/docs/knowledge-base/openmaic-analysis.md
+++ b/docs/knowledge-base/openmaic-analysis.md
@@ -0,0 +1,558 @@
+# 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、条件分支）
--- a/docs/knowledge-base/openmaic-zclaw-comparison.md
+++ b/docs/knowledge-base/openmaic-zclaw-comparison.md
@@ -0,0 +1,384 @@
+# 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` - 完整的技能定义
--- a/docs/knowledge-base/zclaw-technical-reference.md
+++ b/docs/knowledge-base/zclaw-technical-reference.md