實作案例

真實產出的互動知識圖譜與查詢示範

本站的實作案例不是示意圖——每個都是真實工具跑出來的。第一個案例用 graphify 掃描 OpenCodeReview 自己的 Go 源碼,做出可操作的互動知識圖譜。

第一個案例:OCR 源碼知識圖譜

下方是真實 graphify 產出的互動圖(社群聚合檢視)。節點是 168 個功能社群(對應 OCR 的模組結構:command 層、agent 編排、diff 解析、規則引擎…),邊是跨社群的呼叫關係。可拖曳、縮放、點節點看細節、搜尋。

graphify 知識圖譜 — OCR 第一方源碼(社群聚合檢視) 英文界面 ↗中文界面 ↗審計報告 ↗
怎麼跑的:graphify 0.9.40(PyPI graphifyy),對上游 cmd/ + internal/ + bin/ + scripts/(對齊 commit 9148bfd)跑 code-only AST 抽取——純本機、零 LLM、零 API key。完整重現步驟在案例頁。

想看 OCR 對「真實 PR」的評審能力(逐行註解、規則匹配),案例會持續新增。

📖 教學解說:實作案例的價值

Dogfooding:用自己分析自己

graphify 掃描 OCR 自己的源碼——這就是「dogfooding」。價值在於:① 驗證 graphify 的能力(如果它連 OCR 的架構都分析不出來,就不可信)② 產生 OCR 自己的架構地圖(可以反過來用來改善 OCR)。

互動知識圖譜的操作方式

  • 拖曳:按住空白區域拖曳移動視圖
  • 縮放:滾輪縮放,看全局或深入細節
  • 點擊:點節點看該社群的成員檔案與關聯
  • 搜尋:在搜尋框輸入關鍵字定位特定節點

168 個社群意味著什麼

每個社群對應 OCR 的一個功能模組:command 層、agent 編排、diff 解析、規則引擎、工具系統、LLM 通訊、session 持久化、viewer server…社群之間的邊就是跨模組的呼叫關係。如果某個社群特別大或特別孤立,可能暗示架構需要拆分。

🔍 Worked Example:如何重現這個案例

Step 1 — 安裝 graphify

pip install graphifyy

Step 2 — Clone OCR repo

git clone https://github.com/alibaba/open-code-review && cd open-code-review

Step 3 — 跑 graphify

graphify . --output graph.json --format code

Step 4 — 開啟互動圖

graphify serve graph.json  # localhost:8080

產出:4,128 節點 / 12,278 邊 / 168 社群的互動知識圖譜。

練習 / 驗收清單

  • 能描述 graphify 掃描 OCR 源碼的流程
  • 能互動操作知識圖譜(拖曳、縮放、搜尋)
  • 能解釋 dogfooding 的價值

① 進階真實情境 Worked Example:用 OCR 評審 OCR 自己的真實 PR(dogfooding)

情境

你要把一個新功能合進 OpenCodeReview 上游(例如「新增一個 ocr export 命令」)。在開 PR 前,你先用 OCR 審自己對 OCR 的改動——工具審工具、自證清白,順便驗證「在 14 萬行的 Go 專案上,OCR 自己值不值得信任」。

Step 1 — 先跑 preview,確認範圍合理

ocr review --preview

在 OCR 自己的 repo 裡,你會看到 cmd/、internal/ 的變更;*_test.go 預設被擋掉(default_path)——如果你這次改動有測試,就要用 include 把它們撈回來審。

Step 2 — 帶背景跑正式評審

ocr review --background "add ocr export command: dump session comments to JSON file" \
  --format json --audience agent > self-review.json

Step 3 — 用 viewer 看 Agent 在我們自己的架構裡怎麼用工具

開 Session Viewer,找 main_task 泳道:它有沒有用 code_search 找到 internal/session 的既有 API?有沒有讀 cmd/opencodereview/main.go 了解命令註冊方式?這同時是「對 OCR 自身的整合測試」。

