OpenViking · 中文源码精读教程

OpenViking · 中文源码精读教程

文件系统漫游:像 ls/tree/find 一样漫游 Agent 的上下文数据库

这本教程讲什么

这是一份带读源码的 OpenViking 精读教程。

OpenViking(v0.4.9,火山引擎/字节跳动开源,AGPLv3)是 AI Agent 的上下文数据库(Context Database for AI Agents),有论文支撑(VikingMem,VLDB 2026)。它回答的是 Agent 工程当下最热的问题:Agent 的上下文该怎么存、怎么找、怎么省 token?

它的答案是一个范式级创新:把 Agent 的记忆(Memory)、资源(Resource)、技能(Skill)统一组织成 viking:// 协议下的虚拟文件系统——Agent 用 ls/tree/find/grep 这些文件系统操作确定性定位上下文,而不是查询黑盒向量库。三大卖点:①L0/L1/L2 三层分级加载(摘要/概览/详情按需加载,省 token);②目录递归检索(先定位最高分目录再逐层下钻,结果带语境且轨迹可观测可调试);③会话自动沉淀为长期记忆(异步提取用户偏好与 Agent 经验)。

工程体量约 83 万行:Python 约 49 万(核心 17.2 万+测试 18.4 万+VikingBot 5.5 万)、Rust 约 9.9 万(ragfs 聚合文件系统+ov_cli)、TS 约 8.8 万(web-studio+SDK)、C++ 约 1.39 万(abi3 原生向量引擎含 SIMD)。中文文档是一等公民(docs/zh 86 页),官方 benchmark 可复现(LoCoMo 基准 24-57%→80-83%)。

💡 核心心法:OpenViking 的精髓是**"把上下文当文件管理"——目录结构即语义(分类清晰才找得到)、分层加载即经济(L0 摘要 100 token 换 L2 全文 1 万 token 的试探成本)、检索轨迹即可观测(每一步 ls/find 都有日志可调试)。本教程采用文件系统漫游式**:像老派系统管理员一样,用 ls(看有什么)→tree(看结构)→find(按需定位)→grep(深挖细节)的姿势漫游这套上下文数据库,每章是一个漫游动作,沿途拆解源码。

漫游地图(全书主线)

九章漫游路径

第 1 章 OpenViking 全貌与文件系统范式 ── 定位/viking:///三卖点
第 2 章 漫游起点:URI 与上下文树 ── viking://协议/Context 树/空间划分
第 3 章 分层加载:L0/L1/L2 ── abstract/overview sidecar/按需加载
第 4 章 ★ 目录递归检索 ── HierarchicalRetriever/带语境检索/hotness
第 5 章 ★ 会话沉淀记忆 ── 异步提取/patch-merge/hotness 评分
第 6 章 资源入库:多模态解析 ── PDF/Office/OCR/ASR/代码 AST
第 7 章 存储分层与原生引擎 ── C++索引/RAGFS/4种向量后端
第 8 章 生态与服务 ── FastAPI/MCP/VikingBot/Web Studio/SDK
第 9 章 基准复现与全书回顾 ── LoCoMo/评测/部署/全书回顾
​

章节目录

第 1 章 OpenViking 全貌与文件系统范式
OpenViking 是什么(火山引擎/上下文数据库/VLDB 2026 论文);三大痛点(黑盒向量库检索不带语境/token 浪费/记忆不可沉淀);文件系统范式(ls/tree/find/grep 替代向量查询);三大卖点预览(L0-L2 分层/目录递归检索/会话沉淀记忆);体量地图(83 万行:Py+Rust+TS+C++);AGPLv3 协议提示。

第 2 章 漫游起点:URI 与上下文树
viking:// 协议设计(URI 结构/空间划分:memory/resource/skill);core/context.py 与 building_tree.py(上下文树容器);skill_loader 与 mcp_converter(技能与 MCP 的统一);URI 校验;目录语义(分类清晰才找得到)。

第 3 章 分层加载:L0/L1/L2
三层分级模型(L0=abstract.md 摘要/L1=overview.md 概览/L2=原文详情);**sidecar 机制**(.abstract/.overview 文件与正文同目录);按需加载的 token 经济学(L0 100 token 试探 vs L2 1 万 token 全文);分层生成(入库时由 VLM 生成摘要与概览);docs/design 的 sidecar RFC。

