内容
# OpenSCAD 代理插件 🚀
一款先进的插件，赋予 AI 编程代理（如 Antigravity、GitHub Copilot、Claude Code 和 AWS Kiro）使用 OpenSCAD 设计、 可视化和制造 3D 零件的能力。
## 关于 📖
该插件弥合了基于文本的参数化 3D 建模与现实世界制造之间的差距。标准 AI 代理在空间推理方面存在困难，无法真正“看到”他们生成的 3D 模型，而该插件提供了一个完整的 CAD 和部分 CAM 工具链。它允许代理：
1. 生成和迭代编辑 OpenSCAD 几何体。
2. 在聊天窗口内渲染视觉预览，以获得即时的几何反馈。
3. 检查组件之间的物理干涉和碰撞。
4. 提取结构化的物料清单（BOM），用于硬件采购。
5. 自动布局、嵌套和导出 2D 模板，用于激光切割或 CNC 路由。
6. 智能地将超大 3D 打印件分割成相互连接的段。
无论您是设计一个复杂的激光切割网络设备外壳，还是一个 3D 打印的可替换支架，该服务器都为 AI 助手提供了必要的工具，以作为您的自主工程副驾驶。
## 安装 🛠️
您可以通过 AI 代理的原生插件安装程序直接安装该插件：
```bash
# Antigravity
agy plugin install https://github.com/jmo808/OpenSCAD_Plugin.git
```
### 手动安装
如果您的代理不支持直接的 git 安装，我们提供了一个开箱即用的通用多代理安装程序。
1. 确保您已安装 `uv`（`pip install uv`）。
2. 克隆此存储库。
3. 运行安装脚本：
```bash
uv run python3 install.py
```
安装程序将自动检测并配置 MCP 服务器，适用于：
- **Antigravity** （CLI，IDE）
- **Claude Code** (`~/.claude.json`)
- **GitHub Copilot CLI** (`~/.config/github-copilot/mcp.json`)
- **AWS Kiro** (`~/.aws/kiro/mcp.json`)
## 工具和功能 🧰
服务器通过 MCP 暴露了 10 种不同的工具：
- `generate_scad`：编写和修改 OpenSCAD 源文件，并注入参数。
- `compile_and_preview`：渲染高质量的正交或透视预览（等轴测图、顶部、正面等）。
- `export_stl`：将验证的几何体转换为 3D 打印的 `.stl` 文件。
- `export_2d_templates`：将选定的组件展平到 Z=0 平面，并导出为 `.dxf` 或 `.svg`。
- `add_dimensions`：注入蓝图样式的扩展线和文本注释，用于 2D 工程图纸。
- `generate_multiview`：生成一个统一的 4 象限工程图纸（正面、右侧、顶部、等轴测图）。
- `check_interference`：运行 3D CSG 交集逻辑，以检测和突出显示零件之间的碰撞。
- `extract_bom`：将注释中的标记硬件解析为结构化的 JSON/CSV 物料清单。
- `nest_panels`：执行 2D 箱体包装，将零件布局到标准材料板上（例如 4x8 层压板），并考虑刀口宽度。
- `split_for_printing`：沿着最佳轴分割大型模型，并应用互锁接头（燕尾榫、法兰、销）。
## 嵌套算法限制 🧩
`nest_panels` 工具使用高度优化的 **First-Fit Decreasing (FFD) Shelf Packing** 算法。该方法计算每个 2D 形状的边界框，并将它们作为矩形进行打包。
由于这是纯 Python、无依赖的实现，它不执行真正的形状嵌套（需要计算代价高昂的 No-Fit-Polygon 几何引擎，通常用 C++ 编写，如 `libnest2d`）。因此，该工具无法自动将复杂的非矩形形状（例如 L 形或角度侧板）相互锁定到彼此的负空间中。
**如何进一步优化：**
1. `nest_panels` 工具生成一个完全可编辑的 `sheet_1_layout.scad` 文件。您可以简单地打开此文件，并手动编辑 `translate()` 和 `rotate()` 函数，以将零件推近到相互锁定的位置。
2. 该工具现在还导出单独的、隔离的 `.dxf` 配置文件，与生成的布局一起。对于大规模商业作业，您可以直接将这些个别的 DXF 文件拖放到免费的真正形状嵌套应用程序中，如 **Deepnest.io**。
## 示例对话 💬
以下是 AI 代理使用此 MCP 服务器迭代设计网络设备外壳的示例（注意：非常缩略的对话，实际设计需 ~ 40 次迭代）：
**用户：**
> 我想为我的网络设备设计一个外壳。我有这张原始的 AI 生成的概念图，我想让你以它为灵感：
>
> 
>
> 它需要一个顶部面板、一个底部面板和一些结构支架来连接它们。使其宽度为 250mm，深度为 150mm。渲染一个预览让我看看。
**代理：**
> 我将使用 `generate_scad` 编写初始布局，并使用 `compile_and_preview` 向您展示它是什么样子。
> *(代理调用 `generate_scad` 和 `compile_and_preview`)*
> 根据您的概念，这里是初始设计：
>
> 
**用户：**
> 看起来不错，但我认为侧支架与顶部面板发生碰撞。您可以运行一个干涉检查吗？
**代理：**
> 我将运行 `check_interference` 工具来验证是否有重叠。
> *(代理调用 `check_interference`)*
> 啊，您是对的。该工具发现 `top_panel` 和 `cleat_left` 之间有一个 3200mm³ 的交集体积。我将调整顶部面板的 Z 平移量，以添加一个 0.2mm 的公差间隙，并修复碰撞。
> *(代理调用 `generate_scad` 和 `compile_and_preview`)*
> 看起来怎么样？
>
> 
**用户：**
> 越来越接近。支撑块太大，我们还需要一些内部圆柱形支架，用于键盘 PCB/开关板 M2 安装螺丝。
**代理：**
> 了解，我将旋转显示面板 15 度，并在底部面板内添加 5mm 圆柱形支架。
> *(代理调用 `generate_scad` 和 `compile_and_preview`)*
>
> 
***... 30 次迭代后 ...***
**代理：**
> 我已经对后板应用了最终的尺寸调整，并确保所有公差都是正确的。这是具有正确间隙的最终固定版本：
>
> 
**用户：**
> 这是完美的！我想从一张 4x4 硬板上激光切割它。您可以为我打包零件吗？让我们提取 BOM。
**代理：**
> *(代理调用 `nest_panels`，使用 48x48 英寸 / 4x4 预设和 `extract_bom`)*
> 我已成功将所有 2D 平面面板打包到一张 4x4 硬板上，以优化材料利用率并导出 DXF。以下是布局：
>
> 
>
> 根据设计中的注释，我还导出了 `bom.csv`。您需要 **16x M3x12 内六角螺钉** 和 **3x M2x8 内六角螺钉** （用于中间支撑柱）来组装外壳。
---
*为 OpenSCAD 和 MCP 生态系统而建 ❤️*
