Was macht github-cache-hygiene?
Ziel: Häufige GitHub-Leseanfragen zuerst über gitcrawl und den gh-Shim beantworten; Live-API-Aufrufe nur dort verwenden, wo Aktualität oder Schreibzugriffe wichtig sind.
Standardpfad
gh normal verwenden. Auf Peters Maschinen ist davon auszugehen, dass dies der gitcrawl-gestützte Shim ist, sodass unterstützte Lesevorgänge ohne Befehlsänderung lokal oder zwischengespeichert beantwortet werden können.
Diese lokalen/zwischengespeicherten Lesevorgänge bevorzugen:
gitcrawl sync owner/repo --numbers 123 --with pr-details
gh search issues "<Begriffe>" -R owner/repo --state open --json number,title,state,url,updatedAt,labels,author
gh search prs "<Begriffe>" -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
Exakte Refs und enge Felder verwenden. Breite Schleifen wie ein einzelnes gh issue view pro Ergebnis vermeiden, wenn ein einzelner gh search oder gh issue list --json ... die erste Frage beantworten kann.
Für CI: Vermeide enge gh run list/gh run view Polling-Schleifen. Nach einem Push oder Workflow-Dispatch identifiziere einen exakten Run und frage ihn mit Backoff ab. Vollständige Logs nur für fehlgeschlagene Jobs oder wenn der Benutzer explizit nach Logs fragt, abrufen. Abgeschlossene gh run view --log, --log-failed und gängige REST-Log-Endpunkte werden von gitcrawl länger zwischengespeichert, während der Run-Status kurzlebig bleibt.
Aktualität
Lokale Antworten eignen sich für Entdeckung, Duplikatsuche, Überprüfung alter Threads, Autor/Label-Triage und Überprüfungen „Gibt es wahrscheinlich bereits ein Issue/PR?“.
Verwende einen Live-Aufruf, wenn:
- Schreiben, Kommentieren, Schließen, Zusammenführen, Neuausführen oder Bearbeiten
- Überprüfung des endgültigen aktuellen Status vor einer Maintainer-Aktion
- Überprüfung des CI-Status nach einem Push
- das lokale Ergebnis fehlt oder offensichtlich veraltet ist
- der Benutzer nach dem neuesten/aktuellen Zustand fragt
Für PR-Reviews: Bevorzuge das genaue Hydrieren von PR-Details einmalig mit gitcrawl sync owner/repo --numbers <n> --with pr-details, wenn bekannt ist, dass Dateien, Commits, Checks oder Run-Zusammenfassungen wiederholt überprüft werden. Der gh-Shim kann bei Fehltreffer automatisch einen exakten PR hydrieren, indem er GITHUB_TOKEN oder gh auth token verwendet; explizite Hydrierung macht Absicht und Kosten klarer.
Nach einem Schreibvorgang: Ein zielgerichtetes Rücklesen, kein breites Rescan.
XCache
Überprüfe das Cache-Verhalten bei Verdacht auf Ratenbegrenzungen:
gh xcache stats
gh xcache keys
gh xcache gc
backend_misses_by_command und backend_misses_by_route in gh xcache stats --json lesen, bevor neue Live-GitHub-Schleifen hinzugefügt werden. Diese Maps zeigen, welche Befehlsformen den Cache noch umgehen.
gh xcache flush nur verwenden, wenn eine veraltete zwischengespeicherte Fallback-Lesevorgang eine Entscheidung beeinträchtigt.
Für einen rein lokalen Nachweis kann das Backend vorübergehend für einen einzelnen Befehl deaktiviert werden:
GITCRAWL_GH_PATH=/tmp/no-real-gh gh search issues "<Begriffe>" -R owner/repo --json number,title,url
Agenten-Etikette
Fragen nach Repository und Status bündeln. Bereits in der Sitzung ausgegebene Daten wiederverwenden. CI-Polling zurückfahren; Logs nur für fehlgeschlagene Runs oder den genauen Run unter Überprüfung einsehen. Den Shim nicht mit /opt/homebrew/opt/gh/bin/gh umgehen, es sei denn, der Shim selbst wird diagnostiziert.