Onboard-CLI：基于LLM和AST的代码库可视化工具

背景

随着软件项目规模不断膨胀，开发者在面对数百万行代码的遗留系统或快速迭代的现代服务时，往往陷入“代码迷宫”——难以快速定位依赖关系、识别架构边界退化、评估修改影响范围。传统的代码分析工具（如grep、静态分析Lint）虽然能解决部分语法级问题，但缺乏对代码库整体拓扑结构的可视化理解，也无法在团队协作中持续执行架构规则。Onboard-CLI 正是在这一背景下诞生：它结合了大型语言模型（LLM）的能力、抽象语法树（AST）的精确解析以及交互式画布可视化，试图为开发者提供一套“代码库地图绘制与架构观测”的一站式命令行工具。

核心内容

Onboard-CLI 是一个基于命令行的工具，附带一个 Web 可视化界面。它利用 Tree-sitter 进行 AST 解析，生成结构化的拓扑图，并允许用户通过一个 React Flow 画布进行交互式探索。其核心功能包括：

• AST 切片引擎：支持 Go、JavaScript、TypeScript、Python、Java 等语言，通过 Tree-sitter 生成精确的结构节点。
• 交互式可视化器（map命令）：运行 onboard map --target "internal/parser" --radius 2 后，会自动在本地启动一个 React Flow 画布（默认访问 http://localhost:3000/app），用户可以在画布上浏览代码路径、依赖关系以及指定半径内的拓扑图。
• 架构偏移检测（drift命令）：通过 onboard drift --rules architecture.yml 分析代码库，根据预定义的 architecture.yml 规则检测跨文件非法导入和边界违规，确保代码长期健康。
• 生态命令：包括配置管理、影响分析（impact）、代码导出（export）、代码所有者追踪（owners）以及项目概览（pulse）。
• 技术栈：CLI 引擎使用 Go 语言、Cobra 框架、Go-Tree-Sitter 和 YAML；Web UI 则使用 React 19、TypeScript、Vite、@xyflow/react（React Flow）、Tailwind CSS、Framer Motion 和 Lucide React。代码高亮与 Markdown 渲染使用 Shiki、MDX 和 Rehype。
• 安装与初始化：提供一键安装脚本（curl / PowerShell），通过 onboard init 生成 .onboard 配置，可选模板包括 generic、clean-architecture、modular-monolith、mvc、serverless。
• CI/CD 集成：onboard drift 可集成到 GitHub Actions 中，在每次 Pull Request 时强制执行架构边界规则。
• 路由映射：onboard routes --protocol rest --framework express 能自动将后端 API 路由映射到其具体文件及行号位置，支持 Express、Gin、FastAPI、Spring 等框架。
• 全局选项：所有命令均可通过 --no-update-check 禁用自动异步版本检查。

关键要点

• 双重解析精度：结合 LLM 的语义理解与 Tree-sitter 的 AST 解析，既保证对代码结构的精确抓取，又支持对符号关系的智能推断。
• 可视化半径可配置：默认半径设为 1，但可扩展至复杂依赖树，用户按需控制映射深度，避免信息过载。
• 亚秒级边界规则评估：通过正则表达式对数千个文件进行架构偏移检测，性能足以嵌入 CI 流程。
• 多语言原生支持：内置 5 种语言的解析器（Go、TypeScript、JavaScript、Python、Java），覆盖主流后端和前端生态。
• 前端渲染优化：使用 Vite + SWC/Oxc linting 实现大节点集的画布渲染优化，确保交互流畅。
• 模板化架构规则：提供 architecture.yml 模板，用户可自定义架构边界，并自动检测违背情况。
• 模糊搜索与主题切换：在 UI 中按 Ctrl+P 可调用模糊搜索；右上角可切换深色模式和紧凑模式。
• 开源 MIT 许可：代码托管在 GitHub，欢迎贡献，并附有 AI 使用政策指南。

意义与影响

Onboard-CLI 的出现标志着代码库分析工具从“文件级搜索”向“结构级可视化与持续治理”的演进。其意义体现在三个方面：

1. 降低大型代码库的认知负载：通过 AST 生成的拓扑图，开发者可以快速把握模块间的依赖关系，而不必手动翻阅数十个文件。这对于新成员入职、遗留系统重构尤为关键。

2. 将架构治理从“文档约束”变为“自动化检查”：drift 命令与 CI 集成后，团队可以在每次提交时自动检测架构违规，避免了“架构文档与实际代码脱节”的常见问题。这有助于长期维护代码质量和一致性。

3. 开源社区与可扩展性：MIT 许可、多语言支持、丰富的模板（如 Clean Architecture、Modular Monolith）意味着它可以被不同技术栈的团队快速采纳，并围绕其生态开发更多插件或集成。此外，结合 LLM 的上下文感知能力，未来可能进一步实现语义级别的变更影响分析，提升代码审查效率。

总体而言，Onboard-CLI 试图解决开发者日常工作中最棘手的“代码理解”与“架构守护”问题，为现代软件工程提供了一种可视化的、可编程的观测手段。