run-github-scout

GitHub Repo Scout

针对具体用户需求，自适应地发现并筛选候选 GitHub 仓库。默认交付内容是在对话中提供一份基于仓库证据的 Markdown 候选清单。更深入的比较、功能矩阵和 HTML 导出都是可选的末期分支，绝非默认内容。

这项技能的设计精简务实，与语料研究截然不同：没有文件夹树、没有波次分发、没有 MAX-N 上限，也不编写模板。

何时使用此技能

遇到以下表述时触发：

• “为 Y 找到最佳开源 X” / “找一些能……的仓库”
• “为……筛选 GitHub 项目” / “哪些仓库适合这套技术栈／使用场景？”
• “GitHub 上 owner/repo 的替代方案” / “类似于……的仓库”
• “比较适用于……的 GitHub 仓库” / “推荐一个能……的库”
• “适用于……的 GitHub 托管工具／SDK／CLI” / “适用于……的 OSS”
• “确认这个仓库是不是我以为的那个”（先验证再侦察）

不要在以下情况使用此技能

• 问题是单个技术决策，或版本／API／CVE／定价查询，且不涉及发现仓库 → 使用 run-research。
• 用户需要一份涵盖 5 个以上实体的多文件市场／类别语料，并要求每个实体都有资料包和来源台账 → 使用 run-deep-research。 仓库仍可作为实体——区分依据是语料的形式，而不是主题。
• 候选项不在 GitHub 上（闭源 SaaS、市场应用、仅托管产品）→ 使用 run-research 或 run-deep-research。
• 任务针对代码库本身（阅读此仓库、修复此 Bug、规划这些问题）→ 不要使用此技能。具体来说，规划 Issues 时请直接使用 gh CLI（run-issue-tree 技能已停用）。

避免大多数偏离的五条规则

以下五条上游纪律规则可避免大多数失败。如果有任何规则不熟悉，请先阅读 references/discipline.md。

#	规则	原因
1	用户点名某个事物时，先验证	执行一次 gh search repos 'NAME' --limit 5 即可在寻找替代方案前确认类别。跳过这一步会浪费 3-4 次搜索。
2	根据生态成熟度选择 star 阈值，不要凭直觉	新兴领域（AI agents、MCP）无需设阈值；成熟生态则需要 stars:>500+。阈值不当 = 结果集错误。
3	首轮搜索避免使用 topic:、不加引号的多词 OR、in:readme	这三种方式都容易引入噪声。只有在分类结果证明它们有帮助后才使用。
4	先分类，再深入研究	按类型标记为 Relevant / Maybe / Off-topic 的表格，是阅读任何 README 前必须通过的关卡。跳过这一步就只能靠猜测。
5	硬性上限：深入评估最多 5 个仓库	扩大到 6 个或以上时，必须在提升候选项的当下给出明确的行内理由。

前置条件和固定默认值

