edulab: 把数学题变成交互式 3D 课堂

一个学生盯着立体几何题发呆。“求直线 PQ 与平面 ABC 的夹角。” 课本上只有一张静态图。线叠在一起，角看不清楚。你没法旋转它，没法放大看交点，甚至无法直觉判断那个 120° 的答案在空间里到底对不对。

这就是大多数人学立体几何的方式：从二维图片理解三维空间。

eulab 改变了这一点。给它一道题，它还你一个 HTML 页面——左侧 MathJax 公式分步推导，右侧 Three.js 3D 模型可旋转缩放。转动几何体，放大关键截面，看着镜头自动跟随每一步推理。它把”读懂了”变成了”看明白了”。

你得到什么

eulab 生成的是一个自包含的教学页面。不需要服务器，不需要登录，不依赖任何外部资源。浏览器打开即用。

• 左侧面板：题面、答案、分步解析。公式用 MathJax 渲染，是真正排版后的数学公式，不是截图。
• 右侧面板：题面对应的 3D 模型。每一步推理对应高亮关键元素，镜头自动切换到最佳观察视角。
• 同源一致：答案、3D 坐标、每步的中间值，全部来自同一次 sympy 计算。不会出现”答案写 60°，模型里坐标对应 45°“这种对不上的情况。

覆盖题型：正方体和长方体、棱锥和棱柱、圆柱和圆锥上的线面角、二面角、异面直线夹角、点到平面距离、体积。统一用建系 + 向量法求解。

三种方式出题

eulab 支持三种输入方式：

• 文字题目：直接输入或粘贴题目描述，技能自动抽取题面求解。
• 上传图片：拍一张题目照片，视觉识别题目内容，回显确认后求解。
• 随机出题：指定几何体类型和一个随机种子，自动生成参数。答案不够规整会重抽。

如何使用：输入与输出

一次完整的交互长这样。三种入口最终都汇入同一条管线。

输入——任选其一：

• 打字出题：“正四棱锥 P-ABCD，底面边长 2，高 1，E 为 PC 中点，求直线 BE 与平面 PAC 的夹角。”
• 上传题目图片。agent 用视觉识别题面，回显确认后再继续。
• 随机出题：“随机出一道立方体的二面角问题。” agent 随机生成参数，答案不规整就重抽。

不管哪种方式，输入最终都被归一化为一份结构化的 problem spec：几何体类型、尺寸、已知条件、求解目标、输出语言（跟随你的提示词语言）。

Agent 工作流——skill 执行的五个步骤：

1. 归一化：把输入转成机器可读的 JSON（几何体类型、坐标、题型）
2. 计算：Python kernel 用 sympy 做精确坐标运算。从不心算。输出坐标、向量、法向量、最终答案，全部为 LaTeX 字符串。
3. 组装：把所有数据注入 template/lesson.html——题目文字、分步内容、3D 模型坐标、镜头位置、高亮映射
4. 自检：kernel 答案必须等于答案卡等于最终步骤展示值。本地预览确认无控制台报错、公式全部正常渲染。
5. 交付：在你当前工作目录写入一个 HTML 文件，命名 solution-<题目简述>.html

输出——一个自包含的 HTML 文件。任意浏览器打开即用。没有服务器，不用登录。左侧：题目、答案、MathJax 分步解析。右侧：交互式 Three.js 3D 模型，步骤同步高亮和镜头切换。

整个交互就是一次对话。你描述题目，agent 算完写 HTML，你新标签页打开看。

在展开 edulab 之前，先绕个路。

Claude Code 引入了一套叫 agent skills 的插件机制。一个 skill 是一套指令、脚本和模板的打包，教 AI agent 做它原本不会的事——生成视频、渲染图表、或者在这里，求解立体几何并产出交互式教学页面。

可以把 skills 理解为教 agent 一套工作流。agent 不是背答案，而是学方法。视频 skill 教它怎么搭建和渲染 HTML 转视频的项目管线；图表 skill 教它 SVG 构图规则；eulab 教它建系、sympy 计算和模板注入。

这件事之所以重要，是因为它改变了 AI 助手的能力边界。没有 skill，Claude 可以推理几何问题，但不能生成 3D 模型。装上 edulab，它能解、能算、能渲染——一次对话全部完成。

怎么做到的

eulab 的管线分四步：

