企业官网建设流程全解析

OpenViking 路线图全解析：从三层上下文模型到 Agent 记忆生态的落地版图

【免费下载链接】OpenVikingSelf-evolving Context Database for AI Agents. Unify Agent Memory, Knowledge RAG and Skills.项目地址: https://gitcode.com/GitHub_Trending/op/OpenViking

OpenViking 是一个面向 AI Agent 的自进化上下文数据库，以"统一 Agent 记忆、知识 RAG 与技能"为使命。本文基于仓库中 docs/zh/about/03-roadmap.md 的路线图文档，逐项梳理其已完成功能与未来计划，并对照仓库源码与配套概念文档给出实现级佐证，帮助读者系统理解 OpenViking 当前的技术版图、设计取舍与演进方向。

一、核心基础设施：一切内容的统一地基

路线图把 OpenViking 的地基总结为五件事：三层信息模型、Viking URI 寻址、双层存储、异步/同步客户端、QueueFS 存储后端。这五者构成了"内容如何组织、如何寻址、如何存储、如何访问"的完整闭环。

1.1 三层信息模型（L0/L1/L2）

OpenViking 使用 L0/L1/L2 三层信息模型，在检索效率、导航能力和原始内容完整性之间取得平衡。其语义定义可在源码 openviking/core/context.py 中找到：

class ContextLevel(int, Enum): """Context level (L0/L1/L2) for vector indexing""" ABSTRACT = 0 # L0: abstract OVERVIEW = 1 # L1: overview DETAIL = 2 # L2: detail/content

各层级的定位与默认正文上限如下（完整定义见 docs/zh/concepts/03-context-layers.md）：

关键设计是：L0/L1 是目录级语义 sidecar，描述一个目录而非为每个文件生成同名伴生文件；文件摘要会聚合到所在目录的 L1 中。正文上限由semantic.abstract_max_chars与semantic.overview_max_chars配置，限制只作用于 Markdown 正文，不截断 sidecar 元数据。L0/L1 通常成对生成，但允许只存在其中一个——例如mkdir()会先创建 L0，未传入description时用目录名作默认正文。

从 docs/zh/concepts/03-context-layers.md 可以看到一个已完成语义处理的目录结构：

viking://resources/docs/auth/ ├── .abstract.md # L0，隐藏的目录级 sidecar ├── .overview.md # L1，隐藏的目录级 sidecar ├── oauth.md # L2，完整内容 ├── jwt.md # L2，完整内容 └── api-keys.md # L2，完整内容

普通ls默认隐藏.abstract.md和.overview.md，且不要依赖"每个目录始终具有两个 sidecar"的假设。新生成的 L0/L1 使用最小 OKF Markdown 格式（YAML frontmatter + 可见正文），frontmatter 中记录directory、source、generated_by、freshness等元数据，其中 embedding 输入只采用正文与白名单字段directory，保证向量化输入的一致性。

1.2 Viking URI 寻址系统

所有上下文对象统一用viking://<scope>/<path>格式的 URI 标识。URI 解析器实现在 openviking_cli/utils/uri.py，其文档注释给出了完整的作用域划分：

• resources：独立资源 / 客观知识，生命周期长期，account 全局可见；
• user：用户级数据（含 session），长期 / 会话生命周期，仅当前用户可见；
• agent：agent 能力与配置（技能、端点、工具、支付等），account 全局可见；
• queue / temp / upload：内部实现作用域，公开 API 的 URI 参数不能直接访问；
• session：user session 路径的向后兼容别名，新 session 数据位于viking://user/{user_id}/sessions；
• ~：当前调用方用户根目录的服务端别名，viking://~/memories/note.md展开为viking://user/{user_id}/memories/note.md，且仅在路径第 0 段生效、响应始终回显 canonical 形式。

公开 API 和 CLI 的文件系统/内容操作接受公开作用域resources、user、agent以及根 URIviking://。服务端对用户提交的 URI 进行严格校验，见 openviking/core/uri_validation.py 中的validate_viking_uri/validate_request_viking_uri：非法作用域、空 URI、权限不足都会抛出InvalidURIError或PermissionDeniedError。完整的目录树示例与 URI 用法见 docs/zh/concepts/04-viking-uri.md。

1.3 双层存储（AGFS + 向量索引）

OpenViking 将内容存储与索引存储分离：

（注：AGFS 已重写为 Rust 实现 RAGFS，源码位于 crates/ragfs。）分层设计带来四点收益：职责清晰（向量库只检索、AGFS 只存储）、内存优化（向量库不存文件内容）、单一数据源（所有内容从 AGFS 读取）、独立扩展（两层可分别扩容）。

