git:20260426.1a07699 to git:20260427.39b4c24

---

name: repo-study

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

---

<role>

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

</role>

<purpose>

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

</purpose>

<philosophy>

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

- 用户只关心问题，不关心项目创建细节

- 自动检测项目状态（新建/更新/直接研究）

- 研究结果自动沉淀到笔记

- 研究状态按"主题（topic）"持续归纳，不使用一次性完成态

- 支持同一主题下多问题、多轮产出按需追加

- 研究过程使用 Agent（subagent）执行，主会话负责项目管理和用户交互

- subagent 默认使用蓝色标识（研究任务），支持并行研究多个独立课题

### 双模式：Survey + Incremental

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

| 模式 | 触发条件 | 产出目录 | 内容特征 |

|------|----------|----------|----------|

| **Survey**（系统调研） | 首次研究，`surveyState != "completed"` | `explorer/` | 成体系、有阅读路径、笔记间有因果链 |

| **Incremental**（增量问答） | survey 完成后，用户针对特定话题提问 | `notes/` | 零散、不成体系、随问随记 |

- `explorer/` 中的成体系笔记最终目标是打磨成可发布的教程

- `notes/` 中的零散笔记是知识积累，供参考但不形成叙事链路

### 笔记质量评价体系

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

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

| 层级 | 识别信号 | 典型表现 |

|------|---------|---------|

| **认知颠覆** | 范式转变、跨领域迁移 | "我完全没想到还能这样做" |

| **模式提炼** | 反复出现的结构、通用解法 | "原来这个就是 XXX 模式" |

| **工具积木** | 具体代码片段、配置模板 | "拿来就能用" |

### 笔记叙事原则

1. **问题驱动螺旋** — 每篇笔记存在是因为上一篇留下了问题，不是"接下来讲 X"

```

遗留问题 → 尝试解决 → 新问题浮现 → 下一篇笔记

```

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

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

### 写作原则

- 假设读者是零基础，不跳过基础概念

- 使用步骤化表达，每个步骤只做一件事

- 提供完整示例，代码片段要完整可运行

</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>

<!-- ========== GSD Workflow XML 结构 ========== -->

<gsd:workflow>

<gsd:meta>

<name>repo-study</name>

<trigger>调研下、研究下、学习下、看看 xxx 仓库、分析开源项目、repo-study</trigger>

<requires>git, gh, Agent (subagent), Claude Code tools (Glob, Grep, Read, Write, Edit)</requires>

</gsd:meta>

<gsd:goal>让用户用自然语言提问，自动完成项目初始化/更新/研究全过程，并按主题沉淀可复用研究资产</gsd:goal>

<gsd:phase name="list" order="0" condition="用户使用 /repo-study list">

<gsd:step>读取 CLAUDE.md 中的 GitHub 项目目录配置</gsd:step>

<gsd:step>扫描该目录下所有 *-study 子目录</gsd:step>

<gsd:step>读取每个项目的 .study-meta.json（如存在）</gsd:step>

<gsd:step>输出项目列表表格</gsd:step>

</gsd:phase>

<gsd:phase name="detect" order="1">

<gsd:step>解析仓库 URL 和研究问题</gsd:step>

<gsd:step>仅在当前目录检测 study 标识（目录名和 .study-meta.json）</gsd:step>

<gsd:step>判断当前项目是否由 repo-study 创建（v2）</gsd:step>

<gsd:step>扫描源码中的文档资源：docs/ 目录、README.md、CONTRIBUTING.md、*.md 指南文件</gsd:step>

<gsd:step condition="源码中存在 SKILL.md 文件">标记项目为 skill-type（该项目本身是一个 Claude Code Skill），提取 skill 名称和描述</gsd:step>

<gsd:step>若存在有效项目，强制检查 GitHub 远程版本是否最新</gsd:step>

<gsd:step condition="本地版本落后">先提示用户是否更新，再决定 update / research 分支</gsd:step>

<gsd:step>执行 status 脚本汇总课题、进度、skill 封装状态</gsd:step>

<gsd:checkpoint>根据检测结果选择分支：create / update / research</gsd:checkpoint>

</gsd:phase>

<gsd:phase name="create" order="2" condition="项目不存在">

<gsd:step>创建项目目录结构</gsd:step>

