CodeGraph CLI 完全解析：从 init 到 explore 的全部命令、参数与实现细节

CodeGraph 为 Claude Code、Cursor、Codex、Gemini、Copilot 等 AI 编码代理提供预构建的代码知识图谱，而其面向人类和脚本的入口就是 codegraph 命令行工具。本文基于仓库官方参考文档 CLI，结合 CLI 入口实现 与配套测试，逐一拆解每条命令的用途、可用 flag 与默认值，以及 init/index/sync 三种索引策略、explore/node 与 MCP 工具的同源关系、affected 的依赖追踪原理，帮助读者把 CodeGraph 完整嵌入日常开发流与 CI 流程。

全部命令一览

官方文档给出的命令总表如下（括号内为该命令接受的 flag）：

codegraph                         # 运行交互式安装器
codegraph install                 # 运行安装器（显式）
codegraph uninstall               # 从各 Agent 移除 CodeGraph（install 的逆操作）
codegraph init [path]             # 初始化项目 + 构建图谱（一步完成）
codegraph uninit [path]           # 移除项目中的 CodeGraph（--force 跳过确认）
codegraph index [path]            # 从头全量重建索引（--force, --quiet, --verbose）
codegraph sync [path]             # 增量更新（--quiet）
codegraph status [path]           # 查看索引统计（--json）
codegraph unlock [path]           # 删除阻塞索引的残留锁文件
codegraph query <search>          # 搜索符号（--kind, --limit, --json）
codegraph explore <query>         # 一次返回相关符号源码 + 调用路径（与 codegraph_explore MCP 工具同输出）
codegraph node <symbol|file>      # 单个符号的源码 + 调用者，或按行号读取文件（与 codegraph_node 同输出）
codegraph files [path]            # 展示文件结构（--format, --filter, --pattern, --max-depth, --json）
codegraph callers <symbol>        # 查找调用某函数/方法的位置（--limit, --json）
codegraph callees <symbol>        # 查找某函数/方法调用了哪些内容（--limit, --json）
codegraph impact <symbol>         # 分析修改某符号影响到的代码（--depth, --json）
codegraph affected [files...]     # 查找受变更影响的测试文件（详见下文）
codegraph daemon                  # 管理后台守护进程——选择一个停止（别名 daemons）
codegraph telemetry [on|off]      # 查看或更改匿名使用统计
codegraph upgrade [version]       # 更新到最新 release（--check, --force）
codegraph version                 # 打印已安装版本（也支持 -v, --version）
codegraph help [command]          # 显示帮助，可针对单个命令

MCP 服务器（codegraph serve --mcp）由你的 Agent 自动拉起，无需手工运行；其工具清单与 CODEGRAPH_MCP_TOOLS 环境变量见 MCP Server 参考。

从源码看，这套命令注册在 src/bin/codegraph.ts 中，基于 commander 构建。除文档列出的命令外，还有三条隐藏命令不会出现在 --help 里：

• serve（隐藏）：stdio 形式的 MCP 服务器入口。安装器会把 args: ['serve','--mcp'] 写进每个 Agent 的 MCP 配置，由 Agent 自行拉起。若人在 TTY 终端手敲 serve --mcp，程序会打印提示并直接返回，避免"看起来挂死"的误解（见 src/bin/codegraph.ts#L1828-L1901）；
• context（隐藏）：buildContext 公共 API 的 CLI 形态，接受 --format markdown|json、--max-nodes、--no-code 等参数，供脚本化集成使用（src/bin/codegraph.ts#L1262-L1310）；
• prompt-hook（隐藏）：Claude Code UserPromptSubmit 钩子入口，对结构性提问自动注入 codegraph_explore 结果，且任何失败路径都静默退出 0，绝不破坏用户的 prompt 流水线（src/bin/codegraph.ts#L1326-L1474）。

两个全局 flag --color / --no-color 在任意位置生效；管道输出、NO_COLOR 环境变量会自动禁用 ANSI 颜色（src/bin/codegraph.ts#L160-L164）。

路径解析规则：所有 [path] 参数都向上查找

多数命令接受可选的 [path] 参数。resolveProjectPath 的解析逻辑是：

1. 将参数（或当前目录）解析为绝对路径；
2. 若该目录已初始化（存在 .codegraph/codegraph.db，而非仅有 .codegraph/），直接使用；
3. 否则沿父目录逐级向上，直到文件系统根，寻找最近的已初始化项目；
4. 找不到则返回原路径，后续命令会报出带提示的错误（如 Run "codegraph init" first）。