向量库 Context 集合 schema 包含id、uri、parent_uri、context_type、is_leaf、vector、sparse_vector、abstract、name、description、created_at、active_count等字段，索引策略为flat_hybrid混合索引 + cosine 距离 + int8 量化，后端支持local、http、volcengine（火山引擎 VikingDB）。VikingFS 自动维护内容与向量的一致性：rm()同步删除向量记录，mv()同步更新向量库中的uri与parent_uri。详见 docs/zh/concepts/05-storage.md。

1.4 异步/同步客户端与 QueueFS

• 客户端：OpenViking 同时提供 Python HTTP Client 与 Python HTTP Client SDK（见 openviking/client 与 sdk/python），并在openviking.core.context之上统一了 Context 数据模型（Context.to_dict()/from_dict()完成存储与反序列化）。
• QueueFS SQLite 存储后端：处理队列以 SQLite 为后端，相关实现集中在 openviking/storage/queuefs（如queue_manager.py、embedding_msg_converter.py、add_resource_processor.py），支撑资源入库、嵌入等异步任务的排队处理。

二、资源管理与多模态解析

2.1 文本资源管理与自动 L0/L1 生成

资源管理支持 Markdown、HTML、PDF 等文本资源，入库后自动完成 L0/L1 语义生成与带向量索引的语义搜索，并支持资源关联与链接（Context.related_uri）、内容写入 API、Agent 命名空间管理。

L0/L1 的生成由 SemanticProcessor自底向上处理目录：

文件摘要 → 叶子目录 L1 → 叶子目录 L0 → 父目录 → namespace 根边界

子目录 L0 聚合到父目录 L1；多模态文件先生成文本摘要，再作为普通文件摘要参与所在目录的 L0/L1 生成（不会为每个图片/音频/视频创建 per-file sidecar）。相关概念见 docs/zh/concepts/06-extraction.md。

2.2 多模态解析能力

路线图列出的解析器矩阵，在 openviking/parse/parsers 下均有对应实现：

• 图像 OCR 与解析：media/image.py，结合 VLM 视觉理解（prompt 模板见 openviking/prompts/templates/vision/image_understanding.yaml）；
• 音频转写（Whisper ASR）：media/audio.py；
• 视频解析：media/相关模块；
• PDF 书签提取：PDF 解析器；
• Word / PowerPoint / Excel / EPub / ZIP 解析器：anydoc.py及文档类解析器；
• 代码文件解析：code/code.py（配套说明见 openviking/parse/parsers/code/README.md）；
• 飞书/Lark 文档解析器：openviking/parse/feishu_import.py。

统一解析入口通过 openviking/parse/parser_router.py 与 openviking/parse/registry.py 按文件类型路由到具体 parser，base_parser.py定义了 parser 基类与通用处理流。

三、检索体系：从find到search的两阶段链路

路线图把检索能力划分为四个层次：基本语义搜索（find）、带意图分析的上下文感知搜索（search）、基于会话的查询扩展、多供应商重排序流水线。其完整机制记录在 docs/zh/concepts/07-retrieval.md，整体流程为：

查询 → 意图分析 → 层级检索 → Rerank → 结果 ↓ ↓ ↓ TypedQuery 目录递归 精排评分

3.1 find() vs search()

3.2 意图分析（IntentAnalyzer）

实现位于 openviking/retrieve/intent_analyzer.py。IntentAnalyzer输入会话压缩摘要、最近 5 条消息与当前查询，输出 0~5 个TypedQuery（每个包含重写后的query、context_type（MEMORY/RESOURCE/SKILL）、intent、1-5 级priority）。查询风格上：skill 用动词开头（如"创建 RFC 文档"）、resource 用名词短语（如"RFC 文档模板"）、memory 用"用户XX"（如"用户的代码规范偏好"）。0 个查询意味着闲聊等无需检索的场景；多个查询则覆盖"技能 + 资源 + 记忆"的复合需求。意图分析模型可通过query_planner配置项单独指定，未设置时回退到vlm；针对特定微调模型还提供了专用 prompt（见QUERY_PLANNER_PROMPT_BY_MODEL）。

3.3 层级检索（HierarchicalRetriever）

核心实现位于 openviking/retrieve/hierarchical_retriever.py。检索流程为：按context_type确定根目录（MEMORY→viking://~/memories、RESOURCE→viking://resources、SKILL→viking://~/skills）→ 全局向量搜索定位起始目录 → 合并起始点并 Rerank 评分 → 优先队列递归搜索 → 转换为MatchedContext。

递归搜索采用分数传播：final_score = score_propagation_alpha * embedding_score + (1 - score_propagation_alpha) * parent_score，超过阈值则收集，目录继续入队递归；连续 3 轮 topk 不变即提前收敛。关键常量：MAX_CONVERGENCE_ROUNDS = 3、GLOBAL_SEARCH_TOPK = 10、MAX_PARALLEL_CHILD_SEARCHES = 4、DIRECTORY_DOMINANCE_RATIO = 1.2；retrieval.score_propagation_alpha默认为 1.0（仅使用子节点自身分数）。

