Flow Learning System

Flow Learning System

English · 한국어 · 日本語 · 简体中文

基于动态图形和 TTS 构建的学习系统。 适用于任何学科：数学、科学、英语、生物、编程等。 将课程写成 JSON 数据，每个句子都会成为一个场景。最终生成一个单文件 HTML 教材，其中的图表、方程、句子成分、3D 插图和代码会在语音开始朗读对应句子的瞬间动起来。 AI 会使用 MCP 工具编写教材、检查教材、运行示例代码以验证输出、使用 Blender 渲染 3D 插图、录制旁白并构建教材。 内置的 TTS（Supertonic）目前支持韩语和英语配音，示例课程使用韩语编写。

数学 · 平移二次函数 曲线滑动到新的位置，方程中发生变化的部分会高亮显示	科学 · 斜面上的物块 在 Blender 渲染图上，重力分解为两个从物块延伸出来的分力
英语 · 构成被动语态 单词移动到新的位置，英语语音会朗读例句	生物 · 动物细胞的结构 放大查看细胞的 3D 横截面，并逐一指出细胞器

编程 · 17 节 C# 语法课程中的第 7 课（数组）——当前行高亮、数组单元格逐个填充、执行跟踪表、可折叠目录和脚本面板

---

核心理念：一个句子 = 一个场景

• 课程中的每个 say 都是一个场景。场景会整合该时刻的脚本句子、醒目的关键词和视觉内容（图表、方程、句子成分、图像、代码、变量……）。
• 旁白按句合成并拼接，同时会在 timing.json 中记录每个句子的开始时间。
• 播放器每帧都会读取音频的当前播放位置，并据此选择场景。调整播放速度或跳到中间位置，都不会让画面和语音失去同步。

示例课程