这意味着在 monorepo 子目录、或已初始化项目的任意深层目录里执行 codegraph query ... 都能自动命中正确的索引，无需显式传 -p。

生命周期：install 与 uninstall

install 把 CodeGraph 的 MCP 服务器写入一个或多个 Agent 的配置（Claude Code、Cursor、Codex CLI、opencode、Hermes Agent、Gemini CLI、Antigravity IDE、Kiro、GitHub Copilot），支持以下 flag（src/bin/codegraph.ts#L2341-L2445）：

Flag	说明
-t, --target <ids>	目标 Agent，逗号分隔的 id，或 auto / all / none；默认交互式询问
-l, --location <where>	global 或 local；默认交互式询问
-y, --yes	非交互：默认 --location=global --target=auto 并自动放行
-i, --init	配置完 Agent 后顺带在当前目录执行 codegraph init，实现"配置 + 建索引"一条命令；可与 --yes 组合做无值守引导
--no-permissions	跳过写入 auto-allow 权限清单（仅 Claude Code）
--print-config <id>	只打印指定 Agent 的 MCP 配置片段后退出，不写任何文件
--refresh	重写既有安装已配置的内容（说明段、MCP 条目、旧钩子清理），绝不新增 Agent；codegraph upgrade 会自动调用

Agent 目标定义位于 src/installer/targets/ 目录，registry.ts 汇总了全部可用 id。

uninstall 是 install 的逆操作：移除各 Agent 中的 MCP 条目、说明段与权限配置，但不删除 .codegraph/ 索引——删索引是 uninit 的职责。它额外提供 --keep-cli，仅清理 Agent 配置而保留 codegraph CLI 本体（src/bin/codegraph.ts#L2455-L2485）。

init、index 与 sync：三种索引策略

官方文档对此有一段关键说明，原文核心观点是：

codegraph init 创建本地 .codegraph/ 目录并在同一步构建完整图谱。（旧的 -i/--index flag 现在是 no-op，仅为不破坏既有脚本而保留。）此后文件 watcher 会自动保持图谱最新——index（从头全量重建）和 sync（增量更新）只在 watcher 被禁用、或你在 Agent 会话之外用脚本操作索引时才需要。

init：一步完成

runInit 的流程是：

1. 拒绝不安全的根目录——若路径看起来像用户主目录或文件系统根（会索引进缓存、其他项目甚至整盘，产生 GB 级索引），直接报错退出；确有需要可传 --force 覆盖；
2. 若已初始化，提示改用 codegraph index 或 codegraph sync；
3. 创建 .codegraph/，随后在"命令监督"（命令被孤児化或主线程卡死时自我终止的看门狗）下执行首次全量索引；
4. 打印结果统计（文件数、节点/边数、耗时），错误文件会写入 .codegraph/errors.log；
5. 特殊场景：如果索引结果为 0 个节点且当前是 git 父仓库，.gitignore 恰好排除了承载代码的嵌套子仓库，CLI 会点名这些子仓库并交互式提议把它们的 includeIgnored 模式写入 codegraph.json 后重新索引，避免用户拿到"静默的 0 节点"结果（src/bin/codegraph.ts#L482-L544）。

init 的完整 flag（src/bin/codegraph.ts#L706-L715）：

Flag	说明
-i, --index	已废弃：索引现在默认执行，flag 仅为向后兼容保留
-f, --force	路径像主目录/文件系统根时仍继续
-v, --verbose	输出详细的 worker 生命周期与内存信息
-y, --yes	非交互：跳过所有提示取默认值（脚本 / CI / 容器引导用）

uninit [path] 删除 .codegraph/ 目录并顺带清理已安装的 git 同步钩子；-f, --force 跳过确认提示。

index：真正的"全量重建"

源码注释明确 index 走的是 RECREATE 路径——通过 CodeGraph.recreate(projectPath) 直接丢弃旧库与 WAL 从零重建，而不是打开旧图逐行删除（src/bin/codegraph.ts#L781-L873）。这是刻意的：先清空再索引的老做法曾报出"0 nodes"，且在大索引上逐行 FTS 删除会把主线程卡到触发看门狗。因此文档中"Full re-index from scratch"的描述是准确的——其结果与一次全新 init 完全一致。flag 为 --force、--quiet（抑制进度输出）、--verbose。

sync：增量更新

