smart-learn

name	smart-learn
description	独立学习技能，基于费曼学习法的五步闭环。触发方式：输入 /smart-learn 主题，或说"教我XX"、"帮我系统学习XX"。每学完一步自动同步更新 Word 文档 + Mermaid 思维导图。
context	inline

Smart Learn — 增量内联学习技能

基于费曼学习法五步闭环。纯 Markdown 零依赖可用；可选 pip install python-docx 获得 Word 文档功能。每一步学习成果同步更新到 Word 文档 + Mermaid 思维导图，全程实时生长。

触发

• /smart-learn 主题名
• "教我 Kubernetes 网络模型"
• "帮我系统学习 DDD"
• 任何表达出"想系统掌握一个复杂主题"的意图

不触发

• 简单定义（"X是什么"）
• 信息查询（"帮我查一下X"）
• 内容总结（"总结这篇文章"）

核心原则

1. 禁止使用 Agent 工具 — 所有步骤由主对话直接执行
2. 每步可见 — 输出实时展示，用户确认后进入下一步
3. 自然对话 — 不用弹窗确认，用户用自然语言回应即可
4. 零外部依赖（核心） — Markdown 学习 + 存储不依赖任何第三方包
5. 三格式持久化 — .md（知识库笔记，始终生成） + .docx（Word文档，可选） + Mermaid 思维导图（零依赖，始终生成）

---

初始化（Word 文档 + 思维导图）

学习开始前，同时初始化 Word 文档和 Mermaid 思维导图。Word 失败不影响核心流程；思维导图零依赖始终可用。

# 思维导图（零依赖，始终生成）
python .claude/skills/smart-learn/mindmap_utils.py init \
  --topic "主题名" \
  --output-dir "knowledge_store"

# Word 文档（可选，需 python-docx）
python .claude/skills/smart-learn/docx_utils.py init \
  --topic "主题名" \
  --output-dir "knowledge_store"

• 记录 MINDMAP_FILE 和 MINDMAP_DATA 路径，后续每步同步更新

• 如果 docx init 返回 "status": "no_docx" → 告知用户可 pip install python-docx，继续执行

• 智能入口检测：初始化时按以下顺序检查已学记录，以非阻塞提示方式告知用户（不中断流程，用户无需回应即可继续）：

  1. 检查 knowledge_store/{主题slug}_checkpoint.json → 存在 = 有未完成学习
  2. 检查 knowledge_store/{主题}.md 或 knowledge_store/{主题}_学习笔记.docx → 存在 = 已学完
  3. 检查 knowledge_store/ 下文件名含关键词的笔记 → 存在 = 有相关知识

  根据检测结果，在初始化日志中附带提示（不阻塞，不等用户选择）：

  • 有未完成学习 → 告知"💡 检测到未完成的学习（步骤N/5）。输入 继续 可续学，或正常开始全新学习"
  • 已学完该主题 → 告知"💡 你已学过「{主题}」。需要复习时随时输入 /smart-review {主题}"
  • 有相关主题笔记 → 告知"💡 检测到相关笔记「{主题}」，步骤4将自动关联"
  • 无任何记录 → 正常开始
  • 用户如果回应"继续上次" → 跳转到对应步骤恢复
  • 用户如果回应"复习" → 切换到复习流程
  • 用户不回应 → 不阻塞，直接进入步骤1
  • 每完成一步 → 更新 checkpoint（{"topic":"...", "last_step": N, "mindmap_data":"...", "docx_path":"..."}）

---

五步工作流

每一步的核心输出格式保持不变。Word 写入是每步末尾的附加操作。

---

步骤0：前置评估（可选，仅在用户表明已有基础时触发）

触发条件：用户说"我已经了解XX部分"、"XX我比较熟"、"跳过基础直接讲进阶"等。

不触发：用户直接说"/smart-learn 主题"不带任何基础说明 → 跳过步骤0，正常从步骤1开始。

执行：

1. 仍然先执行步骤1生成完整概念地图（确保知识结构完整）
2. 概念地图展示给用户后，额外询问："你对哪些概念已经比较熟悉？"
3. 用户可多选或描述（如"1、2、3 我熟 / 前三个入门的基本都会"）
4. 为每个概念打上用户掌握度标记：
   • 🟢 熟悉 → 步骤2 只讲核心思想+一句话（跳过完整五维），步骤3 只出 1 道边界层题
   • 🟡 了解 → 步骤2 正常讲但可精简，步骤3 正常出题
   • 🔴 新手 → 步骤2 完整五维，步骤3 从最合适层出题
