内容
# 图烯
**AI 编程代理的持久化结构化内存。**
图烯将您的代码仓库转换为可查询的图，从而使 Claude、Cursor 等 MCP 兼容的辅助工具能够在约 20 毫秒内回答这些问题，而无需读取任何文件。 **尤其是在大型、多模块或不熟悉的代码库中**，`grep` 导航和跟踪变得非常困难：
- 是哪些函数调用了这个函数？
- 哪些模块依赖于这个模块？
- 什么是架构中心？
- 哪些是这些组件之间的最短路径？
- 哪些文件属于同一社区？
它取代了 `grep` 导航和跟踪，而不是源代码理解。
---
## 为什么图烯存在
AI 编程辅助工具擅长阅读代码，但它们导航代码仓库的方式就像人类使用 `grep` 一样：搜索符号、打开文件、跟踪导入、打开更多文件、推断关系。然后在下一个会话中重复这一过程。
在一个包含 50 个文件的项目中，`grep` 很好用。但在一个包含 5,000 个文件的单体仓库中，情况就不同了。这种工作流程有五个持久化问题：
- **重复冷启动。** 每个新会话都始于对代码仓库的临时模型。
- **上下文窗口压力。** 原始源文件很大；导航消耗的令牌可能用于推理。
- **没有结构化内存。** 读取文件后，辅助工具没有关于模块、函数和概念如何关联的持久化图。
- **错过跨文件关系。** `grep` 表面显示文本匹配，而不是架构拓扑、中心、社区或路径。
- **规模扩大了问题。** 每个新文件和依赖项都使 `grep` 和跟踪循环变慢、更昂贵。而图烯的图则保持快速，不受仓库大小影响。
图烯运行一次分析，将结果持久化为图，并通过 [MCP](https://modelcontextprotocol.io) 服务器将其公开给辅助工具。该图成为辅助工具对您代码仓库的长期内存。
**变化：**
- **几秒钟内定位，而不是几分钟。** `architecture_summary` 在辅助工具读取任何文件之前提供 30 秒的编码库地图。
- **上下文保持聚焦。** 导航时，辅助工具不会用原始源代码填充上下文窗口，而是基于紧凑的图输出进行推理，只读取相关文件。
- **内存在会话之间存活。** 图烯的图持久存在，新 AI 会话开始时具有与最后一个会话相同的结构知识。
---
## 适用场景（和不适用场景）
**适用场景：**
- **导航大型代码库。** 在 50+ 文件的仓库、monorepos 或不熟悉的项目中，`grep` 和跟踪浪费上下文；图烯的图取代了它们。
- AI 辅助代码导航：无需重复读取文件即可回答结构化问题。
- 影响分析：在更改函数、类或模块之前识别连接的节点。
- 入职培训：快速获得不熟悉的仓库的高级架构地图。
- 重构规划：查找神节点、低凝聚力社区和令人惊讶的跨边界边缘。
- 代码审查：在审查更改的文件之前检查符号、度数和热点。
- 在活跃开发期间使用 `watch` 模式保持图的更新。
**不适用场景：**
- **阅读源代码。** 图烯的图捕获结构和关系，而不是实现逻辑。辅助工具仍需要阅读实际代码。
- **全功能语言服务器。** 它不执行完整的类型检查或 LSP 深度语言特定语义分析。
- **运行时跟踪。** 它是静态分析加上可选的 LLM 提取；它不执行程序。
- **语义搜索/嵌入。** 图烯使用关键词评分和图遍历，而不是向量相似性。
- **安全扫描。** 关系图不是专用 SAST 工具的替代品。
---
## 20 秒示例
```text
没有图烯：
grep → 读取文件 → 跟踪导入 → 读取更多文件 → 推断架构
使用图烯：
query_graph → get_neighbors → shortest_path → 只读取正确的文件
```
```sh
# 为您的项目构建图（不需要 API 密钥）
gm run . --no-semantic --no-viz
# 提问结构化问题
gm query "什么调用了 build_from_extraction？"
# 或连接 AI 辅助工具通过 MCP 直接提问
```
---
## 快速入门
### 一行安装
```sh
curl -fsSL https://raw.githubusercontent.com/lambda-alpha-labs/Graphenium/main/install.sh | sh
```
### 从源码
需要 Rust 1.75+ ([rustup](https://rustup.rs)).
```sh
git clone https://github.com/lambda-alpha-labs/Graphenium
cd Graphenium
cargo install --path .
```
二进制文件安装为 `gm`.
### 首次运行
```sh
# 构建图（不需要 API 密钥）
gm run . --no-semantic --no-viz
# 查询它
gm query "authentication login session" --budget 1000
# 检查您的安装
gm doctor
```
---
## 地图与流量叠加层
图烯有两种提取模式。两者都很有用；它们服务于不同的目的。
| 模式 | 您获得的内容 | 最适合 | API 密钥 |
|---|---|---|---|
| **仅 AST** | 导入、包含、方法、符号、结构社区 | 架构地图、爆炸半径、定位 | 否 |
| **语义** | 使用、概念依赖、理由、推断的跨文件关系 | 行为跟踪、更丰富的代理推理 | 是 |
> 仅 AST 模式为辅助工具提供地图。语义模式添加流量叠加层。
```sh
# 仅 AST，本地，不需要密钥
gm run . --no-semantic --no-viz
# 语义：添加 LLM 推断的关系
export ANTHROPIC_API_KEY=sk-ant-...
gm run . --provider anthropic # 也可以：openai, deepseek, openrouter
```
`graph_stats` 工具始终报告边缘置信度分解，以便辅助工具了解其使用的数据。
---
## MCP 设置
将图烯添加到 AI 辅助工具的 MCP 配置中。服务器使用标准的 MCP stdio 传输协议。或者运行 `gm setup <target>` 以打印辅助工具的配置。
**Claude Desktop** (`claude_desktop_config.json`):
```json
{
"mcpServers": {
"graphenium": {
"command": "gm",
"args": ["serve", "--graph", "/absolute/path/to/graphenium-out/graph.json"]
}
}
}
```
**Cursor** (`~/.cursor/mcp.json`):
```json
{
"mcpServers": {
"graphenium": {
"command": "gm",
"args": ["serve", "--graph", "/absolute/path/to/graphenium-out/graph.json"]
}
}
}
```
**CodeWhale** (`~/.codewhale/mcp.json`):
```json
{
"servers": {
"graphenium": {
"command": "/absolute/path/to/gm",
"args": ["serve", "--graph", "/absolute/path/to/graphenium-out/graph.json"],
"env": {}
}
}
}
```
**更新配置后，请完全退出并重启 AI 工具** （macOS 上为 Cmd+Q，而不是关闭窗口）。MCP 服务器仅在启动时加载。
---
## AI 技能
仓库中附带了一个 AI 技能，位于 `skills/graphenium/SKILL.md`，它教导辅助工具该使用哪个工具、如何解释置信度以及如何在 MCP 不可用时回退到 `gm query`。
---
## 辅助工具可以提问
连接后，辅助工具可以访问 13 种图工具。
**读取工具：**
| 工具 | 目的 |
|---|---|
| `graph_stats` | 节点/边计数、文件类型、置信度分解 |
| `architecture_summary` | 社区、焦点路径、神节点、置信度总结 |
| `query_graph` | 关键词评分的 BFS/DFS 遍历，限令牌预算 |
| `get_node` | 按 ID 或标签获取完整节点详细信息 |
| `get_neighbors` | 直接邻居，带有边类型和置信度 |
| `get_community` | 集群社区中的所有节点 |
| `god_nodes` | 前 N 个最连接的中心节点 |
| `shortest_path` | 任意两个组件之间的路径 |
| `summarize_file` | 从源文件提取的每个符号 |
| `reload_graph` | 热交换图，无需重启 |
**写入工具：**
| 工具 | 目的 |
|---|---|
| `add_node` | 注册 AST 无法捕获的概念 |
| `add_edge` | 记录通过检查确认的关系 |
| `remove_edge` | 纠正假阳性或过时关系 |
所有写入操作立即持久化到磁盘。
---
## 仓库内存模型
图烯将代码库建模为三个事物。
### 节点
节点代表有意义的实体：函数、方法、类、模块、结构体、特征、文档、图像和架构概念。每个节点都带有元数据：标签、限定标签、文件类型、源文件、源位置和社区 ID。
### 边
边是类型化的有向关系。
| 关系 | 含义 | 来源 |
|---|---|---|
| `imports` | 模块级导入/包含 | AST |
| `contains` | 模块/类包含符号 | AST |
| `method` | 方法属于类/类型 | AST |
| `calls` | 函数调用另一个函数 | AST / 语义 |
| `uses` | 跨文件使用依赖 | AST / 语义 |
| `inherits` | 面向对象编程继承 | AST / 语义 |
| `implements` | 接口/特征实现 | AST / 语义 |
| `depends_on` | 概念依赖 | 语义 |
| `rationale_for` | 文档/注释解释代码 | 语义 |
### 拓扑
图烯分析图以显示社区、中心节点、最短路径、令人惊讶的跨社区连接和架构焦点路径。辅助工具可以在阅读实现细节之前在结构上定位。
---
## 信任模型
每条边都带有置信度。
| 级别 | 来源 | 如何对待它 |
|---|---|---|
| `EXTRACTED` | 确定的静态提取 | 真实，直接存在于源代码中 |
| `INFERRED` | LLM 或启发式推理 | 强烈的提示，有用导航；验证后再进行风险更改 |
| `AMBIGUOUS` | LLM 标记的不确定性 | 需要调查的问题，而不是事实 |
良好的辅助工具工作流程：
1. 将 `EXTRACTED` 边视为事实。
2. 使用 `INFERRED` 边作为强烈提示。
3. 将 `AMBIGUOUS` 边视为需要检查的线索。
4. 在进行实现更改前阅读源代码。
`graph_stats` 报告置信度分解，以便您了解正在使用的图的类型。
---
## 语言支持
图烯使用 [tree-sitter](https://tree-sitter.github.io/) 在 9 种语言中进行 AST 提取。
| 语言 | 扩展名 | 提取的特征 |
|---|---|---|
| Python | `.py` | 类、函数、导入、调用图 |
| JavaScript | `.js`, `.mjs`, `.cjs` | 类、函数、箭头函数、导入 |
| TypeScript | `.ts`, `.tsx` | JavaScript 功能 + 类型声明 |
| Rust | `.rs` | 结构体、枚举、特征、实现块、函数、`use` |
| Go | `.go` | 函数、带有接收者的函数、导入块 |
| Java | `.java` | 类、方法、包导入 |
| C | `.c`, `.h` | 函数、包含指令 |
| C++ | `.cpp`, `.cc`, `.cxx`, `.hpp` | 类、函数、包含指令 |
| C# | `.cs` | 类、方法、使用指令、命名空间 |
语义提取还处理文档（`.md`, `.rst`, `.txt`）、PDF 和图像。
使用您需要的语言构建：
```sh
cargo build --release --no-default-features --features lang-python,lang-rust
```
功能：`lang-python`, `lang-js`, `lang-ts`, `lang-rust`, `lang-go`, `lang-java`, `lang-c`, `lang-cpp`, `lang-csharp`.
---
## 命令
### `gm run`
在目录上运行完整的分析管道。
```
gm run [PATH] [OPTIONS]
```
| 选项 | 描述 |
|---|---|
| `PATH` | 要分析的目录（默认为 `.`） |
| `--no-semantic` | 跳过 LLM 提取；使用仅 AST 结果 |
| `--no-viz` | 跳过 HTML 生成 |
| `--provider NAME` | AI 提供商：`anthropic`（默认）、`openai`、`openrouter`、`deepseek`、`openai-compatible` |
| `--model NAME` | 要使用的模型（默认为提供商特定的默认模型） |
| `--api-key KEY` | API 密钥（覆盖提供商特定的环境变量） |
| `--api-base URL` | `openai-compatible` 提供商的 API 基 URL |
| `--mode deep` | 激进的 LLM 推理 |
| `--update` | 增量：仅重新提取更改的文件 |
```sh
gm run . --no-semantic --no-viz # 快速仅 AST 扫描
gm run . --provider openai # 带有 LLM 语义提取
gm run . --update # 增量编辑文件后
```
### `gm query`
使用关键词查询现有的图。
```
gm query "<keywords>" [OPTIONS]
```
| 选项 | 默认值 | 描述 |
|---|---|---|
| `--graph PATH` | `graphenium-out/graph.json` | 图文件路径 |
| `--budget N` | `2000` | 输出令牌预算 |
| `--dfs` | 关闭 | 使用深度优先搜索 |
```sh
gm query "authentication login session"
gm query "parser ast walker" --dfs --budget 4000
```
### `gm serve`
启动一个 MCP 服务器，通过 stdio 公开图。
```
gm serve [OPTIONS]
```
| 选项 | 默认值 | 描述 |
|---|---|---|
| `--graph PATH` | `graphenium-out/graph.json` | 图文件路径 |
### `gm watch`
监视目录并在更改时自动重建图。
```
gm watch [PATH] [OPTIONS]
```
| 选项 | 默认值 | 描述 |
|---|---|---|
| `PATH` | `.` | 要监视的目录 |
| `--debounce SECS` | `3.0` | 最后事件发生后等待时间 |
| `--incremental` | `true` | 补丁更改的文件；`false` 进行完整重建 |
```sh
gm watch . --debounce 2.0
```
### `gm doctor`
对 Graphenium 安装运行诊断检查：二进制位置、图文件健康状况、tree-sitter 语言、API 密钥和图质量。
```
gm doctor [--graph PATH]
```
### `gm setup`
为 AI 辅助工具打印可粘贴的 MCP 配置。
```
gm setup <claude|cursor|codewhale> [--graph PATH]
```
```sh
gm setup claude
gm setup cursor
gm setup codewhale
```
---
## 输出文件
Graphenium 将输出写入 `graphenium-out/` 目录中分析的目录。
| 文件 | 目的 |
|---|---|
| `graph.json` | 机器可读的图，用于 `gm serve` 和 `gm query` |
| `GRAPH_REPORT.md` | Markdown 架构报告 |
| `graph.html` | 自包含的视觉图检查页面 |
| `manifest.json` | 增量更新的 mtime 索引 |
| `cache/` | 每个文件的语义提取缓存（SHA256 键控） |
---
## 架构
```
src/
extract/ 9 种语言的 tree-sitter 提取
model/ 图、节点、边、超边类型
build/ 从提取结果构建图
cluster/ Louvain 社区检测、凝聚力、分割/焦点
detect/ 文件分类、敏感文件跳过、语料库警告
analyze/ 神节点、令人惊讶的连接、架构问题
serve/ MCP 服务器（rmcp）、工具处理程序、图遍历
semantic/ LLM 客户端、提示构建器、响应解析器
export/ JSON 导出、HTML 可视化
cache/ mtime 清单、语义提取缓存
watch/ 文件系统监视器，增量修补
```
---
## 限制
- **仅 AST 图是结构性的，而不是行为性的。** 没有语义提取，边主要是导入、包含和方法声明。控制流关系（`calls`, `uses`, `implements`）来自语义传递。
- **标签冲突。** 像 `new`, `mod`, `run` 这样的常见名称出现在模块中。 可用的限定标签帮助消歧义时可用。 `graph_stats` 报告冲突计数，以便您知道结果可能模糊。
- **大型语料库。** 具有许多供应商依赖项的项目应使用 `.grapheniumignore` 排除 `target/`、`node_modules/`、`.rust-toolchain/` 和类似目录。
---
## 贡献
欢迎贡献，特别是语言提取器、MCP 集成和夹具。参见 [CONTRIBUTING.md](CONTRIBUTING.md)。
[好问题 →](https://github.com/lambda-alpha-labs/Graphenium/issues?q=is%3Aissue+is%3Aopen+label%3A%22good+first+issue%22)
· [工作示例 →](worked/)
· [演示脚本 →](scripts/demo.sh)
