Round 1 deepen: codegraph-zh-tw — advanced examples, deeper theory, diagnostics, challenge exercises

Author: shumingyang-opencode

docs/architecture.html

@@ -119,6 +119,54 @@ <h3>練習：驗收清單</h3>
 </ul>
 </div>
 
+<div class="guide">
+<hr>
+<h2>🔍 進階真實情境 Worked Example：大型 monorepo × 跨服務 trace × MCP</h2>
+<p>前面的範例只在一支 app 內追蹤請求。真實世界更常見的場景是<strong>40+ package 的 monorepo</strong>：前端（TS）、後端 API（Go）、資料處理（Python）混在一起，服務之間靠 HTTP / message queue 溝通。你被要求在大規模 refactor 前產出「跨服務依賴報告」，並把結論交給 AI agent 驗證。</p>
+<div class="term">
+  <div class="term-head"><span class="dot r"></span><span class="dot y"></span><span class="dot g"></span><span class="term-title">monorepo 分析工作流</span></div>
+<pre><code># ① 零設定索引整個 monorepo（副檔名自動分派語言）
+codegraph init
+
+# ② 先看 package 佈局，找服務邊界
+codegraph files --max-depth 2
+
+# ③ 鎖定跨服務的關鍵符號
+codegraph query "PaymentGateway" --kind class
+
+# ④ 一次 explore 拉出跨服務完整呼叫路徑（含 dynamic-dispatch hop）
+codegraph explore "checkout 從 web → payment → notification 的完整路徑"
+
+# ⑤ 量化 refactor 的 blast radius
+codegraph impact PaymentGateway --depth 3
+
+# ⑥ 把結果丟進 MCP agent session 驗證
+#    agent 用 codegraph_explore 就能自己追問「改 payment 會影響哪些服務」</code></pre>
+</div>
+<p><strong>為什麼走這條路徑</strong>：單一入口 + 零設定讓「一個 index 涵蓋整個 monorepo」成立；explore 的呼叫路徑包含 grep 追不到的 dynamic-dispatch 跳躍（callback、interface→impl），跨服務 hop 一次可見；impact 的數字直接變成 refactor 的風險清單。用 CLI 產出報告、用 MCP 讓 agent 接手追問——兩者驅動同一個 <code>CodeGraph</code> class，答案一定一致。</p>
+
+<h2>🔬 深入原理擴充</h2>
+<p><strong>內部架構：facade 只是門面。</strong><code>CodeGraph</code> class 是典型 facade pattern——它不做事，只把四層接起來：<code>files → ExtractionOrchestrator（Rust kernel 一次跨界）→ DB（SQLite/WAL/FTS5）→ ReferenceResolver（多輪 pass）→ GraphTraverser → ContextBuilder</code>。關鍵在「<strong>一個檔案只跨界一次</strong>」：Rust kernel 把 tree-sitter grammar 編進 binary，整份檔案一次解析完再回傳結果，而不是每個符號都穿越一次 N-API 邊界——1000 檔專案就是 1000 次跨界 vs 數萬次的差別。</p>
+<div class="callout warn"><strong>大家以為分析正確但其實有誤</strong>：很多人以為「Rust kernel = 20 份獨立的完整解析器」。實際上 kernel 是<strong>共享的 tree-sitter runtime + 每語言一份 walker 規格</strong>；而且「解析成什麼節點」的規格<strong>同時存在 TS 可攜引擎與 Rust 兩邊</strong>，靠「逐位元組驗證」保證一致——Rust 只負責「快」，不負責「決定語意」。另一個常被誤解的假設是「pipeline 是同步直線」：其實 resolver 有多輪 pass、WAL checkpoint 有背景 valve、重解析在 worker pool——看到「index 花了 1.7s」不是單執行緒跑完的。</div>
+
+<h2>🩺 診斷式疑難排解表</h2>
+<table>
+  <tr><th>症狀</th><th>可能原因</th><th>解決方案</th></tr>
+  <tr><td>某語言的檔案永遠不進圖</td><td>走 per-file fallback 且 grammar 載入失敗</td><td><code>codegraph status</code> 看 error 計數；重跑 <code>codegraph init</code> 重載 grammars</td></tr>
+  <tr><td>查詢結果與磁碟內容不符</td><td>索引過期（watcher 未在跑）</td><td><code>codegraph sync</code>，或確認 daemon 有啟動</td></tr>
+  <tr><td>install 後新 agent 沒被列</td><td>registry 沒註冊，或 target 的 detect() 回 false</td><td>檢查 <code>targets/registry.ts</code> 與該 target 的偵測邏輯</td></tr>
+  <tr><td>跨服務 trace 斷在 route 節點</td><td>framework resolver 沒認得該路由寫法</td><td>確認寫法符合慣例；檢查 <code>runPostExtract</code> 是否重跑 detect</td></tr>
+  <tr><td>index 卡住很久不動</td><td>大目錄未排除，或 WAL 延遲被關</td><td>排除 <code>node_modules</code>/<code>dist</code>；確認 <code>CODEGRAPH_NO_WAL_DEFER</code> 未設</td></tr>
+</table>
+
+<h2>🧩 進階挑戰題</h2>
+<ol>
+  <li>假設你要新增「module」節點層級，讓 explore 能回傳「某 package 的邊界摘要」。從 schema.sql、extraction、resolution 到 context 格式，各列一處你必須改動的地方。</li>
+  <li>解釋「一個檔案只跨界一次」為何是效能關鍵。對 1000 檔、每檔平均 30 個符號的專案，「每檔一次」vs「每符號一次」的跨界次數各是多少？</li>
+  <li>給定「查某 symbol 的 callers 回傳空結果」，列出至少三種可能原因，並為每一種寫出對應的驗證指令。</li>
+</ol>
+</div>
+
 <footer>
   <div>這是 <a href="https://github.com/colbymchenry/codegraph">colbymchenry/codegraph</a> 的非官方繁體中文教學站。</div>
   <div>內容 © <a href="https://github.com/colbymchenry/codegraph">Colby Mchenry</a>（MIT）· 本站與 Colby Mchenry 無關 · 對齊上游 main @ c6aaa20</div>