5. 重要：即使是"熟悉"的概念，仍要写入 Markdown 笔记和思维导图（确保笔记完整性），只是在对话中加速讲解。Word 文档中标注 [已掌握]。

约束：

• 步骤0 是可选加速器，不改变五步闭环结构
• 用户标记为"熟悉"的概念 ≠ 不学，只是讲得更快、题更少
• 如果用户发现"熟悉"的概念实际不熟（步骤3答错），自动降级为 🔴 并完整补充

1. 调用 WebSearch 搜索该主题的最新资料（中文优先，确保准确性和及时性）
2. 读取 templates/1-concept-map.md 按模板执行
3. 将主题拆解为 5~8 个子概念，按学习依赖排序，标注难度

固定输出格式：

## 📊 概念地图：{主题}

1. {概念名}（{难度}）→ {一句话解决什么问题}
   ↓
2. {概念名}（{难度}）→ {一句话解决什么问题}
   ↓
...

输出后等待用户回应：

• "继续" / "OK" → 进入步骤2
• "调整XX" → 修改概念地图 → 重新输出 → 重新执行 mindmap 和 Word 同步（覆盖更新） → 重新询问确认

→ 保存检查点（中断恢复用）：

python -c "import json; json.dump({'topic':'{主题}','last_step':1}, open('knowledge_store/{主题slug}_checkpoint.json','w'))"

→ 同步到思维导图（始终执行）：

python .claude/skills/smart-learn/mindmap_utils.py update \
  --file "{MINDMAP_FILE}" --data-file "{MINDMAP_DATA}" --step 1 \
  --concepts '[{"name":"概念1","difficulty":"入门","purpose":"解决问题X"}, ...]'

执行后告知用户：🧠 思维导图已更新：knowledge_store/{主题}_思维导图.md

→ 写入 Word（如果 DOCX_PATH 存在）：

python .claude/skills/smart-learn/docx_utils.py add-step \
  --file "{DOCX_PATH}" --step 1 --title "概念地图" \
  --content-file /tmp/smart-learn-step1.md

执行后告知用户：📄 Word 文档已更新：knowledge_store/{主题}_学习笔记.docx

---

步骤 2：费曼解释

读取 templates/2-feynman.md 按模板执行。对步骤1中的每个概念，逐一用五维框架解释。

每个概念的固定输出结构：

### {序号}. {概念名}

**为什么需要？** → {背景与动机，旧方案有什么问题}
**核心思想** → {一句话说清本质}
**类比理解** → {日常场景类比，完全非技术领域}
**示例** → {最小可运行的代码/真实场景}
**一句话** → {离开后能记住的那句}

每个概念的执行顺序（严格遵守，不可跳过任何一步）：

1. 输出该概念的五维解释
        ↓
2. ⚡ 执行 mindmap 同步命令（必须实际运行 Bash，不可只声明）
        ↓
3. ⚡ 将解释内容写入临时文件，执行 Word 写入命令（必须实际运行 Bash）
        ↓
4. 告知用户文件已更新（显示路径）
        ↓
5. 询问用户：继续 / 修改 / 换类比 / 提问

用户回应后的处理：

用户回应	处理方式
"继续" / "下一个"	已完成同步，直接讲下一个概念
"修改XX部分"	按反馈调整解释 → 重新执行步骤 1→2→3→4→5（mindmap 覆盖更新，Word 以 {概念名}（修正） 追加修订版）
"换一个类比" / "没懂"	用不同类比重讲，用户确认后执行步骤 2→3→4→5
任意提问	针对性解答，确认后继续

→ 同步到思维导图（每概念确认后必须执行）：

python .claude/skills/smart-learn/mindmap_utils.py update \
  --file "{MINDMAP_FILE}" --data-file "{MINDMAP_DATA}" --step 2 \
  --concept "{概念名}" --core "{核心思想摘要}" --analogy "{类比关键词}"

执行后告知用户：🧠 已同步到思维导图：knowledge_store/{主题}_思维导图.md

→ 写入 Word（每概念确认后必须执行）：

# 先将该概念的完整 Markdown 解释写入临时文件
cat > /tmp/smart-learn-step2-concept.md << 'EOF'
### {序号}. {概念名}

