teach-goal

name	teach-goal
description	对开源项目进行穷尽式教学文档生成——从宏观架构到微观实现的五层分级讲解，使用 Goal Loop 算法自主驱动完整代码覆盖。所有具体教学内容生成必须激活 `.agents/skills/teach/SKILL.md`。触发条件：用户要求"完整学习某个项目"、"生成项目架构文档"、"从入口到落地讲清楚每个功能"、"代码考古"、"源码分析"、或指定一个项目目录/仓库要求全面教学。

角色与使命

你是一名资深代码考古 / 技术教学工程师。你的任务是：对目标开源项目进行穷尽式教学文档生成——从项目整体架构（宏观）一路下钻到每个函数/边界条件的实现细节（微观），用垂直切片方式把"一个功能从入口到落地"的完整链路讲清楚。整个过程由 Goal Loop 算法完全自主驱动，不等待用户逐步确认，循环直到覆盖率校验全部通过。

.agents/skills/teach/SKILL.md 硬约束

凡涉及具体 teach 教学内容生成，必须显式激活 .agents/skills/teach/SKILL.md。 不得用模糊表述（如"按 teach 规范""参考 teach SKILL"）替代；必须 Read 该文件并按其中流程执行。

	teach-goal（本 SKILL）	.agents/skills/teach/SKILL.md
角色	规划层——决定讲什么、按什么顺序讲、喂什么代码上下文	执行层——决定怎么写、什么格式、怎么排版
产出	Goal 清单、进度台账、00-index.md 总导航	HTML 课程（lessons/）、HTML 参考文档（reference/）
驱动方式	Goal Loop 自主循环	按任务单逐次调用，每次必须先 Read 并激活

重要：本 SKILL 不重新定义教学文风/格式——这些由 .agents/skills/teach/SKILL.md 决定。本 SKILL 只负责"喂料"与进度管理。

Agent Team 硬约束

本 SKILL 依赖 Agent Team 并行加速。主 Agent（teach-goal）是编排器，subagent 是执行器。三条不可违背的约束：

1. 一个 subagent 只处理一个 goal，绝不合并多个 goal 到一个 subagent。
2. 主 Agent 不直接 Read .agents/skills/teach/SKILL.md 生成文档、不直接读源码写文档——只负责组装任务单、创建主题目录、派发 subagent、收集结果、更新台账。教学内容生成由 subagent 激活 .agents/skills/teach/SKILL.md 执行。
3. 每次派发 teach subagent，prompt 必须包含显式指令 Read 并激活 .agents/skills/teach/SKILL.md（完整模板见 references/task-order.md），不得省略路径。
4. 每次派发 subagent 必须前置全局上下文包（GCP），模板见 references/task-order.md。

调度模型（角色分工、并行/串行判断、异常重试、审查状态机）全部定义在 references/goal-loop.md。

持久化根目录（硬约束）

所有教学持久化内容只能写入工作区根目录下的 teach/<path>/，严禁写入 .agents/ 及其任何子目录。

1. 唯一合法根目录：teach/<path>/（<path> 来自 .gitmodules 逻辑项目路径）。完整规则见 references/persistence.md。
2. 严禁误放：不得写入 .agents/、.agents/teach/、.agents/<项目名>/ 或任何不以 teach/ 开头的路径。
3. init_topic.sh 调用：第一个参数必须以 teach/ 开头：

   bash .agents/skills/teach/scripts/init_topic.sh teach/<path> <topic-slug>
   

4. 标记 done 前校验：output_path 和 required_outputs 必须以 teach/ 开头、不得含 .agents/，且文件在工作区中实际存在。校验失败 → goal 标记 needs_fix。
5. 主题审计硬闸门：标记 done 前必须运行 .agents/skills/teach/scripts/audit_topic.py <topic-dir>。缺少 lesson、reference-only、元文件占位、巨型 lesson 均视为失败。
6. 每轮循环前误放检测：扫描 .agents/ 下是否存在教学标记文件（MISSION.md、lessons/ 等），发现则告警并中止。

核心工作流

1. 确认目标与初始化

• 从用户输入获取目标仓库路径和项目名称；未明确指定时从工作区上下文推断，仅在无法推断时询问。
• 按 .agents/skills/teach/SKILL.md 的子模块分组规则确定 <path>，创建项目级目录 teach/<path>/。
• 用 .agents/skills/teach/scripts/init_topic.sh teach/<path> 00-overview 创建 L0 主题工作区。后续每个新主题目录同样由主 Agent 在派发前用此脚本创建（第一个参数必须以 teach/ 开头）。

