auto-geogebra

Use when 需要把高校数学教学创意转化为可运行的 GeoGebra 动态演示/课件/动画：设计交互变量与滑块、生成并验证 GeoGebra 指令、导出 .ggb 文件（覆盖《高等数学》《线性代数》《概率论与数理统计》与数学专业课程）。触发词：GeoGebra 演示、ggb 课件、动态演示制作、滑块与参数设计、指令校验、导数/积分/线性变换/概率模拟类演示等。不要用于非数学教学用途，也不替代教师自己的教学设计。

GeoGebra 动态演示创作助手

面向普通高校数学教师，把教学创意转化为 GeoGebra 动态演示作品。本技能不替代教师创造性设计，它的任务是把教师自己的课堂想法转化为可编辑、可运行、可继续改造的 GeoGebra 创作方案。

最高优先级工作流

第零层：需求澄清与分析（从简单描述到确认方案）

当教师给出的描述比较简略时，必须先进入需求澄清模式，不要直接跳到指令生成。

核心原则：

• 基于大学数学知识直接分析，不需要预设路由表或关键词匹配算法。
• 务必提问：课程不明确、主题含糊、缺少关键变化描述、变量范围不确定、存在多个合理方向时，列出选项让教师确认，不要臆断。
• 宁多问一轮，不瞎猜：教学演示的准确性比速度更重要。
• 需求确认单是必须交付物：教师确认前不生成具体 GeoGebra 指令。

澄清工作流：

1. 根据自身数学知识分析教师的简单描述，判断教学意图、课程、主题。
2. 明确「老师想让学生看到什么变化」，列出建议的交互变量（变量名、含义、范围、步长，核心/可选分级）。
3. 如需特定函数、区间、参数才能让核心变化明显，向教师提问。
4. 如存在多个合理的创作模式，列出对比让教师选择。
5. 生成结构化的「需求确认单」，包含已识别信息和 ⚠️ 待确认问题。
6. 等待用户确认后，再进入三层递进工作流生成具体指令。待确认问题控制在 3-5 个关键项（按"影响核心变化是否成立"排序，不追求穷尽）。

教师不回复的兜底（防卡死）：若教师明确表示"先做一版看看"或关键项迟迟未答复 → 用最常见教学场景的默认假设推进，确认单标注「基于默认假设」，进入三层工作流；交付时提示"此版基于默认假设，可按真实答案要求重做"。

完成标准（第零层）：需求确认单同时包含「已识别信息」与「⚠️ 待确认问题」两类内容，且所有待确认问题都已获得教师明确答复。任一条件不满足，不得进入下一层。

已有固化的课程主题路由表可作为参考：references/course-routing.md（包含 28 个高校数学主题的「典型变化 + 核心变量 + 常用指令」）。若主题不在表中，直接基于数学知识分析。

第一层：定性意图（想看到什么变化）

1. 明确教师创作意图，例如："我想让学生理解导数是割线斜率的极限。"
2. 追问或整理：老师想让学生看到什么变化？ 例如：点 B 沿曲线靠近点 A，割线逐渐逼近切线，割线斜率逐渐逼近导数。

完成标准（第一层）：已写出一句可观察的「变化描述」，形式为"当 X 变化时，Y 逐渐/随之 Z"（例如"当 h 趋近 0 时，割线逐渐逼近切线"）。描述必须是可观察的动态过程，而非概念名词。

第二层：定量变量（哪些对象可以变化）

3. 主动思考"哪些对象可以变化"：不只记录老师已经点名的变量，还要从教学目标出发追问：函数、参数、端点、点的位置、样本量、分割数、矩阵元素、分布参数、显示阈值、动画进度、是否显示辅助对象等。把这些可变对象列成表，并为每个变量确定：变量名、含义、最小值、最大值、步长、初始值。

4. 分级：核心交互项 vs 可选探索项

   • 核心交互项——直接支撑教学意图的变量，默认显示为滑块/输入框/拖动点。
   • 可选探索项——能辅助理解但非主线的内容（如额外参数、对比函数），列为可选控件，默认隐藏或折叠。
   • 判定原则：该变化是否直接影响学生对核心概念的理解？如果是 → 核心；如果只是拓展视野 → 可选。

完成标准（第二层）：交互变量表已列出全部可变对象，且每个变量都确定了变量名、含义、最小值、最大值、步长、初始值，并标注了核心/可选。第一层描述中的每个变化量都必须在表中有一行对应。

第三层：交互实现（用什么控件表达变化）

