1. 得到一个好的github仓库后的——学习路径规划(以最近要学的orbit为例)

目标仓库：https://github.com/gitlabhq/orbit-knowledge-graph

官方文档站：https://docs.gitlab.com/orbit/

规划日期：2026-09-17

说明：本文只讲「怎么学」------学习路线、阶段拆解、每步做什么、产出什么。不含动手实操记录。

〇、先给结论：截图里那条路径对不对？

对，但只对了 60%。它是一条很好的「入门路径」，不是一条「学习路径」。

一般的四步：① 丢给ai看看；②全方位看看是个啥思想；③啥架构；④能不能以这个东西搭建点玩意出来

建议	我的评价	说明
① 丢给 AI 看	⚠️ 半对	让 AI 做导读和提问很有效；但让 AI 替你总结整份 README，你会得到一份"看起来懂了其实没懂"的笔记。Orbit 这种"图谱 / 本体 / 查询 DSL"型项目，概念之间的关系才是核心，这个必须自己走一遍才能建立直觉。
② 全方位看看是个啥思想	✅ 完全正确	而且这恰恰是这个项目最值得学的地方。Orbit 的思想内核是「把 SDLC + 代码统一成一张属性图（property graph），作为 AI Agent 的 context API」。这个"思想"比代码本身更有迁移价值。
③ 看啥架构	✅ 完全正确	但要分层看：先看"两个 runtime"的顶层设计，再看索引流水线，最后才是 Rust crate 结构。一上来读 `crates/` 会劝退。
④ 能不能拿它搭点玩法出来	✅ 完全正确，且最重要	这是检验你是否真学会的唯一标准。而且好消息是：Orbit Local 是单二进制 + DuckDB，不需要 GitLab 账号、不需要任何服务端，纯本地就能跑起来，做玩法成本极低。
（缺失）	❌ 缺了一环	路径完全没有"动手跑"这一环。对 Orbit 来说这是致命的：它的价值 90% 体现在「你 query 出东西的那一刻」。补充：必须先本地跑通 Orbit Local，再谈思想和架构。

一句话修正版路径：

先把 Orbit Local 在本地跑通（建立感性认识）→ 再读思想与架构（建立理性认识）→ 最后用 MCP 把它接到 AI Agent 上做玩法（形成能力闭环）。

下面展开成可执行的路线。

一、学习前必须建立的「项目世界观」（先读这 300 字）

读懂这 5 句话，后面所有内容都有了挂靠点：

Orbit 是什么 ：GitLab 官方出的「软件全生命周期上下文图谱 （Software lifecycle context graph）」，官方定位一句话是 "unified context API for AI systems and human users"。
解决什么问题 ：AI Agent 要帮你改代码/查问题，但它不知道"这个函数被谁调用""这个 MR 动了哪些文件""这个漏洞是哪个 MR 引入的"。传统做法是让 Agent 一遍遍 grep、读文件、调 API------慢且不完整 。Orbit 的答案是：提前把所有结构关系建成图，让 Agent 一次 query 拿到答案。

它有两种形态（这是理解一切的钥匙）：

	Orbit Local	Orbit Remote
跑在哪	你的机器	GitLab 托管基础设施
索引范围	只有代码	SDLC + 代码（项目、用户、MR、流水线、漏洞...）
存储	DuckDB 单文件（`~/.orbit/graph.duckdb`）	ClickHouse（属性图）
查询方式	裸 SQL（DuckDB）	JSON Query DSL → 编译成 ClickHouse SQL
需要账号	不需要（安装后完全离线）	需要，且按查询做权限过滤
计费	不消耗 GitLab Credits	MCP / REST 查询消耗 Credits

两个 runtime 共享同一套东西 ：一个 Rust workspace + 一份 YAML ontology 。→ 这意味着：Local 和 Remote 的"本体/语义"是一致的，只是范围和存储不同。学 Local 的经验可以直接迁移到 Remote。
当前状态：Beta 。Query DSL 和 ontology 都可能变；Remote 还被 knowledge_graph feature flag 控制（需在顶级 group 上开启）。→ 不要基于它做生产依赖，学习/试验正合适。

