GGB — GeoGebra 数学可视化

概述

根据用户自然语言描述，生成基于 GeoGebra API 的独立可交互 HTML 文件，浏览器直接打开即可使用，无需本地依赖。

---

工作流程

Step 1 — 解析用户意图

1. 分析用户的自然语言描述，理解可视化需求。
2. 识别：
   • 主图形类型（函数 / 参数曲线 / 几何 / 分布 / 动画滑动条）
   • 数学表达式或几何参数
   • 样式偏好（颜色、线宽、标签等）；若未指定，使用预设配色方案
   • 坐标范围；若未指定，按推断规则自动选择

Step 2 — 向用户确认细节

在继续执行前，必须向用户确认以下内容：

1. 生成内容确认：

   • 图形类型和数学表达式是否正确理解
   • 需要绘制的具体对象（函数曲线、几何图形、点、线等）
   • 是否需要特殊元素（滑动条、动画、标注等）

2. 设计风格确认：

   • 配色方案（使用默认蓝色系或用户指定颜色）
   • 线宽和线条样式偏好
   • 是否需要显示标签、坐标轴、网格
   • 画布尺寸和比例要求

3. 交互功能确认（如适用）：

   • 是否需要滑动条控制参数
   • 是否需要动态演示或动画效果

4. ⭐ 交互模式确认（重要新增）：

   • 选择生成界面的交互程度，决定用户能否在界面中操作和设置元素
   • 不同模式影响工具栏、右键菜单、属性设置等功能的可用性
   • 默认推荐"基础交互模式"，适合大多数教学演示场景

确认方式： 必须使用 AskUserQuestion 工具向用户展示确认对话框，格式如下：

{
  "questions": [
    {
      "question": "我已理解您的需求如下，请确认或选择需要调整的项目：",
      "header": "需求确认",
      "options": [
        {"label": "✅ 理解正确，开始生成", "description": "以上理解无误，立即进入生成步骤"},
        {"label": "❌ 需要调整", "description": "理解有偏差，需要在回复中说明修改意见"}
      ],
      "multiSelect": false
    },
    {
      "question": "设计风格偏好（可多选）：",
      "header": "设计风格",
      "options": [
        {"label": "使用默认蓝色系", "description": "采用技能预设的蓝色配色方案"},
        {"label": "自定义颜色", "description": "使用指定的颜色方案（请在回复中说明）"},
        {"label": "调整线宽/样式", "description": "需要特定的线条粗细或样式"},
        {"label": "隐藏标签/网格", "description": "不显示坐标轴标签或网格线"}
      ],
      "multiSelect": true
    },
    {
      "question": "⭐ 交互模式选择（决定用户能否在生成的界面中操作元素）：",
      "header": "交互模式",
      "options": [
        {"label": "🎯 基础交互（推荐）", "description": "可右键设置属性、使用工具栏、拖动元素，适合教学演示"},
        {"label": "📖 只读演示", "description": "完全禁止操作，仅用于展示最终效果（传统模式）"},
        {"label": "✏️ 完整编辑", "description": "开放所有功能，可自由编辑、修改和使用菜单"}
      ],
      "multiSelect": false
    }
  ]
}

重要约束：

• 必须等待用户在对话框中做出选择并确认后，才能进入 Step 3
• 如果用户选择"需要调整"，必须根据用户反馈修改理解后再重新确认
• 交互模式选择为必选项：必须在每次生成前明确用户的交互模式偏好
• 不得在未获得用户明确确认前直接开始生成 HTML 文件

---

Step 3 — 必读参考文件（每次必须执行）

在生成任何 GeoGebra 命令前，必须按顺序阅读以下参考文件：

1. references/rules.md — ⚠️ 强制优先阅读：GeoGebra 完整中文指令速查（472条指令），确保使用正确的中文指令名和语法格式，避免语法错误
2. references/troubles.md — 踩坑记录，避免已知 Bug 重现
3. references/style.md — 界面风格规范，确保交付风格统一
4. references/geogebra-api.md — API 方法速查与已知缺陷
5. references/nl-to-ggb.md — 自然语言→命令映射与视窗推断规则
6. references/validation-rules.md — ⚠️ 新增必读：验证与自动修复规则，了解哪些错误可被自动检测和修复

