a620906209
89b8e8f343
Run Tests / test (pull_request) Successful in 34s
記錄重建步驟、已知限制（enum case 引用、腳本檔名遮蔽、 子代理並行上限）與前 16 大社群的人工命名對照表。 Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
59 lines
3.0 KiB
Markdown
59 lines
3.0 KiB
Markdown
# 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 這次建置有效；重建後需重新核對。
|