# 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 | 初始版本，用户批准 |