Step 4 — 對照自己的 ground truth

你(人類)在寫程式時一定知道哪邊有風險(例如「忘了處理 session 不存在」)。對照 OCR 有沒有抓到——這是最直接的「這工具行不行」測試。

為什麼選這條審查路徑

Dogfooding 是最誠實的驗證:如果你連自己的 repo 都不信任 OCR,就沒資格要求團隊信任。用 --preview 先看範圍、--background 給需求脈絡、viewer 檢查工具使用——這套流程同時在驗證「OCR 的教學宣稱」與「OCR 的實際能力」。它是這個教學站所有概念的總驗收。

預期產出

self-review.json: 6 files reviewed, 4 comments
  你心中的 ground truth: 2 個風險點
  OCR 命中: 1/2(另一個是「session 檔案不存在」——OCR 看不到磁碟以外的狀態)
  → 結論: 當第二雙眼睛合格;當唯一把關不夠

② 深入原理擴充:知識圖譜(graphify)與評審管線(OCR)是互補的兩種「讀 code」

AST 抽取 vs 語意理解

graphify 對 OCR 源碼做的是 AST 抽取——把函式、結構、呼叫關係變成圖(4,128 節點 / 12,278 邊)。它確定、快速、零 token,但讀不懂「為什麼」——它看的是形狀。OCR 是 LLM 語意理解——讀 diff、跑工具、懂「這段程式碼的意圖」。兩者是同一顆專案的兩種投影:圖譜給你「地圖」,評審給你「路況報告」。

「看起來通過 review 但其實有隱患」的案例

# 你在 OCR 上跑 dogfood review,得到 exit 0 + 0 comments:
ocr review --preview
# → 0 files (no changes in workspace)
# 你以為「我改的碼很乾淨!」——但其實是「工作區沒有變更,根本沒審到」

# 或: 你跑了 review 但忘了 --background
# → Agent 不知道這顆 PR 在幹嘛 → 評論全部是「風格層級」的低價值建議
# → 看起來「審過了」,實際上是「審了,但審在霧裡」

Dogfooding 最容易自欺:「工具通過了」與「工具審過了我的東西」是兩件事。隱患:把「0 comments」誤讀成「程式碼完美」。防禦:先 --preview 確認真的有檔被審;再對照自己的 ground truth(你知道哪裡有風險)確認 OCR 有命中至少一個——否則先質疑「評審有效性」再質疑「程式碼品質」。

③ 診斷式疑難排解

症狀可能原因解決方案
dogfood review 零檔案可審工作區沒有變更(你可能改了但沒 save/stage)用 git status 確認;或改用 ocr review -c <sha> 審已 commit 的改動
self-review 的評論品質低(都是風格建議)沒傳 --background,Agent 不知道 PR 意圖重跑並傳 --background "PR 目的"
測試檔沒被審default_path 預設排除 *_test.go用 include 強制保留測試檔(include 繞過 default_path)
viewer 找不到這次 sessionsession 存在 <encoded-repo-path> 下,目錄名編碼了路徑在 ~/.opencodereview/sessions/ 下用 ls / find 找最近 jsonl
對照 ground truth 發現 OCR 漏了你知道的風險低 Recall 的設計取捨,或該風險需跨檔/磁碟狀態把風險寫成規則(rule.json)讓 Agent 聚焦;接受「少而準」

④ 進階挑戰題

  1. 挑戰一:design a dogfooding experiment:在 OCR 自己的 repo 上,故意在一個小 commit 裡埋 3 個你知道的 bug,看 OCR 抓幾個。列出實驗步驟與「通過」標準。
  2. 挑戰二:解釋「知識圖譜(AST)與評審(LLM)為什麼是互補」——各自在「接手陌生 codebase」時扮演什麼角色?
  3. 挑戰三:判斷題——「dogfood review 的 0 comments 證明我的程式碼完美」。這句話哪裡錯?提出三個「先確認審查有效」的檢查。