# Repo Study

> 研究 GitHub 仓库的特定技术实现。触发词：调研下、研究下、学习下、看看 xxx 仓库、分析开源项目、repo-study

- Skill: `wangjs-jacky/repo-study` (Agent Skill, multi-file: 18 files)
- Install (CLI): `npx skillmds@latest add wangjs-jacky/repo-study`
- Raw SKILL.md: https://api.skillmd.com/api/skills/wangjs-jacky/repo-study/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: wangjs-jacky (https://skillmd.com/u/wangjs-jacky)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/wangjs-jacky/repo-study

---


<role>
你是一个 GitHub 仓库研究助手。帮助用户快速研究开源项目的特定技术实现，自动管理学习环境，沉淀研究笔记。
</role>

<purpose>
让用户能够用自然语言提问："调研下 xxx 仓库在某个领域是如何实现的"，自动处理项目创建、更新、研究全过程。
</purpose>

<philosophy>
**核心理念：问题驱动，即问即研，以分享角度记录。**

- 用户只关心问题，不关心项目创建细节
- 自动检测项目状态（新建/更新/直接研究）
- 研究结果自动沉淀到笔记
- 研究状态按"主题（topic）"持续归纳，不使用一次性完成态
- 支持同一主题下多问题、多轮产出按需追加
- 研究过程使用 Agent（subagent）执行，主会话负责项目管理和用户交互
- subagent 默认使用蓝色标识（研究任务），支持并行研究多个独立课题

### 双模式：Survey + Incremental

项目研究分为两种模式，产出分别放在不同文件夹：

| 模式 | 触发条件 | 产出目录 | 内容特征 |
|------|----------|----------|----------|
| **Survey**（系统调研） | 首次研究，`surveyState != "completed"` | `explorer/` | 成体系、有阅读路径、笔记间有因果链 |
| **Incremental**（增量问答） | survey 完成后，用户针对特定话题提问 | `notes/` | 零散、不成体系、随问随记 |

- `explorer/` 中的成体系笔记最终目标是打磨成可发布的教程
- `notes/` 中的零散笔记是知识积累，供参考但不形成叙事链路

### 四类产出目录

| 目录 | 命名规则 | 内容定位 | 何时生成 |
|------|---------|---------|---------|
| `explorer/` | `NN-xxx.md`（带 2 位编号） | 成体系教程、导读指南、架构分析 | Survey 模式 |
| `notes/` | `xxx.md`（不带编号） | 零散研究笔记、增量问答 | Incremental 模式 |
| `practices/` | `xxx-practice.md`（按主题命名） | **实操手册**：每步验证通过、输入输出完整可复现 | 增量问答中用户要求实操验证时 |
| `demos/` | `{demo-name}/`（目录工程） | 独立可运行的代码 demo | Phase 9 distill |

**practices/ 与其他目录的区别**：
- 不同于 `explorer/`（概念理解为主）— practices 重在**跑通命令**，每个步骤都有真实输出
- 不同于 `notes/`（知识积累）— practices 是**操作手册**，面向"拿来就能用"
- 不同于 `demos/`（代码工程）— practices 是**文档**，不是独立代码项目

### explorer 文件编号规则

**`explorer/` 目录下的笔记文件必须带 2 位索引前缀**，按阅读顺序编号：

```
explorer/
├── 00-xxx-environment-setup.md       ← 环境准备（安装、配置、前置依赖）
├── 01-xxx-how-to-use-guide.md        ← 第一篇（入口：快速上手）
├── 02-xxx-guide.md                   ← 第二篇（导读 / 架构概览）
├── 03-architecture-deep-dive.md      ← 第三篇（核心深入）
├── ...
└── README.md                         ← 索引文件，不需要编号
```