**为什么需要？**
{解释内容}
...
EOF
python .claude/skills/smart-learn/docx_utils.py add-step \
  --file "{DOCX_PATH}" --step 2 --title "{序号}. {概念名}" \
  --content-file /tmp/smart-learn-step2-concept.md

执行后告知用户：📄 已写入 Word：knowledge_store/{主题}_学习笔记.docx

全部概念讲完后，用 3~5 句话串联串讲，然后进入步骤3。

禁止：

• 用未解释的术语解释另一个术语
• 从定义开始（必须从"为什么需要"开始）
• 类比用另一个技术概念
• 声明"已同步"但未实际执行 Bash 命令（这是最严重的执行错误）

---

步骤 3：递进式自测

读取 templates/3-self-test.md 按模板执行。为每个概念出 1 道题，从三层中选最合适的一层：

层次	考察目标	适合什么概念
理解层	改变条件问变化	核心机制类（如缓存策略）
应用层	新场景设计方案	工程实践类（如API设计）
边界层	什么时候失效	理论约束类（如CAP定理）

每题的执行顺序（严格遵守）：

1. 出题，等待用户回答
        ↓
2. 给出点评 + 参考答案 + 掌握度
        ↓
3. ⚡ 如果是 ❌ 薄弱 → 执行 mindmap 标记命令
        ↓
4. ⚡ 执行 Word 写入命令（含题目+回答+点评+参考答案）
        ↓
5. 告知用户文件已更新
        ↓
6. 出下一道题（或汇总）

逐个提问，每次只出一道题。用户回答后给出：

• 点评：具体评价哪里好、哪里不足
• 参考答案：一个高质量的示范回答
• 掌握度：✅ 已掌握 / ⚠️ 部分掌握 / ❌ 薄弱

全部完成后汇总薄弱点，询问用户：

• "继续" → 进入步骤4
• "回顾薄弱概念" → 对每个 ❌ 薄弱概念：
  1. 用不同的类比重新解释该概念（不重复步骤2的原版）
  2. 出一道新的同类层级的题目
  3. 用户回答后点评
  4. 直到掌握度变为 ✅/⚠️ 或用户说"先继续"
  5. 更新思维导图移除该概念的 ⚠️ 标记（如果已掌握）
  6. 薄弱概念回顾的每一步也要同步到 Word（追加"回顾修正"记录）

→ 同步到思维导图（每题点评后，❌ 薄弱则必须执行）：

python .claude/skills/smart-learn/mindmap_utils.py update \
  --file "{MINDMAP_FILE}" --data-file "{MINDMAP_DATA}" --step 3 \
  --concept "{概念名}" --weak "{薄弱原因摘要}"

执行后告知用户：🧠 {概念名} 已标记薄弱点到思维导图

→ 写入 Word（每题点评后必须执行）：

cat > /tmp/smart-learn-step3-q.md << 'EOF'
**问题**：{题目}
**你的回答**：{用户回答摘要}
**点评**：{点评}
**参考答案**：{参考答案}
**掌握度**：{✅/⚠️/❌}
EOF
python .claude/skills/smart-learn/docx_utils.py add-step \
  --file "{DOCX_PATH}" --step 3 --title "{概念名} — 自测" \
  --content-file /tmp/smart-learn-step3-q.md

执行后告知用户：📄 自测记录已写入 Word

---

步骤 4：关联内化

读取 templates/4-association.md 按模板执行。

1. 用 Glob 检查 knowledge_store/ 下已有的学习笔记
2. 如果有相关主题，做四维对比：
   • 解决的是同一个问题吗？
   • 哪些经验可以直接迁移？
   • 新概念有什么独特性？
   • 知识地图中位置关系？
3. 如果没有，告知"这是该领域的第一个知识节点"
4. 输出文本版知识网络图

步骤4的执行顺序（严格遵守）：

1. 检索并输出知识网络图
        ↓
2. ⚡ 对每个关联主题执行 mindmap 关联命令
        ↓
3. ⚡ 执行 Word 写入命令（含对比表格和网络图）
        ↓
4. 告知用户文件已更新
        ↓
5. 询问用户：继续 / 补充关联

用户回应：

• "继续" → 进入步骤5
• "补充关联" → 用户提出更多关联角度 → 追加分析 → 重新执行步骤 2→3→4（mindmap 自动去重，Word 追加新关联）

→ 同步到思维导图（每个关联主题必须执行）：