3.4 多供应商重排序流水线

Rerank 在 THINKING 模式（search()默认）下对候选精排；若 rerank 返回无效结果或 API 调用失败，会回退到向量分数。供应商实现位于 openviking/models/rerank：OpenAI（openai_rerank.py）、LiteLLM（litellm_rerank.py）、Cohere（cohere_rerank.py）、Volcengine（volcengine_rerank.py），通过 openviking/models/rerank/base.py 的RerankClient统一调度，可配置阈值threshold与最大输入 token 数max_input_tokens。

四、会话与记忆：对话状态、自动记忆提取与 Working Memory V2

路线图在"会话与记忆"标题下列出：对话状态追踪、上下文和技能使用追踪、自动记忆提取、使用 LLM 的记忆去重、会话归档和压缩、Working Memory V2 及冷存储归档。

• 会话生命周期：创建 → 交互 → 提交。commit()为同步归档 + 异步后台摘要生成与记忆提取，返回task_id供get_task()轮询进度（pending/running/completed/failed）。API 细节见 docs/zh/concepts/08-session.md。
• Working Memory V2：压缩链路使用ov_wm_v2系列 prompt（openviking/prompts/templates/compression/ov_wm_v2.yaml、ov_wm_v2_update.yaml），配合会话压缩（compressor_v3.py）与归档（history/archive_*目录）实现记忆的持续演进；冷存储归档将低频记忆从热路径移出。
• 记忆提取策略：可通过memory_policy配置逐项开关（self、peer、memory_types、working_memory），解析与校验逻辑见 openviking/session/memory_policy.py，例如memory_policy.working_memory只支持enabled键，其余键会报错，字符串布尔值兼容旧行为但会产生FutureWarning。

五、技能：定义、存储、搜索与 MCP 自动转换

技能模块提供技能定义与存储（viking://agent/skills/...与viking://~/skills/...）、技能搜索与检索，以及 MCP 工具自动转换。

MCP 工具到技能的转换实现在 openviking/core/mcp_converter.py：mcp_to_skill()读取 MCP 工具定义中的name、description、inputSchema，生成带 YAML frontmatter 的 Markdown 技能文档（含 Parameters 与 Usage 段），is_mcp_format()通过是否含inputSchema字段判断输入是否为 MCP 工具格式。技能上下文还会在会话中被注入给 Agent（见 openviking/session/skill/session_skill_context_provider.py）。

六、多租户与安全

• 多租户支持与账户隔离：详见 docs/zh/concepts/11-multi-tenant.md；URI 中user、account_id、owner_user_id、owner_space字段在Context中显式建模（openviking/core/context.py），配合 ACL（docs/zh/concepts/15-acl.md）实现跨账户隔离与资源共享。
• 文件和文档加密：加密实现位于 openviking/crypto（config.py、encryptor.py、providers.py），概念说明见 docs/zh/concepts/10-encryption.md。
• 用户级隐私配置 API：隐私服务位于 openviking/privacy（service.py、models.py、helpers.py），支持技能提取、占位与恢复等细粒度隐私控制，见 docs/zh/concepts/13-privacy.md。
• API Key 认证：openviking/server/api_keys 实现，配合 openviking/server/auth 的认证体系与 OAuth（openviking/server/oauth）。

七、配置与供应商：可插拔的三类模型提供者

路线图强调三类可插拔提供者：Embedding、LLM、重排序，加上基于 YAML 的配置与安装向导。

7.1 Embedding 提供者

从 openviking/models/embedder/init.py 可确认完整矩阵：

模块还提供FailoverEmbedder（故障切换）与CompositeHybridEmbedder（稠密+稀疏组合）。LiteLLM 与 Gemini 为可选依赖（未安装时对应类置为None）。

7.2 LLM 与重排序提供者

LLM 提供者见 openviking/models 与 openviking_cli/utils/llm.py；重排序提供者见 3.4 节。所有配置统一走 YAML 文件（配置示例见仓库根目录 examples/ov.conf.example）。

7.3 安装向导（openviking-server init）

交互式安装向导实现在 openviking_cli/setup_wizard.py，引导用户完成模型选择与配置，对 macOS/Apple Silicon 初学者的本地 Ollama 部署做了针对性支持（内置check_ollama_running、get_ollama_models、ollama_pull_model、start_ollama等工具函数），并预设 Codex / Kimi / GLM 等 coding 模型模板。

八、Server 与 Client 架构、CLI