关于许可证，有个必须提前说清的坑：仓库是 GitLab Enterprise Edition (EE) License ，不是常见的 MIT/Apache。学习、本地运行、照着思路自己实现都没问题；但如果想 fork 改造后商用/分发，必须先读 LICENSE.md 。GitHub 上那个仓库是 community fork ，官方主仓在 gitlab.com/gitlab-org/orbit/knowledge-graph。

二、总路线图（5 个阶段）

复制代码

阶段 0  建立认知地图          （1~2 小时）  ── 读什么、不读什么
   ↓
阶段 1  跑通 Orbit Local      （半天）      ── 建立感性认识 ★关键
   ↓
阶段 2  读懂「思想」          （1 天）      ── 属性图 / Ontology / Context API
   ↓
阶段 3  读懂「架构」          （2~3 天）    ── 两层架构 / 索引流水线 / 查询编译
   ↓
阶段 4  接上 AI Agent 做玩法  （1 天起）    ── MCP / skill / 自建查询
   ↓
阶段 5  （可选）深入源码 / 贡献

核心原则：不要按「文件目录顺序」学，要按「先用起来 → 再拆原理」的顺序学。

三、阶段 0：建立认知地图（1~2 小时）

做什么

只读这 4 个页面，不要扩散（官方文档站内容多，一上来全读必然迷失）：

仓库 README（GitHub 首页）------ 读 "Two ways to run Orbit" + "Architecture" 两节即可
https://docs.gitlab.com/orbit/ ------ 总的概念总览
https://docs.gitlab.com/orbit/indexed-data/ ------ 「它索引什么、不索引什么」（这张表极其重要，它决定了你后面所有玩法的边界）
https://docs.gitlab.com/orbit/local/how-it-works/ ------ Local 是怎么工作的

明确「这一阶段不读什么」（省你 10 小时）

❌ crates/ 里的 Rust 源码
❌ docs/design-documents/ 设计文档（阶段 3 再读）
❌ Remote 的 Query DSL 细节（阶段 3 再读）
❌ Cargo.toml / CI 配置 / 运维 runbook

产出

一张自己画的双形态对比图（Local vs Remote：范围 / 存储 / 查询 / 权限 / 计费）。画出来，说明你读进去了。

用 AI 的正确姿势（回应截图第①条）

截图说"丢给 AI 看看"------可以，但别让它做总结，让它做这三件事：

当导游：让它按"顶层概念 → 次要概念"给你排一个概念依赖顺序
当场出题：让它就 Orbit 问你 5 个"为什么这样设计"的问题，你答，它纠正
当翻译：读到看不懂的术语（property graph / ontology / CDC / Query DSL / MCP）再问它，不要让它替你读原文

四、阶段 1：跑通 Orbit Local（半天）★ 最关键的一步

这一步不能跳。跳过它，后面所有的"思想""架构"都是空转。

为什么先跑 Local 而不是 Remote

Local 不需要 GitLab 账号、不需要申请权限、不需要开 feature flag
产出一个 DuckDB 文件，可以直接用 SQL 查，反馈极快
你本机就有仓库可以索引（甚至可以直接拿 F:\github 下的某个项目试）

要做的事

安装（注意：官方给了 macOS/Linux、Windows、npm、glab 四条路径，你是 Windows，走 Windows 安装器或 npm）
- 参考：https://docs.gitlab.com/orbit/local/getting-started/

索引一个仓库 + 看 schema

shell 复制代码

orbit index /path/to/your/repo
orbit schema          # 打印所有表与字段

跑第一条查询

shell 复制代码

orbit sql 'SELECT count(*) FROM gl_definition'

认识本地图的 5 张核心表（这是 Local 的全部家当，务必记住）：

表	含义
`gl_directory`	目录
`gl_file`	文件（含 language、extension、size_bytes）
`gl_definition`	定义（函数/类/方法/模块，含 `fqn`、`definition_type`、起止行列）
`gl_imported_symbol`	import 语句与跨文件符号引用
`gl_edge`	边（关系）
`_orbit_manifest`	记账表

认识 5 种关系类型 （gl_edge 里的关系）：

