308 lines
10 KiB
Markdown
308 lines
10 KiB
Markdown
# 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 | 初始版本，用户批准 |
|