Step 4 — 构建 evalCommand 命令序列

4.1 ⭐ 根据交互模式确定初始化参数（重要新增）

必须根据 Step 2 用户选择的交互模式，设置对应的 GeoGebra 初始化参数：

关键差异说明：

• 基础交互模式（推荐）：启用右键菜单、样式工具栏、标签拖动，用户可自由设置元素属性
• 只读演示模式：所有交互功能禁用，仅用于展示（传统行为）
• 完整编辑模式：开放所有功能包括菜单栏，适合高级用户

4.2 构建绘图命令

1. 参照 references/geogebra-api.md 的命令语法和已知缺陷规避方案。
2. 遵守以下约束：
   • 使用 evalCommand(str) 传入 GeoGebra 命令字符串
   • 3D 图形模式：正方体、棱柱、球面等 3D 对象必须使用 appName: "3d"，使用 "classic" 会导致无法显示
   • 椭圆：必须用焦点+圆上一点形式 Ellipse(f1, f2, p)，禁止 Ellipse(center, rx, ry)
   • Curve 对象：不调用 setLabelVisible（无效），改用 setCaption
   • 尺寸稳定：所有 API 调用放在 appletOnLoad 回调的 setTimeout(..., 100) 内
   • 坐标轴比例优先原则（⚠️ 重要）：
     • 优先使用 api.evalCommand("SetAxesRatio(1,1)") 保证 x:y 坐标轴比例为 1:1
     • 当需要保持坐标轴比例时，不强制设置固定坐标范围（不调用 setCoordSystem），让 GeoGebra 自动计算合适的视窗
     • 画布尺寸保持用户指定或默认的宽屏比例（如 1600×600），不强制 1:1 画布宽高比
   • 坐标轴比例设置约束：SetAxesRatio(1,1) 和 setCoordSystem() 不能同时使用！
     • 如需 1:1 比例：只使用 SetAxesRatio，禁止调用 setCoordSystem
     • 如需固定范围：使用 setCoordSystem，但接受比例可能不是 1:1
   • SetAxesRatio 强制使用与保护（⚠️ 最高优先级）：
     • 当需要保持坐标轴比例 1:1 时，必须且只能使用 api.evalCommand("SetAxesRatio(1,1)")
     • 该命令不受 evalCommand 返回值影响（即使返回 false 也视为成功）
     • 禁止在静态校验、运行时验证、或修复循环中删除/修改 SetAxesRatio 命令
     • 禁止用其他方法（如 setCoordSystem、setScale 等）替代 SetAxesRatio 来实现 1:1 比例
     • 如需固定坐标范围 + 1:1 比例：先调用 SetAxesRatio(1,1)，再让 GeoGebra 自动计算视窗（不调用 setCoordSystem）
3. 为每个对象按需设置颜色、线宽、标签（默认显示标签和值）。

Step 5 — 生成 HTML 文件

⚠️ 关键约束：必须生成全新的独立 HTML 文件，禁止直接修改 assets/ggb-template.html 模板！

1. 读取 assets/ggb-template.html 内容作为基础模板。

2. 基于模板创建新文件，严格按照 references/style.md 的规范填写样式、配色、线宽和标签。

3. 填写模板占位符：

   • <!--TITLE-->：题目（中文，10字以内，居中）
   • <!--SUBTITLE-->：1-2行简要介绍（灰色小字，公式来源或图形特征）
   • <!--DESCRIPTION-->：底部文字说明/求解过程（若无需说明则删除整个 section）
   • setCoordSystem(...) 填写推断的坐标范围
   • // ── 在此插入绘图命令 ── 区块填写完整命令序列

4. 拷贝 deployggb.js：将 assets/deployggb.js 复制到输出目录（与 HTML 文件同目录），命名为 deployggb.js。这是 CDN 加载失败时的本地回退保障。

