Files

iven afb48f7b80 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

10 KiB

Raw Permalink Blame History

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 发布策略

决策: 内测 → 公测 → 正式

阶段定义:

内测版 (v0.2.0-beta): 邀请 10-20 位种子用户
公测版 (v0.2.0-rc): 开放下载，收集更多反馈
正式版 (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)  │
                                    └─────────────────┘

关键改动:

LlmDriver trait 添加 send_stream() 方法
Kernel 添加 send_message_stream() 实现
前端使用 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. 参考文档

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

10 KiB Raw Permalink Blame History Unescape Escape

ZCLAW v0.2.0 发布设计规格

一、概述

1.1 背景

1.2 目标

1.3 范围

二、关键决策

2.1 流式响应

2.2 Hands 系统

2.3 MCP 协议

2.4 国际化

2.5 发布策略

2.6 时间线

三、工作项清单

3.1 P0 - 必须完成

3.2 P1 - 应该完成

3.3 P2 - 可以完成

四、架构设计

4.1 流式响应架构

4.2 Hands 系统架构

4.3 MCP 协议架构

4.4 i18n 架构

五、文件改动清单

5.1 Rust 后端

5.2 前端

5.3 配置文件

六、成功标准

6.1 功能验收

6.2 质量验收

6.3 发布验收

七、风险与缓解

八、附录

A. 参考文档

B. 相关 Issue

C. 版本历史

10 KiB

Raw Permalink Blame History