From fb263a8ae2f44ff140daf9947401a6d5c020c7b8 Mon Sep 17 00:00:00 2001 From: iven Date: Tue, 24 Mar 2026 01:16:52 +0800 Subject: [PATCH] docs: add v0.2.0 release plan design document Co-Authored-By: Claude Opus 4.6 --- .../2026-03-24-v0.2.0-release-plan-design.md | 359 ++++++++++++++++++ 1 file changed, 359 insertions(+) create mode 100644 docs/superpowers/specs/2026-03-24-v0.2.0-release-plan-design.md diff --git a/docs/superpowers/specs/2026-03-24-v0.2.0-release-plan-design.md b/docs/superpowers/specs/2026-03-24-v0.2.0-release-plan-design.md new file mode 100644 index 0000000..c1fd24c --- /dev/null +++ b/docs/superpowers/specs/2026-03-24-v0.2.0-release-plan-design.md @@ -0,0 +1,359 @@ +# 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 │ +│ │ (Anthropic/ │ │ +│ │ OpenAI) │ │ +│ └─────────────┘ │ +│ │ │ +│ ▼ │ +│ ┌─────────────┐ │ +│ │ LoopRunner │ 发送 Tauri 事件 │ +│ │ │ app.emit("stream:chunk", chunk) │ +│ └─────────────┘ │ +│ │ │ +│ ▼ (Tauri IPC) │ +│ ┌─────────────┐ │ +│ │ 前端 │ listen("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 |