# ZCLAW v0.2.0 发布计划设计文档

> 创建日期: 2026-03-24
> 状态: 待审核
> 目标发布: 2026-05 中旬 (6-8 周)

---

## 一、发布目标与范围

### 1.1 核心定位

面向中文用户的 AI Agent 桌面客户端，提供流畅的对话体验和基础自动化能力。

### 1.2 发布范围

| 类别 | 功能 | 状态 |
|------|------|------|
| **必须完成** | 流式响应 | 完整实现 |
| **必须完成** | MCP 协议 | 完整实现（全规范） |
| **必须完成** | Browser Hand | playwright-rust 实现 |
| **必须完成** | 工具安全验证 | 基础白名单 |
| **必须完成** | 核心对话流程 | 无阻塞 |
| **推迟** | Ollama/Local 驱动 | v0.3.0 |
| **推迟** | Gemini 驱动 | v0.3.0 |
| **推迟** | CI/CD | v0.3.0 |

### 1.3 发布形式

- **平台**: Windows 安装包
- **签名**: 自签名证书（用户需手动信任）
- **分发**: GitHub Releases

---

## 二、时间线与里程碑

### 2.1 8 周发布计划

```
Week 1-2: 流式响应
├── 修改 LlmDriver trait 添加 stream() 方法
├── 实现 Anthropic/OpenAI 流式 API
├── 前端 Tauri 事件接收
└── 测试验证

Week 3: MCP 协议
├── MCP 客户端基础架构
├── 工具发现和调用
├── 资源订阅
├── 提示词支持
└── 采样功能

Week 4-5: Browser Hand
├── playwright-rust 集成
├── navigate/click/input/screenshot 基础操作
├── wait/evaluate 高级操作
├── 错误处理和超时
└── 审批流程集成

Week 6: 工具安全 + 测试
├── shell_exec 命令白名单
├── file_read/write 路径限制
├── 单元测试补充（目标 70%）
├── E2E 测试新增用例
└── Bug 修复

Week 7: 文档 + 打包
├── 用户手册更新
├── CHANGELOG 编写
├── Windows 安装包构建
├── 自签名证书配置
└── 安装测试

Week 8: 发布 + 快速响应
├── GitHub Release 发布
├── 用户反馈渠道建立
├── 监控崩溃报告
└── v0.2.1 hotfix 准备
```

### 2.2 关键里程碑

| 里程碑 | 时间 | 验收标准 |
|--------|------|----------|
| M1: 流式可用 | Week 2 末 | 对话流式显示正常 |
| M2: MCP 可用 | Week 3 末 | 连接 filesystem-mcp 成功 |
| M3: Browser 可用 | Week 5 末 | 基础网页操作正常 |
| M4: 测试通过 | Week 6 末 | 核心流程 E2E 全绿 |
| M5: 正式发布 | Week 8 | GitHub Release 上线 |

---

## 三、技术架构设计

### 3.1 流式响应架构

```
┌─────────────────────────────────────────────────────────────┐
│                        流式响应数据流                         │
├─────────────────────────────────────────────────────────────┤
│                                                             │
│  LLM API (SSE)                                              │
│       │                                                     │
│       ▼                                                     │
│  ┌─────────────┐                                            │
│  │ LlmDriver   │  stream() -> impl Stream<Item = Chunk>     │
│  │ (Anthropic/ │                                            │
│  │  OpenAI)    │                                            │
│  └─────────────┘                                            │
│       │                                                     │
│       ▼                                                     │
│  ┌─────────────┐                                            │
│  │ LoopRunner  │  发送 Tauri 事件                           │
│  │             │  app.emit("stream:chunk", chunk)           │
│  └─────────────┘                                            │
│       │                                                     │
│       ▼ (Tauri IPC)                                         │
│  ┌─────────────┐                                            │
│  │ 前端        │  listen<StreamChunk>("stream:chunk")       │
│  │ ChatStore   │  逐字更新 UI                               │
│  └─────────────┘                                            │
│                                                             │
└─────────────────────────────────────────────────────────────┘
```

**关键改动**：

| 文件 | 改动说明 |
|------|----------|
| `crates/zclaw-runtime/src/driver/mod.rs` | trait 新增 `stream()` 方法 |
| `crates/zclaw-runtime/src/loop_runner.rs` | 流式循环实现 |
| `desktop/src/store/chatStore.ts` | 事件监听和 UI 更新 |

### 3.2 MCP 协议架构