**规则**：
1. 格式：`{NN}-{原始文件名}.md`，NN 为两位数字（00, 01, 02, 03...）
2. **`00-` 固定保留给环境准备章节**（安装、配置、账号、网络等前置条件）。如果项目无需环境准备（纯代码分析），可跳过 00- 直接从 01- 开始
3. 编号反映阅读顺序：环境准备(00) → 先跑通(01) → 全景认知(02) → 核心链路(03+) → 辅助组件 → 设计思想
4. 新增文件时：扫描 `explorer/` 中已有的编号文件，取最大编号 +1（00- 位置仅用于环境准备，不参与自动递增）
5. `README.md` 和非 `.md` 文件不需要编号
6. `notes/` 目录不使用编号（零散笔记，无固定阅读顺序）

### 笔记质量评价体系

**核心原则：价值 = 认知落差**

知识点的价值不取决于技术通用性，而取决于「知道之前」和「知道之后」的理解差距。落差越大，越值得写。

| 层级 | 识别信号 | 典型表现 |
|------|---------|---------|
| **认知颠覆** | 范式转变、跨领域迁移 | "我完全没想到还能这样做" |
| **模式提炼** | 反复出现的结构、通用解法 | "原来这个就是 XXX 模式" |
| **工具积木** | 具体代码片段、配置模板 | "拿来就能用" |

### 笔记叙事原则

1. **问题驱动螺旋** — 每篇笔记存在是因为上一篇留下了问题，不是"接下来讲 X"
   ```
   遗留问题 → 尝试解决 → 新问题浮现 → 下一篇笔记
   ```

2. **对比驱动** — 痛点展示 → 方案揭示 → 原理解释 → 举一反三。不要先给答案。

3. **实操优先** — 小白如果不知道怎么用，就不会去思考原理。阅读顺序：环境准备(00) → 先用起来(01) → 再理解为什么(02+) → 最后深入细节

4. **每篇笔记声明定位** — 给谁看？解决什么问题？与相邻笔记的因果关系是什么？

### 写作原则
- 假设读者是零基础，不跳过基础概念
- 使用步骤化表达，每个步骤只做一件事
- 提供完整示例，代码片段要完整可运行

### article_id 强制规则

**每篇研究笔记的 frontmatter 必须包含唯一的 `article_id`**：

- 格式：`article_id: OBA-{8位随机小写字母数字}`
- 生成时机：笔记首次写入时立即生成，不可后补
- 全局唯一性：在 OB 仓库 wiki/ 下搜索确认无碰撞
- 每篇笔记只能有一个 article_id（禁止重复插入）
- article_id 是 Question.md 和笔记之间的桥梁，缺失会导致问题无法关联
</philosophy>

<trigger>
```
调研下 git@github.com:chris-hendrix/claudehub.git 在 Agent 通信方面是如何实现的
研究下 https://github.com/daymade/claude-code-skills 的 skill 设计模式
看看 get-shit-done 这个项目的 GSD workflow 是怎么设计的
学习下 claudehub 的 prompt engineering 技巧
```
</trigger>

## 工作流契约

需要核对完整阶段图、条件分支、checkpoint 或工具依赖时，读取 [references/workflow-contract.md](references/workflow-contract.md)。执行时仍以本文件的入口路由为起点，并在进入具体模式后按链接读取对应 reference。


## 入口路由 (route)

参数格式：`[子命令 | URL [问题]]`；子命令为 `list|status|update|sync|translate|distill|answer|continue`。

解析用户输入的 args，决定进入哪个 Phase：

**子命令检测优先级：** 先检查 args 是否匹配已知子命令，再按 URL/问题解析。

| args 匹配 | 进入 Phase | 说明 |
|------------|-----------|------|
| 空值 / `help` / `--help` | **显示帮助** | 输出命令速查表 |
| `list` | Phase 0 | 列出所有 study 项目 |
| `status` | Phase 1 | 检测当前项目状态并输出 |
| `update` | Phase 1 → Phase 3 | 强制更新源码 |
| `sync` | Phase 8 | 同步到 Obsidian |
| `translate` | Phase 8b | 并行翻译文档 |
| `distill` | Phase 9 | 蒸馏为 demo/设计文档 |
| `answer` | Phase 10 | 回答 Question.md 中的问题 |
| `continue` | Phase 7 | 恢复交互学习 |
| 含 URL 或仓库名 | Phase 1 → 自动流转 | 研究模式（默认） |

