Onboard-CLI 拆解：Tree-sitter AST + React Flow，把代码库变成交互图谱
Onboard-CLI 拆解：Tree-sitter AST + React Flow，把代码库变成交互图谱
入职第一天面对 50 万行代码？这个工具想帮你画张地图。
接手一个陌生代码库，最痛苦的不是代码难，是不知道谁调用了谁、模块之间怎么依赖、改一个文件会波及哪些地方。
传统方案是装个 IDE 跳来跳去，或者让 AI 读代码给你解释。Onboard-CLI 走了第三条路：用 Tree-sitter 解析 AST，把代码结构提取成节点和边的图，然后在 React Flow 画布上交互式展示。
它在 Hacker News 上以 Show HN 发布，22 分、11 条评论。热度不算爆，但评论区的讨论很有意思--有人质疑"LLM 在哪"，有人说最近代码图谱工具突然扎堆。我把整个仓库翻了一遍，这篇拆解一下它的实际架构和能力。
本文提纲
- Onboard-CLI 是什么（以及 LLM 到底在哪）
- 核心架构：AST 解析 + SQLite 图存储 + React Flow 画布
- 五个核心命令
- 架构漂移检测：用 YAML 规则守住代码边界
- HN 讨论：代码图谱为什么突然火了
- 和同类工具对比
- 技术栈与上手
Onboard-CLI 是什么（以及 LLM 到底在哪）
HN 帖子标题写的是"a LLM powered and AST-based tool to visualize codebase"。但翻完整个仓库，没有一行 LLM 相关代码。没有 OpenAI API 调用，没有 prompt 模板，没有模型推理。唯一的"AI"文件是 AI_USAGE.md--那是给贡献者用 AI 辅助写代码的行为规范，跟工具本身无关。
所以准确地说：Onboard-CLI 是一个纯 AST 驱动的代码库可视化工具。HN 标题里的"LLM powered"要么是路线图计划，要么是营销措辞。HN 评论区也有人直接指出了这一点。
抛开 LLM 的误导，工具本身做的事情是实打实的：
- 用 Tree-sitter 解析 5 种语言（Go、TypeScript、JavaScript、Python、Java）的 AST
- 提取函数、方法、类、接口、枚举等结构节点
- 分析节点之间的依赖关系，构建拓扑图
- 在本地 React Flow 画布上交互式展示
- 用 YAML 规则检测架构边界违规
项目用 Go 写 CLI 核心，React 19 写可视化前端，MIT 协议，59 Star，6 月 28 日创建，还很新。
核心架构：AST 解析 + SQLite 图存储 + React Flow 画布
Onboard-CLI 的架构分三层，每一层都很清晰：
graph LR
subgraph "CLI Core (Go)"
A["Tree-sitter Parser"]
B["AST Extractor"]
C["SQLite Store"]
D["Drift Detector"]
end
subgraph "Data Layer (SQLite)"
E["nodes table"]
F["edges table"]
G["file_cache table"]
H["cached_routes table"]
end
subgraph "Web UI (React 19)"
I["React Flow Canvas"]
J["Fuzzy Finder"]
K["Dark / Compact Mode"]
end
A --> B
B --> C
C --> E
C --> F
C --> G
C --> H
C --> I
D --> C
I --> J
I --> K
style A fill:#FF6B6B,color:#000000
style C fill:#4ECDC4,color:#000000
style I fill:#45B7D1,color:#000000
style D fill:#96CEB4,color:#000000
style E fill:#FFEAA7,color:#000000第一层：AST 解析引擎（Go + Tree-sitter）
核心在 internal/parser/engine.go。用 github.com/smacker/go-tree-sitter 做 AST 解析。解析器把 tree-sitter 的原始节点类型映射成干净的语义类型：
| Tree-sitter 原始类型 | Onboard-CLI 语义类型 |
|---|---|
function_declaration, function_definition |
function |
method_declaration, method_definition |
method |
class_declaration, class_definition |
class |
interface_declaration |
interface |
enum_declaration |
enum |
type_declaration, type_alias_declaration |
type |
lexical_declaration, variable_declaration |
variable |
一个设计细节：解析器会过滤掉函数体内部的嵌套变量声明（topLevelOnly 机制），只保留顶层结构。这避免了图谱被大量局部变量污染。
第二层：SQLite 图存储
解析结果存到本地 SQLite 数据库（internal/store/db.go），WAL 模式，四张表：
-- 结构节点
nodes (id, type, name, file_path, line_number)
-- 依赖关系
edges (source_id, target_id, relationship_type)
-- 文件哈希缓存（增量解析用）
file_cache (file_path, hash)
-- API 路由缓存
cached_routes (file_path, method, path, handler)file_cache 表存文件哈希，用于增量解析--没改过的文件跳过。这对大型代码库很重要，全量解析一次可能要几分钟。
第三层：React Flow 可视化
onboard map 命令会启动一个本地 HTTP 服务器（internal/server/），在 http://localhost:3000/app 挂载 React Flow 画布。Go 二进制通过 ui/embed.go 把编译好的 React 前端嵌入进去，不需要额外装 Node.js。
画布支持模糊查找（Ctrl+P）、暗色模式、紧凑模式。你可以指定 --radius 控制图谱深度，比如 --radius 2 表示从目标节点出发展开两层依赖。
五个核心命令
Onboard-CLI 的命令行用 Cobra 框架构建，主要命令：
onboard init -- 初始化项目，生成 .onboard 配置目录和 architecture.yaml 架构规则文件。支持 5 种模板：
onboard init --template clean-architecture可选模板：generic、clean-architecture、modular-monolith、mvc、serverless。CI/CD 场景可以直接用模板生成标准架构约束。
onboard map -- 核心功能。解析目标路径的 AST，构建依赖图，启动可视化服务器：
onboard map --target "internal/parser" --radius 2浏览器打开 localhost:3000/app 就能看到交互式图谱。--radius 控制展开深度。
onboard routes -- 自动提取后端 API 路由，映射到具体文件和行号。支持四种框架：
onboard routes --protocol rest --framework expressExpress、Gin、FastAPI、Spring 都能识别。对梳理 API 全貌很有用。
onboard drift -- 架构漂移检测。对照 architecture.yml 规则检查跨文件导入和边界违规：
onboard drift --rules architecture.yml可以集成到 GitHub Actions，每个 PR 自动检查。
onboard impact -- 变更影响分析。评估一个改动会波及哪些文件和模块。
另外还有 onboard owners（代码归属追踪）、onboard export（导出 AST/图数据）、onboard pulse（代码库健康摘要）。
架构漂移检测：用 YAML 规则守住代码边界
这是 Onboard-CLI 最有企业实用价值的功能。
大多数项目的架构规范停留在文档和口头约定里。"Controller 不能直接调 DAO""Service 层不能引用 Controller"--这些规则谁都知道，但没人检查，慢慢地代码就乱成一锅粥。
Onboard-CLI 的 drift 命令用 YAML 定义规则，然后基于 AST 解析结果做正则匹配，亚秒级完成数千文件的边界检查。可以集成到 CI/CD：
# architecture.yml 示例（基于模板生成）
# 定义模块边界和允许的依赖方向README 里提供了一个 GitHub Actions 模板（docs/onboard-action.yml），每个 PR 自动跑 onboard drift，违规就拦住。
这种"架构即代码"的思路不新鲜（ArchUnit、dependency-cruiser 都在做），但结合 AST 解析和可视化，Onboard-CLI 的闭环更完整：先 map 看现状，再 drift 查违规，最后 impact 评估改动。
HN 讨论：代码图谱为什么突然火了
帖子 22 分不算高，但评论区的讨论质量不错。
最有趋势洞察的评论来自 XUEYANZ："最近看到很多构建代码库图谱的帖子，为什么突然流行了？有什么突破导致这个趋势吗？"这个问题很到位。答案大概率是 Tree-sitter 的成熟--它提供了跨语言的统一 AST 解析能力，让构建通用代码图谱工具的成本大幅下降。
最尖锐的质疑来自 ImPostingOnHN："有没有比行引用更有意义的代码路径可视化方式？我觉得 LLM 适合解释行为，而可视化代码引用完全不需要 AI。"这直接戳中了 Onboard-CLI 的定位问题--它做的是结构可视化，不是语义理解。AST 能告诉你谁调用了谁，但不能告诉你为什么这么调用。
最务实的提问来自 joe-esquibel："这个工具能在不能编译的代码上工作吗？"答案是可以--Tree-sitter 是容错解析器，不需要代码能编译就能生成 AST。这是 AST 方案相比编译器方案的优势。
最失望的反馈来自 mthoms："看了 1 分 30 秒的视频，没看到一个代码可视化。就一个孤零零的节点在画布上飘。"这说明工具的演示效果可能不够好，或者展示场景没选对。
和同类工具对比
Onboard-CLI 不是唯一做代码图谱的工具。几个对比：
| 工具 | 技术路线 | 语言支持 | 可视化 | 架构约束 | 开源 |
|---|---|---|---|---|---|
| Onboard-CLI | Tree-sitter AST | 5 种 | React Flow 交互画布 | YAML 规则 + CI 集成 | MIT |
| dependency-cruiser | import 分析 | JS/TS 生态 | DOT/SVG 图 | 规则引擎 | MIT |
| ArchUnit | 运行时反射 | Java | 无原生可视化 | Java DSL | Apache-2.0 |
| Sourcegraph | 代码搜索引擎 | 多语言 | Web UI | 企业版功能 | 部分开源 |
| CodeSee | 代码图谱 SaaS | 多语言 | 交互式地图 | 无 | 闭源 |
Onboard-CLI 的差异化在于：Tree-sitter 提供跨语言能力（不只是 JS/TS），React Flow 提供本地交互画布（不需要 SaaS），YAML 规则 + Git hooks 提供 CI 集成。但它还很早期，59 Star，语言支持只有 5 种，C++ 不支持（HN 评论区有人问了）。
技术栈与上手
技术选型：
| 维度 | 详情 |
|---|---|
| CLI 核心 | Go 1.21+，Cobra，go-tree-sitter |
| 数据存储 | SQLite（WAL 模式，嵌入式） |
| Web UI | React 19，Vite，@xyflow/react（React Flow），Tailwind CSS，Framer Motion |
| 代码高亮 | Shiki |
| 协议 | MIT |
| 安装 | curl 脚本（macOS/Linux），PowerShell（Windows） |
安装：
# macOS / Linux
curl -fsSL https://raw.githubusercontent.com/onboard-cli/install.sh | bash
# Windows
Invoke-WebRequest -Uri https://raw.githubusercontent.com/onboard-cli/install.ps1 -OutFile install.ps1; .\install.ps1快速上手：
# 1. 初始化项目
onboard init --template clean-architecture
# 2. 可视化某个模块的依赖关系
onboard map --target "internal/parser" --radius 2
# 3. 检查架构边界违规
onboard drift --rules architecture.yml
# 4. 提取 API 路由
onboard routes --protocol rest --framework ginGo 二进制内嵌了 React 前端，不需要额外装 Node.js。onboard map 会自动启动本地服务器，浏览器打开就能看到画布。
谁该关注 Onboard-CLI
新入职的开发者。 onboard map 能快速画出模块依赖图，比在 IDE 里一个个文件跳转高效。--radius 控制展开深度，先看一层再逐步深入。
做架构治理的技术负责人。 architecture.yml + onboard drift + CI 集成，能在 PR 阶段拦截架构违规。比事后代码审查更有效。
做代码图谱工具的开发者。 技术选型值得参考：Go 做 CLI + Tree-sitter 做解析 + SQLite 做存储 + React Flow 做可视化，这套组合的工程平衡点选得不错。Go 二进制内嵌 React 前端的部署方式也很干净。
反过来，这些情况暂时不用看：只需要 JS/TS 依赖分析的，dependency-cruiser 更成熟；需要 Java 架构约束的，ArchUnit 更专业；需要企业级代码搜索的，Sourcegraph 更完整。Onboard-CLI 现在的优势是跨语言 + 本地优先 + 可视化，但生态还很早期。
参考文档与链接
- GitHub: animesh-94/Onboard-CLI - 59 Star，Go + TypeScript，MIT 协议
- Onboard-CLI 官网 - 产品介绍和文档
- Onboard-CLI README - 功能介绍和快速上手
- Tree-sitter 官方文档 - AST 解析引擎，Onboard-CLI 的核心技术
- go-tree-sitter - Tree-sitter 的 Go 绑定
- React Flow (@xyflow/react) - Onboard-CLI 使用的交互式节点画布库
- Hacker News 原帖 - 22 分，11 条评论，社区讨论
- dependency-cruiser - JS/TS 生态的同类工具对比
- Onboard-CLI GitHub Actions 模板 - CI/CD 集成示例
- Onboard-CLI AI 使用政策 - 贡献者 AI 使用规范（非工具 LLM 集成）
你觉得代码图谱工具值得用吗？还是直接让 AI 读代码更香？评论区聊聊。觉得有用点个赞让更多人看到。
作者: itech001 来源: 公众号：AI人工智能时代 网站: https://www.theaiera.cn/ 每日分享最前沿的AI新闻资讯和技术研究。
本文首发于 AI人工智能时代，转载请注明出处。
