Repo Research
GitHub 仓库深度研究工具,核心目标是从外部项目中获取启发,为用户自己的项目提供可操作的改进建议。
适用范围:本技能适用于研究任何类型的 GitHub 仓库,不仅限于 Claude Skills。可用于研究开源项目、库、框架、工具等。
依赖管理
本技能的核心功能(单仓库/多仓库研究)不需要任何前置技能。
只有使用主题驱动搜索模式时,才需要以下可选依赖:
| 依赖技能 | 用途 | 安装源 | 必需性 |
|---|---|---|---|
| find-skills | 按主题搜索 GitHub 上的相关仓库 | https://skills.sh/vercel-labs/skills/find-skills | 可选 |
使用说明:
- •如果您直接提供 GitHub URL,本技能会直接使用现有的单/多仓库研究模式
- •如果您提供主题关键词(如"研究 OCR 相关项目"),本技能会:
- •首先检测
find-skills是否已安装 - •如未安装,会提示您安装后再继续
- •安装后自动调用
find-skills进行搜索
- •首先检测
快速开始
# 单个仓库研究 /repo-research https://github.com/user/repo # 多仓库对比研究 /repo-research https://github.com/user/repo-a https://github.com/user/repo-b # 指定分析重点 /repo-research https://github.com/user/repo --focus=architecture # 与现有技能整合 /repo-research https://github.com/user/repo --integrate-with=de-ai-polish
对话中触发:当用户提到"研究一下这个仓库"、"对比分析这些项目"、"对我项目有什么启发"等类似表述时自动激活。
工作流程
模式选择
根据输入自动选择研究模式:
| 输入类型 | 研究模式 | 输出 |
|---|---|---|
| 单个 GitHub URL | 单仓库深度研究 | 单仓库分析报告 + 启发建议 |
| 多个 GitHub URL | 多仓库对比研究 | 对比分析报告 + 共性启发 |
| GitHub URL + 本地路径 | 对比启发模式 | 差异分析 + 改进建议 |
| 主题/关键词 | 主题驱动搜索研究 | 搜索结果 + 多仓库综合分析报告 |
主题驱动搜索研究模式
当用户提供主题关键词而非具体 GitHub URL 时,使用此模式。
触发条件
用户表达以下需求时自动激活:
- •"帮我找关于 X 的相关项目"
- •"搜索研究一下主题 X"
- •"找一些关于 X 的开源项目"
- •"主题 X 有什么值得研究的仓库"
工作流程
Step 0: 依赖检查
# 检查 find-skills 是否已安装
if ! /find-skills --help >/dev/null 2>&1; then
echo "⚠️ 主题驱动搜索模式需要 find-skills 技能"
echo "正在为您安装..."
/skill-manager install https://skills.sh/vercel-labs/skills/find-skills
fi
对话提示:
"检测到您需要使用主题搜索功能。正在检查依赖..."
Step 1: 使用 find-skills 搜索相关仓库
调用 find-skills 技能进行搜索:
/find-skills <主题关键词>
示例:
- •
/find-skills pdf converter- 搜索 PDF 转换相关技能 - •
/find-skills video transcription- 搜索视频转录相关技能 - •
/find-skills ocr- 搜索 OCR 相关技能
Step 2: 整理搜索结果
从 find-skills 的返回中提取:
- •仓库名称
- •GitHub URL
- •简要描述
- •相关度评分
搜索结果整理格式:
| # | 仓库名 | URL | 描述 | 相关度 |
|---|---|---|---|---|
| 1 | [name] | [url] | [描述] | ⭐⭐⭐⭐⭐ |
| 2 | [name] | [url] | [描述] | ⭐⭐⭐⭐☆ |
Step 3: 用户确认筛选
对话询问:
"找到 [N] 个相关仓库。请选择要深入研究的项目:" "1. 研究全部 [N] 个仓库" "2. 选择特定编号(如:1,3,5)" "3. 只研究前 [K] 个最相关的" "4. 自定义选择"
根据用户选择确定最终研究列表。
Step 4: 批量克隆与并行分析
4.1 创建研究目录
⚠️ 重要:必须在用户当前工作目录下创建 research 文件夹。
# 获取用户当前工作目录
WORK_DIR="${PWD}"
RESEARCH_DATE=$(date +%Y%m%d)
# 将主题转换为 slug 格式(小写、空格替换为连字符)
TOPIC_SLUG=$(echo "$TOPIC" | tr '[:upper:]' '[:lower:]' | tr ' ' '-')
# 使用绝对路径确保在正确位置
RESEARCH_DIR="${WORK_DIR}/research/${RESEARCH_DATE}-${TOPIC_SLUG}"
mkdir -p "${RESEARCH_DIR}"
cd "${RESEARCH_DIR}"
4.2 批量克隆
for url in "${SELECTED_URLS[@]}"; do
repo_name=$(basename "$url" .git)
echo "正在克隆: $repo_name"
git clone --depth 1 "$url" "$repo_name"
done
4.3 并行分析
对每个克隆的仓库执行基础分析(参见"Step 2: 基础分析")。
Step 5: 生成主题综合报告
使用 assets/topic-research-template.md 作为模板。
报告结构
# [主题] 综合研究报告 > **研究日期**:YYYY-MM-DD > **搜索主题**:[主题关键词] > **研究仓库数**:[N] 个 > **报告路径**:`./research/YYYYMMDD-[topic-slug]/REPORT.md` --- ## 执行摘要 ### 研究概述 [用一段话概括:基于主题搜索了哪些类型的仓库,主要发现了什么] ### 一句话总结 [用一句话概括最关键的发现] ### 核心指标 | 指标 | 数值 | |:-----|:-----| | 搜索结果总数 | [N] 个仓库 | | 深度研究数量 | [M] 个仓库 | | 相关技术栈 | [列举主要技术] | | 活跃项目占比 | [X%] | --- ## 搜索结果概览 ### 仓库清单 | # | 仓库名 | 描述 | 语言 | Stars | 活跃度 | |:-|:-------|:-----|:-----|:-----|:-------| | 1 | [name] | [描述] | [lang] | [★] | 🟢 活跃 | | 2 | [name] | [描述] | [lang] | [★] | 🟡 中等 | ### 分类汇总 **按技术类型**: - [技术1]: [数量] 个项目 - [技术2]: [数量] 个项目 **按功能类型**: - [功能1]: [数量] 个项目 - [功能2]: [数量] 个项目 --- ## 技术栈分析 ### 主流技术选择 | 技术 | 使用项目数 | 占比 | 代表项目 | |:-----|-----------|:-----|:---------| | [技术1] | [N] | [X%] | [项目A, 项目B] | | [技术2] | [N] | [X%] | [项目C] | ### 技术趋势洞察 - **趋势1**:[描述观察到的技术趋势] - **趋势2**:[描述观察到的技术趋势] --- ## 共性模式识别 ### 架构共性 多个项目共同采用的架构模式: 1. **[模式名称]**:[描述] - 采用项目:[列举] - 优势分析:[分析] ### 功能共性 多个项目都实现的核心功能: 1. **[功能名称]**:[描述] - 实现方式差异:[对比] ### 文档共性 文档编写的共同特点: - [观察到的文档模式] --- ## 项目对比分析 ### 功能对比矩阵 | 功能 | 项目1 | 项目2 | 项目3 | 最优实现 | |:-----|:-----|:-----|:-----|:---------| | [功能1] | ✅ | ✅ | ❌ | [分析] | | [功能2] | ✅ | ❌ | ✅ | [分析] | ### 架构对比 | 维度 | 项目1 | 项目2 | 项目3 | 值得学习 | |:-----|:-----|:-----|:-----|:---------| | 目录结构 | [描述] | [描述] | [描述] | [推荐] | | 模块化 | [描述] | [描述] | [描述] | [推荐] | ### 代码质量对比 | 项目 | 代码组织 | 文档 | 测试 | 综合评分 | |:-----|:---------|:-----|:-----|:---------| | 项目1 | ⭐⭐⭐⭐☆ | ⭐⭐⭐☆☆ | ⭐⭐☆☆☆ | B+ | | 项目2 | ⭐⭐⭐☆☆ | ⭐⭐⭐⭐☆ | ⭐⭐⭐☆☆ | B | --- ## 深度剖析(精选项目) ### 项目 A: [仓库名] #### 为什么值得深入研究 [说明选择这个项目进行深度剖析的原因] #### 架构亮点 - [亮点1] - [亮点2] #### 可借鉴的设计 1. **[设计点1]**:[描述可借鉴之处] 2. **[设计点2]**:[描述可借鉴之处] ### 项目 B: [仓库名] [同上结构] --- ## 启发与建议 ### 对本地项目的启发 #### 可直接借鉴 1. **[方面1]** - **来源**:[项目A/项目B] - **做法**:[描述具体做法] - **本地应用**:[如何应用到本地项目] - **优先级**:🔴 高 / 🟡 中 / 🟢 低 - **预计工作量**:[X 小时] #### 需要进一步探索 1. **[技术/模式]** - **为什么**:[说明价值] - **调研方式**:[如何调研] - **预期收益**:[说明] ### 最佳实践总结 从多个项目中提炼的最佳实践: 1. **[实践1]**:[描述] 2. **[实践2]**:[描述] --- ## 项目推荐 ### 不同场景推荐 | 场景 | 推荐项目 | 理由 | |:-----|:---------|:-----| | 学习参考 | [项目名] | [理由] | | 生产使用 | [项目名] | [理由] | | 二次开发 | [项目名] | [理由] | | 特定需求 | [项目名] | [理由] | ### 快速决策指南 - **如果你需要 X** → 推荐 [项目A] - **如果你需要 Y** → 推荐 [项目B] - **如果你需要 Z** → 推荐 [项目C] --- ## 附录 ### 完整仓库列表 #### 深度研究的项目 1. **[项目名]** - [GitHub URL] - 描述:[描述] - 技术栈:[列举] - 最后更新:[日期] #### 仅浏览的项目 1. **[项目名]** - [GitHub URL] - 相关度:⭐⭐☆☆☆ ### 参考资源 - [相关文档链接] - [相关文章链接] --- **报告生成时间**:YYYY-MM-DD HH:MM **研究者**:Claude Code + repo-research skill **搜索工具**:find-skills skill
Step 6: 会话汇报
## 主题研究完成 **搜索主题**:[主题关键词] **搜索结果**:找到 [N] 个相关仓库,深度分析了 [M] 个 **核心发现**: 1. [发现1] 2. [发现2] 3. [发现3] **推荐项目**: - 学习参考:[项目A] - 生产使用:[项目B] **详细报告已保存至**:`./research/YYYYMMDD-[topic-slug]/REPORT.md`
原有研究模式
(以下保持原有内容不变...)
Step 1: 准备研究环境
1.1 创建研究目录
统一目录结构:
research/
└── YYYYMMDD-[topic]/ # 日期+主题目录
├── repo-name/ # 研究的仓库(即使是单个仓库也在子目录中)
├── repo-b/ # 多仓库时会有多个子目录
└── REPORT.md # 研究报告
# 单仓库示例:
# research/20260213-vibe-working-tutorial/
# └── vibe-working-tutorial/ <- 仓库内容
# └── REPORT.md
# 多仓库示例:
# research/20260213-pdf-tools-comparison/
# └── pdf-lib/
# └── pdfkit/
# └── REPORT.md
设计原则:无论研究多少个仓库,都保持
research/日期-主题/仓库名/的统一结构,便于后续管理和扩展。
命名格式:YYYYMMDD-[topic-slug]
- •
topic-slug:主题关键词,用连字符连接,小写 - •示例:
20260211-pdf-ocr-comparison、20260212-transcription-study
主题来源(优先级从高到低):
- •用户指定:调用时通过
--topic参数提供 - •对话询问:自动询问用户输入简短的主题描述
- •自动推断:从仓库名称或研究内容推断(备选)
使用 Bash 工具执行:
⚠️ 重要:必须在用户当前工作目录下创建 research 文件夹,而非 skill 所在目录。
# 获取用户当前工作目录(从环境变量或上下文推断)
WORK_DIR="${PWD}" # 使用当前工作目录
REPO_DATE=$(date +%Y%m%d)
# 确定研究主题(通过对话询问或参数获取)
# 示例:TOPIC="pdf-ocr-comparison"
TOPIC_SLUG=$(echo "$TOPIC" | tr '[:upper:]' '[:lower:]' | tr ' ' '-')
# 新格式(推荐)- 使用绝对路径确保位置正确
RESEARCH_DIR="${WORK_DIR}/research/${REPO_DATE}-${TOPIC_SLUG}"
# 旧格式(向后兼容,如果用户明确要求)
# RESEARCH_DIR="${WORK_DIR}/research/${REPO_DATE}/${REPO_NAME}"
mkdir -p "${RESEARCH_DIR}"
cd "${RESEARCH_DIR}"
对话询问主题:
"请为本次研究提供一个简短的主题描述(用于目录命名,如
pdf-ocr、agent-framework):"
1.2 克隆仓库
⚠️ 重要:无论是单仓库还是多仓库,都统一克隆到子目录中,保持目录结构一致。
# 统一方式:所有仓库都克隆到子目录
# 这样可以保持 research/日期-主题/ 目录结构的一致性
# 单仓库和多仓库的区别只在于克隆的次数
for url in "${URLS[@]}"; do
repo_name=$(basename "$url" .git)
git clone --depth 1 "$url" "$repo_name"
done
# 单仓库示例(实际也是克隆到子目录):
# research/20260213-vibe-working-tutorial/
# └── vibe-working-tutorial/ <- 仓库内容
# └── REPORT.md <- 研究报告
# 多仓库示例:
# research/20260213-pdf-tools-comparison/
# └── pdf-lib/ <- 仓库A
# └── pdfkit/ <- 仓库B
# └── REPORT.md <- 研究报告
Step 2: 基础分析(对每个仓库)
2.1 识别项目类型
| 特征 | 项目类型 | 分析重点 |
|---|---|---|
package.json | Node.js/前端 | 依赖、脚本、构建配置 |
requirements.txt/pyproject.toml | Python | 虚拟环境、依赖管理 |
go.mod | Go | 模块结构、依赖 |
Cargo.toml | Rust | Edition、特性、依赖 |
SKILL.md | Claude Skill | 技能定义、frontmatter |
2.2 核心文件优先阅读
# 必读文件(按优先级) README.md # 项目说明、快速开始 LICENSE # 许可证 package.json/pyproject.toml/go.mod # 依赖元数据
2.3 项目结构分析
使用 Glob 工具探索:
glob "**/*" # 所有文件 glob "**/*.md" # 文档 glob "src/**/*.ts" # 源代码 glob "tests/**/*" # 测试
2.4 技术栈识别
- •前端:React/Vue/Svelte/Next.js/Nuxt + 状态管理 + 样式方案
- •后端:Node.js/Python/Go/Rust + 框架 + ORM
- •工具链:Vite/Webpack + Jest/Pytest + ESLint/Prettier
Step 3: 多仓库对比分析(多仓库模式)
3.1 对比维度
| 维度 | 对比内容 | 启发点 |
|---|---|---|
| 架构设计 | 目录结构、模块划分 | 有哪些组织方式值得借鉴 |
| 功能实现 | 核心功能、API 设计 | 同类功能的不同实现方式 |
| 技术选型 | 框架、依赖、工具链 | 为什么选择这些技术 |
| 文档质量 | README、注释、API 文档 | 文档写法的差异 |
| 代码风格 | 命名、结构、模式 | 哪种风格更清晰 |
3.2 共性提取
识别多个仓库的共同点:
- •共同的技术选择(如都用 Markdown 作为格式)
- •共同的设计模式(如都用插件架构)
- •共同的问题解决方式
3.3 差异分析
识别关键差异及其原因:
- •为什么 A 用 Markdown 而 B 用 JSON
- •为什么 A 有测试而 B 没有
- •不同实现方式的优劣
Step 4: 本地项目对比(启发模式)
4.1 识别本地项目
对话中询问:
"是否需要与本地项目进行对比?如果有,请提供项目路径(相对或绝对)。"
常见本地项目类型:
- •
./test/de-ai-polish- 本地技能 - •
./skills/xxx- 现有技能 - •
./test/yyy- 测试项目
4.2 差异分析框架
| 分析项 | 外部仓库 | 本地项目 | 差异 | 启发 |
|---|---|---|---|---|
| 目录结构 | [描述] | [描述] | [差异点] | [可借鉴之处] |
| 核心功能 | [描述] | [描述] | [差异点] | [可补充之处] |
| 文档方式 | [描述] | [描述] | [差异点] | [可改进之处] |
| 检测规则 | [列举] | [列举] | [差异点] | [可学习之处] |
4.3 启发式问题
在对比时回答以下问题:
- •
功能方面
- •外部仓库有哪些功能是我没有的?
- •我有哪些功能是外部仓库没有的?
- •哪些功能可以整合进来?
- •
架构方面
- •外部仓库的目录结构是否更清晰?
- •模块划分方式是否值得借鉴?
- •配置方式是否更灵活?
- •
实现方面
- •检测规则的组织方式有什么不同?
- •报告生成的格式有什么优劣?
- •用户交互方式有什么可学习之处?
- •
文档方面
- •README 的结构是否更易理解?
- •示例是否更丰富?
- •API 文档是否更完整?
Step 5: 生成报告
5.1 单仓库报告结构
使用 assets/report-template.md 作为模板。
5.2 多仓库对比报告结构
使用 assets/comparison-template.md 作为模板。
5.3 启发式报告结构
# [研究主题] 启发式分析报告 > 研究日期:YYYY-MM-DD > 研究仓库:[列出所有仓库] > 对比项目:[本地项目路径] > 报告路径:`./research/YYYYMMDD-[topic-slug]/REPORT.md` --- ## 核心发现 ### 一句话总结 [用一句话概括最关键的启发] --- ## 对比分析 ### 功能对比 | 功能 | 仓库A | 仓库B | 本地项目 | 启发 | |:-----|:------|:------|:---------|:-----| | [功能1] | ✅ | ✅ | ❌ | [建议] | | [功能2] | ✅ | ❌ | ✅ | [分析] | ### 架构对比 | 维度 | 仓库A | 仓库B | 本地项目 | 启发 | |:-----|:------|:------|:---------|:-----| | 目录结构 | [描述] | [描述] | [描述] | [建议] | | 模块划分 | [描述] | [描述] | [描述] | [建议] | ### 规则/检测方式对比 | 检测项 | 仓库A | 仓库B | 本地项目 | 启发 | |:-------|:------|:------|:---------|:-----| | [规则1] | [实现] | [实现] | [实现] | [可学习] | --- ## 具体启发 ### 可直接借鉴的方面 1. **[方面1]** - **外部做法**:[描述] - **本地现状**:[描述] - **改进建议**:[具体建议] - **优先级**:高/中/低 2. **[方面2]** - **外部做法**:[描述] - **本地现状**:[描述] - **改进建议**:[具体建议] - **优先级**:高/中/低 ### 需要进一步探索的方面 1. **[方面1]**:[为什么值得探索] 2. **[方面2]**:[为什么值得探索] --- ## 行动建议 ### 立即可做的改进 - [ ] [改进1] - 预计时间:[X小时] - [ ] [改进2] - 预计时间:[X小时] ### 需要进一步调研的 - [ ] [调研项1] - 调研方式:[如何调研] - [ ] [调研项2] - 调研方式:[如何调研] --- ## 附录 ### 仓库详细信息 - **仓库A**:[名称](URL) - [一句话描述] - **仓库B**:[名称](URL) - [一句话描述] ### 参考链接 - [相关文档] - [相关文章]
5.4 会话汇报格式
## 研究完成 **研究仓库**: - [仓库名A]:[一句话描述] - [仓库名B]:[一句话描述] **对比项目**:[本地项目路径] **核心启发**: 1. [启发1] 2. [启发2] 3. [启发3] **立即可做的改进**: - [ ] [改进1] - [ ] [改进2] **详细报告已保存至**:`./research/YYYYMMDD-[topic-slug]/REPORT.md`
最佳实践
研究策略
- •启发优先:研究的最终目的是"对我有什么帮助"
- •对比驱动:通过对比发现差异,通过差异获得启发
- •具体可操作:启发必须转化为具体的改进建议
启发提炼原则
- •从差异中学习:不同的实现方式往往有不同的考量
- •从共性中总结:多个仓库的共同选择往往有其原因
- •从细节中洞察:小细节可能反映设计理念
Resources
assets/
- •report-template.md: 单仓库报告模板
- •comparison-template.md: 多仓库对比报告模板
- •topic-research-template.md: 主题驱动搜索研究报告模板(新增)
高级功能 (v0.4.0)
借鉴 Zread MCP 的实现思路,增强本地分析能力。
1. 代码语义搜索
利用本地已克隆的仓库,进行深度代码搜索。
触发方式
用户表达以下需求时激活:
- •"搜索函数 X"
- •"查找类 Y"
- •"看看这个项目怎么实现 Z 的"
- •直接使用
--search参数
使用方法
# 搜索函数定义 /repo-research https://github.com/user/repo --search="function:parse*" # 搜索类定义 /repo-research https://github.com/user/repo --search="class:*Handler" # 搜索导入 /repo-research https://github.com/user/repo --search="import:react" # 搜索特定模式 /repo-research https://github.com/user/repo --search="pattern:console\.log"
内部实现
调用 scripts/search.py 中的 CodeSearcher 类:
- •使用 Grep 工具进行模式匹配
- •支持多种语言:Python, JavaScript, TypeScript, Go, Rust, Java
- •支持多种模式:function, class, import, doc, pattern
2. 深度代码分析
超越基础分析,提供架构和质量层面的深度洞察。
分析类型
| 类型 | 描述 | 触发参数 |
|---|---|---|
| 架构分析 | 目录结构、模块划分、入口文件、架构模式 | --analyze=architecture |
| 质量分析 | 代码统计、注释率、技术债务、潜在问题 | --analyze=quality |
| 完整分析 | 包含架构和质量两个维度 | --analyze=full |
使用方法
# 架构分析 /repo-research https://github.com/user/repo --analyze=architecture # 质量分析 /repo-research https://github.com/user/repo --analyze=quality # 完整分析 /repo-research https://github.com/user/repo --analyze=full
内部实现
- •
架构分析器 (
scripts/analyzer/architecture.py):- •目录结构分析
- •入口文件识别
- •模块/包结构识别
- •配置文件检测
- •架构模式检测(MVC、微服务、插件、monorepo)
- •
质量分析器 (
scripts/analyzer/quality.py):- •代码统计(行数、语言分布)
- •注释覆盖率分析
- •技术债务检测(TODO、FIXME、deprecated)
- •问题检测(硬编码密钥、console.log、大文件)
3. 智能问答
利用 Claude Code 的 LLM 能力,回答关于仓库的自然语言问题。
触发方式
用户表达以下需求时激活:
- •"这个项目是做什么的?"
- •"如何使用这个项目?"
- •"架构是怎样的?"
- •"有哪些主要模块?"
- •直接使用
--ask参数
使用方法
# 询问项目概述 /repo-research https://github.com/user/repo --ask="这个项目是做什么的?" # 询问使用方法 /repo-research https://github.com/user/repo --ask="如何使用这个项目?" # 询问架构 /repo-research https://github.com/user/repo --ask="架构是怎样的?"
内部实现
- •
问题分类 (
scripts/qa.py中的QuestionClassifier):- •意图识别:overview, architecture, usage, api, dependencies
- •实体提取:功能名、组件名、文件名
- •上下文确定:需要读取哪些文件
- •
回答生成:
- •使用 Grep/Glob 搜索相关代码
- •使用 read_file 读取关键文件
- •结合 Claude Code 的 LLM 能力生成自然语言回答
4. 组合使用
高级功能可以组合使用,实现更强大的分析能力:
# 搜索 + 分析 /repo-research https://github.com/user/repo --search="function:parse*" --analyze=architecture # 问答 + 报告 /repo-research https://github.com/user/repo --ask="这个项目如何使用?" --output=report
scripts/ 目录结构
scripts/ ├── __init__.py # 模块导出 ├── search.py # 语义搜索 ├── qa.py # 智能问答 ├── architecture.py # 架构分析 └── quality.py # 质量分析
未来计划
- • 依赖分析模块 (dependency analysis)
- • 安全分析模块 (security analysis)
- • 性能分析模块 (performance analysis)
- • 更智能的问答系统