CodeGraph 定制化部署

在 AI 编程的时代，我们最常遇到的尴尬莫过于：AI 面对一个稍具规模的项目，为了弄清一个函数调用链路，疯狂地 grep、疯狂地 read 几十个文件，不仅速度慢得让人怀疑人生，账单上的 Token 消耗更是让人肉疼。

有没有一种方法，让 AI 像资深架构师一样，大脑里自带一份“代码地图”？

答案是：CodeGraph。

为什么选择 CodeGraph？

简单来说，CodeGraph 是一个为 AI 编程助手打造的本地代码语义知识图谱。它不是简单的全文搜索，而是通过 Tree-sitter 解析你的代码，构建成一张包含函数、类、路由和调用关系的图。

省钱： 减少 70% 的工具调用，节省约 35% 的 Token 费用。
快速： 不需要遍历文件，直接查询索引，秒级定位。
安全： 100% 本地运行，零数据外传，无需 API Key。

细节的技术实现

CodeGraph 使用业界著名的 Tree-sitter 解析器（各大现代编辑器也在用它做语法高亮）在本地将支持的 19+ 种语言的源码解析为 AST，提取类、函数、变量等节点及其调用、继承、导入等关系。
所有提取的代码元素和关系被存入项目根目录下的 SQLite 数据库（.codegraph/codegraph.db），利用 FTS5 实现毫秒级搜索，WAL 模式防止写读冲突。
数据库将这些节点及其关系构建成图谱，支持函数调用链追踪和依赖网络分析，可快速定位受影响的测试文件。
通过系统文件监听和 MCP（Model Context Protocol）服务器，CodeGraph 实时增量更新数据库并向 AI 提供 codegraph_explore 接口，实现即时、精准的代码查询。

总的来说, AI 助手通过 MCP 调用 CodeGraph 查资料，而 CodeGraph 则在后台安静地通过“文件保存事件”自我迭代。是一种无感式（Invisible）设计。

我的安装步骤

CodeGraph 的提供了简单的安装方案, 但是如果你用的不是它预设的环境, 比如 Antigravity, 那么还是需要一些手动技巧的, 本文将记录如何将其部署到 Antigravity，并通过 System Rules 实现“按需激活”的优雅工作流。

第一步：一键获取

打开你的powershell终端，执行这行命令，它会自动检测系统并下载预编译的二进制包：

irm https://raw.githubusercontent.com/colbymchenry/codegraph/main/install.ps1 | iex

该脚本会自动配置 PATH，安装后你随时可以在任何地方调用 codegraph 命令。这样做的好处是不依赖nodejs环境.

通过powershell命令查看它安装的位置:

(Get-Command codegraph).Source

第二步：挂载到 Antigravity

我们需要将 CodeGraph 作为 MCP 服务器接入 Antigravity, 调出它的mcp 的配置管理, 在设置json中加入以下内容¹, 然后刷新应用即可：

{
  "mcpServers": {
    "codegraph": {
      "command": "codegraph",
      "args": [
        "serve",
        "--mcp"
      ],
      "env": {}
    }
  }
}

验证是否成功:

重启 Antigravity，然后在终端或交互界面里尝试输入：codegraph status, 或者通过agent对话问他 “是否能访问codegraph?”

优化：通过 System Rules 实现“按需激活”

默认CodeGraph需要将一堆rules放入全局rules. 无论目录是否有被codegraph初始化过, 它都要执行. 这样有些浪费token.

本着 除非必要, 不去使用 的原则. 我使用了全局哨兵 + skill 的方式调用它.

设置全局触发逻辑 (System Rules)

我在 Antigravity 的全局规则中加入了一个“哨兵”逻辑，它会静默检查项目环境是否有 .codegraph 这个特征目录, 如果有, 才会触发后面的skill调用：

**极高优先级**: 如果项目根中存在 .codegraph 目录, 则在探索代码、分析结构、定位 Bug、追踪调用链或跨文件导航时，必须**绝对优先** 调用全局 `codegraph-protocol` skill执行。 严禁在有 .codegraph 目录时, 未尝试 CodeGraph 的情况下直接使用大范围的 `view_file` 或重复的 `grep_search` 盲目检索，力求实现“零文件读取”的架构级精准分析。

定义技能卡 Skill

Antigravity全局的Skill支持比较隐晦, 新版的 2.0 IDE的路径在: gemini\config\skills. 对官方的rules ² 改造后, 我的skill如下:

---
name: codegraph-protocol
description: 当用户需要探索代码库(explore codebase)、查找符号/函数定义(search symbols)、追踪调用链路(trace callers/callees/call paths)或导航代码上下文时触发，使用 CodeGraph 语义检索工具提供零文件读取的精准分析。
---

## CodeGraph

CodeGraph builds a semantic knowledge graph of codebases for faster, smarter code exploration.

## 执行规则

**Answer directly with CodeGraph — don't delegate exploration to a file-reading sub-agent or a grep/read loop.** CodeGraph *is* the pre-built search index; re-deriving its answers with grep + Read repeats work it already did and costs more for the same result. For "how does X work?", architecture, trace, or where-is-X questions, answer in a handful of CodeGraph calls and stop — typically with **zero file reads**. The returned source is complete and authoritative: treat it as already read and do not re-open those files. Reach for raw Read/Grep only to confirm a specific detail CodeGraph didn't cover.

**Tool selection by intent:**

| Tool | Use For |
|------|---------|
| `codegraph_context` | Map a task / feature / area first — composes search + node + callers + callees in one call |
| `codegraph_trace` | "How does X reach Y" — the call path, each hop's body inline (follows dynamic-dispatch hops grep can't) |
| `codegraph_explore` | Survey several related symbols' source in ONE budget-capped call |
| `codegraph_search` | Find a symbol by name |
| `codegraph_callers` / `codegraph_callees` | Walk call flow one hop at a time |
| `codegraph_impact` | Check what's affected before editing |
| `codegraph_node` | Get a single symbol's source / signature |

A direct CodeGraph answer is a handful of calls; a grep/read exploration is dozens.

日常操作

部署完成后，你的日常开发将变得异常流畅：
1. 进入项目：cd your-project
2. 构建地图：codegraph init -i（仅需执行一次）
3. 开始编码：当你开始与 Antigravity 对话，AI 会自动检测到 .codegraph/，悄悄激活导航模式。
4. 实时同步：你修改代码并保存，CodeGraph 会利用 OS 原生事件（FSEvents/inotify）在后台静默更新. 如果你不放心, 可以通过 codegraph status, 检查它是否自动索引了你的改动.

官方

想了解更多关于 CodeGraph 的细节？访问项目官方仓库：GitHub - colbymchenry/codegraph