CodeGraph 快速上手：三条命令完成安装、Agent 接入与项目索引

本文以 CodeGraph 的 Quickstart 文档为主线，完整还原"安装 CLI → 接入 Agent → 初始化项目"这条最短可用路径，并结合仓库中 install.sh、install.ps1、CLI 入口 与 安装器编排逻辑 的源码，解释每个步骤背后的实际行为、可复现的可选参数，以及 codegraph install 为何"只接 Agent、不索引代码"、codegraph init 为何"一步建图"。读完你可以独立完成从零到 Agent 自动调用 CodeGraph 工具的本地部署，并能自行排查 PATH 冲突、目标 Agent 未识别、非交互式安装等常见问题。

1. 安装 CLI：一行命令，无需 Node.js

Quickstart 的第一步是安装 CLI。CodeGraph 的官方分发方式是"自包含 bundle"——它把一份内嵌（vendored）的 Node 运行时和应用代码一起打包，因此目标机器不需要预先安装 Node.js、构建工具或 npm，适合在一台干净的 Linux VPS 上通过 SSH 直接部署。官方文档给出的两条一键命令如下：

# macOS / Linux
curl -fsSL https://raw.githubusercontent.com/colbymchenry/codegraph/main/install.sh | sh

# Windows (PowerShell)
irm https://raw.githubusercontent.com/colbymchenry/codegraph/main/install.ps1 | iex

1.1 安装脚本到底做了什么

逐行看 install.sh 可以确认，这条命令完成的事情比"下载一个二进制"要多。它的执行顺序是：

1. 平台探测：通过 uname -s / uname -m 把系统映射成 darwin/linux 与 arm64/x64，组合成目标三元组（如 linux-arm64）。不支持的平台或架构会直接报错退出。
2. 版本解析：默认取 latest。脚本优先读取 GitHub releases/latest 的 Web 重定向（而非调用 GitHub API）来解析版本，因为未认证的 API 有每小时 60 次的限流，在共享主机 / CI 上很容易触发 403；只有重定向不可用时才回退到 API。
3. 下载并解压 bundle：从 Releases 拉取 codegraph-<target>.tar.gz，解压到 versions/<v> 目录。
4. 建立软链：把启动器 codegraph 软链到 ~/.local/bin，并用 current 软链标记当前版本。
5. 清理旧版本：每次升级都会新装一个版本目录并重新指向 current，脚本会删掉其余旧 bundle，避免无限堆积（每个含运行时约 50 MB）。POSIX 下即使某 daemon 还在运行旧 bundle，inode 也会存活到进程退出，删除目录不会影响运行中的进程。
6. PATH 健康检查：遍历 $PATH，既检查 ~/.local/bin 是否真的在 PATH 上，也检查是否有另一个更早的 codegraph（最常见是残留的 npm i -g @colbymchenry/codegraph）会抢先执行——这正是文档提示"装完打开新终端"的原因。

安装脚本支持三个环境变量（见 install.sh 头部注释），可用于精确控制安装位置与版本：

环境变量	作用	默认值
CODEGRAPH_VERSION	指定安装的 release tag（默认 latest，接受 vX.Y.Z 或裸 X.Y.Z）	最新
CODEGRAPH_INSTALL_DIR	bundle 存放位置	~/.codegraph
CODEGRAPH_BIN_DIR	启动器软链位置（需加入 PATH）	~/.local/bin

卸载同样是官方支持的操作：curl -fsSL .../install.sh | sh -s -- --uninstall 会移除 ~/.local/bin/codegraph 与 ~/.codegraph。

1.2 Windows 路径

install.ps1 与 shell 版行为对齐：架构探测得到 win32-arm64 / win32-x64，从 Releases 下载 codegraph-<target>.zip，解压到 %LOCALAPPDATA%\codegraph\current（覆盖式升级），并把 current\bin 追加进用户级 PATH（需要重开终端生效）。它还额外检查机器级 + 用户级两条 PATH，若发现有更早的 codegraph.cmd/.exe/.bat/.ps1 会发出"被遮蔽"警告——对应 shell 版的同一类问题。

1.3 已有 Node 环境：npm 安装

文档同时说明：如果你本机已有 Node，npm i -g @colbymchenry/codegraph 在任意受支持版本上都能工作，且行为与 bundle 版一致（无需编译、无原生构建）。从 package.json 可确认关键事实：

• 包名为 @colbymchenry/codegraph，bin 字段把 codegraph 命令映射到 dist/bin/codegraph.js；
• engines 声明 "node": ">=20.0.0 <25.0.0"，即 Node 20 至 24 受支持。CLI 入口 src/bin/codegraph.ts 会在此约束之外做硬拦截：Node ≥ 25 因 V8 turboshaft 对 tree-sitter 大 WASM 语法的 Zone OOM 问题被直接拒绝，Node 低于下限同样拒绝，二者都可用 CODEGRAPH_ALLOW_UNSAFE_NODE 环境变量覆盖。

无论哪种安装方式，安装器都会把 codegraph 放进 PATH，但不会修改当前已打开的 shell——因此文档反复强调在下一步前"打开一个新终端"。这一点与脚本第 6 步的 PATH 检查逻辑一致：新装的路径只有在新 shell 里才会被真正加载。

2. 接入你的 Agent（codegraph install）

codegraph install

这一步把 CodeGraph 的 MCP 服务器写入你选定的各个 Agent 配置。文档明确：这一步只连接 Agent、不索引任何代码。理解这条边界，需要看安装器的设计意图——src/installer/index.ts 在结尾专门注明："install wires up agents only — it deliberately does NOT index"，即刻意不索引，以避免"意外把 $HOME 之类的目录建了索引"。真正建图是用户显式的 codegraph init（或 index）职责。

