davidw-philips/cgraph

CodeGraph (codegraph)

codegraph 构建并维护一个本地、自动同步的知识图谱（SQLite），包含代码库中每个符号、调用边和依赖。一旦初始化，你的代理可以通过 codegraph_explore MCP 工具直接从图谱中回答结构性问题——一次调用，零文件读取——而不是使用 grep/read 循环。

何时使用

• 回答“X 如何工作？”、“X 如何到达 Y？”，或调查活动仓库中不熟悉的区域。
• 查找函数的调用者/被调用者，追踪调用路径，或评估变更的影响范围。
• 启动、管理或停止 CodeGraph 后台守护进程和环境进程。
• 跨 Git 分支、变基和 Git 工作树导航和维护图谱索引。
• 任何你原本需要通过 grep 或读取多个文件来手动重建结构的问题。

不要将其用于没有 .codegraph/ 索引的仓库（先运行 codegraph init）或尚未本地索引的外部/公共仓库——这些情况请优先使用 deepwiki 技能。

预检

command -v codegraph || Get-Command codegraph

如果缺失，请参阅 INSTALL.md，或直接通过以下方式安装：

# macOS / Linux — 无需 Node.js，自带运行时
curl -fsSL https://raw.githubusercontent.com/colbymchenry/codegraph/main/install.sh | sh

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

这对大多数环境来说已经足够——直接跳到下面的工作流程与启动。仅在你确实需要 npm 安装路径或 CodeGraph 的 Node 库 API 时，才使用附带的 scripts/（见 INSTALL.md）。

工作流程与启动

1. 每台机器的一次性设置

将 CodeGraph 接入此代理（在修改前会确认）：

codegraph install

2. 每个项目的首次设置

为活动项目构建图谱（创建 .codegraph/codegraph.db；运行完整初始索引）：

cd your-project
codegraph init

3. 日常启动（开始工作时）

你不需要在工作前手动启动守护进程或后台服务：

• 代理会话（MCP）：你的 AI 主机（VS Code Copilot、Claude Code 等）通过 codegraph serve --mcp 自动启动 MCP 服务器。服务器按需连接或启动后台守护进程，并包含 OS 文件系统监视器。
• 检查健康状态：运行 codegraph status 以验证索引健康状况、符号/边计数和待同步项。
• 追赶式同步：如果在代理关闭时文件发生了变化（例如拉取了提交），运行 codegraph sync 进行快速增量更新。

4. 查询结构

你的代理在接入后会自行调用 codegraph_explore MCP 工具。同样的功能也可以通过命令行使用：

codegraph explore "X 如何到达 Y"
codegraph callers someFunction
codegraph callees someFunction
codegraph impact someSymbol

环境与守护进程生命周期

CodeGraph 默认以后台守护进程（daemon mode）运行，以便多个客户端会话共享一个监视器、缓存和 SQLite 句柄。

关闭守护进程

• 交互式停止：运行 codegraph daemon（或 codegraph daemons）。选择项目守护进程（会置顶）或选择停止所有守护进程。
• 脚本化/非交互式停止：守护进程将其 PID 记录在 <project_root>/.codegraph/daemon.pid 中。直接终止该进程 ID（或检查 ~/.codegraph/daemons/<hash>.json）。
• 清除过期锁：如果进程崩溃或被意外终止，使用以下命令清除过期锁和孤立的守护进程产物：

  codegraph unlock
  

环境开关（守护进程与监视器）

• 直接模式（无守护进程）：设置 CODEGRAPH_NO_DAEMON=1 可强制每个 MCP 和 CLI 会话作为独立、自包含的进程运行，而不是连接到共享守护进程。
• 禁用文件监视器：设置 CODEGRAPH_NO_WATCH=1（或使用 --no-watch 标志）以禁用实时文件系统监视器。建议在慢速文件系统（WSL2 /mnt/ 驱动器、网络挂载）或电池受限情况下使用。

卸载/反初始化

• 从项目中移除：运行 codegraph uninit 删除 .codegraph/ 索引并移除 Git 同步钩子（--force 跳过提示）。
• 从机器中移除：运行 codegraph uninstall（或 codegraph uninstall --keep-cli 保留 CLI 二进制文件）。

使用 Git 分支与工作树

Git 分支切换（单一工作树）

• 基于文件系统的同步：CodeGraph 跟踪文件路径和内容哈希值（存储于 SQLite），而非 git status。切换分支（git switch <branch> 或 git checkout <branch>）会修改磁盘上的文件；文件监视器会自动检测更改并在约 2 秒内增量同步索引。
• 手动同步：如果在签出期间监视器被禁用或未激活，运行 codegraph sync 进行快速增量追赶。
• 重大变基/重建：在涉及大量冲突的重大变基或分支合并后，使用以下命令强制重建索引：

  codegraph index --force
  

• Git 同步钩子（监视器关闭时）：如果设置了 CODEGRAPH_NO_WATCH=1，CodeGraph 可以安装 post-commit、post-merge 和 post-checkout 钩子，这些钩子会在分支切换后自动触发后台 codegraph sync。

Git 工作树与“借用索引”风险

• 索引发现：CodeGraph 通过从当前工作目录向上遍历父目录来发现 .codegraph/。
• 风险：使用 Git 工作树时（例如 git worktree add ../feature-worktree feature），如果工作树缺少自己的 .codegraph/ 目录，CodeGraph 会向上遍历并绑定到主签出目录的 .codegraph/ 索引。工作树中的查询将返回来自主签出分支的符号和源代码，从而丢失工作树特定的更改！
• 不匹配检测：CodeGraph 通过比较 git rev-parse --show-toplevel 与 indexRoot（使用 git rev-parse --git-common-dir）来执行 detectWorktreeIndexMismatch 检测。当工作树借用主索引时，CodeGraph 会在 codegraph status 和 MCP 查询工具中发出警告。
• 工作树黄金法则：始终在每个工作树目录内运行 codegraph init（或 codegraph init -i）。每个工作树必须拥有自己专用的 .codegraph/ 目录，以独立地索引其分支。
• 自定义目录隔离：如果需要自定义索引文件夹命名或隔离（例如分离 Windows 和 WSL2 签出），设置 CODEGRAPH_DIR（例如 export CODEGRAPH_DIR=.codegraph-worktree）。

规则

• 信任图谱的结果——它通过文件监视器保持同步（保存后 2 秒去抖）；不要用 grep 重新验证。
• 将 codegraph_explore 返回的源代码视为已读取；不要用 Read 工具重新打开同一文件。
• 仅查询拥有 .codegraph/ 索引的项目。没有索引的路径会返回清晰的指导，建议改用内置工具——索引仍然是一个有意的决策，而非自动行为。
• 在 Git 工作树中，通过 codegraph status 验证工作树是否拥有自己的本地索引，而不是借用主树的索引。
• 优先使用 codegraph_explore（或 CLI 中的 codegraph explore），而非更狭窄的隐藏工具（codegraph_node、codegraph_search、codegraph_callers、codegraph_callees、codegraph_impact、codegraph_files、codegraph_status）——这些工具返回的所有内容已经内联呈现在 codegraph_explore 中。

安装选项请参阅 INSTALL.md，包括附带的 Node.js 检查器/安装器脚本（位于 scripts/），仅在需要 npm 安装路径或库嵌入时使用。