feat: 添加ESLint和Prettier配置并优化代码结构

style: 格式化代码文件并修复样式问题 docs: 新增部署文档和系统要求文档 test: 更新测试截图和覆盖率报告 refactor: 重构SchedulerPanel加载状态逻辑 ci: 添加lint和format脚本到package.json build: 更新依赖项并添加开发工具 chore: 添加验证报告和上线审查计划
2026-03-26 08:02:23 +08:00
parent bf6d81f9c6
commit d0c6319fc1
286 changed files with 239803 additions and 1118 deletions
--- a/docs/deployment/requirements.md
+++ b/docs/deployment/requirements.md
@@ -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
+```