ops：維運與安全

快取是「圖越大越省」的來源之一：

• file_hash(path, root, cache_root) — 算檔案的內容雜湊（_body_content 只算內容、不含路徑——所以改名也能沿用快取；用 _stat_index 以 stat 簽名快取雜湊本身，避免大檔每次重算）。
• load_cached(path, root, kind) — 依內容雜湊找快取；載入時會把快取內的絕對路徑/ID重新對齊到目前的 root（_relativize_* / _absolutize_*），所以換機器、搬資料夾都能用。
• save_cached(path, result, root, kind) — 寫快取，同樣做路徑可攜化。
• cached_files / clear_cache — 列出快取檔 / 清空。

除此之外還有 prompt_fingerprint（對 prompt 內容算指紋，語意抽取的快取 key 之一）與 cached_word_count（detect 的字數統計快取）。

段落式說明：與 AST 快取同構，但存的是 LLM 抽取的結果。文件語料每次只把 uncached_files 送 LLM，其餘從快取載入——這是「每天更新的 1000 檔語料」能維持低成本的核心。

這是 設計文件 的落地實作，比設計更周全：

1. 跨專案防護：節點帶 repo 欄位且超過一個 repo → 直接 raise。不同 repo 的 label 撞名是巧合，絕不能靠字串相似度合併。
2. ID 預合併：每個 ID 只留一個節點，生還者是「定義這個 ID 的節點」（其 source_file 就是 ID 編碼的那個檔），不是「第一個看到的」——這樣 chunk 順序不決定誰生還（issue #1851）。同源重複的缺失屬性補進生還者（AST 結構與語意補充共存）。
3. 接著是 label 層的模糊合併（entropy gate → MinHash/LSH → Jaro-Winkler → community boost → union-find → 可選 LLM 仲裁），每步都有對應的 _* helper。
4. 最後把邊重接到生還者。

段落式說明：

• _entropy(label) — 算 label 的資訊熵（bits/char），短歧義名（AI、x）太低就不做模糊比對。
• _shingles(text, k) / _make_minhash(text) — 3-gram shingles + MinHash（128 排列），供 LSH blocking 用 O(n) 產生候選對。
• _is_variant_pair(a, b) — 判斷是否為「變體對」（錯字、複數、空格等）。
• _crossfile_fileanchored_blocked — 跨檔 + 檔錨定的節點不作模糊合併（避免 Account 型別誤併）。

段落式說明：_detect_url_type 先判斷 URL 類型（網頁 / arxiv / tweet / 影音 / 一般二進位），再分派到 _fetch_webpage（HTML→Markdown）、_fetch_arxiv（論文）、_fetch_tweet、_download_binary。所有抓取都走 security 的 safe_fetch。

段落式說明（這支很大，挑重點）：

• 用 pending 佇列（_queue_pending / _drain_pending）把變更先落地、再重建成圖，避免熱循環。
• _rebuild_lock — 防止併發重建。
• _reconcile_existing_graph — 把既有圖與新抽取結果調和（增量更新）。
• _check_shrink — 與 to_json 的 shrink guard 對應，重建結果更小就不覆寫。
• 文件頂部有一串 resource limits / git_head / 路徑處理的 helper。

段落式說明：python -m graphify.serve graphify-out/graph.json 啟動 MCP stdio server，提供 query_graph、get_node、get_neighbors、shortest_path 等工具。

query 不是簡單關鍵字比對，而是一套加權評分：_query_terms 切詞（含中文分詞，jieba）→ _compute_idf 算 IDF → _trigram_index 建三字母索引加速候選 → _score_nodes / _score_query 評分。還有 _GraphContextCache 做多專案圖的快取、_load_graph 對損壞圖的復原訊息（見 SECURITY.md）。

SSRF 防護的解析：

1. 用 urlparse 檢查 scheme 是否在 _ALLOWED_SCHEMES（http/https）——file://、ftp://、data: 全部擋掉。
2. 擋已知雲端 metadata hostname（169.254.169.254 等，_BLOCKED_HOSTS）。
3. DNS 解析後驗證 IP：socket.getaddrinfo 把 hostname 解析成 IP，逐一檢查是否落在私有/保留網段（_ip_is_blocked，含 127.x、10.x、169.254.x…）。

光這樣還不夠——validate_url 只是入口。真正的連線用 _SSRFGuardedHTTP(S)Connection 子類別（下一個 fn-block）。

這是一段很漂亮的進階防禦。註解說得很清楚：不 monkey-patch 全域 socket.getaddrinfo（那在並發下是 thread-safe 的 TOCTOU 隱患），而是子類別化 HTTP(S) connection——每個連線只解析一次 DNS、驗證結果 IP、然後連到那個精確 IP。沒有第二次解析，所以 DNS-rebind 攻擊無法在驗證與連線之間換成私有位址。

教學價值：這說明「驗證 URL」與「安全連線」是兩回事——前者是入口檢查，後者是對抗 TOCTOU 的防禦。

段落式說明：

• safe_fetch(url, max_bytes=50MB, timeout=30) — 串流抓取，超過 50MB 中止，非 2xx 拋 HTTPError（錯誤頁不當內容）。
• safe_fetch_text(url, max_bytes=10MB) — 文字版。
• validate_graph_path(path, base) — 解析路徑並要求落在 graphify-out/ 內（防 MCP 路徑穿越）。
• sanitize_label(text) — 去控制字元、上限 256 字元、HTML-escape（防 XSS 與 prompt injection）。
• check_graph_file_size_cap — graph.json 的 512 MiB 上限。

段落式說明：只有 95 行的模組。檢查每個節點/邊的必要欄位（id、label、source_file、source、target、relation），回傳錯誤訊息清單；assert_valid 在錯誤時直接 raise。build_graph() 消費前會先跑它——schema 錯誤就不組圖。