bherbruck/solidcraft · 上手攻略

  • 仓库：bherbruck/solidcraft
  • 链接：https://github.com/bherbruck/solidcraft
  • 分类：agent / app / trending
  • 作者：spark
  • 更新：2026-10-13

是什么

SolidCraft 是一款纯 Rust 编写的开源参数化 3D CAD 应用。它提供“草图 + 约束 + 参数 + 特征时间线”的建模体验：在 sketch 里画线 / 矩形 / 圆 / 圆弧 / 多边形 / 槽 / 椭圆 / 拟合 / 控制样条 / 二次曲线 / 文本 → 约束求解 → 特征（拉伸 / 旋转 / 扫描 / 放样 / 倒角 / 抽壳 / 拔模 / 孔 / 螺纹 / 阵列 / 镜像 / 分割 / 组合 / 移动 / 构造几何）→ 参数化重算。能跑在桌面 / Web / 自动化通过 MCP 三种形态。许可证 Apache-2.0。

解决什么问题

  • 想用国产 / 纯 Rust 的参数化建模器，避免 FreeCAD / OpenSCAD 各自的学习成本与生态割裂。
  • 需要AI Agent 直接建模：内置 MCP server（solidcraft-cli mcp）让 Agent 在 headless 模式或运行中的桌面 App 里建模、测量、检视。
  • 想改一个参数全模型重建：参数表达式（2 * width + 5 mm、angle / 2）、有序规则、特征抑制、按行材质 / 外观。
  • 想跨平台分发：Windows MSI / 便携 ZIP / macOS universal DMG / Linux AppImage & deb & .rpm & snap & aarch64 全覆盖；Web 端免安装直接试。

快速安装

Windows

  1. 下载安装包： - x64 MSI - ARM64 MSI - 32 位 MSI - 或 x64 便携 ZIP（无需安装，直接运行）
  2. ⚠️ 包尚未签名，SmartScreen 警告时点 “More info → Run anyway”。
  3. Windows 构建：cargo xwin build --release --target x86_64-pc-windows-msvc -p solidcraft。

macOS（Apple Silicon + Intel）

  1. 下载 solidcraft-macos-universal.dmg。
  2. ⚠️ 首次运行：右键 SolidCraft → Open（同样未签名）。
  3. 拖入 Applications。

Linux

# AppImage（最方便）
chmod +x solidcraft-linux-x86_64.AppImage
./solidcraft-linux-x86_64.AppImage

# 包管理器：Ubuntu / Debian / Mint
sudo dpkg -i solidcraft-linux-x86_64.deb

# Fedora / openSUSE
sudo rpm -i solidcraft-linux-x86_64.rpm

# Snap
sudo snap install solidcraft

# ARM64 设备同样有 AppImage / .deb / .rpm

Web（免安装）

直接打开 https://bherbruck.github.io/solidcraft/app/ 试用。

验证一致性

仓库自带 docs/oracle.md：76 个公开参考零件中有 75 个的体积、表面积、质心、包围盒与解析值或 FreeCAD 计算值一致，另一件为已知 bug。这些检查不等于完整的几何或工作流等价证明（作者原话）。

核心用法

文档结构（值得先翻）

  • docs/oracle.md：76 件公开 oracle 参考件几何一致性报告（75/76 一致）。
  • docs/features.md：按领域列出现有命令清单，必读，避免用还没实现的命令。
  • docs/face-attachments.md：解释新 face attachments 如何保留构造几何身份，以及缺源时显式的 plane repair workflow。
  • docs/step-import.md：STEP/IGES 导入作为 base feature 的细节与限制。
  • ROADMAP.md：状态机图、未来计划。
  • CONTRIBUTING.md：贡献指南（README 标注 “help is welcome”）。
  • docs/book/：SolidCraft book（用户指南 / 开发者指南 / 命令参考）的源文件。

Sketch 智能拾取细节

  • 曲线绘制与拾取会随缩放 / 显示倍率自适应，包括 Fit 下的小圆和 placed component 里的 sketch。
  • 显式闭合的 fit spline 与闭合 associative link 用 periodic C2 interpolation（参数化连续）。
  • 关联外凸 line-and-arc offset 在 inset 消耗 corner arcs 时仍保留身份；链接 extrusion 跟着当前边界走；打破关联则边界冻结、原 extrusion 仍可用。
  • 新 face attachment 保留支持的 construction identity + 选中的 occurrence；缺源时显式 plane repair workflow（不静默退化）。