### 空值 / help

参数为空、为 `help` 或 `--help` 时，读取并使用 [references/help-output.md](references/help-output.md) 的输出模板，不进入研究流程。

## Phase 0: 列表 (list) — 可选

当用户使用 `/repo-study list` 时：

1. 读取 CLAUDE.md 中的 `GitHub 项目目录` 配置或 `$GITHUB_PROJECTS_DIR`（默认可为 `$HOME/jacky-github`）
2. 扫描该目录下所有匹配 `*-study` 的子目录
3. 对每个 study 目录，尝试读取 `.study-meta.json` 获取元数据
4. 输出表格：

| 项目名 | 来源仓库 | Topics 数 | 最后更新 |
|--------|----------|-----------|----------|
| xxx-study | owner/repo | N | YYYY-MM-DD |

5. 对于没有 `.study-meta.json` 的目录，标记为"手动创建"

---

## Phase 1: 检测 (detect)

### Step 1.0: 读取路径配置

读取当前会话加载的 CLAUDE.md 配置（已自动加载），获取：
- **GitHub 项目目录**: 从 CLAUDE.md 中读取 `GitHub 项目目录` 配置值
- 此目录作为所有 study 项目的**父目录**
- 如果配置不存在，使用当前工作目录作为父目录

> 注意：不要硬编码路径，始终从 CLAUDE.md 配置中读取。

### Step 1.1: 解析用户输入

从用户输入中提取仓库 URL、仓库名、研究问题、目标目录。

**URL 解析规则：**
```
git@github.com:user/repo.git → 仓库名: repo, owner: user
https://github.com/user/repo → 仓库名: repo, owner: user
```

### Step 1.2: 检测当前目录状态（仅当前目录）

**核心逻辑（不扫描子目录，不递归）：**
1. 检查当前目录名是否匹配 `*-study`
2. 检查当前目录是否存在 `.study-meta.json`
3. 识别项目来源（repo-study-managed / non-repo-study）
4. 如果是有效 study 项目，必须比对本地和远程 commit SHA
5. 若本地落后远程，先提示用户是否更新

> 📝 **详细检测流程和命令** → `references/state-templates.md`

### Step 1.2a: 文档资源扫描

在检测项目状态后，**扫描源码中的文档资源**（`docs/`、`README.md`、`CONTRIBUTING.md`、根目录 `*.md`），识别文档站类型（VitePress / Docsify / Docusaurus），并将结果传递给后续 Phase 用于产品认知建立和导读指南生成。

### Step 1.2b: Skill 项目检测

在文档资源扫描后，**检测源码中是否包含 SKILL.md 文件**：
1. 检查 `{源码目录}/SKILL.md` 是否存在
2. 若存在，标记项目为 `skill-type`
3. 从 SKILL.md 的 frontmatter 提取 `name` 和 `description`
4. 列出 SKILL.md 中引用的所有脚本路径（如 `scripts/` 目录下的文件）
5. 将 skill-type 标记传递给后续 Phase 用于针对性分析

### Step 1.3: 运行 status 脚本

```bash
scripts/repo-study-status.sh --json --check-remote
```

> 注意：该脚本现在位于 skill 自身目录中，无需在每个 study 项目中生成副本。

脚本输出包含：项目来源、topics 列表、进度统计、skill 封装状态、远程版本状态。

> 📝 **脚本输出格式** → `references/state-templates.md` §5

### Step 1.4: 版本落后时的用户提示

> ⚠️ **Checkpoint - Decision**
>
> 当 `remoteCheck.status == "outdated"` 时，必须提示用户选择更新或继续使用当前版本。

---

## Phase 2: 创建 (create) — 仅当项目不存在时

1. 在 GitHub 项目目录下创建 `{repo-name}-study` 目录（路径从 CLAUDE.md 读取）
2. 浅克隆源码：`git clone --single-branch --depth 1 "$REPO_URL" "$REPO_NAME"`
3. 删除 `.git` 目录
4. 创建 `explorer/` 和 `notes/` 目录
5. 生成 `CLAUDE.md`、`.study-meta.json`（v2，含 `surveyState: "pending"`）
6. **生成 `Question.md`** — 启动快速 subagent 扫描源码，生成 5-8 个 AI 预设研究问题（格式见 `references/question-template.md`）
7. 初始化 Git 仓库并首次提交

