SolidCraft参数与表达式教程：用一条公式驱动整个模型自动重建

SolidCraft 是一款用纯 Rust 编写的开源参数化 3D CAD 软件，桌面端、浏览器与 MCP 自动化三种形态共用同一套内核。它的参数与表达式系统是整个建模体验的核心：改一个数值，时间线上所有相关特征自动重建，模型随之变化——这就是"一条公式驱动整个模型"的含义。本文面向新手，带你从零掌握这套系统。

先搞懂：模型参数 vs 用户参数

SolidCraft 中每一个尺寸和特征输入本身就是一个参数：草图标注的40、拉伸距离的10，自动编号为d1、d2……

你可以再手动添加用户参数，它由三部分组成：

用户参数的官方说明见 parameters.md，底层命令实现见 parameters.rs。

3 步搭建参数驱动的模型 🛠️

以最经典的"参数化底座"为例：一块由width、depth、height、hole_d四个参数驱动的板，板上一只居中圆孔。官方参考用例 recipe.json 完整演示了这种结构：

1. 添加用户参数：width = 60 mm、depth = 40 mm、height = 15 mm、hole_d = 10 mm
2. 把参数绑到几何上：草图中矩形两条边的尺寸标注分别填width和depth，圆孔直径标注填hole_d，拉伸距离填height
3. 改变参数，看模型重建：把width从 60 改成 80，矩形变宽、圆孔位置自动保持居中（因为孔的坐标公式是width / 2），整条时间线从第一个受影响特征开始增量重建

这里最关键的一步是第 2 步：尺寸标注的值可以填公式而不只是数字。孔心到原点的距离写width / 2、depth / 2，几何关系就被"公式锁死"了——板子怎么缩放，孔都始终居中。

表达式语法：单位感知 + 常用函数

SolidCraft 的表达式是单位感知的，这是新手最容易低估的能力：

• 2 * width + 5 mm：参数运算再叠加长度
• angle / 2：角度直接参与计算
• sqrt(area)：开根号、三角函数等数学函数
• 1 in + 3 mm：不同单位混合运算，自动换算

可用运算符为+ - * / ^和括号，函数包括sin cos tan asin acos atan atan2 sqrt abs min max floor ceil round mod trunc以及单位换算。

⚠️类型不匹配是报错，而不是静默转换：把长度填到期望角度的输入框，或反过来，会直接报错。这比"悄悄帮你换算"安全得多。

用 Change Parameters 对话框管理参数

在 SOLID 工具栏的 CONFIGURE 面板中点击Parameters打开参数编辑器，用户参数和模型参数（d1、d2…）集中管理：

• 快速连加：在名称/表达式/注释栏按Enter提交后，焦点自动回到名称栏，方便连续录入
• 表达式自动补全：输入时↑/↓选择建议，Enter/Tab接受，Escape关闭；补全项包括参数名、函数名、单位、常数（对应 expression_complete.rs）
• 重命名级联更新：改参数名时，所有引用它的表达式、尺寸标注、特征输入自动跟随
• 循环依赖可视化：a → b → a这类循环会连路径一起报出来，而不是给你一个莫名错误
• 受保护删除：被使用的参数删不掉，错误信息会列出所有使用它的地方

一条命令驱动重建：脚本与 CLI 自动化 🚀

SolidCraft 的一切操作都是带 JSON 参数的命令，因此"改参数→重建模型"也能完全脚本化。parameters.change命令同时支持桌面端、CLI 和 MCP：

{"command": "parameters.change", "params": {"name": "wall", "expression": "2 mm"}}

配合solidcraft-cli，一段脚本就能完成建模、改参、导出。官方测试语料中的塑料件示例 modern-plastic.json 先用parameters.change设定壁厚参数wall，再让solid.shell的厚度直接引用它——后续换材料规则改一个值即可。

参数驱动重建的自动化验证也有现成参考：UI 场景测试 s10_parameters_drive_model.json 中，把参数d1从 40 改为 55 后断言模型体积从 12000 精确变为 16500——公式驱动，结果可验证。

实用技巧与进阶功能

• 裸数字遵循设计单位：在 mm 设计中直接填2就是 2 mm，英寸设计里就是 2 in；想显式换算就写"1 in"
• 导出/导入参数：parameters.export/parameters.import支持 CSV 和 JSON，方便把参数表交给采购或工艺同事
• Configurations 多方案：配置表为每行保存一组参数值、被抑制的特征、材料与外观，用config.activate一键切换，适合做"同一设计、多个变体"（如不同厚度版本）
• 查依赖：parameters.users查看某个参数驱动了哪些特征，parameters.graph返回完整依赖图——大模型里改参前先看依赖，心里有数

常见问题速答

Q：公式报"长度不能当角度"？检查输入框的单位要求，在表达式里显式带上单位（30 deg），不要用裸数字跨类型。

Q：改参数后某个特征失败了？重建会列出失败的特征名称和原因；失败特征不会静默跳过，也不会产出残缺的导出文件。

Q：参数越来越多怎么整理？善用注释字段 + 收藏（parameters.favorite）；导出为 CSV 做台账，团队共享后再导入。

小结

SolidCraft 的参数与表达式系统让"改一个数、全模型自动重建"成为日常：用户参数绑定尺寸标注与特征输入，单位感知的公式负责维护几何关系，时间线增量重建保证效率，而parameters.change等命令让整套流程可以脚本化、可验证。上手路径很简单——先给关键尺寸起名字，再让位置关系也用公式表达，剩下的交给自动重建。更多细节可查阅官方指南 parameters.md 与 features.md。