# Repo Research

> GitHub 仓库深度研究与整合分析工具。支持单个/多个仓库研究、与本地项目对比分析、启发式整合建议。支持主题驱动搜索模式：自动搜索相关仓库、克隆、分析并生成报告。克隆远程仓库到本地 research/ 目录，进行深度代码分析、架构评估、依赖解析，并生成结构化研究报告。触发条件：用户提供 GitHub URL 请求研究/分析/整合/对比时，或提供主题关键词请求搜索并研究相关仓库时。

- Skill: `tools-only/repo-research` (Agent Skill, multi-file: 3 files)
- Install (CLI): `npx skillmds@latest add tools-only/repo-research`
- Raw SKILL.md: https://api.skillmd.com/api/skills/tools-only/repo-research/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Research & Search
- Author: tools-only (https://skillmd.com/u/tools-only)
- Updated: 2026-09-08
- Page: https://skillmd.com/skills/tools-only/repo-research

---


# Repo Research

GitHub 仓库深度研究工具，核心目标是从**外部项目中获取启发**，为用户自己的项目提供可操作的改进建议。

> **适用范围**：本技能适用于研究任何类型的 GitHub 仓库，不仅限于 Claude Skills。可用于研究开源项目、库、框架、工具等。

## 依赖管理

本技能的核心功能（单仓库/多仓库研究）**不需要**任何前置技能。

只有使用**主题驱动搜索模式**时，才需要以下可选依赖：

| 依赖技能 | 用途 | 安装源 | 必需性 |
|:---------|:-----|:-------|:-------|
| **find-skills** | 按主题搜索 GitHub 上的相关仓库 | `https://skills.sh/vercel-labs/skills/find-skills` | 可选 |

**使用说明**：
- 如果您直接提供 GitHub URL，本技能会直接使用现有的单/多仓库研究模式
- 如果您提供主题关键词（如"研究 OCR 相关项目"），本技能会：
  1. 首先检测 `find-skills` 是否已安装
  2. 如未安装，会提示您安装后再继续
  3. 安装后自动调用 `find-skills` 进行搜索

---

## 快速开始

```bash
# 单个仓库研究
/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: 依赖检查

```bash
# 检查 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 技能进行搜索：

```bash
/find-skills <主题关键词>
```

示例：
- `/find-skills pdf converter` - 搜索 PDF 转换相关技能
- `/find-skills video transcription` - 搜索视频转录相关技能
- `/find-skills ocr` - 搜索 OCR 相关技能

#### Step 2: 整理搜索结果

从 find-skills 的返回中提取：
1. **仓库名称**
2. **GitHub URL**
3. **简要描述**
4. **相关度评分**

**搜索结果整理格式**：

| # | 仓库名 | URL | 描述 | 相关度 |
|:-|:-------|:----|:-----|:-------|
| 1 | [name] | [url] | [描述] | ⭐⭐⭐⭐⭐ |
| 2 | [name] | [url] | [描述] | ⭐⭐⭐⭐☆ |

#### Step 3: 用户确认筛选

**对话询问**：
> "找到 [N] 个相关仓库。请选择要深入研究的项目："
> "1. 研究全部 [N] 个仓库"
> "2. 选择特定编号（如：1,3,5）"
> "3. 只研究前 [K] 个最相关的"
> "4. 自定义选择"

根据用户选择确定最终研究列表。

#### Step 4: 批量克隆与并行分析

##### 4.1 创建研究目录

```bash
RESEARCH_DATE=$(date +%Y%m%d)
RESEARCH_DIR="research/${RESEARCH_DATE}/topic-$(echo '$TOPIC' | tr ' ' '-')"
mkdir -p "${RESEARCH_DIR}"
cd "${RESEARCH_DIR}"
```

##### 4.2 批量克隆

```bash
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` 作为模板。

##### 报告结构

```markdown
# [主题] 综合研究报告

> **研究日期**：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: 会话汇报

```markdown
## 主题研究完成

**搜索主题**：[主题关键词]

**搜索结果**：找到 [N] 个相关仓库，深度分析了 [M] 个

**核心发现**：
1. [发现1]
2. [发现2]
3. [发现3]

**推荐项目**：
- 学习参考：[项目A]
- 生产使用：[项目B]

**详细报告已保存至**：`./research/YYYYMMDD/topic-[slug]/REPORT.md`
```

---

## 原有研究模式

（以下保持原有内容不变...）

### Step 1: 准备研究环境

#### 1.1 创建研究目录

```bash
# 单仓库目录结构
research/
└── YYYYMMDD/           # 日期目录
    └── repo-name/      # 仓库名称

# 多仓库目录结构
research/
└── YYYYMMDD/
    └── comparison/     # 对比研究使用统一目录
        ├── repo-a/
        ├── repo-b/
        └── REPORT.md   # 对比报告
```

使用 Bash 工具执行：

```bash
REPO_DATE=$(date +%Y%m%d)

# 单仓库
REPO_NAME=$(basename "$URL" .git)
RESEARCH_DIR="research/${REPO_DATE}/${REPO_NAME}"

# 多仓库（对比模式）
RESEARCH_DIR="research/${REPO_DATE}/comparison"

mkdir -p "${RESEARCH_DIR}"
cd "${RESEARCH_DIR}"
```

#### 1.2 克隆仓库

```bash
# 单仓库：直接克隆到当前目录
git clone --depth 1 "$URL" .

# 多仓库：分别克隆到子目录
for url in "${URLS[@]}"; do
    repo_name=$(basename "$url" .git)
    git clone --depth 1 "$url" "$repo_name"
done
```

---

### 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 核心文件优先阅读

```bash
# 必读文件（按优先级）
README.md          # 项目说明、快速开始
LICENSE            # 许可证
package.json/pyproject.toml/go.mod  # 依赖元数据
```

#### 2.3 项目结构分析

使用 Glob 工具探索：

```bash
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 启发式问题

在对比时回答以下问题：

1. **功能方面**
   - 外部仓库有哪些功能是我没有的？
   - 我有哪些功能是外部仓库没有的？
   - 哪些功能可以整合进来？

2. **架构方面**
   - 外部仓库的目录结构是否更清晰？
   - 模块划分方式是否值得借鉴？
   - 配置方式是否更灵活？

3. **实现方面**
   - 检测规则的组织方式有什么不同？
   - 报告生成的格式有什么优劣？
   - 用户交互方式有什么可学习之处？

4. **文档方面**
   - README 的结构是否更易理解？
   - 示例是否更丰富？
   - API 文档是否更完整？

---

### Step 5: 生成报告

#### 5.1 单仓库报告结构

使用 `assets/report-template.md` 作为模板。

#### 5.2 多仓库对比报告结构

使用 `assets/comparison-template.md` 作为模板。

#### 5.3 启发式报告结构

```markdown
# [研究主题] 启发式分析报告

> 研究日期：YYYY-MM-DD
> 研究仓库：[列出所有仓库]
> 对比项目：[本地项目路径]
> 报告路径：`./research/YYYYMMDD/comparison/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 会话汇报格式

```markdown
## 研究完成

**研究仓库**：
- [仓库名A]：[一句话描述]
- [仓库名B]：[一句话描述]

**对比项目**：[本地项目路径]

**核心启发**：
1. [启发1]
2. [启发2]
3. [启发3]

**立即可做的改进**：
- [ ] [改进1]
- [ ] [改进2]

**详细报告已保存至**：`./research/YYYYMMDD/comparison/REPORT.md`
```

---

## 最佳实践

### 研究策略

1. **启发优先**：研究的最终目的是"对我有什么帮助"
2. **对比驱动**：通过对比发现差异，通过差异获得启发
3. **具体可操作**：启发必须转化为具体的改进建议

### 启发提炼原则

1. **从差异中学习**：不同的实现方式往往有不同的考量
2. **从共性中总结**：多个仓库的共同选择往往有其原因
3. **从细节中洞察**：小细节可能反映设计理念

---

## Resources

### assets/

- **report-template.md**: 单仓库报告模板
- **comparison-template.md**: 多仓库对比报告模板
- **topic-research-template.md**: 主题驱动搜索研究报告模板（新增）