项目	默认值
身份验证检查	开展非简单的侦察前，先运行 gh auth status。优先使用经过身份验证的 GH_TOKEN / GITHUB_TOKEN，以获得更高的限制额度。
搜索帮助	gh search repos --help 是受支持 JSON 字段和标志的权威来源。
限流检查	执行大量搜索或深入研究前：`gh api rate_limit --jq '.resources
查询限制	首轮：3-6 个方向。优化：1-4 次查询。深入研究：仅针对排名前 3-5 的仓库。默认 --limit 20。

GitHub 工具使用约定

• 使用 gh search repos 进行发现。
• 仅对入围项目的元数据使用 gh api repos/OWNER/REPO...。
• 仅在 REST/README/搜索结果不足时，使用 gh api graphql 获取排名靠前项目的深入证据。
• 仅当 gh 不可用时，才直接使用 curl。
• 使用 Web/MCP 工具（或 run-research）仅用于补充名称和领域信息；最终的仓库信息以 GitHub 为准。
• gh CLI 本身（run-issue-tree 技能已弃用）也会使用 gh，但其目的是规划/执行 GitHub Issue，而非发现仓库。

速率限制规则：

• 搜索有自己的速率限制桶；切勿无限制地连续发起搜索。
• 优先使用少量且多样的查询，不要反复改写同一查询。
• 如果剩余配额较低，请在元数据/README 证据阶段停止，并说明限制，不要强行继续。
• 将数字写入代码前，先根据官方文档确认 GitHub 当前行为：https://docs.github.com/rest/rate-limit（访问日期：2026-05-09）。

捆绑脚本

相对于此技能目录定位脚本。这些脚本只是便捷工具， 不能替代适配性判断。

脚本	使用场景
scripts/gh-search.sh	从 gh search repos 简洁、可重复地采集 TSV。参见 scripts/gh-search.md。
scripts/score-repos.sh	对采集的行进行轻量信号排序。仅限元数据，不能判断语义适配性。参见 scripts/score-repos.md。

默认立场

• 先筛选入围项目。 默认交付内容是在对话中提供 Markdown 入围清单。
• 先少量搜索，再逐步细化。 从 3-6 个宽泛方向开始，除非结果仍明显不足，否则最多再进行一轮细化搜索。
• 先筛选，再扩展。 查看描述、名称、主题、星标数和近期活动情况后，再考虑新增搜索。
• run-research 是可选项，并非必需。 当仅用 GitHub 搜索结果较少，且名称/领域发现会有所帮助时，再调用它补充搜索分支。内置的 WebSearch 也足以提供少量命名线索。
• 仅对排名靠前的项目进行深入研究。 只有在形成有用的入围清单后，才制作功能矩阵、阅读代码和导出 HTML。

能力检查 — 选择最精简的路径

路径	使用场景	默认工具
仅 GitHub	问题描述明确、类别以仓库为中心，且 GitHub 搜索已找到相关候选项目。	gh search repos、GitHub 网页/API、仓库 README
补充搜索	名称不明确、领域宽泛、类别标签不清，或第一轮 GitHub 搜索结果少或噪声较多。	GitHub 搜索 + run-research（首选）或内置 WebSearch（较轻量的备选）

规则：

• 如果 run-research 和 WebSearch 都不可用，则继续采用仅 GitHub 的路径。
• 如果可以进行网络研究，就用它发现更合适的名称/类别/精选替代方案，然后映射回 GitHub 仓库并在那里进行筛选。
• 切勿要求用户仅为运行此技能而安装研究工具。

默认工作流

0. 用户提及具体对象时先核实

如果用户提到了具体仓库、项目或工具名称，首先要核实该对象是什么，而不是搜索替代方案。只调用一次： gh search repos 'NAME' --limit 5 --sort=stars。确认类别后再继续。

如果该对象与用户所求无关，继续之前应向用户指出这一不匹配。参见 references/discipline.md §2。

仅当用户没有提及具体对象时，才跳过此步骤。

1. 解读请求

在访问 GitHub 前，提取搜索约束：

• 核心问题或要完成的任务
• 必备条件
• 排除项
• 生态系统或语言限制
• 成熟度预期（可用于生产、仍在积极维护、宽松许可证等）
• 已知示例或反例（如果用户提及，请参阅步骤 0）

仅当答案会实质性改变搜索方向时，才提出澄清问题。如果用户的请求已明确指定用例和限制，则完全跳过提问。

2. 选择搜索路径

• 默认使用 仅限 GitHub 路径。
• 如果遇到名称含糊、类别范围过宽导致噪声过多，或社区术语问题，则切换到 增强 路径。
• 仅在需要增强分支时阅读 references/web-augment.md——其中说明了何时以及如何调用 run-research 来发现名称和生态概况。

3. 先进行一轮小规模搜索

从 3-6 个搜索角度 开始，不要列出庞大的假设清单。

最少应包含以下搜索角度：

1. 对用户需求的直接表述
2. 更广泛的类别表述
3. 已知示例或广为人知的替代方案
4. 一个意料之外的命名分支

只有在某项硬性约束很重要时（语言、部署模式、可自托管等），才增加第五或第六个搜索角度。

启动搜索前，按生态成熟度选择 star 阈值。 较新的细分领域（AI Agent、MCP、Agent 编排器）通常不需要阈值——低于 100⭐ 的仓库中也有优质项目。成熟生态（Web 框架、经典 CLI）则需要使用 stars:>500 过滤噪声。矩阵见 references/discipline.md §3。

首轮发现时避免使用 topic:——它会返回垃圾结果。避免使用不带限定条件的多词 OR 查询——这类查询的解析结果含糊。参见 references/discipline.md §4 和 §5。

先使用简短、宽泛的查询。常见的结果收集优先使用 scripts/gh-search.sh；如需精确的搜索模式，请阅读 references/search.md、references/gh-syntax.md 和 references/gh-output.md。

4. 再次搜索前先在内部筛选

将首轮搜索结果视为原始材料，而非最终答案。

任何后续工作开始前，都必须先生成分类表——这是防止偏离方向、深入阅读错误候选项的关卡：

| Repo | Class | Reason | Signals |
|---|---|---|---|
| owner/repo1 | relevant | Direct match for X | 4.2k⭐, pushed 2026-04, MIT |
| owner/repo2 | maybe | Adjacent — wrapper, not engine | 800⭐, active |
| owner/repo3 | off-topic | Tutorial, not implementation | — |

优先使用成本最低的信号进行筛选：

• 仓库名称
• 描述
• 主题
• stars
• 最近活动／推送日期
• 是否已归档
• 是否有许可证

仅对处于边界或潜力较高的候选项阅读 README 简介。 在扩大搜索范围前，从相关和可能相关的仓库中提取更好的术语。

使用 references/dedup-and-rank.md 中的四阶段关卡流程。分类表是必需的；未生成分类表就深入研究，属于未遵守规范（参见 references/discipline.md §8）。在分类过程中，仅将 scripts/score-repos.sh 用作低成本的元数据排序工具；不要让它凌驾于用户适配证据之上。完成首轮分类后，阅读 references/quality-gates.md，以决定是停止、再优化一次、增强搜索，还是深入研究。

5. 进行一轮优化搜索

只有在首轮分类指出缺少什么之后，才进行优化搜索。

适合进行优化搜索的原因：

• 相关仓库太少
• 离题噪声太多
• 用户用语与仓库用语不匹配
• 从候选项的描述或主题中发现了有前景的子类别

优化规则：

• 使用 1-4 条更好的查询，而不是重新搭建一整套搜索流程
• 仅针对观察到的缺口扩大搜索
• 当新搜索大多重复已知仓库时，就停止

可参考 references/search-examples.md 中的示例，了解首轮搜索与优化搜索的循环，包括偏离方向后的恢复模式。

6. 生成默认输出

默认输出是对话中的 Markdown，而非文件。

交付内容：

1. 一段推荐意见或背景说明
2. 使用稳定行结构的精简表格
3. 分组后的候选清单（最适合、值得一看、排除／原因）
4. 最适合 项目的证据包
5. 值得注意的缺口或不确定性

稳定行结构：

| Repo | Fit | Evidence | Signals | Caveat / unknown |
|---|---|---|---|---|
| [owner/repo](https://github.com/owner/repo) | Strong fit for X | README says Y; topics include Z | stars, pushed, license, activity | Not verified: A |

除非 URL 不可用，否则表格中必须包含仓库链接。

对于每个 最适合 的仓库，都要提供简明的证据包：

• 为什么它符合用户的必备条件
• 使用的证据来源：描述、主题、README、API 或代码
• 检查过的低成本质量信号
• 注意事项和未经验证的说法
• 外部状态会变化时，注明最后核查日期

如果用户对 Markdown 候选清单满意，就此停止。

7. 可选地深入评估

只有在 Markdown 候选清单已经有用后，才进行深入评估。深入评估前，请查看 references/quality-gates.md；大多数初步调研到 Markdown 候选清单这一步就应停止。

每个分支只使用最终入选的数据集；不要重新开始调研。

• 轻量深入比较 — 对排名前 3-5 的项目进行并排比较，考察适配度、证据、信号和注意事项
• 代码级评估 — 只评估排名靠前的少数仓库；核实必备功能、README/入门指引、测试/CI 和成熟度风险
• 功能矩阵 — 提供明确的功能覆盖表，并附上证据说明或标注为 unknown
• HTML/导出 — 根据稳定的 Markdown 候选清单生成持久化报告

深度评估最多覆盖 5 个仓库。 要评估 6 个或更多仓库，必须在开始深入评估时给出明确的行内理由，例如：“将 owner/repo6 提升至候选名单，因为它在分类期间出现了可能改变决策的信号。”若无此类理由，则最多评估 5 个。参见 references/discipline.md §10。

如果用户要求生成文件，只能根据最终入选的数据集创建文件。除非用户要求导出或报告输出，否则不要创建 .githubresearch/ 或其他产物目录树。

references/report-template.html 的 HTML 导出数据规范：

• 只有在 Markdown 候选清单稳定后，才生成 HTML。
• 填写 [TOPIC]、[DATE]、[ROW_COUNT]、[RECOMMENDATION]、[SEARCH_PATH_NOTE]、[GAPS_NOTE]。
• 每一行必须提供仓库 URL/名称、适配度、证据、信号、注意事项/未知项。
• 分组说明须来自同一组 Best fits、Worth a look、Ruled out / why 条目。

默认评估规则

默认使用轻量、快速且考虑速率限制的信号：

• 主题/描述/README 与用户需求的匹配度
• 星标数
• 最近活动/推送日期
• 大致的维护者或提交活动
• 是否已归档或禁用
• 是否提供许可证
• README 是否清晰
• 在检测成本较低时，检查是否存在测试或 CI

不要默认采用：

• 作者关注者评分
• 组织声望启发式
• “仅 AI 浪潮期间活跃的作者”这类筛选条件
• 庞大的多指标评分标准
• 对所有候选项目强制逐个进行 GraphQL 或 REST 深度检查

如果用户希望提高置信度，只对排名靠前的少数仓库深入评估。请阅读：

• references/evaluate.md，了解轻量默认流程和深入评估的触发条件
• references/evaluate-rest.md，了解低成本仓库信号
• references/evaluate-graphql.md，了解可选的单仓库深度证据检查
• references/evaluate-code.md，了解可选的代码级检查

编排规则

默认执行模式：精简混合模式。

• 主 Agent 负责解析意图、制定搜索策略、筛选和综合。
• 在有帮助时批量处理或并行执行查询，但应由主 Agent 集中推理。
• 子 Agent 仅用于：范围极大的项目；用户明确要求深入调研；可选的功能矩阵生成；排名前 N 的代码级审查。
• 如果缺少网页补充信息并因此派出子 Agent，该子 Agent 的任务说明中应包含 run-research 技能规范（这样子 Agent 无需重新推导，就能正确使用这套 3 工具工具集）。集成代码块见 references/subagent-prompts.md。

如果派出协助，请阅读 references/subagent-prompts.md。子 Agent 负责收集证据；主 Agent 仍负责编写最终候选清单或比较结果。

参考资料路由

只加载所需分支。参考资料在磁盘上以扁平结构存放，并按决策节点分组。

搜索 / 发现

文件	何时阅读
references/discipline.md	首次使用此技能时，以及结果看起来不太对劲时。了解思维模型和降噪规范。
references/search.md	用于首次搜索和后续优化搜索的默认起点。
references/search-examples.md	需要了解优质首次搜索切入点、优化搜索的转换方向和纠偏模式示例时。
references/gh-syntax.md	需要了解有效的 gh search repos 限定符、OR 规则或阈值指导时。
references/gh-output.md	想要精简 gh 输出或适合 Markdown 的结果记录时。
references/web-augment.md	仅搜索 GitHub 的结果较少或噪声较大，或者名称不明确，适合通过 run-research 或 WebSearch 补充网页搜索时。

评估 / 深入分析

文件	何时阅读
references/evaluate.md	检查仓库质量信号或决定是否深入分析时。
references/evaluate-rest.md	需要获取初步搜索结果之外的低成本仓库信号时。
references/evaluate-graphql.md	需要针对首选候选项进行单仓库深度证据查询时。
references/evaluate-code.md	需要查看少数首选候选项的 README、文件树或源代码证据时。

协调

文件	何时阅读
references/subagent-prompts.md	领域范围较大，或用户明确希望委派更深入的对比工作时。包含供网页搜索补充子 Agent 使用的 run-research 集成区块。

输出 / 导出

文件	何时阅读
references/dedup-and-rank.md	将原始候选项整理成分类后的候选清单时。四阶段筛选流程。
references/report-template.html	用户明确要求在候选清单稳定后导出 HTML 时。

停止 / 优化关卡

文件	何时阅读
references/quality-gates.md	决定是停止、优化一次、补充搜索，还是深入分析时。

防护原则

• 不要将 run-research 或网页搜索补充设为必做项。
• 不要默认使用 .githubresearch/ 或任何持久化产物目录树。
• 不要用 20 个假设、100 次调用上限或多轮搜索流程来填充搜索。
• 未生成分类表前，不要升级到深度评估。
• 不要阅读每个候选项的完整 README；只阅读少数首选项的简介或相关部分，并跳过徽章区域（参见 references/evaluate-code.md）。
• 不要无意中让可选的深度分析工作变成默认流程。
• 候选清单已足够好，且新搜索大多重复相同领域内容时，就停止。
• 明确说明缺失信息、不确定之处，以及你未核实的内容。

常见偏离（阅读一次即可）

此技能最常发现的五种反模式：

1. 用户点名某项内容时跳过先核实（代价：发现不匹配前浪费 3～4 次搜索）。
2. 首次搜索使用 topic: 发现方式，结果返回相关性较低但星标数高达 10 万的仓库。
3. 使用未加限定的多词 OR 查询，导致解析含糊并返回大量无关结果。
4. 在首次搜索和深入分析之间跳过分类表（迫使你猜测前 5 个候选项）。
5. 深入阅读 7～10 份 README，而不是在 5 份时停止。

如果当前流程看起来不太对劲，请查看此列表。问题几乎总出在上游——漏了核实、限定符噪声太多，或候选项未分类。完整说明请参见 references/discipline.md。