iven/zclaw_openfang
1
0
Fork 0
Code Issues Pull Requests Actions 1 Packages Projects Releases Wiki Activity

feat(viking): add local server management for privacy-first deployment

Browse Source 
- Add viking_server.rs (Rust) for managing local OpenViking server process
- Add viking-server-manager.ts (TypeScript) for server control from UI
- Update VikingAdapter to support 'local' mode with auto-start capability
- Update documentation for local deployment mode

Key features:
- Auto-start local server when needed
- All data stays in ~/.openviking/ (privacy-first)
- Server listens only on 127.0.0.1
- Graceful fallback to remote/localStorage modes

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
This commit is contained in:
iven
2026-03-16 08:14:44 +08:00
parent 137f1a32fa
commit c8202d04e0
6 changed files with 1721 additions and 1 deletions
Download Patch File Download Diff File Expand all files Collapse all files

426
docs/OPENVIKING_INTEGRATION.md Normal file
View File

@@ -0,0 +1,426 @@
# OpenViking 深度集成文档
## 概述
ZCLAW 桌面端已集成 OpenViking 记忆系统，支持三种运行模式：
1. **本地服务器模式**：自动管理本地 OpenViking 服务器（隐私优先，数据完全本地）
2. **远程模式**：连接到运行中的远程 OpenViking 服务器
3. **本地存储模式**：使用 localStorage 作为回退（无需外部依赖）
**推荐**：对于注重隐私的用户，使用本地服务器模式，所有数据存储在 `~/.openviking/`。
## OpenViking 架构说明
OpenViking 采用客户端-服务器架构：
```
┌─────────────────────────────────────────────────────────────────┐
│ OpenViking 架构 │
│ │
│ ┌─────────────────┐ HTTP API ┌─────────────────┐ │
│ │ ov CLI │ ◄──────────────────► │ openviking- │ │
│ │ (Rust) │ │ server (Python) │ │
│ └─────────────────┘ └────────┬────────┘ │
│ │ │
│ ┌────────▼────────┐ │
│ │ SQLite + Vector │ │
│ │ ~/.openviking/ │ │
│ └─────────────────┘ │
└─────────────────────────────────────────────────────────────────┘
```
**重要**：CLI 不能独立运行，必须与服务器配合使用。
## ZCLAW 集成架构（本地模式）
```
┌─────────────────────────────────────────────────────────────────┐
│ ZCLAW Desktop (Tauri + React) │
│ │
│ ┌────────────────────────────────────────────────────────────┐ │
│ │ React UI Layer │ │
│ │ ┌──────────────┐ ┌────────────────┐ │ │
│ │ │ MemoryPanel │ │ContextBuilder │ │ │
│ │ └──────┬───────┘ └───────┬────────┘ │ │
│ └─────────┼─────────────────┼─────────────────────────────────┘ │
│ │ │ │
│ ┌─────────▼─────────────────▼─────────────────────────────────┐ │
│ │ TypeScript Integration Layer │ │
│ │ ┌─────────────────┐ ┌──────────────────────────────────┐ │ │
│ │ │ VikingAdapter │ │ viking-server-manager │ │ │
│ │ │ (local mode) │ │ (auto-start local server) │ │ │
│ │ └────────┬────────┘ └──────────────────────────────────┘ │ │
│ └───────────┼──────────────────────────────────────────────────┘ │
│ │ │
│ ┌───────────▼──────────────────────────────────────────────────┐ │
│ │ Tauri Command Layer │ │
│ │ ┌──────────────────────────────────────────────────────────┐│ │
│ │ │ viking_server_start/stop/status/restart ││ │
│ │ │ (Rust: manages openviking-server process) ││ │
│ │ └──────────────────────────────────────────────────────────┘│ │
│ └──────────────────────────┬───────────────────────────────────┘ │
│ │ │
│ ┌──────────────────────────▼───────────────────────────────────┐ │
│ │ Storage Layer (LOCAL DATA ONLY) │ │
│ │ ┌──────────────────────────────────────────────────────────┐│ │
│ │ │ OpenViking Server (Python) ││ │
│ │ │ http://127.0.0.1:1933 ││ │
│ │ │ Data: ~/.openviking/ ││ │
│ │ │ - SQLite database ││ │
│ │ │ - Vector embeddings ││ │
│ │ │ - Configuration ││ │
│ │ └──────────────────────────────────────────────────────────┘│ │
│ └──────────────────────────────────────────────────────────────┘ │
└─────────────────────────────────────────────────────────────────┘
```
## 隐私保证
**本地模式下**：
- ✅ 所有数据存储在 `~/.openviking/` 目录
- ✅ 服务器只监听 `127.0.0.1`（本地回环）
- ✅ 无任何数据上传到远程服务器
- ✅ 向量嵌入通过 doubao API 生成（可选配置本地模型）
## 文件结构
### Rust 后端 (`desktop/src-tauri/src/`)
| 文件 | 功能 |
|------|------|
| `viking_commands.rs` | Tauri 命令封装，调用 OpenViking CLI |
| `memory/mod.rs` | 记忆模块入口 |
| `memory/extractor.rs` | LLM 驱动的会话记忆提取 |
| `memory/context_builder.rs` | L0/L1/L2 分层上下文构建 |
| `llm/mod.rs` | 多提供商 LLM 客户端 (doubao/OpenAI/Anthropic) |
### TypeScript 前端 (`desktop/src/lib/`)
| 文件 | 功能 |
|------|------|
| `viking-adapter.ts` | 多模式适配器 (local/sidecar/remote) |
| `viking-server-manager.ts` | 本地服务器管理（启动/停止/状态） |
| `viking-client.ts` | OpenViking HTTP API 客户端 |
| `viking-local.ts` | Tauri sidecar 客户端 |
| `viking-memory-adapter.ts` | VikingAdapter → MemoryManager 桥接 |
| `context-builder.ts` | 聊天上下文构建器 |
### Rust 后端 (`desktop/src-tauri/src/`)
| 文件 | 功能 |
|------|------|
| `viking_server.rs` | **本地服务器管理** (启动/停止/状态检查) |
| `viking_commands.rs` | Tauri 命令封装（调用 OpenViking CLI） |
### 二进制文件 (`desktop/src-tauri/binaries/`)
| 文件 | 说明 |
|------|------|
| `ov-x86_64-pc-windows-msvc.exe` | Windows mock 二进制 (开发用) |
| `README.md` | 获取真实二进制的说明 |
## L0/L1/L2 分层上下文加载
为了优化 Token 消耗，上下文构建采用三层加载策略：
| 层级 | 名称 | Token 预算 | 策略 |
|------|------|-----------|------|
| L0 | Quick Scan | ~500 | 快速向量搜索，返回概览 |
| L1 | Standard | ~2000 | 加载相关项的详细内容 |
| L2 | Deep | ~3000 | 加载最相关项的完整内容 |
```
L0: find(query, limit=50) → 返回 URI + score + overview
↓
L1: read(uri, level=L1) → 返回详细内容 (score >= 0.5)
↓
L2: read(uri, level=L2) → 返回完整内容 (top 3)
```
## LLM 记忆提取
会话结束后，LLM 自动分析并提取记忆：
```rust
pub enum ExtractionCategory {
UserPreference, // 用户偏好
UserFact, // 用户事实
AgentLesson, // Agent 经验教训
AgentPattern, // Agent 任务模式
Task, // 任务信息
}
```
### 支持的 LLM 提供商
| 提供商 | Endpoint | 默认模型 |
|--------|----------|----------|
| doubao | https://ark.cn-beijing.volces.com/api/v3 | doubao-pro-32k |
| openai | https://api.openai.com/v1 | gpt-4o |
| anthropic | https://api.anthropic.com/v1 | claude-sonnet-4-20250514 |
## 使用方式
### 1. 本地服务器模式 (推荐，隐私优先)
```typescript
import { getVikingAdapter } from './lib/viking-adapter';
import { getVikingServerManager } from './lib/viking-server-manager';
// 获取服务器管理器
const serverManager = getVikingServerManager();
// 确保本地服务器运行
await serverManager.ensureRunning();
// 使用适配器（自动检测本地服务器）
const viking = getVikingAdapter({ mode: 'auto' });
await viking.buildEnhancedContext(userMessage, agentId);
// 检查服务器状态
const status = await serverManager.getStatus();
console.log(`Server running: ${status.running}, port: ${status.port}`);
```
### 2. 自动模式 (智能检测)
```typescript
const viking = getVikingAdapter(); // mode: 'auto'
await viking.buildEnhancedContext(userMessage, agentId);
```
自动检测顺序：
1. 尝试启动本地服务器 (local)
2. 检查 sidecar CLI (sidecar)
3. 连接远程服务器 (remote)
4. 回退到 localStorage
### 3. 强制本地模式
```typescript
const viking = getVikingAdapter({ mode: 'local' });
```
### 4. 强制 Sidecar 模式
```typescript
const viking = getVikingAdapter({ mode: 'sidecar' });
```
### 5. 使用 MemoryManager 接口
```typescript
import { getVikingMemoryAdapter } from './lib/viking-memory-adapter';
const adapter = getVikingMemoryAdapter({
enabled: true,
mode: 'auto',
fallbackToLocal: true
});
// 使用与 agent-memory.ts 相同的接口
await adapter.save(entry);
await adapter.search(query);
await adapter.stats(agentId);
```
## 配置
### 本地服务器配置 (Tauri 命令)
通过 Rust 后端管理本地 OpenViking 服务器：
```typescript
import { invoke } from '@tauri-apps/api/core';
// 获取服务器状态
const status = await invoke<VikingServerStatus>('viking_server_status');
// 启动服务器
await invoke<VikingServerStatus>('viking_server_start', {
config: {
port: 1933,
dataDir: '', // 使用默认 ~/.openviking/workspace
configFile: '' // 使用默认 ~/.openviking/ov.conf
}
});
// 停止服务器
await invoke('viking_server_stop');
// 重启服务器
await invoke<VikingServerStatus>('viking_server_restart');
```
### Tauri Sidecar 配置 (`tauri.conf.json`)
仅在 sidecar 模式下需要：
```json
{
"bundle": {
"externalBin": ["binaries/ov"]
}
}
```
### 环境变量
| 变量 | 说明 |
|------|------|
| `ZCLAW_VIKING_BIN` | OpenViking CLI 二进制路径 (sidecar 模式) |
| `ZCLAW_VIKING_SERVER_BIN` | OpenViking 服务器二进制路径 (本地模式) |
| `VIKING_SERVER_URL` | 远程服务器地址 (远程模式) |
| `OPENVIKING_CONFIG_FILE` | OpenViking 配置文件路径 |
## 安装 OpenViking (本地模式)
### 系统要求
- Python 3.10+
- 可选: Go 1.22+ (用于构建 AGFS 组件)
- 可选: C++ 编译器: GCC 9+ 或 Clang 11+
### 快速安装 (推荐)
ZCLAW 会自动管理本地 OpenViking 服务器。你只需要安装 OpenViking Python 包：
```bash
# 使用 pip 安装
pip install openviking --upgrade --force-reinstall
# 验证安装
openviking-server --version
```
### 自动服务器管理
ZCLAW 的 `viking-server-manager.ts` 会自动：
1. 检测本地服务器是否运行
2. 如未运行，自动启动 `openviking-server`
3. 监控服务器健康状态
4. 在应用退出时清理进程
```typescript
import { getVikingServerManager } from './lib/viking-server-manager';
const manager = getVikingServerManager();
// 确保服务器运行（自动启动如果需要）
await manager.ensureRunning();
// 获取服务器状态
const status = await manager.getStatus();
// { running: true, port: 1933, pid: 12345, dataDir: '~/.openviking/workspace' }
// 获取服务器 URL
const url = manager.getServerUrl(); // 'http://127.0.0.1:1933'
```
### 手动启动服务器 (可选)
如果你希望手动控制服务器：
```bash
# 前台运行
openviking-server --host 127.0.0.1 --port 1933
# 后台运行 (Linux/macOS)
nohup openviking-server > ~/.openviking/server.log 2>&1 &
# 后台运行 (Windows PowerShell)
Start-Process -NoNewWindow openviking-server -RedirectStandardOutput "$env:USERPROFILE\.openviking\server.log"
```
### 配置文件
创建 `~/.openviking/ov.conf`:
```json
{
"storage": {
"workspace": "/home/your-name/openviking_workspace"
},
"embedding": {
"dense": {
"api_base": "https://ark.cn-beijing.volces.com/api/v3",
"api_key": "your-api-key",
"provider": "volcengine",
"dimension": 1024,
"model": "doubao-embedding-vision-250615"
}
},
"vlm": {
"api_base": "https://ark.cn-beijing.volces.com/api/v3",
"api_key": "your-api-key",
"provider": "volcengine",
"model": "doubao-seed-2-0-pro-260215"
}
}
```
设置环境变量:
```bash
# Linux/macOS
export OPENVIKING_CONFIG_FILE=~/.openviking/ov.conf
# Windows PowerShell
$env:OPENVIKING_CONFIG_FILE = "$HOME/.openviking/ov.conf"
```
## 测试
### Rust 测试
```bash
cd desktop/src-tauri
cargo test
```
当前测试覆盖：
- `test_provider_configs` - LLM 提供商配置
- `test_llm_client_creation` - LLM 客户端创建
- `test_extraction_config_default` - 提取配置默认值
- `test_uri_generation` - URI 生成
- `test_estimate_tokens` - Token 估算
- `test_extract_category` - 分类提取
- `test_context_builder_config_default` - 上下文构建器配置
- `test_status_unavailable_without_cli` - 无 CLI 时的状态
### TypeScript 测试
```bash
cd desktop
pnpm vitest run tests/desktop/memory*.test.ts
```
## 故障排除
### Q: OpenViking CLI not found
确保 `ov-x86_64-pc-windows-msvc.exe` 存在于 `binaries/` 目录，或设置 `ZCLAW_VIKING_BIN` 环境变量。
### Q: Sidecar 启动失败
检查 Tauri 控制台日志，确认 sidecar 二进制权限正确。
### Q: 记忆未保存
1. 检查 LLM API 配置 (doubao/OpenAI/Anthropic)
2. 确认 `VIKING_SERVER_URL` 正确 (remote 模式)
3. 检查浏览器控制台的网络请求
## 迁移路径
从现有 localStorage 实现迁移到 OpenViking：
1. 导出现有记忆：`getMemoryManager().exportToMarkdown(agentId)`
2. 切换到 OpenViking 模式
3. 导入记忆到 OpenViking (通过 CLI 或 API)
## 参考资料
- [OpenViking GitHub](https://github.com/anthropics/openviking)
- [ZCLAW_AGENT_INTELLIGENCE_EVOLUTION.md](../docs/ZCLAW_AGENT_INTELLIGENCE_EVOLUTION.md)
- [ZCLAW_OPENVIKING_INTEGRATION_PLAN.md](../docs/ZCLAW_OPENVIKING_INTEGRATION_PLAN.md)