github-research

GitHub 研究技能

触发条件

当用户想要执行以下操作时，激活此技能：

• “查找关于 [topic] 的仓库”、“研究 GitHub 上关于 [topic] 的内容”
• “分析关于 [topic] 的开源代码”
• “查找 [paper/technique] 的实现”
• “哪些仓库实现了 [algorithm]？”
• 使用 /github-research <deep-research-output-dir> 斜杠命令

概述

此技能会系统地发现、评估并深入分析与某个研究主题相关的 GitHub 仓库。它会读取 deep-research 输出（论文数据库、阶段报告、代码引用），并生成一份可操作的集成蓝图，以便复用开源代码。

安装：~/.claude/skills/github-research/ — 脚本、参考资料和此技能定义。 输出：相对于当前工作目录的 ./github-research-output/{slug}/。 输入：deep-research 输出目录（包含 paper_db.jsonl、阶段报告、code_repos.md 等）

6 阶段工作流

Phase 1: Intake     → Extract refs, URLs, keywords from deep-research output
Phase 2: Discovery  → Multi-source broad GitHub search (50-200 repos)
Phase 3: Filtering  → Score & rank → select top 15-30 repos
Phase 4: Deep Dive  → Clone & deeply analyze top 8-15 repos (code reading)
Phase 5: Analysis   → Per-repo reports + cross-repo comparison
Phase 6: Blueprint  → Integration/reuse plan for research topic

输出目录结构

github-research-output/{slug}/
├── repo_db.jsonl                     # Master repo database
├── phase1_intake/
│   ├── extracted_refs.jsonl          # URLs, keywords, paper-repo links
│   └── intake_summary.md
├── phase2_discovery/
│   ├── search_results/               # Raw JSONL from each search
│   └── discovery_log.md
├── phase3_filtering/
│   ├── ranked_repos.jsonl            # Scored & ranked subset
│   └── filtering_report.md
├── phase4_deep_dive/
│   ├── repos/                        # Cloned repos (shallow)
│   ├── analyses/                     # Per-repo analysis .md files
│   └── deep_dive_summary.md
├── phase5_analysis/
│   ├── comparison_matrix.md          # Cross-repo comparison
│   ├── technique_map.md              # Paper concept → code mapping
│   └── analysis_report.md
└── phase6_blueprint/
    ├── integration_plan.md           # How to combine repos
    ├── reuse_catalog.md              # Reusable components catalog
    ├── final_report.md               # Complete compiled report
    └── blueprint_summary.md

脚本参考

所有脚本均为 Python 3，仅使用标准库，位于 ~/.claude/skills/github-research/scripts/。

脚本	用途	主要标志
extract_research_refs.py	从 deep-research 输出中解析 GitHub URL、论文引用和关键词	--research-dir、--output
search_github.py	通过 gh api 搜索 GitHub 仓库	--query、--language、--min-stars、--sort、--max-results、--topic、--output
search_github_code.py	搜索 GitHub 代码以查找实现	--query、--language、--filename、--max-results、--output
search_paperswithcode.py	搜索 Papers With Code，查找论文到仓库的映射	--paper-title、--arxiv-id、--query、--output
repo_db.py	JSONL 仓库数据库管理	子命令：merge、filter、score、search、tag、stats、export、rank
repo_metadata.py	通过 gh api 获取详细元数据	--repos、--input、--output、--delay
clone_repo.py	浅克隆仓库以供分析	--repo、--output-dir、--depth、--branch
analyze_repo_structure.py	映射文件树、关键文件和 LOC 统计	--repo-dir、--output
extract_dependencies.py	提取并解析依赖文件	--repo-dir、--output
find_implementations.py	在克隆的仓库中搜索特定代码模式	--repo-dir、--patterns、--output
repo_readme_fetch.py	不克隆仓库即可获取 README	--repos、--input、--output、--max-chars
compare_repos.py	生成跨仓库对比矩阵	--input、--output
compile_github_report.py	汇总所有阶段的内容并生成最终报告	--topic-dir

---

阶段 1：接收

目标：从 deep-research 输出中提取所有相关引用、URL 和关键词。

步骤