CONTAINS（目录含目录/文件）、DEFINES（文件定义符号、外层定义含内嵌定义）、IMPORTS（文件含 import、import 解析到定义）、CALLS（定义调用定义）、EXTENDS（子类→父类，方向是从子指向父）
自己写 3 条有价值的 SQL，例如：
- 「哪个函数被调用得最多」→ 对 CALLS 边做 GROUP BY
- 「修改某文件会影响谁」→ 从 IMPORTS 反向追溯
- 「这个类继承链是什么」→ 顺着 EXTENDS 边爬

产出（这就是你的"学习证据"）

一份 ~/.orbit/graph.duckdb 里躺着你自己仓库的图
3 条你自己写的、能跑出有意义结果的 SQL
一句话总结："Local 能回答 ___，不能回答 ___"

会踩的坑（提前告诉你）

多个 checkout 共享同一个 ~/.orbit/graph.duckdb，按文件系统路径区分；切分支后重新索引会覆盖该 checkout 上一次的图 ，想同时保留多分支请用 git worktree
只索引当前检出分支（不是所有分支），二进制文件不索引
支持语言：Ruby / Java / Kotlin / Python / TypeScript / JavaScript / Rust / Go / C# / C / C++ / PHP / Bash-Shell /（另有 Elixir 出现在 Remote 列表）

五、阶段 2：读懂「思想」（1 天）

这是截图第②条「全方位看看是个啥思想」，也是最值钱的部分。

要理解的核心思想（4 个）

① 把"关系"从"数据"里抽出来，变成一等公民

传统做法：代码是文本、MR 是记录、流水线是记录，关系靠"查的时候现场 join / grep"。

Orbit 做法：所有东西都是 Node，所有关系都是 Edge，预先建好一张图 。

→ 迁移价值：任何"Agent 需要反复探索才能拼出全貌"的场景，都值得考虑预建图谱。

② 「代码层」和「SDLC 层」必须是同一张图，而不是两个库

两层怎么连起来的？关键在跨层边：

一个 MR（SDLC 层）触碰了文件（代码层）
一个 User（SDLC 层）拥有某个定义（代码层）------依据是该用户最后修改了包含它的文件

→ 这就是为什么它能回答"这个漏洞是哪个 MR 引入的""这段代码谁最该 review"这类跨域问题。单看图或单看表都答不出来。

③ Ontology 用 YAML 定义，且两个 runtime 共享

这说明他们刻意把「领域语义 」和「存储/执行引擎 」解耦了：语义写一遍，Local（DuckDB）和 Remote（ClickHouse）各自实现。

→ 迁移价值：这是"同一套业务语义、多种存储后端"的标准解法。

④ 给 AI Agent 的不是 API，是「上下文 API」

注意官方措辞：unified context API 。区别在哪？

普通 API 是"你告诉我要什么，我给你什么"；context API 是"我给你足够的图上下文，让你自己判断需要什么" 。它的关键设计是：Definition 和 File 节点上直接带 content 字段 （完整源码文本），Agent 可以一次 query 就把代码原文拿回来，不用再单独调 GitLab API 去 hydrate。

→ 这一条是当代 AI 工程的重要范式，建议作为你这次学习的最高优先级收获。

读完要能回答的 3 个问题

为什么 Orbit 不做成"给 Agent 一堆 REST 接口"，而要做成"一张图 + 一个查询入口"？
为什么代码层和 SDLC 层必须连通？举一个只有连通才能回答的问题。
content 字段放在图节点里，这个设计的取舍是什么？（提示：查询变慢 vs 少一次往返）

六、阶段 3：读懂「架构」（2~3 天）

3.1 先看顶层：两个 runtime（半天）

一句话：一套 Rust workspace + 一份 YAML ontology，跑出两个 runtime。

复制代码

                 ┌──────────── 共享 ────────────┐
                 │  Rust workspace + YAML       │
                 │  ontology（领域语义）        │
                 └───────┬──────────────┬───────┘
                         │              │
        ┌────────────────▼───┐      ┌───▼─────────────────────┐
        │   Orbit Local      │      │   Orbit Remote          │
        │   orbit CLI        │      │   gkg-server            │
        │   → DuckDB         │      │   → ClickHouse          │
        │   直连命令 + stdio │      │   HTTP / gRPC / REST    │
        │   MCP server       │      │   MCP / Duo Agent       │
        └────────────────────┘      └─────────────────────────┘

