Graphpilot

GraphPilot

为编码 Agent 提供结构化记忆。
一张可安全应对重构、感知分支且有证据支撑的代码图谱，完全在你的机器上运行。

快速开始 · 工具 · 工作原理 · 编辑器设置 · 限制 · 基准测试

---

它是什么

GraphPilot 是一款本地命令行工具 + MCP 服务，可将你的 TypeScript/JavaScript 仓库编入结构图谱（符号、调用者、被调用者、影响范围），并将其提供给编码 Agent — Claude Code、Cursor、Cline、Windsurf、Continue — 让它们不再每次对话都反复对同一批文件执行 grep。

它解决的问题是：Agent 会消耗大量 token、臆造函数名，并遗漏结构关系（“什么调用了它？”、“重命名它会造成什么影响？”），因为每次会话都从零开始。GraphPilot 就是介于会话之间的持久化结构记忆。

Token 消耗减少。幻觉减少。重构更安全。

让一个真实的编码 Agent（claude-sonnet-4-5）回答关于 fastify 的 40 个结构问题 — 一个约有 300 个文件的 Node.js 框架 — 只提供文件读取能力。然后给它 GraphPilot 的四个工具，再问同样的 40 个问题。使用 GraphPilot 的 Agent 少用 61 % 的 token，费用为 $3.68，而不是 $8.88 — 每次会话节省 $5.20 — 而且答对的题目更多，不是更少（37 题正确，而非 33 题）。模型相同、问题相同、仓库相同；唯一的变化是是否提供结构索引。复现测试 →

另一项正确性基准测试通过精确率验证了这些节省：在 10 个标准化结构查询中，GraphPilot 的得分为 F1 0.89，grep 为 0.42，同时读取的字节数减少 99.9 %（721 B 对比 528 KB）；而且字节开销方面的优势在规模扩大时依然成立 — 对 microsoft/TypeScript 建立索引（601 个文件、17 k 个符号、70 k 条调用边，用时 10 s），查询耗时不到毫秒级，读取字节数减少 99.99 %。完整方法 →

一个二进制文件，两种模式

GraphPilot 以单个 npm 包（@graphpilot-oss/graphpilot）的形式提供，支持两种运行模式——大多数用户会同时使用两种模式。

模式	命令	功能
CLI	graphpilot index <path>	遍历你的代码库，构建结构图，并将其写入 ~/.graphpilot/
	graphpilot watch <path>	保持结构图为最新（每次保存文件约需 10 ms）
	graphpilot status <path>	健康检查——查看结构图上次刷新的时间，以及文件、符号和边的数量
MCP 服务	graphpilot mcp	通过 stdio 使用 MCP——你的编码 Agent 会调用它来查询结构图

工作流程： CLI 构建一次索引（并由 watch 保持其更新）。你的编码 Agent 通过 MCP 服务进行交互——你无需亲自调用它，只需将 Agent 的 MCP 配置一次指向 graphpilot mcp，之后 Agent 会在每个会话中启动它。

如果你只想通过 CLI 访问代码结构图（不使用 Agent），运行 graphpilot index，然后运行 graphpilot stats / 直接查看 graph.json。如果你只想使用 Agent 集成，仍需先运行一次 graphpilot index——MCP 服务只能读取磁盘上的结构图。

它的不同之处

其他代码结构图工具将你的代码库视为静态数据块：只索引一次，然后永远查询；不感知分支，也无法证明答案的来源。GraphPilot 围绕三个其他工具都不具备的特性构建：

• 🔍 证据锚点。 每个工具响应都会为每个符号和调用点提供 file:line @ sha。Agent 可以原样引用锚点，你也能立即验证——跳转到对应行时，幻觉就会暴露。
• 🌿 差异影响分析。 向 gp_impact 传入 since: <commit|branch>，结果就会筛选出你的分支实际改动过的文件。一次调用即可进行 PR 范围内的重构分析，无需执行 git diff | xargs grep。
• 🪵 默认感知工作树。 通过 git worktree add 创建的两个分支会自然生成两个独立索引，无需手动配置。从子目录运行 graphpilot index ./src/feature，它会自动将根目录调整为工作树顶层。使用 --no-worktree 可退出此功能。

此外，它还具备：本地优先（无遥测、无远程调用，并由针对 src/ 本身的 ESLint 策略强制保障）、确定性（相同代码库 → 相同结构图），以及通过监视模式实现的亚秒级增量更新。

