内容
<p align="center">
<img src="docs/assets/graphtrail-social-preview.jpg" alt="GraphTrail banner" width="900">
</p>
<h1 align="center">GraphTrail</h1>
<p align="center">
<strong>一个本地代码图谱的辅助工具，它将您的代码仓库映射到一个 SQLite 图谱中，包含符号、导入和调用边，然后通过 CLI 和只读 MCP 服务器回答调用者、被调用者、影响和上下文。 它是 AI 代理在编辑前读取的内容，因此变更始于调用图谱而非猜测。 与 grep 或嵌入索引不同，它遍历真实的 tree-sitter 调用边，保持只读，不运行守护进程，不进行网络调用。</strong>
</p>
<p align="center">
<a href="https://graphtrail.escoffierlabs.dev"><strong>网站 → graphtrail.escoffierlabs.dev</strong></a>
</p>
<p align="center">
<img src="https://shieldcn.dev/github/ci/escoffier-labs/graphtrail.svg?branch=master&workflow=ci.yml" alt="CI 状态">
<img src="https://shieldcn.dev/badge/crate-v0.2.0-orange.svg?logo=rust&logoColor=white" alt="Crate 版本 0.2.0">
<img src="https://shieldcn.dev/badge/license-MIT-green.svg" alt="MIT 许可证">
<img src="https://shieldcn.dev/badge/MCP-server-8A2BE2.svg" alt="MCP 服务器">
</p>
GraphTrail 对您的代码进行索引，一旦完成，便会保持增量更新，并在代理触及一行代码之前回答结构性问题。
<p align="center">
<img src="docs/assets/graphtrail-context.svg" alt="Recording: graphtrail init and sync build a code graph, then callers and context answer structural questions before an edit" width="760">
</p>
<p align="center"><em><code>graphtrail init</code> 和 <code>sync</code> 索引仓库，然后 <code>callers</code> 和 <code>context</code> 直接从代码图谱中回答。</em></p>
索引仓库，然后询问谁调用某个符号以及编辑前代理应加载的上下文。`context` 包是代理通过 MCP 获取的。
## 功能
GraphTrail 是一个用于 AI 编码代理和开发者的代码图谱导航工具。 它使用 tree-sitter 解析每个源文件，单次遍历提取符号（函数、类、方法）、导入和调用边，并将它们写入 `.graphtrail/` 下的小型本地 SQLite 图谱中。 从该图谱中，它回答您在更改代码前提出的结构性问题：全文符号搜索、符号的调用者、被调用者、影响（变更的辐射范围）和上下文包，汇总入口点及其调用者和被调用者邻居以完成任务。
它通过同一个图谱提供了两个接口：用于人类和脚本的命令行界面和只读模型上下文协议（MCP）服务器 (`graphtrail-mcp`)，该服务器将相同的查询暴露为工具，代理可以调用。 MCP 服务器以 `SQLITE_OPEN_READ_ONLY` 打开每个连接，因此它永远不会修改您的图谱，并且它是多仓库的：一个运行的服务器可以回答您索引的任何仓库的问题。 它支持 Python、TypeScript/JavaScript、Rust 和 Go。 索引后，它是只读的，不安装钩子，不启动守护进程，不进行网络调用。
## 安装
GraphTrail 是一个 Rust 软件包，包含两个二进制文件：`graphtrail`（CLI）和 `graphtrail-mcp`（MCP 服务器）。 从 [crates.io](https://crates.io/crates/graphtrail) 安装两者：
```bash
cargo install graphtrail
```
或跟踪仓库头部：
```bash
cargo install --git https://github.com/escoffier-labs/graphtrail
```
或从克隆仓库后构建：
```bash
git clone https://github.com/escoffier-labs/graphtrail.git
cd graphtrail
cargo build --release # binaries land in target/release/
```
## 快速入门
索引仓库，然后向图谱提出结构性问题：
```bash
# 索引一次，然后保持最新状态。
graphtrail init /path/to/repo
graphtrail sync /path/to/repo # 增量：无操作时无变更
graphtrail sync /path/to/repo --force # 重新构建每个文件
# 查询仓库的图谱数据库。
DB=/path/to/repo/.graphtrail/graphtrail.db
graphtrail --db "$DB" search "handoff lint"
graphtrail --db "$DB" callers serve
graphtrail --db "$DB" callees serve
graphtrail --db "$DB" impact serve --depth 3
graphtrail --db "$DB" context "handoff lint" --json
graphtrail --db "$DB" stats --json
```
对 GraphTrail 自己索引源的实际 `callers` 查询：
```text
$ graphtrail --db .graphtrail/graphtrail.db callers serve
main --calls@19 hops=1--> serve (src/bin/graphtrail-mcp.rs -> src/mcp.rs)
```
## MCP 服务器
`graphtrail-mcp` 是一个只读的 MCP 服务器，通过 stdio 提供换行分隔的 JSON-RPC 2.0。 它没有异步运行时和额外的依赖，因此侧车保持较小。 默认数据库来自 `--db <path>`、 `--db=<path>`、 `GRAPHTRAIL_DB` 环境变量或工作目录中的 `.graphtrail/graphtrail.db`。 每个工具还接受一个可选的 `repo`（使用 `<repo>/.graphtrail/graphtrail.db`）或 `db`（显式路径）参数，因此单个运行的服务器可以回答任何索引仓库的问题。 数据库在每次调用时延迟打开，因此服务器甚至在默认数据库存在之前启动。
使用 MCP 客户端注册它。 对于 Claude Code，请将其添加到 `.mcp.json`（项目范围）或 `~/.claude.json`（用户范围）：
```json
{
"mcpServers": {
"graphtrail": {
"command": "/abs/path/to/graphtrail-mcp",
"args": ["--db", "/abs/path/to/repo/.graphtrail/graphtrail.db"]
}
}
}
```
### 工具
服务器暴露八种工具，每种工具都是只读的。 此列表已针对 `graphtrail-mcp` 的 `tools/list` 响应进行验证：
| 工具 | 必需参数 | 返回内容 |
|---|---|---|
| `search` | `query`（可选 `limit`，默认为 20；可选 `path`） | 代码符号（函数、类、方法）的全文搜索，按名称查询，可选按索引文件路径过滤。 |
| `callers` | `symbol`（可选 `depth`，默认为 1，限制为 1..5） | 调用给定符号的符号（传入调用边），每个边有 `hops`。 |
| `callees` | `symbol`（可选 `depth`，默认为 1，限制为 1..5） | 给定符号调用的符号（传出调用边），每个边有 `hops`。 |
| `impact` | `symbol`（可选 `depth`，默认为 1，限制为 1..5） | 符号的综合调用者和被调用者（变更的辐射范围），每个边有 `hops`。 |
| `context` | `task`（可选 `limit`，默认为 12） | 上下文包：匹配的入口点及其调用者和被调用者邻居及相关文件。 |
| `stats` | 无 | 文件、符号、边、导入、架构版本、同步元数据和每个语言的文件计数的数量。 |
| `file_neighbors` | `path` | 通过传入或传出调用边与索引文件连接的文件。 |
| `repos` | 无（可选 `roots`） | 默认数据库元数据以及 `.graphtrail/graphtrail.db` 在根目录下的可选一级扫描。 |
每个工具还接受一个可选的 `repo` 或 `db` 选择器，用于多仓库使用。 调用边工具在每个方向上限制 500 个真实边。 当遍历被限制时，JSON 数组包含一行 `kind: "truncated"`。
对 `stats` 工具的实际调用（服务器首先索引 GraphTrail 自己的源）：
```json
{
"edges": 168,
"files": 26,
"imports": 119,
"language_files": {
"go": 1,
"python": 3,
"rust": 18,
"typescript": 4
},
"schema_version": 2,
"symbols": 150,
"synced_at": "1783099401",
"tool_version": "0.2.0"
}
```
## 可选集成
GraphTrail 的 Brigade 适配器已内置：`graphtrail context "<task>" --markdown` 将上下文包渲染为 Brigade 友好的 Markdown 文档，您可以将其放入交接的证据部分。
另外两个适配器位于可选的 Cargo 功能后面，因此默认二进制文件不包含网络和跨工具依赖：
```bash
# 从图上下文、代码搜索语义命中和 MiseLedger 证据中构建一个上下文简介。
cargo run --features codesearch,miseledger -- \
--db <db> context "rate limiting" --markdown --blend-code-search --evidence
# 将代码搜索嵌入命中与图中心性相结合。
# 尊重 CODE_SEARCH_URL 和 CODE_SEARCH_API_KEY。
cargo run --features codesearch -- --db <db> blend "rate limiting" --json
# 显示 MiseLedger 证据项（只读 FTS），提及符号或术语。
# 尊重 MISELEDGER_DB（默认为 ~/.local/share/miseledger/miseledger.db）。
cargo run --features miseledger -- links "dispatch" --json
```
## 组件如何组合
GraphTrail 是几个专注的工具中的一个站点：
- **代码搜索** 保存语义块、摘要和嵌入。
- **GraphTrail** 拥有符号、导入、调用边和图上下文。
- **MiseLedger** 拥有会话和证据存档以及 JSON 收据。
- **Brigade** 拥有操作员工作流、交接、上下文包和防护栏。
内部代码分为多个模块：`model`（共享类型）、`extractors`（每个语言的 tree-sitter 提供程序加遍历）、`store`（`db`、`schema`、`sync`）、`query`（`search`、`graph`、`context`、`stats`）和一个薄的 `cli`。
## 为什么不使用 grep 或嵌入索引？
- **grep / ripgrep** 查找文本，而不是结构。 它们会显示名称出现的每一行，但它们不知道一个函数调用另一个函数，因此它们无法回答“谁调用它”或“如果我更改它，会有什么影响”。 GraphTrail 遍历真实的 tree-sitter 调用边并直接回答这些问题。
- **嵌入/语义索引** （代码搜索保存的类型）适用于“查找与此想法相关的代码”，但它按相似性排名，而不是按可达性。 它不会告诉你编辑的辐射范围。 GraphTrail 是结构层；这两个层组合使用，正是可选的 `blend` 功能所做的。
- **语言服务器（LSP）** 在编辑器内提供精确的语言导航，但它是与一个项目和一个进程绑定的有状态守护进程，而不是代理可以通过 MCP 跨多个仓库一次访问的查询数据库。 GraphTrail 持久化一个小型图谱到磁盘，保持只读，不运行守护进程，并且是多仓库的。
- **完整的代码智能平台** （图数据库、ctags 服务器、托管索引器）功能更多，运行成本更高。 GraphTrail 有意作为一个侧车：每个仓库一个 SQLite 文件，无网络，无后台进程。
## GraphTrail 不是什么
GraphTrail 是一个侧车，不是平台。 它不：
- 运行守护进程，安装钩子或监视文件系统
- 在默认构建中进行网络调用
- 拥有内存、收据、发布或调度（这些保留在 Brigade 和 MiseLedger 中）
- 保存语义块、摘要或嵌入（代码搜索拥有这些）
- 在索引后修改您的代码或图谱（MCP 服务器通过构造是只读的）
它将源代码索引到图谱中并回答结构性问题。 就是这样。
## 贡献
欢迎提出问题和拉取请求。 有关本地开发设置、轻松落地的内容，请参见 [CONTRIBUTING.md](CONTRIBUTING.md)、[SECURITY.md](SECURITY.md) 和 [CODE_OF_CONDUCT.md](CODE_OF_CONDUCT.md)。 GraphTrail 采用 MIT 许可证；请参见 [LICENSE](LICENSE)。
