立即开始

本页假设你已经安装了一种受支持的工具（Claude Code、VS Code Copilot、OpenAI Codex CLI、OpenCode、Cursor、Devin Desktop、Aider 或 Cline），并打算将 Coograph 添加到一个项目里。

环境要求

• Python 3.10+
• uv（推荐；首次运行时自动安装依赖）
• 一个 Git 仓库

安装

在项目根目录下：

# Clone Coograph as a sibling directory
git clone https://github.com/paullukic/coograph.git ../coograph

然后在你的 AI 工具聊天里触发初始化器。每个工具的调用语法不同。

自然语言改写（“initialize the project”、“set up coograph”）在每个工具里都有效——每份配置文件都把这些触发词和斜杠形式列在一起。

初始化器会自动识别你的技术栈，填好 AGENTS.md 和 .github/copilot-instructions.md 里的 _TBD_ 占位符，并（如果你选择）为项目构建代码图，把指令布局检查加入 CI。

Claude Code 插件

在 Claude Code 里，你可以把 Coograph 作为插件安装，而不是克隆到旁边的目录，之后用一条命令就能更新：

claude plugin marketplace add paullukic/coograph
claude plugin install coograph@coograph

# later
claude plugin update coograph@coograph

然后在你的项目里运行 /coograph:coograph-init。更新会刷新插件自身的技能、代理和 hook；init 复制到项目里的文件（指令、.claude/hooks/、.github/code-graph/、MCP 配置）需要再次运行 init 才会刷新。

检查安装

觉得哪里不对时（图查不到结果、某个工具不遵守规则、在另一台机器上新克隆），运行 /coograph-doctor（Codex CLI 用 $coograph-doctor，或者说 “check the install”）。它运行一个只读脚本，每项检查一行：

每个 WARN 或 FAIL 都附带修复方法。代理会逐个提出，只有你同意后才执行。init 的最后一步会运行 doctor，所以新安装应该只显示 PASS 和 SKIP（只有你拒绝的选项才会出现 WARN，比如 git hook）。不用代理时：python3 .github/skills/coograph-doctor/doctor.py。

Codex CLI 说明

Codex CLI 注册自定义工作流的方式跟另外七个工具不同。如果你用 Codex，扫一眼这节。

斜杠是保留字

Codex 把 / 留给约 30 个内置命令。输入 /coograph-init 会返回 Unrecognized command。改用：

• $coograph-init — 显式 $skill-name 调用。
• /skills — 内置命令，列出所有已安装的 skill。用来确认 Coograph 已加载。
• 自然语言 — "initialize the project"、"set up coograph"、"wire up coograph in this repo"。Codex 会匹配 skill 描述并自动激活。

Codex 在哪里查找 skill

Codex 按以下优先级扫描这些目录（出处）：

1. $CWD/.agents/skills
2. 父目录的 .agents/skills
3. $REPO_ROOT/.agents/skills
4. $HOME/.agents/skills
5. /etc/codex/skills
6. 内置系统 skill

Coograph 把 .agents/skills/coograph-init/SKILL.md 放在仓库根目录，所以项目里任何位置都能在第 3 步找到。

验证 skill 是否加载

在 Codex 会话里执行 /skills。如果没看到 coograph-init，要么你的 Codex 版本太旧不支持 skill，要么项目的 .agents/skills/ 目录丢了 — 从另一个支持的工具里重新执行 /coograph-init 来恢复。

手动构建图

如果你跳过了初始化器的代码图步骤，可以稍后再建：

uv run -p 3.12 --with-requirements .github/code-graph/requirements.txt \
  .github/code-graph/server.py --build

这会解析仓库里的每个源文件并写入 .code-graph/graph.db（SQLite，MB 量级，已在 gitignore 中）。

接入 MCP 服务器

Coograph 通过 Model Context Protocol 把图查询暴露给你的 AI 工具。

Claude Code（仓库根目录的 .mcp.json）

