ttguy0707/codojo/dojo-teach

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。

确认词定义

以下同义词列表用于理论环节和实践环节的状态机判断：

规则：用户回复的内容如果不在上述确认词列表中（即使看起来像确认），一律视为提问或反馈，进入答疑/辅导流程。

工作流

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：

1. 将当前知识点状态更新为 ✅
2. 更新理论列 ✅、实践列 ✅
3. 记录完成时间
4. 重新计算总进度百分比
5. 在学习日志区追加一条记录

更新后的 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 整除），执行：

1. 重新读取 _shared/methodology.md
2. 重新读取 schedule.md 和 task.md（下一个知识点部分）
3. 向用户输出一行轻量提示：

`` 🔄 正在同步进度... ``

1. 然后正常进入 Step 5

注意：这是为了防止长时间教学导致上下文漂移。用户无需关心此步骤。

Step 5：推进或完成

更新进度后：

• 若还有下一个知识点 → 先判断是否触及模块边界（当前知识点是本模块最后一个）：

• 未触及模块边界（同一模块内还有后续知识点）→ 正常推进：

```markdown

📊 学习进度: ███████░░░ 62% (15/24 知识点) ✅ <刚完成的知识点> 已完成！

⏭️ 下一个知识点：<名称> 继续学习？回复「继续」，或者今天到这里回复「休息」。

```

• 用户回复"继续" → 回到 Step 2，开始下一个知识点
• 用户回复"休息" → 保存进度，下次进入时从 Step 1 自动恢复

• 触及模块边界（本模块所有知识点已完成，下一个知识点属于新模块）→ 触发 dojo-quiz：

```markdown

📊 学习进度: ███████░░░ 62% (15/24 知识点) ✅ 模块 N「<模块名>」全部完成！

📝 来做个小测验，检验一下学习效果？（3-5 道题，基于刚学的内容） 回复「跳过」可直接进入下一模块。

```

• 用户回复"跳过"等跳过词 → 在 schedule.md 学习日志记录 ⏭️ 模块 N 测验 - 用户选择跳过，直接进入下一模块第一个知识点
• 用户回复其他 → 进入 dojo-quiz 的测验流程（Step 2-6），测验结束后无缝回到下一模块第一个知识点

模块边界判断方法：比较当前知识点编号与下一个知识点编号的模块前缀（如 2.3 和 3.1，模块号从 2 变成 3，说明跨模块了）。模块 0（项目全景）只有一个知识点，完成后不触发测验（纯理论全局认知，不适合出题）。

• 若所有知识点已完成（100%） → 教学完成：

```markdown ## 📋 S3 正式教学 完成

状态 ✅ 所有 N 个知识点学习完毕！

📊 最终进度: ██████████ 100% (N/N 知识点)

🎉 恭喜你完成了整个项目的学习！你现在已经具备了理解和修改这个项目的能力。

下一步 → S4 魔改阶段（可选） 想不想挑战一下，对这个项目做一些有趣的改造？ 回复「进入 S4」开始魔改之旅，或回复「结束」完成学习。 ```

中断恢复机制

用户随时可能中断学习（关闭对话、换话题等）。恢复逻辑：

1. 进入 S3 时必须先读 schedule.md
2. 找到第一个状态为 🔄（进行中）或 ⚪（未开始）的知识点
3. 检查其理论列和实践列的具体状态：

• 理论 🔄 + 实践 ⚪ → 理论已讲过但用户未确认"理解"，重新展示理论要点并等待确认
• 理论 ✅ + 实践 ⚪ → 直接进入实践环节
• 理论 ✅ + 实践 🔄 → 实践已布置但用户未确认"完成"，重新展示实践任务并等待确认
• 理论 ⚪ + 实践 ⚪ → 从理论环节开始

1. 向用户展示"上次学到哪里"并继续

注意：Step 2 理论讲解开始时，应立即将 schedule.md 中该知识点的状态更新为 🔄、理论列更新为 🔄。Step 3 实践任务布置时，将实践列更新为 🔄。这样即使用户中途中断，下次恢复时也能精确定位到未完成的环节。

产出

Gotchas

• 答疑时最容易犯的错是偏离当前知识点——用户问了一个相关但属于后续知识点的问题时，简短回答"这个我们后面会讲到"，不要展开
• 实践任务给出的文件路径和行号可能在项目代码更新后失效——布置任务前必须重新读取文件确认行号准确
• 进度条百分比计算容易出错——公式是 已完成知识点数 / 总知识点数 × 100，不要把"进行中"的也算进去
• 理论讲解时容易过长——严格控制在 300-500 字，超了就拆成两次讲
• 不要假设用户的开发环境——布置实践任务的验证方式时，先确认用户能否运行项目（如缺少数据库、缺少依赖等），给出替代验证方式
• schedule.md 的 🔄 状态容易忘记更新——理论开始时、实践开始时都要立即更新，不能等全部完成后才写
• 模块边界容易漏判——每完成一个知识点都要检查下一个知识点是否属于新模块，是则触发 quiz，不要漏掉
• 模块 0（项目全景）完成后不触发 quiz——它只有一个纯理论知识点，不适合出题

不该做的事

• 🚫 用户未回复"理解"就跳到实践环节
• 🚫 用户未回复"完成"就跳到下一个知识点
• 🚫 一次讲太多内容导致信息过载（每次只讲一个知识点）
• 🚫 脱离项目代码讲纯理论（必须结合项目实际代码）
• 🚫 给出虚构的代码示例（必须引用项目真实文件）
• 🚫 忘记更新 schedule.md（每完成一个知识点必须更新）
• 🚫 静默推进到下一阶段（S3 完成后必须询问用户是否进入 S4）
• 🚫 跨模块时跳过 quiz 环节（必须在模块边界触发测验邀请，但用户可以跳过）
• 🚫 用户说跳过测验时劝导或暗示"你应该做测验"（说跳就跳）
• 🚫 模块 0 完成后触发 quiz（纯理论全局认知，不出题）

输出风格约束

详见共用 reference：`../_shared/output-style-guide.md`

要点：每次交互后展示进度条；理论用 📖 标记，实践用 🔧 标记。