第 4 章 ★ 目录递归检索(全书高潮之一)
retrieve/hierarchical_retriever.py 精读;先定位最高分目录→再逐层下钻(目录递归 vs 平铺 RAG);带语境检索(结果带目录路径语境);intent_analyzer 意图分析;rerank 重排;收敛轮次控制;检索轨迹可观测(每步 ls/find 有日志,可调试——黑盒向量库做不到)。

第 5 章 ★ 会话沉淀记忆(全书高潮之二)
session/memory 记忆提取流水线(extract_loop 提取/streaming_memory_updater 流式更新);patch-merge 合并(新记忆与旧记忆的合并策略);memory_lifecycle 的 hotness 评分(热记忆晋升/冷记忆沉降);auto-commit 策略(会话结束异步沉淀);compressor_v3 会话压缩;LoCoMo 基准 24-57%→80-83% 的实测;docs/design 的经验学习重设计 RFC。

第 6 章 资源入库:多模态解析
parse/ 多模态解析全家桶(PDF/Word/PPT/Excel/EPUB;图像 OCR;音频 ASR;视频;tree-sitter 代码 AST 十语言;gitignore;飞书文档);vlm.py(VLM 辅助解析);ingest 编排(orchestrator/poller/sources 递归网页爬取);入库时生成分层 sidecar。

第 7 章 存储分层与原生引擎
storage 双层(虚拟 FS viking_fs + 向量库);C++ 原生向量引擎(src/ abi3 稳定 ABI/SIMD x86 检测/KV 持久化);RAGFS(Rust 聚合文件系统:shell/缓存/git 子系统/PyO3 绑定);4 种向量后端(local 内置/Volcengine VikingDB/HTTP/私有化);cuVS GPU 后端;ovpack 打包快照;事务与 queuefs。

第 8 章 生态与服务
server(FastAPI:路由/auth/oauth/MCP endpoint/API keys);MCP 接入(任何支持 MCP 的 agent 都能用 OpenViking);VikingBot(bot/ 多渠道 Agent 框架:飞书/Slack/Telegram 网关+沙箱执行+子 agent,配 gateway-routing 图);web-studio(React 管理控制台+playground);三语言 SDK(Go/Python/TS);agent 插件生态(claude-code/codex/cursor 等 8+ 记忆插件);crypto/privacy(加密与隐私)。

第 9 章 基准复现与全书回顾
benchmark/ 八个基准(LoCoMo 长对话记忆/tau2/skillsbench/RAG/vectordb_perf);复现脚本与指标;observability(检索轨迹/grafana dashboard 配图);部署(docker-compose Caddy+HTTPS/Helm);全书回顾:漫游九站串讲;OpenViking 核心哲学四点(文件系统范式确定性/分层加载 token 经济/检索轨迹可观测/会话自动沉淀);下一步建议。

适合读者

• 构建 Agent 记忆/上下文系统的 AI 工程师(当下最热方向)
• 对"文件系统范式替代向量库"这种范式级创新感兴趣的架构师
• 研究 RAG 检索质量、Agent 长期记忆的研究者
• 系统编程爱好者(Rust ragfs/C++ 原生引擎/PyO3 绑定)
• 中文开发者(官方中文文档一等公民,微信/飞书社区)

前置知识:Python 基础;RAG/向量检索基本概念(embedding/相似度);可选:Rust/C++(第 7 章)、文件系统概念。

注意事项

• 文件系统漫游主线:每章对应一个漫游动作(ls/tree/find/grep/沉淀)
• 源码带行号引用如 hierarchical_retriever.py:120
• > 💡 **漫游要点**:... 标注每节精华
• > ⚠️ **注意**:... 标注 AGPLv3 传染性/火山云依赖点/版本迭代快

关于源码版本

对照源码来自 OpenViking-main(主项目 AGPLv3,火山引擎),版本 v0.4.9(2026-07,changelog 为准)。核心 openviking/(约 17.2 万行)、crates/ Rust 约 9.9 万、src/ C++ 约 1.39 万、bot/ VikingBot 约 5.5 万、web-studio/ React 约 8.8 万。官方中文文档 docs/zh 86 页可作使用层补充;docs/design 20 篇 RFC 是进阶深水区。