Repo Study

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

双模式：Survey + Incremental

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

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

四类产出目录

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/ 目录不使用编号（零散笔记，无固定阅读顺序）

笔记质量评价体系

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

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

笔记叙事原则

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 和笔记之间的桥梁，缺失会导致问题无法关联

工作流契约

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

入口路由 (route)

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

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

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

空值 / help

参数为空、为 help 或 --help 时，读取并使用 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. 输出表格：

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 脚本

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 字段的存量项目，如果 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：文档感知、代码/Skill 映射、合并输出、Capability Discovery 与沉淀步骤。
2. 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位随机小写字母数字}，全局唯一性校验）。

笔记结构：

# {话题标题}

> 关联教程：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 是否存在且路径有效：

# 检查 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 的对应章节：

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

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

⚠️ 用户交互点总结