# 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
```