• HTTP Server（FastAPI）：openviking/server/app.py，路由按领域拆分在 openviking/server/routers（resources、filesystem、skills、sessions、retrieval、system、admin 等，对应 docs/zh/api 各接口文档）。
• 内置 MCP 端点：openviking/server/mcp_endpoint.py，让任何 MCP 客户端可直接消费 OpenViking 工具面。
• Web 控制台：web-studio（React/TypeScript 实现）。
• Python HTTP Client / SDK：openviking/client与 sdk/python。
• Rust CLI（ov命令）：crates/ov_cli（48 个 Rust 源文件），命令组约 40 个，覆盖隐私、搜索（ov find/ov search）、会话、资源（ov add-resource/ov add-memory/ov add-skill）、文件系统（ov ls/ov rm）与管理操作，并带TUI 文件系统浏览器。按 docs/zh/agent-integrations/16-capability-reference.md 的能力矩阵，ov是唯一同时支持find/search显式检索、三类内容写入与直接删除的完整工具面。

九、Bot 集成与生态插件

• VikingBot 框架：bot/vikingbot（agent、channels、bus、cron、hooks 等模块），配套文档见 docs/zh/concepts/15-vikingbot.md。
• 飞书/Lark 频道：bot/vikingbot/channels中的 feishu/lark 实现。
• Telegram 频道：bot/vikingbot/channels中的 telegram 实现。
• OpenClaw 插件（编程 Agent 上下文引擎）：examples/openclaw-plugin，提供memory_recall、ov_search、memory_store、add_skill等 15 个工具并支持 ContextEngine 压缩接管。
• Claude Code 记忆插件：examples/claude-code-memory-plugin。
• Codex 记忆插件：examples/codex-memory-plugin。

生态上还包含 cursor、trae、zcode、opencode、pi、dsh、hermes、Open WebUI、LangChain 等集成（examples 与 integrations），MCP 型 harness 的工具面由服务端统一定义、经代理连接~/.openviking/ovcli.conf凭据后获得一致体验。

十、可观测性与部署

• Prometheus 指标：指标体系见 openviking/metrics（27 个 collector、14 个 datasource、核心 core/ 与 exporters/），并配套 Grafana 仪表盘（examples/grafana）。
• OpenTelemetry 链路追踪：openviking/telemetry（14 个模块）。
• HTTP 可观测性中间件：openviking/observability/http_observability_middleware.py 及日志链路桥接log_trace_bridge.py。
• Docker 镜像与 Docker Compose：根目录 Dockerfile 与 docker-compose.yml，入口脚本见 docker/openviking-entrypoint.sh。
• Kubernetes Helm Chart：deploy/helm/openviking（8 个 YAML 模板 + 公共 tpl），另有 examples/k8s-helm。
• 云端 VikingDB 支持：向量库后端volcengine（见 openviking/storage/vikingdb_manager.py 与 docs/zh/concepts/05-storage.md）。

十一、未来计划与演进方向

路线图公开了三个明确的未来方向，欢迎通过 issue 提出建议与反馈：

1. 上下文管理：
   • 上下文修改对上层的传导更新（parent-bubbling 的自动化与一致性）；
   • 上下文的版本管理和回滚（参考 git 思路）。仓库中已有相关设计文档沉淀：docs/design/freshness-aware-parent-bubbling-design.md 与 docs/design/git-version-control-design.md，且 L0/L1 sidecar 的freshness元数据（total_entries/sampled_entries/unsampled_entries/pending_child_changes）与稳定采样机制已为传导更新的节流（合并、阈值或时间窗口）铺路（见 docs/zh/concepts/03-context-layers.md 中的 TODO 说明）。
2. 分布式存储后端：在现有 localfs/s3fs 单后端与多写（primary/backup）模式之上进一步演进，相关概念见 docs/zh/concepts/14-multi-write-storage.md。
3. 生态：更多 Agent 框架适配器，进一步扩大 harness 覆盖面。

十二、贡献

路线图同时是贡献指引：OpenViking 欢迎社区贡献以帮助实现这些目标，贡献规范见仓库根目录 CONTRIBUTING_CN.md。无论是实现未来计划中的上下文传导更新与版本管理、探索分布式存储后端，还是新增 Agent 框架适配器，都可以从 docs/zh 各概念文档与 tests 中已有的测试用例入手，理解现状后再动手。

延伸阅读：本文所涉概念均有对应文档可深入：架构概述、上下文层级、Viking URI、存储架构、检索机制、会话管理，以及完整 API 参考 docs/zh/api/01-overview.md。

【免费下载链接】OpenVikingSelf-evolving Context Database for AI Agents. Unify Agent Memory, Knowledge RAG and Skills.项目地址: https://gitcode.com/GitHub_Trending/op/OpenViking