repo-study

入口路由 (route)

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

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

空值 / help 时的输出格式

当用户输入 /repo-study 不带参数，或带 help/--help 时，输出以下提示：

📖 repo-study — GitHub 仓库研究助手

用法: /repo-study <子命令> 或 /repo-study <仓库URL> [研究问题]

子命令:
  list      列出所有 *-study 项目
  status    查看当前项目状态（进度、模式、版本）
  update    更新当前项目源码到最新版本
  sync      同步所有 study 笔记到 Obsidian
  translate 并行翻译文档（*.md → *.zh.md）
  distill   将研究发现蒸馏为独立 demo 或设计文档
  answer    回答 Question.md 中的研究问题
  continue  恢复上次中断的交互学习

研究模式:
  /repo-study <URL> <问题>     首次研究 → Survey 模式（产出 explorer/）
                               后续提问 → Incremental 模式（产出 notes/）

示例:
  /repo-study https://github.com/user/repo 它的缓存策略是怎么实现的
  /repo-study list
  /repo-study sync

注意：如果 args 不匹配任何子命令也不含 URL，则当作研究问题处理（在当前 study 项目中执行增量问答）。

Phase 0: 列表 (list) — 可选

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

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

📖 详细文档 → 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. 汇总验收结果（通过/失败/跳过）

输出格式：explorer/NN-{repo-name}-skill-to-script-mapping.md（带编号）

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

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

1. 产品认知（来自文档感知 subagent）
2. 核心概念 + 前因后果（来自文档 + 代码综合分析）
3. 代码原理（来自代码分析 subagent）

Step 5a.3b: Capability Discovery（能力发现） — YOLO 模式强制步骤

🎯 目标：穷举项目所有可操作能力，生成对应的 Cheat Sheet。此步骤确保研究不仅覆盖架构理解，还覆盖全部可实操的内容。

触发条件：YOLO 模式下的所有项目（不可跳过）。

启动 Capability Discovery subagent（Explore 类型）：

扫描范围（根据项目类型自适应）：

扫描方法：

