创建或修改 OpenSCAD 3D…

适用于用 OpenSCAD 建模、参数化定制、多角度视觉验证并导出 STL（如发布到 MakerWorld）的场景。

适用场景

解决思路

1. 如未安装 OpenSCAD，先执行 `brew install openscad` 安装。
2. 使用技能 `tools/` 目录中的脚本处理 OpenSCAD 模型。
3. 生成单张预览图：`./tools/preview.sh model.scad output.png [--camera=x,y,z,tx,ty,tz,dist] [--size=800x600]`。
4. 生成多角度预览（前、后、左、右、顶、等距）：`./tools/multi-preview.sh model.scad output_dir/`。
5. 导出 STL 供 3D 打印：`./tools/export-stl.sh model.scad output.stl [-D 'param=value']`。
6. 提取 OpenSCAD 文件中的可定制参数：`./tools/extract-params.sh model.scad`。
7. 检查语法错误和警告：`./tools/validate.sh model.scad`。
8. 创建或修改 OpenSCAD 模型后，始终进行视觉验证。
9. 写或编辑任何 OpenSCAD 文件后，用 `multi-preview.sh` 生成多角度预览。
10. 用 `read` 工具查看每张生成的预览图像。
11. 从多角度检查问题：前/后验证对称性、特征和比例；左/右检查深度和侧面轮廓；顶确保顶部特征正确；等距验证整体形状。
12. 如果预览看起来不对，修复代码并重新验证。
13. 视觉验证可捕捉语法验证无法检测的问题：反向法线或内外翻转几何体、错位特征或错误布尔运算、比例不符合预期设计、缺失或悬空几何体、Z-fighting 或重叠表面。
14. 绝不在没有从多角度视觉确认正确的情况下交付 OpenSCAD 模型。
15. 创建 OpenSCAD 模型时，把可定制参数写在文件顶部。
16. 参数注释格式：`// [min:max]` 数值范围；`// [min:step:max]` 带步长的数值范围；`// [opt1, opt2, opt3]` 下拉选项；`// Description text` 纯描述。
17. 在模型顶部写参数示例：`wall_thickness = 2; // [1:0.5:5] Wall thickness in mm`、`width = 50; // [20:100] Width in mm`、`height = 30; // [10:80] Height in mm`、`rounded = true; // Add rounded corners`，然后编写模型代码。
18. 在模型代码中使用参数化模块和布尔运算，例如先定义 `module main_shape()`，再用 `difference()` 等组合形状。
19. 校验模型：`./tools/validate.sh model.scad`。
20. 生成预览到 `./previews/` 并用 `read` 工具查看：`./tools/multi-preview.sh model.scad ./previews/`。
21. 导出默认参数 STL：`./tools/export-stl.sh model.scad output.stl`。
22. 导出带自定义参数的 STL：`./tools/export-stl.sh model.scad output.stl -D 'width=60' -D 'height=40'`。
23. 常用相机角度：Isometric 用 `--camera=0,0,0,45,0,45,200`；Front 用 `--camera=0,0,0,90,0,0,200`；Top 用 `--camera=0,0,0,0,0,0,200`；Right 用 `--camera=0,0,0,90,0,90,200`。
24. 相机参数格式为 `x,y,z,rotx,roty,rotz,distance`。
25. 为 MakerWorld 发布准备：通过 `export-stl.sh` 导出的 STL 文件、预览图像（至少一个好的等距视图）、可定制参数描述。
26. 考虑创建 `model.json` 元数据，包含 `name`、`description`、`parameters`、`tags` 等字段，例如：`{ "name": "Model Name", "description": "Description for MakerWorld", "parameters": [...], "tags": ["functional", "container", "organizer"] }`。
27. 完整工作流示例：1) 编写 `.scad` 模型；2) `./tools/validate.sh box.scad` 校验语法；3) `./tools/multi-preview.sh box.scad ./previews/` 生成多角度预览；4) 用 `read` 工具查看 `previews/box_front.png`、`previews/box_back.png`、`previews/box_left.png`、`previews/box_right.png`、`previews/box_top.png`、`previews/box_iso.png`，检查几何问题、错位或意外结果，有问题回到第 1 步修复；5) `./tools/extract-params.sh box.scad` 提取并检查参数；6) `./tools/export-stl.sh box.scad box.stl` 导出默认参数 STL；7) `./tools/export-stl.sh box.scad box_large.stl -D 'width=80' -D 'height=60'` 导出自定义参数 STL。
28. 永不跳过视觉验证步骤；许多问题（尺寸错误、布尔运算错误、反向几何）只有实际查看渲染模型才可见。
29. OpenSCAD 基本形状语法：`cube([x, y, z]);`、`sphere(r = radius);`、`cylinder(h = height, r = radius);`、`cylinder(h = height, r1 = bottom_r, r2 = top_r);`（圆锥）。
30. OpenSCAD 变换语法：`translate([x, y, z]) object();`、`rotate([rx, ry, rz]) object();`、`scale([sx, sy, sz]) object();`、`mirror([x, y, z]) object();`。
31. OpenSCAD 布尔运算语法：`union() { a(); b(); }` 合并；`difference() { a(); b(); }` 从 a 减去 b；`intersection() { a(); b(); }` 仅重叠部分。
32. OpenSCAD 高级语法：`linear_extrude(height) 2d_shape();`、`rotate_extrude() 2d_shape();`、`hull() { objects(); }` 凸包、`minkowski() { a(); b(); }` Minkowski 和（用于圆角）。
33. OpenSCAD 2D 形状语法：`circle(r = radius);`、`square([x, y]);`、`polygon(points = [[x1,y1], [x2,y2], ...]);`、`text("string", size = 10);`。

适用边界 · 注意事项

• 未安装 OpenSCAD 或无法执行 `brew install openscad` 时不适用。
• 无法运行 `tools/` 脚本或不需要 3D 打印/STL 导出时不适用。
• 目标环境不基于 OpenSCAD 或不支持多角度预览检查时不适用。