RFC：檔案級節點摘要

問題

graph.json 給了代理圖的結構、原始檔、節點 label 與關係。這能避免讀整個 repo，但代理常常還是得打開原始檔，只為了回答一個最基本的導覽問題：

這個檔案／節點是負責做什麼的？

一個放在圖節點附近的短摘要，可以減少 graphify query、graphify explain、MCP 節點查詢與圖導覽時的重複讀檔。

目標與 Non-goals

Goals:
- Help agents choose relevant files with less context.
- Preserve offline, deterministic behavior by default.
- Keep the first implementation small and reviewable.
- Avoid adding long prose to GRAPH_REPORT.md.
- Leave room for a future opt-in LLM summary backend.

Non-goals:
- Summarizing every function/method in v1.
- Calling an LLM by default.
- Replacing graphify explain.
- Turning GRAPH_REPORT.md into a per-file index.

兩種方案的共同約束

• 第一版只做檔案級節點。
• 每條摘要要有界：一句話、約 200–300 字元。
• 先從既有本機訊號產生確定性摘要：模組 docstring、檔頭註解、匯出符號、import、關係數、社群/脈絡資料。
• 儲存模型定案前，預設不輸出摘要。
• 有摘要時在 graphify explain <node> 顯示。
• 有摘要時在 graphify serve / MCP 節點查詢包含。

摘要該含什麼

建議欄位：summary（一句話描述檔案職責，主要省 token 欄位）、source_file（不需解析節點 ID 就能跳到對的檔）、label、generated_by（區分確定性與未來的 LLM 摘要）、summary_version（格式可演進）。

建議納入句子內的訊號：模組 docstring / 檔頭註解（通常是最優質的人工目的陳述）、匯出類別/函數/符號（檔案提供什麼 API 面）、重要 import（屬 auth/DB/UI/CLI/test）、主導圖關係（主要呼叫/匯入/定義）、社群或附近 hub label、可用的來源位置覆蓋。不含長呼叫鏈、完整相依清單、原始碼、每個符號。

{
  "label": "extract.py",
  "source_file": "graphify/extract.py",
  "summary": "Extracts source files into graph nodes and relationships; defines language parsers and import/call extraction helpers.",
  "generated_by": "deterministic",
  "summary_version": 1
}

Option A：摘要放進 graph.json

在檔案級節點加一個可選 summary 欄位。使用者流程：graphify . --summarize-nodes → graphify explain "extract.py"。

優點：圖消費者單一 artifact；符合 NetworkX 節點屬性與既有節點 metadata；explain/serve/視覺化/MCP 都好取用；沒有 sidecar 新鮮度或節點 ID 對接邏輯。

缺點：文字加進核心圖 artifact；圖 schema 面變大；把整個 graph.json 倒進 LLM context 的消費者會一次付出所有摘要的 token。

Option B：sidecar node-summaries.json

摘要寫進另一個以節點 ID 為 key 的 artifact。使用者流程：graphify summarize → graphify explain "extract.py"。

優點：graph.json 保持精簡與拓撲聚焦；摘要明確可選；可獨立重新產生；有放未來 generator metadata 的自然位置。

缺點：多了消費者必須發現並載入的第二個 artifact；引入新鮮度與同步問題；每個想用摘要的消費者都要靠節點 ID 對接。

提議的首版實作順序

1. 加確定性檔案級摘要產生。
2. 用選定的 option 儲存摘要。
3. 在 graphify explain 顯示摘要。
4. 在 graphify serve / MCP 節點查詢顯示。
5. 加測試：預設行為、產生的摘要、缺摘要、摘要長度上限。

後續想法

• 可選的 LLM 生成摘要，帶明確 provider/backend 選擇。
• 若檔案級摘要被證實有用，擴展到 class / module 級節點。
• 允許 graphify query 在預算內為回傳節點包含摘要。
• 若摘要與主圖分開產生，加 cache/新鮮度 metadata。

教學延伸：這份 RFC 展示了 Graphify 團隊怎麼為「AI 代理導覽」設計介面——而實際的檔案摘要概念已部分體現在「本站怎麼挑要教哪個檔案」的策展邏輯上。想讀 graph.json 的實際 schema，看 概念地圖 或 實作案例。