1. 创建输出目录结构：

   SLUG=$(echo "$TOPIC" | tr '[:upper:]' '[:lower:]' | tr ' ' '-' | tr -cd 'a-z0-9-')
   mkdir -p github-research-output/$SLUG/{phase1_intake,phase2_discovery/search_results,phase3_filtering,phase4_deep_dive/{repos,analyses},phase5_analysis,phase6_blueprint}
   

2. 从 deep-research 输出中提取引用：

   python ~/.claude/skills/github-research/scripts/extract_research_refs.py \
     --research-dir <deep-research-output-dir> \
     --output github-research-output/$SLUG/phase1_intake/extracted_refs.jsonl
   

3. 检查提取的引用：读取生成的 JSONL。记录：

   • 报告中直接找到的 GitHub URL
   • 论文标题和 arxiv ID（用于 Papers With Code 查询）
   • 提取的研究关键词和主题（用于 GitHub 搜索查询）

4. 撰写接收摘要：创建 phase1_intake/intake_summary.md，其中包含：

   • 找到的直接 GitHub URL 数量
   • 可能含有代码链接的论文数量
   • 提取的主要研究主题
   • 阶段 2 的计划搜索查询

检查点

• extracted_refs.jsonl 已存在且包含条目
• intake_summary.md 已写入
• 已记录搜索策略

---

阶段 2：发现

目标：广泛搜索，从多个来源找出 50–200 个候选仓库。

步骤

1. 通过直接 URL 搜索：获取第 1 阶段中所有 GitHub URL 的元数据：

   python ~/.claude/skills/github-research/scripts/repo_metadata.py \
     --repos owner1/name1 owner2/name2 ... \
     --output github-research-output/$SLUG/phase2_discovery/search_results/direct_urls.jsonl
   

2. 搜索 Papers With Code：针对每篇带有 arxiv ID 的论文：

   python ~/.claude/skills/github-research/scripts/search_paperswithcode.py \
     --arxiv-id 2401.12345 \
     --output github-research-output/$SLUG/phase2_discovery/search_results/pwc_2401.12345.jsonl
   

3. 按关键词搜索 GitHub（根据研究主题进行 3-8 次查询）：

   python ~/.claude/skills/github-research/scripts/search_github.py \
     --query "multi-agent LLM coordination" \
     --min-stars 10 --sort stars --max-results 50 \
     --output github-research-output/$SLUG/phase2_discovery/search_results/gh_query1.jsonl
   

4. 搜索 GitHub 代码（查找特定实现）：

   python ~/.claude/skills/github-research/scripts/search_github_code.py \
     --query "class MultiAgentOrchestrator" \
     --language python --max-results 30 \
     --output github-research-output/$SLUG/phase2_discovery/search_results/code_query1.jsonl
   

5. 获取 README，用于缺少描述的仓库：

   python ~/.claude/skills/github-research/scripts/repo_readme_fetch.py \
     --input <repos.jsonl> \
     --output github-research-output/$SLUG/phase2_discovery/search_results/readmes.jsonl
   