```
┌─────────────────────────────────────────────────────────────┐
│                        MCP 协议栈                            │
├─────────────────────────────────────────────────────────────┤
│                                                             │
│  ┌─────────────┐  ┌─────────────┐  ┌─────────────┐          │
│  │   Tools     │  │  Resources  │  │   Prompts   │          │
│  │  工具调用   │  │  资源订阅   │  │  提示词模板 │          │
│  └─────────────┘  └─────────────┘  └─────────────┘          │
│         │                │                │                 │
│         └────────────────┼────────────────┘                 │
│                          ▼                                  │
│  ┌─────────────────────────────────────────────┐            │
│  │              MCP Client                      │            │
│  │  - JSON-RPC 2.0 通信                        │            │
│  │  - stdio / HTTP / WebSocket 传输           │            │
│  │  - 能力协商                                 │            │
│  └─────────────────────────────────────────────┘            │
│                          │                                  │
│                          ▼                                  │
│  ┌─────────────────────────────────────────────┐            │
│  │           MCP Server (外部)                  │            │
│  │  filesystem-mcp, github-mcp, etc.           │            │
│  └─────────────────────────────────────────────┘            │
│                                                             │
└─────────────────────────────────────────────────────────────┘
```

**关键改动**：

| 文件 | 改动说明 |
|------|----------|
| `crates/zclaw-protocols/src/mcp.rs` | 完整 MCP 客户端实现 |
| `crates/zclaw-protocols/src/mcp_client.rs` | 新增 - 连接管理 |
| `crates/zclaw-protocols/src/mcp_types.rs` | 新增 - 类型定义 |

### 3.3 Browser Hand 架构

```
┌─────────────────────────────────────────────────────────────┐
│                     Browser Hand 架构                        │
├─────────────────────────────────────────────────────────────┤
│                                                             │
│  ┌─────────────────────────────────────────────┐            │
│  │           BrowserHand (Rust)                │            │
│  │  impl Hand trait                            │            │
│  └─────────────────────────────────────────────┘            │
│                          │                                  │
│                          ▼                                  │
│  ┌─────────────────────────────────────────────┐            │
│  │           playwright-rust                    │            │
│  │  - chromium/firefox/webkit                  │            │
│  │  - Page, Element, Frame API                 │            │
│  └─────────────────────────────────────────────┘            │
│                          │                                  │
│         ┌────────────────┼────────────────┐                 │
│         ▼                ▼                ▼                 │
│  ┌───────────┐    ┌───────────┐    ┌───────────┐            │
│  │ navigate  │    │  click    │    │ screenshot│            │
│  │ input     │    │  wait     │    │ evaluate  │            │
│  └───────────┘    └───────────┘    └───────────┘            │
│                                                             │
└─────────────────────────────────────────────────────────────┘
```

**关键改动**：

| 文件 | 改动说明 |
|------|----------|
| `crates/zclaw-hands/src/hands/browser.rs` | 新增 - Browser Hand 实现 |
| `crates/zclaw-hands/Cargo.toml` | 添加 playwright 依赖 |
| `hands/browser.HAND.toml` | 更新触发词和权限 |

---

## 四、工具安全与风险缓解

### 4.1 工具安全策略

```
┌─────────────────────────────────────────────────────────────┐
│                      工具安全层级                             │
├─────────────────────────────────────────────────────────────┤
│                                                             │
│  Level 1: 审批控制                                          │
│  ├── needs_approval 标记的 Hand 需用户确认                  │
│  └── 敏感操作弹窗提示                                        │
│                                                             │
│  Level 2: 命令/路径白名单                                   │
│  ├── shell_exec: 允许的命令列表 (git, npm, cargo...)        │
│  ├── file_read: 允许的目录前缀                              │
│  └── file_write: 禁止写入系统目录                           │
│                                                             │
│  Level 3: 资源限制                                          │
│  ├── 超时控制 (默认 60s)                                    │
│  ├── 输出大小限制 (1MB)                                     │
│  └── 并发执行限制                                           │
│                                                             │
│  Level 4: 审计日志                                          │
│  ├── 所有工具调用记录                                       │
│  ├── 输入/输出摘要                                          │
│  └── 可追溯查询                                             │
│                                                             │
└─────────────────────────────────────────────────────────────┘
```

**具体实现**：

| 工具 | 安全措施 | 配置位置 |
|------|----------|----------|
| `shell_exec` | 命令白名单 + 超时 | `config/security.toml` |
| `file_read` | 路径前缀检查 | 代码硬编码 |
| `file_write` | 禁止系统目录 + 大小限制 | 代码硬编码 |
| `web_fetch` | SSRF 防护 (禁止内网) | 代码硬编码 |

### 4.2 风险缓解计划