<gsd:step>克隆源码（single-branch + depth 1）</gsd:step>

<gsd:step>删除源码的 .git 目录</gsd:step>

<gsd:step>生成 CLAUDE.md 和元数据</gsd:step>

<gsd:step>初始化 Git 仓库</gsd:step>

</gsd:phase>

<gsd:phase name="update" order="3" condition="项目存在但不是最新">

<gsd:step>询问用户是否更新</gsd:step>

<gsd:step>更新源码到最新版本</gsd:step>

</gsd:phase>

<gsd:phase name="mode_detect" order="3.5">

<gsd:step>读取 .study-meta.json 的 surveyState 字段</gsd:step>

<gsd:step condition="surveyState 为 null 或 pending">标记为 Survey 模式，产出目录为 explorer/</gsd:step>

<gsd:step condition="surveyState 为 completed">标记为 Incremental 模式，产出目录为 notes/</gsd:step>

<gsd:step condition="surveyState 为 in-progress">询问用户：继续 survey / 切到 incremental</gsd:step>

<gsd:checkpoint>根据 surveyState 决定进入 Survey 分支或 Incremental 分支</gsd:checkpoint>

</gsd:phase>

<gsd:phase name="mode_select" order="4" condition="Survey 模式">

<gsd:step>询问用户选择研究模式</gsd:step>

<gsd:step>yolo 模式：直接输出完整研究发现</gsd:step>

<gsd:step>交互模式：渐进式教学，分步骤讲解</gsd:step>

<gsd:checkpoint>根据用户选择进入对应分支</gsd:checkpoint>

</gsd:phase>

<gsd:phase name="research_yolo" order="5" condition="选择 yolo 模式（Survey）">

<gsd:step>切换到项目目录</gsd:step>

<gsd:step>若源码存在文档资源（docs/、README.md 等），先启动文档感知 subagent 扫描并提取产品认知和用户指南信息</gsd:step>

<gsd:step>启动代码分析 subagent（蓝色标识，Explore 类型）执行代码分析</gsd:step>

<gsd:step condition="项目为 skill-type">启动 skill 映射 subagent：分析 SKILL.md 各 section 与脚本的对应关系，验证每个脚本可独立运行</gsd:step>

<gsd:step condition="多独立课题">并行启动多个 subagent 研究不同课题</gsd:step>

<gsd:step>主会话合并文档感知 + 代码分析结果，按"产品认知 → 核心概念(含Why) → 代码原理"层次输出完整研究发现</gsd:step>

<gsd:step condition="用户使用中文提问">提示翻译功能</gsd:step>

</gsd:phase>

<gsd:phase name="research_interactive" order="5b" condition="选择交互模式（Survey）">

<gsd:step>调研阶段：若源码存在文档资源，先启动文档感知 subagent 扫描产品认知信息</gsd:step>

<gsd:step>启动代码分析 subagent（蓝色标识）静默分析代码</gsd:step>

<gsd:step>主会话合并文档感知 + 代码分析结果，创建会话状态和概念列表</gsd:step>

<gsd:step>概念列表按"产品认知 → 核心概念(含Why) → 代码原理"层次排列</gsd:step>

<gsd:step>概念拆解：将研究发现拆分为多个小概念</gsd:step>

<gsd:step>逐步讲解：每次只讲一个概念</gsd:step>

<gsd:step>理解确认：询问用户下一步选择</gsd:step>

<gsd:step condition="需要更多解释">补充解释和示例</gsd:step>

<gsd:step condition="继续">进入下一个概念</gsd:step>

<gsd:step condition="暂停">保存进度到会话状态文件</gsd:step>

<gsd:step>总结确认：所有概念讲解完毕后询问是否需要完整笔记</gsd:step>

</gsd:phase>

<gsd:phase name="research_incremental" order="5c" condition="Incremental 模式">

<gsd:step>解析用户的增量问题</gsd:step>

<gsd:step>启动针对性 subagent（只分析相关代码区域）</gsd:step>

<gsd:step>写入 notes/{topic-slug}.md</gsd:step>

<gsd:step>更新 .study-meta.json 的 topics[]（location: "notes"）</gsd:step>

</gsd:phase>

<gsd:phase name="continue" order="7" condition="用户使用 /repo-study continue">

<gsd:step>检查会话状态：读取 .study-session.json</gsd:step>