1. 文件结构扫描：Glob 搜索注册文件、路由文件、命令定义文件
2. 模式匹配：Grep 搜索常见的注册模式（cli(、command(、router.、app.get、export、register）
3. Manifest/Config 读取：读取 package.json（bin 字段）、manifest.json、CLI manifest 等
4. 文档交叉验证：对比 docs/ 和 README.md 中列出的功能与源码中的实际实现

Cheat Sheet 生成规则：

1. 按维度分文件：每个有意义的维度生成一份独立 Cheat Sheet（如"命令速查"、"API 速查"、"配置速查"）
2. 文件命名：explorer/cheatsheet/{topic}-cheat-sheet.md（不带编号）
3. 每份 Cheat Sheet 必须包含：标题 + 一句话说明 + 分维度表格 + 使用示例 + article_id
4. 表格格式：命令/操作 | 干什么 | 关键参数 | 示例
5. 对于大型项目（命令/API 数量 > 50），额外生成一份总览 Cheat Sheet（explorer/cheatsheet/all-{dimension}-cheat-sheet.md），按分类组织所有内容

📝 详细 subagent prompt 模板 → references/yolo-mode-guide.md §6

Step 5a.4: 沉淀与指南

1. 沉淀笔记到 explorer/（文件名必须带 2 位索引前缀，如 01-xxx.md、02-xxx.md）并更新 .study-meta.json 的 topics[]（location: "explorer"）
   • 每篇笔记写入时立即生成 article_id 并写入 frontmatter（格式：OBA-{8位随机小写字母数字}，全局唯一性校验）
   • 更新 Question.md：对本次新建的每篇笔记，检查其 article_id 是否已在 Question.md 中有对应 section，若没有则在末尾追加（格式见 references/question-template.md）
2. 环境准备章节（可选）：如果项目需要安装、配置等前置步骤，生成 explorer/00-{repo-name}-environment-setup.md（纯代码分析项目可跳过）
3. 设置 surveyState = "completed"
4. 首次研究强制生成导读指南：检查 explorer/ 中是否已有 *-guide.md，若不存在则生成（带编号前缀）
5. 自动 Capability Discovery + Cheat Sheet 生成：启动 Capability Discovery subagent，扫描项目所有可操作能力（命令/API/配置/端点/插件钩子等），自动生成对应 Cheat Sheet 到 explorer/cheatsheet/。此项为 YOLO 模式强制步骤，不可跳过（详见 references/yolo-mode-guide.md §6）
6. 中文提问时提示翻译功能

📝 导读指南完整模板 → references/guide-template.md 📝 subagent prompt 模板、输出模板 → references/yolo-mode-guide.md §1-3

⚠️ 强制规则：每个项目首次研究时必须生成导读指南，不可跳过。指南是 explorer/ 的入口文档。 ⚠️ 00- 规则：如果项目是工具/CLI/库（需要安装和环境配置），必须生成 00- 环境准备章节。纯代码分析项目可跳过。

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）

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

适用场景：研究的项目是工具/CLI/库，需要可执行教程时使用。 产出文件：explorer/NN-{repo-name}-how-to-use-guide.md（带编号）

📖 完整教程工作流文档 → 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 6e: 实操手册生成 (practice)

适用场景：用户要求对工具/CLI 的命令进行逐个实测验证，生成可复现的操作手册。 产出文件：practices/{topic}-practice.md（不带编号，按主题命名） 前置条件：项目已完成 survey（surveyState = "completed"）+ 环境已配置（Phase 1 通过）

Step 6e.1: 识别实操范围

1. 从用户请求中提取要验证的范围（如"B 站的所有命令"、"browser 命令"）
2. 从 explorer/ 和 notes/ 中提取已有研究素材，列出待验证的命令清单
3. 展示命令清单（命令 → 说明 → 认证模式），用户确认范围

Step 6e.2: 逐个验证

1. 按分组逐个执行命令（如按功能模块、认证模式分组）
2. 每个命令记录：输入命令 → 真实输出 → 状态（✅/❌/⚠️）
3. 失败的命令：标注错误原因和替代方案
4. 可并行的命令使用 Bash 工具并行执行

Step 6e.3: 写入实操手册

1. 创建 practices/ 目录（如不存在）
2. 写入 practices/{topic}-practice.md，结构如下：

---
article_id: OBA-xxx
title: {标题}
description: {一句话说明}
date: YYYY-MM-DD
status: verified
environment:
  opencli: x.x.x
  ...
---

# {标题}

> 所有命令均已在 YYYY-MM-DD 实测通过。

## 前置条件
（环境检查命令和期望输出）

## 命令全景
（表格：命令 / 功能 / 认证模式 / 实测状态）

## 第 1 章：xxx
（分章节，每章包含：命令 → 真实输出 → 说明）

## 已知问题
（表格：问题 / 影响 / 解决方案）

## 命令速查表
（紧凑的命令列表）

3. 写入时立即生成 article_id 并写入 frontmatter
4. 更新 .study-meta.json 的 topics[]（location: "practices"）
5. 更新 CLAUDE.md 笔记索引

Step 6e.4: 同步到 Obsidian

执行 Phase 5.5 自动同步检测（包括 practices/ symlink）。

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}/explorer symlink → {study项目}/explorer
   • 创建 wiki/open-source/{project}/notes symlink → {study项目}/notes
   • 创建 wiki/open-source/{project}/practices symlink → {study项目}/practices（如存在）
   • 创建 wiki/open-source/{project}/Question.md symlink → {study项目}/Question.md（如存在）
   • 若 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 项目根目录运行翻译计划脚本：

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

2. 读取任务清单中的 tasks[]（字段：source、target、group）
   约束：target 必须是 source 对应的 *.zh.md

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

4. 默认跳过已存在的 *.zh.md
   若用户明确要求全量重译，使用：

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：指向发现该模式的研究笔记路径

Phase 10: 问答 (answer) — 补充研究笔记中看不懂的地方

当用户使用 /repo-study answer 时：

核心理念：因为看不懂，所以才有这个文件。用户边看笔记边记录困惑，AI 读取后补充对应笔记内容。

Step 10.0: 前置检查

1. 检查当前目录是否为有效 study 项目（目录名 *-study + .study-meta.json）
2. 检查 Question.md 是否存在于项目根目录
3. 若 Question.md 不存在，提示"当前项目尚未生成 Question.md"
4. 检查历史批次文件：扫描目录中是否有 Question-*.md 临时文件，如果有 status: pending 的未处理批次，提示用户：
   • "发现未处理的历史批次 Question-{N}.md，是否先处理？"
   • 用户选择：先处理历史 / 忽略，继续处理 Question.md

Step 10.1: 读取 Question.md

1. 读取 Question.md 全文
2. 提取一级标题（# Question）以下的所有内容，分为两部分：
   • (A) 顶部自由内容：# Question 之后、第一个 ## OBA-xxx 之前的所有非空内容（整体建议、反馈、优化想法等）
   • (B) article_id sections：所有 ## OBA-xxx section 及其下用户内容
3. 若 (A) 和 (B) 均为空，提示"没有待处理的问题"并退出
4. (A) 类内容的处理方式：整体建议/反馈类内容直接在主会话处理（如文件移动、结构调整、skill 优化等），不需要启动 subagent

Step 10.2: 展示问题概况

如果存在 (A) 顶部自由内容，优先展示：

然后展示 (B) article_id sections：

📝 对应笔记查找：在 explorer/ 和 notes/ 中搜索含该 article_id 的文件。

Step 10.3: 用户选择

使用 AskUserQuestion 询问：

1. 全部处理（N 个 section）
2. 选择部分处理
3. 取消

Step 10.3b: 立即拆分（避免编辑冲突）

核心目的：用户确认处理范围后，立即将待处理内容提取到临时文件，同时立即清理 Question.md。这样 Question.md 马上可以被用户继续编辑，subagent 慢慢处理临时文件即可。

用户选择完成后、启动 subagent 之前，立即执行以下操作：

1. 生成临时批次文件：

• 文件名：Question-{N}.md（N 从 1 递增，扫描目录中已有 Question-*.md 取最大 N+1）
• 位置：项目根目录（与 Question.md 同级）
• 内容：将待处理的顶部自由内容 + 待处理的 article_id sections 原样复制到临时文件

---
title: "Question - 待处理批次 {N}"
type: question-batch
source: Question.md
created_at: "{YYYY-MM-DD}"
status: pending
sections:
  - {OBA-xxx}
  - {OBA-yyy}
---

# 待处理问题（批次 {N}）

{待处理的顶部自由内容，原样复制}

## {OBA-xxx}
{原始 section 内容}

## {OBA-yyy}
{原始 section 内容}

2. 立即清理 Question.md（此步骤完成后用户即可安全编辑）：

• 删除顶部自由内容中已被提取的部分（# Question 说明行之后、第一个 ## OBA-xxx 之前已选处理的内容）
• 删除已选处理的 article_id sections（整个 ## {article_id} + 其下所有内容直到下一个 ## OBA-xxx 或文件末尾）
• 未选择的 sections 保持不动
• 更新 frontmatter 的 updated_at

3. 输出提示：告知用户 已从 Question.md 中提取 {N} 个 section 到 Question-{M}.md，原文件已清理，可继续编辑

Step 10.4: AI 拆解（Multi Teams 并行）

注意：此步骤基于 Step 10.3b 生成的临时批次文件（Question-{N}.md），不再直接读取 Question.md。

对于 (A) 顶部自由内容：直接在主会话中分析处理（从临时批次文件读取），不启动 teammate。根据内容类型决定处理方式：

• 文件移动/重命名 → 直接执行
• 目录结构调整 → 直接执行
• repo-study skill 改进建议 → 记录到 jacky-skills 项目的改进 backlog 或直接修改 skill
• 其他反馈 → 讨论后执行

对于 (B) article_id sections：使用 Multi Teams 模式并行处理，每个 section 分配一个独立 teammate：

Step 10.4a: 创建团队和任务

1. TeamCreate：创建团队 answer-{N}（N 为批次编号）
2. TaskCreate：为每个待处理的 article_id section 创建独立任务，描述中包含：
   • section 的 article_id
   • 临时批次文件路径（Question-{N}.md）
   • 对应笔记的查找方式（通过 article_id 在 explorer/ 和 notes/ 中搜索 frontmatter）
   • 源码路径
   • 期望输出格式

Step 10.4b: 并行派发 teammates

为每个 section spawn 一个 general-purpose 类型 teammate（带 team_name 和唯一 name，如 answer-1-OBA-xxx）：

teammate prompt 模板：

你是代码分析和知识补充专家。

你被分配了一个具体的研究问题，请完成以下任务：

1. 读取批次文件 {Question-{N}.md} 中你负责的 section: {article_id}
2. 通过 article_id 在 explorer/ 和 notes/ 中搜索 frontmatter，找到对应的研究笔记
3. 读取该笔记全文，理解现有内容结构
4. 理解用户写的内容（可能是问题、困惑、"看不懂"、需要补充示例等）
5. 分析源码 {源码路径}，找到答案或补充材料
6. 提出具体补充方案

**源码路径**: {项目目录}/{repo-name}/
**研究笔记路径**: {项目目录}/explorer/ 和 {项目目录}/notes/
**批次文件路径**: {Question-{N}.md}
**你的 section**: {article_id}

**输出格式**：
- **对应笔记**: {找到的笔记路径}
- **用户诉求**: {对用户内容的理解，1-2 句}
- **补充内容**: {可直接写入笔记的 Markdown 内容}
- **插入位置**: {在笔记中的哪个 section 之后插入，如"## 三、xxx 之后"}

每个 teammate：

• 通过 TaskUpdate 将任务标记为 in_progress
• 独立读取批次文件、研究笔记、源码
• 生成补充方案并通过 SendMessage 返回给 team lead
• 通过 TaskUpdate 将任务标记为 completed

Step 10.4c: 收集结果

主会话（team lead）通过 TaskList 监控进度，收集各 teammate 返回的补充方案。

Step 10.5: 执行补充

主会话（team lead）收到所有 teammate 的分析结果后：

1. 关闭团队：SendMessage shutdown 所有 teammates，然后 TeamDelete 清理团队资源
2. 对每个 section 的结果：
   • 找到对应的研究笔记文件
   • 将补充内容插入到指定位置
   • 保留原有内容，只做追加/补充
3. 展示补充摘要给用户确认

Step 10.6: 标记批次完成

注意：Question.md 的清理已在 Step 10.3b 中完成，此步骤只需更新临时批次文件状态。

用户确认所有内容（顶部自由内容 + article_id sections）已处理后：

1. 更新临时批次文件（Question-{N}.md）的 frontmatter：status: pending → status: done
2. 自动删除已完成的批次文件（Question-{N}.md），避免目录残留
3. 如果所有 section 均已处理且 Question.md 只剩空壳（frontmatter + 标题 + 说明），无需额外操作（Step 10.3b 已处理）

Step 10.7: 输出摘要

✅ 已处理 {N} 个 section，补充了 {M} 篇笔记

| Article | 笔记 | 补充内容 |
|---------|------|---------|
| OBA-xxx | explorer/01-xxx.md | 补充了 sqlite3 使用场景说明 |
| OBA-yyy | notes/xxx.md | 添加了 B 站视频测试示例 |

📁 批次文件: Question-{K}.md（status: done，可手动删除）