内容
<div align="center">
# BHGraph
## 🎉 1.0 发布！
已经安装？运行 `bhgraph upgrade`
在 X 上关注 [@getbhgraph](https://x.com/getbhgraph) 以获取更新。
### 为 Claude Code、Cursor、Codex、OpenCode、Hermes Agent、Gemini、Antigravity 和 Kiro 提供语义代码智能
**精确上下文 · 更少工具调用 · 更快答案 · 100% 本地**
### [文档和网站 →](https://BharanitharanKR.github.io/bhgraph/)
[](https://www.npmjs.com/package/bhgraph)
[](https://opensource.org/licenses/MIT)
[](https://nodejs.org/)
[](#支持的平台)
[](#支持的平台)
[](#支持的平台)
[](#支持的代理)
[](#支持的代理)
[](#支持的代理)
[](#支持的代理)
[](#支持的代理)
[](#支持的代理)
[](#支持的代理)
[](#支持的代理)
<br>
**BHGraph 平台即将到来** — 对于每个 PR，都能准确知道需要测试的内容、可能出现的问题、受影响的流程以及业务逻辑是否受损。
<a href="https://getbhgraph.com"><img alt="加入早期测试计划，获取内测资格" src="https://raw.githubusercontent.com/BharanitharanKR/BHgraph/main/assets/waitlist.svg?v=2" height="52"></a>
<sub>获取 **早期测试资格**，使用托管产品 · [getbhgraph.com](https://getbhgraph.com)</sub>
</div>
## 目录
- [快速开始](#快速开始)
- [语言支持](#语言支持)
- [为什么选择 BHGraph？](#为什么选择bhgraph)
- [关键特性](#关键特性)
- [框架感知路由](#框架感知路由)
- [混合 iOS / React Native / Expo 桥接](#混合-ios--react-native--expo-桥接)
- [快速入门](#快速入门)
- [工作原理](#工作原理)
- [CLI 参考](#cli参考)
- [MCP 工具](#mcp工具)
- [库使用](#库使用)
- [配置](#配置)
- [遥测](#遥测)
- [支持的平台](#支持的平台)
- [支持的代理](#支持的代理)
- [支持的语言](#支持的语言)
- [跨文件覆盖率测量](#跨文件覆盖率测量)
- [故障排除](#故障排除)
- [星际历史](#星际历史)
- [许可证](#许可证)
## 快速开始
### 1. 安装 CLI
**无需 Node.js** — 一条命令即可获取适合您操作系统的正确构建版本：
```bash
# macOS / Linux
curl -fsSL https://raw.githubusercontent.com/BharanitharanKR/BHgraph/main/install.sh | sh
# Windows (PowerShell)
irm https://raw.githubusercontent.com/BharanitharanKR/BHgraph/main/install.ps1 | iex
```
<details>
<summary><b>已经安装 Node.js？使用 npm 代替（适用于任何版本）</b></summary>
```bash
npm i -g bhgraph
```
<sub>BHGraph 捆绑了自己的运行时 — 无需编译，无需原生构建，在任何地方都可运行。安装程序会将 `bhgraph` 放入您的 PATH 中，但 **不会更改当前 shell** — 在下一步之前打开一个新的终端，以便命令能够正确解析。</sub>
<sub>**随时升级**，使用 `bhgraph upgrade` — 它可以检测您如何安装（捆绑、npm 或 npx）并原地更新。添加 `--check` 以查看是否有可用的更新，或 `bhgraph upgrade <version>` 以锁定到特定版本。</sub>
</details>
### 2. 连接您的代理
在 **新终端** 中，运行安装程序以将 BHGraph 连接到您使用的代理：
```bash
bhgraph install
```
<sub>检测并自动配置 Claude Code、Cursor、Codex CLI、OpenCode、Hermes Agent、Gemini CLI、Antigravity IDE 和 Kiro — 将 BHGraph MCP 服务器连接到每个代理。**这是将 BHGraph 连接到您的代理的步骤；** 安装第 1 步中的 CLI 不会单独执行此操作。它仅连接您的代理 — 它 **不** 索引任何代码；每个项目的图构建是单独的 `bhgraph init`，在步骤 3 中。（快捷方式：`npx bhgraph` 一步完成下载和运行此操作。）</sub>
### 3. 初始化每个项目
```bash
cd your-project
bhgraph init
```
<sub>`bhgraph init` 创建本地 `.bhgraph/` 目录并在同一步骤中构建完整的图 — 一条命令即可完成。</sub>
<div align="center">
</div>
### 4. 无需再同步！
默认启用自动同步。BHGraph 监视项目并在每次文件更改时更新图 — 当您的代理编辑代码或您添加、修改或删除文件时。**索引永远不会过时，也无需重新运行。**
### 卸载
改变主意？一条命令即可从您配置的所有代理中删除 BHGraph：
```bash
bhgraph uninstall
```
<sub>撤销安装程序 — 从每个配置的代理中删除 BHGraph MCP 服务器配置、说明和权限。您的项目索引（`.bhgraph/`）保持不变；使用 `bhgraph uninit` 删除每个项目的文件。</sub>
---
## 语言支持
以下每种语言都得到相同的处理 — 完整的结构提取和跨文件解析成一个图，无需每种语言的单独设置：
<p align="center">
<img src="https://raw.githubusercontent.com/BharanitharanKR/BHgraph/main/assets/languages/typescript.svg?v=1" width="104" height="104" alt="TypeScript" />
<img src="https://raw.githubusercontent.com/BharanitharanKR/BHgraph/main/assets/languages/javascript.svg?v=1" width="104" height="104" alt="JavaScript" />
<img src="https://raw.githubusercontent.com/BharanitharanKR/BHgraph/main/assets/languages/arkts.svg?v=1" width="104" height="104" alt="ArkTS" />
<img src="https://raw.githubusercontent.com/BharanitharanKR/BHgraph/main/assets/languages/python.svg?v=1" width="104" height="104" alt="Python" />
<img src="https://raw.githubusercontent.com/BharanitharanKR/BHgraph/main/assets/languages/go.svg?v=1" width="104" height="104" alt="Go" />
<img src="https://raw.githubusercontent.com/BharanitharanKR/BHgraph/main/assets/languages/rust.svg?v=1" width="104" height="104" alt="Rust" />
<img src="https://raw.githubusercontent.com/BharanitharanKR/BHgraph/main/assets/languages/java.svg?v=1" width="104" height="104" alt="Java" />
<img src="https://raw.githubusercontent.com/BharanitharanKR/BHgraph/main/assets/languages/csharp.svg?v=1" width="104" height="104" alt="C#" />
<img src="https://raw.githubusercontent.com/BharanitharanKR/BHgraph/main/assets/languages/php.svg?v=1" width="104" height="104" alt="PHP" />
<img src="https://raw.githubusercontent.com/BharanitharanKR/BHgraph/main/assets/languages/ruby.svg?v=1" width="104" height="104" alt="Ruby" />
<img src="https://raw.githubusercontent.com/BharanitharanKR/BHgraph/main/assets/languages/c.svg?v=1" width="104" height="104" alt="C" />
<img src="https://raw.githubusercontent.com/BharanitharanKR/BHgraph/main/assets/languages/cpp.svg?v=1" width="104" height="104" alt="C++" />
<img src="https://raw.githubusercontent.com/BharanitharanKR/BHgraph/main/assets/languages/objective-c.svg?v=1" width="104" height="104" alt="Objective-C" />
<img src="https://raw.githubusercontent.com/BharanitharanKR/BHgraph/main/assets/languages/metal.svg?v=1" width="104" height="104" alt="Metal" />
<img src="https://raw.githubusercontent.com/BharanitharanKR/BHgraph/main/assets/languages/cuda.svg?v=1" width="104" height="104" alt="CUDA" />
<img src="https://raw.githubusercontent.com/BharanitharanKR/BHgraph/main/assets/languages/swift.svg?v=1" width="104" height="104" alt="Swift" />
<img src="https://raw.githubusercontent.com/BharanitharanKR/BHgraph/main/assets/languages/kotlin.svg?v=1" width="104" height="104" alt="Kotlin" />
<img src="https://raw.githubusercontent.com/BharanitharanKR/BHgraph/main/assets/languages/scala.svg?v=1" width="104" height="104" alt="Scala" />
<img src="https://raw.githubusercontent.com/BharanitharanKR/BHgraph/main/assets/languages/dart.svg?v=1" width="104" height="104" alt="Dart" />
<img src="https://raw.githubusercontent.com/BharanitharanKR/BHgraph/main/assets/languages/svelte.svg?v=1" width="104" height="104" alt="Svelte" />
<img src="https://raw.githubusercontent.com/BharanitharanKR/BHgraph/main/assets/languages/vue.svg?v=1" width="104" height="104" alt="Vue" />
<img src="https://raw.githubusercontent.com/BharanitharanKR/BHgraph/main/assets/languages/astro.svg?v=1" width="104" height="104" alt="Astro" />
<img src="https://raw.githubusercontent.com/BharanitharanKR/BHgraph/main/assets/languages/liquid.svg?v=1" width="104" height="104" alt="Liquid" />
<img src="https://raw.githubusercontent.com/BharanitharanKR/BHgraph/main/assets/languages/delphi.svg?v=1" width="104" height="104" alt="Pascal / Delphi" />
<img src="https://raw.githubusercontent.com/BharanitharanKR/BHgraph/main/assets/languages/lua.svg?v=1" width="104" height="104" alt="Lua" />
<img src="https://raw.githubusercontent.com/BharanitharanKR/BHgraph/main/assets/languages/r.svg?v=1" width="104" height="104" alt="R" />
<img src="https://raw.githubusercontent.com/BharanitharanKR/BHgraph/main/assets/languages/luau.svg?v=1" width="104" height="104" alt="Luau" />
<img src="https://raw.githubusercontent.com/BharanitharanKR/BHgraph/main/assets/languages/cfml.svg?v=1" width="104" height="104" alt="CFML" />
<img src="https://raw.githubusercontent.com/BharanitharanKR/BHgraph/main/assets/languages/cobol.svg?v=1" width="104" height="104" alt="COBOL" />
<img src="https://raw.githubusercontent.com/BharanitharanKR/BHgraph/main/assets/languages/vbnet.svg?v=1" width="104" height="104" alt="Visual Basic .NET" />
<img src="https://raw.githubusercontent.com/BharanitharanKR/BHgraph/main/assets/languages/erlang.svg?v=1" width="104" height="104" alt="Erlang" />
<img src="https://raw.githubusercontent.com/BharanitharanKR/BHgraph/main/assets/languages/solidity.svg?v=1" width="104" height="104" alt="Solidity" />
<img src="https://raw.githubusercontent.com/BharanitharanKR/BHgraph/main/assets/languages/terraform.svg?v=1" width="104" height="104" alt="Terraform / OpenTofu" />
<img src="https://raw.githubusercontent.com/BharanitharanKR/BHgraph/main/assets/languages/nix.svg?v=1" width="104" height="104" alt="Nix" />
</p>
<sub>每种语言的详细信息 — 扩展、框架和确切的提取内容 — 请参阅 [支持的语言](#支持的语言)。</sub>
---
## 为什么选择 BHGraph？
当 AI 代理需要理解代码时 — 回答问题或进行更改 — 它会通过缓慢的方式发现结构：grep、glob 和读取，一次一个文件，手动重建调用路径和依赖关系。在开始真正的工作之前，这已经是一堆工具调用和往返了。
**BHGraph 为代理提供其所需代码。** 它是一个预先构建的图，包含代码库中的每个符号、调用边和依赖项 — 因此，代理不是爬取文件，而是提出一个问题并获得相关源、调用路径（包括 grep 无法跟踪的动态调度跳转）和更改的辐射半径。**精确上下文，而不是逐文件搜索** — 这意味着更少的工具调用和更快的答案，无论代码库大小如何。
<img width="1536" height="1024" alt="token-cost-savings-scale" src="https://github.com/user-attachments/assets/eb74a11a-a3ab-4b01-80a6-19f78352ae8e" />
> **关于成本的说明：** BHGraph 在 *每个* 代码库上的优势是精度和速度 — 更少的工具调用、更快的答案。它还能降低 token 和美元成本，但这些节省 **依赖于规模**：在小型代码库中节省的成本很小且不明显，只有在代码库（和团队）规模较大时，节省的成本才会显现出来 — 达到 Google 或 Microsoft monorepo 的规模，再乘以整个团队每天的代理使用量 — 才能转化为真正的财务节省。对于一个 500 文件的项目，采用 BHGraph 以提高速度；成本节省在代码库（和团队）变大时才会显现出来。
### 基准测试结果
在 7 个不同语言的现实世界开源代码库中进行测试，比较了一个智能代理（Claude Code，无头）回答一个架构问题的表现，有和没有 BHGraph 加持，在每组测试中运行 4 次，取中位数。_在 Opus 4.8（2026-06-02）上重新验证，使用当前构建版本（`bhgraph_explore` 作为主要工具）。_
> **普遍的优势 — 每个仓库，每个规模：58% 更少的工具调用 · 22% 更快 · 文件读取次数减少到接近零。**
可靠、普遍的收益是**精确的上下文和速度**：BHGraph 将智能代理的 grep/find/Read 爬行转换为几个直接查询 — 直接返回您询问的方法，即使它们位于数千行文件深处 — 因此它以**接近零的文件读取**回答，而没有 BHGraph 的智能代理将其预算花费在发现上。**Tokens** 和 **Cost** 列也是真实的，但 — 如上所述 — 它们是**规模依赖**的：小型且每查询噪音较小，累积到大型代码库和高容量规模时才变成真金白银。
| 代码库 | 语言 | 工具调用 | 时间 | 文件读取 | Tokens | 成本 |
| --- | --- | --- | --- | --- | --- | --- |
| **VS Code** | TypeScript · ~10k 文件 | 减少 81% | 快 11% | 0 vs 9 | 减少 64% | 便宜 18% |
| **Excalidraw** | TypeScript · ~640 文件 | 减少 40% | 快 27% | 0 vs 7 | 减少 25% | 持平 |
| **Django** | Python · ~3k 文件 | 减少 77% | 快 13% | 0 vs 9 | 减少 60% | 便宜 8% |
| **Tokio** | Rust · ~790 文件 | 减少 57% | 快 18% | 0 vs 8 | 减少 38% | 持平 |
| **OkHttp** | Java · ~645 文件 | 减少 50% | 快 31% | 0 vs 4 | 减少 54% | 便宜 25% |
| **Gin** | Go · ~110 文件 | 减少 44% | 快 24% | 1 vs 6 | 减少 23% | 便宜 19% |
| **Alamofire** | Swift · ~110 文件 | 减少 58% | 快 33% | 0 vs 9 | 减少 64% | 便宜 40% |
<sub>**文件读取** = 智能代理在有和没有 BHGraph 的情况下打开的文件数量中位数 — 精确上下文的胜利在一列中。 **Tokens** 和 **Cost** 是相同有-vs-无的差异；它们是定向的（它们每次运行都会变化），并且每个查询的绝对值很小 — 这就是为什么它们只有在规模化时才成为一个重要的项目。 `bhgraph_explore` 还将冗余的可互换实现折叠为签名，因此响应大小适合**答案**而不是文件数量。</sub>
<details>
<summary><strong>每个仓库的详细分解 — 有 vs 没有（中位数为 4）</strong></summary>
**VS Code** · ~10k 文件
| 指标 | 有 cg | 没有 cg | Δ |
| --- | --- | --- | --- |
| 时间 | 1m 59s | 2m 13s | 快 11% |
| 文件读取 | 0 | 9 | -9 |
| Grep/Bash | 0 | 11 | -11 |
| 工具调用 | 4 | 21 | 减少 81% |
| 总 tokens | 640k | 1.79M | 减少 64% |
| 成本 | $0.68 | $0.83 | 便宜 18% |
**Excalidraw** · ~640 文件
| 指标 | 有 cg | 没有 cg | Δ |
| --- | --- | --- | --- |
| 时间 | 1m 32s | 2m 6s | 快 27% |
| 文件读取 | 0 | 7 | -7 |
| Grep/Bash | 1 | 8 | -7 |
| 工具调用 | 9 | 15 | 减少 40% |
| 总 tokens | 1.27M | 1.69M | 减少 25% |
| 成本 | $0.78 | $0.78 | 持平 |
**Django** · ~3k 文件
| 指标 | 有 cg | 没有 cg | Δ |
| --- | --- | --- | --- |
| 时间 | 1m 43s | 1m 58s | 快 13% |
| 文件读取 | 0 | 9 | -9 |
| Grep/Bash | 0 | 5 | -5 |
| 工具调用 | 3 | 13 | 减少 77% |
| 总 tokens | 559k | 1.41M | 减少 60% |
| 成本 | $0.57 | $0.62 | 便宜 8% |
**Tokio** · ~790 文件
| 指标 | 有 cg | 没有 cg | Δ |
| --- | --- | --- | --- |
| 时间 | 1m 55s | 2m 20s | 快 18% |
| 文件读取 | 0 | 8 | -8 |
| Grep/Bash | 0 | 6 | -6 |
| 工具调用 | 6 | 14 | 减少 57% |
| 总 tokens | 1.08M | 1.73M | 减少 38% |
| 成本 | $0.82 | $0.82 | 持平 |
**OkHttp** · ~645 文件
| 指标 | 有 cg | 没有 cg | Δ |
| --- | --- | --- | --- |
| 时间 | 1m 1s | 1m 29s | 快 31% |
| 文件读取 | 0 | 4 | -4 |
| Grep/Bash | 2 | 6 | -4 |
| 工具调用 | 5 | 10 | 减少 50% |
| 总 tokens | 502k | 1.10M | 减少 54% |
| 成本 | $0.41 | $0.55 | 便宜 25% |
**Gin** · ~110 文件
| 指标 | 有 cg | 没有 cg | Δ |
| --- | --- | --- | --- |
| 时间 | 1m 14s | 1m 37s | 快 24% |
| 文件读取 | 1 | 6 | -5 |
| Grep/Bash | 1 | 2 | -1 |
| 工具调用 | 5 | 9 | 减少 44% |
| 总 tokens | 651k | 847k | 减少 23% |
| 成本 | $0.46 | $0.57 | 便宜 19% |
**Alamofire** · ~110 文件
| 指标 | 有 cg | 没有 cg | Δ |
| --- | --- | --- | --- |
| 时间 | 1m 35s | 2m 21s | 快 33% |
| 文件读取 | 0 | 9 | -9 |
| Grep/Bash | 0 | 4 | -4 |
| 工具调用 | 5 | 12 | 减少 58% |
| 总 tokens | 766k | 2.10M | 减少 64% |
| 成本 | $0.57 | $0.95 | 便宜 40% |
</details>
<details>
<summary><strong>完整的基准测试详情</strong></summary>
**方法论。** 每个测试臂都是 `claude -p`（Claude Opus 4.8），无头运行在仓库上，配置 `--strict-mcp-config`：**有** = BHGraph 的 MCP 服务器启用，**没有** = 空的 MCP 配置。内置的 Read/Grep/Bash 对两者都可用。每个仓库使用相同的问题，**每个测试臂运行 4 次，报告中位数**。成本 = 运行的 `total_cost_usd`；Tokens = 处理的总 tokens（输入包括缓存 + 输出）；时间 = 墙上时钟；工具调用 = 每个工具调用，包括智能代理生成的子代理内的调用。仓库以 `--depth 1` 克隆，并由为它们服务的同一个 BHGraph 构建索引。2026-06-02 在当前构建上重新验证。这些数字低于之前的 Opus 4.7 验证 — 不是 BHGraph 回归，而是更强的本地基线：Opus 4.8 在主线程上高效 grep/reads，而不是扩展到大型 Explore 子代理扫描，因此没有 BHGraph 的测试臂比以前更精简。
**查询：**
| 代码库 | 查询 |
| --- | --- |
| VS Code | "扩展主机如何与主进程通信？" |
| Excalidraw | "Excalidraw 如何渲染和更新画布元素？" |
| Django | "Django 的 ORM 如何从 QuerySet 构建和执行查询？" |
| Tokio | "tokio 如何在其运行时调度和运行异步任务？" |
| OkHttp | "OkHttp 如何通过其拦截器链处理请求？" |
| Gin | "gin 如何通过其中间件链路由请求？" |
| Alamofire | "Alamofire 如何构建、发送和验证请求？" |
**BHGraph 为什么获胜：** 有索引可用，智能代理直接回答 — 通常一次 `bhgraph_explore` 返回相关源并停止，通常文件读取为零。没有它，智能代理在读取正确代码之前花费大部分预算在发现（find/ls/grep）上。BHGraph 仅在**直接查询**时提供帮助，因此其指令引导智能代理直接回答，而不是将探索委派给读取文件的子代理 — 否则子代理无论如何都会读取文件，BHGraph 成为开销。
</details>
---
## 主要功能
| | |
| --- | --- |
| **精确上下文** | 一个工具调用返回入口点、相关符号和代码片段 — 没有缓慢的文件逐一探索 |
| **全文搜索** | 使用 FTS5 在整个代码库中立即按名称查找代码 |
| **影响分析** | 在更改任何符号之前跟踪调用者、被调用者和完整的影响半径 |
| **始终保持最新** | 文件监视器使用本机 OS 事件（FSEvents/inotify/ReadDirectoryChangesW）带有去抖动自动同步 — 图表在您编码时保持最新，零配置 |
| **20+ 语言** | TypeScript、JavaScript、ArkTS、Python、Go、Rust、Java、C#、VB.NET、PHP、Ruby、C、C++、CUDA、Objective-C、Metal、Swift、Kotlin、Scala、Dart、Lua、Luau、R、Nix、Erlang、CFML、COBOL、Solidity、Terraform/OpenTofu、Svelte、Vue、Astro、Liquid、Pascal/Delphi |
| **框架感知路由** | 识别 Web 框架路由文件并链接 URL 模式到其处理类或函数，涵盖 17 个框架 |
| **混合 iOS / React Native / Expo** | 闭合跨语言流程，静态解析遗漏：Swift ↔ ObjC 桥接，React Native 旧版桥接 + TurboModules + Fabric 视图组件，本地 → JS 事件发射器，Expo 模块 |
| **100% 本地** | 没有数据离开您的机器。没有 API 密钥。没有外部服务。只有 SQLite 数据库 |
<details>
<summary><strong>自动同步的工作原理 — 以及您不需要手动运行 <code>bhgraph sync</code></strong></summary>
当您的智能代理（Claude Code、Cursor、Codex、opencode）启动 `bhgraph serve --mcp` 时，三个层次保持索引与代码同步 — 确保智能代理在编辑的短时间内不会得到错误的答案：
1. **文件监视器带有去抖动自动同步。** 原生 FSEvents / inotify / ReadDirectoryChangesW 监视器捕获每个源文件创建/修改/删除，并在去抖动窗口后触发重新索引（默认 `2000ms`，可通过 `BHGRAPH_WATCH_DEBOUNCE_MS` 调整，限制 `[100ms, 60s]`）。编辑爆发合并为单个同步。
2. **每个文件的过时横幅。** 在去抖动窗口期间，MCP 工具响应会引用仍待处理的文件，并在响应中添加 `⚠️` 横幅，告知智能代理直接“读取”它。待处理文件 **未** 被引用作为小页脚显示。无论如何，智能代理都会收到明确的信号 — 在 Claude Code 中验证，其中智能代理会说“直接读取文件以获取实时内容”然后打开它。
3. **连接时赶上。** 当 MCP 服务器（重新）连接时，bhgraph 运行快速的 `(size, mtime)` + 内容哈希与工作树协调 — 因此在没有运行 MCP 服务器的情况下所做的编辑（`git pull` 从终端、来自另一个编辑器的编辑、以前的智能代理会话退出）在下一个会话的第一个工具调用时被吸收。
```
agent writes src/Widget.ts
→ 监视器触发（<100ms）
→ 去抖动（默认 2s）
→ 同步；Widget.ts 索引完成
→ 下一个智能代理查询看到它
```
**随时验证** 使用 `bhgraph status`（CLI）。如果有任何待处理的文件，您将看到一个 `### Pending sync:` 部分，列出文件及其编辑年龄。
很少情况下，手动 `bhgraph sync` 有意义：监视器被禁用（沙盒环境，或 `BHGRAPH_NO_DAEMON=1`），或您在智能代理会话之外以脚本与索引交互并希望在脚本开始前进行预同步。
→ 完整的深入了解 [指南 → 索引项目](https://BharanitharanKR.github.io/bhgraph/guides/indexing/#stay-fresh-automatically).
</details>
---
## 框架感知路由
BHGraph 检测 Web 框架路由文件并发出 `route` 节点，由 `references` 边链接到其处理类或函数。查询调用者时，视图/控制器现在会显示绑定它的 URL 模式。
| 框架 | 识别的形状 |
| --- | --- |
| **Django** | `path()`、`re_path()`、`url()`、`include()` 在 `urls.py` 中（CBV `.as_view()`，带点路径） |
| **Flask** | `@app.route('/path', methods=[...])`，蓝图路由 |
| **FastAPI** | `@app.get(...)`、`@router.post(...)`，所有标准方法 |
| **Express** | `app.get(...)`、`router.post(...)` 带有中间件链 |
| **NestJS** | `@Controller` + `@Get/@Post/...`，GraphQL `@Resolver` + `@Query/@Mutation`，`@MessagePattern`/`@EventPattern`，`@SubscribeMessage` |
| **Laravel** | `Route::get()`、`Route::resource()`、`Controller@action`，元组语法 |
| **Drupal** | `*.routing.yml` 路由（`_controller`，`_form`，实体处理程序）；`.module`/`.theme`/`.install`/`.inc` 中的 `hook_*` 实现 |
| **Rails** | `get '/x', to: 'users#index'`，哈希火箭 `=>` 语法 |
| **Spring** | 方法上的 `@GetMapping`、`@PostMapping`、`@RequestMapping` |
| **Play** | `conf/routes` 中的 `GET`/`POST`/… 动词路由 → `Controller.method` 操作（Scala + Java） |
| **Gin / chi / gorilla / mux** | `r.GET(...)`、`router.HandleFunc(...)` |
| **Axum / actix / Rocket** | `.route("/x", get(handler))` |
| **ASP.NET** | 操作方法上的 `[HttpGet("/x")]` 属性 |
| **Vapor** | `app.get("x", use: handler)` |
| **React Router** / **SvelteKit** | 路由组件节点 |
| **Vue Router** / **Nuxt** | `pages/` 基于文件的路由，`server/api/` 端点，路由中间件 |
| **Astro** | `src/pages/` 基于文件的路由（`.astro` 页面 + `.ts` 端点， `[param]`/`[...rest]` 语法） |
---
## 混合 iOS / React Native / Expo 桥接
实际的 iOS 和 React Native 代码库存在于多个语言中 — Swift 调用者调用通过自动桥接的 Objective-C 选择器，一个 JS 文件调用原生模块通过 React Native 桥接，一个 JSX 组件委托给原生视图管理器。静态树提取在每个语言边界停止。BHGraph 将它们桥接起来，以便 `bhgraph_explore` 可以连接端到端流 — 调用路径和爆炸半径跨越边界而不是停止在它。
| 边界 | JS/Swift 侧 | 原生侧 | 怎么做 |
| --- | --- | --- | --- |
| **Swift → ObjC** | Swift `obj.foo(bar:)` | ObjC 选择器 `-fooWithBar:` | `@objc` 自动桥接规则（包括 init/property/protocol 表单）+ 可可语气前缀 (`With`/`For`/`By`/`In`/`On`/`At`/…) |
| **ObjC → Swift** | ObjC `[obj fooWithBar:]` | Swift `@objc func foo(bar:)` | 反向桥接名称候选；从源代码验证 `@objc` 暴露 |
| **React Native 旧版桥接** | JS `NativeModules.X.fn(...)` | ObjC `RCT_EXPORT_METHOD` / `RCT_REMAP_METHOD` · Java/Kotlin `@ReactMethod` | 解析宏/注释声明以构建 JS 名称 → 原生方法映射 |
| **React Native TurboModules** | JS `import M from './NativeM'; M.fn(...)` | 原生实现匹配 Codegen 规范 | 将 `Native<X>.ts` 规范接口视为真理 |
| **RN 原生 → JS 事件** | JS `new NativeEventEmitter(...).addListener('e', cb)` | ObjC `[self sendEventWithName:@"e" body:...]` · Swift `sendEvent(withName: "i, ...)` · Java/Kotlin `.emit("e", ...)` | 合成跨语言事件通道，键控为文字事件名称 |
| **Expo 模块** | JS `requireNativeModule('X').fn(...)` | Swift / Kotlin `Module { Name("X"); AsyncFunction("fn") { ... } }` | 解析 Expo DSL 文字；合成方法节点通过现有名称匹配解析 |
| **Fabric 视图组件** | JSX `<MyView prop={v}/>` | TS Codegen 规范 + 原生实现类 | 规范 → `component` 节点；基于约定的名称 + 后缀查找 (`View`/`ComponentView`/`Manager`/`ViewManager`) 桥接到原生 |
| **旧版 Paper 视图管理器** | JSX `<MyView prop={v}/>` | ObjC `RCT_EXPORT_VIEW_PROPERTY` · Java/Kotlin `@ReactProp` | 与 Fabric 相同 — 旧版 Paper 声明也生成 `component` + `property` 节点 |
**在每个桥接类型（每个桥接的小型 + 中型 + 大型代码库）下验证的真实代码库：**
| 桥接 | 小型 | 中型 | 大型 |
| --- | --- | --- | --- |
| Swift ↔ ObjC | [Charts](https://github.com/danielgindi/Charts) | [realm-swift](https://github.com/realm/realm-swift) | [Wikipedia-iOS](https://github.com/wikimedia/wikipedia-ios) |
| RN 旧版桥接 | [AsyncStorage](https://github.com/react-native-async-storage/async-storage) | [react-native-svg](https://github.com/software-mansion/react-native-svg) | [react-native-firebase](https://github.com/invertase/react-native-firebase) |
| RN 原生 → JS 事件 | [RNGeolocation](https://github.com/Agontuk/react-native-geolocation-service) | — | react-native-firebase |
| Expo 模块 | expo-haptics | expo-camera | expo SDK 扫描（7 个包） |
| Fabric / Paper 视图 | [react-native-segmented-control](https://github.com/react-native-segmented-control/segmented-control) | [react-native-screens](https://github.com/software-mansion/react-native-screens) | [react-native-skia](https://github.com/Shopify/react-native-skia) |
每个桥接都发出带有 `provenance:'heuristic'` 边和 `metadata.synthesizedBy:` 设置为稳定通道名称的边（例如 `swift-objc-bridge`、`rn-event-channel`、`fabric-native-impl`、`expo-module-extract`），以便智能代理可以一目了然地了解跳转是如何进入图表的。
---
## 快速开始
### 1. 运行安装程序
```bash
npx bhgraph
```
安装程序将：
- 询问要配置哪些智能代理 — 从以下自动检测已安装的智能代理：**Claude Code**、**Cursor**、**Codex CLI**、**opencode**、**Hermes Agent**、**Gemini CLI**、**Antigravity IDE**、**Kiro**
- 提示安装 `bhgraph` 到您的 PATH（以便智能代理可以启动 MCP 服务器）
- 询问配置是否适用于所有项目或仅适用于此项目
- 编写每个选定智能代理的 MCP 服务器配置，以及智能代理指令文件中的一个小型标记围栏 BHGraph 部分 — 这是子代理和非 MCP 智能代理学习 `bhgraph explore` 命令的方式，因为 MCP 服务器的自身指导仅到达主智能代理。干净地由 `bhgraph uninstall` 删除。
- 在 Claude Code 为目标之一时设置自动允许权限
安装程序 **仅配置您的智能代理** — 它 **不索引您的代码**。安装完成后，通过 `bhgraph init`（步骤 3）为每个项目构建项目图。一个全局的 `bhgraph 安装` 涵盖所有项目；您在一个项目上运行一次 `bhgraph init`。一个 `bhgraph 安装` 涵盖所有项目；您在一个项目上运行一次 `bhgraph init`。
**非交互式（脚本/CI）：**
```bash
bhgraph install --yes # 自动检测智能代理，安装全局
bhgraph install --target=cursor,claude --yes # 显式目标列表
bhgraph install --target=auto --location=local # 检测到的智能代理，项目本地
bhgraph install --print-config codex # 打印代码段，不写入文件
```
| 标志 | 值 | 默认 |
| --- | --- | --- |
| `--target` | `auto`、`all`、`none` 或 csv (`claude,cursor,...`) | 提示 |
| `--location` | `global`、`local` | 提示 |
| `--yes` | （布尔值） | 提示每个步骤 |
| `--no-permissions` | （布尔值）跳过 Claude 自动允许列表 | 允许权限开启 |
| `--print-config <id>` | 打印代码段并退出 | — |
### 2. 重启您的智能代理
重启您的智能代理（Claude Code / Cursor / Codex CLI / opencode / Hermes Agent / Gemini CLI / Antigravity IDE / Kiro），让 MCP 服务器加载。对于 MCP 服务器来说，智能代理重启后将加载。
请按照以下步骤操作：
### 3. 初始化项目
```bash
cd your-project
bhgraph init
```
为每个项目构建项目特定的知识图索引，该索引会在每次文件更改时自动同步。单个全局的 `bhgraph install` 命令适用于你打开的每个项目 - 无需为每个项目重新运行安装程序。
就这样 - 当存在 `.bhgraph/` 目录时，你的代理将自动使用 BHGraph 工具。
<details>
<summary><strong>手动设置（替代）</strong></summary>
**全局安装：**
```bash
npm install -g bhgraph
```
**添加到 `~/.claude.json`：**
```json
{
"mcpServers": {
"bhgraph": {
"type": "stdio",
"command": "bhgraph",
"args": ["serve", "--mcp"]
}
}
}
```
**添加到 `~/.claude/settings.json`（可选，自动允许）：**
```json
{
"permissions": {
"allow": [
"mcp__bhgraph__*"
]
}
}
```
<sub>一个通配符自动批准每个 BHGraph 工具 - `bhgraph_explore` 是默认列出的唯一工具，但如果您通过 `BHGRAPH_MCP_TOOLS` 重新启用其他工具，它们已经获得许可，无需提示。</sub>
</details>
<details>
<summary><strong>代理工具指导</strong></summary>
BHGraph 的 MCP 服务器会将其用法指导**自动**传递给您的代理，在 MCP `initialize` 响应中。简而言之，它告诉代理：
- **直接使用 BHGraph 回答结构问题** - 它*是*预建的索引，因此 grep/read 循环只是重复已经完成的工作。 将返回的源视为已经读取。
- **几乎所有情况下都使用 `bhgraph_explore`** - “某个功能如何工作”，流程 (“某个功能如何到达另一个功能”)，或调查某个区域。 一个调用返回相关符号的逐行源，按文件分组，它们之间的调用路径（包括动态调度跳转）以及辐射范围摘要。 在查询中命名文件或符号以读取其当前逐行源。
- **信任结果 - 不要用 grep 重新验证**，并在编辑后检查过时横幅。
- **按项目工作**：查询任何具有 `.bhgraph/` 索引的项目，通过传递 `projectPath` - 因此，monorepo 中只有某些服务被索引，或者第二个仓库在一个会话中工作。 没有索引的路径返回清晰的指导，以使用内置工具；索引仍然由您决定。
确切的文本位于 `src/mcp/server-instructions.ts` - 代理的主要源代码的单一事实来源。 由于子代理和非 MCP 工具链永远不会看到 MCP 指导，因此安装程序还会向代理的指令文件中写入一个简短的标记隔离部分，指向 `bhgraph explore` CLI 等价项。
</details>
---
## 工作原理
```
┌───────────────────────────────────────────────────────────────────┐
│ Claude Code │
│ │
│ "How does a request reach the database?" │
│ calls BHGraph tools directly — no Explore sub-agent │
│ │ │
└─────────────────────────────────┬─────────────────────────────────┘
│
▼
┌───────────────────────────────────────────────────────────────────┐
│ BHGraph MCP Server │
│ │
│ explore · one call → verbatim source + call flow + blast radius │
│ │ │
│ ▼ │
│ SQLite knowledge graph │
│ symbols · edges · files · FTS5 full-text search │
└───────────────────────────────────────────────────────────────────┘
```
1. **提取** — [tree-sitter](https://tree-sitter.github.io/) 将源代码解析为抽象语法树。 语言特定的查询提取节点（函数、类、方法）和边（调用、导入、扩展、实现）。
2. **存储** — 所有内容都进入本地 SQLite 数据库（`.bhgraph/bhgraph.db`）并具有 FTS5 全文搜索。
3. **解析** — 提取后，解析引用：函数调用 → 定义，导入 → 源文件，类继承和框架特定模式。
4. **自动同步** — MCP 服务器使用原生 OS 文件事件监视项目。 更改经过去抖（2 秒安静窗口），过滤到仅源文件，并增量同步。 图表在编码时保持最新 - 无需配置。
---
## CLI 参考
```bash
bhgraph # 运行交互式安装程序
bhgraph install # 运行安装程序（显式）
bhgraph uninstall # 从代理中删除 BHGraph（安装的逆操作）
bhgraph init [path] # 初始化项目 + 构建其图表（一步）
bhgraph uninit [path] # 从项目中删除 BHGraph（--force 跳过提示）
bhgraph index [path] # 完整索引（--force 重新索引，--quiet 输出较少）
bhgraph sync [path] # 增量更新
bhgraph status [path] # 显示统计信息
bhgraph unlock [path] # 删除阻止索引的过时锁定文件
bhgraph query <search> # 搜索符号（--kind, --limit, --json）
bhgraph explore <query> # 相关符号的源 + 调用路径（与 bhgraph_explore MCP 工具相同）
bhgraph node <symbol|file> # 一个符号的源 + 调用者，或使用行号读取文件（与 bhgraph_node 相同）
bhgraph files [path] # 显示文件结构（--format, --filter, --max-depth, --json）
bhgraph callers <symbol> # 查找调用函数/方法的内容 (--limit, --json）
bhgraph callees <symbol> # 查找函数/方法调用的内容 (--limit, --json）
bhgraph impact <symbol> # 分析更改符号影响的代码 (--depth, --json）
bhgraph affected [files...] # 查找受更改影响的测试文件（见下文）
bhgraph daemon # 管理后台守护进程 - 选择一个停止（别名：daemons）
bhgraph telemetry [on|off] # 显示或更改匿名使用情况遥测
bhgraph upgrade [version] # 更新到最新版本 (--check, --force）
bhgraph version # 打印已安装的版本（也使用 -v, --version）
bhgraph help [command] # 显示帮助， optionally for one command
```
### `bhgraph affected`
跟踪导入依赖关系，以事务方式查找哪些测试文件受更改的源文件影响。
```bash
bhgraph affected src/utils.ts src/api.ts # 传递文件作为参数
git diff --name-only | bhgraph affected --stdin # 从 git diff 输入
bhgraph affected src/auth.ts --filter "e2e/*" # 自定义测试文件模式
```
| 选项 | 描述 | 默认值 |
|--------|-------------|---------|
| `--stdin` | 从 stdin 读取文件列表 | `false` |
| `-d, --depth <n>` | 最大依赖遍历深度 | `5` |
| `-f, --filter <glob>` | 自定义 glob 以识别测试文件 | 自动检测 |
| `-j, --json` | 输出为 JSON | `false` |
| `-q, --quiet` | 仅输出文件路径 | `false` |
**CI/hook 示例：**
```bash
#!/usr/bin/env bash
AFFECTED=$(git diff --name-only HEAD | bhgraph affected --stdin --quiet)
if [ -n "$AFFECTED" ]; then
npx vitest run $AFFECTED
fi
```
---
## MCP 工具
当作为 MCP 服务器运行时，BHGraph 公开一个**单一工具** - `bhgraph_explore`。 测量的代理行为表明，一个强大的工具优于多个较窄的工具 - 误选较少，并且每次会话都节省上下文：
| 工具 | 目的 |
|------|---------|
| `bhgraph_explore` | 一次调用回答几乎任何问题 - “某个功能如何工作”，流程（“某个功能如何到达另一个功能”），或调查某个区域 - 返回相关符号的逐行源，按文件分组，它们之间的调用路径和辐射范围摘要。 表面动态调度跳转（回调，React 重新渲染，接口→实现）grep 无法跟随。 在查询中命名文件或符号以读取其当前逐行源，与 Read 工具提供的格式相同。 |
其他工具（`bhgraph_node`, `bhgraph_search`, `bhgraph_callers`, `bhgraph_callees`, `bhgraph_impact`, `bhgraph_files`, `bhgraph_status`）仍然完全功能，但**默认不列出** - 它们返回的内容已经内联出现在 `bhgraph_explore`（其辐射范围部分，关系图，符号的正文作为调用者列表）。 通过 `BHGRAPH_MCP_TOOLS` 环境变量重新启用任何一个以供 MCP 界面使用（例如 `BHGRAPH_MCP_TOOLS=explore,node,search,callers`），或使用其 CLI 等价项（`bhgraph node` / `query` / `callers` / `callees` / `impact` / `files` / `status`）。
即使服务器自己的根目录没有 `.bhgraph/` 索引，工具仍然可用：传递 `projectPath` 以查询任何索引项目 - monorepo 中的子服务，或第二个仓库 - 在同一会话中。 没有索引的路径返回清晰的指导，以使用内置工具，而不是失败。
---
## 库使用
BHGraph 可以直接嵌入。 npm 包重新导出其编程接口，
因此 `import` 和 `require` 都能在您的进程中解析 `BHGraph` 类 -
这对于将其嵌入应用程序中很有用（例如 Electron 主进程）。
```typescript
import BHGraph from 'bhgraph';
// CommonJS 也支持：
// const { BHGraph } = require('bhgraph');
const cg = await BHGraph.init('/path/to/project');
// 或：const cg = await BHGraph.open('/path/to/project');
await cg.indexAll({
onProgress: (p) => console.log(`${p.phase}: ${p.current}/${p.total}`)
});
const results = cg.searchNodes('UserService');
const callers = cg.getCallers(results[0].node.id);
const context = await cg.buildContext('fix login bug', { maxNodes: 20, includeCode: true, format: 'markdown' });
const impact = cg.getImpactRadius(results[0].node.id, 2);
cg.watch(); // 自动同步文件更改
cg.unwatch(); // 停止监视
cg.close();
```
较低级别的构建块从同一个入口点导出，供调用者直接驱动图表：
`DatabaseConnection`, `QueryBuilder`, `getDatabasePath`, `initGrammars` / `loadGrammarsForLanguages`, 和 `FileLock`.
**嵌入要求**
- 从 npm 安装 (`npm i bhgraph`）以便匹配的平台特定包 -
携带编译后的库及其依赖项 - 被一起获取。
- API 在**您的**运行时上运行，因此它需要 **Node 22.5+** 来实现内置的
`node:sqlite`（Electron 在其捆绑的 Node 是 22.5+ 时符合要求）。 CLI 和
MCP 服务器不受影响 - 它们在自包含的捆绑运行时上运行。
- 类型随包一起提供。 与任何 Node 目标库一样，
保持 `@types/node` 可用并 `skipLibCheck: true`（常见的默认值）。
---
## 配置
几乎没有 - BHGraph **默认零配置**，无需编写或保持同步即可启动。 语言支持从文件扩展名自动检测；无需为语言配置任何内容。 唯一可选文件是用于映射[自定义文件扩展名](#自定义文件扩展名)。
它跳过的内容：
- **依赖、构建和缓存目录** - `node_modules`, `vendor`,
`dist`, `build`, `target`, `.venv`, `Pods`, `.next` 等等，跨越每个
[支持的堆栈](#supported-languages) - 因此图是您的代码，而不是
第三方噪音。 即使没有 `.gitignore`，此规则也适用。
- **`.gitignore` 中的所有内容** - 在 git 仓库中通过 git 受到尊重，在非 git 项目中通过直接读取 `.gitignore` 受到尊重（根目录和嵌套）。
- **大于 1MB 的文件** - 生成的捆绑包、压缩的 JS、供应商的 blob。
要保持其他内容排除在外，请将其添加到 `.gitignore`。要将默认排除的目录**拉回**（例如，您确实希望索引供应商依赖项），
请添加取反 - `!vendor/`。 默认规则统一应用，因此提交依赖项或构建目录不会强制将其纳入图表；`.gitignore`
取反是显式选择加入。
`.gitignore` 不能删除您已**提交**的目录。但是，对于已检入存储库的供应商主题或 SDK（例如 Metronic 主题位于
`static/`），请在 `bhgraph.json` 下列出 `exclude` - gitignore 样式
模式，与存储库根目录相对的路径，在索引、同步和
监视时受到尊重：
```json
{
"exclude": ["static/", "**/vendor/**"]
}
```
相反，当实际源代码故意被 gitignore 以适应第二个
版本控制系统（SVN，Perforce）`.gitignore` 其源代码以使其不进入 Git -
强制它返回与 `include`（与 `exclude` 相反；`includeIgnored`
仅恢复嵌入的 git 仓库，而非纯源代码）：
```json
{
"include": ["Tools/", "Local/typescript/"]
}
```
BHGraph 从磁盘发现这些文件，覆盖 `.gitignore`，在索引、
同步和监视。 显式 `exclude` 仍然获胜，内置跳过
（`node_modules`, `dist`, `.git`）永远不会被重新包含。
### 自定义文件扩展名
如果您的项目使用非标准扩展名用于支持的
[语言](#supported-languages) - 例如 `.dota_lua` 用于 Lua，或 `.tpl` 用于 PHP -
这些文件默认被跳过，因为扩展名不是 BHGraph 识别的。 使用可选的 **`bhgraph.json`** 在项目根目录下映射它们：
```json
{
"extensions": {
".dota_lua": "lua",
".tpl": "php"
}
}
每个值都是支持的语言 ID。 映射合并在内置
默认值之上并在冲突时生效，因此您也可以重新指向内置的（例如
`".h": "cpp"`）。 提交文件以便与团队共享映射。 输入错误的
语言或格式错误的文件将被警告并跳过 - 它永远不会破坏
索引 - 添加或更改映射后重新索引 (`bhgraph index`)。
## 遥测
BHGraph 收集**匿名使用情况统计数据** - 使用哪些工具和命令，哪些语言被索引 -
以指导语言和代理支持工作进展。 **永远不会**
任何代码、路径、文件或符号名称、查询或 IP
地址；使用情况在本地聚合为每日总数，然后发送任何内容之前，
并且摄入端点是 [公共代码在此仓库](telemetry-worker/)
强制执行文档化的字段列表。 安装程序一开始就询问；随时关闭：
```bash
bhgraph telemetry off # 或：BHGRAPH_TELEMETRY=0，或 DO_NOT_TRACK=1
```
[`TELEMETRY.md`](TELEMETRY.md) 列出每个字段，具有关闭开关和完整的
数据处理故事。
## 支持的平台
每个版本都提供自包含的构建（捆绑的 Node 运行时 - 无需
编译）适用于所有三个桌面操作系统，Intel/AMD（x64）和 ARM（arm64）：
| 平台 | 架构 | 安装 |
|----------|---------------|---------|
| Windows | x64, arm64 | PowerShell 安装程序或 npm |
| macOS | x64, arm64 | shell 安装程序或 npm |
| Linux | x64, arm64 | shell 安装程序或 npm |
参见 [开始](#get-started) 以获取一行安装命令。
## 支持的代理
交互式安装程序自动检测并配置每个代理 - 布线
MCP 服务器（它提供自己的用法指导，因此不写入指令文件）：
- **Claude Code**
- **Cursor**
- **Codex CLI**
- **opencode**
- **Hermes Agent**
- **Gemini CLI**
- **Antigravity IDE**
- **Kiro**
支持的语言
| 语言 | 扩展名 | 状态 |
| --- | --- | --- |
| TypeScript | `.ts`, `.tsx` | 完全支持 |
| JavaScript | `.js`, `.jsx`, `.mjs` | 完全支持 |
| ArkTS (HarmonyOS) | `.ets` | 完全支持（ArkTS 支持 TypeScript 的所有功能，以及 `@Component`/`@ComponentV2` 结构体及其 ArkUI 装饰器（`@State`/`@Prop`/`@Link`/`@Local`/`@Builder`/…），`build()` 视图树 — 父→子组件边、链式属性链接到 `@Extend`/`@Styles` 函数、`.onClick(this.handler)` 事件绑定 — 状态→`build()` 重新渲染的动态调度桥、`@ohos.events.emitter` 发出→订阅者对（仅静态事件键）以及 `router.pushUrl` 文字网址 → 目标页面结构体；ohpm 工作区模块通过 `oh-package.json5` `file:` 依赖解析裸 `import { X } from "data"`，并遵循每个模块的 `main` 入口） |
| Python | `.py` | 完全支持 |
| Go | `.go` | 完全支持 |
| Rust | `.rs` | 完全支持 |
| Java | `.java` | 完全支持 |
| C# | `.cs` | 完全支持 |
| PHP | `.php` | 完全支持 |
| Ruby | `.rb` | 完全支持 |
| C | `.c`, `.h` | 完全支持 |
| C++ | `.cpp`, `.hpp`, `.cc` | 完全支持 |
| Objective-C | `.m`, `.mm`, `.h` | 部分支持（类、协议、方法、`@property`、`#import`、消息发送；`.mm` ObjC++ 可能解析不完全） |
| Metal | `.metal` | 完全支持（顶点/片段/内核函数、结构体、类型别名、调用边 — MSL 解析为 C++，并处理 `[[attribute]]` 注解） |
| CUDA | `.cu`, `.cuh` | 完全支持（内核和设备/主机函数、结构体、类、主机→内核调用边通过 `<<<grid, block>>>` 启动语法 — 模板化启动、函数指针启动（`auto kernel = &fn<...>`）、`dim3{...}` 配置以及宏定义的内核；处理 `__`/`__device__`/`__launch_bounds__符；普通 `.h`/`.hpp` 头文件中的 CUDA 被内容识别） |
| Swift | `.swift` | 完全支持 |
| Kotlin | `.kt`, `.kts` | 完全支持 |
| Scala | `.scala`, `.sc` | 完全支持（类、特质、方法、类型别名、Scala 3 | Dart | `.dart` | 完全支持 |
| Svelte | `.svelte` | 完全支持（脚本提取、Svelte 5 符文、SvelteKit 路由） |
| Vue | `.vue` | 完全支持（脚本 + 脚本设置提取、Nuxt 页面/API/中间件路由） |
| Astro | `.astro` | 完全支持（前言 + 脚本提取、模板组件/调用引用、`src/pages/` 路由） |
| Liquid | `.liquid` | 完全支持 |
| Pascal / Delphi | `.pas`, `.dpr`, `.dpk`, `.lpr` | 完全支持（类、记录、接口、枚举、DFM/FMX 窗体文件） |
| Lua | `.lua` | 完全支持（函数、带接收者的函数、局部变量、`require` 导入、调用边） |
| R | `.R` `.r` | 完全支持（每种赋值形式的函数、S4/R5/R6 类及其方法、`library`/`require` 导入、`source()` 文件引用、调用边） |
| Luau | `.luau` | 完全支持（Lua 的所有功能，以及 `type`/`export type` 别名、类型签名以及 Roblox 实例路径 `require`） |
| CFML | `.cfc`, `.cfm`, `.cfs` | 完全支持（基于标签的 `<cfcomponent>`/`<cffunction>` 和裸脚本 `component { ... }` 样式、`extends`/`implements`、嵌入式 `<cfscript>` 委托、调用边） |
| COBOL | `.cbl`, `.cob`, `. | 完全支持（程序、带有 PERFORM/GO TO 调用边的章节/段、CALL 'literal' 跨程序调用、COPY 复制书导入 — 包括独立的 `.cpy` 文件 — 数据分割记录/字段/88 级、EXEC CICS LINK/XCTL 和 EXEC SQL INCLUDE 目标；固定和自由格式） |
| Visual Basic .NET | `.vb` | 完全支持（类、模块、接口、结构体、枚举、属性、事件、`Declare` P/Invoke、`Handles`/`WithEvents`、`Inherits`/`Implements` 边、通过 VB 的调用/索引括号歧义的调用边、`As New` 实例化、内插字符串、LINQ、Unicode 标识符） |
| Erlang | `.erl`, `.hrl`, `.escript`, `.app.src`, `.app` | 完全支持（带有多个子句/多个元数的函数、`-spec` 签名、带有字段的记录、`-type`/`-opaque` 别名、`-define` 宏、`-include`/`-include_lib`/`-import` 边、局部和 `mod:fn` 远程调用 name/arity` 引用、`spawn`/`apply`/`proc_lib`/`timer`/`rpc` MFA 参数调用边、`gen_server:call/cast(?MODULE)` → 自己的 `handle_call`/`handle_cast` 链接、`-behaviour` 链接、`-export` 基于的可见性） |
| Solidity | `.sol` | 完全支持（合约、库、接口、结构体、枚举、修饰符、事件、错误、状态变量、`import`/`using` 指令、`emit`/`revert` 调用） |
| Terraform / OpenTofu | `.tf`, `.tfvars`, `.tofu` | 完全支持（资源、数据源、模块、变量、输出、提供者包括别名、`locals`；`var.`/`local.`/`module.`/资源引用，带有 Terraform 的每个目录作用域强制执行；跨边界的模块调用桥接 — 输入到子模块的变量、`module.M.out` 到子模块的输出、`source` 到模块的文件；当组件静态命名时，cloudposse/atmos `remote-state` 跨组件连接；`provider = aws.east` 选择在模块树中解析；`moved`/`import`/`removed`/`check` 块引用；`.tfvars` 赋值链接到它们设置的变量） |
| Nix |` | 完全支持（带有简单/解构/柯里化参数的let`/属性集绑定、`inherit`、`import ./ 文件边 — `./dir` 通过 `default.nix — 加上 Nix `imports = [.nix ]` `callPackage ./pkg.nix` 文件边；调用边；模块系统选项连接 — 配置写入类似 `launchd.user.agents.x = { ... }` 链接到声明 `options.launchd.user.agents` 的模块，因此选项流经模块） |
## 测量的跨文件覆盖率
影响和爆炸半径查询仅限于其背后的依赖图，因此覆盖率是衡量而不是断言的。**公平覆盖率** = 带有至少一个已解析的跨文件依赖的符号源文件的份额 — 某些东西导入、调用、引用或（通过框架约定）路由到它们 — 在每个语言的现实世界基准测试仓库中。残差始终是一个真正的静态分析前沿（运行时动态调度、反射/DI 容器、框架约定入口点、第三方代码），从不通过游戏来隐藏分母。
| 语言 | 基准测试仓库 | 覆盖率 |
| --- | --- | --- |
| TypeScript / JavaScript | 本仓库 | 95.8% |
| Python | psf/requests | 100% |
| Go | gin-gonic/gin | 96.6% |
| Rust | BurntSushi/ripgrep | 86.7% |
| Java | google/gson | 93.3% |
| C# | jbogediatR | 85.2% |
| PHP | guzzle/guzzle | 100% |
| Ruby | sidekiq/sidekiq | 100% |
| C | redis/redis | 92.2% |
| C++ | google/leveldb | 94.8% |
| Objective-C | SDWebImage | 91.6% |
| Swift | Alamofire | 95.3% |
| Kotlin | square/okhttp | 96.2% |
| Scala | gatling/gatling |.2% |
| Dart | flutter/packages | 92.4% |
| Svelte / SvelteKit | sveltejs/realworld | 100% Vue / Nuxt | nuxt/movies | 5% |
| xingwangzalux | 93% |
| Lua | nvim-telescope/telescope.nvim | 84. |
| Luau | dphfox/Fusion | 92.2% |
| Liquid | Shopify/dawn | 73.8% |
| Pascal / Delphi | PascalCoin | 77.4% |
框架路由按照相同的方式验证，在每个框架上使用一个规范的应用：Express 100%，FastAPI 98%，Flask 100%，NestJS 96.8%，Gin 96.5%，Axum 100%，Rocket 93.8%，Vapor 100%，Laravel 92%，Rails 89.6%，React Router 100% — 以及在它们的诚实静态分析上限的约定/反射重的框架：ASP.NET 83.9%，Spring 83.3%，Drupal 78.9%，Play 76.3%，Django 74.1%。SvelteKit、Vue/Nuxt 和 Astro 使用基于文件的路由，因此它们的页面/端点覆盖率是 Svelte/SvelteKit（100%）、Vue/Nuxt（93.5%）和 Astro（93.0% — 每个 `src/pages/` 文件映射到一个路由节点）在表中的数字。
## 故障排除
**"BHGraph 未初始化"** — 在项目目录中运行 `bhgraph init`。
**索引速度慢** — 检查是否排除了 `node_modules` 和其他大目录。使用 `--quiet` 减少输出开销。
**MCP 遇到 `database is locked`** — 当前构建不应这样：BHGraph 捆绑了自己的 Node 运行时，并使用 Node 内置的 `node:sqlite` 以 WAL 模式运行，其中并发读取永远不会阻塞写入。如果您仍然看到它：
- **您正在使用旧版本（0.9 之前）。** 重新安装以获取捆绑的运行时 — `curl -fsSL https://raw.githubusercontent.com/BharanitharanKR/BHgraph/main/install.sh | sh`（macOS/Linux），`irm https://raw.githubusercontent.com/BharanitharanKR/BHgraph/main/install.ps1 | iex`（Windows），或 `npm i -g bhgraph@latest- **`bhgraph status` 显示 `Journal:` 除 `wal` 之外** — WAL 无法在此文件系统上启用（在网络共享和 WSL2 `/mnt` 上很常见），因此读取可能会阻塞写入。将项目（及其 `.bhgraph/` 文件夹）移动到本地磁盘。
**MCP 服务器无法连接** — 代理启动服务器本身，因此您不需要手动启动它。确保项目已初始化和索引 (`bhgraph status`)，并且您的 MCP 配置中的路径正确。如果仍然无法连接，请重新运行 `bhgraph install` 以重写配置。
**MCP 工具调用失败，出现 `Transport closed`，而 `bhgraph status`/`sync` 健康** — 几乎总是 WSL2，项目位于 Windows 驱动器（路径为 `/mnt/c` 或 `/mnt/d`），其中 BHGraph 用于在会话之间共享后台服务器的本地套接字不可靠。BHGraph 现在会回落到在进程中提供会话，而不是断开连接，但如果您仍然遇到问题，请在 MCP 服务器的环境中设置 `BHGRAPH_NO_DAEMON=1`，以完全跳过共享服务器。 将项目移动到 Linux 原生文件系统（例如 `~/` 而不是 `/mnt/`）可以恢复共享服务器。
**缺少符号** — MCP 服务器在保存时自动同步（等待几秒钟）。如有需要，可以手动运行 `bhgraph sync`。检查文件的语言是否受支持，以及文件是否位于 `.gitignore` 的目录或默认排除的目录（例如 `node_modules`、`dist`）中。
**在 Windows 和 WSL 之间共享一个检出** — 不要指向同一个 `.bhgraph/`：后台服务器锁和 SQLite 索引与写入它们的 OS 绑定，跨 WSL2/Windows 文件系统边界的 SQLite 锁定不可靠。给每个端一个单独的索引在同一棵树中，通过在其中一个上设置 `BHGRAPH_DIR` 为不同的名称 — 例如在 Windows 上为 `BHGRAPH_DIR=.bhgraph-win`，而 WSL 默认使用 `.bhgraph`。BHGraph 在索引和监视时跳过任何兄弟 `.bhgraph-*` 目录，因此两者永远不会相互干扰。
## 星史
<a href="https://www.star-history.com/?repos=BharanitharanKR%2Fbhgraph&type=date&legend=top-left">
<picture>
<source media="(prefers-color-scheme: dark)" srcset="https://api.star-history.com/chart?repos=BharanitharanKR/BHgraph&type=date&theme=dark&legend=top-left" />
<source media="(prefers-color-scheme: light)" srcset="https://api.star-history.com/chart?repos=BharanitharanKR/BHgraph&type=date&legend=top-left" />
<img alt="Star History Chart" src="https://api.star-history.com/chart?repos=BharanitharanKR/BHgraph&type=date&legend=top-left" />
</picture>
</a>
## 许可证
MIT
---
<div align="center">
**为 AI 编码代理而制 — Claude Code, Cursor, Codex CLI, opencode, Hermes Agent, Gemini CLI, Antigravity IDE, 以及 Kiro**
[报告 Bug](https://github.com/BharanitharanKR/BHgraph/issues) · [请求功能](https://github.com/BharanitharanKR/BHgraph/issues)
</div>
MCP 配置
以下是此 MCP Server 的配置信息，可直接复制到 Cursor 或其他 MCP 客户端中使用。
mcp.json
连接信息
猜你喜欢
暂无推荐服务器