3ff08faa56
## 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>
260 lines
5.9 KiB
Markdown
260 lines
5.9 KiB
Markdown
# ZCLAW 快速启动指南
|
||
|
||
> 5 分钟内启动 ZCLAW 开发环境
|
||
|
||
---
|
||
|
||
## 前置要求
|
||
|
||
| 工具 | 最低版本 | 检查命令 |
|
||
|------|----------|----------|
|
||
| Node.js | 18.x | `node -v` |
|
||
| pnpm | 8.x | `pnpm -v` |
|
||
| Rust | 1.70+ | `rustc --version` |
|
||
|
||
**重要**: ZCLAW 使用内部 Kernel 架构，**无需**启动外部后端服务。
|
||
|
||
---
|
||
|
||
## 快速启动
|
||
|
||
### Windows 用户
|
||
|
||
```powershell
|
||
# 在项目根目录执行
|
||
.\scripts\quick-start-dev.ps1
|
||
```
|
||
|
||
### Linux/macOS 用户
|
||
|
||
```bash
|
||
# 在项目根目录执行
|
||
./scripts/quick-start.sh
|
||
```
|
||
|
||
---
|
||
|
||
## 手动启动步骤
|
||
|
||
### 1. 安装依赖
|
||
|
||
```bash
|
||
# 根目录依赖
|
||
pnpm install
|
||
|
||
# 桌面端依赖
|
||
cd desktop && pnpm install && cd ..
|
||
```
|
||
|
||
### 2. 配置 LLM 提供商
|
||
|
||
**首次启动后**，在应用的"模型与 API"设置页面配置：
|
||
|
||
1. 点击设置图标 ⚙️
|
||
2. 进入"模型与 API"页面
|
||
3. 点击"添加自定义模型"
|
||
4. 填写配置信息：
|
||
- 服务商：选择 Kimi / Qwen / DeepSeek / Zhipu / OpenAI 等
|
||
- 模型 ID：如 `kimi-k2-turbo`、`qwen-plus`
|
||
- API Key：你的 API 密钥
|
||
- Base URL：（可选）自定义 API 端点
|
||
5. 点击"设为默认"
|
||
|
||
### 3. 启动开发环境
|
||
|
||
```bash
|
||
# 方法 A: 一键启动（推荐）
|
||
pnpm start:dev
|
||
|
||
# 方法 B: 仅启动桌面端
|
||
pnpm desktop
|
||
```
|
||
|
||
---
|
||
|
||
## 测试环境启动
|
||
|
||
### 单元测试
|
||
|
||
```bash
|
||
# 运行所有单元测试
|
||
pnpm test
|
||
|
||
# 监听模式
|
||
pnpm test:watch
|
||
|
||
# 桌面端测试
|
||
cd desktop && pnpm test
|
||
```
|
||
|
||
### E2E 测试
|
||
|
||
```bash
|
||
# 运行 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`
|
||
|
||
**解决**:
|
||
```powershell
|
||
# Windows - 查找并终止进程
|
||
netstat -ano | findstr "1420"
|
||
taskkill /PID <PID> /F
|
||
|
||
# Linux/macOS
|
||
lsof -i :1420
|
||
kill -9 <PID>
|
||
```
|
||
|
||
### Q2: 请先在"模型与 API"设置页面配置模型
|
||
|
||
**症状**: 连接时显示"请先在'模型与 API'设置页面配置模型"
|
||
|
||
**解决**:
|
||
1. 打开应用设置
|
||
2. 进入"模型与 API"页面
|
||
3. 添加自定义模型并配置 API Key
|
||
4. 设为默认模型
|
||
5. 重新连接
|
||
|
||
### Q3: LLM 调用失败
|
||
|
||
**症状**: `Chat failed: LLM error: API error 401` 或 `404`
|
||
|
||
**排查步骤**:
|
||
1. 检查 API Key 是否正确
|
||
2. 检查 Base URL 是否正确（特别是 Kimi Code 用户）
|
||
3. 确认模型 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 编译错误
|
||
|
||
**解决**:
|
||
```bash
|
||
# 更新 Rust
|
||
rustup update
|
||
|
||
# 清理并重新构建
|
||
cd desktop/src-tauri
|
||
cargo clean
|
||
cargo build
|
||
```
|
||
|
||
### Q5: 依赖安装失败
|
||
|
||
**症状**: pnpm install 报错
|
||
|
||
**解决**:
|
||
```bash
|
||
# 清理缓存
|
||
pnpm store prune
|
||
|
||
# 删除 node_modules 重新安装
|
||
rm -rf node_modules desktop/node_modules
|
||
pnpm install
|
||
```
|
||
|
||
---
|
||
|
||
## 验证清单
|
||
|
||
启动成功后，验证以下功能:
|
||
|
||
- [ ] 桌面端窗口正常显示
|
||
- [ ] 在"模型与 API"页面添加了自定义模型
|
||
- [ ] 可以发送消息并获得响应
|
||
- [ ] 可以切换 Agent
|
||
- [ ] 可以查看设置页面
|
||
|
||
---
|
||
|
||
## 停止服务
|
||
|
||
```bash
|
||
# 停止所有服务
|
||
pnpm start:stop
|
||
|
||
# 或手动停止
|
||
# Ctrl+C 终止运行中的进程
|
||
```
|
||
|
||
---
|
||
|
||
## 架构说明
|
||
|
||
ZCLAW 使用**内部 Kernel 架构**：
|
||
|
||
```
|
||
┌─────────────────────────────────────────────────────────────────┐
|
||
│ ZCLAW 桌面应用 │
|
||
├─────────────────────────────────────────────────────────────────┤
|
||
│ ┌─────────────────┐ ┌─────────────────────────────────┐ │
|
||
│ │ React 前端 │ │ Tauri 后端 (Rust) │ │
|
||
│ │ ├─ KernelClient│────▶│ └─ zclaw-kernel │ │
|
||
│ │ └─ Zustand │ │ └─ LLM Drivers │ │
|
||
│ └─────────────────┘ └─────────────────────────────────┘ │
|
||
└─────────────────────────────────────────────────────────────────┘
|
||
```
|
||
|
||
**关键点**：
|
||
- 所有核心能力集成在 Tauri 应用内
|
||
- 无需启动外部后端进程
|
||
- 模型配置通过 UI 完成
|
||
|
||
---
|
||
|
||
## 相关文档
|
||
|
||
- [完整开发文档](./DEVELOPMENT.md)
|
||
- [故障排查指南](./knowledge-base/troubleshooting.md)
|
||
- [配置说明](./knowledge-base/configuration.md)
|
||
|
||
---
|
||
|
||
**最后更新**: 2026-03-22
|