開始使用

這頁假設你已經裝好其中一個支援的工具（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 安裝成外掛，而不是並列的 clone，並用一條指令更新它：

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

# later
claude plugin update coograph@coograph

然後在你的專案裡執行 /coograph:coograph-init。更新會刷新外掛本身的 skill、代理和 hook；init 複製到專案裡的檔案（指令、.claude/hooks/、.github/code-graph/、MCP 設定）需要再次執行 init 才會刷新。

檢查安裝

覺得哪裡不對時（圖查不到結果、某個工具不遵守規則、在另一台機器上新 clone），執行 /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 Application Control 的 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，內含 skill 路徑和程式碼圖伺服器。它刻意寫入本機的絕對路徑：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}

每次 commit、merge 或 rebase 時，圖只重新解析 SHA-1 有變動的檔案。更新只要毫秒。

讓專案保持最新

登記在 Coograph 簽出目錄 projects.json 中的專案，會在每次 git pull Coograph 時同步：skill、代理、hook、Retro 分析器和佈局檢查器都會被更新。同步永遠不會覆寫你編輯過的檔案。每個它要取代的檔案，都會和它上次寫入的內容以及 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，安全地做大改動
• 指令佈局：讓指令檔案保持在預算之內