内容
# 3D 打印 CAD AI 框架
用于快速和可重复地设计可 3D 打印的参数化零件的框架，通过使用 AI、FreeCAD、Python 和 OrcaSlicer/BambuStudio。
## 项目栈
- **IDE:** VS Code + AI 代理（Claude Code / Codex / Antigravity）
- **CAD:** FreeCAD（v0.19+）
- **切片器（Slicer）：** BambuStudio（macOS 默认）/ OrcaSlicer（Linux 默认）
- **打印机:** 在 [`printer.yaml`](printer.yaml) 中可配置 — 默认 BambuLab P1S（FDM，256x256x256 mm 体积）
- **语言:** Python 3 + `trimesh`（用于网格验证）
### 可配置打印机
打印机的物理限制（打印体积、喷嘴、层高）在 [`printer.yaml`](printer.yaml) 中定义，在仓库根目录下。验证脚本（[`validate_mesh.py`](scripts/validate_mesh.py)）和零件模板（[`part_template.py`](templates/part_template.py)）通过 [`framework/printer.py`](framework/printer.py) 读取该配置文件。
要使用其他 FDM 打印机，只需编辑 `printer.yaml` 即可。请注意，`docs/` 目录下的文档（特别是 [`bambulab-p1s.md`](docs/bambulab-p1s.md)）是为默认打印机编写的；如果您使用其他打印机，请生成您自己的等效文档。
## 仓库结构
- [`docs/`](docs/)：参考文档和最佳实践。
- [`freecad-python-rules.md`](docs/freecad-python-rules.md)：Python 建模规则和拓扑命名预防。
- [`design-principles.md`](docs/design-principles.md)：FDM 功能设计原则。
- [`bambulab-p1s.md`](docs/bambulab-p1s.md)：默认打印机（BambuLab P1S）的物理参数和 FDM 可打印性。
- [`tolerances.md`](docs/tolerances.md)：装配公差（0.2 mm 至 0.5 mm）和孔收缩。
- [`design-review-checklist.md`](docs/design-review-checklist.md)：打印前检查清单。
- [`framework/`](framework/)：可重用 Python 库（几何、紧固件、导出）。
- [`templates/`](templates/)：新零件和元数据的可重用模板。
- [`examples/`](examples/)：参数化实用示例（盒子、带分隔的托盘、加强板、线束支架和卡扣）。
- [`scripts/`](scripts/)：自动化、验证和 MCP 服务器工具。
- `parts/`：框架设计的最终零件存储目录。
> **注意：** `output/` 目录（生成的 STL/STEP/FCStd 文件）**不被版本控制**。每个零件都可以通过运行其宏重新生成。
## 初始配置
### 1. Python 环境（网格验证）
```bash
python3 -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt
```
### 2. FreeCAD 和切片器
| 操作系统 | FreeCAD | 切片器 |
| :--- | :--- | :--- |
| **macOS** | 官方应用（`/Applications/FreeCAD.app`）；使用其内部二进制文件 `freecadcmd` | BambuStudio |
| **Linux** | 原生软件包（`freecadcmd` 在 PATH 中），Flatpak `org.freecad.FreeCAD` 或 `~/Applications/` 中的 AppImage | OrcaSlicer（PATH，Flatpak `io.github.softfever.OrcaSlicer` 或 `~/Applications/` 中的 AppImage） |
脚本 [`scripts/run_freecad_macro.py`](scripts/run_freecad_macro.py) 按此顺序自动检测这些安装。
### 环境变量
您可以通过环境变量强制使用可执行文件（允许带参数的命令）：
- `FREECAD_COMMAND`：FreeCAD 命令行接口（例如 `freecadcmd` 或 `flatpak run --command=freecadcmd org.freecad.FreeCAD`）。
- `SLICER_COMMAND`：切片器可执行文件命令或路径。
在 macOS 上使用 OrcaSlicer 代替 BambuStudio 的示例：
```bash
export SLICER_COMMAND="/Applications/OrcaSlicer.app/Contents/MacOS/OrcaSlicer"
```
## 框架使用指南
### 模式 1：无头自动执行（CLI 自动化）
如果您编写或修改了 FreeCAD Python 宏（例如，在 `examples/simple_box.py` 中），并希望生成 STEP/STL 文件并直接将其加载到切片器中：
1. 从终端运行自动化脚本：
```bash
./scripts/run_freecad_macro.py examples/simple_box.py --open
```
2. **幕后发生了什么？**
- FreeCAD 在后台运行（`freecadcmd`），仓库根目录在 `PYTHONPATH` 中（以便导入 `framework/`）。
- 处理宏并在 `examples/output/` 中导出 `simple_box.step` 和 `simple_box.stl`。
- 使用 `--open` 选项，切片器（`BambuStudio` 或 `OrcaSlicer`）将打开并加载 STL 文件。
3. 验证生成的网格是否物理上是流形的（manifold）并且符合打印机的尺寸限制：
```bash
.venv/bin/python3 scripts/validate_mesh.py examples/output/simple_box.stl --material PLA
```
### 模式 2：实时交互编辑（通过 MCP）
如果您希望在 VS Code 中编写或改进零件时与 FreeCAD GUI 进行交互，并获得实时 AI 辅助：
1. **步骤 1：在 FreeCAD 中启动 XML-RPC 服务器**
- 自动化选项（推荐）：运行一次 `python3 scripts/install_rpc_autostart.py`，之后每次打开 FreeCAD GUI 时，桥接器都会自动启动。
- 手动选项：打开 FreeCAD 的 Python 控制台（*视图 > 面板 > Python 控制台*），然后运行/加载脚本 [`freecad_rpc_server.py`](scripts/freecad_rpc_server.py)。
- 在这两种情况下，您都会看到一条消息，确认桥接器正在端口 `9875` 上监听。
2. **步骤 2：将 VS Code 连接到 MCP 服务器**
- 在您的客户端（VS Code、Claude Code 或 Claude Desktop）上配置 [`mcp_server.py`](scripts/mcp_server.py) 作为 MCP 服务器，使用您机器上的仓库绝对路径：
```json
"freecad-mcp": {
"command": "python3",
"args": ["<仓库路径>/scripts/mcp_server.py"]
}
```
3. **步骤 3：通过 AI 设计**
- 现在，您可以从 VS Code 聊天中要求 AI：*"创建一个 50x40 mm 的盒子，壁厚 2 mm"*。
- AI 将使用 `run_macro` 工具向 FreeCAD 发送指令，或使用 `run_macro_file` 重新执行仓库中的宏（关闭前面的文档，保持相机视角并返回几何摘要）。
- **您将看到零件实时在 FreeCAD 屏幕上绘制和交互。**
- 一旦满意，AI 就可以调用 `export_active_part` 和 `validate_stl_mesh` 来保存和认证打印模型。
4. **无需 AI 的替代方法：宏监视器（热重载）**
- 如果您更喜欢手动编辑宏并在保存时查看结果：
```bash
./scripts/watch_macro.py parts/<名称>/macro.py
```
- 每次保存宏（或 `framework/` 中的任何 `.py` 文件，或零件的 `params.yaml`）时，它将在 FreeCAD GUI 中重新执行，保持相机视角，终端显示每个对象的有效性、体积和边界框。
## 许可
© 2026 Alberto Pozo Esteban。本项目根据 [CC BY-NC 4.0](https://creativecommons.org/licenses/by-nc/4.0/deed.zh) 许可（参见 [LICENSE](LICENSE)）进行分发：您可以自由使用、修改和分享 **注明作者** 且 **非商业用途**。
