From 89b8e8f343fd407452a6100158cc0448f2f6dea5 Mon Sep 17 00:00:00 2001 From: Hank Date: Thu, 29 Oct 2026 17:34:29 +0800 Subject: [PATCH] =?UTF-8?q?docs(graphify):=20=E6=96=B0=E5=A2=9E=E7=9F=A5?= =?UTF-8?q?=E8=AD=98=E5=9C=96=E8=AD=9C=E6=93=8D=E4=BD=9C=E7=AD=86=E8=A8=98?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 記錄重建步驟、已知限制（enum case 引用、腳本檔名遮蔽、 子代理並行上限）與前 16 大社群的人工命名對照表。 Co-Authored-By: Claude Sonnet 5.5 --- docs/GRAPHIFY.md | 58 ++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 58 insertions(+) create mode 100644 docs/GRAPHIFY.md diff --git a/docs/GRAPHIFY.md b/docs/GRAPHIFY.md new file mode 100644 index 0000000..7fa4514 --- /dev/null +++ b/docs/GRAPHIFY.md @@ -0,0 +1,58 @@ +# 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 + +## 安裝與重建 + +```bash +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 這次建置有效；重建後需重新核對。 -- 2.52.0