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