学科	课程	场景数	使用的视觉元素	看点
数学	examples/math-quadratic	13	plot、math、tbl	同名曲线会在不同场景之间变形，因此能直观看到平移
科学	examples/physics-incline	12	img（3D 渲染）、math、bars、plot	箭头朝着在 3D 中计算出的力的端点延伸；可缩放
英语	examples/english-passive	12	tokens、例句面板、tbl、flow	单词块移动到新的位置；`{en
生物	examples/biology-cell	13	img（3D 渲染）、flow、cards	视图放大细胞横截面时，细胞器标签也会移动
编程	examples/csharp-grammar	321（17 节课）	代码、变量、数组、栈/队列/字典、控制台	所有 48 个示例都会实际运行，并与屏幕上的输出进行比对

使用 Blender 添加 3D 插图

render_3d 工具会在无界面模式下运行由 AI 编写的 Blender 场景脚本，并使用 Cycles 渲染。 当脚本通过 spot("name", (x, y, z)) 标记一个 3D 位置时，工具会计算该点在透视投影图像中的落点，并将其与渲染图一同保存。 之后，课程会使用这些名称来设置标签、缩放中心和箭头。

# Block on an incline — compute the endpoints of gravity and its two components as 3D vectors
th = math.radians(30)
d = V3((math.cos(th), 0, -math.sin(th)))   # down-slope direction
n = V3((math.sin(th), 0, math.cos(th)))    # normal to the incline
spot("block", C)
spot("g_tip", C + V3((0, 0, -2.6)))                 # gravity mg
spot("par_tip", C + d * 2.6 * math.sin(th))         # mg sinθ
spot("perp_tip", C - n * 2.6 * math.cos(th))        # mg cosθ

{"img": ["assets/incline.png", {
  "spots": {"theta": {"label": "θ = 30°"}},
  "arrows": [{"from": "block", "to": "g_tip", "label": "mg", "c": "bad"},
             {"from": "block", "to": "par_tip", "label": "mg sinθ", "c": "g1"}],
  "zoom": 1.35, "focus": "block"}]}

由于箭头尖端是根据 3D 点计算得出的，因此它们与渲染出的斜面完全对齐。场景脚本保存在 assets/src/ 中，可以随时重新渲染。

屏幕布局

区域	内容
左侧：目录	课程和章节。可折叠；点击章节即可跳转到对应场景
中间：舞台	关键短语 + 左侧面板（代码或示例句子，并突出显示当前行）+ 视觉内容。始终使用深色，不受主题影响
右侧：脚本	约占屏幕的 1/5。突出显示正在朗读的句子；点击句子即可从该处播放。可折叠
底部：时间轴	按场景划分的进度条

顶栏仅包含课程导航、播放、场景导航和播放速度（0.75×–2×）。在手机上，目录面板和脚本面板会变成可覆盖在舞台上的抽屉。

动效规则

场景切换时，屏幕上的元素会按名称（键）匹配并进行动画处理。无需单独指定动画：只要更改数据即可产生动效。

动效	触发条件	示例
滑动	同名元素的位置发生变化	数组排序、指针 i、被动语态中的词语移动
变形	同名曲线、点或线的坐标发生变化	平移抛物线、改变其宽度
飞入	为源单元格指定了 from	answer[(i + k) % n] = arr[i]
生长	出现新箭头	将力分解为分量
缩放 / 平移	图像的 zoom 或 focus 发生变化	指出细胞器
闪烁 · 散开	仅数值发生变化 · 元素消失	变量值、弹出

课程剖析

{
  "id": 1, "group": "수학", "title": "이차함수의 평행이동",
  "ops": [
    {"op": "part", "title": "x축 방향으로 평행이동"},
    {"op": "say", "head": "{m|y = (x - 2)^2} : 오른쪽으로 2",
     "text": "x 자리에 x 빼기 2를 넣으면 그래프 전체가 오른쪽으로 2만큼 미끄러집니다.",
     "board": {"seq": [
       {"plot": [{"curves": [{"fn": "(x-2)**2", "c": "g1", "key": "p"}],
                  "points": [{"x": 2, "y": 0, "label": "꼭짓점 (2, 0)", "key": "v"}]}]},
       {"math": [["y = x^2", "y = (x - 2)^2"], {"hl": [1]}]}]}}
  ]
}

示例课程使用韩语旁白；{en|…} 片段会切换为英语语音。

​say 之前的操作会逐步构建屏幕状态，而 say 会将该时刻连同对应句子一起捕捉为一个场景。 22 种操作、24 种组件以及句子标记（{m|equation}、{en|English}、[[written form|spoken form]]）均记录在**编写指南**（韩语）中。MCP authoring_guide 工具会返回相同内容。

工作流

sequenceDiagram
    participant U as User
    participant AI as AI (Claude, etc.)
    participant M as Flow Learning System MCP
    participant F as Course folder
    U->>AI: "Make a lesson on cell organelles"
    AI->>M: authoring_guide
    AI->>M: course_init
    AI->>M: render_3d(cell scene script)
    M->>F: assets/cell.png + hotspot coordinates
    AI->>M: lesson_save(lesson JSON)
    M-->>AI: Validation results (missing hotspots, hard-to-read words …)
    AI->>M: speech_preview → pronunciation_add
    AI->>M: code_verify (subjects with code)
    AI->>M: audio_synthesize
    M->>F: audio/l01.mp3 + timing.json
    AI->>M: course_build
    M->>F: dist/index.html
    U->>F: Open with fls serve

检查项如下：

• 验证：未知操作或组件、图像中不存在的热点、尝试突出显示代码中不存在的行的场景、TTS 无法朗读的英语单词
• 代码验证：实际编译并运行每个示例，并将其与屏幕控制台输出逐字符比较（C#：Mono 或 .NET SDK；Python）
• 朗读预览：17개 → 열일곱 개（韩语本土数词读法），19.6 → 십구 점 육（汉字词读法的“十九点六”），8분의 1 → 팔분의 일（“八分之一”），{en|…} → 英语语音

安装

git clone https://github.com/ghlee0786/flow-learning-system.git
cd flow-learning-system
pip install -e ".[tts]"

要求	用途	缺少时的情况
Python 3.10+	所有功能	—
Supertonic ([tts])	合成韩语和英语语音。首次运行时会从 Hugging Face 下载模型	教材仍可运行，但不包含音频，使用估算的时间
ffmpeg	保存为 mp3	保存为 wav
Blender 3.6+	render_3d	仅无法使用 3D 插图。如果它不在 PATH 中，请将 FLS_BLENDER 设置为可执行文件路径
Mono 或 .NET SDK	验证 C# 示例	仅跳过 C# 验证

注册 MCP 服务

无需让 MCP 服务一直运行。只需向客户端注册一次，AI 每次使用工具时都会自行启动它（stdio）。

Claude Code

claude mcp add flow-learning-system -- python -m flow_learning_system.server

Claude Desktop（claude_desktop_config.json）

{
  "mcpServers": {
    "flow-learning-system": {
      "command": "python",
      "args": ["-m", "flow_learning_system.server"],
      "env": { "FLS_BLENDER": "C:\\Program Files\\Blender Foundation\\Blender 4.2\\blender.exe" }
    }
  }
}

在 Windows 上，如果 python 指向其他环境，请使用安装了该软件包的虚拟环境中 python.exe 的完整路径。

工具（13 个）

工具	功能
authoring_guide	课程格式、组件、动态规则和句子编写方法
course_init / course_status	创建新课程 / 查看每课的场景数、问题数和音频状态
lesson_get / lesson_save	读取课程 / 验证并保存课程（有错误时不会保存）
lesson_validate	验证
render_3d	Blender 场景脚本 → 图像 + 热点坐标
assets_list	课程的图像及其热点名称和坐标
speech_preview	TTS 将为每个场景朗读的确切句子
pronunciation_add	为英语单词登记韩文读音
code_verify	检查示例代码的输出是否与屏幕上的控制台输出一致
audio_synthesize	课程音频和时间表（仅处理有更改的课程）
course_build	dist/index.html + 音频 + 图像

命令行

fls validate examples/biology-cell              # validation
fls render   examples/biology-cell --name cell --script scene.py   # Blender render
fls speech   examples/english-passive --lesson 1   # TTS reading preview
fls verify   examples/csharp-grammar            # run and verify example code
fls audio    examples/math-quadratic            # speech synthesis
fls build    examples/math-quadratic            # dist/index.html
fls serve    examples/math-quadratic            # open locally (also from phones on the same Wi-Fi)
fls all      examples/physics-incline           # validate → verify → audio → build

构建后的教材仅由 index.html、audio/ 和 assets/ 文件夹组成，因此无需服务器即可运行。可以直接上传到 GitHub Pages 等静态托管服务。 仓库中不包含音频文件。请使用 fls audio <course> 生成音频。

文件夹结构

src/flow_learning_system/
  server.py      MCP server (13 tools)
  cli.py         fls command
  lesson.py      Lesson ops interpretation · validation (same rules as the player)
  speech.py      Script → TTS sentences (code-term readings, Korean number reading, English segments)
  tts.py         Supertonic synthesis · per-sentence timing · cache
  render.py      Blender rendering · hotspot projection
  verify.py      Example code execution (C#: Mono/.NET, Python)
  build.py       Single-file HTML build
  guide.md       Lesson authoring guide
  player/        Player (core.js equations/graphics, lesson.js scene builder/widgets, interp.js JSON interpretation, app.js playback/sync/motion)
examples/                  Math · science · English · biology · C# example courses (3D scene scripts in assets/src/)
docs/                      Authoring guide, README figures
tools/                     README figure generators, legacy JS lesson converter
tests/                     pytest

许可证

MIT。用于语音合成的 Supertonic Python 软件包采用 MIT 许可证，其模型采用 OpenRAIL 许可证；两者均未包含在此仓库中（模型会在首次运行时下载）。