AiGGB 使用教程：一句话生成 GeoGebra 教学动图
静态插图讲不清「过程」：单摆怎么摆、斜抛怎么飞、参数滑动时图像如何变形——这些恰恰是数理教学里最需要动的部分。AiGGB（开源，MIT 协议）解决的就是这件事：用自然语言描述，AI 直接在 GeoGebra 画布上生成可拖动、可播放的教学动图，甚至可以把题目拍照发给它，读题、建模、作图一条龙。本篇是从安装到上手的完整教程。
五分钟跑起来
安装与启动
AiGGB 是纯前端项目（React + Vite），不需要后端，本地起一个开发服务器即可：
git clone https://github.com/gmsjy/aiggb
cd aiggb
npm install
npm run dev # 浏览器打开 http://localhost:5173配置模型 API
首次启动会自动弹出 API 设置面板。它接受任何 OpenAI 兼容接口，预置了 6 个服务商。国内使用推荐 DeepSeek（直连、快、便宜）：
| 设置项 | 推荐值 |
| Provider | DeepSeek |
| 主力模型 | deepseek-v4-pro（复杂动图 / 3D）或 deepseek-v4-flash（日常） |
| 轻量模型（精炼 / 评估） | deepseek-v4-flash |
| 视觉模型（题目识别） | deepseek-v4-flash-vision-exp |
| API Key | 从 platform.deepseek.com 获取，形如 sk-... |
填好后点「测试连接」，通过即保存。Moonshot（Kimi）、智谱 GLM、SiliconFlow、OpenAI、本地 Ollama 都在预置列表里，切换 Provider 改个 Key 就行。
记忆点：API Key 明文存在浏览器 localStorage 里——公共电脑不要用，随时可在设置面板清除。所有会话数据与 Key 是分开存储的，「清除全部会话」不会动到凭据。
两种运行模式
设置面板里可以切换执行模式，面向使用者的区别一句话讲清：
- 两阶段管线（默认）：AI 先把你的意图「精炼」成一份分节绘图规格，弹出规格确认气泡（可编辑、可重新生成），确认后再编译成 GeoGebra 命令逐条执行，最后自动做一次满足度评估——不满意会追加一轮修复。适合「一句话出图」的常规场景；
- Agent 模式：AI 作为工具调用代理，逐步操作 23 个工具（建点、造滑块、执行命令、查询对象……），每一步都拿到执行反馈再决定下一步。负半径、min 大于 max、依赖对象缺失这类错误会在调用画布前被语义预检拦截并喂回 AI 自行修正；连续 3 轮执行失败自动熔断。适合复杂构造、多对象联动的场景。
带图片输入的轮次固定走 Agent 构造，与模式开关无关。
拍题出动图：把题目截图变成动图
这是 AiGGB 最适合教学者的功能：把高中数理题拍照或截图发给它，AI 读题后自动设计并构造动图。
三种加图方式
- 点输入框左侧的「附件」按钮选择图片（可多选）；
Ctrl+V直接粘贴剪贴板截图；- 把图片文件拖拽到输入区。
每条消息最多 3 张（同一题的多张图会合并解读），上传前自动等比压缩到最长边 1280px。
前置配置：视觉模型
题目识别由视觉模型完成（设置 → 高级 → 角色专用模型），需要选一个支持图片输入的模型：DeepSeek 选 deepseek-v4-flash-vision-exp，智谱选 glm-4.5v，SiliconFlow 选 Qwen2.5-VL-72B，OpenAI 选 gpt-4o，本地 Ollama 选 qwen2.5vl:7b。留空则跟随主力模型（此时主力必须本身多模态）。
完整流程
- 附加题目图片，可附一句补充（如「画出运动过程」）；
- 视觉模型识别后弹出题目确认气泡：题干转写、已知量、求解目标、图示信息、动画建议——识别有误直接编辑题干改正（比重新识别快），图片不清点「重新识别」；
- 确认后 AI 以 Agent 工具循环逐步构造，右侧脚本面板可实时观察；
- 构造完成时自动做画布状态核对：画布与题目解读逐项对照，发现偏差自动回喂修正（最多 2 轮）；
- 结束后附一份满足度评估报告。
降级边界：识别失败但消息里有文字，直接按文字构造；纯图片识别失败会提示去配置视觉模型；3D 题目要先手动切到 3D 模式再发送。
提示词怎么写：说清三要素
AiGGB 把自然语言转译成 GeoGebra 命令——描述越精确，结果越接近预期。每个请求说清三件事：画什么、参数怎么调、要不要动起来。
对照示例：
模糊：画个圆 明确：画以原点为圆心、半径为 3 的圆
模糊：画个运动的点 明确：点 P 在单位圆上匀速旋转，角速度用滑块控制
模糊：画个函数 明确：画 y = sin(kx)，k 用滑块从 1 调到 5确实缺核心参数（如画圆没给半径）AI 会反问；能合理默认的不会追问——圆心默认原点，角速度默认 1 rad/s。
让图像动起来靠四个关键词：自动播放、留轨迹、滑块可调、动画。想控制某个量可调，直接给范围与默认值：
单摆 L = 1 m，初角 30 度，小角近似，摆动留轨迹，右侧同步画摆角-时间曲线
振幅 A 滑块 0.5 到 3，默认 1
斜抛 v0 = 20 m/s，仰角 45 度，t 自动播放多轮对话里 AI 记得住已创建的对象名，可以持续修改：「把圆改成蓝色虚线」→「加一条从圆心 O 到 P 的半径，染绿」→「P 的轨迹关掉，速度改成 2 倍」。注意修改指令依赖上一轮成功创建的对象——上轮失败了，修改也会失败。
记忆点：两类常见踩坑——
v在 GeoGebra 里是矢量类型，不能当标量滑块（改说「速度大小用滑块默认 5」）；大写单字母A默认是点类型，当振幅名会跟坐标点冲突（改用Amp或加「振幅」前缀描述）。
平面与 3D 模式
默认在二维平面作图。工具栏可切换到 3D 画布，切换会清空当前画布与聊天历史（两者是不同的 GeoGebra 引擎）。在平面模式描述「正方体」，AI 只能画投影；切到 3D 再发同一句话，才是真三维：
正方体边长 3，平面 ACF 截正方体，截面红色高亮
球体半径 3，用平面 z = 1.5 截球，截面橙色高亮
空间向量 u=(2,0,0)、v=(1,2,0)，叉乘 w = u x v 用蓝色画出工具箱、会话与导出
| 功能 | 说明 |
| 数学 / 物理域 | 切换 AI 的行为偏好：物理模式自动启用力矢量叠加、 等常量、带单位坐标轴 |
| 模板库 | 数学 / 物理 / 3D 各 4 个场景模板，点卡片即出图，不想写提示词就从这里开始 |
| 会话 | 每轮对话自动保存（含画布快照），刷新不丢；最多 30 个会话，可新建 / 切换 / 重命名 |
| 撤销 | 撤销上一轮 AI 产生的全部命令 |
| 导出 .ggb | 下载 GeoGebra 原生文件——可在桌面版 GeoGebra 打开继续编辑 |
| 截图 | 导出 PNG，直接插进课件或笔记 |
| token 统计 | 顶栏实时显示会话累计用量，设置面板有历史图表 |
课堂演示的实际工作流通常是：模板或一句话出图 → 多轮微调 → 导出 .ggb 留档 + 截图进课件。AiGGB 支持安装为 PWA（Chrome / Edge 地址栏安装图标，iOS 走「添加到主屏幕」），安装后界面可离线打开，AI 调用仍需在线。
和本站结合：给每篇笔记配一幅动图
本站的高中数理笔记几乎每一课都有适合做成动图的对象。三条现成的提示词，直接对应站内文章：
对应《三角函数》：单位圆上点 P 逆时针匀速旋转，画出 P 的纵坐标随角度变化的
正弦曲线生成过程，角速度用滑块控制，留轨迹
对应《机械振动与机械波》：单摆 L = 1 m 初角 30 度，小角近似，摆球留轨迹，
右侧同步画摆角随时间的曲线，周期 T 自动播放
对应《抛体运动》：斜抛 v0 = 20 m/s 仰角 45 度，显示速度矢量分解与轨迹，
t 自动播放，可调仰角滑块 15 到 75 度观察射程变化生成后用「截图」把关键帧存下来贴进笔记，「导出 .ggb」的文件则留给课堂上的实时演示——静态图讲结构，动图讲过程，两者正好互补。
使用边界
- Key 安全第一：浏览器明文存储，公共环境不用、用完即清；
- 2D / 3D 切换即清空：动手前先想好这题是平面还是立体；
- 思考深度保持默认：实测开启「高」档在轻量模型上更慢且无质量收益，除非刻意做难题否则别开；
- 复杂构造交给 Agent：一句话出图用两阶段管线，多对象联动、需要中途调整的场景切 Agent 模式。
上手清单
- 装好即配：启动后第一件事是填 API Key 并「测试连接」，顺手把视觉模型也选上；
- 先模板后自由：不熟悉提示词语感时，从模板库卡片入手，观察它生成时用的措辞；
- 三要素自查：发送前问一遍——对象明确吗？参数给范围了吗？提动画了吗？
- 迭代优于重写：图不对就多轮修改（「改成红色虚线」「半径改成 5」），不必推倒重来；
- 重要结果随手导出：
.ggb留档、PNG 进笔记，会话有 30 个上限会被淘汰。
一句话收束：AiGGB 把「做教学动图」的成本从「会 GeoGebra 命令」降到「会把题意说清楚」——工具已经把排版、纠错、自检都自动化了，留给使用者的只剩一件事：像给学生讲题一样，把图描述出来。