用 CodeGraph 给编码智能体预建代码知识图谱：安装接入、增量同步与影响面分析实操

# macOS / Linux 也可以走官方安装脚本
curl -fsSL https://raw.githubusercontent.com/colbymchenry/codegraph/main/install.sh | sh

# 通用方式：npm 全局安装
npm i -g @colbymchenry/codegraph

# 验证安装
codegraph version

两种装法选其一即可：习惯脚本安装的用官方 install.sh，Node 环境现成的直接 npm。装完跑 codegraph version 确认 CLI 进了 PATH；如果提示找不到命令，重开一个终端再试。装完先别急着进项目，下一步要把它接到你的智能体上。

# 新开一个终端运行（装完 CLI 后 PATH 需要刷新）
codegraph install

# 交互式安装器会探测本机的智能体并逐个询问，
# 自动为 Claude Code、Cursor、Codex CLI、
# opencode、Gemini CLI 等写入 MCP Server 配置

codegraph install 是个交互式安装器：它探测你机器上装了哪些编码智能体，逐个写入 MCP 配置。以 Claude Code 为例，写入的配置长这样：

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

也就是说 CodeGraph 以 stdio 子进程方式常驻，Agent 每次启动会话时自动拉起它。配置写完后重启你的智能体（MCP Server 配置在启动时加载），然后在新会话里确认 codegraph_explore 工具已经出现在可用工具列表中。

cd your-project

# 初始化并建图（init = 初始化 + 建索引一步完成）
codegraph init

# 查看索引统计
codegraph status

# 示例输出（中型项目）：
#   Indexed 92 files
#   1,166 nodes, 2,141 edges in 1.3s

官方 CLI 参考里 init [path] 的语义就是「初始化项目 + 建图」一步到位；建完后 status 会给出文件数、符号数、调用边数等统计。之后不需要再手动重建索引：初始化时启动的文件监听器会在你保存代码后自动增量同步，改哪个文件就重解析哪个文件。想强制全量重建有 codegraph index --force，想手动增量刷新有 codegraph sync。

# 在接入后的智能体里直接问：
#   "这个项目的订单创建入口在哪？谁调用了它？"
#   Agent 会调用 codegraph_explore 完成回答

# 不开智能体也能用 CLI 查同一张图：
codegraph callers handleCreateOrder   # 谁调用它
codegraph callees app.main            # 它调用谁
codegraph query --kind function --limit 20  # 按符号类型搜
codegraph search "checkout"           # 全文搜符号名
codegraph node services/orders.ts:42  # 看某符号原文与调用者

验收方式很直接：在智能体里抛一个只有「读懂结构」才能答对的问题，比如「改这个函数会影响哪些调用方」，观察它是否走 codegraph_explore 一次拿到答案，而不是连续 Grep 十几轮。CLI 的 explore / node 子命令与 MCP 工具同源，适合你自己先人工验证图谱质量——如果 CLI 查出来的调用关系明显不对，先检查语言是否在支持列表里，再考虑 index --force 重建。

# 改动影响面：谁会受这个符号变更影响
codegraph impact services.billing.price --depth 3 --json

# 找出受改动文件影响的测试文件：
codegraph affected src/utils.ts src/api.ts

# 更实用的姿势——直接从 git diff 管道进来：
git diff --name-only HEAD | codegraph affected --stdin

# 自定义测试文件的匹配规则
codegraph affected src/auth.ts --filter "e2e/*"

affected 会顺着导入依赖做传递性追踪，找出所有受变更源文件影响的测试文件，官方 README 还给了接 CI 或本地钩子的示例：把 git diff 的文件列表喂给 affected --stdin，非空就触发针对性测试。这样一来，智能体改完代码，你可以让它只跑受影响的测试子集，而不是每次全量跑一遍几十分钟的套件——这是图谱数据「变现」最直接的场景。

#!/usr/bin/env bash
AFFECTED=$(git diff --name-only HEAD | codegraph affected --stdin --quiet)
if [ -n "$AFFECTED" ]; then
  echo "需要重跑的测试覆盖文件："
  echo "$AFFECTED"
fi

把这段放进 pre-commit 或 CI 脚本，就得到了一个零成本的「改动感知测试闸门」。注意它是辅助判断而非绝对真理：动态调用、反射这类运行时才确定的路径图谱抓不全，关键路径仍要靠全量测试兜底。

# 浏览器里查看已索引项目的图谱
codegraph ui --port 4173 --read-only

# 查看与停止后台守护进程（文件监听由它承担）
codegraph daemon
codegraph daemons

# 升级与卸载
codegraph upgrade --check
codegraph uninstall --keep-cli   # 只清智能体配置，保留 CLI
codegraph uninit . --force       # 移除某项目的索引

ui 子命令会在本地起一个只读的图谱查看器，肉眼确认「调用边连得对不对」，比在对话里猜靠谱得多。后台的文件监听由守护进程承担，多个项目并行时用 daemon 子命令逐个管理；不想要某个项目的图谱了，uninit 移除索引（.codegraph/ 目录一并清理），退订整个工具则用 uninstall，加 --keep-cli 可以保留 CLI 只清各智能体里的 MCP 配置。整个过程数据不出本机：索引、查询、同步全部发生在你自己的磁盘上，公司项目也能放心用。