juanmackie/juanskills

GitHub 宝藏猎人

目的

通过跨话题图谱广泛搜索以及跨星标和日期范围深度搜索，发现给定领域中高价值、低可见度的 GitHub 仓库。

何时使用

• 用户询问某个技术领域的“隐藏宝藏”、“未被充分评价”、“被忽视的机会”或“我错过了什么”。
• 用户希望进行探索性发现，而不是寻找某个单一最知名的仓库。
• 用户提供了某个话题、编程语言或问题描述。

何时不要使用

• 用户想要最流行的仓库（应直接按星标数排序搜索）。
• 用户想要代码搜索（应使用代码搜索，而非仓库搜索）。
• 用户没有 GitHub token 且期望深入结果（应警告限制）。

执行流程

阶段 0 — 身份验证检查

• 优先使用 gh CLI（如果已认证）；否则要求提供 GITHUB_TOKEN。
• 如果未认证，则警告：搜索上限约为每分钟 10 次请求，且结果将较为浅显。

阶段 1 — 话题扩展（广度）

1. 查询 /search/topics?q=<用户话题> 以查找相关话题名称。
2. 构建包含 3–8 个相关话题的话题集群。
3. 为集群中的每个话题构建带有 topic: 限定词的仓库查询。

阶段 2 — 星标范围切片（深度）

对于集群中的每个话题，运行以下不相交的范围： stars:1..10、stars:11..50、stars:51..200、stars:201..1000、stars:1001..5000。 在每个范围内分页，直到达到 1000 条结果上限。

阶段 3 — 时效性筛选

对于返回超过 1000 条结果的范围，递归拆分 pushed: 日期范围，直到每个窗口的结果数低于上限。

阶段 4 — 低星宝藏扫描

为每个话题运行专门的 stars:1..20 查询，并添加 pushed:>YYYY-MM-DD（6 个月前）。单独收集这些结果。

阶段 5 — 去重与数据丰富

• 通过 full_name 去重。
• 获取元数据：星标数、fork 数、开放 issue 数、最后推送日期、创建日期、话题标签、许可证、README 长度（通过内容 API）。
• 排除 fork，除非用户要求包含它们（fork:true）。

阶段 6 — 评分与排名

应用宝石评分：

• 星标速度（星标数 / 自创建以来的月数）
• 自上次推送以来的天数（越短越好）
• README 长度与结构
• 话题相关性密度
• issue 响应性（如果可用）

将结果分组为：

• 活跃宝石（近期有提交，速度上升）
• 预牵引宝石（低星标，近期活跃）
• 间隙填补（连接两个话题集群的仓库）

阶段 7 — 输出

返回一个排名的 Markdown 表格，列为： 仓库 | 星标数 | 年龄 | 最后推送 | 为何是宝藏 包含简短的方法说明和 API 速率限制的注意事项。

错误处理

• 收到 HTTP 403（次要速率限制）：休眠并重试，使用指数退避策略。
• 收到 HTTP 422（查询过于复杂）：简化查询，移除最不重要的限定词后重试。
• 某个星标范围无结果：跳过该范围并继续。

限制

• GitHub 搜索对每个查询上限为 1000 条结果；切片可缓解但无法完全消除此限制。
• 星标速度对非常新的仓库（少于 30 天）来说噪声较大。
• README 长度是近似指标，并非质量保证。