快速入门

前置条件

• Node.js ≥ 20（运行 node --version 检查）
• 支持 MCP 的编码 Agent（Claude Code、Cursor、Cline、Windsurf 或 Continue）
• 一个用于建立索引的 TypeScript 或 JavaScript 代码仓库

端到端耗时：约 3 分钟。

1. 安装 CLI

npm install -g @graphpilot-oss/graphpilot
# or: pnpm add -g @graphpilot-oss/graphpilot
# or one-shot, no install: npx @graphpilot-oss/graphpilot <command>

确认它已加入你的 PATH：

graphpilot --version
# → 0.1.0

如果看到 command not found: graphpilot，说明全局 npm bin 目录不在 PATH 中。运行 npm config get prefix，并将 <prefix>/bin 添加到 shell 的 PATH 中，或者使用上面的 npx 形式。

2. 为代码仓库建立结构索引

每个项目运行一次。它会遍历源代码树，使用 tree-sitter 解析每个 TS/JS 文件，提取符号和调用边，并将图写入 ~/.graphpilot/<repo-id>/graph.json。

graphpilot index ~/code/my-app

你会看到类似 indexed 412 files · 3,981 symbols · 7,204 edges · 1.8s 的单行摘要。

3. 将其接入编码 Agent

GraphPilot 通过 stdio 使用 MCP。将此服务条目添加到 Agent 的 MCP 配置中——每个受支持的客户端都使用相同的两行格式：

{
  "mcpServers": {
    "graphpilot": {
      "command": "graphpilot",
      "args": ["mcp"]
    }
  }
}

此文件的位置取决于客户端（~/.cursor/mcp.json、~/.claude.json、Cline 的设置面板等）。examples/ 中提供了预先配置好的文件，其中包含每个 Agent 对应的确切文件路径——复制适用于你的客户端的配置即可。

重启 Agent。它现在拥有四个新工具：gp_recall、gp_callers、gp_impact、gp_index——有关每个工具的功能及 Agent 应在何时使用它，请参阅下文的四个工具。

4. 试用

向 Agent 提出结构性问题，而不是让它使用 grep：

“使用 gp_impact，告诉我重命名 parseToken 会导致哪些内容出问题。”

你应该会看到包含 file:line @ sha 锚点的回复，可直接点击跳转。如果 Agent 没有调用该工具，请明确提示：“使用 gp_ MCP 工具。”如果它完全看不到这些工具，说明 MCP 配置未生效——运行 graphpilot doctor 查明原因（或参阅 docs/troubleshooting.md），然后重启 Agent。

5. 编辑时保持索引最新（可选，但建议）

graphpilot watch ~/code/my-app

每次保存文件都会进行低于 10 ms 的增量更新。让它在终端标签页中持续运行。

6. 将各编辑器的路由规则加入代码仓库（可选）

graphpilot init

自动检测已安装的编辑器（Cursor、Claude Code、Cline、Windsurf、Continue），并在当前目录中写入对应的规则文件（.cursorrules、CLAUDE.md 等）。这些规则会教 Agent 在使用 grep 前先调用 gp_* 工具。

graphpilot init --all            # write rules for every supported editor
graphpilot init --client cursor  # one editor only
graphpilot init --dry-run        # preview without writing

包含截图的完整 5 分钟演示：docs/quickstart.md。

四个工具

GraphPilot 提供四个 MCP 工具。每个工具都能回答一个结构性问题，否则 Agent 只能通过 grep 并阅读文件来解决。

gp_recall — 按名称查找符号

当 Agent 想知道“X 定义在哪里？”或需要在分析前定位某个函数时，使用此工具。

• 输入： { query, limit?, substring?, path? }
• 返回： 名称匹配的符号（默认不区分大小写进行精确匹配；设置 substring: true 可进行部分匹配），每个符号都带有 file:line @ sha。
• 替代操作： grep -rn "function X"，然后逐一阅读命中内容以找到实际定义。

Agent: gp_recall({ query: "parseToken" })
→ parseToken (function) — src/auth.ts:42 @ a1b2c3d
  export function parseToken(raw: string): Token | null

gp_callers — 列出调用方（或被调用方）

当 Agent 需要知道“谁调用了 X？”或“X 调用了什么？”时使用——这是重构时最基础的两个问题。