docs/auto-sync.html

@@ -122,6 +122,54 @@ <h3>練習：驗收清單</h3>
 </ul>
 </div>
 
+<div class="guide">
+<hr>
+<h2>🔍 進階真實情境 Worked Example：大型 repo 的 debounce 調校 + CI pre-flight sync</h2>
+<p>前面的範例是觀察單一檔案的自動同步。這裡是兩件工程實務：在 <strong>27,000 檔的 Swift compiler repo</strong> 上把 debounce 調到不會「每次儲存都重同步」，以及 sandbox CI 環境的 pre-flight sync。</p>
+<div class="term">
+  <div class="term-head"><span class="dot r"></span><span class="dot y"></span><span class="dot g"></span><span class="term-title">調校工作流</span></div>
+<pre><code># ① 大型 repo：把 debounce 調大，避免編輯連發觸發多次重同步
+export CODEGRAPH_WATCH_DEBOUNCE_MS=8000    # 合法範圍 [100ms, 60s]
+
+# ② 排除 build 產物，減少 watcher 雜訊
+#    (swift build 產物、.build/ 已是預設排除，確認無誤)
+
+# ③ 驗證 pending 狀態
+codegraph status
+# ### Pending sync:
+#   .build/...          (excluded)   ← 確認排除生效
+#   Sources/Model.swift (modified 2s ago)
+
+# ④ sandbox / CI（watcher 常不可用）：pre-flight sync
+codegraph sync   # 在 agent 工作前先對帳一次
+
+# ⑤ 大型 repo 單檔編輯的預期成本
+#    中型 repo ~0.3s；27,000 檔 Swift repo ~0.4s</code></pre>
+</div>
+<p><strong>為什麼走這條路徑</strong>：debounce 是「新鮮度 vs 重同步成本」的旋鈕——repo 越大、編輯越密集，旋鈕越該調大；CI 沒有長駐 watcher，所以「手動 sync 一次」是成本最低的對帳。兩者都是「把三層機制用對」的實例：watcher 處理互動編輯、catch-up 處理離線編輯、pre-flight sync 處理沒有 watcher 的環境。</p>
+
+<h2>🔬 深入原理擴充</h2>
+<p><strong>內部架構：三層各自防住的缺口。</strong>① watcher（FSEvents/inotify/RDCW）捕抓 create/modify/delete，debounce 折疊編輯連發；② staleness banner 誠實標出「debounce 窗口內被引用但未入索引」的檔案——agent 看到 <code>⚠️</code> 會先 Read 再作答（已用 Claude Code 驗證）；③ connect-time catch-up 在 MCP server 重連時，用 <code>(size, mtime) + content-hash</code> 對帳，吸收「沒有 server 期間」的編輯（git pull、別的 editor、前一個 session）。<strong>sync 不是「重新掃描」</strong>：它只載變動檔的 unresolved refs、重試先前 failed 的 refs（#1240）、修復定義增減造成的 stale 邊（CG-33 rebind）、清掃被 kill 的解析 pass 留下的 orphan rows（#1187）。</p>
+<div class="callout warn"><strong>大家以為分析正確但其實有誤</strong>：以為 debounce 是固定 2 秒。實際是<strong>可調 [100ms, 60s]</strong>，且調完立刻生效。另一個誤解：以為「auto-sync 就保證圖永遠新鮮」。在 debounce 窗口內圖就是舊的——所以第三層（staleness banner）才存在，它的存在正是「圖可能舊」的誠實承認。</div>
+
+<h2>🩺 診斷式疑難排解表</h2>
+<table>
+  <tr><th>症狀</th><th>可能原因</th><th>解決方案</th></tr>
+  <tr><td>新檔一直顯示 pending</td><td>watcher 未啟動（sandbox）或 debounce 過大</td><td>檢查 <code>CODEGRAPH_NO_DAEMON</code>；縮小 debounce 或手動 sync</td></tr>
+  <tr><td>sync 很快但圖還是錯</td><td>failed-ref 重試沒成功</td><td>再 <code>codegraph sync</code> 一次，或 <code>codegraph index --force</code></td></tr>
+  <tr><td>編輯連發造成多次重同步</td><td>debounce 太小（如 100ms）</td><td>調高 <code>CODEGRAPH_WATCH_DEBOUNCE_MS</code></td></tr>
+  <tr><td>停機期間的編輯沒進圖</td><td>connect-time catch-up 未觸發</td><td>重連後第一次呼叫應吸收；確認 daemon 有重啟</td></tr>
+  <tr><td>大型 repo 索引吃滿 CPU</td><td>build 產物沒排除、debounce 過小</td><td>排除 build 目錄 + 調大 debounce</td></tr>
+</table>
+
+<h2>🧩 進階挑戰題</h2>
+<ol>
+  <li>debounce 的 trade-off：太大 → agent 拿舊答案；太小 → 每次儲存都重同步。依 repo 規模與編輯頻率，寫出你的選擇規則。</li>
+  <li>catch-up 用 <code>(size, mtime) + content-hash</code> 對帳，為何不直接全量 re-index？content-hash 碰撞的風險如何被吸收？</li>
+  <li>畫一張「編輯 → debounce 窗口 → sync → agent 查詢」的時序圖，標出 staleness banner 會被觸發的窗口，並說明 agent 此時該怎麼應對。</li>
+</ol>
+</div>
+
 <footer>
   <div>這是 <a href="https://github.com/colbymchenry/codegraph">colbymchenry/codegraph</a> 的非官方繁體中文教學站。</div>
   <div>內容 © <a href="https://github.com/colbymchenry/codegraph">Colby Mchenry</a>（MIT）· 本站與 Colby Mchenry 無關 · 對齊上游 main @ c6aaa20</div>