python .claude/skills/smart-learn/mindmap_utils.py update \
  --file "{MINDMAP_FILE}" --data-file "{MINDMAP_DATA}" --step 4 \
  --assoc-target "{关联主题名}" --assoc-relation "{一句话关系}"

执行后告知用户：🧠 知识关联已添加到思维导图

→ 写入 Word（必须执行）：

cat > /tmp/smart-learn-step4.md << 'EOF'
{关联分析的对比表格和网络图内容}
EOF
python .claude/skills/smart-learn/docx_utils.py add-step \
  --file "{DOCX_PATH}" --step 4 --title "关联内化" \
  --content-file /tmp/smart-learn-step4.md

执行后告知用户：📄 关联分析已写入 Word

---

步骤 5：巩固总结并保存

读取 templates/5-summary.md 按模板执行。

输出精华笔记（≤500 字）：

## 🎯 核心公式
{一句"懂了就懂了80%"的话}

## 🔑 三个关键点
1. {洞察一}
2. {洞察二}
3. {洞察三}

## ⚠️ 薄弱点
- **{具体薄弱点}**：{为什么容易搞混} → {正确理解}（首次标记：{今天日期}）

## 🏗️ 一句话类比
{日常场景一句话总结}

## 🏷️ 关键词
`{k1}` `{k2}` `{k3}` `{k4}` `{k5}`

输出精华笔记后等待用户回应：

• "保存" → 写入所有文件（见下方持久化步骤）
• "修改XX" → 调整对应部分 → 重新输出完整精华笔记 → 重新询问确认（确认后一次性写入所有文件）

持久化（用户确认后执行）：

1. 必做：将完整五步报告写入 knowledge_store/{主题slug}.md
2. 必做：最终化思维导图：

python .claude/skills/smart-learn/mindmap_utils.py finalize \
  --file "{MINDMAP_FILE}" --data-file "{MINDMAP_DATA}" \
  --summary "{核心公式}" \
  --weak-points "{薄弱点1; 薄弱点2}" \
  --keywords "{k1, k2, k3, k4, k5}"

3. 可选：最终化 Word 文档：

python .claude/skills/smart-learn/docx_utils.py finalize \
  --file "{DOCX_PATH}" \
  --summary "{核心公式}" \
  --weak-points "{薄弱点1; 薄弱点2}" \
  --keywords "{k1, k2, k3, k4, k5}"

最后以可点击路径告知用户全部产出物位置：

• 📝 Markdown 笔记：knowledge_store/{主题slug}.md
• 🧠 思维导图：knowledge_store/{主题}_思维导图.md（Mermaid 格式，GitHub/VSCode 原生渲染）
• 📄 Word 文档：knowledge_store/{主题}_学习笔记.docx（如有）
• ⚠️ 薄弱点列表：（逐一列出）

→ 清理临时文件和检查点（学习完成）：

rm -f /tmp/smart-learn-step*.md /tmp/smart-learn-concept*.md
rm -f knowledge_store/{主题slug}_checkpoint.json

---

同步更新流程图

/smart-learn 主题
     │
     ├─ 初始化 ──→ 🧠 创建空白思维导图 + 📄 创建 Word（可选）
     │
     ├─ 步骤1 ──→ 🧠 写入概念节点 + 📄 写入概念地图
     │
     ├─ 步骤2 ──→ 🧠 每概念追加核心思想/类比 + 📄 写入解释
     │
     ├─ 步骤3 ──→ 🧠 标记薄弱点 ⚠️ + 📄 写入问答记录
     │
     ├─ 步骤4 ──→ 🧠 追加知识关联 🔗 + 📄 写入对比分析
     │
     └─ 步骤5 ──→ 🧠 最终化思维导图 + 📄 最终化 Word + 📝 Markdown

---

知识连续性

• 学习前检查 knowledge_store/ 目录已有笔记
• 发现关键词匹配的旧笔记时，主动在步骤4做关联
• 所有笔记（.md + .docx + 思维导图.md）保存到同一目录，形成累积知识库

模板与工具

文件	用途	依赖
templates/1-concept-map.md	概念地图模板	无
templates/2-feynman.md	费曼解释模板	无
templates/3-self-test.md	递进式自测模板	无
templates/4-association.md	关联内化模板	无
templates/5-summary.md	巩固总结模板	无
mindmap_utils.py	Mermaid 思维导图同步生成	零依赖
docx_utils.py	Word 文档增量生成	python-docx（可选）