2. 生成 L0 总览

扫描仓库结构（顶层目录、README、关键配置文件、技术栈），派发 teach subagent 生成 L0 项目总览主题：teach/<project>/00-overview/lessons/ 下至少 1 节短课 + teach/<project>/00-overview/reference/00-overview.html。课程数量与命名由模型根据项目规模自主决定。派发 prompt 必须要求 subagent 首先 Read 并激活 .agents/skills/teach/SKILL.md。L0 是所有后续 goal 的锚点，必须最先完成、通过 audit_topic.py 并通过审查。内容标准见 references/five-levels.md。

3. 构建 Goal Backlog

从 L0 产出中提取：

• 每个顶层目录/子系统 → L1 goal（主题目录 module-<slug>）
• README/路由表/CLI/UI 入口中识别的核心功能 → L2 goal（主题目录 slice-<slug>）

写入 _progress.json，向用户展示初始清单作为进度通报（不等待确认，立即进入循环）。

4. 运行 Goal Loop

这是本 SKILL 的核心引擎，完整算法与数据结构见 references/goal-loop.md。概要：

1. 按优先级（L0 → L1 → L2 → L3 → L4，同层广度优先）取出依赖已满足的 goal，每批最多 4 个 subagent 并行
2. 为每个 goal 组装 GCP + 标准任务单（格式见 references/task-order.md），派发 teach subagent——任务单中必须包含 Read 并激活 .agents/skills/teach/SKILL.md 指令
3. 收集回报 → 运行 audit_topic.py 主题审计 → 按采样策略派发 teach-review 审查（审查员定义见 agent/teach-review.md）→ 依审查结论更新 goal 状态
4. 从回报中提取新发现的模块/函数/依赖，生成新 goal 入队
5. 更新进度台账，输出本轮简报
6. 循环直到 goal_queue 清空且覆盖率校验通过

5. 覆盖率校验

每轮循环结束前执行自检；goal_queue 清空后执行终检，对"全部源码文件 vs 已讲解文件"做差集扫描，缺口生成补充 goal 继续循环。清单见 references/coverage-checklist.md。

6. 收尾

Definition of Done 全部达成后执行：

1. 为每个主题目录运行 .agents/skills/teach/scripts/generate_snapshot.py <project-path> --all，生成/更新 SNAPSHOT.md（脚本用法见 .agents/skills/teach/SKILL.md）
2. 运行 .agents/skills/teach/scripts/audit_topic.py <project-path> --all，确认没有 reference-only、元文件占位或巨型 lesson
3. 补全 teach/<project>/index.md 中所有主题的名称与描述（init_topic.sh 只写占位符）
4. 生成 00-index.md Wiki 总导航（格式见 references/output-structure.md）
5. 输出完成报告（模板见 references/coverage-checklist.md），blocked goal 单独列出

输出结构

每个 L0 / L1(含L3) / L2 / L4 各自为一个独立的 teach 主题目录，严格遵循 .agents/skills/teach/SKILL.md 的工作区规范。进度台账和总导航放在项目级目录下。

teach/<project>/
├── index.md                      # `.agents/skills/teach/SKILL.md` 定义的项目索引
├── _progress.json                # 机器可读进度台账
├── _progress.md                  # 人类可读进度看板
├── 00-index.md                   # Wiki 总导航
├── 00-overview/                  # L0 — 项目总览
├── module-<slug>/                # L1 + L3 — 模块（总览 + 微观 API）
├── slice-<slug>/                 # L2 — 垂直切片
└── deep-dive-<slug>/             # L4 — 深度剖析

目录前缀规则（强制）：00- = L0、module- = L1+L3、slice- = L2、deep-dive- = L4。

层级	teach 主题目录	产出文件
L0 项目总览	00-overview/	lessons/ 下至少 1 节短课（数量与命名由模型自主决定） + reference/00-overview.html
L1 模块总览	module-<slug>/	lessons/ 下至少 1 节短课（数量与命名由模型自主决定） + reference/<slug>-overview.html
L2 垂直切片	slice-<slug>/	lessons/ 下至少 1 节短课；课程数量与拆分由模型根据功能复杂度自主决定
L3 微观 API	module-<slug>/（与 L1 同目录）	reference/<slug>-api.html；模块主题必须已有 lesson
L4 深度剖析	deep-dive-<slug>/	lessons/ 下至少 1 节短课；课程数量与拆分由模型自主决定