docs/benchmarks.html

@@ -107,6 +107,55 @@ <h3>練習：驗收清單</h3>
 </ul>
 </div>
 
+<div class="guide">
+<hr>
+<h2>🔍 進階真實情境 Worked Example：在自己 repo 重跑最小 A/B + 殘留上下文決策</h2>
+<p>前面的範例是「理解官方方法論」。這裡是實際應用：你的團隊想在自己的中型 repo 上確認「CodeGraph 值不值得上」，並解決小 context window 的殘留上下文問題——用 20 分鐘跑一個最小但可信的對照。</p>
+<div class="term">
+  <div class="term-head"><span class="dot r"></span><span class="dot y"></span><span class="dot g"></span><span class="term-title">最小 A/B 實作</span></div>
+<pre><code># ① 準備：索引一次
+codegraph init
+
+# ② WITH arm（啟用 CodeGraph）
+claude -p "列出 buildService 的 callers 並解釋影響" \
+  --strict-mcp-config \
+  --mcp-config '{"mcpServers":{"codegraph":{"command":"codegraph","args":["serve","--mcp"]}}}'
+
+# ③ WITHOUT arm（空 MCP config，兩邊都封 CLI）
+claude -p "列出 buildService 的 callers 並解釋影響" \
+  --strict-mcp-config --mcp-config '{}'
+
+# ④ 各跑 4 次取中位數；記錄工具呼叫數、時間、token
+
+# ⑤ 殘留上下文決策：小窗口長 session 用
+CODEGRAPH_MCP_TOOLS=explore,status    # 只留最少工具
+CODEGRAPH_EXPLORE_DEDUP=1             # 同一對話不重送已看過的檔
+#   並在 buildContext 層面限制 maxNodes 避免一次塞爆</code></pre>
+</div>
+<p><strong>為什麼走這條路徑</strong>：官方數字是用 VS Code、Django 那種規模跑出來的，你的 repo 規模不同必須自己量。重點是<strong>守住方法論</strong>（strict MCP config、封 CLI、4 runs 中位數）——只要對照公平，數字縮水也是有用的結論。殘留上下文的調校（dedup + maxNodes + 最少工具）正是把「較大常駐 footprint」壓回可接受的關鍵。</p>
+
+<h2>🔬 深入原理擴充</h2>
+<p><strong>內部架構：為什麼「殘留上下文較多」是真的。</strong>CodeGraph 回傳一坨 dense、逐字元對齊的 payload——它是「處理較少 token」（throughput）的代價。grep-and-read agent 則 churn 很多會被逐出的小結果，所以 window 裡剩下的反而少。兩者同時為真：<strong>處理較少 token 與較大常駐 footprint</strong>。方法論的另一個關鍵是 <strong>CLI 封鎖</strong>：WITHOUT arm 若沒封，agent 會自己找到 CLI 用 Bash 呼叫（官方 28 次跑中 26 次如此），讓「WITHOUT 沒工具」的假設破功。</p>
+<div class="callout warn"><strong>大家以為分析正確但其實有誤</strong>：以為「88% 更少工具呼叫 = token 一定更少」。不一定——<code>residual context</code> 顯示 CodeGraph 反而<strong>多 80%</strong>。它是「省每次查詢的處理量」但「留更多常駐」。另一個誤解：以為這些數字對所有問題普遍成立——其實「成本」欄只對需要 discovery 的架構/影響問題有優勢，簡單問題（Django 13% 省、Gin 打平）幾乎無差。</div>
+
+<h2>🩺 診斷式疑難排解表</h2>
+<table>
+  <tr><th>症狀</th><th>可能原因</th><th>解決方案</th></tr>
+  <tr><td>自己的 A/B 結果波動大</td><td>LLM 非確定性 + 樣本不足</td><td>≥4 runs/arm 取中位數，問題寫死不要變</td></tr>
+  <tr><td>WITHOUT arm 意外變快</td><td>agent 自己找到 CLI 用 Bash 呼叫</td><td>sanitized PATH + PreToolUse hook 封鎖所有 codegraph 呼叫</td></tr>
+  <tr><td>殘留上下文爆量、小窗口撐爆</td><td>dense payload 留在 window</td><td>開 dedup、降 maxNodes、精簡 allowlist</td></tr>
+  <tr><td>成本欄幾乎沒省</td><td>問題本身不需 discovery</td><td>換架構/影響類問題；或接受「此類問題無優勢」的結論</td></tr>
+  <tr><td>WITH arm 出現多次 explore</td><td>單一問題被拆多段探索</td><td>檢查問題是否單一聚焦；過於發散會吃掉優勢</td></tr>
+</table>
+
+<h2>🧩 進階挑戰題</h2>
+<ol>
+  <li>解釋「CLI 封鎖」為何是可信度的關鍵。若不封，WITHOUT arm 的「工具呼叫數」會如何被污染？（官方數據：28 次跑中 26 次會偷用 CLI。）</li>
+  <li>throughput（處理的 token/成本）與 residual context（session 結束時 window 剩多少）是兩個相反指標。設計一個能同時呈現兩者的報告格式，讓決策者一眼看懂。</li>
+  <li>為什麼「檔案讀取七個 repo 全歸零」是最強信號？它比時間、成本少了哪些干擾因子？</li>
+</ol>
+</div>
+
 <footer>
   <div>這是 <a href="https://github.com/colbymchenry/codegraph">colbymchenry/codegraph</a> 的非官方繁體中文教學站。</div>
   <div>內容 © <a href="https://github.com/colbymchenry/codegraph">Colby Mchenry</a>（MIT）· 本站與 Colby Mchenry 無關 · 對齊上游 main @ c6aaa20</div>