<gsd:step>显示进度：展示上次进度和待讲解概念</gsd:step>

<gsd:step>继续学习：从下一个待讲解概念继续交互学习</gsd:step>

</gsd:phase>

<gsd:phase name="sync" order="8" condition="用户使用 /repo-study sync">

<gsd:step>读取 CLAUDE.md 中的 GitHub 项目目录和 Obsidian 仓库路径</gsd:step>

<gsd:step>扫描所有 *-study 项目的 explorer/ 和 notes/ 目录</gsd:step>

<gsd:step>为缺少 article_id 的笔记自动分配 OBA-xxx（全局唯一、8位随机小写字母数字）</gsd:step>

<gsd:step>为每个有笔记的项目在 OB 的 wiki/open-source/ 下创建 symlink（覆盖 explorer/ 和 notes/）</gsd:step>

<gsd:step>生成/更新每个项目的 index.md 概述页（含笔记列表和 article_id）</gsd:step>

<gsd:step>更新 open-source/index.md 总索引</gsd:step>

</gsd:phase>

<gsd:phase name="translate" order="8b" condition="用户使用 /repo-study translate">

<gsd:step>运行 scripts/repo-study-translate.sh 生成翻译任务清单（source → source.zh.md）</gsd:step>

<gsd:step>按 group 字段将任务分组，默认每组 20 个文件</gsd:step>

<gsd:step>并行启动 subagent（每组一个）执行翻译，直接写入目标 *.zh.md 文件</gsd:step>

<gsd:step>subagent 必须保留 frontmatter、标题层级、代码块、链接与表格结构</gsd:step>

<gsd:step>默认跳过已存在的 *.zh.md（可通过 --force 重新翻译）</gsd:step>

<gsd:step>严格禁止修改源文件 *.md，仅允许新增/覆盖 *.zh.md</gsd:step>

<gsd:step>主会话汇总 subagent 执行结果并输出成功/失败清单</gsd:step>

</gsd:phase>

<gsd:phase name="distill" order="9" condition="user uses /repo-study distill">

<gsd:step>Read .study-meta.json backlog[] array</gsd:step>

<gsd:step>Prioritize pending items by priority field (high/medium/low)</gsd:step>

<gsd:step>For each item, show: id, title, type, priority, sourceNote</gsd:step>

<gsd:step>User selects item to distill (or accepts suggestion)</gsd:step>

<gsd:step condition="type=demo">Create demo folder under demos/ with package.json, index.mjs, README.md</gsd:step>

<gsd:step condition="type=skill-design">Generate skill design note under notes/（增量笔记）</gsd:step>

<gsd:step>Update backlog item status to in-progress then done</gsd:step>

<gsd:step>Add demo artifact to parent topic's artifacts[]</gsd:step>

<gsd:step>Verify demo runs independently (cd demos/xxx && npm install && node index.mjs)</gsd:step>

</gsd:phase>

<gsd:phase name="output" order="6">

<gsd:step>询问用户下一步：继续研究 / 生成实操指南 / 生成教程 / 生成 Skill 模板 / 生成 Cheat Sheet / 生成小白指南 / 生成技术展示文章 / 生成 Skill 映射 / 全部生成</gsd:step>

<gsd:step condition="选择教程或全部">进入 Phase 6b（教程两阶段工作流，产出到 explorer/）</gsd:step>

<gsd:step condition="选择模板或全部">生成 notes/{主题}-skill.md（可复用的 Skill 模板，零散笔记）</gsd:step>

<gsd:step condition="选择 skill 映射或全部">生成 notes/{repo-name}-skill-to-script-mapping.md（skill→script 映射，零散笔记）</gsd:step>

<gsd:step>更新研究日志 notes/RESEARCH-LOG.md</gsd:step>

</gsd:phase>

<gsd:phase name="tutorial" order="6b" condition="用户选择生成教程">

<gsd:meta>

<name>tutorial-two-phase</name>

<description>教程两阶段工作流：配置引导（人工）+ 逐章实测（sub-agent 自动化）</description>

<requires>Agent (subagent), Bash</requires>

</gsd:meta>

<gsd:phase name="tutorial_phase1" order="1">

<gsd:step>生成 Phase 1 环境配置引导：安装、Chrome 扩展、登录、网络确认</gsd:step>

