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>
This commit is contained in:
iven
265
plans/encapsulated-beaming-clover.md
Normal file
265
plans/encapsulated-beaming-clover.md
Normal file
@@ -0,0 +1,265 @@
|
||||
# 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，而非复制代码。
|
||||
Reference in New Issue
Block a user