docs/cli.html

@@ -203,6 +203,51 @@ <h3>練習：驗收清單</h3>
 </ul>
 </div>
 
+<div class="guide">
+<hr>
+<h2>🔍 進階真實情境 Worked Example：On-call 快速定位</h2>
+<p>前面的範例是 CI/CD 整合。換一個完全不同場景：凌晨 on-call，production 結帳失敗。你只有一個 terminal，目標是<strong>在幾分鐘內從「現象」走到「根因」</strong>，且每一步都能留下可稽核的證據。</p>
+<div class="term">
+  <div class="term-head"><span class="dot r"></span><span class="dot y"></span><span class="dot g"></span><span class="term-title">on-call 工作流</span></div>
+<pre><code># ① 從錯誤訊息反向找：誰在呼叫 checkout？
+codegraph callers checkout --json | jq '.callers[].symbol'
+
+# ② 用 explore 一次拿「結帳鏈」的原始碼 + 呼叫路徑
+codegraph explore "checkout 失敗的完整呼叫鏈"
+
+# ③ 鎖定可疑函式，看它呼叫誰（callees）
+codegraph callees validatePayment --limit 20
+
+# ④ 評估「改這裡」的爆炸半徑
+codegraph impact validatePayment --depth 2
+
+# ⑤ 找受影響的測試，確認修復不會漏測
+git diff --name-only | codegraph affected --stdin --quiet</code></pre>
+</div>
+<p><strong>為什麼走這條路徑</strong>：on-call 的時間成本極高，<code>explore</code> 一次把「相關符號原始碼 + 呼叫路徑 + blast radius」全部拿回，取代幾十次 grep+Read；<code>--json</code> 讓每一步都能接進 jq/shell 管線自動化；最後用 <code>affected</code> 把「我要改什麼」轉成「我要跑哪些測試」——這正是把圖譜當「可查詢的結構」而非「搜尋結果」來用。</p>
+
+<h2>🔬 深入原理擴充</h2>
+<p><strong>內部架構：CLI 是薄殼。</strong>每個子指令的實作都極薄——把參數整理好 → 呼叫 <a href="code/main.html">CodeGraph class</a> 對應方法 → 排版輸出。<code>explore</code> 與 <code>node</code> 的輸出<strong>與 MCP 工具逐字元一致</strong>：它們就是同一段組裝邏輯的 CLI 入口（非 MCP harness 的對等介面）。查詢類指令都帶 <code>--json</code>，這是與腳本世界接軌的正式契約。<code>node-version-check.ts</code> 在 Node &lt;20 或 ≥25 時硬性退出——CLI/MCP 跑在 self-contained bundle runtime（不受影響），從 source 跑才需要 Node ≥22.5（node:sqlite）。</p>
+<div class="callout warn"><strong>大家以為分析正確但其實有誤</strong>：以為 <code>codegraph query</code> 是「全文搜尋」（像 grep 一樣搜檔案內容）。實際上是 <strong>FTS5 名稱/符號搜尋</strong>——比對的是 symbol 的 name 與 qualified_name，不是檔案內文。想找「誰用了這個字串」要換工具；想找「這個符號在哪、誰碰它」才用 query/explore。另一個誤解：以為 uninstall 會刪掉 CLI，其實 <code>--keep-cli</code> 只移除 agent 設定。</div>
+
+<h2>🩺 診斷式疑難排解表</h2>
+<table>
+  <tr><th>症狀</th><th>可能原因</th><th>解決方案</th></tr>
+  <tr><td><code>codegraph affected --stdin</code> 沒輸出</td><td>管線上游沒餵入檔名，或 depth 太小</td><td>先 <code>echo src/a.ts | codegraph affected --stdin</code> 測管線；再加大 <code>--depth</code></td></tr>
+  <tr><td><code>--json</code> 輸出被 jq 解析失敗</td><td>stderr 與 stdout 混雜，或引號沒包好</td><td>加 <code>2&gt;/dev/null</code>；用單引號包 filter</td></tr>
+  <tr><td>剛裝完卻 <code>command not found</code></td><td>npm global bin 不在 PATH</td><td>檢查 <code>npm prefix -g</code>/bin 並加入 PATH</td></tr>
+  <tr><td><code>codegraph version</code> 與預期不符</td><td>多份安裝（global + local）打架</td><td><code>which -a codegraph</code> 找出全部，保留一份</td></tr>
+  <tr><td><code>node-version-check</code> 硬退出</td><td>Node &lt;20 或 ≥25</td><td>用 bundle runtime，或用 nvm 切到支援版本</td></tr>
+</table>
+
+<h2>🧩 進階挑戰題</h2>
+<ol>
+  <li>寫一行 bash：把 <code>git diff --name-only</code> 的結果接給 <code>codegraph affected --stdin --quiet</code>，且只在有輸出時執行 vitest。說明為什麼 <code>--quiet</code> 是關鍵。</li>
+  <li>假設 <code>codegraph callers foo --json</code> 的輸出要送進 jq 統計 caller 數量。寫出 filter；若結果是 0，用哪個指令進一步診斷？</li>
+  <li>為什麼 explore 與 node 的輸出要和 MCP 工具「逐位元組一致」？列出至少兩類依賴這個保證的 consumer。</li>
+</ol>
+</div>
+
 <footer>
   <div>這是 <a href="https://github.com/colbymchenry/codegraph">colbymchenry/codegraph</a> 的非官方繁體中文教學站。</div>
   <div>內容 © <a href="https://github.com/colbymchenry/codegraph">Colby Mchenry</a>（MIT）· 本站與 Colby Mchenry 無關 · 對齊上游 main @ c6aaa20</div>