# Graphify

> 代码结构的实时地图。已连接的智能体向它提出结构性问题而不是 grep，每次查询都会在地图上实时亮起。

Source: https://docs.neurosquad.ai/zh/plugins/graphify

像“请求是怎么到达数据库的？”或“改了 `parseConfig` 会影响什么？”这样的问题，智能体通常要靠一长串
grep 和读文件才能回答。**Graphify** 插件用 Graphify-Labs 的开源工具
[graphify](https://github.com/Graphify-Labs/graphify) 把工作区转换为知识图谱：文件、函数、类、调用、
导入、Markdown 章节以及 `NOTE:` / `WHY:` 注释，并按子系统分组。已连接的智能体用自然语言或符号名向图谱
提问，一次调用就能得到图谱中相关的部分，每个结果都带有文件和行号。

卡片把图谱画成一张地图，智能体的每次查询都会在上面实时回放：你能看到智能体问了什么、从哪些节点出发、
搜索如何扩散、找到了什么。

## 如何使用

1. 在添加卡片菜单中选择**插件…**，在**插件**标签页中打开 **Graphify**，然后点击**添加到画布**。
2. 点击卡片上的**安装**（每台电脑一次）。NeuroSquad 从 GitHub 下载 [uv](https://github.com/astral-sh/uv)
0.12.22，并按应用中固定的校验和进行核对；uv 配置独立的 Python 3.12，然后从 PyPI 安装 graphify 0.9.74，
每个包都按哈希固定（`--require-hashes`，仅使用二进制包）。约 250 MB，全部放在应用的数据文件夹中。
不会使用或修改你自己的 Python、uv 或 pip 设置。
3. 随后卡片会自动构建**整个工作区**的图谱，并显示已读取的文件数、总数和预计剩余时间。
4. 从智能体向卡片画一条[箭头](https://docs.neurosquad.ai/zh/canvas/arrows)。

现在智能体就拥有了图谱工具。大多数 CLI 无需重启即可使用；删除箭头后工具随之消失。

## 智能体能做什么

| 工具 | 回答什么 |
| --- | --- |
| `graphify_query` | 用自然语言或符号名提问 → 相关子图（符号、带行号的文件、调用和导入关系） |
| `graphify_neighbors` | 某个符号调用了什么、被谁调用、导入了什么、被谁导入，以及每处使用的文件和行号 |
| `graphify_path` | 两处之间最短的调用/导入链 |
| `graphify_affected` | 修改的影响范围：所有直接或间接依赖某个符号或文件的内容 |
| `graphify_node` | 某个符号的位置、类型和所属子系统 |
| `graphify_community` | 某个子系统的全部成员 |
| `graphify_god_nodes` | 连接最多的符号——代码库的核心 |
| `graphify_stats` | 图谱规模，以及有多少关系是直接从代码中读出的 |
| `graphify_reindex` | 立即更新图谱，以反映刚刚的修改 |

首次构建尚未完成时，工具会回答当前进度（“仍在构建：37%，已读 461 个文件中的 170 个…”），智能体可以先用
常规搜索，稍后再问。

## 如何引导智能体使用图谱

拥有图谱工具的智能体并不总会用它：模型习惯了 grep。Graphify 增加了三层轻量引导，任何一层都不会阻止操作：

- **工具描述**会说明何时图谱更合适（“当问题与结构有关时，先于 grep 使用”），以及何时文本搜索仍然是对的
（字符串字面量、日志信息、配置值）。在 Claude Code 中，`graphify_query`、`graphify_neighbors` 和
`graphify_affected` 始终加载，而不是藏在工具搜索后面。
- **首个回合的说明。** 带有箭头的会话的第一个回合会附上一段简短、客观的说明：图谱是什么、哪个工具回答
哪类问题、何时 grep 仍然合适。之后，当提示与代码结构有关时（以及无论如何每五个回合一次），会附上一行
提醒。删除箭头后，下一个回合会收到一条说明，告知这些工具已不可用。Claude Code、Codex 和 Qwen Code
通过提示钩子接收；OpenCode、Kilo Code、pi、omp 和 Gemini CLI 通过 NeuroSquad 的插件、扩展或钩子桥接接收。
其他 CLI 只获得工具。
- **文本搜索前的提示（Claude Code）。** 当智能体准备对看起来像符号名的内容执行 `Grep`、`Glob`，或
`grep` / `rg` / `find` 命令时，会收到一行上下文，指向 `graphify_neighbors` 和 `graphify_query`。
搜索仍会按原样执行：不做任何权限决定，你的 allow / deny 规则和确认提示照常生效。智能体使用图谱后的
两分钟内不会提示，之后最多每 45 秒、每四次搜索提示一次。

在卡片设置中关闭**引导智能体使用图谱**，即可只保留工具。

## 地图

- **文件**显示为圆点，大小取决于内容多少，颜色取决于子系统。放大（或点击**显示符号**）即可看到每个文件
周围的函数和类。
- **实时查询。** 智能体查询图谱时，起始节点会泛起涟漪，搜索沿着经过的关系逐跳扩散，结果面板列出找到的
内容及文件和行号。点击结果可将地图定位到该处，或在编辑器中打开文件。
- 底部的**时间线**：最近的查询及提问者。点击即可重新回放。
- 在角落的输入框中自己**搜索**图谱，匹配项同样会亮起。
- **点击节点**查看详情和关系；**适应视图**让所有内容回到视野中。
- **展开**卡片，以大视图查看地图。

用鼠标拖动地图，用滚轮缩放；当你缩放画布或卡片不在屏幕上时，地图动画会暂停。

## 始终保持最新

开启**自动更新**（默认开启）时，卡片会发现更改过的文件，并在最后一次更改约 4 秒后更新图谱。已连接的
智能体完成一个回合后，以及每次打开应用时，也会更新一次。graphify 会缓存读过的每个文件，因此更新只会重新
读取有变化的部分。关闭后可用**立即更新**手动更新。

## 设置

卡片标题栏中的设置按钮：

- **自动更新**和**引导智能体使用图谱**（见上文）。
- **语言**：从图谱中排除整门语言。
- **额外忽略**：额外的模式，每行一个，`.gitignore` 语法。项目中的 `.gitignore` 和 `.graphifyignore`
始终生效。
- **包含 git 忽略的文件**：适用于应进入图谱的生成代码。

更改索引范围会重新构建图谱。

## WSL 和 SSH 工作区

- **WSL**：graphify 在 Windows 上运行，通过 Windows 路径读取发行版中的文件。位于 Windows 磁盘上的项目
（`/mnt/c/…`）照常监视文件；位于发行版自身磁盘上的项目，会在已连接智能体完成回合后以及点击**立即更新**
时更新。
- **SSH**：不支持，卡片会注明。请使用[代码图谱](https://docs.neurosquad.ai/zh/plugins/code-graph)插件，它会在 SSH 主机上运行自己的引擎。

## Graphify 还是代码图谱？

两者都会索引代码，但擅长回答的问题不同，可以同时使用。

| | 代码图谱 | Graphify |
| --- | --- | --- |
| 擅长 | 精确导航：调用者和被调用者、代码片段、只读 Cypher、语义搜索 | 用自然语言提问 → 相关子图、事物之间如何关联、修改会影响什么 |
| 还会映射 | 路由、包 | 子系统、Markdown 章节、`NOTE:` / `WHY:` 注释 |
| 卡片上 | 索引统计和搜索框 | 实时地图，动画展示每次查询 |
| WSL / SSH | 在 WSL 内和 SSH 主机上运行 | WSL 通过 Windows 路径；不支持 SSH |

> 图谱基于工作区文件夹构建。在隔离 worktree 中工作的智能体查询的仍是主文件夹的图谱。

## 隐私与存储

一切都在你的电脑上运行。Graphify 只读取代码（不处理需要语言模型的文档、图片等内容），从不使用语言模型，
也不会向它传递任何 API 密钥。graphify 没有遥测，其可选的查询日志已关闭。引擎位于应用的数据文件夹中，每个
图谱位于其中的 `graphify/projects/<文件夹>-<哈希>/`。不会向你的项目或主目录写入任何内容。删除某个文件夹的
最后一张卡片会删除其图谱。

graphify 由 Graphify-Labs 开发，以 Apache License 2.0 发布。

## 故障排除

- **在代理后安装失败。** uv 使用应用环境中的 `HTTPS_PROXY` / `HTTP_PROXY`；在启动 NeuroSquad 之前设置它，
然后再次点击**安装**。
- **安装失败，提示 “no matching distribution”。** 某个包没有适用于你系统的二进制包；graphify 不会从源码
构建。卡片会显示 uv 的消息。
- **“仍在构建”。** 非常大的工作区首次构建需要一些时间；卡片会显示进度，智能体提问时也会得到同样的进度。
- **智能体仍在使用 grep。** 检查箭头是否存在、**引导智能体使用图谱**是否开启，以及智能体的 CLI 是否属于
接收指引的那些（其他 CLI 会被卡片标为“仅工具”）。也可以直接要求它：“用 graphify 查找…”。
- **地图为空或缺少文件。** 检查设置中的**语言**和**额外忽略**，以及项目的 `.gitignore`。
- **卡片提示不支持 SSH。** SSH 工作区请使用代码图谱插件。