| name | geometry-assistant |
| description | Use when rendering high-school solid-geometry problem data into an interactive 3D standalone HTML artifact with known-condition highlights, step-by-step constructions, faces, polygons, line-plane angles, or dihedral angles. |
| version | 1.0.0 |
| allowed-tools | ["file_read","file_write","document_read","vision_analyze","exec_command"] |
| metadata | {"short-description":"立体几何 3D 单文件 HTML 可视化"} |
Geometry Assistant
技术方案
SINGLE_FILE_HTML_ONLY：本 Skill 只交付单文件 HTML。geometryData、样式和页面逻辑嵌入一个 .html 文件，用户不需要启动服务端；Three.js 与 addons 通过 jsDelivr CDN 加载，因此首次打开或浏览器未缓存依赖时需要联网。不要宣称完全离线或零外部依赖。
已淘汰的 localhost/--serve 方案只保留在 archive/legacy-localhost-preview.md 中作为历史记录，不属于当前工作流。遇到浏览器已经打开 localhost 页面时，不要沿用该页面判断结果；应重新生成 HTML 文件并让用户打开该文件。
标准流程
- 读取题目并完成数学分析；读取
references/data-format.md。
- 构建 geometryData JSON。
- 用
file_write 将临时 JSON 写入系统提示给出的当前 Agent 临时目录。
- 用
exec_command 运行内置 /skills/geometry-assistant/scripts/deploy.py，显式指定最终 HTML 输出路径。
- 运行
/skills/geometry-assistant/scripts/check_output.py 检查生成结果；Node 可用时增加 --node-check。
- 交付最终
.html 虚拟路径和 CDN 联网说明。不要启动本地服务器。
MindSpace 输入处理
- 用户直接粘贴题目：从对话提取题干、已知条件和问题。
- 图片、截图或扫描试卷：使用
vision_analyze 识别文字、顶点、线段、面、垂直/平行关系和图形标注；看不清时要求用户补充，不猜测。
- PDF、Word、Excel、PPT：使用
document_read 读取；需要理解内嵌图形时，用 document_read(intent="extract_images") 导出图片，再交给 vision_analyze。
- Markdown、TXT、JSON 等普通文本：使用
file_read。
先完成数学解题和 geometryData 设计，再渲染。不能为了让图形闭合而编造题目未给出的长度、角度、垂直、平行、圆或辅助点。
MindSpace 路径规则
最终 HTML 必须写入系统提示给出的当前 Agent 当日输出目录，例如：
/agents/{当前Agent英文名}/outputs/{真实日期}/立体几何-题目名称.html
临时文件写入系统提示给出的当前 Agent 当日临时目录，例如：
/tmp/{当前Agent英文名}/{真实日期}/geometry-data.json
/tmp/{当前Agent英文名}/{真实日期}/geometry-module.mjs
这些花括号只用于解释。实际调用时必须替换为系统提示中的真实 Agent 目录名和真实日期，不能原样写 {date}、YYYY-MM-DD 或“当天日期”。
/skills/geometry-assistant/ 是只读目录，只能读取脚本、模板和 references；不得把用户题目、临时 JSON、中间脚本或最终 HTML 写回 Skill 目录。
调用示例（实际使用时替换所有路径）：
exec_command({
"cmd": "python",
"args": [
"/skills/geometry-assistant/scripts/deploy.py",
"/tmp/当前Agent/真实日期/geometry-data.json",
"--output",
"/agents/当前Agent/outputs/真实日期/立体几何-题目名称.html"
],
"cwd": "/"
})
优先使用结构化 cmd、args、cwd。不要调用 bash、sh、execute，也不要通过 localhost 预览。
数据构建要点
- 坐标使用 pos: [x, z, y]，第三个坐标是竖直高度。
- 顶点 ID 用大写字母；边 ID 用两端点拼接，如 AB、PA。
- 面 ID 用顶点顺序拼接，如 ABC、PAB、PAM。
- conditions 只放题目直接给出的已知条件。
- 用户手动添加的标注不需要反向更新题目已知条件。
- 题目已知长度可用 valueText、displayValue、label 或 exactValue 提供精确显示，例如 2√2、sqrt(2)/2、3/4。
- 题干出现“圆 O”“圆心 O”“AB 是圆 O 的直径”等命名圆时，必须在 solids[].circles 声明圆，例如 { "id": "circle_O", "centerVertex": "O", "radiusVertex": "A" }，不能只画 OA/OB/OC 半径线。
- 真实几何边应根据视线遮挡动态切换实线/虚线；只有题面明确隐藏、辅助或构造的边才使用 dashed 或 renderMode: "auxiliary" 作为固定虚线。
高亮规则
- 选中的面、多边形、线面角、面面角，对应面或多边形必须高亮。
- 面高亮统一使用半透明柔和蓝色，避免橙色或强饱和色。
- solutionSteps[].highlights 可混用顶点、边、面 ID。
- 若步骤文字中提到已有 face ID，例如 PAM、PAC，也应纳入高亮，避免二面角说明中漏高亮两个面。
- length 和 equal-length 已知条件应在线段中点显示题目给出的精确长度标签；只限题目已知条件。
- 页面初始不自动高亮任何已知条件；点击已知条件右侧眼睛按钮时，才显示该条件对应的线段、面或标注。
解题展示边界
- 初始图只展示题面直接给出的结构。
- 辅助点、投影线、垂线、平面角、坐标轴等随 solutionSteps 逐步显示。
- 线面角、二面角、截面平面角等默认属于解题构造，不应放进全局 conditions，除非题面已明确给出对应辅助对象。
- 多问问题必须使用 parts 或 questionParts，并为每个 part 指定 stepIds 和 conditionIds。
- 每个 solutionSteps[] 必须提供 rules 数组列出本步骤使用的定理、性质、推论或公式；theorem 写证明、计算或构造过程，不能只写定理名。
坐标系规则
- 使用坐标法、法向量、平面方程、向量夹角公式或点到平面距离公式的步骤，必须同步显示 x/y/z 坐标轴。
- 坐标轴使用 renderMode: "axis" 和 auxiliary: true。
- 轴端点使用 axisEndpoint: true 和 label: ""，不要显示成普通几何点。
- x/y/z 坐标轴端点必须分别沿第 1/第 2/第 3 坐标正方向放置，避免 y 轴画反。
垂直与直角标记
- 题面已知条件出现垂直、直角或 90° 时，图上必须画 L 形直角标记。
- 这些标记属于已知条件注记，点击对应条件时显示，不要作为新推导塞进步骤。
运行后注意
- 生成的 HTML 不依赖本地 Node 服务端。
- 页面通过 importmap 加载 Three.js CDN，打开 HTML 时需要能访问
cdn.jsdelivr.net。
- 可在浏览器控制台调用 window.__debugVertices() 调试几何点。
依赖与失败处理
没有 exec_command 或命令权限
说明当前 Agent 需要在工具与权限中开启“执行命令”和“文件写入”。可以先保存 geometryData JSON，但不能声称 HTML 已生成。
Python 不可用
说明需要在“设置 > 环境检测”安装或修复 Python。不要自动运行 pip，不从 GitHub 安装；内置脚本不需要额外 Python 第三方包。
Node 不可用
Python validator 和 HTML 结构检查仍然必须通过。跳过增强的 node --check，并在交付说明中注明。Node 不是生成 HTML 的硬依赖。
CDN 不可用
HTML 仍可生成，但浏览器无法加载 3D 库。说明页面需要访问 cdn.jsdelivr.net，不要为此恢复 localhost 服务。
geometryData 校验失败
根据 validator 的具体错误修改 JSON 后重新生成。不能绕过 validator、删除校验规则或交付未通过校验的 HTML。
输出检查
生成后运行：
python /skills/geometry-assistant/scripts/check_output.py <最终HTML> --module-output <临时MJS> --node-check
检查内容：
- HTML 存在且非空；
- 已嵌入
window.__GEOMETRY_DATA__；
- 有 importmap 和 Three.js CDN；
- 没有活动的 localhost 依赖；
- 能提取 module script；
- Node 可用时 module script 通过语法检查。
创建成功后向用户返回最终 HTML 的虚拟路径。成果中心注册由系统运行结束后的产物扫描处理；不要操作数据库或伪造 artifact ID。
