github-cache-hygiene

GitHub 缓存卫生

目标：先在本地 Gitcrawl 存档中查找，再使用现有的 Octopool 支持的 gh shim 获取当前 GitHub 元数据并执行已授权的写入操作。

默认路径

先读取本地存档：

gitcrawl search prs "<terms>" -R owner/repo --state open --json number,title,url

gitcrawl threads owner/repo --numbers 123 --include-closed --json

--include-closed 会将已关闭或已合并的候选项纳入范围。存档状态可能滞后于 GitHub，不能作为当前状态的证明。

需要当前元数据时，再使用裸 PATH gh。在 Peter 的机器上，预期它是由 Octopool 支持的 shim，因此受支持的 JSON 读取会共享整个集群的缓存，且不会更改身份验证或命令路由：

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,labels,url
gh pr view 123 -R owner/repo --json number,title,state,url,headRefName,headRefOid
gh pr checks 123 -R owner/repo --json name,state,bucket,link
gh run list -R owner/repo --branch branch-name --json databaseId,workflowName,status,conclusion,url
gh pr diff 123 -R owner/repo --patch

使用精确的引用和精简的字段。--json 用于选择输出，而非读取器身份。 在 Octopool 0.7.1 中，PR 的 mergeStateStatus 和 issue 的 comments 会使整个字段集合改用原生 gh。PR 评论、审查和提交导出也仍由原生 gh 处理。需要时请求这些字段；对于不使用这些字段的描述性读取，则省略它们。切勿仅为提高缓存复用率而移除合并或审查门槛，也不要把一个决策拆成分别定时的多次读取，除非保留其一致性约定。

受支持的人类可读输出和已识别的落地页 GraphQL 投影也可以通过中继处理。受支持的 gh api --paginate/--slurp 和 --hostname github.com 读取不一定需要绕过 Octopool。遵循已安装版本的 CLI 约定和实际观察到的路由；仅使用 gh 的绝对路径并不能证明它是原生二进制文件。

避免使用宽泛的循环，例如对每条结果分别执行一次 gh issue view；如果一次 gh search 或 gh issue list --json ... 就能回答初步问题，就应优先使用它。

对于 CI，避免紧密循环轮询 gh run list / gh run view。推送或分派工作流后，先确定一个精确的运行实例，然后使用精确运行实例监视器，或按 30 秒、60 秒、120 秒的间隔轮询该运行实例。 检查预期的 head SHA 和运行尝试次数。即使上游刚刚获取了数据，宽泛或经过筛选的列表也可能滞后；其中最新的一行并不是最终的 CI 证据。仅在失败或收到明确请求后获取日志，且只获取一次。重用先前的输出，不要再次读取已完成的运行。

新鲜度

本地答案适用于发现、重复项搜索、审阅旧讨论串、作者/标签分类，以及“是否可能已经存在 issue/PR？”之类的检查。

以下情况使用实时调用：

• 写入、评论、关闭、合并、重新运行或编辑
• 执行维护者操作前检查最终当前状态
• 推送后验证 CI 状态
• 本地结果缺失或明显过时
• 用户要求获取最新/实时状态

仅当本地存档需要文件、提交、检查或运行摘要以便重复审阅时，才获取精确 PR 的详细信息：

gitcrawl sync owner/repo --numbers 123 --with pr-details

此刷新会消耗 GitHub API 调用并更新 Gitcrawl 的存档，但不会更新 Octopool 独立的 gh 缓存。裸 gh 读取不会自动更新 Gitcrawl 存档。

gitcrawl gh 已停用，执行后会以退出码 2 结束，并显示迁移说明。请将这些用法替换为先读取存档，再使用裸 gh；该说明并不表示身份验证失败。请勿运行 octopool login，也不要更改令牌、身份验证、PATH 或配置，或绕过现有 shim 来修复已停用的命令。

写入后，只进行一次有针对性的实时回读，不要进行宽泛的重新扫描。 对中继读取使用 OCTOPOOL_FRESH=1 或显式设置 Cache-Control: max-age=0。 state、headRefOid 和 statusCheckRollup 等受支持的 PR 决策字段会自动重新验证。title 等描述性字段可以复用缓存。

gh api --include 使用原生 gh 和调用方凭据。它会改变身份、配额以及潜在的可见性；它不是新鲜度开关，也无法保证解决过时列表的问题。需要基于调用方身份的权限和合并决策，应沿用其要求的身份路径。中继返回的新鲜 MISS 和过时列表本身并不能证明缓存复用已过期；重新验证后的 HIT 也不能证明完全没有请求上游。

Octopool

怀疑存在速率限制时，检查缓存行为：

octopool whoami
octopool health
octopool stats --since 1h
octopool stats --since 24h --json

优先查看已缓存且符合条件的响应数与符合条件的请求数之比。保留 UTC 时间窗口、分子、分母、未命中、绕过和合并请求数。在将变化归因于某个因素之前，先比较路由/客户端构成、明确的新鲜度和延迟。这些是响应复用指标，并非 GitHub 配额节省量。池总计涵盖所有调用方，而客户端表仅涵盖经过身份验证的调用方。原生 GraphQL 和直接客户端不在中继指标范围内；未出现在有界样本中，并不能证明安装已损坏。

检查实际执行上下文。主机 shim 可正常工作，但容器可能使用单独的原生只读包装器。保留该包装器的允许列表和凭据边界；切勿挂载主机的变更凭据来扩大缓存覆盖范围。

仅对有界且已知受支持的中继读取操作使用 OCTOPOOL_NO_FALLBACK=1。它会阻止从中继切换到原生方式，但明确不受支持的命令仍可直接委派。因此，仅凭成功并不能证明所有操作都经过中继。应将其与已知受支持的命令以及观察到的路由/缓存证据配合使用。单独的原生包装器可能完全忽略此变量。不要全局设置它；变更操作和不受支持的读取仍需要真正的 gh。

若要仅验证中继：

OCTOPOOL_NO_FALLBACK=1 gh api repos/owner/repo --jq .full_name

Agent 礼仪

按仓库和状态批量整理问题。重复利用会话中已输出的数据。降低 CI 轮询频率；运行失败时只检查一次日志。常规读取和获授权的写入使用不带路径的 PATH gh；让 Octopool 负责回退到真实的 CLI。不要使用真实 gh 的绝对路径或二进制覆盖来绕过 shim，以替代已弃用的 Gitcrawl 配方。