草图到特征：典型工作流

  1. 在 origin plane / offset plane / 平面 face 上画 sketch。
  2. 加约束 + 维度；Levenberg–Marquardt 解剩余自由度（Jacobian 秩报剩余 DOF）；被约束过/被锁死的点按构造精确放置。
  3. 自动识别 profile（含内孔、分裂 region）；partial / ambiguous 边界被丢弃。
  4. 在参数化时间线上加 extrude / revolve / sweep / loft / fillet / chamfer / shell / draft / holes / threads / patterns / mirror / split / combine / move / construction。
  5. 编辑参数 → 全模型重算；草图与特征都可以重新排序、抑制、重命名、删除。
  6. 导出 STEP（AP243） 或 IGES 5.3 / 3MF / STL / OBJ。

装配 / 运动学（声明存在，注意早期状态）

  • Assemblies：嵌套组件 + occurrences、joints、motion studies、contact sets、干涉检查。
  • 保留建模历史与 world placement 的 body transfers。
  • 3D sketch 导线：编辑后仍保留其坐标系。
  • 材料感知的质量属性。

Sheet metal 关键细节

  • Flanges / hems / fold / unfold / refold、material cutouts、flat patterns、retained shallow prismatic pockets。
  • DXF 输出 exact line / arc / circle outlines + bend tables。
  • 塑料外壳特征与规则可启用。
  • Pocket depth 与 side 在 unfold/refold 中保留；与 through-hole 轮廓在 flat preview / DXF 中分开。

桌面 App 跑起来

# 用 sample 跑桌面应用
cargo run --release -p solidcraft-cli -- commands          # 命令注册表
cargo run --release -p solidcraft-cli -- run examples/bracket.json --out bracket.step
cargo run --release -p solidcraft-cli -- snapshot examples/bracket.json --out bracket.png
cargo run --release -p solidcraft -- part.step           # 把 STEP 当新设计打开
cargo run --release -p solidcraft-cli -- eval part.step   # 测量导入的 STEP

# 一键 CI：fmt + clippy + tests + assets + layers + wasm
cargo xtask ci

草图与求解器

  • 几何：直线、矩形、圆、圆弧、槽、椭圆、拟合 / 控制样条、二次曲线、文本；构造几何、投影、修剪、倒角和圆角（包括原点处的角）。
  • 约束：重合、点在曲线、水平 / 垂直、平行、垂直、相切、曲率（G2）、相等、同心、共线、中点、对称、固定。
  • 维度：线性、对齐、水平、垂直、点到线、半径、直径、角度、弧扫、弧长、槽长；由参数驱动。
  • 求解：作者自写求解器。被约束固定的点（locus 交点、刚性子簇分解，参考 Owen 1991 和 Fudos–Hoffmann 1997）按构造精确放置；其余用 Levenberg–Marquardt，Jacobian 秩报告剩余自由度。
  • 过约束编辑会被拒绝；完全约束的几何会变黑作为视觉信号。

参数与配置

unit-aware 表达式：2 * width + 5 mm
                angle / 2
参数：width, height, diameter, ...
配置：parameters + ordered rules
特征抑制：feature suppression
按行材质：per-row body materials / appearances

特征时间线

extrude / revolve / sweep / loft / fillet / chamfer / shell / draft / holes / threads / patterns / mirror / split / combine / move / construction。

  • 增量重建，特征可编辑、抑制、重命名、重新排序、删除。
  • 新旋转特征在反向轴上保留对称 + 双向角度放置；旧设计保留原有约定。

文件格式

  • 设计容器：.solidcraft，无损二进制 mesh payload；普通 JSON 仍支持 Open / Save As / Export。
  • 导入：STEP（AP203 / AP214 / AP242，支持 solids / assemblies / units / names / colours）；IGES（manifold solid B-rep，或 trimmed & bounded surfaces 缝合为 solids）；3MF / STL / OBJ（导入为 mesh body，能渲染可测可导出，solid feature 需要 B-rep body）。
  • 导出：STEP（AP242，含 body 名 / 颜色 / 组件为 assemblies；revolved faces 作为原生 planes / cylinders / cones / spheres / tori）；IGES 5.3；3MF；STL（binary / ASCII）；OBJ。
  • Mesh → Solid 重建：Convert Mesh 把支持的 closed constant-section parts 重建为含 plane 与圆柱面的参数化 solid。

