# Github Reference Scout

> 在动手做任何东西之前,先侦察 GitHub 上已有的开源实现:多路搜索候选项目 → 按活跃度/星标/许可证/README 质量打分筛选 → 深读头部项目的目录结构与设计思路 → 输出「直接 fork / 抄架构 / 只借鉴思路」三档可复用清单。Use this skill whenever the user wants to find existing open-source projects, GitHub repos, templates, boilerplates, plugins, or reference implementations for something they plan to build — including phrases like 找开源项目、有没有现成的、别人怎么做的、GitHub 上有什么参考、调研一下、不想从零开始、find similar repos、survey existing solutions、what's already out there. Also trigger when the user asks to evaluate or compare specific GitHub repos.

- Skill: `yuna1016/github-reference-scout` (Agent Skill)
- Install (CLI): `npx skillmds@latest add yuna1016/github-reference-scout`
- Raw SKILL.md: https://api.skillmd.com/api/skills/yuna1016/github-reference-scout/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: yuna1016 (https://skillmd.com/u/yuna1016)
- Updated: 2026-09-22
- Page: https://skillmd.com/skills/yuna1016/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 次/分钟,所以把多组关键词合并规划好再发请求,不要循环轰炸。

```bash
# 按 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 步:筛选(四维打分)

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

| 维度 | 看什么 | 红线 |
|---|---|---|
| 活跃度 | pushed_at 距今多久;open issues 有无回应 | 超过 18 个月未更新 → 降级为"仅参考思路" |
| 星标 | 相对同类的量级,不看绝对值 | 无红线,小众领域 50★ 也可能是头部 |
| 许可证 | MIT/Apache-2.0 最自由;GPL/AGPL 有传染性;无 License 默认不可复用代码 | 用户要商用/闭源时,GPL 类和无证项目只能借鉴思路,不能抄代码 |
| README 质量 | 有无截图/演示、安装说明、结构介绍 | README 空白或纯 AI 生成腔 → 大幅降权 |

批量补充元数据可以用单个 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 步:输出侦察报告

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

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

## 结论先行
<一句话:推荐哪条路——直接 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 完成,质量略降但流程不变