GitHub 快取衛生
目標:先透過 gitcrawl 與 gh shim 回答常見的 GitHub 讀取問題,只有在需要最新資料或有寫入需求時才花費即時 GitHub API 呼叫。
預設路徑
正常使用 gh。在 Peter 的機器上,它預期是 gitcrawl 驅動的 shim,因此支援的讀取作業可在本地或快取中完成,無需變更指令。
優先使用這些本地/快取讀取:
gitcrawl sync owner/repo --numbers 123 --with pr-details
gh search issues "<terms>" -R owner/repo --state open --json number,title,state,url,updatedAt,labels,author
gh search prs "<terms>" -R owner/repo --state open --json number,title,state,url,updatedAt,isDraft,author
gh issue list -R owner/repo --state open --author user --assignee user --label bug --json number,title,url
gh pr list -R owner/repo --state open --author user --label dependencies --json number,title,url
gh issue view 123 -R owner/repo --json number,title,state,body,comments,labels,url
gh pr view 123 -R owner/repo --json number,title,state,body,comments,labels,files,commits,statusCheckRollup,url
gh pr checks 123 -R owner/repo --json name,state,detailsUrl,workflow
gh run list -R owner/repo --branch branch-name --json databaseId,workflowName,status,conclusion,url
gh pr diff 123 -R owner/repo --patch
使用精確的引用與窄化的欄位。避免在單一 gh issue view 上進行廣泛迴圈,當一個 gh search 或 gh issue list --json ... 就能回答初步問題時,請直接使用後者。
對於 CI,請避免密集的 gh run list / gh run view 輪詢迴圈。推送或工作流程觸發後,先識別出一個確切的執行,再以回退策略進行輪詢。只在偵測到失敗的作業或用戶明確要求日誌時,才拉取完整的日誌。已完成風格的 gh run view --log、--log-failed 以及常見的 Actions REST 日誌端點會由 gitcrawl 較長時間快取,而執行狀態則保持短效期。
新鮮度
本地答案適用於探索、重複搜尋、舊討論回顧、作者/標籤分類,以及「是否已經有相關的 issue/PR?」的檢查。
在以下情況使用即時呼叫:
- 撰寫、評論、關閉、合併、重新執行或編輯時
- 在維護者操作前檢查最終當前狀態
- 推送後驗證 CI 狀態
- 本地結果遺失或明顯過時
- 用戶要求最新/即時狀態
進行 PR 審查時,如果你知道會反覆檢查檔案、提交、檢查或執行摘要,建議先使用 gitcrawl sync owner/repo --numbers <n> --with pr-details 一次灌入精確的 PR 細節。gh shim 可在遺漏時自動灌入一個精確的 PR(使用 GITHUB_TOKEN 或 gh auth token);明確的灌入能讓意圖與成本更清楚。
寫入後,只進行一次針對性的回讀,不要進行廣泛的重新掃描。
XCache
當懷疑速率限制時,檢視快取行為:
gh xcache stats
gh xcache keys
gh xcache gc
在 gh xcache stats --json 中檢視 backend_misses_by_command 與 backend_misses_by_route,然後再新增新的即時 GitHub 迴圈。這些對應表會顯示哪些指令形狀仍在逃脫快取。
只有當過時的快取回讀誤導了決策時,才使用 gh xcache flush。
若要進行僅限本地的驗證,可暫時讓後端無法使用,對單一指令:
GITCRAWL_GH_PATH=/tmp/no-real-gh gh search issues "<terms>" -R owner/repo --json number,title,url
代理程式禮儀
按儲存庫與狀態批次處理問題。重複使用已經在對話中列印過的資料。在 CI 輪詢時退讓;僅對失敗的執行或正在審查的精確執行檢查日誌。除非正在診斷 shim 本身,否則不要以 /opt/homebrew/opt/gh/bin/gh 繞過 shim。