• 输入： { symbol, direction?: 'callers' | 'callees', limit?, includeUnresolved?, path? }
• 返回： 以该符号为目标（调用方）或来源（被调用方）的每条调用边，并附带锚点。
• 替代操作： grep -rn "X("，再手动筛除注释、字符串和重命名后留下的同名项。

Agent: gp_callers({ symbol: "authenticate", direction: "callers" })
→ login → authenticate — src/routes/login.ts:18 @ a1b2c3d
→ refreshSession → authenticate — src/session.ts:64 @ a1b2c3d

gp_impact — 一次调用即可查看影响范围

当 Agent 询问“如果我重命名 X，会有什么东西出问题？”或“有哪些内容依赖它？”时使用——这是 Agent 通常需要解决的成本最高的问题。

• 输入： { symbol, depth? (1–5, default 3), since?, path? }
• 返回： 直接调用方、按 BFS 深度分组的传递调用方、可能受影响的测试、公共 API 标记和摘要统计信息。
• 杀手级功能： 传入 since: 'main'，结果便会限定在分支实际触及的文件中——无需费劲使用 git diff，即可按 PR 范围审查重构。

Agent: gp_impact({ symbol: "extractSymbols", depth: 2, since: "main" })
→ Direct callers (2):    indexDirectory, applyUpdate
→ Depth-2 callers (1):   cmdIndex
→ Tests affected (3):    tests/indexer.test.ts, tests/symbols.test.ts, tests/cli.test.ts
→ Public API:            no

gp_index — 在 Agent 内部刷新索引

当 Agent（或用户）进行了一批结构性编辑，并希望图谱反映这些更改，而不必切换到 shell 时使用。

• 输入： { path? }
• 返回： 重新索引仓库，并使每路径查询缓存失效。
• 配合使用： graphpilot watch，在显式重新索引之间实现亚 10 ms 的增量更新。

工作原理

数据流是单向的：源代码 → 树 → 符号 + 边 → JSON → 查询 → Agent。GraphPilot 绝不会修改你的代码。

包含文件引用的完整流水线说明：docs/architecture.md。

何时使用哪种工具

如果 Agent 即将……	使用……	原因
使用 grep 按名称搜索函数	gp_recall	一次调用，不会被注释或字符串误导
阅读 20 个文件来查找“谁调用了 X”	gp_callers	预先计算的反向索引，亚毫秒级
规划重命名或签名变更	gp_impact	一次调用即可获取直接调用方、传递调用方、测试和公共 API
审查 PR 的结构性影响范围	gp_impact({ since: 'main' })	差异化结果——仅包含分支触及的调用方
编辑多个文件后再次使用 grep 搜索	gp_index	增量更新：让下一次调用看到你的编辑

对于字符串字面量、错误消息、配置值或任何非 TS/JS 语言的内容：继续使用 grep。 GraphPilot 索引的是代码结构，而非文本。

编辑器设置

GraphPilot 通过 stdio 使用 MCP，因此适用于任何支持 MCP 的客户端。可直接粘贴的配置位于 examples/：

客户端	文件夹
Claude Code（Anthropic）	examples/claude-code/
Cursor	examples/cursor/
Cline（VS Code 扩展）	examples/cline/
Windsurf（Codeium）	examples/windsurf/
Continue.dev	examples/continue/
其他任何 MCP 客户端	参见 docs/mcp-setup.md

每个文件夹都包含：一份 README.md 操作指南、一个包含可直接粘贴的确切 JSON 的示例配置文件，以及（在客户端支持的情况下）一个路由模板，让 Agent 自动在结构性问题上使用 GraphPilot。

隐私与安全

GraphPilot 从承诺到构建门禁都坚持本地优先。

• **绝不遥测，绝不远程调用。**可验证：src/ 中没有任何 http、fetch、axios 或分析相关导入——通过 ESLint 规则和元测试强制执行，元测试会验证该规则能拦截每一种被禁止的导入。
• **不使用 child_process、exec 或 spawn。**通过纯 JavaScript 辅助函数直接读取 .git/ 中的 Git 信息。
• **源代码绝不会离开你的机器。**只有结构性元数据（名称、位置、签名、调用关系）会存储在 ~/.graphpilot/ 中。
• 签名会经过脱敏处理，在写入磁盘前过滤常见机密模式（OpenAI/Anthropic 的 sk-、GitHub 的 ghp_/ghs_、AWS 的 AKIA、JWT、PEM 标头、Slack/Stripe 令牌）。
• **严格的文件权限：**目录为 0o700，文件为 0o600。
• **加载时进行架构验证：**遭篡改或损坏的 graph.json 会回退到“无索引”状态，而不会污染 Agent。
• 每个 MCP 工具都使用手写的输入验证器——拒绝未知字段，检查每个字段的类型，校验数字范围，并限制字符串长度。