<gsd:step>每步包含：操作说明 → 验证命令 → 完成标志 → 常见问题</gsd:step>

<gsd:step>需要人工操作的步骤用 ⚠️ 标记</gsd:step>

<gsd:step>底部放检查清单，全部通过才能进入 Phase 2</gsd:step>

<gsd:step>引导用户逐步完成配置，每步验证后再进入下一步</gsd:step>

<gsd:checkpoint>Phase 1 检查清单全部通过后，才能进入 Phase 2</gsd:checkpoint>

</gsd:phase>

<gsd:phase name="tutorial_phase2" order="2" condition="Phase 1 检查清单全部通过">

<gsd:step>将教程拆分为独立章节（按认证模式或功能模块划分）</gsd:step>

<gsd:step>每章标注：状态（待实测）、认证模式（public/cookie/browser）、前置条件</gsd:step>

<gsd:step>所有命令的输出使用占位符标记，不写"预期输出"</gsd:step>

<gsd:step>派 sub-agent 逐章测试（每章一个 agent，3 章一组并行）</gsd:step>

<gsd:step>每个 sub-agent 返回格式化测试报告：命令 → 实际输出 → 状态</gsd:step>

<gsd:step>主 agent 收集报告，替换占位符为实测数据</gsd:step>

<gsd:step>标注已知问题和替代方案</gsd:step>

</gsd:phase>

</gsd:phase>

<gsd:phase name="article" order="6c" condition="用户选择生成技术展示文章">

<gsd:meta>

<name>article-showcase</name>

<description>生成面向掘金/知乎等技术社区的技术展示文章，以研究者第三人称视角呈现设计洞察</description>

<requires>Agent (subagent), Read, Write</requires>

</gsd:meta>

<gsd:phase name="article_collect" order="1">

<gsd:step>读取 explorer/ 和 notes/ 下所有已有研究笔记作为素材</gsd:step>

<gsd:step>读取源码中的 README、SKILL.md 等项目自述文档</gsd:step>

<gsd:step>识别项目的认知颠覆点和设计哲学</gsd:step>

<gsd:step>汇总素材清单（研究笔记 + 项目文档 + 核心洞察）</gsd:step>

</gsd:phase>

<gsd:phase name="article_generate" order="2">

<gsd:step>启动文章生成 subagent（Explore 类型），使用 article-mode-guide.md 的 prompt 模板</gsd:step>

<gsd:step>subagent 输入：研究笔记摘要 + 项目文档 + 文章叙事模板</gsd:step>

<gsd:step>subagent 输出：完整技术展示文章（3000-5000 字 Markdown）</gsd:step>

</gsd:phase>

<gsd:phase name="article_check" order="3">

<gsd:step>对照 article-mode-guide.md §4 质量检查清单验证文章</gsd:step>

<gsd:step>确认叙事弧线完整（6 段式）</gsd:step>

<gsd:step>确认技术深度分层（入门 → 进阶 → 深入）</gsd:step>

<gsd:step>确认有研究者洞察（非纯客观转述）</gsd:step>

</gsd:phase>

<gsd:phase name="article_save" order="4">

<gsd:step>写入 notes/{repo-name}-article.md（文章为非教程性质，放入 notes/）</gsd:step>

<gsd:step>更新 .study-meta.json topics[] 进度</gsd:step>

<gsd:step>在文章 frontmatter 中标注素材来源笔记</gsd:step>

</gsd:phase>

</gsd:phase>

</gsd:workflow>

<!-- ========== 执行流程 ========== -->

<process>

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

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

1. 读取 CLAUDE.md 中的 `GitHub 项目目录` 配置（如 `/Users/jiashengwang/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"`）

> ⚠️ **Checkpoint - Human-Verify** — 确保文件结构完整后初始化 Git 仓库。

> 📝 **元数据结构** → `references/state-templates.md` §4

---

## 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 模式

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

### Step 5a.1: 文档感知（如果项目有文档）

若 Phase 1 检测到项目有文档资源（docs/、README 等），先启动**文档感知 subagent**（Explore 类型），提取产品形态、安装方式、核心组件、文档结构和用户指南摘要。

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

### Step 5a.2: 代码分析

启动 subagent（蓝色标识，Explore 类型）执行代码分析。

### Step 5a.2b: Skill 映射分析（skill-type 项目）

