CFDivePlatform/docs/GRAPHIFY.md

graphify 知識圖譜操作筆記

graphify 把專案的程式碼、OpenSpec 文件、設定檔轉成可查詢的知識圖譜，輸出在 graphify-out/。 該目錄被 .gitignore 忽略（graph.json 每次重建都整份重寫，進版控只會產生無意義 diff），換機器或清掉後需自行重建。

規則（先 query 再 grep、改完程式碼跑 graphify update .）見根目錄 CLAUDE.md，此處不重複。

建置紀錄（2026-10-29）

• 規模：2429 節點、4369 邊、約 117 個社群
• 來源：253 個程式碼檔以 AST 抽取；218 份文件與 5 張圖片以子代理做語意抽取
• 語意抽取沒有設 GEMINI_API_KEY，由 Claude Code 的子代理擔任 LLM

安裝與重建

uv tool install --upgrade graphifyy   # 安裝（Windows，graphify 位於 uv tool 目錄）
/graphify .                           # 在 Claude Code 內完整建置
graphify update .                     # 只重新處理變更的檔案（AST 免費，語意抽取才耗 token）
graphify query "<問題>"               # 查詢既有圖譜

完整建置的語意抽取需派約 15 個子代理，同時最多 4 個（超過會被拒絕），要分批派。

已知限制與踩過的坑

項目	說明	處理
enum case 引用	AST 只看得到類別被引用，看不到 BookingStatus::Pending 這類 case 的使用處，所以 Pending／Confirmed／Completed 在圖上看起來孤立	查 enum case 的使用處改用 grep
腳本檔名	輔助腳本不可命名為 ast.py，會遮蔽標準函式庫造成循環匯入	換名稱，並用 python -I 執行
二進位檔覆蓋率	PNG 沒有「行數」，覆蓋率檢查會誤報 partial（hero.png）	可忽略
子代理只讀檔頭	.pi/agents/ 三個檔案只讀了檔頭，未寫入 manifest	與 .claude/agents/ 僅工具名稱寫法不同，已決定不補
同端點邊合併	YAML 中重複的鍵（如 steps 底下多個 name）會被合併成一條邊	正常現象，不是圖損壞

社群命名

graphify 預設以「連線最多的節點名稱 + cluster」命名社群。前 16 大社群已手動改名（依成員與所在資料夾判斷）：

編號	名稱
0	預約狀態機與生命週期測試
1	預約通知（Notification 類別）
2	早期 OpenSpec 設計文件（預約／評價／會員入口）
3	教練端前端（排程／評價／個人檔案）
4	預約即時訊息（Reverb 事件）
5	認證強化 spec（鎖定／OAuth state／稽核補強）
6	課程排程與預約 API
7	會員端前端（我的預約／課程列表）
8	AuthController 認證
9	前端與根目錄 package.json
10	課程詳情頁前端（評價／預約）
11	前端 Pinia 狀態與通知
12	評價功能測試
13	Docker Compose 服務
14	Feature 測試基底與授權測試
15	管理後台前端

社群編號可能隨重建而改變，此表只對 2026-10-29 這次建置有效；重建後需重新核對。