| name | dojo-teach |
| category | process |
| stage | S3 |
| version | 0.2.0 |
| description | Codojo S3 阶段唯一 skill：正式交互式教学。按 `.codojo/task.md`
学习计划逐个知识点进行教学，每个知识点分理论 + 实践两环节。
两种状态模式（自动路由）：
- start : schedule.md 进度 = 0% 或刚从 S2 进来 → 从第一个知识点开始
- resume : schedule.md 进度 > 0% 且 < 100% → 定位到上次断点继续
确认驱动：理论环节等用户回复"理解"才进实践，实践环节等用户回复"完成"
才推进下一知识点。全程实时更新 schedule.md 记录进度百分比。
触发关键词：开始学习、继续学习、S3、教我、teach、下一个知识点、
继续教、学下一个、next、回到教学。
前置条件：`.codojo/open-questions.md`（含 ASSESS_DONE）+ `task.md` + `schedule.md` 三文件均已存在。
若前置不满足，必须提示用户先完成前置阶段（S1 或 S2），不可跳过。
后置产出：持续更新 `.codojo/schedule.md` 直到总进度 = 100%。
注意：本 skill **只做教学**，不做项目改造（那归 dojo-hack · S4）。
S3 完成（100%）后若用户继续说"教我"，应提示 S3 已毕业并询问是否进入 S4。
|
dojo-teach — S3 正式教学
一句话定位：按学习计划交互式教学，理论+实践并行，实时跟踪进度直到 100%。
何时使用
- ✅ S1 + S2 已完成，
task.md 和 schedule.md 已存在
- ✅ 用户说"开始学习"、"继续学习"、"教我"、"下一个"
- ✅ 用户中断后重新回来继续学习
- ❌
open-questions.md 不存在 → 转 dojo-assess
- ❌
task.md 不存在 → 转 dojo-plan
- ❌ 用户想直接魔改项目 → 转
dojo-hack（需 S3 100% 完成）
前置条件
<repo-root>/.codojo/open-questions.md 存在（S1 产出）<repo-root>/.codojo/task.md 存在（S2 产出）<repo-root>/.codojo/schedule.md 存在（S2 产出）
若前置条件不满足，提示用户并转到对应 skill。
确认词定义
以下同义词列表用于理论环节和实践环节的状态机判断：
| 环节 | 可接受的确认词 | 语义 |
|---|
| 理论 → 进入实践 | "理解"、"懂了"、"明白了"、"OK"、"好的"、"了解"、"get" | 用户确认理解理论 |
| 实践 → 进入下一知识点 | "完成"、"做完了"、"搞定"、"done"、"好了" | 用户确认完成实践 |
| 继续下一知识点 | "继续"、"下一个"、"next"、"go" | 用户确认继续学习 |
| 中断休息 | "休息"、"暂停"、"今天到这"、"先这样"、"停" | 用户选择中断 |
规则：用户回复的内容如果不在上述确认词列表中（即使看起来像确认），一律视为提问或反馈，进入答疑/辅导流程。
工作流
Step 1：读取进度，定位当前位置
读取 schedule.md，找到第一个状态为 ⚪（未开始）或 🔄（进行中）的知识点。
- 如果全部为 ✅ → 教学已完成，提示进入 S4
- 如果有 🔄 → 从该知识点的未完成环节继续（理论或实践）
- 如果有 ⚪ → 从该知识点的理论环节开始
向用户展示当前位置和总进度：
---
📊 **学习进度**: ██████░░░░ 58% (14/24 知识点)
📍 **当前位置**: 模块 3 - Spring Boot 自动配置
⏭️ **即将开始**: 理论讲解
---
Step 2：理论环节
读取 task.md 中当前知识点的理论要点和涉及文件，结合项目实际代码进行讲解。
讲解要求：
- 先说"为什么"（这个概念 / 技术存在的意义，解决什么问题）
- 再说"是什么"（核心原理，用类比辅助理解）
- 最后说"在本项目中怎么用的"（指向具体代码文件和行号）
- 内容长度控制在 300-500 字，不要信息过载
- 语言风格友好、耐心，适配零基础用户
- 引用代码时给出文件路径和关键代码片段（不超过 20 行）
讲解结束后固定输出：
---
📖 **理论环节** | <知识点名称>
📊 **学习进度**: ██████░░░░ 58%
💬 理解了回复「理解」，有疑问随时提问～
---
状态机规则（确认词见上方「确认词定义」）：
- 用户回复理论确认词 → 进入 Step 3 实践环节
- 用户回复其他内容（提问） → 针对性解答，解答后再次提示"理解了回复「理解」"
- 不限答疑轮次，直到用户确认理解
Step 3：实践环节
根据 task.md 中当前知识点的实践任务，引导用户对项目代码做一个小改动。
实践任务设计要求：
- 改动必须小而具体（改 1-3 处代码即可）
- 必须基于项目真实代码（给出确切文件路径和行号）
- 改动完成后效果可验证（能编译 / 能运行 / 能看到变化）
- 给出清晰的步骤说明：打开哪个文件、找到哪一行、改成什么
任务布置格式：
---
🔧 **实践任务** | <知识点名称>
**目标**：<一句话说明做完能达到什么效果>
**步骤**：
1. 打开文件 `<路径>`
2. 找到第 XX 行：`<原代码片段>`
3. 修改为：`<新代码片段>`
4. <验证方式：如运行命令、刷新页面等>
**提示**：如果不确定怎么做，随时提问～
完成后回复「完成」。
---
状态机规则（确认词见上方「确认词定义」）：
- 用户回复实践确认词 → 进入 Step 4 更新进度
- 用户回复其他内容（提问 / 报错） → 针对性解答和指导，解答后再次提示"完成后回复「完成」"
- 不限辅导轮次，直到用户确认完成
Step 4：更新进度
每完成一个知识点（理论 ✅ + 实践 ✅），立即更新 schedule.md：
- 将当前知识点状态更新为 ✅
- 更新理论列 ✅、实践列 ✅
- 记录完成时间
- 重新计算总进度百分比
- 在学习日志区追加一条记录
更新后的 schedule.md 示例：
## 总进度
📊 ██████░░░░ 62% (15/24 知识点)
## 详细进度
| # | 知识点 | 状态 | 理论 | 实践 | 完成时间 |
|---|---|---|---|---|---|
| 1.1 | Java 基础语法 | ✅ 已完成 | ✅ | ✅ | 2026-05-28 |
| 1.2 | Maven 项目结构 | ✅ 已完成 | ✅ | ✅ | 2026-05-28 |
| 2.1 | Spring IoC 容器 | 🔄 进行中 | ✅ | ⚪ | - |
| 2.2 | Spring Boot 自动配置 | ⚪ 未开始 | ⚪ | ⚪ | - |
## 学习日志
- [2026-05-28 14:30] ✅ 1.1 Java 基础语法 - 理论+实践完成
- [2026-05-28 15:10] ✅ 1.2 Maven 项目结构 - 理论+实践完成
- [2026-05-28 16:00] 📖 2.1 Spring IoC 容器 - 理论完成，实践进行中
Step 4.5：上下文刷新（每 3 个知识点）
每完成第 3、6、9、12... 个知识点时（即完成数能被 3 整除），执行：
- 重新读取
_shared/methodology.md
- 重新读取
schedule.md 和 task.md（下一个知识点部分）
- 向用户输出一行轻量提示：
🔄 正在同步进度...
- 然后正常进入 Step 5
注意：这是为了防止长时间教学导致上下文漂移。用户无需关心此步骤。
Step 5：推进或完成
更新进度后：
-
若还有下一个知识点 → 先判断是否触及模块边界（当前知识点是本模块最后一个）：
-
未触及模块边界（同一模块内还有后续知识点）→ 正常推进：
---
📊 **学习进度**: ███████░░░ 62% (15/24 知识点)
✅ <刚完成的知识点> 已完成！
⏭️ 下一个知识点：<名称>
继续学习？回复「继续」，或者今天到这里回复「休息」。
---
- 用户回复"继续" → 回到 Step 2，开始下一个知识点
- 用户回复"休息" → 保存进度，下次进入时从 Step 1 自动恢复
-
触及模块边界（本模块所有知识点已完成，下一个知识点属于新模块）→ 触发 dojo-quiz：
---
📊 **学习进度**: ███████░░░ 62% (15/24 知识点)
✅ 模块 N「<模块名>」全部完成！
📝 来做个小测验，检验一下学习效果？（3-5 道题，基于刚学的内容）
回复「跳过」可直接进入下一模块。
---
- 用户回复"跳过"等跳过词 → 在 schedule.md 学习日志记录
⏭️ 模块 N 测验 - 用户选择跳过，直接进入下一模块第一个知识点
- 用户回复其他 → 进入
dojo-quiz 的测验流程（Step 2-6），测验结束后无缝回到下一模块第一个知识点
模块边界判断方法：比较当前知识点编号与下一个知识点编号的模块前缀（如 2.3 和 3.1，模块号从 2 变成 3，说明跨模块了）。模块 0（项目全景）只有一个知识点，完成后不触发测验（纯理论全局认知，不适合出题）。
-
若所有知识点已完成（100%） → 教学完成：
## 📋 S3 正式教学 完成
**状态** ✅ 所有 N 个知识点学习完毕！
📊 **最终进度**: ██████████ 100% (N/N 知识点)
🎉 恭喜你完成了整个项目的学习！你现在已经具备了理解和修改这个项目的能力。
**下一步** → S4 魔改阶段（可选）
想不想挑战一下，对这个项目做一些有趣的改造？
回复「进入 S4」开始魔改之旅，或回复「结束」完成学习。
中断恢复机制
用户随时可能中断学习（关闭对话、换话题等）。恢复逻辑：
- 进入 S3 时必须先读
schedule.md
- 找到第一个状态为 🔄（进行中）或 ⚪（未开始）的知识点
- 检查其理论列和实践列的具体状态：
- 理论 🔄 + 实践 ⚪ → 理论已讲过但用户未确认"理解"，重新展示理论要点并等待确认
- 理论 ✅ + 实践 ⚪ → 直接进入实践环节
- 理论 ✅ + 实践 🔄 → 实践已布置但用户未确认"完成"，重新展示实践任务并等待确认
- 理论 ⚪ + 实践 ⚪ → 从理论环节开始
- 向用户展示"上次学到哪里"并继续
注意：Step 2 理论讲解开始时，应立即将 schedule.md 中该知识点的状态更新为 🔄、理论列更新为 🔄。Step 3 实践任务布置时，将实践列更新为 🔄。这样即使用户中途中断，下次恢复时也能精确定位到未完成的环节。
产出
| 文件 | 路径 | 说明 |
|---|
schedule.md | <repo-root>/.codojo/schedule.md | 持续更新的进度跟踪表 |
Gotchas
- 答疑时最容易犯的错是偏离当前知识点——用户问了一个相关但属于后续知识点的问题时，简短回答"这个我们后面会讲到"，不要展开
- 实践任务给出的文件路径和行号可能在项目代码更新后失效——布置任务前必须重新读取文件确认行号准确
- 进度条百分比计算容易出错——公式是
已完成知识点数 / 总知识点数 × 100，不要把"进行中"的也算进去
- 理论讲解时容易过长——严格控制在 300-500 字，超了就拆成两次讲
- 不要假设用户的开发环境——布置实践任务的验证方式时，先确认用户能否运行项目（如缺少数据库、缺少依赖等），给出替代验证方式
- schedule.md 的 🔄 状态容易忘记更新——理论开始时、实践开始时都要立即更新，不能等全部完成后才写
- 模块边界容易漏判——每完成一个知识点都要检查下一个知识点是否属于新模块，是则触发 quiz，不要漏掉
- 模块 0（项目全景）完成后不触发 quiz——它只有一个纯理论知识点，不适合出题
不该做的事
- 🚫 用户未回复"理解"就跳到实践环节
- 🚫 用户未回复"完成"就跳到下一个知识点
- 🚫 一次讲太多内容导致信息过载（每次只讲一个知识点）
- 🚫 脱离项目代码讲纯理论（必须结合项目实际代码）
- 🚫 给出虚构的代码示例（必须引用项目真实文件）
- 🚫 忘记更新 schedule.md（每完成一个知识点必须更新）
- 🚫 静默推进到下一阶段（S3 完成后必须询问用户是否进入 S4）
- 🚫 跨模块时跳过 quiz 环节（必须在模块边界触发测验邀请，但用户可以跳过）
- 🚫 用户说跳过测验时劝导或暗示"你应该做测验"（说跳就跳）
- 🚫 模块 0 完成后触发 quiz（纯理论全局认知，不出题）
输出风格约束
详见共用 reference：../_shared/output-style-guide.md
要点：每次交互后展示进度条；理论用 📖 标记，实践用 🔧 标记。
