131b9c93ae
- 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>
80 lines
1.9 KiB
Markdown
80 lines
1.9 KiB
Markdown
# 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)
|