Files

iven 3ff08faa56 release(v0.2.0): streaming, MCP protocol, Browser Hand, security enhancements

## Major Features

### Streaming Response System
- Implement LlmDriver trait with `stream()` method returning async Stream
- Add SSE parsing for Anthropic and OpenAI API streaming
- Integrate Tauri event system for frontend streaming (`stream:chunk` events)
- Add StreamChunk types: Delta, ToolStart, ToolEnd, Complete, Error

### MCP Protocol Implementation
- Add MCP JSON-RPC 2.0 types (mcp_types.rs)
- Implement stdio-based MCP transport (mcp_transport.rs)
- Support tool discovery, execution, and resource operations

### Browser Hand Implementation
- Complete browser automation with Playwright-style actions
- Support Navigate, Click, Type, Scrape, Screenshot, Wait actions
- Add educational Hands: Whiteboard, Slideshow, Speech, Quiz

### Security Enhancements
- Implement command whitelist/blacklist for shell_exec tool
- Add SSRF protection with private IP blocking
- Create security.toml configuration file

## Test Improvements
- Fix test import paths (security-utils, setup)
- Fix vi.mock hoisting issues with vi.hoisted()
- Update test expectations for validateUrl and sanitizeFilename
- Add getUnsupportedLocalGatewayStatus mock

## Documentation Updates
- Update architecture documentation
- Improve configuration reference
- Add quick-start guide updates

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

2026-03-24 03:24:24 +08:00

5.9 KiB

Raw Blame History

ZCLAW 快速启动指南

5 分钟内启动 ZCLAW 开发环境

前置要求

工具	最低版本	检查命令
Node.js	18.x	`node -v`
pnpm	8.x	`pnpm -v`
Rust	1.70+	`rustc --version`

重要: ZCLAW 使用内部 Kernel 架构，无需启动外部后端服务。

快速启动

Windows 用户

# 在项目根目录执行
.\scripts\quick-start-dev.ps1

Linux/macOS 用户

# 在项目根目录执行
./scripts/quick-start.sh

手动启动步骤

1. 安装依赖

# 根目录依赖
pnpm install

# 桌面端依赖
cd desktop && pnpm install && cd ..

2. 配置 LLM 提供商

首次启动后，在应用的"模型与 API"设置页面配置：

点击设置图标 ⚙️
进入"模型与 API"页面
点击"添加自定义模型"
填写配置信息：
- 服务商：选择 Kimi / Qwen / DeepSeek / Zhipu / OpenAI 等
- 模型 ID：如 kimi-k2-turbo、qwen-plus
- API Key：你的 API 密钥
- Base URL：（可选）自定义 API 端点
点击"设为默认"

3. 启动开发环境

# 方法 A: 一键启动（推荐）
pnpm start:dev

# 方法 B: 仅启动桌面端
pnpm desktop

测试环境启动

单元测试

# 运行所有单元测试
pnpm test

# 监听模式
pnpm test:watch

# 桌面端测试
cd desktop && pnpm test

E2E 测试

# 运行 E2E 测试
pnpm test:e2e

# 带界面运行
cd desktop && pnpm test:e2e:ui

开发端口说明

服务	端口	说明
Vite 开发服务器	1420	前端热重载
Tauri 窗口	-	桌面应用窗口

注意: 不再需要端口 50051，所有 Kernel 功能已内置。

支持的 LLM 提供商

Provider	Base URL	环境变量
Kimi Code	`https://api.kimi.com/coding/v1`	UI 配置
百炼/Qwen	`https://dashscope.aliyuncs.com/compatible-mode/v1`	UI 配置
DeepSeek	`https://api.deepseek.com/v1`	UI 配置
智谱 GLM	`https://open.bigmodel.cn/api/paas/v4`	UI 配置
OpenAI	`https://api.openai.com/v1`	UI 配置
Anthropic	`https://api.anthropic.com`	UI 配置
Local/Ollama	`http://localhost:11434/v1`	UI 配置

常见问题排查

Q1: 端口被占用

症状: Port 1420 is already in use

解决:

# Windows - 查找并终止进程
netstat -ano | findstr "1420"
taskkill /PID <PID> /F

# Linux/macOS
lsof -i :1420
kill -9 <PID>

Q2: 请先在"模型与 API"设置页面配置模型

症状: 连接时显示"请先在'模型与 API'设置页面配置模型"

解决:

打开应用设置
进入"模型与 API"页面
添加自定义模型并配置 API Key
设为默认模型
重新连接

Q3: LLM 调用失败

症状: Chat failed: LLM error: API error 401 或 404

排查步骤:

检查 API Key 是否正确
检查 Base URL 是否正确（特别是 Kimi Code 用户）
确认模型 ID 是否正确

常见 Provider 配置:

Provider	模型 ID 示例	Base URL
Kimi Code	`kimi-k2-turbo`	`https://api.kimi.com/coding/v1`
Qwen/百炼	`qwen-plus`	`https://dashscope.aliyuncs.com/compatible-mode/v1`
DeepSeek	`deepseek-chat`	`https://api.deepseek.com/v1`
Zhipu	`glm-4-flash`	`https://open.bigmodel.cn/api/paas/v4`

Q4: Tauri 编译失败

症状: Rust 编译错误

解决:

# 更新 Rust
rustup update

# 清理并重新构建
cd desktop/src-tauri
cargo clean
cargo build

Q5: 依赖安装失败

症状: pnpm install 报错

解决:

# 清理缓存
pnpm store prune

# 删除 node_modules 重新安装
rm -rf node_modules desktop/node_modules
pnpm install

验证清单

启动成功后，验证以下功能:

桌面端窗口正常显示
在"模型与 API"页面添加了自定义模型
可以发送消息并获得响应
可以切换 Agent
可以查看设置页面

停止服务

# 停止所有服务
pnpm start:stop

# 或手动停止
# Ctrl+C 终止运行中的进程

架构说明

ZCLAW 使用内部 Kernel 架构：

┌─────────────────────────────────────────────────────────────────┐
│                      ZCLAW 桌面应用                              │
├─────────────────────────────────────────────────────────────────┤
│  ┌─────────────────┐     ┌─────────────────────────────────┐   │
│  │  React 前端     │     │  Tauri 后端 (Rust)              │   │
│  │  ├─ KernelClient│────▶│  └─ zclaw-kernel                │   │
│  │  └─ Zustand     │     │     └─ LLM Drivers              │   │
│  └─────────────────┘     └─────────────────────────────────┘   │
└─────────────────────────────────────────────────────────────────┘

关键点：

所有核心能力集成在 Tauri 应用内
无需启动外部后端进程
模型配置通过 UI 完成

5.9 KiB Raw Blame History Unescape Escape