GraphPilot 是一个本地 CLI 加 MCP 服务器，为编程智能体提供结构记忆。它把你的 TypeScript/JavaScript 仓库一次性索引为结构化图（符号、调用方、被调用方、影响半径），并通过 MCP 暴露给编码智能体（Claude Code、Cursor、Cline、Windsurf、Continue），避免每次对话都重新 grep 相同文件。
它解决的问题：智能体消耗 token、幻觉函数名、遗漏结构关系（“谁调用了这个？”“重命名会破坏什么？”），因为每次会话都从零开始。GraphPilot 充当持久化的结构记忆。据官方描述，token 成本下降，幻觉减少，重构更安全。
基准数据（来自官方资料）：在 fastify（约 300 文件的 Node.js 框架）上，用真实编码智能体（claude-sonnet-4-5）回答 40 个结构性问题，仅给文件读取与给 GraphPilot 四个工具对比。使用 GraphPilot 的智能体 token 用量减少 61%，成本 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 文件、17k 符号、70k 调用边）耗时 10 秒，查询亚毫秒，读取字节减少 99.99%。
运行模式：单一 npm 包 @graphpilot-oss/graphpilot，两种运行时模式。CLI 构建索引（watch 保持热更新）。MCP 服务器供编码智能体调用——你把智能体的 MCP 配置指向 graphpilot mcp 一次，智能体每个会话自行启动它。若只需 CLI 访问，运行 graphpilot index 后通过 graphpilot stats / inspect graph.json 查看。若只需智能体集成，仍需先运行一次 graphpilot index，MCP 服务器对磁盘上的图只读。
差异化特性：证据锚点——每个工具响应中每个符号和调用点都带 file:line @ sha，智能体可逐字引用，你可立即验证。差异影响——向 gp_impact 传 since: <commit|branch>，结果过滤为分支实际触及的文件，PR 范围重构分析一次调用完成。worktree 感知——两个 git worktree add 的分支自然产生两个独立索引，无需手动配置；从子目录运行 graphpilot index ./src/feature 会自动重定位到 worktree 顶层，可用 --no-worktree 关闭。此外：本地优先（无遥测、无远程调用，由 ESLint 策略强制）、确定性（同仓库同图）、watch 模式下亚秒级增量更新。
环境要求：Node.js ≥ 20，一个支持 MCP 的编码智能体（Claude Code、Cursor、Cline、Windsurf 或 Continue），一个待索引的 TypeScript 或 JavaScript 仓库。端到端约 3 分钟。
快速开始：1. 安装 CLI（全局 npm 包）。2. 为仓库构建结构索引（每个项目运行一次，解析 TS/JS 文件，提取符号与调用边，写入 ~/.graphpilot/<repo-id>/graph.json）。3. 接入编码智能体：GraphPilot 通过 stdio 讲 MCP，在智能体的 MCP 配置中添加服务器条目，各客户端使用相同两行结构；预置配置在 examples/ 中。重启智能体后获得四个工具：gp_recall、gp_callers、gp_impact、gp_index。4. 向智能体提问结构性问题，例如“用 gp_impact 展示重命名 parseToken 会破坏什么”，应看到带 file:line @ sha 锚点的响应。若智能体未调用工具，可显式提示“使用 gp_ MCP 工具”；若看不到工具，运行 graphpilot doctor 诊断后重启智能体。5. 可选：运行 graphpilot watch 保持索引新鲜，每次文件保存亚 10 毫秒增量更新。6. 可选：运行命令向仓库写入各编辑器路由规则，自动检测已安装编辑器并写入匹配规则文件（如 .cursorrules、CLAUDE.md 等），教导智能体在 grep 前先用 gp_* 工具。
四个 MCP 工具：gp_recall——按名称查找符号，输入 { query, limit?, substring?, path? }，返回匹配符号及 file:line @ sha，替代 grep -rn "function X" 加重读。gp_callers——列出调用方或被调用方，输入 { symbol, direction?: 'callers' | 'callees', limit?, includeUnresolved?, path? }，返回每条调用边及锚点。gp_impact——一次调用获得影响范围，输入 { symbol, depth? (1–5, 默认 3), since?, path? }，返回直接调用方、按 BFS 深度分组的传递调用方、可能受影响的测试、公共 API 标记、统计摘要；传 since: 'main' 可限定到分支实际触及的文件。gp_index——在智能体内部刷新索引，输入 { path? }，重新索引并失效按路径查询缓存。
隐私与安全：本地优先。src/ 中无 http、fetch、axios 或分析导入，由 ESLint 规则加元测试强制；无 child_process、exec、spawn；源码不离开本机，仅结构元数据（名称、位置、签名、调用关系）存于 ~/.graphpilot/；签名在写盘前对常见密钥模式（OpenAI/Anthropic sk-、GitHub ghp_/ghs_、AWS AKIA、JWT、PEM 头、Slack/Stripe token）脱敏；严格文件权限（目录 0o700，文件 0o600）；加载时模式校验，损坏图回退为“无索引”；每个 MCP 工具手写输入验证器。
限制（v0.1）：仅支持 TS/JS，Python、Rust、Go、Java 不在 v1 范围，Python 视需求可能加入 v0.2/v0.3；基于名称的解析器（无导入路径追踪、无类型方法分派），预期约 25–35% 的边解析到仓库内符号，其余为标准库/第三方；无语义搜索，gp_recall 仅按名称；暂无 .graphpilotignore（默认跳过 node_modules、dist、build、.git、coverage、.next、.nuxt、.cache、out、*.d.ts）；单次查询单仓库，工作区抽象在 v1.x 路线图。
其他信息：仓库 License 为 Apache-2.0，版权 2026 Akshay Sharma。问题排查可运行 graphpilot doctor。文档包括 docs/quickstart.md、docs/mcp-setup.md、docs/troubleshooting.md、docs/architecture.md、docs/limitations.md、bench/README.md、examples/。安全报告请遵循 SECURITY.md。