5. CDN 与加载机制：模板已内置动态 CDN 容错加载（官方源优先，自动切换 → 本地回退）和 useBrowserForJS: true，无需手动配置。

6. 画布要求：

   • 宽度 100% 填满容器，无 max-width 限制
   • 高度自适应内容或根据场景灵活设置（不强制 1:1 比例）
   • 左右边距相等（已在模板中设置）

7. 输出路径与命名规则：

   • 必须保存到技能根目录：技能根目录（即与本 SKILL.md 同级的目录）
   • 文件命名格式：ggb-[简短描述]-[YYYYMMDD].html
   • 示例：ggb-sin-curve-20260504.html

8. 立即执行自检程序（强制）：

   • HTML 文件生成后，必须立即执行 scripts/validate_ggb.py 进行验证
   • 命令格式：

     python scripts/validate_ggb.py <生成的html文件路径>
     

   • 禁止跳过：无论时间紧迫与否，自检为强制步骤
   • 自检通过标准：
     • 脚本退出码为 0
     • errors 数组为空
     • 无白屏警告
   • 若自检失败，进入 Step 6.3 自动修复循环
   • 若发现未知错误类型（不在 troubles.md 和 validation-rules.md 中记录的错误），按 Step 6.3.4 要求记录错误经验

Step 6 — 三层防御验证（新增核心步骤）

在交付用户前，必须通过以下三层验证体系确保产物无错误。至多进行 3 轮修复循环。

6.1 第一层 — 静态校验（生成后立即执行）

在 HTML 写入磁盘前，对生成的代码进行规则匹配检查：

1. 括号/引号匹配：检查所有 evalCommand("...") 内的圆括号和双引号是否成对。
2. Bug 语法黑名单：扫描并自动修复以下已知错误（详见 references/validation-rules.md 第 1.3 节）：
   • Ellipse(center, rx, ry) 三参数形式 → 改为焦点形式
   • 对 Curve 对象调用 setLabelVisible → 改为 setCaption
   • 使用 api.setScale(...) → 改为 api.evalCommand("SetAxesRatio(1,1)")
   • 3D 对象使用 appName: "classic" → 改为 "3d"
3. 坐标轴比例冲突检测（重要）：检查是否同时存在 SetAxesRatio 和 setCoordSystem，如有则报错（详见 validation-rules.md 1.9）
4. 对象名冲突检测：检查是否有重复定义的对象名，自动重命名并同步更新后续引用。
5. 指令名合法性：核对指令名是否在 rules.md 的指令集中。
6. 模板占位符残留：确认 <!--TITLE-->、<!--SUBTITLE-->、<!--DESCRIPTION--> 已替换。

若静态校验发现问题，立即修复后重新校验，不计入 3 轮循环。

6.2 第二层 — 运行时验证（使用 validate_ggb.py 脚本）

使用专用验证脚本：scripts/validate_ggb.py

1. 运行验证脚本：

   cd <技能根目录> && python scripts/validate_ggb.py <html_file_path>
   

   示例：

   python scripts/validate_ggb.py ggb-linear-functions-20260513.html
   

2. 脚本自动执行以下检查：

   • 启动本地 HTTP 服务器（自动处理，无需手动启动）
   • 使用 Playwright 打开页面
   • 等待 window.__ggbValidation.status === 'completed'（最多 60 秒）
   • 读取 window.__ggbValidation.errors 数组，检查是否有命令失败或异常
   • 读取 window.__ggbValidation.commandResults，确认每条 evalCommand 的返回结果
   • 截图并保存为 <html文件名>-screenshot.png（临时文件，验证完成后自动删除）
   • 白屏检测（分析截图中心区域白色像素比例）

3. 验证通过标准：

   • 脚本退出码为 0
   • errors 数组为空
   • 无白屏警告
   • ggbLoaded 为 true

4. 查看结果与清理：

   • 控制台输出详细的验证报告（JSON 格式）
   • ⭐ 验证完成后自动删除截图文件，避免占用磁盘空间
   • 仅在验证失败且需要人工排查时保留截图

6.2.1 截图自动清理机制（⚠️ 重要）

