edulab git:20260925.32ce6c0A

Immutable. This exact content never changes and is served at /api/v1/blob/0103ca4982530fae.

---
name: edulab
description: "面向中高考数学的可视化解题工具：空间几何题生成可交互 3D 解题演示（建系向量法 + sympy 校验 + Three.js），函数表达式生成参数可控的 2D 图形（滑块实时联动）。产物为单文件自包含交互式 HTML。适用：用户给出立体几何题要 3D 演示解题步骤、要函数图像并能拖滑块看参数变化、要数学可视化教学素材。触发词：/edulab、立体几何、空间几何题、线面角、二面角、点到平面距离、异面直线距离、外接球、内切球、三视图、函数图像、函数可视化、二次函数、数学可视化。用法：/edulab <题目或函数>。"
---

# edulab

## Purpose

中高考数学可视化：把中文立体几何题或函数表达式，变成单文件、可离线打开、可交互的 HTML 演示。几何走"读题 -> spec JSON -> 建系向量法求解（sympy 校验）-> Three.js 场景"；函数走"函数族 + 参数 -> Canvas2D 绘图 + 参数滑块实时联动"。

## When to Use

- 用户给出立体几何题（中高考风格），需要 3D 演示解题过程。
- 用户想要函数图像，并希望调参看变化（滑块联动）。
- 用户需要离线可开的数学可视化教学素材。
- 触发词：`/edulab <题目或函数>`、立体几何、空间几何题、线面角、二面角、外接球、内切球、三视图、函数图像、数学可视化。

## When NOT to Use

- 用户要的是概念讲解而非数学演示 -> 交给 `teach-eli5`（可视化教学页）。
- 用户要设计课程或教案 -> 交给 `curriculum-design`。
- 用户要信息卡片、封面等设计产物 -> 交给 `infocard` / `mckinsey-cover`。
- 题目超出 13 种 query.type 覆盖范围 -> 先说明不支持，不要硬套近似题型交付。

## Workflow

> **路径约定**：下文 `<skill>` 指本技能安装目录（如 `~/.claude/skills/edulab`）。运行脚本前先 `cd` 到该目录，或替换为实际路径。Python 需装 sympy（建议 `python3 -m venv .venv && .venv/bin/pip install sympy`）。

### 几何模块

1. 读题，确定立体类型与参数，写入 spec JSON（契约见 `references/schema.md`；题型清单见 `references/taxonomy.md`）。
2. 求解：
   ```
   cd <skill>/scripts/geometry
   python3 geometry_solver.py <spec.json> <scene.json>
   ```
   检查 steps 与 result 是否与标准答案一致；不一致则修 spec 重跑，不得静默交付错误答案。
3. 生成 HTML（`--offline` 内联 Three.js，无网环境可打开）：
   ```
   python3 build_html.py <scene.json> <out.html> [--offline]
   ```
4. 用 `present_files` 打开 out.html。

### 函数模块

1. 确定函数族（quadratic / linear / inverse / trig / exp / log / power，或 custom 自由表达式、multi 多曲线对比）。
2. 生成 scene：
   ```
   cd <skill>/scripts/function
   python3 function_engine.py <family> <params.json> <scene.json>
   ```
3. `python3 build_html.py <scene.json> <out.html>`，然后用 `present_files` 打开。

完整命令配方见 `examples/quickstart.md`。

## Decision Rules

- 输入是立体几何题 -> 几何模块；输入是函数/表达式/参数 -> 函数模块；两者混合 -> 拆成两个产物分别生成。
- `query.type` 支持 13 种：line_plane_angle / line_line_angle / dihedral_angle / point_plane_distance / volume_tetra / parallel_perp / skew_distance / circumsphere / insphere / three_views / surface_shortest_path / net / surface_volume。
- 立体支持 8 种：cube / cuboid / tetra / prism3 / pyramid4 / cylinder / cone / sphere。
- 自定义表达式（custom）-> params 传 `{"expr": "sin(x)/x"}`，只走 `safe_expr.py`，非法输入直接拒绝。
- 多曲线对比（multi）-> params 传 `{"items": [{"expr":..., "label":...}]}`。
- 需要 JSON 契约字段 -> 读 `references/schema.md`。
- 需要确认某题型/函数族/立体是否支持 -> 读 `references/taxonomy.md`。
- 需要架构决策、阶段规划或已知边界 -> 读 `references/design.md`。
- 无网环境 -> 必须加 `--offline`，否则 CDN 版打不开。

## Constraints

- **几何答案必须经 sympy 计算并独立核验，不符不交付**；禁止用手算或近似值糊弄。
- **前端零求值**：自由表达式只允许走 `safe_expr.py`（禁 `eval`/`Function`）。
- **scene JSON 是唯一中间契约**：模板只消费 scene，不得在模板里写求解逻辑。
- 文件写入禁 Box Drawing 等 Unicode 装饰字符（防乱码）；中文标签走 DOM/Canvas 文本。
- 离线打包依赖 `assets/vendor/three.min.js`、`assets/vendor/OrbitControls.js`、`assets/vendor/CSS2DRenderer.js`（`--offline` 时内联）。
- 产出 HTML 写到用户指定路径或工作目录，不要写回技能目录。

