iven/zclaw_openfang
1
0
Fork 0
Code Issues Pull Requests Actions 1 Packages Projects Releases Wiki Activity
Files
b7f3d94950cdc2ee0965c4ee7334c854b907806b
zclaw_openfang/docs/superpowers/specs/2026-03-23-v0.2.0-release-design.md
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 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 发布策略

决策: 内测 → 公测 → 正式

阶段定义:

  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. 参考文档

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