命名彩蛋：产品叫 Orbit ，但二进制和指标名还留着工程名 GKG （gkg-server）。

3.2 再看 Remote 的索引流水线（1 天）

要搞清两条数据是怎么汇进同一张图的：

SDLC 数据这条线（这是架构上最能学到东西的部分）：

复制代码

GitLab 实例 ──CDC（变更数据捕获）──▶ Data Insights Platform ──▶ ClickHouse
                                                                   │
                                                            Orbit 读写图

是持续增量的：有人开 MR / 建 issue / 跑流水线，几分钟内就传播到图里
为什么用 CDC 而不是轮询？→ CDC 是事件驱动、延迟低、对源库压力小，这是数据同步架构的经典取舍

源代码这条线：

复制代码

Orbit ──调用 GitLab Rails 内部 API──▶ 取源码文件
      ──语言专属 parser 解析──▶ 抽定义 + import 引用
      ──写成节点和边──▶ ClickHouse

只索引默认分支；默认分支变了自动重新索引

查询执行链路（6 步，务必背下来）：

复制代码

1. 收到 JSON query（REST / MCP / Duo Agent Platform）
2. 按当前 schema 校验 query
3. 把 JSON DSL 编译成 ClickHouse SQL   ★核心
4. ClickHouse 执行
5. 做授权过滤（结果只含当前用户有权限看的实体）
6. 返回 typed JSON

调试技巧：options.include_debug_sql: true 能拿到编译后的 SQL（仅限实例管理员或 Reporter+ 权限的成员）------这是学习"DSL 怎么变成 SQL"的最佳抓手

性能与保留 ：初始索引大 group（数千项目、数百万行）分钟级；增量秒级~分钟级。跑在独立 K8s 集群 ，不与你的 GitLab 实例抢资源。停用 Orbit 后数据保留 30 天再永久删除，30 天内重新启用可断点续传。

3.3 再学 Remote 的 Query DSL（1 天）

5 种查询形状（query_type）------这是 DSL 的骨架：

使用场景	query shape
取某一类实体的匹配节点（搜索就是这个形状，Orbit 没有独立的 `search` 类型）	单节点 `traversal`
沿已知实体类型之间的关系走	多节点 `traversal`
计数 / 求和 / 平均 / 分组	`aggregation`
找两个已知端点之间的路径	`path_finding`
问"某个节点连着什么"	`neighbors`

Schema 规模：27 个 node types，分 6 个 domain （官方文案在 28 和 27 之间有过不一致，以 glab orbit ontology 的实时输出为准）：

Domain	Node types
Core	`Group`、`Project`、`User`、`Note`
Source code	`Branch`、`Definition`、`Directory`、`File`、`ImportedSymbol`
Code review	`MergeRequest`、`MergeRequestDiff`、`MergeRequestDiffFile`
CI/CD	`Pipeline`、`Stage`、`Job`、`Deployment`、`Environment`、`Runner`
Planning	`WorkItem`、`Milestone`、`Label`
Security	`Finding`、`SecurityScan`、`Vulnerability`、`VulnerabilityIdentifier`、`VulnerabilityOccurrence`、`VulnerabilityScanner`

学习方法：直接读 Cookbook，别从语法读起。

https://docs.gitlab.com/orbit/remote/cookbook/ ------ 它给的是**「用自然语言问 Agent」的 prompt**，每个 prompt 下面折叠着"背后实际跑的 query"。这是最好的 DSL 教材：先看它解决什么业务问题，再展开看 query 怎么写。

Cookbook 六大类场景：

CI 成本归因：把 CI 花费追溯到具体文件/函数（失败排行 → 找出跨项目复现的共享模板 → 追到反复失败的文件和定义）
快速理解陌生代码库：最活跃贡献者、核心类模块及关系、从哪 3 个文件读起
依赖与爆炸半径（blast radius）：改这个库会崩什么
流水线健康度：失败最多的项目 / Job / 失败原因
安全风险溯源：高危漏洞在哪些项目、怎么进来的、追溯到引入它的 MR
读取真实源码：把文件/定义原文直接拉进对话

注意一个真实局限（文档自己承认的）：HAS_FILE 边是稀疏填充 的，所以相关查询结果偏短时是不完整覆盖，不能当权威结论。这种"知道工具边界"的能力，比会用工具更值钱。

