SolidCraft命令引擎设计解析：如何把每一个界面操作变成可脚本化命令

SolidCraft 是一个用纯 Rust 编写的开源参数化 3D CAD 软件。它的核心设计很克制：每一个你点得着的界面操作，本质上都是一条命令。同一个命令注册表同时驱动桌面界面、命令面板、CLI 脚本、本地控制通道，以及给 AI Agent 用的 MCP 接口——画草图、拉伸、倒圆角、改参数，全都可以通过一行 JSON 命令复现。本文带你拆解 SolidCraft 命令引擎的设计思路：一条命令长什么样、如何被安全执行，以及为什么这套架构让"界面操作 = 脚本操作 = AI 操作"成为可能。

一条命令的"身份证"：统一的注册表

打开命令注册表源码 crates/engine/src/cmd/mod.rs，你会看到每个命令都由一个CommandSpec结构体描述：

• id：稳定的点分小写标识，如solid.extrude、sketch.create、timeline.rollback
• label：界面显示名称（如 "Extrude"）
• tab / panel：命令在工具栏的位置（SOLID → CREATE 之类的分区）
• icon / shortcut：图标与快捷键
• params：一行参数文档
• enabled：当前状态下命令是否可用（及不可用原因）
• run：真正执行动作的函数，入参是 JSON 参数，出参是 JSON 结果

这种设计的巧妙之处在于：工具栏不是"画出来"的，而是从注册表"生成"的。新增一个功能 = 新增一条注册表条目，界面、搜索、脚本、AI 四个渠道自动同步。注册表按工具栏顺序汇总在 command_specs()，按 id 查找则走 find_command()（大小写不敏感）。

命令 id 的命名遵循域.动作的规范，覆盖了建模的全部领域：

执行管线：四条"保命"规则

命令不是拿来就执行的。入口函数 Session::execute 为每条命令建立了一套完整的安全管线，这也是"界面点击"和"脚本调用"能共享同一套代码的关键：

1. 执行前检查状态。enabled谓词先确认当前会话允许该操作（比如草图命令要求"已进入草图编辑"），不满足时返回明确的可读错误，而不是静默失败。
2. 先拍快照，失败即回滚。执行前对文档做一份Snapshot；命令失败或中途 panic 时，文档原样恢复——源码注释说得很直白："a failing or panicking command leaves it unchanged"。
3. undo/redo 自动纳入管线。可撤销命令在文档发生变化后自动压入 undo 栈，脚本和 AI 跑 20 步建模，人照样能一步一步撤销。
4. 崩溃日志（crash journal）。桌面应用会记录最近 32 条命令；万一崩溃，报告里自带"触发命令 + 设计文件 + 重放脚本"，可用solidcraft-cli crashes replay <id>一键复现（见 docs/crash-reports.md 与 crates/engine/src/crash.rs）。

此外还有一个隐藏福利：命令支持live: true帧模式（拖拽草图时每帧只重解草图、暂不评估整模型），交互手势既流畅，手势结束又会自动补全模型——交互体验与脚本正确性两不误。

四个入口，一条命令

这是 SolidCraft 命令引擎最出彩的部分：所有入口最终都汇聚到同一个Session::execute。

1️⃣ 桌面界面：点按钮 = 执行命令

工具栏按钮、菜单项触发的就是run函数本身。更有趣的是底部的命令行/命令面板（crates/ui-egui/src/palette.rs）：任意位置按 S，输入Extrude {"distance": 20}这样的"命令 id + JSON 参数"直接执行；输入模糊关键词则搜索命令名。界面操作者同时也是命令的"手写者"。

2️⃣ CLI：脚本化与自动化

solidcraft-cli 提供run（回放 JSON 命令脚本）、exec（对空设计执行单条命令）、commands（打印完整命令注册表）等子命令。一个脚本就是一个 JSON 数组，每项形如{"command": "sketch.create", "params": {"plane": "XY"}}，Session::run_script 逐条执行并在首个错误处停下。

3️⃣ 控制通道：外部程序"开"你的 CAD

solidcraft --control PORT让本地程序通过 JSON-lines 调用engine.execute/engine.script/ui.click等方法，详见 docs/control-protocol.md。官方演示 examples/demo/enclosure_steps.json 就是这样一步步"点"出了一整个电子外壳：

{"command": "sketch.create", "params": {"plane": "XY", "name": "Outline"}} {"command": "sketch.rectangle.center", "params": {"center": [0,0], "corner": [40,30]}} {"command": "solid.extrude", "params": {"distance": 20}}

4️⃣ MCP：AI Agent 建模

solidcraft-cli mcp 把命令引擎包装成标准 MCP 工具：list_commands列出带参数文档的完整命令目录，execute执行单条命令，batch批量执行并在出错时整体回滚（依赖引擎的 checkpoint 机制，见 Session::checkpoint），外加inspect_design、measure、export等检查工具。AI 建模时遇到报错，错误信息本身（"unknown commandsolid.estrude"、"solid.filletis not available right now: …"，见 EngineError）就是可直接自我纠正的文本。更多细节见 docs/mcp.md。

质量保障：命令引擎如何被"烤"得足够硬

既然一切操作都能脚本化，SolidCraft 就用脚本来测试自己：

• Oracle 参考测试：tests/oracle/ 下 80 个零件各配一份recipe.json（纯命令配方），CLI 重放后对比体积、面积、质心，甚至与独立内核 FreeCAD 的构建结果做 Hausdorff 距离对比（docs/oracle.md）。
• Action Matrix：对真实设计语料的每个面、边、顶点，用"桌面会发的同一组命令和参数"穷举普通操作，通过项记入 baseline.json 形成棘轮——今天过了明天失败就是回归（docs/action-matrix.md）。
• Fuzz：solidcraft-cli fuzz随机生成命令序列轰炸内核，挖掘边界崩溃。

也就是说，你在界面上"随手一点"的每个动作，都已经被成千上万次脚本化的自动化点过了。

小结：命令引擎设计带来的三个直接好处

1. 行为一致性——UI、脚本、AI 共享同一实现，"所见"与"所跑"永远一致；
2. 可自动化——从参数化批量改图到 AI 建模，都只是"命令数组"的不同来源；
3. 可恢复性——失败回滚 + 崩溃重放，让脚本化建模和手工建模一样安全。

如果你想亲手试试，可以从 crates/engine/src/cmd/ 挑一个感兴趣的命令看起（比如只有百余行的 sketch_create.rs），再跑一次solidcraft-cli commands看看完整注册表——你会对"命令即界面"这句话有非常具体的感受。