19 KiB
19 KiB
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 |