1. 归一化题目：无论你是打字、传图还是随机出题，都会被转成结构化的题目描述——几何体类型、尺寸、已知条件、求解目标。
2. 精确计算：Python 核心用 sympy 算出坐标、向量、法向量和答案。没有浮点误差。每个值都是精确的分数或根式。
3. 组装模板：计算输出注入到数据驱动的 HTML 模板中。3D 顶点坐标和解题步骤来自同一份数据源。
4. 自检：kernel 答案要等于答案卡等于最后步骤的展示值。本地预览确认公式渲染正常、控制台无报错。

你也可以不经过 Claude，直接命令行生成：

python3 lib/geometry_kernel.py                     # 内置样例自检
python3 scripts/generate.py cube   ./cube.html     # 正方体·线面角
python3 scripts/generate.py random 7 ./random.html # 随机出题（seed=7）

HTML 页面的技术细节

产出的 HTML 页面是一个单文件。所有依赖——Three.js、MathJax、CSS——全部走 CDN 加载。没有后端，没有构建步骤，没有 npm。

以下是交互效果的实现方式：

数据驱动渲染。 每个教学页面都来自同一份模板 template/lesson.html。Python 脚本把题目、解题步骤、3D 模型坐标、每步的镜头位置等数据，注入到一个 JSON script 标签中。页面读取这个数据岛，全客户端渲染。没有硬编码内容。

3D 场景。 Three.js WebGLRenderer 绘制几何体：顶点（小球体）、棱（圆柱管状 Mesh）、面（半透明 Mesh）、箭头，长度标签用 CSS2DRenderer 叠加。OrbitControls 负责左键旋转、滚轮缩放、右键平移。

步骤导航 + 镜头动画。 JSON 数据中每个解题步骤都指定了 cameraPos（镜头位置）和 highlight（需要高亮的元素列表）。切换步骤时，页面先隐藏所有高亮元素，再按当前步骤显示需要的，同时用 camera.position.lerp() 平滑过渡镜头。右侧 3D 场景切换的同时，左侧文字内容做一个 280ms 的淡入上移动画。

动点拖拽探索。 目前的样例（正四棱锥）允许拖动动点 P 沿 SA 线段滑移。用 Raycaster 把鼠标位置投射到约束线段上求参数 t，setParam(t) 实时更新数学坐标 → 重建所有引用了该点的 3D 元素（线、面、箭头），同时底部面板实时显示变化后的角度/距离值。学生可以测试”把 P 拖到不同位置，角度会怎么变”，而不是只看一个固定答案。

溢出公式处理。 MathJax 渲染的块级公式如果超出侧栏宽度，会强制显示横向滚动条。也可以直接鼠标按住拖拽滑动长公式，不用碰滚动条。

无障碍。 页面包含跳过链接、步骤容器有 aria-label/aria-live，尊重 prefers-reduced-motion 关闭所有动画。

安装

一行命令：

npx skills add wy51ai/edulab

或通过 Claude Code 插件市场：

/plugin marketplace add wy51ai/edulab
/plugin install edulab

计算核心依赖 sympy，如果缺失：

python3 -m pip install sympy

触发方式：描述一道几何题——“求这个正四棱锥的二面角”——或者上传一张题目图片。

局限

eulab 目前只覆盖立体几何。平面几何、代数、微积分、物理都不在范畴内。可解的题型限于能用建系 + 向量法求解的部分——需要纯综合法推理的题目，edulab 目前做不了。

产出是静态 HTML 文件。它不是带用户系统和进度跟踪的 web app。它的设计意图就是生成、打开、探索。

好消息是 edulab 很容易扩展。加题型就是在 geometry_kernel.py 里写一个求解函数。加几何体就是定义它的坐标和棱拓扑。架构很干净——Python 管计算，HTML 管呈现。

Skills 是一种学习范式

大多数人讨论 agent skills 时，谈的是开发者效率：生成代码、搭建项目、写测试。eulab 展示了另一个方向。

Skills 可以产出五分钟前还不存在的学习材料。学生问棱锥上的二面角怎么求，agent 生成一节定制课程——带那个具体棱锥的 3D 模型，高亮那个具体角度。而不是一个通用的 Khan Academy 视频，也不是数字不一样的课本插图。就是他卡住的那个东西，可视化。

这比几何更广。同样的模式——题目归一化、精确计算、模板注入产出交互输出——适用于物理、化学、统计，任何理解受益于可视化的领域。

我们习惯了 AI 回答问题。edulab 指向的是 AI 搭建学习环境。

试试看

eulab 是 Apache 2.0 开源项目，235 star，51 fork，作者 WY。装上它，甩一道几何题给它，打开那个 HTML。

edulab on GitHub