docs: add setup guides and error notification component

- Add OpenFang Kernel configuration guide (docs/setup/OPENFANG-SETUP.md) - Add Chinese models configuration guide (docs/setup/chinese-models.md) - Add quick start guide (docs/quick-start.md) - Add quick start scripts for Windows and Linux/macOS - Add ErrorNotification component for centralized error display These additions help users: - Quickly set up development environment - Configure OpenFang backend correctly - Configure Chinese LLM providers (GLM, Qwen, Kimi, MiniMax) - See error notifications in a consistent UI Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
2026-03-21 00:17:44 +08:00
parent c5d91cf9f0
commit d3a4de2480
6 changed files with 1931 additions and 0 deletions
--- a/docs/quick-start.md
+++ b/docs/quick-start.md
@@ -0,0 +1,233 @@
+# ZCLAW 快速启动指南
+
+> 5 分钟内启动 ZCLAW 开发环境
+
+---
+
+## 前置要求
+
+| 工具 | 最低版本 | 检查命令 |
+|------|----------|----------|
+| Node.js | 18.x | `node -v` |
+| pnpm | 8.x | `pnpm -v` |
+| Rust | 1.70+ | `rustc --version` |
+| OpenFang | - | `openfang --version` |
+
+---
+
+## 快速启动
+
+### Windows 用户
+
+```powershell
+# 在项目根目录执行
+.\scripts\quick-start-dev.ps1
+```
+
+### Linux/macOS 用户
+
+```bash
+# 在项目根目录执行
+./scripts/quick-start.sh
+```
+
+---
+
+## 手动启动步骤
+
+### 1. 安装依赖
+
+```bash
+# 根目录依赖
+pnpm install
+
+# 桌面端依赖
+cd desktop && pnpm install && cd ..
+```
+
+### 2. 启动 OpenFang 后端
+
+```bash
+# 方法 A: 使用 CLI
+openfang start
+
+# 方法 B: 使用 pnpm 脚本
+pnpm gateway:start
+```
+
+验证后端运行:
+```bash
+curl http://127.0.0.1:50051/api/health
+# 应返回: {"status":"ok"}
+```
+
+### 3. 启动开发环境
+
+```bash
+# 方法 A: 一键启动（推荐）
+pnpm start:dev
+
+# 方法 B: 仅启动桌面端（需要后端已运行）
+pnpm desktop
+
+# 方法 C: 分开启动
+# 终端 1 - 启动 Gateway
+pnpm dev
+
+# 终端 2 - 启动桌面端
+pnpm desktop
+```
+
+---
+
+## 测试环境启动
+
+### 单元测试
+
+```bash
+# 运行所有单元测试
+pnpm test
+
+# 监听模式
+pnpm test:watch
+
+# 桌面端测试
+cd desktop && pnpm test
+```
+
+### E2E 测试
+
+```bash
+# 运行 E2E 测试
+pnpm test:e2e
+
+# 带界面运行
+cd desktop && pnpm test:e2e:ui
+```
+
+---
+
+## 开发端口说明
+
+| 服务 | 端口 | 说明 |
+|------|------|------|
+| OpenFang 后端 | 50051 | API 和 WebSocket 服务 |
+| Vite 开发服务器 | 1420 | 前端热重载 |
+| Tauri 窗口 | - | 桌面应用窗口 |
+
+---
+
+## 常见问题排查
+
+### Q1: 端口被占用
+
+**症状**: `Port 1420 is already in use` 或 `Port 50051 is already in use`
+
+**解决**:
+```powershell
+# Windows - 查找并终止进程
+netstat -ano | findstr "1420"
+taskkill /PID <PID> /F
+
+# Linux/macOS
+lsof -i :1420
+kill -9 <PID>
+```
+
+### Q2: 后端连接失败
+
+**症状**: `Network Error` 或 `Connection refused`
+
+**排查步骤**:
+```bash
+# 1. 检查后端是否运行
+curl http://127.0.0.1:50051/api/health
+
+# 2. 检查端口监听
+netstat -ano | findstr "50051"
+
+# 3. 重启后端
+openfang restart
+```
+
+### Q3: API Key 未配置
+
+**症状**: `Missing API key: No LLM provider configured`
+
+**解决**:
+```bash
+# 编辑配置文件
+# Windows: %USERPROFILE%\.openfang\.env
+# Linux/macOS: ~/.openfang/.env
+
+# 添加 API Key
+echo "ZHIPU_API_KEY=your_key" >> ~/.openfang/.env
+
+# 重启后端
+openfang restart
+```
+
+### 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
+```
+
+---
+
+## 验证清单
+
+启动成功后，验证以下功能:
+
+- [ ] 后端健康检查通过: `curl http://127.0.0.1:50051/api/health`
+- [ ] 桌面端窗口正常显示
+- [ ] 可以发送消息并获得响应
+- [ ] 可以切换 Agent
+- [ ] 可以查看设置页面
+
+---
+
+## 停止服务
+
+```bash
+# 停止所有服务
+pnpm start:stop
+
+# 或手动停止
+# Ctrl+C 终止运行中的进程
+```
+
+---
+
+## 相关文档
+
+- [完整开发文档](./DEVELOPMENT.md)
+- [故障排查指南](./knowledge-base/troubleshooting.md)
+- [配置说明](./knowledge-base/configuration.md)
+
+---
+
+**最后更新**: 2026-03-21