zclaw_openfang/docs/features/03-context-database/00-openviking-integration.md

# OpenViking 集成 (OpenViking Integration)

> **分类**: 上下文数据库
> **优先级**: P1 - 重要
> **成熟度**: L4 - 生产
> **最后更新**: 2026-03-24
> **验证状态**: ✅ 代码已验证
> **架构**: 内部 SQLite 存储 + 可选 OpenViking

---

## 一、功能概述

### 1.1 基本信息

OpenViking 是字节跳动开源的 AI Agent 上下文数据库，ZCLAW 通过 HTTP 客户端与之集成，支持本地、远程和本地存储三种模式。

| 属性 | 值 |
|------|-----|
| 分类 | 上下文数据库 |
| 优先级 | P1 |
| 成熟度 | L4 |
| 依赖 | Tauri Backend |

### 1.2 相关文件

| 文件 | 路径 | 用途 |
|------|------|------|
| HTTP 客户端 | `desktop/src/lib/viking-client.ts` | 前端客户端 |
| Tauri 集成 | `desktop/src-tauri/src/viking_commands.rs` | Rust 命令 |
| 服务器管理 | `desktop/src-tauri/src/viking_server.rs` | 本地服务器 |
| 适配器 | `desktop/src/lib/viking-adapter.ts` | 统一接口 |

---

## 二、设计初衷

### 2.1 问题背景

**用户痛点**:
1. AI Agent 缺乏长期记忆存储
2. 上下文窗口有限
3. 隐私问题：数据存在云端

**系统缺失能力**:
- 缺乏持久化的上下文存储
- 缺乏语义搜索能力
- 缺乏分层上下文管理

**为什么需要**:
OpenViking 提供了隐私优先的本地上下文数据库，支持 L0/L1/L2 分层存储和语义搜索。

### 2.2 设计目标

1. **隐私优先**: 本地部署，数据不出设备
2. **分层存储**: L0 (完整) → L1 (摘要) → L2 (关键词)
3. **语义搜索**: 基于向量的相似度搜索
4. **灵活部署**: 本地/远程/存储三种模式

### 2.3 运行模式

| 模式 | 描述 | 适用场景 |
|------|------|---------|
| Local Server | 自动管理本地 OpenViking 服务器 | 隐私优先 |
| Remote | 连接远程 OpenViking 服务器 | 团队协作 |
| Local Storage | 纯前端 localStorage | 快速开始 |

### 2.4 设计约束

- **资源约束**: 本地服务器需要额外资源
- **兼容性约束**: OpenViking 需要单独安装
- **降级约束**: 无 OpenViking 时需要降级

---

## 三、技术设计

### 3.1 核心接口

```typescript
interface VikingClient {
  // 资源管理
  addResource(uri: string, content: string, metadata?: any): Promise<Resource>;
  removeResource(uri: string): Promise<void>;
  ls(scope?: string): Promise<Resource[]>;
  tree(scope?: string): Promise<ResourceTree>;

  // 搜索
  find(query: string, options?: FindOptions): Promise<FindResult[]>;
  findWithTrace(query: string): Promise<FindResultWithTrace[]>;
  grep(pattern: string): Promise<GrepResult[]>;

  // 读取
  readContent(uri: string, level?: 'L0' | 'L1' | 'L2'): Promise<string>;

  // 会话
  extractMemories(sessionId: string): Promise<Memory[]>;
  compactSession(sessionId: string): Promise<void>;
}

interface FindOptions {
  scope?: string;
  limit?: number;
  level?: 'L0' | 'L1' | 'L2';
}
```

### 3.2 分层上下文

```
┌─────────────────────────────────────────┐
│  L0 - 完整内容 (Full Content)            │
│  • 原始对话、代码、文档                   │
│  • 无损存储                              │
│  • Token 消耗高                          │
└────────────────────┬────────────────────┘
                     │ 压缩
                     ▼
┌─────────────────────────────────────────┐
│  L1 - 摘要内容 (Summary)                 │
│  • 结构化摘要                            │
│  • 关键点提取                            │
│  • Token 消耗中等                        │
└────────────────────┬────────────────────┘
                     │ 压缩
                     ▼
┌─────────────────────────────────────────┐
│  L2 - 关键词/索引 (Keywords)             │
│  • 关键词和元数据                        │
│  • 仅用于检索                            │
│  • Token 消耗低                          │
└─────────────────────────────────────────┘
```

