05-建议的源码阅读路线

建议的源码阅读路线

第一阶段：先学会“用户怎么用它”

目标

不要一开始就研究底层实现，先搞懂用户视角。

看这些文件

1. README.md
2. examples/quick_start.py
3. pyproject.toml

学完后应该会回答

• OpenViking 是干嘛的
• 它怎么安装
• 它依赖什么模型能力
• 它怎么本地跑起来

第二阶段：搞懂 Python 公开接口

看这些文件

1. openviking/__init__.py
2. openviking/sync_client.py
3. openviking/async_client.py

学完后应该会回答

• OpenViking 默认指向谁
• 同步接口和异步接口关系是什么
• 本地模式和 HTTP 模式差别是什么

第三阶段：搞懂能力模块怎么分

优先看这些目录

• openviking/session/
• openviking/resource/
• openviking/retrieve/
• openviking/storage/
• openviking/service/
• openviking/server/

学完后应该会回答

• 资源怎么进入系统
• 检索怎么做
• session 怎么管理
• 存储层和服务层怎么分工

第四阶段：再看高级内容

再去看这些

• openviking/pyagfs/
• crates/ragfs/
• crates/ragfs-python/
• src/
• docs/design/
• benchmark/
• bot/

为什么放后面

因为这些更偏：

• 底层能力
• 性能 / 编译
• 跨语言绑定
• 工程扩展
• 产品化应用层

适合小白的实际学习顺序

如果你今天只想开始，不要贪多：

Day 1

• 看 README.md
• 跑读 examples/quick_start.py
• 看 openviking/__init__.py

Day 2

• 看 sync_client.py
• 看 async_client.py
• 把公开 API 抄一遍

Day 3

• 选一个主题继续：
  • session
  • resource
  • retrieve

一句话建议

对小白来说，先从“怎么用”入手，再去理解“怎么实现”，会比直接啃 storage 或 Rust/C++ 代码轻松很多。