背景

進階團隊把 graphify 用得很深之後，會出現「多圖譜共存」的場景：

• 同一台機器跑了兩個 python -m graphify.serve（一個本地實驗、一個 team 共用）
• 同一份 codebase 有多份 graph.json（main branch 的、feature branch 的、merge-graphs 合出來的）
• Claude Code 跟 Cursor 同時裝了 graphify，MCP 設定各自指向不同圖譜

這時常見的詭異症狀：

• 助理回答「我知道這個 function」但拿的是過時圖譜
• 兩個助理對同一個問題給出不一致的答案
• MCP server 莫名其妙 401 或 timeout
• query 結果跟程式碼對不上，卻找不到原因

這些多半是「same-endpoint 衝突」：多個 graphify 實例搶同一個資源（同一個 port、同一個 graph.json、同一個 API key），互相踩腳。graphify diagnose multigraph 是專門抓這類問題的診斷指令。

⚠️ 注意：是 graphify diagnose multigraph，子指令不可省。graphify diagnose（沒接子指令）不會做事。

適用情境

• 同機器跑多個 graphify MCP server（local + team 共用）
• 多平台整合（Claude Code + Cursor + Codex CLI 都裝了 graphify）
• 升級 graphify 版本後行為異常，懷疑舊實例殘留
• 多人共用開發機，懷疑別人的 graphify 干擾自己
• merge-graphs 後查詢結果異常（子圖譜與合併圖同時被助理存取）

完整流程

步驟 1：症狀確認

先確認問題真的是 multigraph 衝突，而不是其他原因。常見症狀：

• graphify query 在 CLI 正確，但在助理內錯
• 兩個助理（例如 Claude Code 跟 Cursor）對同一問題答案不一致
• graphify hook status 顯示 hook 跑過，但圖譜還是過時
• MCP server 連線間歇性失敗

如果只在一個地方出錯，先排除該處本身的問題（hook 沒裝、圖譜過時、API key 失效）。多處同時詭異、症狀跳來跳去，才比較可能是 multigraph 衝突。

步驟 2：跑 diagnose multigraph

確認懷疑之後，直接跑診斷：

cd ~/my-project

graphify diagnose multigraph

graphify 掃描系統現況，列出所有正在運行或已註冊的 graphify 實例：

Scanning for multigraph conflicts...

== Running MCP servers ==
[1] PID 4521  python -m graphify.serve
    graph: /home/alice/my-project/graphify-out/graph.json (modified 2h ago)
    transport: http://0.0.0.0:8080
    api-key: set (starts with "sk-team-...")

[2] PID 28432  python -m graphify.serve
    graph: /home/alice/my-project/graphify-out/merged.json (modified 5min ago)
    transport: http://0.0.0.0:8080
    api-key: set (starts with "sk-alice-personal-...")

⚠️  CONFLICT: Two servers binding same port 8080
    → Assistant may hit either server nondeterministically
    → Two different api-keys registered: queries from one client may 401 on the other

== Registered AI assistants ==
[1] Claude Code (.config/claude/mcp.json)
    graphify endpoint: http://localhost:8080/mcp
    → points to conflicting port

[2] Cursor (.cursor/mcp.json)
    graphify endpoint: http://localhost:8080/mcp
    → same endpoint as Claude Code, but different graph behind it

== On-disk graph files ==
[1] graphify-out/graph.json        (current branch: main)
[2] graphify-out/merged.json       (from merge-graphs)
[3] graphify-out/feature-x.json    (stale, 3 days old)

⚠️  STALE: graphify-out/feature-x.json last modified 3 days ago
    → Likely abandoned; consider removing to avoid confusion

這份報告就是你需要的根因地圖。

步驟 3：解讀報告，定位根因

報告分三區：

• Running MCP servers：現在正在跑的 python -m graphify.serve 實例，含 PID、port、graph 路徑、API key
• Registered AI assistants：各助理平台的 MCP 設定，看 endpoint 指到哪
• On-disk graph files：硬碟上所有 graph.json 相關檔案，標出 stale（過時）的

重點看 ⚠️ 標記：

• Port 衝突：兩個 server 搶同一個 port，助理隨機打到任一個
• API key 不一致：不同 server 用不同 key，client 偶爾 401
• Stale 檔案：廢棄的 graph.json 還躺在那、可能被誤用
• Endpoint 指向不一致：兩個助理 endpoint 看似相同，背後其實是不同 graph

步驟 4：清理衝突

依報告動手清理。範例情境的修復：

# 1. 殺掉搶 port 的舊 server（PID 28432 是本地實驗殘留）
kill 28432