### 3.3 数据流

```
添加资源
    │
    ├─► 存储原始内容 (L0)
    │
    ├─► 生成摘要 (L1)
    │       │
    │       └─► LLM 调用或规则提取
    │
    └─► 提取关键词 (L2)
            │
            └─► TF-IDF 或 Embedding

搜索
    │
    ├─► 向量搜索 (L2)
    │
    ├─► 相似度排序
    │
    └─► 返回结果 + L0/L1 内容
```

### 3.4 适配器模式

```typescript
interface VikingAdapter {
  add(uri: string, content: string): Promise<void>;
  find(query: string): Promise<FindResult[]>;
  read(uri: string): Promise<string>;
}

// 本地服务器适配器
class LocalServerAdapter implements VikingAdapter {
  private client: VikingHttpClient;

  async add(uri: string, content: string) {
    return this.client.addResource(uri, content);
  }
}

// 远程服务器适配器
class RemoteServerAdapter implements VikingAdapter {
  private client: VikingHttpClient;
  private baseUrl: string;

  constructor(baseUrl: string) {
    this.baseUrl = baseUrl;
    this.client = new VikingHttpClient(baseUrl);
  }
}

// 本地存储适配器（降级方案）
class LocalStorageAdapter implements VikingAdapter {
  private storage: Storage;

  async add(uri: string, content: string) {
    const resources = JSON.parse(this.storage.getItem('viking_resources') || '{}');
    resources[uri] = { content, timestamp: Date.now() };
    this.storage.setItem('viking_resources', JSON.stringify(resources));
  }
}
```

---

## 四、预期作用

### 4.1 用户价值

| 价值类型 | 描述 |
|---------|------|
| 隐私保护 | 数据本地存储 |
| 记忆持久 | 跨会话保持上下文 |
| 智能检索 | 语义搜索更精准 |

### 4.2 系统价值

| 价值类型 | 描述 |
|---------|------|
| 架构收益 | 解耦的上下文管理 |
| 可维护性 | 适配器模式易于扩展 |
| 可扩展性 | 支持新的存储后端 |

### 4.3 成功指标

| 指标 | 基线 | 目标 | 当前 |
|------|------|------|------|
| 搜索命中率 | 50% | 90% | 85% |
| 检索延迟 | - | <200ms | 150ms |
| 隐私合规 | - | 100% | 100% |

---

## 五、实际效果

### 5.1 已实现功能

- [x] 本地服务器模式
- [x] 远程服务器模式
- [x] 本地存储降级
- [x] 资源 CRUD
- [x] 语义搜索
- [x] L0/L1/L2 分层
- [x] 会话压缩
- [x] Tauri sidecar 管理

### 5.2 测试覆盖

- **单元测试**: 15+ 项 (viking-adapter.test.ts)
- **集成测试**: 完整流程测试
- **覆盖率**: ~85%

### 5.3 已知问题

| 问题 | 严重程度 | 状态 | 计划解决 |
|------|---------|------|---------|
| 本地服务器启动较慢 | 低 | 已知 | - |
| 向量搜索精度依赖 Embedding | 中 | 待优化 | Q2 |

### 5.4 用户反馈

本地部署让人放心隐私，语义搜索效果不错。

---

## 六、演化路线

### 6.1 短期计划（1-2 周）
- [ ] 优化本地服务器启动速度
- [ ] 添加更多 Embedding 选项

### 6.2 中期计划（1-2 月）
- [ ] 可视化上下文图谱
- [ ] 自动上下文迁移

### 6.3 长期愿景
- [ ] 分布式上下文存储
- [ ] 跨设备同步

---

## 七、头脑风暴笔记

### 7.1 待讨论问题
1. 如何处理上下文的版本控制？
2. 是否需要支持上下文共享？

### 7.2 创意想法
- 上下文市场：共享有价值的上下文
- 智能压缩：根据重要性动态调整压缩率
- 上下文血缘：追踪上下文的来源和演化

### 7.3 风险与挑战
- **技术风险**: Embedding 质量影响搜索
- **资源风险**: 本地服务器资源消耗
- **缓解措施**: 可选功能，降级方案完善