feat: 添加ESLint和Prettier配置并优化代码结构
Some checks failed
CI / Lint & TypeCheck (push) Has been cancelled
CI / Unit Tests (push) Has been cancelled
CI / Build Frontend (push) Has been cancelled
CI / Rust Check (push) Has been cancelled
CI / Security Scan (push) Has been cancelled
CI / E2E Tests (push) Has been cancelled
Some checks failed
CI / Lint & TypeCheck (push) Has been cancelled
CI / Unit Tests (push) Has been cancelled
CI / Build Frontend (push) Has been cancelled
CI / Rust Check (push) Has been cancelled
CI / Security Scan (push) Has been cancelled
CI / E2E Tests (push) Has been cancelled
style: 格式化代码文件并修复样式问题 docs: 新增部署文档和系统要求文档 test: 更新测试截图和覆盖率报告 refactor: 重构SchedulerPanel加载状态逻辑 ci: 添加lint和format脚本到package.json build: 更新依赖项并添加开发工具 chore: 添加验证报告和上线审查计划
This commit is contained in:
iven
188
docs/deployment/README.md
Normal file
188
docs/deployment/README.md
Normal file
@@ -0,0 +1,188 @@
|
||||
# ZCLAW 部署指南
|
||||
|
||||
本指南涵盖 ZCLAW 桌面应用的部署流程。
|
||||
|
||||
## 目录
|
||||
|
||||
- [系统要求](#系统要求)
|
||||
- [构建流程](#构建流程)
|
||||
- [安装方式](#安装方式)
|
||||
- [配置说明](#配置说明)
|
||||
- [故障排查](#故障排查)
|
||||
|
||||
## 系统要求
|
||||
|
||||
### 开发环境
|
||||
|
||||
| 组件 | 最低版本 | 推荐版本 |
|
||||
|------|---------|---------|
|
||||
| Node.js | 18.x | 20.x |
|
||||
| pnpm | 8.x | 9.x |
|
||||
| Rust | 1.70 | 1.80+ |
|
||||
| Windows | 10 64-bit | 11 64-bit |
|
||||
|
||||
### 运行时环境
|
||||
|
||||
| 组件 | 要求 |
|
||||
|------|------|
|
||||
| 操作系统 | Windows 10/11 64-bit |
|
||||
| 内存 | 8GB+ (推荐 16GB) |
|
||||
| 磁盘空间 | 500MB+ |
|
||||
| 网络 | 需要访问 LLM API |
|
||||
|
||||
## 构建流程
|
||||
|
||||
### 1. 安装依赖
|
||||
|
||||
```bash
|
||||
# 克隆仓库
|
||||
git clone <repository-url>
|
||||
cd ZCLAW
|
||||
|
||||
# 安装根目录依赖
|
||||
pnpm install
|
||||
|
||||
# 安装桌面端依赖
|
||||
cd desktop
|
||||
pnpm install
|
||||
```
|
||||
|
||||
### 2. 开发模式
|
||||
|
||||
```bash
|
||||
# 从根目录启动开发环境
|
||||
pnpm start:dev
|
||||
|
||||
# 或仅启动桌面端
|
||||
cd desktop
|
||||
pnpm tauri:dev
|
||||
```
|
||||
|
||||
### 3. 生产构建
|
||||
|
||||
```bash
|
||||
cd desktop
|
||||
|
||||
# 标准构建
|
||||
pnpm tauri:build
|
||||
|
||||
# 打包构建（包含运行时）
|
||||
pnpm tauri:build:bundled
|
||||
```
|
||||
|
||||
构建产物位于：
|
||||
- `desktop/src-tauri/target/release/ZClaw.exe` - 可执行文件
|
||||
- `desktop/src-tauri/target/release/bundle/nsis/` - NSIS 安装包
|
||||
|
||||
## 安装方式
|
||||
|
||||
### NSIS 安装包（推荐）
|
||||
|
||||
1. 下载 `ZCLAW-Setup-{version}.exe`
|
||||
2. 双击运行安装程序
|
||||
3. 按照向导完成安装
|
||||
4. 首次启动时配置 API Key
|
||||
|
||||
### 便携版
|
||||
|
||||
1. 复制 `ZClaw.exe` 及相关文件
|
||||
2. 放置到任意目录
|
||||
3. 直接运行 `ZClaw.exe`
|
||||
|
||||
## 配置说明
|
||||
|
||||
### 配置文件位置
|
||||
|
||||
| 文件 | 位置 |
|
||||
|------|------|
|
||||
| 主配置 | `%USERPROFILE%\.openfang\openfang.toml` |
|
||||
| 环境变量 | `%USERPROFILE%\.openfang\.env` |
|
||||
| 数据库 | `%USERPROFILE%\.openfang\data\openfang.db` |
|
||||
| 日志 | `%USERPROFILE%\.openfang\logs\` |
|
||||
|
||||
### 首次启动配置
|
||||
|
||||
1. 启动 ZCLAW
|
||||
2. 进入「设置」→「模型与 API」
|
||||
3. 选择 LLM 提供商
|
||||
4. 输入 API Key
|
||||
5. 选择默认模型
|
||||
6. 点击「保存」
|
||||
|
||||
### 环境变量（可选）
|
||||
|
||||
参考 `.env.example` 文件：
|
||||
|
||||
```env
|
||||
# AI Provider
|
||||
ZCLAW_AI_PROVIDER=zhipu
|
||||
ZCLAW_ZHIPU_API_KEY=your-api-key
|
||||
ZCLAW_DEFAULT_MODEL=glm-4-flash
|
||||
|
||||
# Database
|
||||
ZCLAW_DB_PATH=./data/zclaw.db
|
||||
```
|
||||
|
||||
## 故障排查
|
||||
|
||||
### 常见问题
|
||||
|
||||
#### 1. 启动失败
|
||||
|
||||
**症状**：双击图标后无响应
|
||||
|
||||
**解决方案**：
|
||||
1. 检查是否被杀毒软件拦截
|
||||
2. 检查端口 50051 是否被占用
|
||||
3. 查看日志文件 `logs/error.log`
|
||||
|
||||
#### 2. API 连接失败
|
||||
|
||||
**症状**：发送消息后无响应
|
||||
|
||||
**解决方案**：
|
||||
1. 检查网络连接
|
||||
2. 验证 API Key 是否有效
|
||||
3. 检查 API 端点配置
|
||||
|
||||
#### 3. 数据库错误
|
||||
|
||||
**症状**：无法保存设置或历史记录
|
||||
|
||||
**解决方案**：
|
||||
1. 检查数据目录权限
|
||||
2. 备份后删除 `data/zclaw.db`
|
||||
3. 重启应用
|
||||
|
||||
### 日志收集
|
||||
|
||||
```bash
|
||||
# 查看最新日志
|
||||
type %USERPROFILE%\.openfang\logs\app.log | more
|
||||
```
|
||||
|
||||
## 更新流程
|
||||
|
||||
### 手动更新
|
||||
|
||||
1. 下载最新版本安装包
|
||||
2. 关闭正在运行的 ZCLAW
|
||||
3. 运行新版本安装程序
|
||||
4. 启动 ZCLAW
|
||||
|
||||
### 数据迁移
|
||||
|
||||
配置和数据存储在用户目录，更新时自动保留。
|
||||
|
||||
## 安全建议
|
||||
|
||||
1. **API Key 保护**：不要分享 API Key
|
||||
2. **定期备份**：备份 `.openfang` 目录
|
||||
3. **网络隔离**：建议在可信网络使用
|
||||
4. **权限控制**：限制对配置目录的访问
|
||||
|
||||
## 技术支持
|
||||
|
||||
- 文档：`docs/`
|
||||
- 故障排查：`docs/knowledge-base/troubleshooting.md`
|
||||
- 用户手册：`docs/USER_MANUAL.md`
|
||||
225
docs/deployment/requirements.md
Normal file
225
docs/deployment/requirements.md
Normal file
@@ -0,0 +1,225 @@
|
||||
# ZCLAW 系统要求
|
||||
|
||||
本文档详细说明 ZCLAW 的系统要求和兼容性信息。
|
||||
|
||||
## 最低系统要求
|
||||
|
||||
### Windows
|
||||
|
||||
| 组件 | 要求 |
|
||||
|------|------|
|
||||
| 操作系统 | Windows 10 64-bit (版本 1809 或更高) |
|
||||
| 处理器 | x64 架构，双核心 |
|
||||
| 内存 | 8 GB RAM |
|
||||
| 磁盘空间 | 500 MB 可用空间 |
|
||||
| 网络 | 宽带互联网连接 |
|
||||
|
||||
### 推荐配置
|
||||
|
||||
| 组件 | 推荐 |
|
||||
|------|------|
|
||||
| 操作系统 | Windows 11 64-bit (最新版本) |
|
||||
| 处理器 | x64 架构，四核心或以上 |
|
||||
| 内存 | 16 GB RAM |
|
||||
| 磁盘空间 | 1 GB SSD |
|
||||
| 网络 | 稳定宽带连接 |
|
||||
|
||||
## 开发环境要求
|
||||
|
||||
### 必需软件
|
||||
|
||||
| 软件 | 最低版本 | 推荐版本 | 用途 |
|
||||
|------|---------|---------|------|
|
||||
| Node.js | 18.x LTS | 20.x LTS | JavaScript 运行时 |
|
||||
| pnpm | 8.x | 9.x | 包管理器 |
|
||||
| Rust | 1.70 | 1.80+ | 后端编译 |
|
||||
| Git | 2.x | 最新 | 版本控制 |
|
||||
|
||||
### 可选软件
|
||||
|
||||
| 软件 | 用途 |
|
||||
|------|------|
|
||||
| Visual Studio Code | 代码编辑 |
|
||||
| Visual Studio Build Tools | 原生模块编译 |
|
||||
| Windows SDK | Windows 特定功能 |
|
||||
|
||||
## 外部依赖
|
||||
|
||||
### LLM API 服务
|
||||
|
||||
ZCLAW 需要连接到 LLM API 服务才能正常工作。支持的提供商：
|
||||
|
||||
| 提供商 | 需要配置 |
|
||||
|--------|---------|
|
||||
| 智谱 GLM | API Key |
|
||||
| 通义千问 | API Key |
|
||||
| DeepSeek | API Key |
|
||||
| Kimi/Moonshot | API Key |
|
||||
| OpenAI | API Key + Base URL（可选） |
|
||||
|
||||
### 可选服务
|
||||
|
||||
| 服务 | 用途 |
|
||||
|------|------|
|
||||
| Telegram Bot | 消息通道集成 |
|
||||
| 飞书应用 | 消息通道集成 |
|
||||
| FFmpeg | 视频处理 Hand |
|
||||
|
||||
## 网络要求
|
||||
|
||||
### 端口使用
|
||||
|
||||
| 端口 | 用途 | 协议 |
|
||||
|------|------|------|
|
||||
| 50051 | 内核通信 | gRPC |
|
||||
| 1420 | 开发服务器 | HTTP |
|
||||
|
||||
### 防火墙规则
|
||||
|
||||
确保以下出站连接被允许：
|
||||
|
||||
- LLM API 端点（各提供商不同）
|
||||
- `*.zhipu.ai`（智谱 GLM）
|
||||
- `dashscope.aliyuncs.com`（通义千问）
|
||||
- `api.deepseek.com`（DeepSeek）
|
||||
|
||||
## 兼容性
|
||||
|
||||
### Windows 版本
|
||||
|
||||
| 版本 | 支持状态 |
|
||||
|------|---------|
|
||||
| Windows 11 23H2 | ✅ 完全支持 |
|
||||
| Windows 11 22H2 | ✅ 完全支持 |
|
||||
| Windows 11 21H2 | ✅ 支持 |
|
||||
| Windows 10 22H2 | ✅ 支持 |
|
||||
| Windows 10 21H2 | ⚠️ 有限支持 |
|
||||
| Windows 10 早期版本 | ❌ 不支持 |
|
||||
| Windows 7/8 | ❌ 不支持 |
|
||||
|
||||
### 处理器架构
|
||||
|
||||
| 架构 | 支持状态 |
|
||||
|------|---------|
|
||||
| x64 (AMD64) | ✅ 支持 |
|
||||
| x86 (32-bit) | ❌ 不支持 |
|
||||
| ARM64 | ⚠️ 实验性支持 |
|
||||
|
||||
## 存储要求
|
||||
|
||||
### 应用程序
|
||||
|
||||
| 组件 | 大小 |
|
||||
|------|------|
|
||||
| 主程序 | ~150 MB |
|
||||
| 运行时依赖 | ~100 MB |
|
||||
| 资源文件 | ~50 MB |
|
||||
| **总计** | **~300 MB** |
|
||||
|
||||
### 用户数据
|
||||
|
||||
| 数据类型 | 估算大小 |
|
||||
|----------|---------|
|
||||
| 配置文件 | < 1 MB |
|
||||
| 会话历史 | 10-100 MB |
|
||||
| 记忆向量 | 50-500 MB |
|
||||
| **建议预留** | **1 GB** |
|
||||
|
||||
## 性能基准
|
||||
|
||||
### 启动时间
|
||||
|
||||
| 配置 | 冷启动 | 热启动 |
|
||||
|------|--------|--------|
|
||||
| 最低配置 | ~5 秒 | ~2 秒 |
|
||||
| 推荐配置 | ~3 秒 | ~1 秒 |
|
||||
|
||||
### 内存使用
|
||||
|
||||
| 场景 | 内存占用 |
|
||||
|------|---------|
|
||||
| 空闲状态 | ~150 MB |
|
||||
| 单对话 | ~200 MB |
|
||||
| 多对话 (5+) | ~300 MB |
|
||||
| 最大负载 | ~500 MB |
|
||||
|
||||
### API 响应
|
||||
|
||||
| 指标 | 目标值 |
|
||||
|------|--------|
|
||||
| 首字节时间 | < 500 ms |
|
||||
| 流式响应延迟 | < 100 ms |
|
||||
|
||||
## 限制
|
||||
|
||||
### 已知限制
|
||||
|
||||
1. **并发对话**：建议不超过 10 个活跃对话
|
||||
2. **历史记录**：单个对话建议不超过 1000 条消息
|
||||
3. **文件大小**：单个附件不超过 10 MB
|
||||
4. **上下文长度**：受限于所选模型
|
||||
|
||||
### 不支持的配置
|
||||
|
||||
- 32 位操作系统
|
||||
- Windows Server Core
|
||||
- Windows 容器环境
|
||||
- 虚拟机中的 GPU 直通（部分功能受限）
|
||||
|
||||
## 升级要求
|
||||
|
||||
### 从旧版本升级
|
||||
|
||||
| 从版本 | 升级路径 |
|
||||
|--------|---------|
|
||||
| 0.1.x → 0.2.x | 直接升级，配置兼容 |
|
||||
| 0.0.x → 0.2.x | 需要重新配置 |
|
||||
|
||||
### 数据迁移
|
||||
|
||||
用户数据存储在用户目录，升级时自动保留：
|
||||
- 会话历史
|
||||
- 配置设置
|
||||
- API 密钥（加密存储）
|
||||
|
||||
## 安全要求
|
||||
|
||||
### 运行权限
|
||||
|
||||
- **不需要** 管理员权限
|
||||
- 以标准用户身份运行
|
||||
- 数据存储在用户目录
|
||||
|
||||
### 数据安全
|
||||
|
||||
- API 密钥使用 OS keyring 加密存储
|
||||
- 敏感数据不写入日志
|
||||
- 本地数据库不加密（用户责任）
|
||||
|
||||
## 故障排查
|
||||
|
||||
### 检查系统兼容性
|
||||
|
||||
```powershell
|
||||
# 检查 Windows 版本
|
||||
winver
|
||||
|
||||
# 检查架构
|
||||
echo %PROCESSOR_ARCHITECTURE%
|
||||
|
||||
# 检查可用内存
|
||||
systeminfo | findstr /C:"Total Physical Memory"
|
||||
```
|
||||
|
||||
### 验证依赖
|
||||
|
||||
```powershell
|
||||
# Node.js
|
||||
node --version # 应 >= 18.0.0
|
||||
|
||||
# pnpm
|
||||
pnpm --version # 应 >= 8.0.0
|
||||
|
||||
# Rust
|
||||
rustc --version # 应 >= 1.70.0
|
||||
```
|
||||
227
docs/deployment/windows.md
Normal file
227
docs/deployment/windows.md
Normal file
@@ -0,0 +1,227 @@
|
||||
# Windows 部署指南
|
||||
|
||||
本指南详细说明 ZCLAW 在 Windows 平台上的部署流程。
|
||||
|
||||
## 系统要求
|
||||
|
||||
| 组件 | 最低要求 | 推荐配置 |
|
||||
|------|---------|---------|
|
||||
| 操作系统 | Windows 10 64-bit (1809+) | Windows 11 64-bit |
|
||||
| 处理器 | Intel Core i5 / AMD Ryzen 5 | Intel Core i7 / AMD Ryzen 7 |
|
||||
| 内存 | 8 GB | 16 GB |
|
||||
| 磁盘空间 | 500 MB | 1 GB |
|
||||
| 网络 | 宽带连接 | 稳定宽带 |
|
||||
|
||||
## 构建步骤
|
||||
|
||||
### 1. 准备构建环境
|
||||
|
||||
```powershell
|
||||
# 安装 Rust (如果未安装)
|
||||
winget install Rustlang.Rust.MSVC
|
||||
|
||||
# 安装 Node.js (如果未安装)
|
||||
winget install OpenJS.NodeJS.LTS
|
||||
|
||||
# 安装 pnpm
|
||||
npm install -g pnpm
|
||||
|
||||
# 验证安装
|
||||
rustc --version
|
||||
node --version
|
||||
pnpm --version
|
||||
```
|
||||
|
||||
### 2. 获取源代码
|
||||
|
||||
```powershell
|
||||
git clone <repository-url>
|
||||
cd ZCLAW
|
||||
```
|
||||
|
||||
### 3. 安装依赖
|
||||
|
||||
```powershell
|
||||
# 根目录依赖
|
||||
pnpm install
|
||||
|
||||
# 桌面端依赖
|
||||
cd desktop
|
||||
pnpm install
|
||||
```
|
||||
|
||||
### 4. 执行构建
|
||||
|
||||
```powershell
|
||||
cd desktop
|
||||
|
||||
# 开发构建（快速）
|
||||
pnpm tauri:dev
|
||||
|
||||
# 生产构建
|
||||
pnpm tauri:build
|
||||
|
||||
# 完整打包（包含运行时）
|
||||
pnpm tauri:build:bundled
|
||||
```
|
||||
|
||||
### 5. 查看构建产物
|
||||
|
||||
```powershell
|
||||
# 可执行文件
|
||||
dir src-tauri\target\release\ZClaw.exe
|
||||
|
||||
# NSIS 安装包
|
||||
dir src-tauri\target\release\bundle\nsis\
|
||||
```
|
||||
|
||||
## 安装选项
|
||||
|
||||
### NSIS 安装包
|
||||
|
||||
**优点**：
|
||||
- 自动处理依赖
|
||||
- 创建开始菜单快捷方式
|
||||
- 支持卸载
|
||||
|
||||
**步骤**：
|
||||
1. 双击 `ZCLAW-Setup-{version}-x64.exe`
|
||||
2. 选择安装位置（默认：`C:\Program Files\ZCLAW`）
|
||||
3. 选择是否创建桌面快捷方式
|
||||
4. 点击「安装」
|
||||
5. 完成后启动 ZCLAW
|
||||
|
||||
### 便携版
|
||||
|
||||
**优点**：
|
||||
- 无需安装
|
||||
- 可放在 U 盘运行
|
||||
- 不修改系统设置
|
||||
|
||||
**步骤**：
|
||||
1. 复制以下文件到目标目录：
|
||||
- `ZClaw.exe`
|
||||
- `resources/` 目录（如有）
|
||||
2. 双击 `ZClaw.exe` 运行
|
||||
|
||||
## 配置
|
||||
|
||||
### 用户数据目录
|
||||
|
||||
ZCLAW 在以下位置存储用户数据：
|
||||
|
||||
```
|
||||
%USERPROFILE%\.openfang\
|
||||
├── openfang.toml # 主配置文件
|
||||
├── .env # 环境变量（可选）
|
||||
├── data/
|
||||
│ └── openfang.db # SQLite 数据库
|
||||
└── logs/
|
||||
└── app.log # 应用日志
|
||||
```
|
||||
|
||||
### 防火墙配置
|
||||
|
||||
如果遇到网络问题，请确保 ZCLAW 可以通过 Windows 防火墙：
|
||||
|
||||
1. 打开「Windows Defender 防火墙」
|
||||
2. 点击「允许应用通过防火墙」
|
||||
3. 点击「更改设置」→「允许其他应用」
|
||||
4. 添加 `ZClaw.exe`
|
||||
5. 确保勾选「专用」和「公用」
|
||||
|
||||
### 杀毒软件排除
|
||||
|
||||
某些杀毒软件可能误报，建议添加排除项：
|
||||
|
||||
**Windows Defender**：
|
||||
1. 打开「Windows 安全中心」
|
||||
2. 选择「病毒和威胁防护」
|
||||
3. 点击「管理设置」
|
||||
4. 滚动到「排除项」→「添加或删除排除项」
|
||||
5. 添加 ZCLAW 安装目录
|
||||
|
||||
## 常见问题
|
||||
|
||||
### 启动闪退
|
||||
|
||||
**可能原因**：
|
||||
1. 缺少 Visual C++ 运行库
|
||||
2. 配置文件损坏
|
||||
3. 端口被占用
|
||||
|
||||
**解决方案**：
|
||||
```powershell
|
||||
# 安装 VC++ 运行库
|
||||
winget install Microsoft.VCRedist.2015+.x64
|
||||
|
||||
# 重置配置
|
||||
Remove-Item -Recurse -Force "$env:USERPROFILE\.openfang"
|
||||
|
||||
# 检查端口占用
|
||||
netstat -ano | findstr :50051
|
||||
```
|
||||
|
||||
### 更新后无法启动
|
||||
|
||||
**解决方案**：
|
||||
1. 完全卸载旧版本
|
||||
2. 删除 `%LOCALAPPDATA%\ZClaw` 目录
|
||||
3. 重新安装新版本
|
||||
|
||||
### 权限问题
|
||||
|
||||
**症状**：无法保存设置
|
||||
|
||||
**解决方案**：
|
||||
```powershell
|
||||
# 检查目录权限
|
||||
icacls "$env:USERPROFILE\.openfang"
|
||||
|
||||
# 修复权限
|
||||
icacls "$env:USERPROFILE\.openfang" /grant:r "%USERNAME%:(OI)(CI)F"
|
||||
```
|
||||
|
||||
## 卸载
|
||||
|
||||
### 通过安装程序卸载
|
||||
|
||||
1. 打开「设置」→「应用」→「已安装的应用」
|
||||
2. 找到 ZCLAW
|
||||
3. 点击「卸载」
|
||||
|
||||
### 手动卸载
|
||||
|
||||
1. 删除安装目录（默认：`C:\Program Files\ZCLAW`）
|
||||
2. 删除用户数据（可选）：
|
||||
```powershell
|
||||
Remove-Item -Recurse -Force "$env:USERPROFILE\.openfang"
|
||||
```
|
||||
3. 删除快捷方式
|
||||
|
||||
## 性能优化
|
||||
|
||||
### 启动速度
|
||||
|
||||
```powershell
|
||||
# 禁用开机自启（如果不需要）
|
||||
# 在任务管理器 → 启动 中禁用 ZCLAW
|
||||
```
|
||||
|
||||
### 内存使用
|
||||
|
||||
- 关闭不使用的对话标签页
|
||||
- 定期清理历史记录
|
||||
- 减少保留的上下文长度
|
||||
|
||||
## 日志收集
|
||||
|
||||
用于问题排查：
|
||||
|
||||
```powershell
|
||||
# 查看最新日志
|
||||
Get-Content "$env:USERPROFILE\.openfang\logs\app.log" -Tail 50
|
||||
|
||||
# 导出日志
|
||||
Copy-Item "$env:USERPROFILE\.openfang\logs" -Destination "C:\temp\zclaw-logs" -Recurse
|
||||
```
|
||||
Reference in New Issue
Block a user