立即开始
仓库： GitHub 上的 paullukic/coograph。旧地址 paullukic/copilot-template 通过 README 提示重定向。
本页假设你已经安装了一种受支持的工具（Claude Code、VS Code Copilot、OpenAI Codex CLI、OpenCode、Cursor、Windsurf、Aider 或 Cline），并打算将 Coograph 添加到一个项目里。
环境要求
- Python 3.10+
uv（推荐；首次运行时自动安装依赖）- 一个 Git 仓库
安装
在项目根目录下：
# Clone Coograph as a sibling directory
git clone https://github.com/paullukic/coograph.git ../coograph然后在你的 AI 工具聊天里触发初始化器。每个工具的调用语法不同。
| 工具 | 调用方式 |
|---|---|
| Claude Code | /coograph-init |
| VS Code Copilot | /coograph-init |
| Codex CLI | $coograph-init 或 “initialize the project” — Codex 保留 / 给内置命令（见下方 Codex CLI 说明） |
| OpenCode | /coograph-init |
| Cursor | /coograph-init（字符串匹配，无菜单） |
| Windsurf | /coograph-init（字符串匹配） |
| Aider | /coograph-init（字符串匹配） |
| Cline | /coograph-init（字符串匹配） |
自然语言改写（“initialize the project”、“set up coograph”）在每个工具里都有效——每份配置文件都把这些触发词和斜杠形式列在一起。
初始化器会自动识别你的技术栈，填好 .github/copilot-instructions.md 里的 _TBD_ 占位符，并（如果你选择）为项目构建代码图。
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 按以下优先级扫描这些目录（出处）：
$CWD/.agents/skills- 父目录的
.agents/skills $REPO_ROOT/.agents/skills$HOME/.agents/skills/etc/codex/skills- 内置系统 skill
Coograph 把 .agents/skills/coograph-init/SKILL.md 放在仓库根目录，所以项目里任何位置都能在第 3 步找到。
验证 skill 是否加载
在 Codex 会话里执行 /skills。如果没看到 coograph-init，要么你的 Codex 版本太旧不支持 skill，要么项目的 .agents/skills/ 目录丢了 — 从另一个支持的工具里重新执行 /coograph-init 来恢复。
手动构建图
如果你跳过了初始化器的代码图步骤，可以稍后再建：
uv run --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",
"--with-requirements",
"${workspaceFolder}/.github/code-graph/requirements.txt",
"${workspaceFolder}/.github/code-graph/server.py"
]
}
}
}VS Code Copilot（.vscode/mcp.json）
{
"servers": {
"code-graph": {
"type": "stdio",
"command": "uv",
"args": [
"run",
"--with-requirements",
"${workspaceFolder}/.github/code-graph/requirements.txt",
"${workspaceFolder}/.github/code-graph/server.py"
]
}
}
}第一次查询
在你选用的代理会话里：
“要给
OrderService.place_order加缓存，需要读哪些文件？”
代理会对图调用 get_minimal_context(...)，返回四到六个文件，而不是对每个匹配做 grep。
自动更新
安装一次 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 帮上了忙，给 GitHub 加颗星能让下一个人更容易找到它。