6. 合并所有结果到主数据库：

   python ~/.claude/skills/github-research/scripts/repo_db.py merge \
     --inputs github-research-output/$SLUG/phase2_discovery/search_results/*.jsonl \
     --output github-research-output/$SLUG/repo_db.jsonl
   

7. 编写发现日志：创建 phase2_discovery/discovery_log.md，记录使用的搜索查询、各来源的结果，以及找到的唯一仓库总数。

速率限制

• GitHub 搜索 API：每分钟 30 次请求（已认证）
• Papers With Code API：没有严格限制，但请合理使用（每秒 1 次请求）
• 必要时，在批处理操作中添加 --delay 1.0

检查点

• repo_db.jsonl 中有 50-200 个仓库
• discovery_log.md 记录了搜索详情

---

第 3 阶段：筛选

目标：为仓库评分并排序，选出 15-30 个进行深入分析。

步骤

1. 补充所有仓库的元数据：

   python ~/.claude/skills/github-research/scripts/repo_metadata.py \
     --input github-research-output/$SLUG/repo_db.jsonl \
     --output github-research-output/$SLUG/repo_db.jsonl \
     --delay 0.5
   

2. 为仓库评分（质量分数 + 活跃度分数）：

   python ~/.claude/skills/github-research/scripts/repo_db.py score \
     --input github-research-output/$SLUG/repo_db.jsonl \
     --output github-research-output/$SLUG/repo_db.jsonl
   

3. 使用大模型评估相关性：阅读排名靠前的约 50 个仓库（按 quality_score 排序），并根据以下因素指定 relevance_score（0.0-1.0）：

   • 与研究主题的直接相关性
   • 实现的完整性
   • 代码质量信号（来自 README、描述）
   • 更新相关性分数：

   python ~/.claude/skills/github-research/scripts/repo_db.py tag \
     --input github-research-output/$SLUG/repo_db.jsonl \
     --ids owner/name --tags "relevance:0.85"
   

4. 计算综合分数并排序：

   python ~/.claude/skills/github-research/scripts/repo_db.py score \
     --input github-research-output/$SLUG/repo_db.jsonl \
     --output github-research-output/$SLUG/repo_db.jsonl
   python ~/.claude/skills/github-research/scripts/repo_db.py rank \
     --input github-research-output/$SLUG/repo_db.jsonl \
     --output github-research-output/$SLUG/phase3_filtering/ranked_repos.jsonl \
     --by composite_score
   

5. 选出排名靠前的仓库：筛选前 15-30 个：

   python ~/.claude/skills/github-research/scripts/repo_db.py filter \
     --input github-research-output/$SLUG/phase3_filtering/ranked_repos.jsonl \
     --output github-research-output/$SLUG/phase3_filtering/ranked_repos.jsonl \
     --max-repos 30 --not-archived
   

6. 编写筛选报告：创建 phase3_filtering/filtering_report.md：

   • 筛选前后的统计数据
   • 分数分布
   • 排名前 30 的仓库及其分数和理由

评分公式

activity_score = sigmoid((days_since_push < 90) * 0.4 + has_recent_commits * 0.3 + open_issues_ratio * 0.3)
quality_score  = normalize(log(stars+1) * 0.3 + log(forks+1) * 0.2 + has_license * 0.15 + has_readme * 0.15 + not_archived * 0.2)
composite_score = relevance * 0.4 + quality * 0.35 + activity * 0.25

检查点

• ranked_repos.jsonl 中有 15-30 个仓库
• filtering_report.md 记录了评分详情

---

第 4 阶段：深入分析

目标：克隆并深入分析排名靠前的 8-15 个仓库。

步骤

1. 选择要深入分析的仓库：从排名列表中选取前 8-15 个。

2. 克隆每个仓库（浅克隆）：

   python ~/.claude/skills/github-research/scripts/clone_repo.py \
     --repo owner/name \
     --output-dir github-research-output/$SLUG/phase4_deep_dive/repos/
   

3. 分析每个克隆仓库的结构：

   python ~/.claude/skills/github-research/scripts/analyze_repo_structure.py \
     --repo-dir github-research-output/$SLUG/phase4_deep_dive/repos/name/ \
     --output github-research-output/$SLUG/phase4_deep_dive/analyses/name_structure.json
   

4. 提取依赖项：

   python ~/.claude/skills/github-research/scripts/extract_dependencies.py \
     --repo-dir github-research-output/$SLUG/phase4_deep_dive/repos/name/ \
     --output github-research-output/$SLUG/phase4_deep_dive/analyses/name_deps.json
   

5. 查找实现：搜索研究中的关键算法/概念：

   python ~/.claude/skills/github-research/scripts/find_implementations.py \
     --repo-dir github-research-output/$SLUG/phase4_deep_dive/repos/name/ \
     --patterns "class Transformer" "def forward" "attention" \
     --output github-research-output/$SLUG/phase4_deep_dive/analyses/name_impls.jsonl
   

6. 深入阅读代码：针对每个仓库，阅读结构分析中识别出的关键源文件。在 phase4_deep_dive/analyses/{name}_analysis.md 中编写每个仓库的分析：

   • 架构概述
   • 已实现的关键算法
   • 代码质量评估
   • API / 接口设计
   • 依赖项和要求
   • 优势与局限
   • 可复用性评估（提取组件的难易程度）

7. 编写深入分析摘要：phase4_deep_dive/deep_dive_summary.md

重要：实际阅读代码

不要只总结 README。你必须：

• 阅读主要源文件（入口点、核心模块）
• 理解实际的实现方式
• 找出实现研究概念的具体函数/类
• 记录代码模式、设计决策和权衡

检查点

• 仓库已克隆到 repos/
• 每个仓库的分析文件位于 analyses/
• 已编写 deep_dive_summary.md

---

第 5 阶段：分析

目标：跨仓库比较，并建立技术与代码之间的映射。

步骤

1. 生成对比矩阵：

   python ~/.claude/skills/github-research/scripts/compare_repos.py \
     --input github-research-output/$SLUG/phase4_deep_dive/analyses/ \
     --output github-research-output/$SLUG/phase5_analysis/comparison.json
   

2. 编写对比矩阵：创建 phase5_analysis/comparison_matrix.md：

   • 从语言、代码行数（LOC）、星标数、框架、许可证和测试等维度比较代码仓库
   • 分析依赖项重叠情况
   • 列出每个代码仓库的优势和劣势

3. 编写技术映射：创建 phase5_analysis/technique_map.md：

   • 将每个论文概念／研究技术映射到具体的代码仓库、文件和函数
   • 找出缺口（未找到实现的技术）
   • 记录同一概念的替代实现

4. 编写分析报告：phase5_analysis/analysis_report.md：

   • 对发现结果进行执行摘要
   • 代码分析的关键见解
   • 针对不同用途推荐使用哪些代码仓库

检查点

• 包含代码仓库对比表的 comparison_matrix.md
• 将概念映射到代码的 technique_map.md
• 包含发现结果的 analysis_report.md

---

第 6 阶段：蓝图

目标：制定可执行的集成与复用计划。

步骤

1. 编写集成计划：phase6_blueprint/integration_plan.md：

   • 组合代码仓库的推荐架构
   • 分步骤的集成方法
   • 依赖项解决策略
   • 潜在冲突及其解决方法

2. 编写复用目录：phase6_blueprint/reuse_catalog.md：

   • 对每个可复用组件，列出来源代码仓库、文件路径、函数／类、功能以及提取方法
   • 许可证兼容性矩阵
   • 集成工作量估算（简单／中等／困难）

3. 汇总最终报告：

   python ~/.claude/skills/github-research/scripts/compile_github_report.py \
     --topic-dir github-research-output/$SLUG/
   

4. 编写蓝图摘要：phase6_blueprint/blueprint_summary.md：

   • 一页执行摘要
   • 前 5 个代码仓库及推荐理由
   • 后续步骤建议

检查点

• 已完成 integration_plan.md
• 包含组件目录的 reuse_catalog.md
• 已汇总 final_report.md
• 作为执行摘要的 blueprint_summary.md

---

质量规范

1. 代码仓库按综合得分排序：relevance × 0.4 + quality × 0.35 + activity × 0.25
2. 深入分析必须阅读实际代码，不能只看 README
3. 集成蓝图必须将论文概念映射到具体代码文件／函数
4. 增量保存：每个阶段都立即将结果写入磁盘
5. 检查点恢复：检查已有输出，即可从任意阶段继续
6. 所有脚本均为仅使用标准库的 Python——无需安装 pip 包
7. 必须使用 gh CLI 访问 GitHub API（必须已完成身份验证）
8. 在所有搜索中按 repo_id（owner/name）去重
9. 注意速率限制：遵守 GitHub 搜索 API 的限制（30 次请求／分钟）

错误处理

• 如果未安装 gh：警告用户并提供安装说明
• 如果代码仓库已归档／删除：跳过并妥善处理，在日志中注明
• 如果克隆失败：跳过并在日志中注明，然后继续处理剩余代码仓库
• 如果 Papers With Code API 不可用：跳过，仅依靠 GitHub 搜索
• 始终将部分进度写入磁盘，以免工作丢失

参考资料

• 详细的阶段执行指南请参阅 references/phase-guide.md
• 深度研究 skill：~/.claude/skills/deep-research/SKILL.md
• 论文数据库模式：~/.claude/skills/deep-research/scripts/paper_db.py