auto-geogebra
Use when 需要把高校数学教学创意转化为可运行的 GeoGebra 动态演示/课件/动画:设计交互变量与滑块、生成并验证 GeoGebra 指令、导出 .ggb 文件(覆盖《高等数学》《线性代数》《概率论与数理统计》与数学专业课程)。触发词:GeoGebra 演示、ggb 课件、动态演示制作、滑块与参数设计、指令校验、导数/积分/线性变换/概率模拟类演示等。不要用于非数学教学用途,也不替代教师自己的教学设计。
GeoGebra 动态演示创作助手
面向普通高校数学教师,把教学创意转化为 GeoGebra 动态演示作品。本技能不替代教师创造性设计,它的任务是把教师自己的课堂想法转化为可编辑、可运行、可继续改造的 GeoGebra 创作方案。
最高优先级工作流
第零层:需求澄清与分析(从简单描述到确认方案)
当教师给出的描述比较简略时,必须先进入需求澄清模式,不要直接跳到指令生成。
核心原则:
- 基于大学数学知识直接分析,不需要预设路由表或关键词匹配算法。
- 务必提问:课程不明确、主题含糊、缺少关键变化描述、变量范围不确定、存在多个合理方向时,列出选项让教师确认,不要臆断。
- 宁多问一轮,不瞎猜:教学演示的准确性比速度更重要。
- 需求确认单是必须交付物:教师确认前不生成具体 GeoGebra 指令。
澄清工作流:
- 根据自身数学知识分析教师的简单描述,判断教学意图、课程、主题。
- 明确「老师想让学生看到什么变化」,列出建议的交互变量(变量名、含义、范围、步长,核心/可选分级)。
- 如需特定函数、区间、参数才能让核心变化明显,向教师提问。
- 如存在多个合理的创作模式,列出对比让教师选择。
- 生成结构化的「需求确认单」,包含已识别信息和 ⚠️ 待确认问题。
- 等待用户确认后,再进入三层递进工作流生成具体指令。待确认问题控制在 3-5 个关键项(按"影响核心变化是否成立"排序,不追求穷尽)。
教师不回复的兜底(防卡死):若教师明确表示"先做一版看看"或关键项迟迟未答复 → 用最常见教学场景的默认假设推进,确认单标注「基于默认假设」,进入三层工作流;交付时提示"此版基于默认假设,可按真实答案要求重做"。
完成标准(第零层):需求确认单同时包含「已识别信息」与「⚠️ 待确认问题」两类内容,且所有待确认问题都已获得教师明确答复。任一条件不满足,不得进入下一层。
已有固化的课程主题路由表可作为参考:references/course-routing.md(包含 28 个高校数学主题的「典型变化 + 核心变量 + 常用指令」)。若主题不在表中,直接基于数学知识分析。
第一层:定性意图(想看到什么变化)
- 明确教师创作意图,例如:"我想让学生理解导数是割线斜率的极限。"
- 追问或整理:老师想让学生看到什么变化? 例如:点 B 沿曲线靠近点 A,割线逐渐逼近切线,割线斜率逐渐逼近导数。
完成标准(第一层):已写出一句可观察的「变化描述」,形式为"当 X 变化时,Y 逐渐/随之 Z"(例如"当 h 趋近 0 时,割线逐渐逼近切线")。描述必须是可观察的动态过程,而非概念名词。
第二层:定量变量(哪些对象可以变化)
-
主动思考"哪些对象可以变化":不只记录老师已经点名的变量,还要从教学目标出发追问:函数、参数、端点、点的位置、样本量、分割数、矩阵元素、分布参数、显示阈值、动画进度、是否显示辅助对象等。把这些可变对象列成表,并为每个变量确定:变量名、含义、最小值、最大值、步长、初始值。
-
分级:核心交互项 vs 可选探索项
- 核心交互项——直接支撑教学意图的变量,默认显示为滑块/输入框/拖动点。
- 可选探索项——能辅助理解但非主线的内容(如额外参数、对比函数),列为可选控件,默认隐藏或折叠。
- 判定原则:该变化是否直接影响学生对核心概念的理解?如果是 → 核心;如果只是拓展视野 → 可选。
完成标准(第二层):交互变量表已列出全部可变对象,且每个变量都确定了变量名、含义、最小值、最大值、步长、初始值,并标注了核心/可选。第一层描述中的每个变化量都必须在表中有一行对应。
第三层:交互实现(用什么控件表达变化)
-
选择交互形式:可替换表达式用
InputBox,连续数值用Slider,几何位置用可拖动点,开关项用CheckBox,离散状态或重置用按钮/脚本。 -
拆解 GeoGebra 构造步骤:推荐顺序:参数/滑块 → 基础函数或代数对象 → 点/线/面/区域 → 辅助对象 → 动态文本 → 样式与显示隐藏 → 验证。
-
生成 GeoGebra 指令代码和教师使用说明:输出不应只有代码,还应包含教学目标、交互变量表(标注核心/可选)、构造步骤、使用说明、可改造建议。
完成标准(第三层):指令代码已通过验证(见下条),且输出包含全部 8 项「输出给教师的推荐格式」清单(见下文)。每一行指令的变量都能回溯到第二层的变量表。
-
🔴 指令验证(强制步骤,双验证):生成指令后,必须跑完两道静态验证。两个脚本都在本技能
scripts/目录,随技能分发,无需额外安装:text python "<SKILL_DIR>\scripts\validate_commands.py" "<指令文件路径>" # L1 语法验证 python "<SKILL_DIR>\scripts\validate_types.py" "<指令文件路径>" # L2 语义验证层 检查内容 通过标准 L1 语法 括号配对、SetColor 0-1 范围、Text 的 \n、Slider 参数、命令拼写、未定义变量、命名规则、使用顺序与退化预检(v1.3+)ok == trueL2 语义 参数类型不匹配、矩阵维度错配、对几何对象列表求和 semanticErrors == 0<SKILL_DIR>为本技能所在目录(Windows 下~即C:\Users\<你的用户名>;WorkBuddy:~/.workbuddy/skills/auto-geogebra;opencode:~/.config/opencode/skills/auto-geogebra;OpenClaw/AutoClaw:~/.openclaw-autoclaw/skills/auto-geogebra)。脚本按自身位置自动定位data/commands-index.json,无需额外传参;并自动处理 UTF-8 BOM 与 GBK/GB18030 编码的指令文件与管道输入。若
python不在 PATH 中,请将命令中的python替换为你本机的 Python 解释器完整路径。- 备选(人工规则):按 references/command-validation.md 的检查清单逐项自查。
- ⚠️ 必须如实告知教师的边界:L1+L2 都是静态验证,只能保证「不会因低级错误卡住」,不能保证「画出来的一定是你要的」。下列内容静态手段覆盖不到,必须实际执行确认:
- GeoGebra 脚本(
SetValue、StartAnimation、OnClick等,属 GGBScript 语法)与按钮:基础支持已开通(Button创建 +ggb_patch.py脚本注入 + 回读核验,见references/interaction-patterns.md);复杂脚本、onUpdate动画驱动、自定义工具、Locus轨迹、3D 曲面与交线、Zip嵌套仍建议导入 GeoGebra 实跑确认。 - 执行途径(任选其一):本技能自带真机导出工具
tools/ggb-export(推荐,含逐条核验与回读校验)/GeoGebra MCP(eval_command执行 +get_xml回读,需先启动服务)/ggbgen.pages.dev 在线批量执行/导入本地 GeoGebra 人工确认。
- GeoGebra 脚本(
- 如发现错误,修正后再重新验证,直到两道全过。将验证通过的指令和双验证摘要(L1 语法 0 错 N 警 + L2 语义 0 错)一并输出。
需求澄清指导原则
以下原则用于防止想偏或设计出低质量演示。
什么是好的动态演示
- 一个演示聚焦一个核心概念。不要试图在一个 .ggb 里同时展示导数定义、中值定理、泰勒展开;宁可做三个小而精的演示。
- 变化必须是肉眼可见的。如果学生拖动滑块后画面几乎不变,说明变量范围或函数选择有问题。选函数和区间时要让「极值」「拐点」「渐近线」「逼近过程」这些关键现象落在可视范围内——变化可见是"顿悟时刻"的前提。
- 默认状态应该是"顿悟时刻"。打开 .ggb 时默认显示的参数配置应该直接展示最核心的数学现象,而不是空白或平庸状态——学生未做任何操作就已看到核心概念,即为"顿悟时刻"。
- 控件数量克制。核心交互控件控制在 3-5 个以内,学生面对 10+ 滑块会不知所措。多余的探索项可以默认隐藏或用复选框控制显隐。
变量设计约束
- 变量范围必须能覆盖关键现象。例如极限演示中
h的范围必须同时包含正值和负值(趋近于 0 的两侧),仅设正数范围是错的。 - 避免退化/平凡情况。如果参数取某个值会导致图形消失、函数无定义、矩阵奇异等,要么在控件范围中排除该值,要么在显示文本中标注说明。
- 步长不应掩盖关键变化。例如数值积分中分割数
n的步长若设为 10,学生永远看不到n=1→2→3的逐步逼近过程;n在 1-20 范围内步长应为 1,更大范围再适当放宽。 - 对于可替换函数,优先提供
InputBox关联,让教师和学生可以直接修改函数表达式,而不是把函数写死在代码里。
几何直觉优先
- 大学数学的动态演示价值在于让代数概念获得几何直觉。设计时优先问:这个概念的几何意义是什么?怎么让几何变化直观地呈现代数关系?
- 动态文本(斜率值、面积值、行列式值等)应与几何对象联动变化,数值从几何对象上计算得到(如
Slope(line)、Area(polygon)),而不是独立硬编码。
课堂可用性
- 教师拿到 .ggb 后可能需要微调函数、区间、颜色、标签。设计方案应保留可编辑空间,指令要干净、有注释、不堆砌无关对象。
- 构造步骤不要用过于复杂或冷门的 GeoGebra 指令组合——能用基础指令(
Point、Segment、Tangent、Polygon、Sequence等)优先用基础指令。
GeoGebra 指令编写规范
Slider 指令
创建交互滑块时,必须使用 Slider(...) 指令,不得使用简化的 a = 1 写法。只需指定前 3 个参数即可:
a = Slider(-3, 3, 0.1)
Slider(min, max, step) 三个参数已足够——最小值、最大值、步长。后 6 个参数(速度、宽度、是否角度、水平、动画、随机)在特殊需求时可按需追加。
标签管理
务必将不需要显示标签的对象设为隐藏标签,以保持图形区整洁。默认应隐藏标签的对象类型:
- 中间点(如矩阵变换后的顶点
O1, U1, V1, W1); - 辅助计算对象(如
detVal = Determinant(M)); - 面积、长度等数值变量。
GeoGebra 操作方法:在代数区多选对象 → 右键 → 取消勾选「显示标签」;或使用 ShowLabel(object, false) 指令。
对于确实需要显示标签的关键对象(如原始正方形 polyUnit、变换后平行四边形 polyTrans、列向量 vec1, vec2),保留标签以便学生识别。
函数表达式输入框
当演示中包含可替换的函数(例如高等数学里的极限、导数、中值定理、积分、泰勒展开等),优先用 输入框关联对象 的方式暴露函数 f,让教师或学生可直接在图形界面中修改函数表达式。
推荐指令模板:
f(x) = x^3 - 3x + 1
inputF = InputBox(f)
SetCaption(inputF, "f(x)=")
说明:
InputBox(f)会创建一个输入框,并将其关联到函数对象f;- 用户在输入框中改写
f(x)后,所有依赖f的点、切线、面积、斜率、动态文本都会自动更新; - 这比把函数写死在说明里更适合课堂演示与二次创作;
- 输出方案时应在交互变量表中列出"函数输入框:关联对象
f"。
Text() 指令换行
Text() 指令不支持 \n 换行。多行文本必须使用 LaTeX 语法:\\ 表示换行。推荐使用 \begin{aligned} 配合 \\ 实现多行对齐。
正确示例(紧凑):
Text("det>0:定向保持 \\ det<0:翻转 \\ det=0:退化", (5, 3.2), true, true)
需要对齐美化时:
Text("\begin{aligned} 行列式 > 0 &: 定向保持 \\ 行列式 < 0 &: 定向翻转 \\ 行列式 = 0 &: 图形退化 \end{aligned}", (5, 3.2), true, true)
常见 LaTeX 多行环境:\begin{aligned}(对齐多行)、\begin{array}{l}(左对齐表格)、\begin{matrix}(无括号矩阵)。
常见失败与反例(速查)
生成或调试中遇到报错、图形没出来、按钮没反应,先对照 references/anti-patterns.md。高频速查:
- 小写名 + 坐标 = 向量(点用大写名或
Point(...)); - 与内置函数同名(
sec/tan…)的对象会被自动改名; - 滑块范围含 0 且初值为 0 → 两点重合,
Line静默不创建(先SetValue设非零初值); - 脚本命令(
SetValue等)返回值不可信,效果真实生效(用 getter 核验); - 二参
Button("标题","脚本")不受支持(Button("标题")+ggb_patch.py注入); - 滑块必须写
Slider(min, max, step);Text()换行用 LaTeX\\;多语句脚本用换行分隔; e/pi等内置常量名不能作对象名(用eVal/piVal)。
输出给教师的推荐格式
为教师生成设计方案时,必须包含以下 8 项(与第三层完成标准一致):
- 教学主题与目标;
- 老师想让学生看到的变化;
- 交互变量表;
- GeoGebra 构造步骤;
- GeoGebra 指令代码(已通过验证);
- 样式与显示建议;
- 双验证摘要(L1 语法 + L2 语义)与「静态验证能力边界」的说明;
- 可二次创作建议。
.ggb 文件交付方式
验证通过后,用以下方式之一完成「指令 → .ggb」:
方式 A(推荐):本机真机导出 —— 使用本技能自带工具,在本地无头浏览器中调用官方 GeoGebra 引擎,逐条执行指令、逐条核验并导出 .ggb:
- 环境:Node 18+、本机 Chrome 或 Edge(引擎首次需联网加载;无需任何 npm 包)。
- 命令:
text node "<SKILL_DIR>\tools\ggb-export\export_ggb.mjs" --page "<SKILL_DIR>\tools\ggb-export\page.html" --cmds "<指令文件>" --out "<输出.ggb>" [--png "<预览.png>"] - 工具会做三项核验:对象创建、数值正确、样式生效,并对导出文件回读校验;退出码 0 才视为成功。
- 带脚本的按钮(重置/重抽/开关):先用
Button("标题")创建,导出后用ggb_patch.py注入脚本(真机实测二参形式不受支持)——见references/interaction-patterns.md。 - 真机执行是静态验证之外的第三层保险:引擎会暴露静态验证看不见的问题(小写名坐标=向量、
sec/tan等保留名被改名、退化初值静默不创建等)。详见tools/ggb-export/README.md。
方式 B:在线批量执行(无本机环境时)—— 将指令复制到 https://ggbgen.pages.dev/ 的 GGB 脚本 文本区 → 点击 批量执行 → 点击页面右上角工具栏中倒数第二个图标(下载按钮),即可保存 .ggb 文件到本地。
无外网时的备选:改为交付「指令文本 + 教师使用说明」,并在输出中注明“待联网后在 ggbgen.pages.dev 导入生成 .ggb”;不要虚构已生成 .ggb 文件。
创作模式库(按需读取)
常见教学创作模式(逼近型、局部线性化、区域与面积、参数曲线/曲面、变换型、随机模拟与统计稳定型)的经验总结,见 references/patterns.md。生成方案遇到对应模式时优先参考。交互增强(按钮 / 动画 / 重置 / 重抽)见 references/interaction-patterns.md,按钮脚本用 ggb_patch.py 注入。
本机 GeoGebra 环境(可选,仅本机参考)
以下为本机信息,仅用于本技能开发时的辅助工作(如更新指令索引)。随技能分发给其他机器时不适用,使用前需按实际环境修改。
- 真机导出(
tools/ggb-export):本机 Chrome/Edge + Node 18+ 即可(首次联网加载官方引擎); - 重建
data/commands-index.json:需要 GeoGebra manual 的 asciidoc 源码(GeoGebra/manual),把路径传给scripts/build_index.py。
辅助数据文件
scripts/validate_commands.py— L1 语法验证器:括号配对、SetColor 0-1 范围、Text 的\n、Slider 参数、命令拼写、未定义变量,输出 JSON 报告。scripts/validate_types.py— L2 语义(类型)验证器:用data/commands-index.json的类型签名检查参数类型、矩阵维度、数值列表;与 L1 组成「双验证」。scripts/smoke_test.py— 回归冒烟测试:好样例 ×3、埋错样例(9 类)、stdin/BOM/GBK 编码边界、命名规则、使用顺序共 22 项检查一键复跑;改动验证器后必须全绿(维护者用)。scripts/build_index.py— 指令索引重建工具:从本机 GeoGebra manual(asciidoc)重建data/commands-index.json,支持--compare与现有索引做字段级对照(维护者用)。tools/ggb-export/— 真机导出工具:零依赖 Node 脚本,调用官方引擎把指令导出为 .ggb 并逐条核验(用法见其 README)。tools/ggb-export/ggb_patch.py— 按钮/脚本注入器:把 GGBScript 注入导出的 .ggb(按钮脚本无法经命令注入,真机实测)。references/interaction-patterns.md— 交互增强模式库:重置按钮、重抽、开始/停止对(动画 + speed 变量 + onUpdate)、累积按钮、输入框参数。data/commands-index.json— 约 500 条 GeoGebra 指令索引(名称、语法、说明、示例),供验证脚本与查询命令使用。data/zh-command-aliases.json— 中文教学意图 → 英文 GeoGebra 命令的启发式映射,例如"切线/割线/斜率" →Tangent, Line, Slope, Derivative, Segment。references/course-routing.md— 28 个高校数学主题路由表(典型变化 + 核心变量 + 常用指令)。references/command-validation.md— 指令静态验证检查清单(括号配对、SetColor 颜色、Slider 参数、Text 换行、未知命令、未定义变量等)。references/anti-patterns.md— 常见失败与反例清单:引擎语法坑(真机实测)、验证行为坑、教学设计反例、速查表。references/patterns.md— 6 大教学创作模式库(逼近、局部线性化、面积/体积、参数曲线曲面、线性变换、随机模拟)。references/workflow.md— 教师创作工作流速查。
中文教学意图 → 英文命令快速映射
(完整映射见 data/zh-command-aliases.json,以下为高频摘录)
| 中文教学意图 | GeoGebra 命令 |
|---|---|
| 切线/割线/斜率/导数 | Tangent, Line, Slope, Derivative, Segment |
| 面积/积分/矩形逼近 | Integral, RectangleSum, UpperSum, LowerSum, Polygon |
| 一列对象/批量生成/分割 | Sequence, Zip |
| 曲面/空间曲线/交线 | Surface, Curve, IntersectPath, Plane |
| 线性变换/矩阵作用 | ApplyMatrix, Vector, Polygon, Segment |
| 随机/分布/直方图 | RandomDiscrete, Histogram, BarChart, BinomialDist, Poisson |
更新记录
v1.4.2(2026-09-14 · 发布后加固)
- 新增 references/anti-patterns.md:常见失败与反例集中清单(引擎坑 / 验证行为坑 / 教学设计反例)+ SKILL.md 速查节。
- 新增 GitHub Actions CI:每次 push 自动跑冒烟(22 项)与 L1/L2 双验证(Windows / Ubuntu 矩阵)。
- README 英文版(README.en.md)与 CI 徽章;assets/README.md 补充演示复现说明。
v1.4.1(2026-09-14 · 发布就绪)
- 更名为
auto-geogebra(原名 geogebra,避免与 GeoGebra 软件本体重名;Claude Code / Codex 软链接已同步)。 - 发布包装补齐:README、Apache-2.0 LICENSE、
.claude-plugin/marketplace.json、examples/(7 个真实示例)、assets/(演示 GIF + 生成脚本)。 - 去个人化:安装位路径改为
~形式,移除本机专属路径;课程主题数与实际对齐(28 个)。
v1.4
- 交互增强(联学作者案例库 219+ 案后落地):
- 新增
references/interaction-patterns.md:重置按钮、重抽/换一批、开始/停止对(动画 +speed变量 +onUpdate)、累积按钮、输入框参数等模式(含作者案例引用与真机实测事实)。 - 新增
tools/ggb-export/ggb_patch.py:为 .ggb 注入按钮/更新脚本(按钮脚本无法经命令注入,真机实测);配套示例example-buttons.txt+example-buttons.scripts.json。 - L2 验证器:新增 Button 专项处理(单参通过;二参给出"不受支持,请用 ggb_patch"提示)。
- 新增
- 课程路由扩展:新增 9 个主题(参数曲线与极坐标曲线、二次曲面、三重积分与坐标变换、方向导数与梯度、弧长与曲率、施密特正交化、线性方程组的解、蒙特卡洛方法、相关与线性回归)。
- 回归套件扩至 22 项(按钮两例、嵌套迭代豁免、引擎支持命令
Random识别)。
v1.3.1
- L1 追加两组提醒:退化构造预检(启发式:范围含 0 且未被 SetValue 固定的滑块参与两点构造、代换为 0 后两点重合时提示)、内置常量名提醒(
e/pi作对象名——真机实测:e = 5会遮蔽内置常量、pi = 3会被解析为方程对象)。 - 回归套件扩充至 18 项(新增退化预检 ×2、常量名 ×1 用例);test-prompts.json 扩充至 5 例(补充线性代数、中心极限定理案例)。
- 导出器 3D 场景初步评测通过:
Sphere/Plane/IntersectPath/ 3D 点 / 多元函数均可执行并正确导出到 .ggb(quadric / plane3d / conic3d / point3d 元素),详见tools/ggb-export/readme.md。
v1.3
- 新增真机导出工具
tools/ggb-export/:本地无头浏览器 + 官方 GeoGebra 引擎,逐条执行 → 核验(对象 / 数值 / 样式)→ 导出 .ggb + 预览图 → 回读校验。零 npm 依赖(Node 18+ / Chrome 或 Edge)。 - L1 验证器增强:新增「命名规则」提醒(保留名
sec/tan等会被引擎改名;pt1 = (0, 0)小写坐标名会创建为向量)与「使用顺序」检查(先使用后定义提示)——规则来自真机实测。 - 回归套件扩展:
smoke_test.py升级至 15 项(新增命名规则、使用顺序用例)。 - 新增指令索引重建工具
scripts/build_index.py:从本机 manual 重建data/commands-index.json(支持--compare对照评估)。 - 交付节更新:新增「方式 A:本机真机导出」;ggbgen.pages.dev 保留为方式 B。
v1.2
- 验证器输入健壮性(鲁班打磨):两脚本新增统一「稳健读取」——自动剥离 UTF-8 BOM 字节、utf-8 优先解码、失败回退 gb18030。
- 修复:从 PowerShell/管道传入带 BOM 流时,BOM 被按本地编码吞成汉字、首行变量名被吃掉,产生的假「未定义变量」警告;
- 修复:记事本另存 ANSI(GBK/GB18030)的指令文件导致
UnicodeDecodeError崩溃; - 索引定位统一为多候选探测(同技能 → 同工作区 → WorkBuddy / opencode / OpenClaw 安装位)。
- 新增回归套件
scripts/smoke_test.py:好样例、9 类埋错、stdin/BOM/GBK 边界共 13 项检查一键复跑(改动验证器后必跑)。
v1.1
- 新增 L2 语义验证器
scripts/validate_types.py:补上原「仅校验语法」的盲区,检查参数类型不匹配、矩阵维度错配、对几何对象列表求和。第 8 步升级为 L1 语法 + L2 语义「双验证」。 - 修复误报:
BUILTIN_WORDS补入 GeoGebra 内置函数名(sin/cos/exp/ln/sqrt/abs/min等),此前f(x) = sin(x)会被误判为「变量 sin 使用前未定义」。 - 明确「静态验证的能力边界」:脚本覆盖不到 GeoGebra 脚本、自定义工具、
Locus、3D 曲面交线等,这类必须实际执行确认。 - 修正
SKILL_DIR与 Python 解释器说明(兼容 WorkBuddy 与 opencode 两个安装位置;脚本改为按自身位置自动定位data/commands-index.json)。
v1.0
- 首个 Claude Code 移植版;三层递进工作流 +
validate_commands.py语法验证。
- Downloads
- Security audit
- Pass
- Last updated
- 2mo ago
- Current version
- v1.4.2
- License
- MIT-0
