03-核心代码入口

OpenViking 核心代码入口

1. openviking/__init__.py

这是 Python 包入口。

它做了什么

• 导出公开 API
• 把 OpenViking 指向 SyncOpenViking
• 同时暴露：
  • SyncOpenViking
  • AsyncOpenViking
  • SyncHTTPClient
  • AsyncHTTPClient
  • Session

小白要点

当你写：

import openviking as ov
client = ov.OpenViking(...)

其实你拿到的是：

• SyncOpenViking

也就是默认的同步本地客户端。

2. openviking/sync_client.py

这个文件非常适合新手看，因为它很像“人类可读接口层”。

关键理解

SyncOpenViking 本身不是最底层实现。 它更像一个同步包装器：

• 内部实际持有 AsyncOpenViking
• 再通过 run_async(...) 把异步方法包装成同步方法

为什么这样设计

因为：

• 底层异步实现更统一
• 但很多用户更喜欢同步接口
• 所以项目同时满足两类使用习惯

你能从这个文件学到什么

从 SyncOpenViking 的方法列表，可以直接看出产品能力：

• session 管理
• message 管理
• resource 导入
• skill 导入
• 搜索 / 查找
• 读取摘要 / 概览 / 文件内容
• 写入内容

这比一头扎进底层 storage 更容易理解项目。

3. openviking/async_client.py

这是更接近真实执行逻辑的主客户端。

第一轮看到的重点

• AsyncOpenViking 被描述为 embedded mode only
• 它内部使用 LocalClient
• 有 singleton 逻辑
• 会负责初始化和资源生命周期

小白理解

你可以把它看成：

OpenViking 在本地模式下的主控制器。

4. openviking_cli/server_bootstrap.py

这是 openviking-server 命令的轻量入口。

它做了什么

• 处理 init 子命令
• 处理 doctor 子命令
• 预处理 --config
• 再转交给真正的服务启动逻辑

这说明什么

说明项目把“命令行入口”和“真正的服务逻辑”分开了，这是一种比较成熟的工程做法。

5. pyproject.toml

这个文件能告诉你项目的整体形态。

第一轮读到的关键信息

• Python 包名：openviking
• 描述：An Agent-native context database
• Python 版本：>=3.10
• 有 FastAPI / Uvicorn 依赖 → 说明能跑服务
• 有 OpenTelemetry 依赖 → 说明支持观测
• 有 tree-sitter 系列依赖 → 说明做代码/文本结构解析
• 有 CLI scripts：
  • ov
  • openviking
  • openviking-server
  • vikingbot

小白最推荐的源码阅读顺序

1. examples/quick_start.py
2. openviking/__init__.py
3. openviking/sync_client.py
4. openviking/async_client.py
5. openviking_cli/server_bootstrap.py
6. 再继续看 openviking/client/、resource/、retrieve/、session/