1. 数据新鲜度检查
在执行任何检索之前，应先通过 gitcrawl doctor --json 检查本地归档数据的新鲜度，确保后续查询基于足够新的数据。
2. 归档检索（本地优先）
Gitcrawl 提供多种本地检索命令，无需实时调用 GitHub API：
| 命令 | 用途 |
|---|---|
gitcrawl threads |
按编号批量获取 Issue/PR 线程 |
gitcrawl neighbors |
获取与指定 Issue/PR 关联的相邻线程 |
gitcrawl search |
按关键词搜索 Issue，支持按状态（open/closed）筛选 |
gitcrawl clusters |
识别相似的 Issue 聚类，支持按规模排序和最小规模过滤 |
gitcrawl cluster-detail |
查看某个聚类的详细信息 |
所有检索命令均支持 --json 输出，便于程序化处理。
3. PR 状态同步（gh-shim）
在做出合并/变更决策前，Gitcrawl 提供了 gitcrawl gh 子命令来获取 PR 的最新状态：
-
gitcrawl gh pr status --compact—— 查看 PR 状态摘要 -
gitcrawl gh pr view --json—— 查看 PR 的详细 JSON 信息（包括编号、标题、状态、URL、是否草稿、头部分支和 SHA） -
使用
--live标志可强制获取实时数据
4. 实况校验（live gh）
在实际执行变更操作（评论、打标签、关闭、重新打开、合并、提交 PR 审核）之前，必须使用原生的 gh 命令行工具进行实时校验：
gh pr view <number> --json number,title,state,mergedAt,body,files,comments,reviews,statusCheckRollup
gh issue view <number> --json number,title,state,body,comments,closedAt三、主要用途
1. Issue/PR 分类与筛选（Triage）
在大量 Issue/PR 中快速定位候选对象——先查本地归档获取上下文，仅在需要做变更决策时才调用实时 API。
2. 重复 Issue 检测与管理
通过 clusters 和 cluster-detail 命令发现语义相似的 Issue 聚类，便于合并或归类处理。
3. PR 合并前的状态确认
在合并 PR 之前，通过 gitcrawl gh 快速确认 PR 的最新状态（是否可合并、是否草稿、头部分支等），避免基于过期数据做出错误决策。
4. 减少 API 调用
通过本地归档优先的策略，显著降低对 GitHub API 的实时调用频率，提升检索速度，尤其适合需要批量处理大量 Issue/PR 的场景。
四、标准工作流程
1. gitcrawl doctor --json → 检查归档新鲜度
2. gitcrawl search / threads / clusters → 在本地归档中检索候选
3. gitcrawl gh pr view → 获取 PR 最新状态（缓存优先）
4. gitcrawl gh --live pr view → 仅在需要实时数据时使用 --live
5. gh pr view / gh issue view → 在执行任何变更操作前，用原生 gh 做最终实况校验
6. 执行变更操作（合并、关闭、打标签等）五、重要原则与注意事项
-
报告完整性：在输出结果时，必须报告绝对日期、仓库名称、Issue/PR 编号、聚类 ID 以及数据来源缺口。
-
相似性≠操作依据：不得仅凭相似性就执行关闭或打标签操作——必须确保意图匹配，并经过实况验证。
-
变更前必须实况校验：在评论、打标签、关闭、重新打开、合并或提交 PR 审核之前，必须使用原生
gh命令进行实时数据核对。
六、总结
Gitcrawl 是一个本地优先的 GitHub 归档查询与 PR 状态同步工具，通过“先归档后实时”的策略，在保证数据准确性的前提下大幅提升 Issue/PR 检索效率。它特别适合需要高效处理大量 GitHub Issue/PR 的开发者、开源项目维护者或自动化 triage 流程使用。