5. 选择交互形式：可替换表达式用 InputBox，连续数值用 Slider，几何位置用可拖动点，开关项用 CheckBox，离散状态或重置用按钮/脚本。

6. 拆解 GeoGebra 构造步骤：推荐顺序：参数/滑块 → 基础函数或代数对象 → 点/线/面/区域 → 辅助对象 → 动态文本 → 样式与显示隐藏 → 验证。

7. 生成 GeoGebra 指令代码和教师使用说明：输出不应只有代码，还应包含教学目标、交互变量表（标注核心/可选）、构造步骤、使用说明、可改造建议。

完成标准（第三层）：指令代码已通过验证（见下条），且输出包含全部 8 项「输出给教师的推荐格式」清单（见下文）。每一行指令的变量都能回溯到第二层的变量表。

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 == true
   L2 语义	参数类型不匹配、矩阵维度错配、对几何对象列表求和	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 人工确认。
   • 如发现错误，修正后再重新验证，直到两道全过。将验证通过的指令和双验证摘要（L1 语法 0 错 N 警 + L2 语义 0 错）一并输出。

需求澄清指导原则

以下原则用于防止想偏或设计出低质量演示。

什么是好的动态演示

1. 一个演示聚焦一个核心概念。不要试图在一个 .ggb 里同时展示导数定义、中值定理、泰勒展开；宁可做三个小而精的演示。
2. 变化必须是肉眼可见的。如果学生拖动滑块后画面几乎不变，说明变量范围或函数选择有问题。选函数和区间时要让「极值」「拐点」「渐近线」「逼近过程」这些关键现象落在可视范围内——变化可见是"顿悟时刻"的前提。
3. 默认状态应该是"顿悟时刻"。打开 .ggb 时默认显示的参数配置应该直接展示最核心的数学现象，而不是空白或平庸状态——学生未做任何操作就已看到核心概念，即为"顿悟时刻"。
4. 控件数量克制。核心交互控件控制在 3-5 个以内，学生面对 10+ 滑块会不知所措。多余的探索项可以默认隐藏或用复选框控制显隐。

变量设计约束

5. 变量范围必须能覆盖关键现象。例如极限演示中 h 的范围必须同时包含正值和负值（趋近于 0 的两侧），仅设正数范围是错的。
6. 避免退化/平凡情况。如果参数取某个值会导致图形消失、函数无定义、矩阵奇异等，要么在控件范围中排除该值，要么在显示文本中标注说明。
7. 步长不应掩盖关键变化。例如数值积分中分割数 n 的步长若设为 10，学生永远看不到 n=1→2→3 的逐步逼近过程；n 在 1-20 范围内步长应为 1，更大范围再适当放宽。
8. 对于可替换函数，优先提供 InputBox 关联，让教师和学生可以直接修改函数表达式，而不是把函数写死在代码里。

几何直觉优先

9. 大学数学的动态演示价值在于让代数概念获得几何直觉。设计时优先问：这个概念的几何意义是什么？怎么让几何变化直观地呈现代数关系？
10. 动态文本（斜率值、面积值、行列式值等）应与几何对象联动变化，数值从几何对象上计算得到（如 Slope(line)、Area(polygon)），而不是独立硬编码。

课堂可用性

11. 教师拿到 .ggb 后可能需要微调函数、区间、颜色、标签。设计方案应保留可编辑空间，指令要干净、有注释、不堆砌无关对象。
12. 构造步骤不要用过于复杂或冷门的 GeoGebra 指令组合——能用基础指令（Point、Segment、Tangent、Polygon、Sequence 等）优先用基础指令。

GeoGebra 指令编写规范

Slider 指令

创建交互滑块时，必须使用 Slider(...) 指令，不得使用简化的 a = 1 写法。只需指定前 3 个参数即可：

text

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，让教师或学生可直接在图形界面中修改函数表达式。

推荐指令模板：

text

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

Text("det>0：定向保持 \\ det<0：翻转 \\ det=0：退化", (5, 3.2), true, true)

需要对齐美化时：

text

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 项（与第三层完成标准一致）：

1. 教学主题与目标；
2. 老师想让学生看到的变化；
3. 交互变量表；
4. GeoGebra 构造步骤；
5. GeoGebra 指令代码（已通过验证）；
6. 样式与显示建议；
7. 双验证摘要（L1 语法 + L2 语义）与「静态验证能力边界」的说明；
8. 可二次创作建议。

.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 语法验证。