威胁模型和各项防护对应的测试参考见 docs/architecture.md。请按照 SECURITY.md 报告安全问题。

局限性

GraphPilot v0.1 有意做出取舍，以保持精简而高效：

• **仅支持 TS/JS。**Python、Rust、Go、Java 不在 v1 的支持范围内。Python 是否加入 v0.2 / v0.3 取决于需求。
• 基于名称的解析器（不跟踪导入路径，也不按类型分派方法）。预计解析率：约 25–35% 的边会解析到仓库内的符号，其余则是标准库或第三方内容。这已经足够，因为 Agent 实际会问的问题（“我的仓库里谁调用了 X？”）正是这个简单解析器能正确回答的问题。
• 不支持语义搜索。gp_recall 仅按名称搜索。“查找与此代码片段相似的代码”会暂缓实现，直到有 30 多位用户提出需求。
• 暂不支持 .graphpilotignore（默认跳过 node_modules、dist、build、.git、coverage、.next、.nuxt、.cache、out、*.d.ts）。
• **每次查询仅支持一个仓库。**工作区抽象已列入 v1.x 路线图。

包含缓解措施的完整列表：docs/limitations.md。

常见问题

它会把我的代码发送到其他地方吗？ 不会。src/ 中没有网络代码，也没有遥测或更新检查。ESLint 规则会在构建门禁中阻止添加任何此类代码。

它会拖慢我的编辑器吗？ MCP 服务会保持空闲状态，直到 Agent 调用工具。首次延迟加载后，工具调用耗时不到 1 毫秒。监视模式会让每次文件保存额外耗时约 3–10 毫秒。

切换分支时，图会发生什么变化？ 如果使用 git worktree，系统会自动为每个工作树生成独立的图。在单一工作副本中使用 git checkout 切换分支时，图会反映上次运行 gp_index 后的状态（或监视模式的更新）。切换分支后运行 gp_index 即可刷新。

每次会话都需要重新索引吗？ 不需要。图会持久化在 ~/.graphpilot/<repo-id>/graph.json 中。大规模改动后请重新索引；其他情况下，监视模式会增量更新以保持内容最新。

为什么先支持 TypeScript/JavaScript？ 这是维护者最常遇到的问题所在，而且 tree-sitter-typescript 能通过单一语法同时覆盖 TS、TSX、JSX 和 JS。Python 是最有可能加入的下一种语言；欢迎在 GitHub Discussion 中投票。

它与 LSP 相比如何？ LSP 的作用范围局限于单个编辑器和单个缓冲区，并且会在每次查询时重新计算。GraphPilot 与编辑器无关，可跨会话持久保存，并能回答 LSP 未统一提供的结构性问题（谁调用了某项内容、影响范围）。

Agent 看不到这些工具／有些功能无法正常运行。 运行 graphpilot doctor——它会一次性检查 Node、PATH、索引、MCP 握手以及各客户端的配置。针对不同症状的修复方法见 docs/troubleshooting.md。

文档

• docs/quickstart.md — 5 分钟快速指南
• docs/mcp-setup.md — 各客户端的配置参考
• docs/troubleshooting.md — 按症状索引的解决方案（从 graphpilot doctor 开始）
• docs/architecture.md — 包含文件引用的流水线说明
• docs/limitations.md — v1 的注意事项（请阅读）
• bench/README.md — 基准测试方法与结果
• examples/ — 为每个受支持的客户端准备的即贴即用配置

贡献

GraphPilot 体量小、立场鲜明，并欢迎贡献。请从 CONTRIBUTING.md 开始阅读——在提出功能建议前，尤其要先阅读 "What we are NOT doing in v1" 部分。

发现安全问题？请按照 SECURITY.md 中的说明操作，而不要公开提交问题。

许可证

Apache-2.0。版权所有 2026 Akshay Sharma — [email protected]