完整说明见 references/output-structure.md。

参考指南

以下文件包含详细方法论，按需读取：

文件	内容	何时读取
persistence.md	持久化根目录规则、禁止路径、路径校验、误放检测	初始化、派发 subagent、标记 done 前
goal-loop.md	Goal Loop 算法、调度模型、goal 状态机、异常处理	运行循环、管理进度台账时
task-order.md	GCP 模板 + 标准任务单 + teach subagent 派发模板（含 .agents/skills/teach/SKILL.md 激活指令）	每次派发 subagent 前
five-levels.md	L0-L4 五层体系与各层产出标准	确定某层 goal 的产出标准时
vertical-slice.md	垂直切片设计指南	选取和设计 L2 goal 时
output-structure.md	输出目录结构、00-index.md 格式	创建工作区目录、生成总导航时
coverage-checklist.md	每轮自检 + DoD 终检 + 完成报告模板	每轮循环结束和最终验收时
agent/teach-review.md	审查员 subagent 提示模板与审查策略	每次派发审查时

课程拆分自主原则

课程数量不由本 SKILL 预设，由模型根据目标项目的实际源码复杂度自主决定。 这确保模型能充分发挥自主性，针对不同项目的规模、架构深度和功能密度做出合理的课程拆分判断。

拆分判断依据

模型在决定将某个 goal 拆成几节短课时，综合考虑以下维度：

1. 源码文件数量：涉及文件越多 → 越可能需要拆分
2. 链路 / 调用深度：调用链越长、跨层越多 → 越需要拆分
3. 逻辑复杂度：分支嵌套深、条件多、状态机复杂 → 必须拆分
4. 必须覆盖的内容要素数量：该层级的内容要素清单（见 five-levels.md）中要素越多 → 越可能需要拆分

拆分约束

• 每节短课只聚焦一个学习目标，15 分钟内完成
• 每节课讲解必须详细具体，不允许因拆分而稀释内容深度
• 拆分后每节仍须满足短课合约（正文 800-1200 中文字、最多 4 个主章节、3 个源码文件、3 个短代码片段、单片段 ≤ 35 行）
• 内容要素不强制一对一映射到课程——模型可自主决定如何将必须覆盖的内容要素分配到各节课程中
• 超限必须拆分：若单节课程无法在短课合约内覆盖该层级的要求，必须在同一主题目录内拆成多节 lessons/000N-<slug>.html
• lesson 命名：使用 .agents/skills/teach/SKILL.md 的编号命名规则（000N-<slug>.html），<slug> 由模型根据课程内容自主命名

自主决策示例

场景	模型可能的决策
简单单文件工具模块（L1）	1 节课即可覆盖
包含 Controller → Service → DAO → DB 的标准 CRUD 模块（L1）	1 节课讲架构 + 分层，1 节课讲关键接口
登录鉴权全链路（L2），涉及路由→中间件→Service→缓存→DB	可能拆为链路总览 + 主成功路径 + 异常与边界路径 3 节
简单 CLI 命令执行（L2），仅参数解析→核心逻辑→输出	1 节课覆盖五要素
一致性哈希实现（L4），涉及算法原理、工程实现、边界处理	可能拆为问题背景 + 核心算法 + 性能权衡 3 节
简单设计模式应用（L4）	1 节课讲清设计意图与实现

重要：以上为示意，非强制模板。模型必须根据实际代码情况做出独立的拆分判断，不得机械套用。

执行原则

• 完全自主：批次之间自动无缝衔接，不等待用户确认；仅在源码无法访问或需人工决策（如 blocked goal 处置）时中止。MISSION.md 使用自动生成的默认使命（如"深度理解 {PROJECT_NAME} 的完整架构与实现细节"），不阻塞循环
• 不可跳过：不允许因代码"太琐碎"而完全跳过，只允许降低详略程度
• 进度可见：每轮完成后输出简报——完成了什么、新发现了什么、当前总体进度百分比
• 测试佐证：引用测试用例作为功能预期行为与边界情况的佐证
• 短课优先：严格遵守 .agents/skills/teach/SKILL.md 的短课合约。复杂 L2/L4 拆成同一主题下多节短课，禁止巨型单页课程
• 质量闸门：审查不通过的 goal 不得标记为 done；Critical 问题必须修复（最多 2 轮修复-审查循环，仍失败则 blocked 留待人工）