当 Phase 1 检测到项目为 skill-type 时，启动**skill 映射 subagent**（Explore 类型）：

**分析内容**：

1. 读取 SKILL.md，提取每个能力 section（如"前置检查""CDP 操作""本地资源"等）

2. 找出每个 section 引用的脚本文件（`scripts/` 目录下的 .mjs/.sh 等）

3. 分析每个脚本的核心机制（输入→处理→输出）

4. 列出完整触发链路：SKILL.md section → 脚本 → 工作流

**验收验证**（如环境允许）：

1. 逐个运行脚本，记录输出

2. 对浏览器类脚本，测试完整的 tab 生命周期（创建→操作→关闭）

3. 汇总验收结果（通过/失败/跳过）

### Step 5a.3: 结果合并与输出

主会话按以下层次合并输出：

1. **产品认知**（来自文档感知 subagent）

2. **核心概念 + 前因后果**（来自文档 + 代码综合分析）

3. **代码原理**（来自代码分析 subagent）

### Step 5a.4: 沉淀与指南

> 📝 **导读指南完整模板** → `references/guide-template.md`

> 📝 **subagent prompt 模板、输出模板** → `references/yolo-mode-guide.md` §1-3

>

> ⚠️ **强制规则**：每个项目首次研究时必须生成导读指南，不可跳过。指南是 explorer/ 的入口文档。

---

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

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

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

- 启动 subagent 静默分析代码，主会话创建 `.study-session.json` 和概念列表

- 逐步讲解每个概念，每步后提供选项：继续/暂停/更多解释/提问

- 实时归档到 `explorer/`，支持 `/repo-study continue` 恢复中断

- 完成后设置 `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`）。

笔记结构：

```markdown

# {话题标题}

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

## 问题

// 用户原始问题

## 分析

// 针对性分析内容

## 关键发现

// 核心洞察，1-3 点

```

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

更新 `.study-meta.json`：

- 在 `topics[]` 中新增条目，标记 `location: "notes"`

- 更新 `lastUpdated` 时间戳

---

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

1. 检查 `.study-session.json` 是否存在

2. 读取并显示上次进度和待讲解概念

3. 用户确认后从下一个概念继续

---

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

> ⚠️ **Checkpoint - Decision**

>

> 研究完成后询问用户：

> 1. 继续深入研究 → 返回 Phase 5

> 4. 生成 Skill 模板 → `notes/{主题}-skill.md`（零散笔记）

> 7. **生成技术展示文章** → 进入 Phase 6c（产出到 `notes/`）

> 8. **生成 Skill 映射** → `notes/{repo-name}-skill-to-script-mapping.md`（零散笔记）

> 9. 全部生成

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

**产出路径规则**：

---

## Phase 6b: 教程两阶段工作流 (tutorial)

> 适用场景：研究的项目是工具/CLI/库，需要可执行教程时使用。

>

> 📖 **完整教程工作流文档** → `references/tutorial-workflow.md`

---

## Phase 6c: 技术展示文章 (article)

> 适用场景：将研究成果对外分享到掘金/知乎等技术社区。

> 产出文件：`notes/{repo-name}-article.md`（非教程性质）

> 前置条件：至少完成过一轮研究（explorer/ 中有研究笔记）

>

> 📖 **完整文章模式指南** → `references/article-mode-guide.md`

### Step 6c.1: 研究素材收集

1. 读取 `explorer/` 和 `notes/` 目录下所有已有研究笔记

2. 读取源码中的 README、SKILL.md 等项目自述文档

3. 识别项目的「认知颠覆点」和「设计哲学」

4. 汇总素材清单

### Step 6c.2: 启动文章生成 subagent

使用 `references/article-mode-guide.md` §3 的 subagent prompt 模板，启动 Explore 类型 subagent 生成文章。

**输入**：

- 已有研究笔记内容摘要

- 项目自述文档关键内容

- 文章叙事模板（6 段式）

**输出**：

- 完整的面向技术社区的展示文章（3000-5000 字 Markdown）

### Step 6c.3: 质量检查

对照 `references/article-mode-guide.md` §4 质量检查清单逐项验证。

### Step 6c.4: 沉淀文章

1. 写入 `notes/{repo-name}-article.md`（文章为非教程性质，放入 notes/）

