Github Reference Scout

GitHub Reference Scout

核心理念:大多数轮子已经被造过了。这个 skill 的任务不是替用户写代码,而是替用户完成一次高质量的"开源侦察",让用户站在最好的现有实现上做定制,而不是从零搭建。

整个流程分四步:取词 → 撒网 → 筛选 → 深挖,最后按固定模板输出侦察报告。

第 0 步:取词(理解需求,生成搜索词)

先从用户的描述里提炼:

1. 领域词:生态/平台名(如 obsidian、nextjs、raycast、home-assistant)
2. 功能词:要解决的问题(如 dashboard、daily-notes、workflow、template、starter)
3. 形态词:期望的产物形态(plugin / vault / template / boilerplate / cli / config)

组合出 3-6 组搜索词,从宽到窄排列。同时准备 1-2 个英文同义改写(GitHub 上英文项目占绝对多数,中文需求必须翻译后搜索)。

如果用户需求太模糊(比如只说"想优化我的工作流"),先用一句话确认关键约束:平台是什么、想要成品还是参考、有没有许可证要求(商用需避开 GPL 类)。只问一个问题,不要连环追问。

复合需求先拆解,再取词:如果用户描述里包含多个可以独立存在的子需求(比如"桌宠监控CLI + 记todo + 日历提醒 + 会议录音",这四件事分别都是独立赛道),不要把它们拼成一条大查询去搜——GitHub Search API 对多关键词是 AND 语义,子需求越多,同时命中的概率越接近 0,几乎必然搜空、白白浪费限流配额。正确做法:先把需求拆成 N 个独立子需求清单,每个子需求单独走一遍"取词→撒网",子需求之间不共享关键词。撒网和输出阶段也要分开处理(见第 1 步和第 4 步)。

第 1 步:撒网(多路并行搜索)

用三条互补的渠道,不要只依赖一条:

渠道 A:GitHub Search API(主渠道,用 bash + curl)

沙箱可匿名直连 api.github.com。搜索 API 限流约 10 次/分钟,所以把多组关键词合并规划好再发请求,不要循环轰炸。

# 按 stars 排序搜索,只取需要的字段,节省 context
curl -s "https://api.github.com/search/repositories?q=KEYWORDS+pushed:>YYYY-MM-DD&sort=stars&per_page=10" \
  | python3 -c "