| 风险 | 概率 | 影响 | 缓解措施 |
|------|------|------|----------|
| 流式响应延期 | 中 | 高 | Week 2 评估，必要时切换 SSE 方案 |
| MCP 兼容问题 | 中 | 中 | 优先测试主流服务器 (filesystem, github) |
| Browser 依赖问题 | 低 | 中 | Week 4 前验证 playwright-rust 可用性 |
| 自签名警告投诉 | 高 | 低 | 文档说明 + 安装指南 |
| 崩溃问题 | 中 | 高 | 崩溃报告收集 + 快速 hotfix 流程 |

### 4.3 发布后响应策略

```
┌─────────────────────────────────────────────────────────────┐
│                    问题响应流程                              │
├─────────────────────────────────────────────────────────────┤
│                                                             │
│  P0 问题 (数据安全/崩溃)                                    │
│  └── 24h 内 hotfix → v0.2.1                                 │
│                                                             │
│  P1 问题 (功能阻塞)                                         │
│  └── 72h 内修复 → v0.2.2                                    │
│                                                             │
│  P2 问题 (体验优化)                                         │
│  └── 收集反馈 → v0.3.0 统一处理                             │
│                                                             │
└─────────────────────────────────────────────────────────────┘
```

---

## 五、验收标准与发布检查清单

### 5.1 功能验收标准

| 功能 | 验收标准 | 测试方法 |
|------|----------|----------|
| **流式响应** | 消息逐字显示，延迟 < 500ms | 手动测试 + E2E |
| **MCP 协议** | 连接 filesystem-mcp，读取文件成功 | 集成测试 |
| **Browser Hand** | 打开网页、点击、截图成功 | E2E 测试 |
| **工具安全** | 恶意命令被拦截 | 单元测试 |
| **核心对话** | 发送消息 → 收到响应 → 无崩溃 | E2E 全流程 |
| **分身管理** | 创建/切换/删除分身正常 | 手动测试 |
| **配置保存** | 重启后配置持久化 | 手动测试 |

### 5.2 发布前检查清单 (Go/No-Go)

```
┌─────────────────────────────────────────────────────────────┐
│  v0.2.0 发布检查清单                                        │
├─────────────────────────────────────────────────────────────┤
│                                                             │
│  □ 流式响应功能正常                                         │
│  □ MCP 至少连接 1 个外部服务器成功                          │
│  □ Browser Hand 基础操作正常                                │
│  □ 工具安全白名单生效                                       │
│  □ 核心对话流程 E2E 测试全绿                                │
│  □ 无已知数据安全问题                                       │
│  □ Windows 安装包构建成功                                   │
│  □ 自签名证书配置完成                                       │
│  □ 用户手册更新完成                                         │
│  □ CHANGELOG 编写完成                                       │
│  □ GitHub Release 草稿准备                                  │
│  □ 反馈渠道建立 (GitHub Issues)                             │
│                                                             │
│  决策: □ GO  □ NO-GO (需完成: _______________)             │
│                                                             │
└─────────────────────────────────────────────────────────────┘
```

### 5.3 发布物料清单

| 物料 | 负责人 | 状态 |
|------|--------|------|
| Windows 安装包 | - | 待制作 |
| 用户手册 | - | 待更新 |
| CHANGELOG | - | 待编写 |
| GitHub Release Notes | - | 待编写 |
| 自签名证书 | - | 待生成 |

---

## 六、关键文件清单

| 文件 | 优先级 | 说明 |
|------|--------|------|
| `crates/zclaw-runtime/src/loop_runner.rs` | P0 | 流式响应核心 |
| `crates/zclaw-runtime/src/driver/mod.rs` | P0 | LlmDriver trait |
| `crates/zclaw-protocols/src/mcp.rs` | P0 | MCP 协议实现 |
| `crates/zclaw-hands/src/hands/browser.rs` | P0 | Browser Hand |
| `crates/zclaw-runtime/src/tool/builtin/shell_exec.rs` | P1 | 工具安全 |
| `desktop/src/store/chatStore.ts` | P0 | 前端流式处理 |
| `config/security.toml` | P1 | 安全配置 |

---

## 七、决策记录

| 决策项 | 选择 | 日期 |
|--------|------|------|
| 发布时间 | 6-8 周内，v0.2.0 正式版 | 2026-03-24 |
| 内测策略 | 跳过内测，直接发布 | 2026-03-24 |
| 流式响应 | 完整实现（Tauri 事件） | 2026-03-24 |
| MCP 协议 | 完整实现（全规范） | 2026-03-24 |
| Browser Hand | playwright-rust | 2026-03-24 |
| 本地模型 | 推迟到 v0.3.0 | 2026-03-24 |
| 代码签名 | 自签名证书 | 2026-03-24 |
| 发布路线图 | 方案 A：功能优先 | 2026-03-24 |