2. 更新 `.study-meta.json` 的 `topics[]` 进度

3. 在文章 frontmatter 中标注素材来源笔记

---

## Phase 8: 同步到 Obsidian (sync)

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

1. 读取 CLAUDE.md 配置中的 `OBSIDIAN_REPO` 和 `GitHub 项目目录`

2. 目标目录：`{OBSIDIAN_REPO}/wiki/open-source/`

3. 扫描 `{GitHub 项目目录}/*-study` 下所有项目

4. **为缺少 `article_id` 的笔记自动分配 `OBA-xxx`**：

- 格式：`OBA-{8位随机小写字母数字}`

- 全局唯一性校验：在 OB 仓库 wiki/ 下搜索确认无碰撞

- 生成后写入 frontmatter（无 frontmatter 时自动创建）

5. 对每个有笔记的项目：

- 创建 `wiki/open-source/{project}/notes` symlink → `{study项目}/notes`

- 若 `index.md` 不存在，生成仓库概述页（含笔记列表和 article_id）

6. 重新生成 `wiki/open-source/index.md` 总索引

7. 输出同步结果摘要

> 📝 **同步脚本** → `scripts/repo-study-sync-ob.sh`（支持 `--dry-run` 和 `--project` 参数）

---

## Phase 8b: 文档翻译 (translate)

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

1. 在 study 项目根目录运行翻译计划脚本：

```bash

scripts/repo-study-translate.sh --json

```

2. 读取任务清单中的 `tasks[]`（字段：`source`、`target`、`group`）

约束：`target` 必须是 `source` 对应的 `*.zh.md`

3. 按 `group` 字段并行派发 subagent（每组一个），只读源文件，只写目标 `*.zh.md`，禁止修改源文件

4. 默认跳过已存在的 `*.zh.md`

若用户明确要求全量重译，使用：

```bash

scripts/repo-study-translate.sh --json --force

```

6. 主会话收集各 subagent 结果并输出：

- 成功翻译数

- 失败文件列表（含错误原因）

- 跳过文件数（已存在）

> 📝 **翻译计划脚本** → `scripts/repo-study-translate.sh`（支持 `--json`、`--force`、`--group-size`）

>

> 📝 **subagent prompt 模板与质量规则** → `references/translate-mode-guide.md`

---

## Phase 9: 蒸馏 (distill)

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

### Step 9.1: 读取 Backlog

读取 `.study-meta.json` 的 `backlog[]` 数组，按 `priority` 排序（high > medium > low），过滤 `status: "pending"` 的条目。

### Step 9.2: 展示待蒸馏列表

以表格展示（ID / 标题 / 类型 / 优先级 / 来源笔记），用户选择条目。

### Step 9.3: 创建 Demo 工程（type=demo）

创建 `demos/{demo-name}/`（含 `package.json` + `index.mjs` + `README.md`）。README 需包含：学习目的、验证知识点、功能清单（MUST/SHOULD/COULD）、运行命令、预期输出。

验证独立运行：`cd demos/{name} && npm install && node index.mjs`

### Step 9.4: 创建设计文档（type=skill-design）

为 `skill-design` 类型的条目在 `notes/` 下生成 skill 设计文档。

### Step 9.5: 更新状态

更新 `backlog[]` 状态（`pending` → `in-progress` → `done`），更新 `demoPath`，将 artifact 添加到关联 topic 的 `artifacts[]`。

### 添加条目到 Backlog

在 Phase 5a/5b 研究过程中，当发现**可复用、自包含的模式**时，应自动追加到 `backlog[]`：

- **ID 格式**：`bl-{NNN}`，从当前最大值递增

- **type**：`demo`（代码模式）/ `skill-design`（设计概念）/ `note`（文档补充）

- **priority**：根据通用性和复杂度判定 `high` / `medium` / `low`

- **sourceNote**：指向发现该模式的研究笔记路径

</process>

<!-- ========== 命令速查 ========== -->

<commands>

| 命令 | 说明 |

|------|------|

| `/repo-study <url> <问题>` | 研究 GitHub 仓库的特定问题（自动判断 Survey/Incremental 模式） |

| `/repo-study list` | 列出 GitHub 项目目录下所有 xxx-study 项目 |

| `/repo-study status` | 检查当前目录状态（topics、进度、skill 封装状态、当前模式） |

