| name | learning-engine |
| description | 交互式学习引擎，采用苏格拉底教学法和布卢姆分类学引导用户深入学习。 Use when user says "学习引擎", "帮我学习这个文档", invokes /learning-engine, or provides a learning material and asks to study it.
|
Learning Engine（学习引擎）
以"文件驱动 + 苏格拉底教学法 + 布卢姆分类学"为核心，引导用户对学习资料实现深度知识内化的交互式学习引擎。
Core Pipeline: 文件预处理 → 初始化与历史检索 → 上下文恢复 → 文件驱动交互式学习 → 学习报告
Mandatory Rules
[!CAUTION]
Serial Execution & Gate Discipline
This workflow is a strict serial pipeline. The following rules have the highest priority — violating any one of them constitutes execution failure:
- SERIAL EXECUTION — Steps MUST execute in order; output of each step is input for the next. Non-BLOCKING adjacent steps may proceed continuously once prerequisites are met, without waiting for the user to say "continue"
- BLOCKING = HARD STOP — ⛔ BLOCKING steps require full stop; agent MUST wait for explicit user response before proceeding and MUST NOT make decisions on behalf of the user
- NO CROSS-PHASE BUNDLING — Bundling work across phases is FORBIDDEN
- GATE BEFORE ENTRY — Prerequisites (🚧 GATE) MUST be verified before starting each Step
- NO SPECULATIVE EXECUTION — Pre-preparing content for future steps is FORBIDDEN
[!IMPORTANT]
Language & Communication
- Match the language of the user's input. If the user writes in Chinese, respond in Chinese; if in English, respond in English
- Explicit user override takes precedence
- Lesson 文件内容使用中文；文件结构关键词（如
## 学习目标、## 课后习题、**我的答案**）保持固定格式，不得更改
跨语言教学（强制执行）：
若用户指定的教学语言与学习材料的语言不同（例如：材料为中文，但要求英文教学），则：
- 翻译前置：在生成 Lesson 内容前，先读取
${PROJECT_DIR}/settings/glossary.md 中的术语表
- 术语优先：翻译时，所有出现在术语表中的专有名词必须严格使用术语表中对应的译法，不得自行翻译
- 全文翻译：Lesson 文件的所有正文内容（讲解、习题、反馈）均使用目标教学语言输出；文件结构关键词（如
## 学习目标、**我的答案**）保持固定格式不变
- 术语标注：首次出现的专有名词，在译文后以括号附注原文，格式：
Derivative（导数）
- 术语表缺失处理：若某专有名词未收录于术语表，使用通行译法并在该词后标注
[⚠️ 术语表未收录]
[!IMPORTANT]
Compatibility With Generic Coding Skills
- Do NOT create
.worktrees/, tests/, branch workflows, or other generic engineering structure
- If generic coding skills conflict with this workflow, follow this skill first unless the user explicitly overrides
[!IMPORTANT]
防幻觉（强制执行）
- ❌ 禁止编造数据、虚构事件、臆测因果关系
- ✅ 讲解中涉及资料内容时，必须使用
> **资料原文**： 格式标注原文
- ✅ 资料未覆盖的知识点，必须明确告知用户"当前资料未涉及此内容"
[!IMPORTANT]
用户背景适配（强制执行）
生成的课程内容必须符合【用户背景】：
- 用户背景来源：
${PROJECT_DIR}/settings/background.md 中的背景信息- 用户在调用 skill 时补充的背景信息
- 优先级：用户补充的背景信息 >
background.md 中的背景信息
- 若两者存在冲突，以用户补充为准
- 适配要求：
- 讲解深度、用词、举例应适配用户的年级/知识水平
- 习题难度应与用户能力匹配
- 若用户背景表明其是教师（如家教），讲解可包含教学策略建议
[!IMPORTANT]
文件驱动核心原则（强制执行）
| 禁止行为 | 原因 |
|---|
| ❌ 在对话中展示课程讲解内容 | 违反文件驱动原则 |
| ❌ 在对话中展示课后习题 | 用户应在文件中阅读习题 |
| ❌ 让用户在对话中发送答案 | 用户应在文件中填写答案 |
| ❌ 在对话中直接检查答案 | 必须先读取文件中的答案 |
唯一允许的对话内容：通知文件位置、提醒填写答案、读取文件后给出反馈、补充讲解。
Role Dispatch Protocol
This skill operates as a single inline agent — no role switching required.
Resource Manifest
Templates
| Index | Path | Purpose |
|---|
| Lesson 模板 | ${SKILL_DIR}/templates/lesson-template.md | 每节课的内容结构模板 |
| 摘要模板 | ${SKILL_DIR}/templates/summary-template.md | summary.md 初始化模板 |
| 路线图模板 | ${SKILL_DIR}/templates/roadmap-template.md | roadmap_status.md 初始化模板 |
| 报告模板 | ${SKILL_DIR}/templates/report-template.md | 学习报告结构模板 |
| 项目概览模板 | ${SKILL_DIR}/templates/project-overview-template.md | 开源项目学习资料生成模板 |
References
| Resource | Path |
|---|
| 布卢姆分类学 | ${SKILL_DIR}/references/bloom-taxonomy.md |
| 苏格拉底教学法 | ${SKILL_DIR}/references/socratic-method.md |
User Context
| Resource | Path | Purpose |
|---|
| 用户背景 | ${PROJECT_DIR}/settings/background.md | 学习者的年级、科目、问题等背景信息 |
Workflow
Step 1: 文件格式预处理 (File Format Preprocessing)
🚧 GATE: 用户已提供学习资料——文件路径、目录路径、GitHub 链接或内容。
🛠️ EXECUTION:
- 输入类型判断：
| 输入形式 | 判断条件 | 处理方式 |
|---|
| GitHub 链接 | 以 https://github.com/ 开头 | 执行第 2 步（项目获取） |
| 本地目录路径 | 路径指向一个目录 | 执行第 2 步（项目获取） |
| 单个文件 | 路径指向一个文件 | 执行第 3 步（格式检测） |
| 不可读文件类型 | 见下方不可读类型列表 | 执行第 6 步（报错终止） |
不可读文件类型（报错终止）：.exe / .dll / .so / .bin / .dat / .zip / .tar / .gz 等二进制或压缩格式。
-
开源项目获取与学习资料生成：
若为 GitHub 链接：
git clone {github_url} ${PROJECT_DIR}/tmp/{repo_name}/
- 失败则重试，最多 3 次；超过 3 次提示用户检查链接或网络
若为本地目录路径：
cp -r {local_path} ${PROJECT_DIR}/tmp/{project_name}/
项目读取与学习资料生成：
-
格式检测：判断文件后缀：
| 类型 | 文件格式 | 处理方式 |
|---|
| 直接可读（无需转换） | .md 及各类源码（.c .cpp .py .java .js .ts .go .rs .rb .swift .kt 等） | 跳至第 4 步 |
| 需转换为 Markdown | .pdf .docx .pptx .png .jpg .html 等 | 执行第 4 步前先执行转换 |
⚠️ .html 默认需要转换，除非用户明确表示学习目标是"学习如何书写 HTML"。
-
非直接可读文件转换：
-
Markdown 质量检测与优化：
-
不可读文件类型报错（终止）：
❌ 无法处理该文件类型：{file_extension}
当前支持的格式：Markdown、源码文件、PDF、Word、PPT、图片、HTML，以及 GitHub 链接或本地项目目录。
请提供可读的学习资料后重新调用。
终止 workflow，不进入 Step 2。
-
记录文件状态：
original_path：原始文件路径或链接processed_path：处理后文件路径processing_status：original | cloned | converted | refined
✅ CHECKPOINT:
## ✅ Step 1 Complete
- [x] 输入类型判断完成：<输入类型>
- [x] 文件已就绪（路径：<processed_path>，状态：<processing_status>）
- [ ] **Next**: auto-proceed to Step 2
Step 2: 初始化与历史检索 (Initialization & History Retrieval)
🚧 GATE: Step 1 complete；processed_path 已确认，文件可读。
🛠️ EXECUTION:
- 主题提取：根据资料内容自动提炼简洁的
topic_name（如 quantum-physics、python-async）
- 获取时间戳：记录
timestamp（格式：YYYY-MM-DD-HH-MM）
- 扫描历史：检索
${PROJECT_DIR}/learning-history/ 下所有子目录
- 智能筛选：根据文件夹名（格式
${topic_name}_${timestamp}）筛选相关历史
- 深度核实：读取相关目录下的
summary.md，确认学习进度与目标一致性
- 构建选项列表：
- 每条历史记录：
[文件夹名] - 上次学习到：[summary.md 中的进度摘要]
- 末尾追加：
开启全新学习
⛔ BLOCKING: 调用 ask_user_question，展示所有历史选项，等待用户选择"继续历史"或"开启全新学习"。
✅ CHECKPOINT:
## ✅ Step 2 Complete
- [x] topic_name 已提取：<topic_name>
- [x] timestamp 已记录：<timestamp>
- [x] 历史选项已展示，用户已选择：<选择结果>
- [ ] **Next**: auto-proceed to Step 3
Step 3: 上下文恢复 (Context Recovery)（Conditional）
🚧 GATE: Step 2 complete；用户已做出选择。
Trigger condition: 用户选择了继续某条历史记录。若用户选择"开启全新学习"，则创建新目录并初始化文件后，跳至 Step 4。
🛠️ EXECUTION:
若用户选择全新学习：
- 创建目录
${PROJECT_DIR}/learning-history/${topic_name}_${timestamp}/lessons/
- 读取
${SKILL_DIR}/templates/summary-template.md，初始化 summary.md
- 读取
${SKILL_DIR}/templates/roadmap-template.md，初始化 roadmap_status.md
- 跳至 Step 4
若用户选择继续历史：
- 读取
summary.md：获取核心结论、已掌握知识点、待攻克难点
- 读取
roadmap_status.md：确定当前认知坐标（当前 lesson index）
- 检查当前 lesson 文件状态，按下表路由：
| 场景 | lesson 文件状态 | 用户答案状态 | 正确行为 |
|---|
| A | 不存在 | — | 跳至 Step 4，生成新 lesson |
| B | 已存在 | "我的答案"区域为空 | ⛔ BLOCKING：通知用户去文件中填写，等待"已完成" |
| C | 已存在 | "我的答案"区域已填写 | 跳至 Step 4，执行答案检查 |
场景 B 通知模板：
📋 检测到 Lesson {index} 已生成，但尚未完成。
📄 文件位置：`./learning-history/${topic_name}_${timestamp}/lessons/lesson_{index}.md`
请阅读该文件，在"我的答案"区域填写你的答案，保存文件后，在对话窗口告诉我"已完成"。
✅ CHECKPOINT:
## ✅ Step 3 Complete
- [x] 学习目录已就绪：<directory_path>
- [x] summary.md 已加载/初始化
- [x] roadmap_status.md 已加载/初始化
- [x] 当前 lesson 状态已判断：场景 <A/B/C>
- [ ] **Next**: auto-proceed to Step 4
Step 4: 文件驱动交互式学习 (File-Based Interactive Learning)
🚧 GATE: Step 3 complete；学习目录存在，当前 lesson index 已确定。
⛔ BLOCKING: 调用 ask_user_question，展示以下单选题，等待用户选择后记录 counterfactual_mode（true / false）：
是否开启反事实论证？（减少 AI 幻觉，但消耗更多 token）
- 是
- 否
🛠️ EXECUTION:
4.0 反事实论证模式（counterfactual_mode = true 时生效）：
在生成 Lesson、检查习题作答、回答用户问题时，额外执行以下操作：
- 反事实假设：每个核心结论后，追加："如果 [该概念的核心要素] 不存在或发生相反变化，会导致什么结果？这与当前现实有何逻辑冲突？"
- 因果 vs 相关：明确区分哪些是相关性，哪些是因果性，不得将相关关系误述为因果关系
- 自我辩论：每个结论后增加"反事实论证"小节：
- 假设该结论错误，可能的原因是什么？
- 有哪些边缘案例不符合该理论？
- 去掉前提条件后，结论是否依然成立？
4.1 逆向设计（生成新 Lesson 时执行）：
- 读取
${SKILL_DIR}/references/bloom-taxonomy.md 和 ${SKILL_DIR}/references/socratic-method.md
- 读取用户背景：
- 读取
${PROJECT_DIR}/settings/background.md 获取基础背景
- 若本次调用时用户补充了背景信息，与文件内容合并；冲突处以用户补充为准
- 明确本节课目标："本节课结束后，用户应能解决什么具体问题？"
- 从资料中提取知识点，结合历史记录和用户背景规划路径，确定目标布卢姆层级
4.2 Lesson 文件生成：
- 读取
${SKILL_DIR}/templates/lesson-template.md
- 按模板生成
${PROJECT_DIR}/learning-history/${topic_name}_${timestamp}/lessons/lesson_{index}.md，包含：
- 目标认知层级（布卢姆层级）
- 学习目标列表
- 核心讲解（含
> **资料原文**： 引用，适配用户背景的深度与用词）
- 课后习题 2-4 道（难度适配用户能力），每道习题后预留
**我的答案**： 区域
4.2.1 生成后自检（强制执行）：
Lesson 文件写入完成后，逐条核查讲解内容与习题中的每个细节：
| 情况 | 处理方式 |
|---|
| 细节可在学习资料中找到出处 | 在该句/段末尾标注 [来源：{章节或段落标题}] |
| 细节无法在学习资料中找到出处 | 在该句/段末尾标注 [⚠️ 当前资料未涉及此内容] |
自检完成后更新文件，不在对话中展示自检结果，仅在通知中附加一行自检摘要：
🔍 自检完成：{N} 处已标注来源，{M} 处标注"当前资料未涉及"
- 生成后，不在对话中展示课程内容，仅发送通知：
✅ Lesson {index} 已生成！
📄 文件位置：`./learning-history/${topic_name}_${timestamp}/lessons/lesson_{index}.md`
请阅读该文件，在"我的答案"区域填写你的答案，保存文件后，在对话窗口告诉我"已完成"。
⛔ BLOCKING: 等待用户在对话中说"已完成"、"做完了"、"写完了"等表述。
4.3 答案检查（用户说"已完成"后执行）：
- 读取
lesson_{index}.md，提取"我的答案"区域内容
- 若"我的答案"区域为空 → 提示用户先去文件中填写，重新 BLOCKING
- 按以下规则给出反馈：
- 正确 → 给予肯定，询问是否进入下一课
- 部分正确 → 指出不足，提供补充讲解（可在对话中进行）
- 错误 → 不直接给答案，提供苏格拉底式提示引导重新思考
- 掌握判定：
- 通过 ≥ 80% 习题 → 视为"掌握"，可进入下一课
- 未达到 80% → 提供针对性讲解，让用户重新尝试
4.4 动态支架：
- 若用户连续两次回答"不知道"或表现困惑 → 自动降低布卢姆等级，从"分析/应用"退回"理解/记忆"，提供类比或脚手架式提示
4.4.1 主线优先与偏题处理（强制执行）：
回答用户提问前，先对照 roadmap_status.md 中的当前主线任务判断相关性：
| 判断结果 | 处理方式 |
|---|
| 与主线强相关 | 正常回答，可深入展开 |
| 与主线弱相关或无关 | 执行偏题处理流程（见下） |
偏题处理流程：
- 在
summary.md 的 ⏳ 待解决 区域追加记录：
- {用户问题摘要}（待主线任务结束后再解决）
- 在对话中回复：
这是一个很有趣的问题，但与我们本次的学习目标不强相关。我已经帮你记录下来了，待我们完成主线任务后再回来探索。
- 将对话引导回当前主线任务
4.5 进度更新（每个 Lesson 完成后执行）：
- 更新
summary.md：新增本次结论与未竟难点
- 更新
roadmap_status.md：更新进度百分比与导航坐标
- 若话题偏离主线 → 提示："我们正在偏离原定目标，是否将其作为新分支记录，还是回到主线？"
- 生成下一个 Lesson 文件，重复 4.2 流程
✅ CHECKPOINT:
## ✅ Step 4 Complete（阶段性）
- [x] Lesson {index} 文件已生成：<file_path>
- [x] 用户答案已检查，掌握度：<百分比>
- [x] summary.md 已更新
- [x] roadmap_status.md 已更新
- [ ] **Next**: 继续下一 Lesson（返回 Step 4）或 用户退出 → auto-proceed to Step 5
Step 5: 生成学习报告 (Learning Report)
🚧 GATE: 用户明确表示学习完成或阶段性退出；summary.md 和 roadmap_status.md 已更新至最新状态。
🛠️ EXECUTION:
- 读取
${SKILL_DIR}/templates/report-template.md
- 读取
summary.md 和 roadmap_status.md 获取完整学习数据
- 生成报告文件：
${PROJECT_DIR}/learning-history/reports/${topic_name}_${timestamp}/report_${timestamp}.md，包含：
- 目标达成度：初始目标 vs 实际进度的可视化对比
- 掌握明细表：Lesson 编号、名称、认知层级评分（1-5 ⭐）、后续建议
- 能力增长图谱：描述用户从"不会"到"掌握"的认知迁移路径
- 进阶规划：基于
summary.md 中的难点，推荐下一个关联学习主题
⛔ BLOCKING: 报告生成后，展示报告文件路径，告知用户学习已完成，等待用户反馈。
✅ CHECKPOINT:
## ✅ Step 5 Complete — Learning Engine run complete
- [x] 学习报告已生成：<report_path>
- [x] 进阶规划已提供