2.1 支持的 Agent 目标

文档列出了 Claude Code、Cursor、Codex CLI、opencode、Hermes Agent、Gemini CLI、Antigravity IDE、Kiro。源码中实际注册的目标更多——targets/registry.ts 的 ALL_TARGETS 还包含三个 GitHub Copilot 变体：copilot-vscode、copilot-cli、copilot-jetbrains。也就是说，codegraph install 能配置的 Agent 集合是这 11 个目标，顺序即多选提示里的显示顺序。

安装器的工作流（runInstallerWithOptions，见 src/installer/index.ts）大致是：

1. 先问目标：通过 detectAll 探测本机已装的 Agent，把已识别的预勾选进多选框；若什么都没探测到，默认回退到 Claude（保持历史最小惊讶行为）。
2. （可选）装 CLI 到 PATH：交互式下会询问，非交互 --yes 时跳过（假定已存在）。
3. 问位置：global（写 ~/.claude、~/.cursor 等，全项目生效）或 local（写 ./.claude、./.cursor 等，仅当前项目）。若所有所选目标都只支持 global（如 Copilot CLI），会跳过提示强制 global。
4. （可选）自动允许权限：仅对 Claude Code 有意义，跳过其权限提示。
5. 逐个目标写入：调用每个目标的 install(location, {...})，逐文件打印 Created/Updated/Removed/Unchanged。
6. 收尾提示：打印"下一步：codegraph init 建图"的提示，并要求重启对应 Agent 生效。

2.2 codegraph install 的可选参数

CLI 入口 src/bin/codegraph.ts 为 install 定义了完整的参数集，适合脚本化与 CI：

参数	说明
-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	跳过写入自动允许权限列表（仅 Claude Code）。
--print-config <id>	打印指定 Agent 的 MCP 配置片段后退出，不写任何文件。
--refresh	仅对已配置的 Agent 重写其表面（说明块、MCP 条目、旧 hook 清理），从不新增目标。codegraph upgrade 会自动执行。

--target 的取值解析见 resolveTargetFlag：auto 返回所有 detect().installed === true 的目标，探测不到则回退 ['claude']；all 返回注册表全部；none 返回空列表（调用方跳过 Agent 写入）；CSV 列表遇到未知 id 会抛出并打印全部已知 id。

文档还给了一个便捷写法：npx @colbymchenry/codegraph 会在一条命令里"下载并运行安装器"，省去手动装 CLI 这一步（仓库中 scripts/npm-shim.js 与 scripts/npm-sdk.js 即其配套 shim/SDK 入口）。

2.3 反向操作与升级

• codegraph uninstall 是 install 的逆操作：移除 MCP 服务器条目、说明块与权限，但不删 .codegraph/ 索引（那是 codegraph uninit 的职责），见 src/bin/codegraph.ts。
• 升级走 codegraph upgrade（或重跑同一条安装命令），它会重新运行安装脚本、换新版本目录并重指 current 软链，随后通过 --refresh 让已配置 Agent 的表面与"当前二进制"的模板保持一致。

3. 初始化每个项目（codegraph init）

cd your-project
codegraph init

codegraph init 会创建本地 .codegraph/ 目录，并在同一步里构建完整图——一条命令即完成。文档强调："只要存在 .codegraph/ 目录，你的 Agent 就会自动使用 CodeGraph 工具。" 这正是"存在性即启用"的约定：Agent 端依据该目录判断是否启用 CodeGraph 工具，而不是靠全局开关。

3.1 codegraph init 的可选参数

CLI 入口 src/bin/codegraph.ts 为 init 提供了如下参数：

参数	说明
-i, --index	已弃用：索引现在默认执行，仅为向后兼容保留。
-f, --force	即便路径看起来像主目录或文件系统根，也允许初始化。
-v, --verbose	显示详细的 worker 生命周期与内存信息。
-y, --yes	非交互：跳过所有提示取默认值，适合脚本 / CI / 容器引导。

安全护栏值得注意：init / index 都内置 unsafeIndexRootReason 检查，当目标路径形如主目录或文件系统根时会拒绝执行（--force 作为显式覆盖），从源头避免"误把 $HOME 建了索引"。此外，当实时文件监听在本机被禁用（例如 WSL2 的 /mnt 盘、或设置了 CODEGRAPH_NO_WATCH）时，init 之后会提示"索引会冻结"，并询问是否改用 git 同步钩子（commit / pull / checkout 后自动刷新），对应 src/installer/index.ts 的 offerWatchFallback。

3.2 建图之后的生命周期

理解 init 的后续行为，有助于把"一次建图"变成"持续同步"：

• codegraph index [path]：全量重建索引（等价于一次全新 init）。实现上它调用 CodeGraph.recreate 从底重建数据库，而非打开旧图逐行删除——后者在大或已损坏的索引上会把主线程卡到触发存活看门狗（见 src/bin/codegraph.ts）。
• codegraph sync [path]：对上次索引之后的增量变更做快速更新，是日常保持新鲜度的首选。
• codegraph uninit [path]：移除项目里的 CodeGraph（删除 .codegraph/），并清理曾安装的 git 同步钩子；删除前会请求确认，-f 跳过。

至此，"三条命令"的闭环成立：curl/irm 装 CLI → codegraph install 接 Agent → cd 项目 && codegraph init 建图。Agent 端重启后即可在会话中自动调用 CodeGraph 工具，无需每次手动触发。

延伸阅读

• 更完整的安装选项与环境细节：Installation。
• 建好图后如何验证与使用：Your First Graph。
• CLI 全量命令参考：reference/cli。
• 想理解图是怎么构建与解析的，可看 core-concepts/how-it-works。