Back to Details

interactive-learner

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Interactive Learner

交互式学习工具

Create deeply researched, engaging, interactive courses on any topic. Lessons open in the browser with a mix of click-based exercises, open-ended challenges, real-world missions, and AI-evaluated responses. Every course is personalized, evidence-based, and a little adventurous.
针对任意主题创建经过深度调研、引人入胜的交互式课程。课程会在浏览器中打开，包含点击式练习、开放式挑战、真实任务以及AI评估反馈等多种形式。每一门课程都是个性化、基于实证且充满趣味的。

Workflow

工作流程

New course: Profile → Research → Curriculum → Session → Build → Debrief

新课程：学员画像调研 → 主题研究 → 课程大纲设计 → 学习阶段规划 → 课程内容构建 → 学习复盘

1. Profile the student (first time only)

1. 构建学员画像（仅首次使用）

Keep profiling fast and frictionless. The student wants to learn, not fill out forms.
Rules:
  • Prefer multiple-choice questions. They're faster to answer and give you structured data. Use the agent's question tool with concrete options wherever possible.
  • Max 1 open-ended question at a time. Never dump multiple open questions in one message.
  • Max 3-4 profiling questions total. Infer the rest from context and conversation.
  • Start teaching quickly. You can refine the profile during the first session based on how they perform.
What to gather (in order of priority):
  1. Experience level with this topic (multiple-choice: none / some exposure / use it occasionally / use it daily)
  2. Goal (multiple-choice: career / hobby / curiosity / specific task + optional free text)
  3. Time per session (multiple-choice: ~10 min / ~20 min / ~30+ min)
  4. Background — only if not obvious from context (one open question max, e.g. "What's your day job or main interest?")