## Priority

1. 答案正确性 > 交付速度：sympy 校验不一致时先修 spec，绝不静默交付。
2. 安全 > 便利：自由表达式只走 `safe_expr.py`，任何绕过解析器的写法都禁止。
3. 离线可开 > 产物体积：无网环境优先 `--offline`，接受约 +630KB 内联开销。

## Stop Conditions

- 同一 spec 最多修正并重跑 3 次；仍与标准答案不一致则报告差异、列出已尝试的 spec，不交付错误答案。
- 题型不在 13 种之内且无法拆解为多步查询 -> 停止并说明限制，不近似硬套。
- 用户只要求"先看效果" -> 跑通一个样例即可，不继续扩展全部题型。

## Verification

交付前逐项确认：

- [ ] steps 与 result 已与标准答案核对一致（几何）。
- [ ] scene JSON 结构符合 `references/schema.md`。
- [ ] HTML 为单文件自包含，浏览器直接打开可交互。
- [ ] 无网环境已用 `--offline` 验证可打开。
- [ ] 自由表达式经 `safe_expr.py` 解析，注入样例被拒绝。
- [ ] 产物与模板文件内无 U+FFFD、无 Box Drawing 字符。
- [ ] 已用 `present_files` 向用户展示产物。

## Output

- **Outcome**：一个单文件交互式 HTML —— 几何为可旋转的 3D 解题演示（含步骤与精确结果），函数为带参数滑块、实时联动的 2D 图形。
- **Done when**：HTML 已生成并展示，且通过 Verification 清单（几何另需 sympy 校验一致）。
- **Evidence**：`scene.json`（中间契约）+ `out.html`；几何产物含 steps 数组与精确值/数值双结果；函数产物含参数滑块与联动性质（顶点/零点/渐近线等）。

## References

按需加载，不要预先全读：

- `references/schema.md` — 写 spec 或读取 scene、需要字段契约时读。
- `references/taxonomy.md` — 需要确认题型 / 函数族 / 立体的支持状态时读。
- `references/design.md` — 需要架构决策、渲染要点、阶段规划、验证记录或已知边界时读。

## Examples

按需加载：

- `examples/quickstart.md` — 第一次跑通或需要完整命令配方与样例清单时读。
- 几何样例 spec：`examples/geom_line_plane_angle.json`、`examples/geom_line_line_angle.json`、`examples/geom_dihedral_angle.json`、`examples/geom_point_plane_distance.json`、`examples/geom_skew_distance.json`、`examples/geom_volume_tetra.json`、`examples/geom_parallel_perp.json`、`examples/geom_circumsphere.json`、`examples/geom_insphere.json`、`examples/geom_three_views.json`、`examples/geom_net.json`、`examples/geom_surface_path.json`、`examples/geom_surface_volume.json`、`examples/geom_pyramid_apex_angle.json` — 需要构造同类题目时读，改造其 solid/params/query 即可。
- 函数样例 spec：`examples/func_quadratic.json`、`examples/func_custom.json`、`examples/func_multi.json` — 需要函数产物的参数写法时读。

## Scripts

按调用链使用，不要跳步：

- `scripts/geometry/geometry_solver.py` — `python3 geometry_solver.py <spec.json> <scene.json>`；返回 scene JSON（points/edges/steps/result 等）。
- `scripts/geometry/build_html.py` — `python3 build_html.py <scene.json> <out.html> [--offline]`；返回单文件 HTML 路径。
- `scripts/geometry/solids.py` — 立体积木库（8 种立体的参数化标准顶点 labeling 与 edges）；新增立体在此加 vertices/edges。
- `scripts/geometry/template_3d.html` — Three.js r128 + CSS2DRenderer 中文标签模板，含数据注入占位。
- `scripts/function/function_engine.py` — `python3 function_engine.py <family> <params.json> <scene.json>`；返回函数 scene JSON，支持 custom 与 multi。
- `scripts/function/build_html.py` — `python3 build_html.py <scene.json> <out.html>`；返回单文件 HTML（前端零求值）。
- `scripts/function/function_families.py` — 7 个函数族的参数定义（默认/范围/步长）；新增函数族在此加项。
- `scripts/function/safe_expr.py` — 递归下降 AST 安全表达式解析器；`SafeExpr(expr).eval({"x": v})`。
- `scripts/function/template_2d.html` — Canvas2D + 参数滑块模板，含 `f()` / `computeProps()` 分支。

## Related Skills

- `teach-eli5` — 把概念讲给外行听的教学页；本技能产出可交互演示，它产出图文讲解。
- `curriculum-design` — 课程与教案设计，本技能可作为课堂互动素材。
- `grasp` — 十维认知框架与学习路线图，用于学习者的系统自学。