sync 打开现有索引并只处理自上次索引以来的变更，完成后报告 Added / Modified / Removed 三类文件计数与节点更新数；无变更时输出 Already up to date（src/bin/codegraph.ts#L878-L935）。唯一的 flag 是 -q, --quiet，注释写明其用途是 git hook 场景——这也是 CodeGraph 安装 git 钩子自动同步时使用的模式。

查询命令族

官方文档指出：query、callers、callees、impact 均支持 --json 输出机器可读结果：

codegraph query UserService --kind class --limit 10
codegraph callers handleRequest --json
codegraph impact AuthMiddleware --depth 3

query：符号搜索

实现要点（src/bin/codegraph.ts#L1140-L1210）：

• flag：-p, --path <path>、-l, --limit <number>（默认 10）、-k, --kind <kind>（按节点类型过滤，如 function、class）、-j, --json；
• 底层调用 cg.searchNodes（SQLite FTS/BM25），返回顺序即相关度排序；
• 生成文件降权：CLI 复用了 MCP 搜索的降权策略——通过 generatedFilePredicate 判定 protobuf/gRPC 等脚手架生成文件，命中时排到手工实现之后（src/bin/codegraph.ts#L1165-L1173）；
• 人读输出不打印分数：score 是无界的 BM25 数值，仅具相对排序意义，早期版本曾渲染成 12042% 之类的无意义百分比；现在人读视图只按排名展示，原始 score 保留在 --json 输出中。这一点有专门测试固化：tests/cli-query-command.test.ts 验证人读输出不含任何 (\d+%)，而 --json 仍带数值型 score。

explore 与 node：MCP 工具的 CLI 同体

文档明确写道：

explore 和 node 是 codegraph_explore 与 codegraph_node MCP 工具的 CLI 面——输出完全相同——使得 subagent 与非 MCP 框架也能从 shell 触达图谱。

源码印证了这一"同体"设计：explore 直接把多词参数拼成 query，然后 new ToolHandler(cg) 调用 handler.execute('codegraph_explore', args)，原样打印工具返回文本（src/bin/codegraph.ts#L1221-L1251）。存在这条 CLI 面是有明确理由的：Claude Code 的 Task 工具 subagent 不继承 MCP 工具，非 MCP 框架根本看不到 MCP——shell 命令是它们触达图谱的唯一通道。

• explore 的 flag：-p, --path、--max-files <number>（限制携带源码的文件数）。
• node 接受可选位置参数，支持两种模式（src/bin/codegraph.ts#L1486-L1551）：
  • 符号模式：codegraph node parseToken —— 该符号的源码 + 调用者/被调用者线索；
  • 文件模式：codegraph node -f src/auth.ts，或位置参数本身含 /、\ 时自动识别为文件读取（带行号 + 依赖方，与 Read 工具对齐）。flag 有 --file、--offset（1 基起始行）、--limit（最大行数）、--symbols-only（仅符号表 + 依赖方）。

两者共用一条"未初始化"提示：若目录没有索引，CLI 会明确告知 AI Agent"继续用你常规的工具，索引是用户的决定，不要自行执行"（src/bin/codegraph.ts#L1231）——这是对 Agent 行为边界的内建约束。

callers / callees / impact：图遍历

三者共享同一套查询模式：searchNodes 定位符号（最多 50 个候选）→ 仅保留精确名匹配（含 .、:: 后缀的成员名）→ 在多个精确匹配上合并去重遍历结果（src/bin/codegraph.ts#L1941-L2015）。

命令	flag	默认值	说明
callers <symbol>	-p, -l, --limit, -j, --json	limit=20	所有调用该符号的函数/方法
callees <symbol>	-p, -l, --limit, -j, --json	limit=20	该符号调用的所有函数/方法
impact <symbol>	-p, -d, --depth, -j, --json	depth=2	变更该符号的受影响半径

impact 有两个值得注意的实现细节（src/bin/codegraph.ts#L2098-L2190）：--depth 会被钳制到 1～10（源码 Math.min(Math.max(depth, 1), 10)），超出即被截断；人读输出按文件分组展示受影响符号，--json 则输出 { symbol, depth, nodeCount, edgeCount, affected: [...] } 结构。

files：索引内的文件结构

codegraph files 从索引（而非扫盘）读取项目文件结构，flag 全表（src/bin/codegraph.ts#L1556-L1676）：