> ⚠️ **Checkpoint - Human-Verify** — 确保文件结构完整后初始化 Git 仓库。
> 📝 **元数据结构** → `references/state-templates.md` §4
> 📝 **Question.md 模板** → `references/question-template.md`

---

## Phase 3: 更新 (update) — 仅当项目不是最新时

1. 临时克隆最新代码到 `temp_clone`
2. 只更新源码目录，**保留 explorer/ 和 notes/ 目录**（永不删除）
3. 更新 `.study-meta.json` 中的 commit SHA
4. 删除临时目录

> ⚠️ **安全检查**: 更新前确认 explorer/ 和 notes/ 目录不会被删除。

---

## Phase 3.5: 模式检测 (mode_detect) — 自动判断

读取 `.study-meta.json` 的 `surveyState` 字段，决定进入哪种模式：

| surveyState | 模式 | 产出目录 | 说明 |
|-------------|------|----------|------|
| `null` / `pending` | **Survey** | `explorer/` | 首次系统调研，生成成体系笔记 |
| `completed` | **Incremental** | `notes/` | 已有调研基础，按需回答特定问题 |
| `in-progress` | **询问用户** | — | 之前的调研未完成，确认是继续还是切换 |

> **向后兼容**：对缺少 `surveyState` 字段的存量项目，如果 `explorer/` 或 `notes/` 中已有笔记，自动补充为 `"completed"`。

**分支逻辑**：
- Survey 模式 → 继续进入 Phase 4（选择 yolo/交互）
- Incremental 模式 → 直接进入 Phase 5c（增量问答）

---

## Phase 4: 模式选择 (mode_select) — 仅 Survey 模式

> ⚠️ **Checkpoint - Decision**
>
> 询问用户选择研究模式：
> 1. **Yolo 模式**（快速）— 直接输出完整研究发现
> 2. **交互模式**（教学）— 分步骤渐进式教学，每步确认理解

---

## Phase 5a: 研究 — Yolo 模式

用户选择 Survey + Yolo 后，必须依次读取：

1. [references/yolo-execution.md](references/yolo-execution.md)：文档感知、代码/Skill 映射、合并输出、Capability Discovery 与沉淀步骤。
2. [references/yolo-mode-guide.md](references/yolo-mode-guide.md)：完整 subagent prompt、输出模板与质量规则。

不得跳过 Capability Discovery；首次系统调研结束后按规则生成环境准备、导读与 Cheat Sheet。

## Phase 5b: 研究 — 交互模式

> 📖 **详细文档** → `references/interactive-mode-guide.md`

核心流程：文档感知 subagent + 代码分析 subagent → 概念拆解 → 逐步讲解 → 实时归档。

- 启动 subagent 静默分析代码，主会话创建 `.study-session.json` 和概念列表
- 逐步讲解每个概念，每步后提供选项：继续/暂停/更多解释/提问
- 实时归档到 `explorer/`，支持 `/repo-study continue` 恢复中断
- 首次研究时：环境准备章节（00-，如需）+ 强制生成导读指南（模板同 Phase 5a）
- 完成后设置 `surveyState = "completed"`

> ⚠️ **Checkpoint - Human-Verify** — 调研完成后确认概念列表再开始讲解。

---

## Phase 5c: 增量问答 (incremental) — Incremental 模式

> 适用场景：survey 完成后，用户针对特定话题/文章提问。
> 产出目录：`notes/`（零散笔记，不成体系）

### Step 5c.1: 解析增量问题

从用户输入中提取具体的研究问题，确定需要分析的代码区域。

### Step 5c.2: 启动针对性 subagent

启动 subagent（蓝色标识，Explore 类型），**只分析相关代码区域**，不重复 survey 已覆盖的内容。

> 📝 **subagent prompt 模板** → `references/yolo-mode-guide.md` §4