强制要求：

• 验证脚本执行完毕后（无论成功或失败），必须删除生成的截图文件
• 删除时机：在 validate_ggb.py 脚本的 finally 块或主流程末尾执行
• 删除命令：

  import os
  screenshot_path = "<html文件名>-screenshot.png"
  if os.path.exists(screenshot_path):
      os.remove(screenshot_path)
      print(f"✓ 已清理临时截图: {screenshot_path}")
  

例外情况（仅以下情况保留截图）：

1. 用户明确要求保留截图用于调试
2. 验证失败且进入修复循环时（便于对比前后差异）
3. 脚本添加 --keep-screenshot 参数时

目的：

• 避免大量截图文件堆积占用磁盘空间
• 保持工作目录整洁
• 符合"生成即销毁"的临时文件管理原则

6.3 第三层 — 自动修复循环（至多 3 轮）

触发条件（满足任一即进入修复循环）：

1. Step 5.8 强制自检失败（脚本退出码非0或检测到错误）
2. Step 6.1 静态校验发现问题
3. 用户反馈有渲染问题

修复循环流程：

第 1 轮：分析错误日志 → 匹配 validation-rules.md 修复规则 → 修改命令 → 重新生成 HTML → 重新执行自检程序
第 2 轮：同上，增加模糊匹配修复（指令名纠错、表达式重构）
第 3 轮：同上，尝试简化命令序列（移除可疑命令、用最简表达式替代）

**修复优先级**：
1. 致命错误（JS 语法错误、所有命令失败）→ 优先修复
2. 命令失败（部分图形缺失）→ 次优先修复
3. 警告（不影响主功能）→ 记录但不阻断交付

#### 6.3.4 错误经验积累（核心机制）

**触发条件**：在自检或修复循环中发现**未知错误**（即 `troubles.md` 和 `validation-rules.md` 中未记录的错误类型）

**必须执行的操作**：

1. **记录到 troubles.md**：
   - 使用 troubles.md 中的格式模板
   - 追加到对应分类末尾
   - 在变更记录中登记

2. **如属于可自动修复的错误，同时更新 validation-rules.md**：
   - 在对应分类下新增规则
   - 填写完整的检测层、错误签名、自动修复策略
   - 提供修复前后示例

3. **更新 SKILL.md 变更记录**：
   - 在变更记录表中添加新条目
   - 简要描述新增的错误类型

**格式要求**：
- 严格按照参考文件中的格式模板填写
- 日期使用 YYYY-MM-DD 格式
- 分类标签保持一致

**目的**：形成"错误发现 → 自动修复 → 经验记录 → 下次避免"的闭环，确保技能持续进化。

#### 6.4 交付

**情况A — 验证通过或修复成功**：
1. 将验证通过的 HTML 文件路径告知用户。
2. 在回复中简要说明图像内容和可交互功能（如有滑动条）。
3. 若经过修复循环，简要说明进行了哪些自动修正。

**情况B — 3轮后仍失败**：
- 停止循环，向用户交付当前最优版本
- 附上错误说明与建议

### Step 7 — 启动预览服务（⭐ 新增核心步骤）

**在交付用户前，必须启动预览服务器让用户可以直接在浏览器中查看生成的可视化结果。**

#### 7.1 使用 preview_server.py 管理预览服务

**脚本位置**：`scripts/preview_server.py`

**核心命令**（选项A：自动重启模式）：