{
  "mcpServers": {
    "code-graph": {
      "type": "stdio",
      "command": "uv",
      "args": [
        "run",
        "-p",
        ">=3.10",
        "--with-requirements",
        "${workspaceFolder}/.github/code-graph/requirements.txt",
        "${workspaceFolder}/.github/code-graph/server.py"
      ],
      "env": { "UV_NO_MANAGED_PYTHON": "1", "UV_PYTHON_DOWNLOADS": "never" }
    }
  }
}

-p ">=3.10" 接受任何足以运行 MCP SDK 的 Python 版本。两个 env 固定项让 uv 使用系统安装的 Python：在启用了智能应用控制（Smart App Control）或 Defender 应用程序控制的 Windows 机器上，uv 自己下载的 Python 可能被禁止加载，服务器随即在启动时以 DLL load failed while importing _overlapped 退出。如果你没有 3.10 或更新的系统 Python，就去掉这两个固定项。

OpenCode（opencode.json）

OpenCode 既不读 .mcp.json，也不读 .github/skills/。在项目的工具列表里加上 opencode 并设置 code_graph: true 来注册它，sync 就会生成一个 opencode.json，里面有技能路径和代码图服务器。它有意写入本机的绝对路径：OpenCode 会相对于它启动时所在的文件夹解析相对的 cwd，所以在子文件夹里启动时相对路径会失效。它只在缺失时创建，永远不会被重写，也不应提交到仓库。

VS Code Copilot（.vscode/mcp.json）

{
  "servers": {
    "code-graph": {
      "type": "stdio",
      "command": "uv",
      "args": [
        "run",
        "-p",
        ">=3.10",
        "--with-requirements",
        "${workspaceFolder}/.github/code-graph/requirements.txt",
        "${workspaceFolder}/.github/code-graph/server.py"
      ],
      "env": { "UV_NO_MANAGED_PYTHON": "1", "UV_PYTHON_DOWNLOADS": "never" }
    }
  }
}

第一次查询

在你选用的代理会话里：

“要给 OrderService.place_order 加缓存，需要读哪些文件？”

代理调用 get_minimal_context(...)。它把 OrderService 和 place_order 解析到图上，从定义它们的文件出发，沿依赖边向外走——四到六个文件，而不是关键词的每一个匹配。它同时还返回图的规模、未提交改动的风险，以及要放宽范围该用哪个工具。

当任务里提到的东西不在图里时，文件列表要么为空，要么来自同一句话里更宽泛的词，而 files_reason 会说明是哪种。一个基于猜测的答案会被标注成猜测。

自动更新

安装一次 git 钩子：

cp .github/code-graph/post-commit  .git/hooks/post-commit
cp .github/code-graph/post-merge   .git/hooks/post-merge
cp .github/code-graph/post-rewrite .git/hooks/post-rewrite
chmod +x .git/hooks/post-{commit,merge,rewrite}

每次提交、合并或 rebase 时，图只重新解析 SHA-1 变了的文件。更新只要毫秒级。

保持项目最新

在 Coograph 检出目录的 projects.json 里注册过的项目，会在每次 git pull Coograph 时同步：技能、代理、hook、Retro 分析器和布局检查器都会刷新。sync 永远不会覆盖你编辑过的文件。它要替换的每个文件，都会和它上次写入的内容以及 Coograph 发布过的每一个版本比对；两者都不匹配的文件会被保留，新的上游版本放进 .coograph/upstream/<path>，日志里写 KEPT <path> (local edit)。要采用新版本，把它复制覆盖你的文件，再同步一次。CLAUDE.md、AGENTS.md、copilot-instructions.md、layout.json、rules.json 和 GOTCHAS.md 归你所有，一旦存在就永远不会被写入。

下一步

• 代码图 — graph.db 里有什么，怎么查
• 工作流 — Plan → Propose → Apply，安全推进大改动
• 指令布局：让指令文件保持在预算之内