iven/zclaw_openfang
1
0
Fork 0
Code Issues Pull Requests Actions 1 Packages Projects Releases Wiki Activity

docs: add v0.2.0 release plan design document

Browse Source 
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
This commit is contained in:
iven
2026-03-24 01:16:52 +08:00
parent 5c8b1b53ce
commit fb263a8ae2
1 changed files with 359 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files

359
docs/superpowers/specs/2026-03-24-v0.2.0-release-plan-design.md Normal file
View File

@@ -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<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 |