# 2. 移除 stale 的 feature-x.json
rm graphify-out/feature-x.json

# 3. 統一兩個助理的 endpoint 設定，指向 team 共用 server
# 確認 Claude Code 的 .config/claude/mcp.json 跟 Cursor 的 .cursor/mcp.json
# 都指向同一個 URL（http://localhost:8080/mcp）

# 4. 統一 API key
export TEAM_GRAPHIFY_KEY=sk-team-...
# 兩個助理的 headers 都用這個 key

清完再跑一次診斷確認：

graphify diagnose multigraph

這次應該乾淨：

Scanning for multigraph conflicts...

== Running MCP servers ==
[1] PID 4521  python -m graphify.serve
    graph: /home/alice/my-project/graphify-out/graph.json
    transport: http://0.0.0.0:8080
    api-key: set (starts with "sk-team-...")

== Registered AI assistants ==
[1] Claude Code → http://localhost:8080/mcp  ✓
[2] Cursor      → http://localhost:8080/mcp  ✓

== On-disk graph files ==
[1] graphify-out/graph.json        (current branch: main)
[2] graphify-out/merged.json       (from merge-graphs)

✓ No conflicts detected.

步驟 5：把診斷自動化進 CI / 開機腳本

多人共用開發機、或自己常開多個 server，把 diagnose 加進日常腳本：

# ~/.local/bin/graphify-health.sh
#!/usr/bin/env bash
set -e

echo "==> graphify multigraph health check"
graphify diagnose multigraph

echo "==> hook status"
graphify hook status

每天早上或開機跑一次，問題一出現就抓到，不會累積到「助理行為詭異」才回頭找。

步驟 6：升級前後的例行診斷

升級 graphify 版本（例如 v0.9.31 → v0.9.32）前後都跑一次 diagnose：

# 升級前：記錄現況
graphify diagnose multigraph > /tmp/before-upgrade.txt

uv tool install graphifyy --upgrade
graphify install

# 升級後：比對
graphify diagnose multigraph > /tmp/after-upgrade.txt
diff /tmp/before-upgrade.txt /tmp/after-upgrade.txt

升級偶爾會留下舊版的 server、hook、或 MCP 註冊，diagnose 抓得出來。

真實輸出範例

$ graphify diagnose multigraph
Scanning for multigraph conflicts...

== Running MCP servers ==
[1] PID 4521  python -m graphify.serve
    graph: /home/alice/my-project/graphify-out/graph.json (modified 2h ago)
    transport: http://0.0.0.0:8080
    api-key: set (starts with "sk-team-...")

[2] PID 28432  python -m graphify.serve
    graph: /home/alice/my-project/graphify-out/merged.json (modified 5min ago)
    transport: http://0.0.0.0:8080
    api-key: set (starts with "sk-alice-personal-...")

⚠️  CONFLICT: Two servers binding same port 8080
    → Assistant may hit either server nondeterministically

== Registered AI assistants ==
[1] Claude Code → http://localhost:8080/mcp
[2] Cursor      → http://localhost:8080/mcp
    (both point to the conflicting port)

== On-disk graph files ==
[1] graphify-out/graph.json        (current, main)
[2] graphify-out/merged.json       (from merge-graphs)
[3] graphify-out/feature-x.json    ⚠️ stale (3 days old)

== Summary ==
2 conflicts found. See steps above to resolve.

對比傳統排查

diagnose multigraph 的價值在「整合視角」：把 server、助理、檔案三個面向一次呈現，不用切換工具。

失敗處理

內部連結

• graphify install 指令詳解
• graphify watch-update 指令詳解
• graphify build 指令詳解
• 完整開發工作流

下一步

1. 合併多個子專案圖譜（合併圖譜是 multigraph 衝突的常見來源）
2. PR 審查 + 團隊共享 graphify-out（共用 MCP server 的正確設定）

關鍵學習點

• 指令是 graphify diagnose multigraph，子指令不可省。graphify diagnose 單獨跑不做事。
• 同機器多個 graphify 實例的根因通常是：port 衝突、API key 不一致、stale 檔案、endpoint 指向不一致。diagnose 一份報告抓全部。
• 症狀若是「多處同時詭異、症狀跳來跳去」，優先懷疑 multigraph 衝突，而不是單一環節壞掉。
• 升級前後跑 diagnose 並 diff，是抓升級殘留（舊版 server / hook / 註冊）的最快方法。
• 把 diagnose 加進開機腳本或日常 health check，問題一出現就抓到，不會累積到「助理行為詭異」才回頭找根因。