import json,sys
d=json.load(sys.stdin)
for r in d['items']:
    lic=(r.get('license') or {}).get('spdx_id','NONE')
    print(f\"{r['stargazers_count']:>6}★  {r['full_name']:<45} {lic:<12} pushed:{r['pushed_at'][:10]}  {(r['description'] or '')[:80]}\")
"

有用的查询修饰符:topic:xxx、pushed:>2025-07-01(近一年活跃)、stars:>100、in:name,description,readme。日期阈值按当前日期动态计算。

渠道 B:Awesome 列表(发现"搜索词想不到"的项目)

用 web_search 找 awesome-<领域> 列表(如 awesome-obsidian、awesome-selfhosted),必要时用 web_fetch 读列表内容。Awesome 列表经过人工策展,常收录星标不高但质量极好的项目,是对 API 搜索的重要补充。

渠道 C:web_search 兜底

搜 "<需求描述>" github、best <功能> <平台> reddit。Reddit/HN 的讨论帖能反映真实口碑,补充"星标看不出来"的信息(如项目已弃坑、有更好的替代品)。

撒网目标:凑齐 8-15 个候选项目再进入筛选。少于 5 个说明搜索词太窄,换词重搜。若某个子需求换了 2-3 组词依然 0-2 个命中,不要继续硬搜——大概率是这个子需求本身没有现成开源方案,记录下来直接进入"空白赛道"处理(见第 4 步),这本身就是一个有价值的结论。

若需求是拆解出的多个子需求(见第 0 步):每个子需求单独撒网、单独判断是否够 5 个候选,不要把所有子需求的候选混在一起数数量——某个子需求 0 命中不代表整体调研失败,只代表这一块是空白。

第 2 步:筛选(四维打分)

对候选项目按四个维度快速评估,汇总成一张候选表:

批量补充元数据可以用单个 repo API(限流 60 次/小时,省着用): curl -s "https://api.github.com/repos/OWNER/REPO" → 关注 pushed_at、open_issues_count、license.spdx_id、archived(archived=true 直接标记为已归档)。

筛出 2-3 个头部项目进入深挖。

第 3 步:深挖(读结构,提炼设计)

对每个入选项目:

1. 读 README:curl -s "https://raw.githubusercontent.com/OWNER/REPO/HEAD/README.md"。raw 链接区分大小写,404 时依次改试 Readme.md、readme.md,再试 main/master 分支;仍失败就 web_search 该仓库名后用 web_fetch 读 GitHub 页面
2. 看目录结构:curl -s "https://api.github.com/repos/OWNER/REPO/git/trees/HEAD?recursive=1" 取文件树(大仓库会截断,够用即可),提炼组织方式而非罗列文件
3. 提炼三样东西:
   • 架构决策:它把问题拆成了哪几块?为什么这样拆?
   • 可直接搬运的部分:配置文件、模板、目录骨架、脚本
   • 它的坑:README/issues 里承认的限制、已知问题

深挖时保持克制:每个项目的分析控制在 200 字以内,用户要的是决策依据,不是论文。

第 4 步:输出侦察报告

固定用这个结构(可视语言习惯译为用户语言):

# 侦察报告:<需求一句话>

## 结论先行
<一句话:推荐哪条路——直接 fork X / 以 Y 的架构为骨架自建 / 现有方案都不合适的原因>

## 候选全景(N 个)
<一张表:项目(格式固定为 owner/repo,不要只写 repo 名——同名不同作者的项目很常见,比如可能同时存在 alterhq/openpets 和 alvinunreal/openpets,不带 owner 会张冠李戴) | ★ | 最近更新 | 许可证 | 一句话定位。全部附链接>

<若需求在第 0 步被拆解为多个独立子需求,每个子需求单独出一张候选表,标题写成"候选全景·<子需求名>(N 个)";某子需求 0-2 命中就直接写"候选全景·<子需求名>:空白赛道,未找到现成方案",不要为了凑数硬塞不相关项目>

## 头部深挖(2-3 个,若有多个子需求则每个有候选的子需求各挑 1-2 个)
### <owner/repo> —— <一句话定位>
- 架构思路:...
- 可直接搬运:...
- 注意/坑:...
- 许可证影响:...

## 行动建议
1. 直接 fork/安装:<...>
2. 抄架构自建:<...>
3. 只借鉴思路:<...>
<每条给出第一步具体操作>

注意事项

• 诚实标注证据强度:星标数和更新时间是硬数据;"社区口碑"来自搜索是软证据,要注明出处
• 不要虚构仓库:所有项目名、链接必须来自实际 API 返回或搜索结果,拿不准就再查一次
• 限流意识,但不要一开工就查:search(10次/分)和 core(60次/小时,单仓库 GET、trees 目录树走这个)是两个独立配额,且沙箱出口 IP 共享,core 配额经常一开始就是 0——这与你能不能顺利完成侦察基本无关,因为撒网和筛选阶段只靠 search,不查 core 也能跑完大半流程。所以 rate_limit 检查只在第 3 步深挖、真正要调用 repos/OWNER/REPO 或 git/trees 之前查一次,不要在第 1 步开局就查——查早了对后续搜索毫无指导意义,纯属浪费一次判断。
  • 查到 core 余量充足:正常用 core API 补元数据、拉目录树。
  • 查到 core=0:不要等待或反复重试,直接降级——单仓库元数据改用 search/repositories?q=repo:OWNER/REPO 拿 stars/license/pushed_at(这个查询占用的是 search 配额,不是 core);目录树部分放弃 API,改成读 README 里的目录结构说明,或 web_fetch 仓库主页看文件列表面板。
• 警惕"高星弃坑":README 开头出现 archived、no longer maintained、"I've moved to X" 等字样时,无论星标多高一律降为"只借鉴思路",并在报告里明确标注。这类信息只有读 README 才能发现,元数据看不出来
• 网络受限时的降级:若沙箱无法访问 api.github.com,整个流程改用 web_search + web_fetch 完成,质量略降但流程不变