```bash
# 每次生成新文件后，使用 open 命令自动重启服务器并打开浏览器
python scripts/preview_server.py open <生成的html文件名>

示例：

# 生成文件 ggb-sin-curve-20260518.html 后执行：
cd e:\GGB
python .trae/skills/Geogebra-Generator/scripts/preview_server.py open ggb-sin-curve-20260518.html

执行流程：

1. 停止现有服务器（如果有）：避免端口冲突
2. 启动新服务器（后台运行，PID 保存在 .preview-server.pid）
3. 打开浏览器：自动在默认浏览器中打开 http://localhost:8080/<filename>
4. 返回结果：
   • 成功：输出 "✅ 已在默认浏览器中打开" 和 URL
   • 失败：输出错误信息（文件不存在、端口占用等）

7.2 其他管理命令（可选）

# 手动启动服务器
python scripts/preview_server.py start

# 停止服务器
python scripts/preview_server.py stop

# 查看状态
python scripts/preview_server.py status

# 重启服务器
python scripts/preview_server.py restart

7.3 使用 OpenPreview 工具（推荐）

当 preview_server.py open 执行成功后，必须调用 OpenPreview 工具向用户提供可点击的预览链接：

OpenPreview(
    command_id=<RunCommand 的 command_id>,
    preview_url="http://localhost:8080/ggb-xxx.html"
)

目的：

• 让用户可以在 Trae IDE 内直接点击链接打开预览
• 提供更好的用户体验
• 确保预览服务正常运行

7.4 ⭐ 关键约束（必须遵守）

1. 每次生成新 HTML 文件后必须执行 preview_server.py open
2. 禁止手动维护 HTTP 服务器进程：统一使用 preview_server.py 管理
3. 端口冲突处理：如果端口 8080 被占用，open 命令会自动尝试重启
4. 服务器生命周期：
   • 启动：每次 open 命令时自动启动/重启
   • 运行：后台持续运行，直到下次 open 或手动 stop
   • 停止：用户手动停止或系统关闭时自动终止
5. 与 validate_ggb.py 的关系：
   • validate_ggb.py 使用临时服务器（验证完成后自动终止）
   • preview_server.py 提供持久化预览服务（持续运行）
   • 两者互不干扰，validate_ggb.py 会检查端口并给出警告

7.5 故障排查

---

参考资源

---

配色规则

生成图形时必须严格遵循以下配色方案（完整定义见 references/style.md 第6节）：

快速参考：GeoGebra图形对象色（A类）

主色：蓝色系（5色，按优先级顺序使用）

补充色：灰色系

核心原则

• setColor() 仅使用上述A类颜色（蓝色系 + 灰色系）
• 页面UI装饰色（背景、文字、边框等）定义在 style.md 6.2 节，禁止用于图形对象
• 所有点的颜色统一使用 (100, 149, 237)
• 详细分类和完整颜色表 → 见 references/style.md

---

关键约束（勿违反）

• 禁止修改 assets/ggb-template.html 模板文件，必须基于模板生成新的独立HTML文件到技能根目录
• 使用 GeoGebra 官方CDN + 模板内置动态容错加载机制（禁止 bootcdn/cdnjs/jsdelivr 静态引用）
• 必须通过 HTTP 服务器预览（禁止 file:// 协议）
• useBrowserForJS 必须设为 true（规避 iframe 沙箱安全限制）
• 禁止使用 Ellipse(center, rx, ry) 三参数形式（GeoGebra 解析错误）
• 禁止对 Curve 对象调用 setLabelVisible（无效，改用 setCaption）
• 所有绘图 API 必须在 setTimeout(..., 100) 内执行
• 输出必须是完整可独立运行的 HTML 文件，不依赖本地脚本
• 每次生成后必须执行自检程序：使用 scripts/validate_ggb.py 验证 HTML 文件，确认无错误后方可交付用户
• ⭐ 每次生成后必须启动预览服务：使用 scripts/preview_server.py open <filename> 启动预览服务器并打开浏览器，确保用户可以直接查看生成的可视化结果

---

示例触发场景

用户：画一条正弦曲线
→ evalCommand("f(x) = sin(x)"), 视窗 [-2π,2π]×[-2,2]

用户：画椭圆，长轴 4，短轴 2
→ 计算焦距 c=√(16-4)=√12，evalCommand("Ellipse((-sqrt(12),0),(sqrt(12),0),(0,2))")

用户：帮我可视化心形线
→ evalCommand("Curve((1-cos(t))*cos(t),(1-cos(t))*sin(t),t,0,2π)")

用户：画带滑动条的 a·sin(bx) 函数
→ 先创建滑动条 a、b，再 evalCommand("f(x) = a * sin(b * x)")

---

变更记录