docs: update OpenViking installation requirements

- Add Python version compatibility notes (3.10-3.12 required)
- Add Windows-specific installation instructions
- Add conda/WSL alternatives for Python 3.13+ users
- Update binaries README with system requirements table
- Clarify that CLI requires server to run

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
This commit is contained in:
iven
2026-03-16 08:28:27 +08:00
parent 0eb30c0531
commit 131b9c93ae
2 changed files with 118 additions and 5 deletions

View File

@@ -0,0 +1,79 @@
# OpenViking Integration
## 重要说明
OpenViking 采用客户端-服务器架构:
- **服务器** (`openviking-server`): Python 服务,提供核心功能
- **CLI** (`ov`): Rust 客户端,与服务器通信
**CLI 不能独立运行**,必须与服务器配合使用。
## 系统要求
| 组件 | 要求 | 说明 |
|------|------|------|
| Python | **3.10 - 3.12** | ⚠️ Python 3.13+ 可能没有预编译 wheel |
| Go | 1.22+ | 可选,从源码构建时需要 |
| C++ 编译器 | GCC/Clang/MSVC | 可选,从源码构建时需要 |
## 推荐使用方式
### 1. 安装并运行 OpenViking 服务器
```bash
# 安装 Python 包 (推荐 Python 3.10-3.12)
pip install openviking --upgrade
# 验证安装
openviking-server --version
# 启动服务器 (默认端口 1933)
openviking-server
```
### ⚠️ Python 3.13+ 用户
如果你使用 Python 3.13+,预编译 wheel 可能不可用。推荐方案:
```bash
# 方案 1: 使用 Python 3.12
py -3.12 -m pip install openviking
# 方案 2: 使用 conda
conda create -n openviking python=3.12
conda activate openviking
pip install openviking
```
### 2. ZCLAW 自动管理
ZCLAW 会自动:
- 检测本地 OpenViking 服务器是否运行
- 如未运行,自动启动 `openviking-server`
- 管理服务器生命周期
### 3. 环境变量配置(可选)
```bash
# 指定远程服务器
export VIKING_SERVER_URL=http://your-server:1933
# Windows PowerShell
$env:VIKING_SERVER_URL = "http://your-server:1933"
```
## 本地回退模式
如果 OpenViking 服务器不可用ZCLAW 会自动回退到 localStorage 模式(使用 `agent-memory.ts`)。
## 目录内容
| 文件 | 说明 |
|------|------|
| `ov-x86_64-pc-windows-msvc.exe` | Mock 二进制(开发测试用) |
## 参考链接
- [OpenViking GitHub](https://github.com/volcengine/OpenViking)
- [OpenViking PyPI](https://pypi.org/project/openviking/)
- [完整文档](https://github.com/volcengine/OpenViking#readme)