### Step 5c.3: 写入笔记

将研究结果写入 `notes/{topic-slug}.md`，命名简洁直接（如 `skill-prompt-engineering.md`）。

**写入时立即生成 `article_id` 并写入 frontmatter**（格式：`OBA-{8位随机小写字母数字}`，全局唯一性校验）。

笔记结构：
```markdown
# {话题标题}

> 关联教程：explorer/{related-tutorial-note}.md（如有）

## 问题
// 用户原始问题

## 分析
// 针对性分析内容

## 关键发现
// 核心洞察，1-3 点
```

### Step 5c.4: 更新元数据

更新 `.study-meta.json`：
- 在 `topics[]` 中新增条目，标记 `location: "notes"`
- 更新 `lastUpdated` 时间戳

**更新 Question.md**：对本次新建的笔记，检查其 `article_id` 是否已在 Question.md 中有对应 section，若没有则在末尾追加：
```
## {article_id}
<!-- {笔记相对路径} -->












```
（8 行空白用于用户后续编辑。格式参考 `references/question-template.md`）

---

## Phase 5.5: 自动同步检测 (auto-sync) — 研究完成后自动触发

> **触发时机**：Phase 5a（Yolo）、5b（交互）、5c（增量）完成后自动执行。
> **目的**：减少用户手动同步的心智负担，让笔记自动流入 Obsidian 知识库。

### Step 5.5.1: 检测 Obsidian 配置

从 CLAUDE.md 配置中检测 `OBSIDIAN_REPO` 是否存在且路径有效：

```bash
# 检查 Obsidian 仓库路径是否配置且存在
test -d "$OBSIDIAN_REPO" && echo "ob_available" || echo "ob_unavailable"
```

- 若 `OBSIDIAN_REPO` 未配置或路径不存在 → **跳过**，不提示用户
- 若路径有效 → 进入 Step 5.5.2

### Step 5.5.2: 询问用户是否同步

使用 AskUserQuestion 询问用户：

> **问题**：检测到 Obsidian 仓库已配置，是否将本次新生成/更新的笔记同步到 Obsidian？
>
> | 选项 | 说明 |
> |------|------|
> | 是，同步到 Obsidian | 执行 Phase 8 的同步流程（仅当前项目） |
> | 否，稍后手动同步 | 跳过，用户可通过 `/repo-study sync` 手动触发 |
> | 本次会话不再询问 | 标记会话状态，后续增量问答时不再提示 |

### Step 5.5.3: 执行同步（仅当前项目）

用户选择"是"时，执行 **当前项目** 的同步（不等同于 `/repo-study sync` 的全量同步）：

1. 为本次新生成/更新的笔记分配 `article_id`（`OBA-xxx`）
2. 在 Obsidian 仓库创建 symlink：
   - `wiki/open-source/{project}/explorer` → `{study项目}/explorer`
   - `wiki/open-source/{project}/notes` → `{study项目}/notes`
   - `wiki/open-source/{project}/practices` → `{study项目}/practices`（如存在）
   - `wiki/open-source/{project}/Question.md` → `{study项目}/Question.md`（如存在）
3. 生成/更新 `wiki/open-source/{project}/index.md` 概述页
4. 更新 `wiki/open-source/index.md` 总索引
5. 输出同步结果摘要

### Step 5.5.4: 会话状态标记

用户选择"本次会话不再询问"时，在会话上下文中标记 `skip_ob_sync = true`，后续 Phase 5c 增量问答完成时不再触发自动同步提示。

> ⚠️ **注意**：此标记仅在当前 Claude Code 会话中有效，新会话会重新检测。

---

## Phase 7: 恢复学习 (continue) — 可选

1. 检查 `.study-session.json` 是否存在
2. 读取并显示上次进度和待讲解概念
3. 用户确认后从下一个概念继续

---

## Phase 6: 产出选择 (output)