3.4 最后再看源码结构（1 天，可选但推荐）

读源码的正确顺序（不要按目录字母序）：

CONTEXT.md ------ 领域词汇表，先统一语言
docs/design-documents/data_model.md ------ 数据模型，图的完整定义
docs/design-documents/ ------ 设计文档，看他们为什么这么设计、否掉了哪些方案
crates/indexer/AGENTS.md ------ 索引器 crate 的指南
crates/ ------ 最后才进代码，从 indexer 开始
docs/dev/adding-a-language.md ------ 想贡献的最佳切入点（加一门语言的 parser）

顶层目录速查：

目录	用途
`crates`	Rust 主代码（核心）
`docs`	文档（`source/` 用户文档、`dev/` 开发文档、`design-documents/` 设计文档）
`skills`	Agent skill（CLI 共享搜索结果模型等）
`clients`	gRPC 契约 `orbit.v1.OrbitService`
`e2e` / `fixtures` / `bench`	端到端测试 / 测试夹具 / 基准测试
`dashboards` / `config` / `scripts`	监控面板 / 配置 / 脚本
`.claude/skills`、`.opencode/agent`、`.agents`	各类 AI Agent 配置（注意：他们自己也在重度用 Agent 开发）

关键文件：AGENTS.md、CLAUDE.md（给 AI 的指导）、CONTEXT.md（词汇表）、Cargo.toml、mise.toml（任务运行器）、install.ps1（Windows 安装）。

本地开发全部走 mise：

shell 复制代码

mise build / test:fast / test:integration / lint:code / server:start

官方明确说了：大部分贡献不需要 Rust 经验 ------ontology YAML、文档、cookbook 配方、语言 parser 骨架都可以上手。想找切入点就看 orbit::hackathon 标签的 issue。

七、阶段 4：接上 AI Agent 做玩法（1 天起）★ 第④条

「能不能以这个东西搭建点玩法出来」------这才是学习的终点。下面给你从易到难的玩法阶梯。

4.1 先打通连接（半天）

三条路，任选：

方式	命令 / 做法	适合
MCP（推荐）	`claude mcp add orbit-cli -- orbit mcp serve`	把 Local 图暴露给你的 AI 编码 Agent
安装官方 skill	`glab skills install --global orbit`（装到 `~/.agents/skills/orbit`；加 `--force` 更新）	让 Agent 一次性获得查询配方 + DSL 参考 + 排错指南 + 仓库地图脚本
glab orbit	`glab orbit --install`，然后 `glab orbit index/schema/ontology/query`	你已经习惯用 glab；要求 glab ≥ 1.117

官方 skill 里包含 4 样东西（很值得拆开看它怎么写的）：Query recipes （可粘贴的 JSON 配方：爆炸半径、流水线历史、贡献者模式）、DSL reference 、Troubleshooting （退出码、空结果诊断、常见坑）、Repository map helpers 。

支持 Agent：Claude Code、Codex、Cursor、opencode、Gemini CLI。

4.2 玩法阶梯（由易到难，建议按序做）

Lv.1 「代码地图」 （半小时）

让 Agent 索引你手头一个真实项目，然后问它"这个项目的核心模块是什么、入口在哪、我该先读哪 3 个文件"。

→ 检验点：它的回答是不是明显优于裸 grep？

Lv.2 「爆炸半径检查」 （1 小时）

对你要改的一个公共函数/模块问："改它的签名会崩哪些地方？按风险排序。"

→ 这是 Orbit 最经典的价值场景，也是最能给同事演示的。

Lv.3 「死代码 / 孤儿代码猎手」 （半天）

自己写 SQL：找出没有任何 CALLS 边指入 的 gl_definition。

→ 用图算法做静态分析，纯 SQL 就能完成，成就感很强。

Lv.4 「架构漂移检测」 （1 天）

对比两个时间点（两次索引/两个 worktree）的图，找出：

新增了哪些跨模块 import（说明这层依赖被打破了）
哪个目录的边密度暴涨
→ 把"架构约束"变成可查询、可自动化的检查。

Lv.5 「给 AI Agent 装一个代码理解后端」 （1 天）

