内容
# viking-go
OpenViking 的轻量级 Go 语言重实现版本 — 面向 AI 智能体的分层上下文数据库，具有长期记忆、知识检索和技能管理功能。
**单个二进制文件，约 14 MB，运行时内存占用 30–80 MB**
> [中文文档](README_CN.md)
## 架构
```
viking-go (31,000+ 行代码，98 个源文件，363 个测试)
├── cmd/viking-go/ # 命令行入口
├── pkg/
│ ├── uri/ # viking:// URI 解析与标准化
│ └── client/ # HTTP 及嵌入式客户端 SDK
└── internal/
├── config/ # JSON + 环境变量配置
├── context/ # 上下文模型（L0/L1/L2，类型，身份）
├── storage/ # SQLite + sqlite-vec 存储层
│ ├── backend.go # 多后端（SQLite/HTTP/内存）
│ ├── transaction.go # 路径级锁管理器及重做日志
│ └── filter.go # 过滤表达式（Eq/And/In/PathScope）
├── vikingfs/ # 本地文件系统（URI → 路径映射）
├── embedder/ # 多提供商嵌入及重排名
│ ├── embedder.go # OpenAI 兼容 + 提供商路由器
│ ├── voyage.go # Voyage AI 原生 API
│ ├── jina.go # Jina AI 原生 API
│ ├── cohere.go # Cohere 原生 API
│ └── rerank.go # 重排名器（OpenAI 兼容 + Cohere 原生）
├── llm/ # LLM 对话完成 + 工具调用
├── vlm/ # 视觉-语言模型（图像理解）
├── retriever/ # 分层 BFS 检索器 + 热点评分
├── indexer/ # 内容 → 向量管道
├── session/ # 会话管理，存档及压缩
│ ├── compressor.go # V1 基本内存提取
│ └── compressor_v2.go # V2 模式驱动，带有 ReAct 环路
├── memory/ # 内存提取，模式及合并
│ ├── mergeop/ # 字段合并策略（patch/immutable/sum）
│ ├── schema.go # YAML 驱动的内存类型注册
│ ├── generator.go # YAML → Go 结构体代码生成器
│ ├── extractor.go # 基于 LLM 的内存提取
│ └── deduplicator.go # 基于嵌入的重复数据删除
├── intent/ # LLM 驱动的查询规划
├── tree/ # 内存上下文树
├── bootstrap/ # 目录结构初始化
├── content/ # 内容写入协调器
├── prompts/ # 提示模板管理器（YAML 模板）
├── message/ # 消息模型及组装器
├── parse/ # 文档导入及解析（18+ 格式）
│ ├── ast_extract.go # 代码 AST 提取（9 种语言）
│ ├── diff_sync.go # 增量目录同步
│ ├── parse_image.go # VLM 驱动的图像理解
│ ├── parse_audio.go # Whisper API 转录
│ ├── parse_video.go # ffmpeg + VLM 帧分析
│ ├── parse_feishu.go # Feishu/Lark 文档解析器
│ ├── parse_legacy_doc.go # 旧版 .doc（OLE2）解析器
│ └── registry.go # 解析器注册表
├── server/ # HTTP API 服务器（67 个端点）
│ ├── apikeys.go # 多密钥身份验证
│ ├── routes_pack.go # 打包导出/导入（.ovpack）
│ ├── routes_debug.go # 调试及向量检查
│ ├── routes_observer.go # 组件健康观察器
│ ├── routes_resources.go # 资源导入，带过滤
│ ├── routes_stats.go # 内存及会话统计
│ └── routes_tasks.go # 后台任务跟踪
├── mcpserver/ # MCP 协议服务器（streamable-http）
├── bot/ # OpenAI 兼容聊天 API，带有 RAG
├── console/ # Web 管理界面（嵌入式 SPA）
├── watch/ # 目录/URL/Git 监视及同步
├── agent/ # 智能体生命周期桥接（钩子）
├── queue/ # 异步处理队列
│ ├── queue.go # 嵌入工作池
│ ├── semantic.go # 语义 DAG 执行器
│ ├── named_queue.go # 命名队列，带状态跟踪
│ └── queue_manager.go # 多队列管理器
├── eval/ # RAGAS 风格的检索及 RAG 评估
├── skill/ # SKILL.md 解析器 + MCP → 技能转换
├── integrations/ # Langfuse LLM 跟踪
├── observer/ # 组件健康监测
├── resilience/ # 熔断器及重试
├── telemetry/ # 操作跟踪及运行时指标
└── metrics/ # Prometheus 格式的可观察性
```
## 主要功能
### 核心检索
- **分层 BFS 检索** — 跨 L0（摘要）、L1（概述）、L2（详细）级别的分数传播
- **向量搜索** — SQLite + sqlite-vec，用于稠密向量相似性
- **热点评分** — 访问频率 + 最近衰减，用于排名
- **重排名** — 可选的重排名器（OpenAI 兼容 + Cohere 原生）
### 内存系统
- **8 类结构化提取** — 配置文件、偏好、实体、事件、案例、模式、工具、技能
- **模式驱动** — YAML 定义，带有字段级合并操作（patch、immutable、sum）
- **ReAct 风格的编排** — CompressorV2，带有 LLM 驱动的多步骤提取
- **重复数据删除** — 基于嵌入的语义重复数据删除
- **代码生成** — 从 YAML 模式定义自动生成 Go 结构体
### 文档解析（18+ 格式）
| 格式 | 解析器 | 备注 |
|--------|--------|-------|
| Markdown | 内置 | 分节拆分，元数据提取 |
| HTML | 内置 | 内容提取，标签剥离 |
| PDF | 内置 | 文本提取 |
| Word (.docx) | 内置 | 基于 XML 的提取 |
| Word (.doc) | 旧版解析器 | OLE2 字节级分析 |
| Excel | 内置 | 表格/单元格提取 |
| EPUB | 内置 | 章节提取 |
| PowerPoint | 内置 | 幻灯片提取 |
| ZIP | 内置 | 递归存档提取 |
| 代码 | AST 提取 | Python、JS、TS、Java、Rust、Ruby、C#、Go、PHP、C/C++ |
| 文本 | 内置 | 普通文本，带有编码检测 |
| Feishu/Lark | 内置 | 导出 JSON → Markdown 转换 |
| 图片 | VLM 驱动 | jpg、png、gif、webp、bmp、tiff、svg |
| 音频 | Whisper API | mp3、wav、ogg、flac、m4a、wma、aac、opus |
| 视频 | ffmpeg + VLM | mp4、avi、mkv、mov、wmv、flv、webm |
### 嵌入提供商
| 提供商 | 类型 | 备注 |
|----------|------|-------|
| OpenAI | 原生 API | 默认，text-embedding-3-small |
| Voyage AI | 原生 API | voyage-3，voyage-code-3 |
| Jina AI | 原生 API | jina-embeddings-v3 |
| Cohere | 原生 API | embed-english-v3.0 |
| SiliconFlow | OpenAI 兼容 | Qwen3-8B 嵌入 |
| 任意 OpenAI 兼容 | API 代理 | 通过 api_base 配置 |
### AI 集成
- **MCP 服务器** — 通过 streamable-http 协议的 11 种工具
- **Bot OpenAPI** — OpenAI 兼容的 `/v1/chat/completions`，带有内置 RAG（流式 + 非流式）
- **智能体桥接** — 透明内存注入/提取的生命周期钩子
- **技能加载器** — 解析 SKILL.md 文件并转换 MCP 工具为技能定义
- **Langfuse 跟踪** — 异步缓冲 LLM 调用跟踪
- **VLM 支持** — OpenAI Vision API 兼容的图像理解
### 基础设施
- **多租户** — 账户 + owner_space 隔离
- **API 密钥身份验证** — 多密钥管理
- **监视与同步** — 监视本地目录、HTTP URL 或 Git 仓库
- **评估框架** — RAGAS 风格的指标（Precision@K、Recall@K、MRR、NDCG、Faithfulness、Answer Correctness）
- **可观察性** — Prometheus 指标、Langfuse 跟踪、组件健康监测
- **弹性** — 熔断器 + 指数级回退重试
- **控制台 UI** — 嵌入式 Web 仪表盘（Dashboard、Search、Browse、Watch、Metrics）
## 快速开始
### Docker（推荐）
```bash
git clone https://github.com/XimilalaXiang/viking-go.git
cd viking-go
OPENAI_API_KEY=sk-xxx docker-compose up -d
# 健康检查
curl http://localhost:6920/health
# 控制台 UI
open http://localhost:6920/console/
```
### 从源码构建
```bash
# 需要 Go 1.24+ 和 CGO（用于 sqlite3）
go build -o viking-go ./cmd/viking-go/
# 默认运行（端口 6920，数据在 ~/.viking-go/data）
./viking-go
# 自定义配置
./viking-go --config config.json --port 6920
```
### MCP 客户端配置
将以下内容添加到您的 MCP 客户端配置（Claude Desktop、Cursor 等）：
```json
{
"mcpServers": {
"viking-go": {
"type": "streamableHttp",
"url": "http://127.0.0.1:6920/mcp"
}
}
}
```
## 配置
创建 `config.json`:
```json
{
"server": {
"host": "0.0.0.0",
"port": 6920,
"auth_mode": "dev",
"mcp_enabled": true,
"mcp_path": "/mcp"
},
"storage": {
"data_dir": "/data",
"db_path": "/data/viking.db"
},
"embedding": {
"provider": "voyage",
"model": "voyage-3",
"api_key": "pa-...",
"dimension": 1024
},
"rerank": {
"provider": "cohere",
"model": "rerank-english-v3.0",
"api_key": "...",
"threshold": 0.3
},
"llm": {
"provider": "openai",
"model": "gpt-4o-mini",
"api_key": "sk-...",
"api_base": "https://api.openai.com/v1"
}
}
```
### 嵌入提供商示例
```json
// Voyage AI
{ "provider": "voyage", "model": "voyage-3", "api_key": "pa-...", "dimension": 1024 }
// Jina AI
{ "provider": "jina", "model": "jina-embeddings-v3", "api_key": "jina_...", "dimension": 1024 }
// Cohere
{ "provider": "cohere", "model": "embed-english-v3.0", "api_key": "...", "dimension": 1024 }
// SiliconFlow（Qwen）
{ "provider": "openai", "model": "Qwen/Qwen3-8B", "api_key": "sk-...", "api_base": "https://api.siliconflow.cn/v1", "dimension": 4096 }
// OpenAI
{ "provider": "openai", "model": "text-embedding-3-small", "api_key": "sk-...", "dimension": 1536 }
```
环境变量覆盖：`OPENAI_API_KEY`，`VIKING_DATA_DIR`。
## MCP 工具
| 工具 | 描述 |
|------|-------------|
| `query` | 分层目录递归检索（内存、资源、技能） |
| `search` | 平面语义向量搜索 |
| `add_resource` | 写入内容 + 自动索引（异步通过队列） |
| `read` | 在 L0/L1/L2 详细级别读取内容 |
| `list_directory` | 浏览知识库结构 |
| `tree` | 带有摘要的目录树 |
| `status` | 系统统计 |
| `watch_create` | 创建监视任务（本地目录、URL 或 Git 仓库） |
| `watch_list` | 列出监视任务 |
| `watch_cancel` | 取消监视任务 |
| `queue_status` | 嵌入队列状态 |
## REST API（67 个端点）
<details>
<summary>点击展开完整 API 参考</summary>
### 健康与状态
| 方法 | 端点 | 描述 |
|--------|----------|-------------|
| GET | `/health` | 健康检查 |
| GET | `/api/v1/system/status` | 系统统计 |
| GET | `/metrics` | Prometheus 格式的指标 |
### 搜索
| 方法 | 端点 | 描述 |
|--------|----------|-------------|
| POST | `/api/v1/search/find` | 带有 BFS 的分层检索 |
| POST | `/api/v1/search/search` | 直接向量搜索 |
### 内容
| 方法 | 端点 | 描述 |
|--------|----------|-------------|
| GET | `/api/v1/content/read` | 通过 URI 读取内容 |
| GET | `/api/v1/content/abstract` | 读取 L0 摘要 |
| GET | `/api/v1/content/overview` | 读取 L1 概述 |
| POST | `/api/v1/content/write` | 写入内容（L0/L1/L2） |
| POST | `/api/v1/content/reindex` | 重新索引目录 |
### 文件系统
| 方法 | 端点 | 描述 |
|--------|----------|-------------|
| GET | `/api/v1/fs/ls` | 列出目录内容 |
| GET | `/api/v1/fs/tree` | 递归树列表 |
| GET | `/api/v1/fs/stat` | 文件/目录信息 |
| POST | `/api/v1/fs/mkdir` | 创建目录 |
| POST | `/api/v1/fs/rm` | 删除文件/目录 |
| POST | `/api/v1/fs/mv` | 移动/重命名 |
### 资源
| 方法 | 端点 | 描述 |
|--------|----------|-------------|
| POST | `/api/v1/resources` | 添加资源（路径/URL/临时，带过滤） |
| POST | `/api/v1/resources/temp_upload` | 上传临时文件 |
### 打包（导出/导入）
| 方法 | 端点 | 描述 |
|--------|----------|-------------|
| POST | `/api/v1/pack/export` | 导出为 .ovpack 存档 |
| POST | `/api/v1/pack/import` | 导入 .ovpack 存档 |
### 调试
| 方法 | 端点 | 描述 |
|--------|----------|-------------|
| GET | `/api/v1/debug/health` | 存储健康检查 |
| GET | `/api/v1/debug/vector/scroll` | 分页向量列表 |
| GET | `/api/v1/debug/vector/count` | 向量记录计数 |
### 观察者
| 方法 | 端点 | 描述 |
|--------|----------|-------------|
| GET | `/api/v1/observer/queue` | 队列健康 |
| GET | `/api/v1/observer/storage` | 存储健康 |
| GET | `/api/v1/observer/models` | 模型可用性 |
| GET | `/api/v1/observer/system` | 完整系统健康 |
### 统计
| 方法 | 端点 | 描述 |
|--------|----------|-------------|
| GET | `/api/v1/stats/memories` | 按类别的内存计数 |
| GET | `/api/v1/stats/sessions/{id}` | 会话提取统计 |
### 任务
| 方法 | 端点 | 描述 |
|--------|----------|-------------|
| GET | `/api/v1/tasks` | 列出后台任务 |
| GET | `/api/v1/tasks/{id}` | 获取任务状态 |
### 关系
| 方法 | 端点 | 描述 |
|--------|----------|-------------|
| GET | `/api/v1/relations` | 列出关系 |
| POST | `/api/v1/relations/link` | 创建关系 |
| DELETE | `/api/v1/relations/link` | 删除关系 |
### 会话
| 方法 | 端点 | 描述 |
|--------|----------|-------------|
| POST | `/api/v1/sessions` | 创建会话 |
| GET | `/api/v1/sessions` | 列出会话 |
| GET | `/api/v1/sessions/{id}` | 获取会话信息 |
| GET | `/api/v1/sessions/{id}/context` | 会话消息 |
| POST | `/api/v1/sessions/{id}/commit` | 存档 & 清理 |
| DELETE | `/api/v1/sessions/{id}` | 删除会话 |
### 监视
| 方法 | 端点 | 描述 |
|--------|----------|-------------|
| POST | `/api/v1/watch` | 创建监视任务 |
| GET | `/api/v1/watch` | 列出监视任务 |
| DELETE | `/api/v1/watch/{id}` | 取消监视任务 |
### 智能体桥接
| 方法 | 端点 | 描述 |
|--------|----------|-------------|
| POST | `/api/v1/agent/start` | 为智能体检索上下文 |
| POST | `/api/v1/agent/end` | 提取内存 & 存档 |
| POST | `/api/v1/agent/compact` | 提取后压缩 |
### 机器人（OpenAI 兼容聊天）
| 方法 | 端点 | 描述 |
|--------|----------|-------------|
| POST | `/v1/chat/completions` | 带有 RAG 的聊天（流式/非流式） |
| POST | `/bot/chat` | 聊天完成的别名 |
### 控制台
| 路径 | 描述 |
|------|-------------|
| `/console/` | Web 管理仪表盘 |
| `/console/api/v1/*` | 控制台 API 代理 |
</details>
## URI 方案
```
viking://{scope}/{space}/{path...}
范围：user、agent、shared、session、resources
示例：
viking://user/alice/memories/profile.md
viking://agent/alice-agent/memories/cases/case_001.md
viking://resources/obsidian/my-note.md
viking://session/default/sess_abc123/
```
## 存储模型
每个 VikingFS 目录存储三个级别的内容：
- **L0** (`.abstract.md`) — 一行摘要，用于 BFS 评分
- **L1** (`.overview.md`) — 中等详细程度的概述
- **L2** (`content.md`) — 完整内容
关系存储为 `.relations.json` 文件，以双向方式链接 URI。
## 测试
```bash
go test ./... -v -count=1
```
363 个测试，分布在 23 个包中。
## 依赖
- [github.com/mattn/go-sqlite3](https://github.com/mattn/go-sqlite3) — SQLite3 驱动（CGO）
- [github.com/google/uuid](https://github.com/google/uuid) — UUID 生成
- [github.com/mark3labs/mcp-go](https://github.com/mark3labs/mcp-go) — MCP 协议（streamable-http）
- [gopkg.in/yaml.v3](https://gopkg.in/yaml.v3) — YAML 解析
可选运行时：
- [sqlite-vec](https://github.com/asg017/sqlite-vec) — SQLite 的向量相似性扩展
- OpenAI 兼容 API — 用于嵌入、重排名和 LLM 功能
- ffmpeg — 用于视频帧提取
- Whisper API — 用于音频转录
## 许可证
AGPL-3.0 — 参见 [LICENSE](LICENSE) 文件。
MCP 配置
以下是此 MCP Server 的配置信息，可直接复制到 Cursor 或其他 MCP 客户端中使用。
mcp.json
连接信息
猜你喜欢
暂无推荐服务器