MCP / Agent 自动化

solidcraft-cli mcp    # 启动 MCP server，让 AI Agent 建模、测量、检视

桌面端还提供 JSON-lines 控制通道，方便 Agent 与测试脚本驱动 UI。

3D 鼠标（SpaceNavigator / SpaceMouse）

  • 自动识别 3Dconnexion HID 接口；上下倾 / 旋转 / 平移 / 缩放。
  • 在 sketch 编辑时，cap 只平移和缩放，不动 sketch 视图。
  • Linux 直接读 /dev/hidrawN，普通用户需设备访问权限。udev 规则示例：
# /etc/udev/rules.d/70-3d-mouse.rules
SUBSYSTEM=="hidraw", ATTRS{idVendor}=="256f", TAG+="uaccess"

典型适用场景

  • 早期产品原型 / 教学：76 件参考件 / 75 件一致已足够演示参数化建模核心理念。
  • AI Agent 主导的 CAD 自动化：通过 solidcraft-cli mcp 让 LLM 驱动建模并测量。
  • 板级机械设计 / 简单零件：Pi 4 外壳类（README demo 中的 58 × 49 mm 安装孔矩形 + 阵列 + 拉伸 + 抽壳 + 倒角）。
  • 无重型 CAD 桌面环境：浏览器直接打开 Web 版本 试用。
  • 跨平台工具栈：Windows + macOS + Web + Linux ARM64 一次性覆盖。

坑与注意

  • ⚠️ 早期状态，作者原话 “early but usable for simple parts”：76 件参考件 75 件一致，剩下 1 件是已知 bug；命令覆盖度见 docs/features.md，路线图见 ROADMAP.md。
  • ⚠️ 下载包未签名：Windows SmartScreen、macOS Gatekeeper 首次运行都需手动放行（More info → Run anyway / 右键 Open）。
  • ⚠️ 3MF / STL / OBJ 导入为 mesh body：能渲染、可测、可平移、可导出，solid feature 需要 B-rep body——所以导入非 STEP/IGES 时建模能力受限。
  • ⚠️ partial / ambiguous 边界不进入自动 profile：作者明文写 “Partial or ambiguous boundaries do not qualify”。
  • ⚠️ breaking association 会冻结边界：原有 extrusion 仍可用，但不再随边界更新；样条 span 计数变化会影响完整自适应边界保留 outer / hole 源身份。
  • ⚠️ Sheet metal：pocket depth and side 在 unfold/refold 中保留，但与 through-hole 轮廓在 flat preview 与 DXF 中分开显示。
  • ⚠️ mature 度卡在 research：建议非关键场景试 5–10 件自己手测 oracle；不要把它当生产 CAD 主线。
  • ⚠️ CI 验证 vs 实操不等价：oracle.md 只覆盖几何量，不覆盖工作流或装配质量。

与同类对比

维度 solidcraft FreeCAD OpenSCAD Onshape / Fusion 360
纯 Rust 实现 ✅ ❌（C++ / Python） ❌（C++） ❌
参数化 + 约束求解 ✅ 自写 ✅ ❌ 编程式 ✅
AI Agent MCP 接入 ✅ 内置 部分（脚本） 部分（脚本） ❌
Web 端运行 ✅ ❌ ❌ ✅（受限）
全平台分发 ✅ Win / mac / Linux / Web ✅ ✅ ❌ 云端
STEP / IGES 全 round-trip ✅（含 import） ✅ 部分 ✅
生态 / 插件 早期 成熟 成熟 商业
开源 ✅ Apache-2.0 ✅ LGPL ✅ ❌

一句话推荐结论

如果你的需求是纯 Rust 参数化建模器 + 内置 MCP 让 AI Agent 直接建模 + 跨平台（含 ARM64 Linux）分发，bherbruck/solidcraft 是目前少见的选项；如果你要做复杂装配 / 钣金大批量生产，仍应优先 FreeCAD / Fusion 360 / Onshape 等成熟工具，等 SolidCraft 跑出更多 oracle 件再说。