把 Orbit Local 的 MCP 和你自己的 Agent/工具链结合，让 Agent 在回答代码问题前先查图再读文件 ，而不是盲目 grep。

→ 这一步做完，你就真正理解了 Orbit 那句 "context API for AI systems" 是什么意思。

Lv.6（进阶）自定义 Ontology 扩展

照着他们的 YAML ontology，加自己的实体/关系（比如把你们内部的工单系统也建模进来）。

→ 这一步能彻底吃透"Ontology 与存储解耦"的设计。

4.3 能体现"真学会了"的产出

一个能跑的小工具/脚本（哪怕只是几条 SQL 包一层）
一份对比说明：用 Orbit 查 vs 用 grep/API 查，在同一个问题上差多少
如果可能，在组内做一次 15 分钟分享

八、时间预算与优先级

阶段	内容	建议投入	优先级
0	建立认知地图	1~2 小时	必做
1	跑通 Orbit Local	半天	必做（最高）
2	读懂思想	1 天	必做
3	读懂架构（含 Query DSL）	2~3 天	必做
4	接 Agent 做玩法	1 天起	必做
5	源码深入 / 贡献	按需	选做

如果时间极度有限（只有 1 天） ：只做阶段 1 + 阶段 4 的 Lv.1、Lv.2。

把 Local 跑起来 + 让 Agent 通过 MCP 查它，你就已经掌握了这个项目 80% 的实用价值。

九、验收清单（自测是否真学会）

十、关键链接清单（收藏这一节就够）

必读

仓库：https://github.com/gitlabhq/orbit-knowledge-graph
官方主仓（代码更新更全）：https://gitlab.com/gitlab-org/orbit/knowledge-graph
文档站总入口：https://docs.gitlab.com/orbit/

Orbit Local（先学这个）

快速开始：https://docs.gitlab.com/orbit/local/getting-started/
工作原理：https://docs.gitlab.com/orbit/local/how-it-works/
Schema 参考：https://docs.gitlab.com/orbit/local/schema/
CLI 用法：https://docs.gitlab.com/orbit/local/access/cli/
MCP 接入：https://docs.gitlab.com/orbit/local/access/mcp/

Orbit Remote

快速开始：https://docs.gitlab.com/orbit/remote/getting-started/
工作原理：https://docs.gitlab.com/orbit/remote/how-it-works/
Schema（27 个 node types）：https://docs.gitlab.com/orbit/remote/schema/
Cookbook（最好的 DSL 教材）：https://docs.gitlab.com/orbit/remote/cookbook/
Query 语言参考：https://docs.gitlab.com/orbit/remote/queries/
安全与授权：https://docs.gitlab.com/orbit/remote/security/

索引范围 / AI Agent

索引什么数据：https://docs.gitlab.com/orbit/indexed-data/
AI coding agent 接入：https://docs.gitlab.com/orbit/ai_coding_agents/

仓库内文档（clone 后读）

CONTEXT.md ------ 领域词汇表（先读这个）
docs/design-documents/data_model.md ------ 数据模型
docs/design-documents/ ------ 设计文档
docs/dev/local-development.md ------ 本地开发
docs/dev/adding-a-language.md ------ 加一门语言（最佳贡献切入点）
crates/indexer/AGENTS.md ------ 索引器 crate 指南
CONTRIBUTING.md ------ 构建 / 测试 / MR 规范
LICENSE.md ------ GitLab EE License，改造商用前必读

附：回答三句话

这个项目在解决什么：把 GitLab 的 SDLC 数据和源码统一成一张属性图，作为 AI Agent 的"上下文 API"，让 Agent 不用反复 grep / 调接口就能拿到完整的结构关系。
我打算怎么学：先在本机跑通 Orbit Local（单二进制 + DuckDB，无需账号），再把图通过 MCP 接给 AI Agent，做一个真实的"爆炸半径分析 / 死代码扫描"小工具验证价值。
我的判断 ：项目处于 Beta，Query DSL 和 ontology 还会变，许可证是 GitLab EE------直接依赖它上生产有风险，但它"上下文图谱 + Ontology 解耦 + 给 Agent 供上下文"的设计思想很有迁移价值，我们可以借鉴思路自建轻量版本。