360 lines
19 KiB
Markdown
360 lines
19 KiB
Markdown
# 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 |
|