GitHub Cache Hygiene
目标:首先优先通过 gitcrawl 和 gh 垫片回答常见的 GitHub 读取问题,仅在需要数据新鲜度或写入操作时才发起实时的 GitHub API 调用。
默认路径
正常使用 gh。在 Peter 的机器上,它预期被设置为由 gitcrawl 支持的垫片,因此支持的读取操作可以在本地或缓存中得到回答,而无需更改命令。
优先选择这些本地/缓存的读取操作:
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 更长时间地缓存,而运行状态的生命周期则较短。
新鲜度
本地答案适用于发现、重复搜索、旧线程审查、作者/标签分类,以及“该问题/PR 是否已经存在?”的检查。
在以下情况使用实时调用:
- 写入、评论、关闭、合并、重新运行或编辑时
- 在执行维护者操作前检查最终当前状态
- 推送后验证 CI 状态
- 本地结果缺失或明显过时时
- 用户要求最新/实时状态时
对于 PR 审查,当你知道会反复检查文件、提交、检查项或运行摘要时,优先精确地一次性使用 gitcrawl sync owner/repo --numbers <n> --with pr-details 来充实 PR 的详细信息。gh 垫片可以在未命中时自动充实一个确切的 PR,使用 GITHUB_TOKEN 或 gh auth token;显式地充实则能让意图和成本更加清晰。
写入操作后,进行一个有针对性的读取回查,而不是全盘重新扫描。
XCache
当怀疑速率限制时,检查缓存行为:
gh xcache stats
gh xcache keys
gh xcache gc
在添加新的实时 GitHub 循环之前,先查看 gh xcache stats --json 中的 backend_misses_by_command 和 backend_misses_by_route。这些映射显示了哪些命令形态仍然未被缓存命中。
仅当过时的缓存回退读取误导了决策时,才使用 gh xcache flush。
如需仅在本地进行验证,可以暂时使后端对单个命令不可用:
GITCRAWL_GH_PATH=/tmp/no-real-gh gh search issues "<terms>" -R owner/repo --json number,title,url
代理行为规范
按仓库和状态批量提问。复用在会话中已经打印过的数据。降低 CI 轮询频率;仅对失败的运行或当前正在审查的确切运行收集日志。除非是为了诊断垫片本身,否则不要通过 /opt/homebrew/opt/gh/bin/gh 绕过该垫片。