Flag	默认	说明
-p, --path <path>	cwd	项目路径
--filter <dir>	—	只显示该目录下的文件（前缀匹配）
--pattern <glob>	—	glob 过滤（支持 **、*、?，见 globToRegex 实现）
--format <format>	tree	tree / flat / grouped（按语言分组）
--max-depth <number>	不限	tree 格式的最大目录深度
--no-metadata	—	隐藏语言、符号数等元数据
-j, --json	—	输出 [{path, language, nodeCount, size}]

status：索引健康检查

codegraph status 的人读视图包含：项目路径、git worktree 索引错配警告、索引状态机（indexing/partial/failed 分别给出"被中途杀死/静默丢文件/构建失败"的修复提示）、待解析引用数 pendingRefs（非 0 说明有被打断的 resolution 路径，提示运行 sync）、文件/节点/边计数、DB 与 WAL 体积、后端与 journal 模式、按 kind 与语言的分布、以及待同步变更。

--json 输出与之对应的结构化字段（src/bin/codegraph.ts#L986-L1025），其中 index 子对象携带 builtWithVersion、currentExtractionVersion 与 reindexRecommended——当索引由旧引擎构建、存在迁移无法回填的数据时，CLI 会明确建议重跑 codegraph index。

affected：变更驱动的测试选择

官方文档将其描述为：

沿 import 依赖传递地追踪，找出受变更源文件影响的测试文件。更多选项与 CI 示例见 Affected Tests in CI。

该指南文档给出的用法与选项表（完整继承）：

codegraph affected src/utils.ts src/api.ts          # 文件作为参数
git diff --name-only | codegraph affected --stdin   # 从 git diff 管道
codegraph affected src/auth.ts --filter "e2e/*"     # 自定义测试文件模式

选项	说明	默认值
--stdin	从 stdin 读取文件清单	false
-d, --depth <n>	最大依赖遍历深度	5
-f, --filter <glob>	识别测试文件的自定义 glob	自动检测
-j, --json	JSON 输出	false
-q, --quiet	只输出文件路径	false

实现上的几个要点（src/bin/codegraph.ts#L2202-L2336）：

• 路径归一化：输入统一转为"项目相对 + 正斜杠"形式，./src/x.ts、绝对路径（包装脚本常传）、Windows 反斜杠路径都能命中同一索引文件（issue #825 的修复）；
• 内置测试识别：无 --filter 时使用默认模式集 /\.spec\./、/\.test\./、/__tests__/、/tests?/、/e2e/、/spec/；--filter 提供 glob 时则完全取代默认集；
• BFS 遍历：从每个变更文件出发，沿 getFileDependents 的依赖边广度优先搜索，深度不超过 --depth；变更文件本身是测试文件时直接计入；
• 输出形态：--json 返回 { changedFiles, affectedTests, totalDependentsTraversed }；--quiet 仅逐行打印路径——这正是为管道设计的。CI 示例（来自指南文档）：

#!/usr/bin/env bash
AFFECTED=$(git diff --name-only HEAD | codegraph affected --stdin --quiet)
if [ -n "$AFFECTED" ]; then
  npx vitest run $AFFECTED
fi

对应行为测试见 tests/cli-affected-paths.test.ts。

daemon、unlock 与运维命令

daemon（别名 daemons）

交互式管理后台 MCP 守护进程：列出所有已验证存活的 daemon（pid、版本、运行时长、项目根），当前项目的 daemon 置顶并预选，回车即停止；输出非 TTY 时退化为纯列表打印（src/bin/codegraph.ts#L1782-L1823）。底层依赖 src/mcp/daemon-registry.ts 的 listVerifiedDaemons / stopDaemonAt / stopAllDaemons。

unlock

删除阻塞索引的陈旧锁：先清理 .codegraph/codegraph.lock，再调用 clearStaleDaemonArtifacts 清理遗留的 daemon 注册工件；两者皆无则提示"无事可做"（src/bin/codegraph.ts#L1906-L1932）。行为测试见 tests/cli-unlock.test.ts。

telemetry

codegraph telemetry [action]，action 取 status（默认）、on、off（src/bin/codegraph.ts#L2490-L2529）。status 打印当前状态及其决策来源（DO_NOT_TRACK 环境变量、CODEGRAPH_TELEMETRY 环境变量、本地配置或默认值）、机器 ID 与配置文件路径；若环境变量覆盖了你的选择，会明确警告当前实际生效状态。收集范围严格限定为匿名使用统计（子命令名，不含代码、路径、参数），详见仓库根目录 TELEMETRY.md 与 src/telemetry/index.ts。源码中还可见一个细节：init/uninit/index/sync/upgrade 这组长命令才触发遥测冲刷，快速命令只在本地缓冲，不产生额外网络开销（src/bin/codegraph.ts#L221-L233）。