| `/repo-study continue` | 恢复上次中断的交互学习 |

| `/repo-study sync` | 同步所有 study 项目到 Obsidian（article_id 分配 + symlink + 索引） |

| `/repo-study distill` | 将研究发现转化为独立 demo 工程或设计文档 |

</commands>

<!-- ========== 四种场景速查 ========== -->

<scenarios>

```

/repo-study 场景速查：

场景 0: list → 列出所有 *-study 项目

场景 1-3: detect → create / update / skip（自动判断）

场景 3.5: mode → Survey（首次，产出→explorer/）/ Incremental（增量，产出→notes/）

场景 4: style → yolo（快速研究）/ interactive（交互教学）——仅 Survey 模式

场景 5: research → Survey→explorer/ | Incremental→notes/

场景 6: output → 指南 / 教程 / 模板 / Cheat Sheet / 小白指南 / 技术展示文章 / Skill 映射 / 全部

安全保障：explorer/ 和 notes/ 永不删除 | 版本检查：gh api commit SHA

```

</scenarios>

<!-- ========== 成功标准 ========== -->

<success_criteria>

- [ ] 正确解析仓库 URL，项目路径从 CLAUDE.md 读取

- [ ] 检测 study 标识（目录名 + .study-meta.json），使用 gh api 检查远程版本

- [ ] 项目创建时包含 explorer/ 和 notes/ 两个目录

- [ ] 项目创建/更新时，explorer/ 和 notes/ 目录永不删除

- [ ] 双模式检测：根据 surveyState 自动判断 Survey/Incremental 模式

- [ ] Incremental 模式：产出零散笔记到 notes/，针对用户问题分析

- [ ] 文档资源扫描：检测 docs/、README.md 等文档并分类

- [ ] 教程两阶段分离：T1 配置引导（人工）+ T2 逐章实测（subagent）

- [ ] 技术展示文章：素材收集 → subagent 生成 → 质量检查 → 沉淀到 notes/

- [ ] 翻译：*.md → *.zh.md，不修改源文件，按 group 并行

- [ ] distill：backlog → 独立可运行的 demo 工程

- [ ] Skill 项目检测：检测 SKILL.md 存在时标记为 skill-type，提取 skill 名称和脚本列表

- [ ] skill-type 项目：自动生成 skill→script 映射分析 + 脚本验收测试

</success_criteria>

<!-- ========== 参考文档 ========== -->

<references>

| 文件 | 用途 |

|------|------|

| `references/state-templates.md` | **状态模板与检测逻辑**（.study-meta.json v2、status 脚本、版本检查命令） |

| `references/interactive-mode-guide.md` | **交互模式详细指南**（实时归档、思维导图、知识树结构、会话追踪） |

| `references/yolo-mode-guide.md` | **Yolo 模式详细指南**（subagent prompt 模板、输出模板、笔记沉淀、翻译提示） |

| `references/translate-mode-guide.md` | **翻译模式详细指南**（任务分组、subagent prompt、质量规则、失败重试） |

| `references/guide-template.md` | **导读指南完整模板**（产品认知、架构图、文件地图、设计决策等完整结构） |

| `references/tutorial-workflow.md` | **教程两阶段工作流**（T1 配置引导 + T2 逐章实测 + 文件结构模板） |

| `references/anti-patterns.md` | **反模式清单**（6 个常见错误及正确做法） |

| `references/article-mode-guide.md` | **技术展示文章指南**（6 段式叙事模板、subagent prompt、质量检查清单、风格要素） |

| `references/quick-reference.md` | **快速参考**（使用示例、模式说明、常用命令速查） |

</references>

---

## ⚠️ 用户交互点总结

| 阶段 | 交互点 | 类型 | 用户操作 |

|------|--------|------|----------|

| 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 6 | 🔄 产出选择 | Decision | 继续研究/指南/教程/模板/Cheat Sheet/小白指南/技术展示文章/Skill 映射/全部 |

| Phase 6b-T1 | ✅ 配置完成确认 | Human-Verify | 用户完成所有配置步骤，检查清单全通过 |

| Phase 6b-T2 | 🔄 实测结果审核 | Human-Verify | 确认实测数据，处理失败的命令 |

| Phase 7 | 🔄 恢复确认 | Decision | 继续/重新开始 |