docs: add v0.2.0 release design spec

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
2026-03-23 23:24:08 +08:00
parent cbd3da46a3
commit afb48f7b80
1 changed files with 307 additions and 0 deletions
--- a/docs/superpowers/specs/2026-03-23-v0.2.0-release-design.md
+++ b/docs/superpowers/specs/2026-03-23-v0.2.0-release-design.md
@@ -0,0 +1,307 @@
+# ZCLAW v0.2.0 发布设计规格
+
+> **版本**: 1.0
+> **日期**: 2026-03-23
+> **状态**: 已批准
+> **作者**: Claude + 用户协作
+
+---
+
+## 一、概述
+
+### 1.1 背景
+
+ZCLAW 是一个面向中文用户的 AI Agent 桌面客户端，基于 Tauri 2 + React 19 + Rust workspace 技术栈。当前项目整体完成度约 70%，需要进行关键功能补全和发布准备工作。
+
+### 1.2 目标
+
+将 ZCLAW 打造成功能完整、可正式发布的 AI Agent 桌面客户端，通过内测 → 公测 → 正式的三阶段发布策略，确保产品质量和用户体验。
+
+### 1.3 范围
+
+- **包含**: 流式响应、核心 Hands、MCP 协议、i18n 架构、发布准备
+- **不包含**: 其他 6 个通用 Hands、通道适配器、macOS/Linux 构建（推迟到后续版本）
+
+---
+
+## 二、关键决策
+
+### 2.1 流式响应
+
+**决策**: 必须实现真正流式
+
+**理由**:
+- 流式响应对用户体验至关重要
+- 当前模拟方案无法接受
+- 需要 SSE/WebSocket 实现
+
+**实现要求**:
+- 替换 `loop_runner.rs:125` 的 TODO 占位符
+- 实现真正的 SSE 流式传输
+- 前端 `KernelClient` 需要支持流式消费
+
+### 2.2 Hands 系统
+
+**决策**: 补充核心通用 Hands (Browser + Collector)
+
+**理由**:
+- 教育类 Hands (4个) 已完成
+- Browser 和 Collector 是最常用的通用能力
+- 其他 6 个 Hands 可后续迭代
+
+**实现要求**:
+- Browser Hand: 网页自动化（导航、点击、输入、截图）
+- Collector Hand: 数据收集聚合（网页抓取、API 调用、文件读取）
+
+### 2.3 MCP 协议
+
+**决策**: 必须实现
+
+**理由**:
+- MCP 是 Claude Code 等工具的生态标准
+- 用户期望能接入外部工具
+- 是差异化竞争力
+
+**实现要求**:
+- 完成 `mcp.rs:151,155` 的 TODO
+- 实现工具调用和资源读取
+- 至少能连接 1 个外部 MCP 服务器
+
+### 2.4 国际化
+
+**决策**: 搭建多语言基础架构，v0.2.0 仅中文
+
+**理由**:
+- 当前硬编码无法维护
+- 需要为国际化预留空间
+- 先专注中文用户
+
+**实现要求**:
+- 集成 react-i18next
+- 提取所有 UI 字符串
+- v0.2.0 仅提供中文翻译
+
+### 2.5 发布策略
+
+**决策**: 内测 → 公测 → 正式
+
+**阶段定义**:
+1. **内测版 (v0.2.0-beta)**: 邀请 10-20 位种子用户
+2. **公测版 (v0.2.0-rc)**: 开放下载，收集更多反馈
+3. **正式版 (v0.2.0)**: 稳定后发布
+
+### 2.6 时间线
+
+**决策**: 灵活，功能完成即发布
+
+**理由**:
+- 不设硬性日期可减少压力
+- 保证质量优先
+- 便于应对意外情况
+
+---
+
+## 三、工作项清单
+
+### 3.1 P0 - 必须完成
+
+| ID | 工作项 | 复杂度 | 依赖 | 验收标准 |
+|----|--------|--------|------|----------|
+| P0-1 | 真正流式响应 | 高 | 无 | 用户能看到逐字输出 |
+| P0-2 | Browser Hand | 高 | P0-1 | 能完成基础网页自动化 |
+| P0-3 | Collector Hand | 中 | 无 | 能收集指定来源数据 |
+| P0-4 | MCP 协议实现 | 高 | 无 | 能连接至少 1 个 MCP 服务器 |
+
+### 3.2 P1 - 应该完成
+
+| ID | 工作项 | 复杂度 | 依赖 | 验收标准 |
+|----|--------|--------|------|----------|
+| P1-1 | i18n 基础架构 | 中 | 无 | react-i18next 集成，中文可用 |
+| P1-2 | 版本号统一 | 低 | 无 | 所有配置文件版本一致 |
+| P1-3 | CHANGELOG.md | 低 | 无 | 记录所有变更 |
+| P1-4 | 代码签名 | 中 | 无 | Windows 安装无警告 |
+
+### 3.3 P2 - 可以完成
+
+| ID | 工作项 | 复杂度 | 依赖 | 验收标准 |
+|----|--------|--------|------|----------|
+| P2-1 | 测试覆盖率提升 | 中 | 无 | 从 60% 提升到 75%+ |
+| P2-2 | 无障碍支持 | 中 | 无 | 关键组件有 ARIA 属性 |
+
+---
+
+## 四、架构设计
+
+### 4.1 流式响应架构
+
+```
+┌─────────────────┐     SSE/WS      ┌─────────────────┐
+│  React UI       │ ◄──────────────►│  Tauri Backend  │
+│  ChatArea.tsx   │                 │  KernelClient   │
+└─────────────────┘                 └────────┬────────┘
+                                             │
+                                             ▼
+                                    ┌─────────────────┐
+                                    │  zclaw-runtime  │
+                                    │  LlmDriver      │
+                                    │  (stream mode)  │
+                                    └─────────────────┘
+```
+
+**关键改动**:
+1. `LlmDriver` trait 添加 `send_stream()` 方法
+2. `Kernel` 添加 `send_message_stream()` 实现
+3. 前端使用 Tauri 事件系统接收流式数据
+
+### 4.2 Hands 系统架构
+
+```
+┌─────────────────────────────────────────────────────┐
+│                   zclaw-hands                        │
+├─────────────────────────────────────────────────────┤
+│  HandRegistry                                        │
+│    ├── WhiteboardHand (已实现)                       │
+│    ├── SlideshowHand (已实现)                        │
+│    ├── SpeechHand (已实现)                           │
+│    ├── QuizHand (已实现)                             │
+│    ├── BrowserHand (新增) ★                          │
+│    └── CollectorHand (新增) ★                        │
+└─────────────────────────────────────────────────────┘
+```
+
+**Browser Hand 能力**:
+- `navigate(url)` - 导航到 URL
+- `click(selector)` - 点击元素
+- `input(selector, text)` - 输入文本
+- `screenshot()` - 截图
+- `wait(selector)` - 等待元素
+
+**Collector Hand 能力**:
+- `fetch_url(url)` - 抓取网页
+- `call_api(url, method, body)` - API 调用
+- `read_file(path)` - 读取文件
+- `aggregate(sources)` - 聚合多个来源
+
+### 4.3 MCP 协议架构
+
+```
+┌─────────────────────────────────────────────────────┐
+│                 zclaw-protocols                      │
+├─────────────────────────────────────────────────────┤
+│  McpClient (trait)                                   │
+│    └── HttpMcpClient (新增) ★                        │
+│         ├── connect() - 建立连接                     │
+│         ├── list_tools() - 获取工具列表              │
+│         ├── call_tool() - 调用工具                   │
+│         ├── list_resources() - 获取资源列表          │
+│         └── read_resource() - 读取资源               │
+└─────────────────────────────────────────────────────┘
+```
+
+### 4.4 i18n 架构
+
+```
+desktop/src/
+├── i18n/
+│   ├── index.ts          # i18n 配置
+│   └── locales/
+│       └── zh-CN/
+│           ├── common.json
+│           ├── chat.json
+│           ├── hands.json
+│           └── settings.json
+└── components/
+    └── *.tsx             # 使用 useTranslation()
+```
+
+---
+
+## 五、文件改动清单
+
+### 5.1 Rust 后端
+
+| 文件 | 改动类型 | 说明 |
+|------|----------|------|
+| `crates/zclaw-runtime/src/loop_runner.rs` | 修改 | 实现流式响应 |
+| `crates/zclaw-runtime/src/driver/mod.rs` | 修改 | 添加 stream 方法 |
+| `crates/zclaw-kernel/src/kernel.rs` | 修改 | 流式消息处理 |
+| `crates/zclaw-hands/src/hands/browser.rs` | 新增 | Browser Hand |
+| `crates/zclaw-hands/src/hands/collector.rs` | 新增 | Collector Hand |
+| `crates/zclaw-protocols/src/mcp.rs` | 修改 | MCP 协议实现 |
+
+### 5.2 前端
+
+| 文件 | 改动类型 | 说明 |
+|------|----------|------|
+| `desktop/src/i18n/` | 新增 | i18n 配置和翻译文件 |
+| `desktop/src/components/ChatArea.tsx` | 修改 | 使用 i18n |
+| `desktop/src/store/chatStore.ts` | 修改 | 流式消息处理 |
+| `desktop/package.json` | 修改 | 版本号统一 |
+
+### 5.3 配置文件
+
+| 文件 | 改动类型 | 说明 |
+|------|----------|------|
+| `package.json` | 修改 | 版本号统一 |
+| `Cargo.toml` | 修改 | 版本号统一 |
+| `tauri.conf.json` | 修改 | 版本号统一 |
+| `CHANGELOG.md` | 新增 | 变更日志 |
+
+---
+
+## 六、成功标准
+
+### 6.1 功能验收
+
+- [ ] 用户能正常进行流式对话，看到逐字输出
+- [ ] Browser Hand 能完成：导航、点击、输入、截图
+- [ ] Collector Hand 能完成：网页抓取、API 调用、数据聚合
+- [ ] MCP 能连接至少 1 个外部工具（如 filesystem-mcp）
+- [ ] i18n 框架可用，中文界面完整
+
+### 6.2 质量验收
+
+- [ ] 所有 Rust 单元测试通过
+- [ ] 所有 E2E 测试通过
+- [ ] 测试覆盖率 ≥ 75%
+- [ ] TypeScript 类型检查无错误
+
+### 6.3 发布验收
+
+- [ ] 版本号所有位置一致
+- [ ] CHANGELOG.md 记录完整
+- [ ] Windows 安装包无 SmartScreen 警告
+- [ ] 内测用户无阻塞性问题反馈
+
+---
+
+## 七、风险与缓解
+
+| 风险 | 概率 | 影响 | 缓解措施 |
+|------|------|------|----------|
+| 流式响应实现复杂度超预期 | 高 | 高 | 先实现 SSE，WebSocket 可后续迭代 |
+| Browser Hand 依赖问题 | 中 | 中 | 使用 headless-chrome 或 playwright |
+| MCP 协议兼容性 | 中 | 中 | 先实现核心功能，边缘场景后续处理 |
+| 代码签名成本 | 中 | 高 | 预算规划，或使用自签名（仅内测） |
+| i18n 工作量 | 低 | 低 | 使用 i18next-scanner 自动提取 |
+
+---
+
+## 八、附录
+
+### A. 参考文档
+
+- [Tauri Events](https://tauri.app/v2/guides/features/events/)
+- [MCP Specification](https://modelcontextprotocol.io/)
+- [react-i18next](https://react.i18next.com/)
+
+### B. 相关 Issue
+
+- 流式响应 TODO: `crates/zclaw-runtime/src/loop_runner.rs:125`
+- MCP TODO: `crates/zclaw-protocols/src/mcp.rs:151,155`
+
+### C. 版本历史
+
+| 版本 | 日期 | 变更 |
+|------|------|------|
+| 1.0 | 2026-03-23 | 初始版本，用户批准 |