OpenHeart快速上手教程：3条命令从克隆到运行你的第一个代码库静态分析与UML生成
OpenHeart快速上手教程：3条命令从克隆到运行你的第一个代码库静态分析与UML生成
OpenHeart 是一款用 Rust 编写的静态分析引擎与 UML 图生成器，它能扫描你的 Java/Kotlin 代码库，自动构建程序图（SCPG），并一键导出 14 张标准 UML 图和 5 张编译器级流程图。本文将带你用 3 条命令 完成从克隆仓库到运行第一次代码库分析的全过程，无需任何背景知识。
📖 什么是 OpenHeart？
OpenHeart 的核心思路是：把源代码当作"活的心跳"，通过一条 10 阶段编译流水线（从词法摄取 → 符号表 → 控制流 → SSA 数据流 → 调用图 → 路径摘要 → UML 语义提取）把代码压缩成统一的二进制程序图 SCPG，再从这张图投影出各种视图。
它主打两个卖点：
- 🧠 轻量：用平衡括号串 + Rank/Select 索引替代指针节点，官方称可实现高达 128× 内存压缩
- 🎨 全能：自动导出 14 张 OMG 标准 UML 2.5 图（类图、时序图、用例图、状态图、部署图等）+ 5 张编译器管线图（CFG、DFG、CDG、调用图、ROBDD）
想深入了解架构原理，可以阅读 docs/architecture.md 和 docs/uml_derivation.md。
✅ 环境准备：你只需要这两样
| 依赖 | 版本要求 | 说明 |
|---|---|---|
| Rust 工具链（含 Cargo） | 1.75+ | 编译分析引擎的核心 |
| Git | 2.20+ | 克隆仓库 |
验证 Rust 是否已安装：
rustc --version
如果尚未安装，通过官方 rustup 安装即可。项目依赖配置见 Cargo.toml。
🚀 第 1 条命令：克隆仓库
git clone https://gitcode.com/gh_mirrors/open/OpenHeart
cd OpenHeart
仓库结构一目了然，核心代码都在 src/ 下：
- src/ingestion/ —— 阶段 1：词法摄取与 token 语料库
- src/ast/ —— 阶段 2：平衡括号串压缩 AST
- src/symbol/ —— 阶段 3：符号表与类型层级
- src/scpg/ —— 阶段 10：统一二进制与图导出（JSON / PlantUML / Mermaid）
- web/ —— 浏览器可视化门户（零后端，纯前端渲染 19 张图）
🔨 第 2 条命令：编译分析引擎
cargo build --release
首次编译需要几分钟（依赖 tree-sitter 解析器）。完成后会在 target/release/openheart 生成一个独立可执行文件。
💡 也可以直接用 Makefile 中的
make release目标，效果相同。
🎯 第 3 条命令：运行你的第一个代码库分析
仓库自带一套包含 35 个 GoF 设计模式的示例 Java 代码库（examples/test_patterns_codebase/），是最完美的"第一个实验对象"：
target/release/openheart analyze ./examples/test_patterns_codebase ./output_patterns
这条命令会依次跑完 10 个阶段，你会在终端看到阶段化的结构化日志，最后打印出一行统计摘要：token 数、AST 节点数、符号数、CFG 边数、SSA 变量数、调用点数、检测到的设计模式数量等。
📦 输出目录里有什么？
output_patterns/
├── corpus.tca # 阶段1 词法语料库
├── ast.bpa # 阶段2 平衡括号串 AST
├── symbols.sta # 阶段3 符号表与类型层级
├── cfg.cfa # 阶段4 控制流图与支配树
├── ssa.ssa # 阶段5 SSA 与数据流图
├── callgraph.cga # 阶段6 调用图与指针分析
├── traceability.tra # 阶段7 双向溯源索引
├── paths.psa # 阶段8 ROBDD 路径摘要
├── metadata.uma # 阶段9 UML 语义元数据
├── unified.scpg # 阶段10 统一 SCPG 二进制
└── diagrams/ # ⭐ 19 张图的 .puml / .mmd / .json 三种格式
其中 diagrams/ 目录是重头戏——类图（class.puml）、时序图（sequence.puml）、用例图（usecase.puml）、调用图（callgraph.puml）等全部自动生成，.puml 文件可直接粘贴到任何 PlantUML 工具中渲染。
各阶段产物的二进制格式（魔数、存储结构）在 README.md 的 "Binary Artifact Specifications" 一节有完整对照表。
🔍 附加玩法：验证产物完整性
每个二进制产物都带 CRC-64 校验，可以用 inspect 子命令体检：
target/release/openheart inspect ./output_patterns/callgraph.cga
CLI 的完整用法（analyze / inspect / server / 日志级别参数）可查看 src/main.rs 中的 usage 说明。
🌐 加分项：启动 Web 可视化门户
除了命令行，OpenHeart 还内置了一个零后端的浏览器工作室，可以把 19 张图以矢量卡片形式交互浏览：
target/release/openheart server 8080
然后打开 http://localhost:8080。或者直接运行仓库根目录的一键脚本 run.sh（Linux/macOS）/ run.bat（Windows），它会自动检测环境、启动服务并帮你打开浏览器。
门户的前端代码在 web/js/，声明式的图表清单在 web/diagrams/manifest.json。
❓ 常见问题
Q1：报错 "No .java or .kt files found"？
analyze 只会收集 .java、.kt、.kts 文件（见 src/main.rs 的文件收集逻辑），请确认分析路径下确实包含这类源码。
Q2：想分析自己的项目？ 把第一个参数换成你的项目路径即可：
target/release/openheart analyze /path/to/your_project ./my_output
省略第二个参数时，输出默认写入 ./openheart_output。
Q3：想加详细日志排查问题？
在 analyze 命令末尾追加 --verbose 或 --trace 即可开启逐级日志。
📚 延伸阅读与下一步
| 想做什么 | 看这里 |
|---|---|
| 了解工作区搭建与命令行细节 | docs/getting_started.md |
| 理解 10 阶段管线与 19 张图映射 | docs/architecture.md |
| 学习仓库各模块内部结构 | docs/codebase-guide.md |
| 掌握 BP 树、CSR、ROBDD 等简明数据结构 | docs/succinct_structures.md |
| 跑更大规模的基准代码库 | examples/huge_enterprise_src/ |
| 浏览全部示例代码库说明 | examples/README.md |
写在最后
回顾一下，你只用 3 条命令就走完了 OpenHeart 静态分析引擎的核心闭环：
git clone—— 克隆仓库cargo build --release—— 编译引擎openheart analyze—— 分析代码库并生成 19 张图
从源码到 UML 图的全自动链路，就是 OpenHeart 想带给你的体验。接下来不妨换一个自己的 Java 项目试试，看看它为你画出怎样的类图与时序图吧！