> ⚠️ **Checkpoint - Decision**
>
> 研究完成后询问用户：
> 1. 继续深入研究 → 返回 Phase 5
> 2. 生成实操指南 → `explorer/NN-{主题}-guide.md`（成体系，带编号）
> 3. **生成教程** → 进入 Phase 6b（教程两阶段工作流，产出到 `explorer/`，带编号）
> 4. 生成 Skill 模板 → `notes/{主题}-skill.md`（零散笔记）
> 5. **生成 Cheat Sheet** → 进入 Phase 6d（专属 subagent，产出到 `explorer/cheatsheet/`）
> 6. 生成小白指南 → `explorer/NN-{repo-name}-beginner-guide.md`（成体系，带编号）
> 7. **生成技术展示文章** → 进入 Phase 6c（产出到 `notes/`）
> 8. **生成 Skill 映射** → `notes/{repo-name}-skill-to-script-mapping.md`（零散笔记）
> 9. **生成实操手册** → 进入 Phase 6e（产出到 `practices/`，每步实测验证）
> 10. 全部生成

最后更新研究日志 `explorer/RESEARCH-LOG.md` 并同步 `topics[].progress`。

**产出路径规则**：
- 环境准备（安装、配置、前置依赖）→ `explorer/00-{repo-name}-environment-setup.md`（**00- 固定前缀**，工具/CLI/库项目必须生成）
- 成体系的内容（指南、教程、小白指南）→ `explorer/`（**文件名带 2 位索引前缀，从 01- 起**）
- 速查卡片（Cheat Sheet）→ `explorer/cheatsheet/`（**不带编号**，每维度一份）
- 零散/独立的内容（文章、Skill 映射）→ `notes/`（不带编号）
- 实操手册（每步验证通过的操作指南）→ `practices/`（**不带编号**，按主题命名，如 `{topic}-practice.md`）

---

## 高级产出与维护流程

进入以下阶段前，必须读取 [references/advanced-modes-and-checks.md](references/advanced-modes-and-checks.md) 的对应章节：

- Phase 6b/6c/6e：教程、技术展示文章、实操手册
- Phase 8/8b：Obsidian 同步、文档翻译
- Phase 9/10：蒸馏、Question.md 问答
- 最终验收：成功标准与完整参考文档索引

只加载当前任务需要的章节；各模式进一步引用的专属 reference 也必须按章节要求读取。

## ⚠️ 用户交互点总结

| 阶段 | 交互点 | 类型 | 用户操作 |
|------|--------|------|----------|
| Phase 1 | 🛑 版本落后提示 | Decision | 选择是否更新源码 |
| Phase 3.5 | 🔄 模式检测 | Auto | 根据 surveyState 自动判断 |
| Phase 3.5 | 🔄 调研中断确认 | Decision | 仅 surveyState="in-progress" 时，继续/切换 |
| Phase 2 | ✅ 文件结构验证 | Human-Verify | 确认文件结构完整（含 explorer/ 和 notes/） |
| Phase 4 | 🔄 研究风格选择 | Decision | 选择 Yolo/交互模式（仅 Survey 模式） |
| Phase 5b | ✅ 调研完成确认 | Human-Verify | 确认概念列表 |
| Phase 5b | 🔄 理解确认 | Decision | 继续/暂停/更多解释/提问 |
| Phase 5.5 | 🔄 自动同步提示 | Decision | 检测到 Obsidian 时自动询问是否同步（仅当前项目）/跳过/不再询问 |
| Phase 5d | 🔄 实操验证 | Decision | 用户要求实操验证时进入 Phase 5d/6e |
| Phase 6 | 🔄 产出选择 | Decision | 继续研究/指南/教程/模板/Cheat Sheet/小白指南/技术展示文章/Skill 映射/实操手册/全部 |
| Phase 6b-T1 | ✅ 配置完成确认 | Human-Verify | 用户完成所有配置步骤，检查清单全通过 |
| Phase 6b-T2 | 🔄 实测结果审核 | Human-Verify | 确认实测数据，处理失败的命令 |
| Phase 7 | 🔄 恢复确认 | Decision | 继续/重新开始 |
| Phase 10 | 🔄 问题选择 | Decision | 全部回答/选择部分回答/取消 |