Infer (don't ask): learning pace, jargon tolerance, visual vs text preference, analogies from their domain.
See student-profiling.md for the full profiling framework.
Initialize progress:
All scripts use 
uv run
. If 
uv
is not available, use 
python3
instead.
Path note: 
.agents/skills/
and 
.claude/skills/
are symlinked — both paths reference the same location. Examples below use 
.agents/
.
bash
uv run .agents/skills/interactive-learner/scripts/progress.py init <course> <name>
保持画像调研快速顺畅。学员想要的是学习，而非填写冗长表单。
规则：
  • 优先使用选择题。这类问题回答速度更快，且能提供结构化数据。尽可能使用Agent的提问工具提供明确选项。
  • 每次最多1个开放式问题。切勿在一条消息中抛出多个开放式问题。
  • 总共最多3-4个调研问题。其余信息从上下文和对话中推断。
  • 尽快开始教学。你可以在第一个学习阶段根据学员的表现完善其画像。
需要收集的信息（按优先级排序）：
  1. 学员对该主题的经验水平（选择题：无经验 / 略有了解 / 偶尔使用 / 日常使用）
  2. 学习目标（选择题：职业发展 / 兴趣爱好 / 满足好奇心 / 特定任务 + 可选自由文本补充）
  3. 每次学习的时长（选择题：约10分钟 / 约20分钟 / 30分钟以上）
  4. 背景信息 — 仅当上下文无法体现时收集（最多1个开放式问题，例如：“你的日常工作或主要兴趣是什么？”）
通过推断获取（无需询问）：学习节奏、术语接受度、视觉/文本偏好、与学员领域相关的类比。
完整的画像调研框架请参考 student-profiling.md。
初始化学习进度：
所有脚本均使用 
uv run
执行。若未安装 
uv
，可使用 
python3
替代。
路径说明： 
.agents/skills/
和 
.claude/skills/
为符号链接 — 两个路径指向同一位置。以下示例使用 
.agents/
。
bash
uv run .agents/skills/interactive-learner/scripts/progress.py init <course> <name>

2. Research the topic thoroughly

2. 对主题进行全面研究

This is critical. Do not skip or rush this step. Before designing any curriculum, become an expert on the subject.
Deep research protocol:
  1. Search for authoritative, recent sources — prioritize official documentation, peer-reviewed content, respected practitioners, and recent (2024-2026) material
  2. Find the best learning resources that already exist — outstanding blog posts, interactive tutorials, YouTube channels, open-source tools, practice sandboxes, visualization tools, community forums
  3. Identify the conceptual structure — what are the foundational concepts? What depends on what? What are the common misconceptions? What's the optimal learning order?
  4. Discover the "aha moments" — what analogies, visualizations, or exercises make this topic click for people? What do the best teachers do differently?
  5. Collect real-world examples — case studies, war stories, practical applications that make abstract concepts tangible
  6. Find hands-on resources — playgrounds, sandboxes, tools the student can actually use during the course
Save research notes to a file the student can reference later:
bash
undefined
这一步至关重要，切勿跳过或仓促完成。 在设计任何课程大纲之前，先成为该主题的专家。
深度研究流程：
  1. 查找权威、最新的资料 — 优先选择官方文档、经同行评审的内容、知名从业者的分享以及2024-2026年的最新资料
  2. 寻找现有的优质学习资源 — 优秀的博客文章、交互式教程、YouTube频道、开源工具、实践沙箱、可视化工具、社区论坛
  3. 梳理概念结构 — 哪些是基础概念？概念之间的依赖关系是什么？常见的误解有哪些？最优的学习顺序是什么？
  4. 挖掘“顿悟时刻” — 哪些类比、可视化内容或练习能让学员快速理解该主题？顶尖教师的独特教学方法是什么？
  5. 收集真实案例 — 案例研究、实战经历、能将抽象概念具体化的实际应用场景
  6. 寻找实操资源 — 学员在课程中可以实际使用的在线沙箱、工具等
将研究笔记保存到文件中，供学员后续参考：
bash
undefined

Write research to a markdown file alongside the course

将研究内容写入课程对应的markdown文件

Include: key sources, recommended deep-dives, practice resources, community links

包含：核心资料来源、推荐深度学习资源、实践资源、社区链接


**Source priorities** (in order):

1. Official documentation and specs
2. Peer-reviewed research / reputable educational content
3. Respected practitioners and educators (conference talks, well-known blogs)
4. Community-vetted resources (highly-rated tutorials, curated awesome-lists)
5. Interactive tools and sandboxes

**Connecting research to lessons:**
- Reference 1-2 sources inline in story-cards where relevant (e.g., "According to the Bash Reference Manual...")
- End every explainer with a `recommended-deep-dive` section linking 2-4 of your best research sources

**资料优先级（从高到低）：**

1. 官方文档和规范
2. 经同行评审的研究 / 知名教育内容
3. 知名从业者和教育者的分享（会议演讲、知名博客）
4. 社区认可的资源（高评分教程、精选的awesome列表）
5. 交互式工具和沙箱

**将研究内容与课程关联：**
- 在故事卡片中适当引用1-2个资料来源（例如：“根据Bash参考手册...”）
- 在每个讲解模块末尾添加 `recommended-deep-dive` 部分，链接2-4个你找到的最佳研究资源

3. Design the curriculum

3. 设计课程大纲

Based on research, plan the full course:
  • 8-12 sessions for a standard course (3-5 for quick intro, 12-20 for deep dive)
  • Define learning objectives per session — what will the student be able to DO after each one?
  • Map concept dependencies — what must come before what?
  • Plan review touchpoints — which earlier concepts get revisited where?
  • Identify sessions where real-world missions, external tools, or deeper exploration fit naturally
  • Max 6 new vocabulary terms per session, each with a bridging analogy
Save the curriculum and show it to the student as an interactive dashboard:
  1. Write a curriculum JSON file (array of session objects):
    json
    [
  {
    "session_number": 1,
    "title": "How Bash Actually Works",
    "description": "The mental model that changes everything",
    "objectives": ["Explain what a shell does", "Break down command syntax"],
    "concepts": ["shell-mental-model", "commands-and-arguments"],
    "estimated_minutes": 20
  }
]
  2. Save it to the course progress:
    bash
    uv run .agents/skills/interactive-learner/scripts/progress.py set-curriculum <course> <curriculum.json>
  3. Build and open the dashboard so the student can see the full plan:
    bash
    uv run .agents/skills/interactive-learner/scripts/build-dashboard.py --open
STOP here. Ask the student to review the curriculum in the dashboard. Let them react, reprioritize, or skip sessions they already know. Do not proceed to step 4 until the student confirms the plan.
See course-design-guide.md for topic-type → component mapping and session patterns.
基于研究结果，规划完整课程：
  • 标准课程设置8-12个学习阶段（快速入门为3-5个阶段，深度学习为12-20个阶段）
  • 定义每个学习阶段的学习目标 — 学员在完成每个阶段后能够完成哪些任务？
  • 梳理概念依赖关系 — 哪些内容必须前置学习？
  • 规划复习节点 — 哪些前期概念需要在后续阶段回顾？
  • 确定适合加入真实任务、外部工具或深度探索内容的学习阶段
  • 每个阶段最多引入6个新术语，每个术语都需搭配一个关联类比
将课程大纲保存为交互式仪表盘并展示给学员：
  1. 编写课程大纲JSON文件（由多个阶段对象组成的数组）：
    json
    [
  {
    "session_number": 1,
    "title": "How Bash Actually Works",
    "description": "The mental model that changes everything",
    "objectives": ["Explain what a shell does", "Break down command syntax"],
    "concepts": ["shell-mental-model", "commands-and-arguments"],
    "estimated_minutes": 20
  }
]
  2. 将其保存到学习进度文件中：
    bash
    uv run .agents/skills/interactive-learner/scripts/progress.py set-curriculum <course> <curriculum.json>
  3. 构建并打开仪表盘，让学员查看完整规划：
    bash
    uv run .agents/skills/interactive-learner/scripts/build-dashboard.py --open
在此处暂停。请学员在仪表盘中查看课程大纲。让他们提出反馈、调整优先级或跳过已掌握的阶段。在学员确认规划之前，请勿进入第4步。
主题类型与组件映射、阶段模式请参考 course-design-guide.md。

4. Build the explainer

4. 构建讲解内容

Build a lesson config using only content components (no scored exercises):
  • MANDATORY: Before generating JSON for ANY component, read its schema in component-catalog.md. Do NOT guess field names. Every component has different required fields — using wrong field names produces empty/broken output that silently fails.
  • MANDATORY: Search for videos before building the explainer:
    bash
    uv run .agents/skills/interactive-learner/scripts/find-videos.py "topic for beginners"
    Embed 1-2 if good results exist. If nothing suitable, note this and move on. The search is required; embedding is not.
  • See sharp-edges.md for anti-patterns to avoid
  • Design the explanation first, then pick the best component for each piece
  • Include at least one moment of surprise, delight, or creative challenge per session
  • Keep JSON concise but rich: ~60-100 lines
bash
uv run .agents/skills/interactive-learner/scripts/build-lesson.py <explainer.json> --mode explainer --course <course-id> --open
Tell the student what the explainer covers (1-2 sentences about concepts and ideas), invite questions, and let them know you're available to explain anything in more detail. Do NOT list component types in your message — describe what they'll learn, not what components you used.
仅使用内容组件构建课程配置（不含计分练习）：
  • 强制要求：在为任何组件生成JSON之前，请先阅读 component-catalog.md 中的对应 schema。切勿猜测字段名称。每个组件都有不同的必填字段 — 使用错误的字段名称会导致输出为空或损坏，且无报错提示。
  • 强制要求：在构建讲解内容前先搜索视频：
    bash
    uv run .agents/skills/interactive-learner/scripts/find-videos.py "topic for beginners"
    如果找到合适的视频，嵌入1-2个。若无合适结果，记录此情况并继续。搜索步骤是必须的，嵌入视频为可选操作。
  • 避免反模式请参考 sharp-edges.md
  • 先设计讲解内容，再为每个部分选择最佳组件
  • 每个学习阶段至少包含一个惊喜、趣味或创意挑战环节
  • 保持JSON简洁但内容丰富：约60-100行
bash
uv run .agents/skills/interactive-learner/scripts/build-lesson.py <explainer.json> --mode explainer --course <course-id> --open
告知学员讲解内容涵盖的范围（1-2句话介绍概念和知识点），邀请他们提问，并让他们知道你可以详细解释任何内容。请勿在消息中列出组件类型 — 描述他们将学到什么，而非你使用了哪些组件。

5. Conversational checkpoint

5. 对话式检查点

When the student comes back after reading:
  1. Ask "Was everything clear?" — discuss any confusion, clarify using your research sources. If the student has questions, answer them thoroughly and refer to the research notes.
  2. Ask 1 teach-back question in chat — "Let me quickly check if you're ready for the test: [question about a key concept from the explainer]"
  3. If the student struggles, explain further before proceeding. If they nail it, move to the test.
Open-ended assessment (explain-back, roleplay, open-reflection) happens here in conversation, not in HTML. The agent evaluates responses in real-time.
当学员看完讲解内容返回后：
  1. 询问“所有内容都清楚吗？” — 讨论任何疑问，使用你的研究资料进行澄清。如果学员有问题，务必详细解答并参考研究笔记。
  2. 在对话中提出1个回讲问题 — “让我快速检查你是否准备好进行测试：[关于讲解内容中核心概念的问题]”
  3. 如果学员表现不佳，在进入测试前进一步讲解。如果学员掌握良好，则进入测试环节。
开放式评估（回讲、角色扮演、开放式反思）在此对话环节进行，而非在HTML中。Agent会实时评估学员的回答。

6. Build the test

6. 构建测试内容

Build a test config using only scored components + 
score-summary
:
  • Include 
    quiz
    , 
    matching
    , 
    fill-blanks
    , 
    sorting-game
    , and/or 
    custom
    components
  • Always end with 
    score-summary
  • Keep JSON concise: ~40-80 lines
bash
uv run .agents/skills/interactive-learner/scripts/build-lesson.py <test.json> --mode test --course <course-id> --open
Tell the student to complete the test and click "Get my result code" when done.
仅使用计分组件 + 
score-summary
构建测试配置：
  • 包含 
    quiz
    、
    matching
    、
    fill-blanks
    、
    sorting-game
    和/或 
    custom
    组件
  • 始终以 
    score-summary
    结尾
  • 保持JSON简洁：约40-80行
bash
uv run .agents/skills/interactive-learner/scripts/build-lesson.py <test.json> --mode test --course <course-id> --open
告知学员完成测试后点击“获取我的结果代码”。

7. Debrief after the session

7. 学习阶段复盘

After the student completes the test:
  1. Student clicks "Get my result code" — a compact code appears on screen (e.g. 
    BASH-7A3E-9C51-...
    )
  2. Student copies the code and pastes it back in chat
  3. Agent decodes the result code:
    bash
    uv run .agents/skills/interactive-learner/scripts/progress.py decode <code>
  4. Update progress with decoded scores AND concept mastery:
    bash
    uv run .agents/skills/interactive-learner/scripts/progress.py update <course> --session N --score S --max M --concepts '{"pod-basics": 0.9, "deployments": 0.6}'
    Assign concept scores based on your knowledge of which test questions tested which concepts.
  5. Rebuild the dashboard:
    bash
    uv run .agents/skills/interactive-learner/scripts/build-dashboard.py --open
  6. Discuss what they found hard or interesting
  7. If they had a real-world mission: ask how it went, what they discovered
  8. Prepare notes for the next session — adjust based on everything you learned
学员完成测试后：
  1. 学员点击“获取我的结果代码” — 屏幕上会显示一个紧凑的代码（例如：
    BASH-7A3E-9C51-...
    ）
  2. 学员复制代码并粘贴回对话中
  3. Agent解码结果代码：
    bash
    uv run .agents/skills/interactive-learner/scripts/progress.py decode <code>
  4. 使用解码后的分数和知识点掌握情况更新学习进度：
    bash
    uv run .agents/skills/interactive-learner/scripts/progress.py update <course> --session N --score S --max M --concepts '{"pod-basics": 0.9, "deployments": 0.6}'
    根据你对测试题目对应知识点的了解，为知识点分配分数。
  5. 重新构建仪表盘：
    bash
    uv run .agents/skills/interactive-learner/scripts/build-dashboard.py --open
  6. 与学员讨论他们觉得困难或有趣的内容
  7. 如果安排了真实任务：询问任务完成情况和他们的发现
  8. 为下一个学习阶段准备笔记 — 根据所学内容进行调整

Returning student: Review → Adapt → Build next session

回归学员：复习 → 调整 → 构建下一个学习阶段

bash
uv run .agents/skills/interactive-learner/scripts/progress.py show
Check:
  • Concept mastery levels — which concepts need review? (below 0.7 = needs reinforcement)
  • Time since last session — longer gap = more review needed
  • Recent scores — adjust difficulty
  • Open questions or missions from last session — follow up on these
  • Achievements earned — acknowledge naturally
Generate the next session, weaving in review of weak concepts using varied component types (not just repeating the same quiz).
bash
uv run .agents/skills/interactive-learner/scripts/progress.py show
检查以下内容：
  • 知识点掌握程度 — 哪些知识点需要复习？（低于0.7分 = 需要强化）
  • 距上次学习的时间间隔 — 间隔越长，需要的复习内容越多
  • 近期测试分数 — 调整后续内容难度
  • 上一阶段未解决的问题或任务 — 跟进这些内容
  • 获得的成就 — 自然地提及这些成就
生成下一个学习阶段的内容，将需要复习的薄弱知识点融入其中，并使用不同类型的组件（切勿仅重复相同的测验）。

Generate review session (when needed)

生成复习阶段内容（必要时）

When concepts are fading or it's been a while:
bash
uv run .agents/skills/interactive-learner/scripts/progress.py review <course>
This outputs concepts due for review. Build a review session that mixes these concepts into fresh contexts and varied exercise types.
当知识点记忆衰退或间隔时间较长时：
bash
uv run .agents/skills/interactive-learner/scripts/progress.py review <course>
该命令会输出需要复习的知识点。构建一个复习阶段，将这些知识点融入新的场景和不同类型的练习中。

View student dashboard

查看学员仪表盘

bash
uv run .agents/skills/interactive-learner/scripts/build-dashboard.py --open
Options: 
--progress <path>
(custom progress file), 
--output <path>
(custom output path).
bash
uv run .agents/skills/interactive-learner/scripts/build-dashboard.py --open
可选参数：
--progress <path>
（自定义进度文件路径），
--output <path>
（自定义输出路径）。

Lesson JSON Structure

课程JSON结构

Each session produces two JSON files: an explainer (content-only) and a test (scored exercises). Open-answer questions (explain-back, roleplay, open-reflection) are asked by the agent in conversation between the two phases.
每个学习阶段会生成两个JSON文件：讲解内容（仅含学习内容）和测试内容（含计分练习）。开放式问题（回讲、角色扮演、开放式反思）由Agent在对话环节提出（第5步），不会渲染到HTML中。

Explainer JSON (
--mode explainer
)

讲解内容JSON（
--mode explainer
）

json
{
  "course_name": "Kubernetes",
  "title": "Why Does Kubernetes Exist?",
  "subtitle": "The problem before the solution",
  "session": 1,
  "estimated_minutes": 12,
  "xp_start": 0,
  "concepts": ["container-orchestration", "scaling-problem", "self-healing"],
  "sections": [
    {
      "type": "story-card",
      "variant": "blue",
      "label": "The Problem",
      "content": "<p>Imagine you're running 50 containers...</p>"
    },
    { "type": "vocab-cards", "terms": [{ "term": "Pod", "icon": "🫛", "definition": "...", "analogy": "..." }] },
    { "type": "video-embed", "youtube_id": "dQw4w9WgXcQ", "title": "Watch This", "intro": "Quick overview." },
    {
      "type": "side-by-side",
      "title": "Docker Alone vs With Kubernetes",
      "left": { "header": "Docker Alone", "icon": "🐳", "items": ["You manage everything", "Manual restarts"] },
      "right": { "header": "With Kubernetes", "icon": "☸️", "items": ["Automated management", "Self-healing"] }
    },
    {
      "type": "real-world-mission",
      "mission": "Open play-with-k8s.com and run: kubectl get nodes. How many nodes do you see?",
      "url": "https://labs.play-with-k8s.com/",
      "context": "This is a free Kubernetes playground — no install needed.",
      "followup": "We'll discuss what you found at the start of next session."
    }
  ]
}
json
{
  "course_name": "Kubernetes",
  "title": "Why Does Kubernetes Exist?",
  "subtitle": "The problem before the solution",
  "session": 1,
  "estimated_minutes": 12,
  "xp_start": 0,
  "concepts": ["container-orchestration", "scaling-problem", "self-healing"],
  "sections": [
    {
      "type": "story-card",
      "variant": "blue",
      "label": "The Problem",
      "content": "<p>Imagine you're running 50 containers...</p>"
    },
    { "type": "vocab-cards", "terms": [{ "term": "Pod", "icon": "🫛", "definition": "...", "analogy": "..." }] },
    { "type": "video-embed", "youtube_id": "dQw4w9WgXcQ", "title": "Watch This", "intro": "Quick overview." },
    {
      "type": "side-by-side",
      "title": "Docker Alone vs With Kubernetes",
      "left": { "header": "Docker Alone", "icon": "🐳", "items": ["You manage everything", "Manual restarts"] },
      "right": { "header": "With Kubernetes", "icon": "☸️", "items": ["Automated management", "Self-healing"] }
    },
    {
      "type": "real-world-mission",
      "mission": "Open play-with-k8s.com and run: kubectl get nodes. How many nodes do you see?",
      "url": "https://labs.play-with-k8s.com/",
      "context": "This is a free Kubernetes playground — no install needed.",
      "followup": "We'll discuss what you found at the start of next session."
    }
  ]
}

Test JSON (
--mode test
)

测试内容JSON（
--mode test
）

json
{
  "course_name": "Kubernetes",
  "title": "Session 1 Test",
  "subtitle": "Container orchestration basics",
  "session": 1,
  "xp_start": 0,
  "sections": [
    {
      "type": "quiz",
      "questions": [
        {
          "question": "What happens when a container crashes in plain Docker?",
          "options": ["It auto-restarts", "Nothing — it stays dead", "Docker alerts Kubernetes", "The host reboots"],
          "correct": 1,
          "feedback_correct": "Exactly — without orchestration, crashed containers stay down.",
          "feedback_wrong": "Not quite. Without an orchestrator, Docker won't auto-restart crashed containers."
        }
      ]
    },
    {
      "type": "matching",
      "title": "Match Terms",
      "pairs": [
        { "term": "Pod", "definition": "Smallest deployable unit in Kubernetes" },
        { "term": "Node", "definition": "A machine in the cluster" }
      ],
      "right_order": [1, 0]
    },
    {
      "type": "score-summary",
      "learned": ["Why container orchestration exists", "Pod and Node basics"],
      "next_preview": "Next: what Kubernetes actually does about these problems."
    }
  ]
}
json
{
  "course_name": "Kubernetes",
  "title": "Session 1 Test",
  "subtitle": "Container orchestration basics",
  "session": 1,
  "xp_start": 0,
  "sections": [
    {
      "type": "quiz",
      "questions": [
        {
          "question": "What happens when a container crashes in plain Docker?",
          "options": ["It auto-restarts", "Nothing — it stays dead", "Docker alerts Kubernetes", "The host reboots"],
          "correct": 1,
          "feedback_correct": "Exactly — without orchestration, crashed containers stay down.",
          "feedback_wrong": "Not quite. Without an orchestrator, Docker won't auto-restart crashed containers."
        }
      ]
    },
    {
      "type": "matching",
      "title": "Match Terms",
      "pairs": [
        { "term": "Pod", "definition": "Smallest deployable unit in Kubernetes" },
        { "term": "Node", "definition": "A machine in the cluster" }
      ],
      "right_order": [1, 0]
    },
    {
      "type": "score-summary",
      "learned": ["Why container orchestration exists", "Pod and Node basics"],
      "next_preview": "Next: what Kubernetes actually does about these problems."
    }
  ]
}

Available Components

可用组件

Explainer phase (content-only, 
--mode explainer
)

讲解阶段（仅含内容，
--mode explainer
）

story-card
vocab-cards
side-by-side
video-embed
timeline
concept-map
mind-map
kanban-board
radar-profile
recommended-deep-dive
(include at end of every explainer) 
debug-challenge
simulator
real-world-mission
community-challenge
custom
story-card
vocab-cards
side-by-side
video-embed
timeline
concept-map
mind-map
kanban-board
radar-profile
recommended-deep-dive
（每个讲解内容末尾必须包含） 
debug-challenge
simulator
real-world-mission
community-challenge
custom

Test phase (scored, 
--mode test
)

测试阶段（含计分，
--mode test
）

quiz
matching
fill-blanks
sorting-game
score-summary
custom
quiz
matching
fill-blanks
sorting-game
score-summary
custom

Conversational (asked by agent in chat, not in HTML)

对话式组件（由Agent在对话中提出，不在HTML中显示）

explain-back
roleplay
open-reflection
— these are handled in the conversational checkpoint (Step 5), not rendered into HTML.
explain-back
roleplay
open-reflection
— 这些组件在对话式检查点（第5步）中使用，不会渲染到HTML中。

Escape hatch

应急方案

custom
— allowed in both phases. When no template fits, invent something new.
Full JSON schemas and usage guidance: component-catalog.md
custom
— 两个阶段均允许使用。当没有合适的模板时，可以创建新的内容形式。
完整的JSON schema和使用指南请参考 component-catalog.md。

Finding Videos

查找视频

bash
uv run .agents/skills/interactive-learner/scripts/find-videos.py "topic for beginners"
The video search script scrapes YouTube HTML and may break when YouTube changes their page structure. If it fails, ask the user to search YouTube manually and paste the URL.
Max 2 embedded videos per lesson. But you CAN recommend additional videos/resources via 
recommended-deep-dive
components — these are optional extras, not required viewing.
bash
uv run .agents/skills/interactive-learner/scripts/find-videos.py "topic for beginners"
视频搜索脚本会抓取YouTube的HTML内容，当YouTube页面结构变化时可能失效。如果脚本运行失败，请让用户手动搜索YouTube并粘贴视频链接。
每个课程最多嵌入2个视频。但你可以通过 
recommended-deep-dive
组件推荐更多视频/资源 — 这些是可选的补充内容，非必须学习的内容。

Core Rules

核心规则

  1. Research first. Never teach from assumptions. Find authoritative, recent sources.
  2. Bridge from known knowledge. Read the student profile. Connect every new concept to something they already understand.
  3. Explain, then discuss, then test. The explainer HTML teaches. The conversation checks understanding and fills gaps. The test HTML assesses. This flow is structurally enforced by 
    --mode explainer
    and 
    --mode test
    .
  4. Mostly click-based tests. Test exercises should be click/drag/select. Open-ended assessment happens in conversation (Step 5), not in HTML.
  5. Conversational teach-back is powerful. Use the checkpoint between explainer and test to ask 1 teach-back question, discuss confusion, and verify readiness. This replaces the old in-HTML open-answer textareas.
  6. Max 6 new terms per session. Each needs an analogy bridging to what the student knows.
  7. 50% practice, 30% content, 20% assessment — but treat this as a guideline, not a straitjacket. Some sessions are exploration-heavy, some are drill-heavy.
  8. Design content first, then choose components. Outline what you want to teach and how you'd explain it conversationally. Then map each piece to the best component. If three story-cards in a row is the clearest way to teach something, that's fine. Vary components when it serves comprehension, not for variety's sake.
  9. Always end tests with score-summary.
  10. Be adventurous. Send students to real websites, sandboxes, and tools. Recommend books, talks, and articles. Ask them to draw something and share it. Suggest they explain a concept to a friend. The lesson HTML is the core, but learning extends beyond it.
  11. Achievements are dynamic. Don't use a fixed list. Generate achievements that match the specific course, topic, and student milestones. See gamification.md.
  12. Every interaction earns data. Track concept mastery, not just session scores. Feed this into future sessions.
  1. 先研究，后教学。切勿凭假设教学。务必找到权威、最新的资料。
  2. 从已知知识引入。查看学员画像。将每个新概念与学员已掌握的知识关联起来。
  3. 讲解 → 讨论 → 测试。HTML讲解内容负责传授知识。对话环节负责检查理解并填补知识空白。HTML测试内容负责评估学习效果。
    --mode explainer
    和 
    --mode test
    会从结构上强制遵循此流程。
  4. 测试以点击式为主。测试练习应采用点击/拖拽/选择的形式。开放式评估在对话环节（第5步）进行，而非在HTML中。
  5. 对话式回讲效果显著。在讲解内容和测试之间的检查点提出1个回讲问题，讨论疑问并验证学员是否准备就绪。这取代了旧版HTML中的开放式文本输入框。
  6. 每个阶段最多6个新术语。每个术语都需搭配一个与学员已知知识相关的类比。
  7. 50%练习，30%内容，20%评估 — 但这只是一个指导原则，而非硬性规定。有些阶段以探索为主，有些阶段以练习为主。
  8. 先设计内容，再选择组件。先勾勒出你想要教授的内容以及对话式讲解的方式。然后将每个部分映射到最佳组件。如果连续使用三个故事卡片是最清晰的教学方式，那也完全可行。仅当有助于理解时才更换组件，切勿为了多样性而多样性。
  9. 测试内容始终以score-summary结尾。
  10. 勇于创新。引导学员访问真实网站、沙箱和工具。推荐书籍、演讲和文章。让他们绘制内容并分享。建议他们向朋友讲解某个概念。HTML课程是核心，但学习不应局限于此。
  11. 成就动态生成。不要使用固定的成就列表。生成与特定课程、主题和学员里程碑匹配的成就。请参考 gamification.md。
  12. 每次交互都要收集数据。跟踪知识点掌握程度，而非仅记录阶段分数。将这些数据应用于后续的学习阶段。

Anti-patterns

反模式

See sharp-edges.md — updated with guidance on when open answers help vs hurt, and new anti-patterns around research shortcuts and stale content.
反模式内容请参考 sharp-edges.md — 包含开放式问题的适用场景、研究捷径和过时内容等反模式的最新指导。

Gamification

游戏化设计

See gamification.md — dynamic achievements, XP, streaks, and the memory garden concept.
游戏化设计请参考 gamification.md — 动态成就、经验值、连续学习天数和记忆花园概念。