upgrade

自更新命令自动检测安装方式（install.sh/.ps1 捆绑包、npm 全局、npx 或源码检出）并就地升级，逻辑位于 src/upgrade/index.ts 与 src/upgrade/update-check.ts。flag：

Flag	说明
--check	只检查是否有新版本，不安装
-f, --force	已是目标版本也重新安装
[version]	定位到指定版本；未传时还会读取 CODEGRAPH_VERSION 环境变量

version

codegraph version 打印 package.json 中的版本号（当前仓库为 1.6.0，见 package.json）。由于 commander 的 version 短 flag 是大写 -V，源码在解析前拦截了小写 -v 与 -version 两种拼法（src/bin/codegraph.ts#L145-L155），三者等价，行为由 tests/cli-version.test.ts 覆盖。

运行环境约束：Node 版本硬校验

CLI 入口在加载任何重模块之前就做 Node 版本硬校验（src/bin/codegraph.ts#L82-L107）：

• Node ≥ 25 被硬性阻断：V8 的 turboshaft WASM JIT 存在 Zone 分配器 bug，编译 tree-sitter 大语法时可靠地 OOM 崩溃。此前的软警告会滚出屏幕、30 秒后才是 OOM，所以现在是直接退出；
• Node < 最低版本同样阻断：package.json 的 engines 声明 node >=20.0.0 <25.0.0，而 npm 对 engines 只告警不拦截，因此 CLI 在入口处硬阻断，让 package.json 的声明真正生效；
• 两种情况都可用环境变量 CODEGRAPH_ALLOW_UNSAFE_NODE 覆盖（适用于自行修补过 V8 或测试未来修复的用户）。

另外两个启动阶段的行为值得了解：入口第一个 import 是 early-ppid——在启动器还活着时捕获 process.ppid，防止启动中途启动器被杀导致 PPID 看门狗永久失明；随后若未设置 --liftoff-only，进程会带该 flag 重新 exec 自身，避免 tree-sitter 大 WASM 语法在 Node ≥ 22 上触发 turboshaft Zone OOM（src/bin/codegraph.ts#L109-L114）。安装器目标与 init 组合的行为（--init 一键引导）由 tests/cli-install-init.test.ts 覆盖。

CLI 与 MCP 的分工模型

把上述命令放回整体架构，CodeGraph 的双面性就清晰了：

1. Agent 面（MCP）：安装器把 codegraph serve --mcp 写入各 Agent 配置，默认只暴露一个强工具 codegraph_explore（单次调用即返回相关符号源码、调用路径与影响半径），其余 7 个工具默认不列出、可用 CODEGRAPH_MCP_TOOLS 白名单恢复，详见 MCP Server 文档；
2. 人/脚本面（CLI）：explore、node 与 MCP 工具共享同一个 ToolHandler，输出逐字节一致；query/callers/callees/impact/files/status 则以 --json 支撑脚本与 CI；init/sync/index/unlock/daemon 是纯粹的运维命令。

这种"CLI 是 MCP 的投影"设计，使得不跑 MCP 的 harness（subagent、纯 shell 脚本、git hook、CI 流水线）也能获得与 Agent 完全一致的图查询能力——这正是官方文档将 explore/node 单列说明的原因。

小结

• CodeGraph CLI 覆盖完整生命周期：install/uninstall（Agent 接线）→ init（一步建图）→ sync/index（增量/全量）→ status/unlock/daemon（运维）→ query/explore/node/callers/callees/impact/files/affected（查询）→ upgrade（自更新）；
• 记住三个关键区分：init 一步完成初始化+首建索引（旧 -i flag 已无意义）；index 是丢弃重建而非清空重灌；sync 是 watcher 失效或脚本化场景下的增量手段；
• explore/node 与同名 MCP 工具同源同输出，是给非 MCP 环境的等价入口；
• 环境要求：Node 20～24（25+ 被硬阻断，可用 CODEGRAPH_ALLOW_UNSAFE_NODE 覆盖）；
• 进一步阅读：MCP Server 参考、Affected Tests in CI、CLI 参考原文、CLI 源码。