企业官网建设流程全解析

一句话看懂

项目地址：https://github.com/bherbruck/solidcraft

SolidCraft 是 Rust 实现的参数化 3D CAD 应用，桌面、浏览器和 MCP 服务器共享同一代码库。参数化特征时间线允许回溯编辑草图约束和实体特征，修改参数后自动触发增量重建。MCP 服务器通过 stdio 或网络端口提供 execute、measure、screenshot 等工具，AI 代理可发送 JSON 命令直接驱动建模流程。项目创建于 2026 年 10 月 7 日，当前 Star 1083，Fork 107，Open Issues 112，主语言 Rust 9518016 字节，Apache-2.0 许可证。

它解决什么问题

传统 CAD 软件绑定特定操作系统或需要商业许可证，脚本化接口各家实现不一。SolidCraft 提供统一 Rust 代码库跨平台运行，用户在不同平台获得相同的特征时间线和约束求解行为。MCP 服务器让 AI 代理通过工具调用发送命令，无需手动点击即可批量创建草图、添加约束、挤出实体并导出 STEP 文件。二进制 .solidcraft 和 JSON 格式同时支持，方便版本控制和脚本读写。

核心概念速览

参数化时间线：特征历史记录可回溯编辑并自动重建。timeline 记录每个草图和实体特征，用户可编辑、抑制、重命名、重排序或删除任意步骤，后续特征根据脏标记增量重建。

MCP 服务器：Model Context Protocol 让 AI 用工具调用建模。solidcraft-cli mcp 命令在 stdio 或指定端口提供 execute、measure、screenshot 等工具，Claude Code 等客户端调用 execute 工具发送 JSON 命令数组，服务器在无头模式或连接到已打开的 App 实例中执行。

B-rep 内核：边界表示实体几何内核用拓扑面、边、顶点描述实体。SolidCraft 使用 truck-modeling 和 truck-shapeops（Apache-2.0）实现边界表示和布尔运算，kernel/body.rs 定义 Solid 结构体封装 truck 的 Shell。

约束求解器：几何约束求解器计算满足尺寸关系的点位置。sketch 层混合两种方法，固定点用 loci 交点和刚性簇分解精确放置（exactly by construction），剩余自由度用 Levenberg–Marquardt 数值优化求解。

架构拆解

SolidCraft 采用分层架构，底层到顶层依次为 geom、sketch/kernel/render、doc、engine、ui-egui/mcp。

geom（L0 层）提供向量、平面、轮廓、网格数据结构及测量方法，不依赖 truck。

sketch、kernel、render（L1 层）：sketch 实现约束求解器，kernel 封装 truck B-rep 边界表示和布尔运算，render 提供视图变换和 CPU 光栅化（桌面用 wgpu GPU 加速，Web 用 WebGPU 或 WebGL2）。

doc（L2 层）管理参数表达式、特征时间线和增量评估。参数可引用其他参数（如width * 2），特征评估时 doc 检测脏标记，只重建受影响的后续特征。

engine（L4 层，L3 是 io 层处理 STEP/IGES 导入导出）注册所有命令定义和回调函数，实现 everything is a command 的会话管理。

ui-egui 和 mcp（L5 层）：ui-egui 用 egui 实现桌面和 Web 前端，工具栏和对话框发送 JSON 命令到 engine。mcp 实现 MCP 服务器，execute 工具接收 JSON 命令数组转发到 engine 执行。

数据流：ui-egui 工具栏 → engine 命令注册表 → doc timeline 评估 → kernel B-rep 布尔 → sketch 约束求解。MCP 服务器的 execute 工具直接注入 engine 命令队列，与 UI 操作共享执行路径。

关键实现走读

命令注册表定义

pub static COMMANDS: &[CommandSpec] = &[ CommandSpec::new("sketch.create", "Create Sketch", create_sketch) .at("SOLID", "CREATE") .icon("sketch") .params("plane: XY|XZ|YZ | construction plane name or id | {origin, x_dir, y_dir} | {face: [world x,y,z], body?: exact world body, index?: face index, path?: complete occurrence ids, fixed?: bool}; new face attachments require a unique certified source (a flat face of a sheet metal body attaches to its panel instead, in the flat pattern's coordinates), fixed:true explicitly freezes the selected plane; offset?: expr, project_edges?: bool, name?"), CommandSpec::new("sketch.edit", "Edit Sketch", edit_sketch).noundo().icon("sketch").params("sketch: id or name"), CommandSpec::new("sketch.finish", "Finish Sketch", finish_sketch).at("SKETCH", "FINISH SKETCH").icon("finish").enabled(in_sketch).noundo(),

静态数组定义 sketch 模块的三个命令规格。sketch.create 注册到 SOLID 模式的 CREATE 菜单，参数 DSL 描述 plane 可以是预定义平面、构造平面名称或 ID、显式原点和方向向量，或面选择对象。engine 注册表遍历 COMMANDS 数组构建路由表，参数 DSL 字符串在运行时解析为 JSON schema，UI 根据 schema 生成对话框。

草图容量限制和坐标范围校验

pub const MAX_POINTS: usize = 20_000; pub const MAX_CONSTRAINTS: usize = 40_000; pub const MAX_CURVES: usize = MAX_POINTS; pub(crate) const MAX_COORD: f64 = 1e9; pub(crate) fn in_range(p: Vec2) -> bool { p.is_finite() && p.x.abs() < MAX_COORD && p.y.abs() < MAX_COORD } pub(crate) fn in_range3(p: Vec3) -> bool { p.is_finite() && p.x.abs() < MAX_COORD && p.y.abs() < MAX_COORD && p.z.abs() < MAX_COORD } pub(crate) fn radius_in_range(r: f64) -> bool { r.is_finite() && r > 1e-9 && r < MAX_COORD }

定义草图点数量上限 20000、约束数量上限 40000，坐标绝对值必须小于 1e9 毫米（1000 千米），半径必须大于 1e-9 毫米且小于上限。in_range 函数先检查 is_finite（排除 NaN 和 Infinity），再检查绝对值范围。约束求解器用 Levenberg–Marquardt 数值优化，雅可比矩阵和海森矩阵计算对数值稳定性敏感，坐标过大或过小会导致浮点误差累积。

动手上手

安装编译

项目需要 Rust 工具链，克隆仓库并运行示例：

cargo run --release -p solidcraft -- --sample

查看 CLI 可用命令：

cargo run --release -p solidcraft-cli -- commands

运行持续集成测试套件：

cargo xtask ci

执行 75/76 参考件的体积面积计算并与 FreeCAD 预期值对比。

无头批量处理

从 JSON 命令列表生成 STEP 文件：

cargo run --release -p solidcraft-cli -- run examples/bracket.json --out bracket.step

渲染模型为 PNG：

cargo run --release -p solidcraft-cli -- snapshot examples/bracket.json --out bracket.png

启动 stdio MCP 服务器（供 Claude Code 等客户端调用）。启动 App 并监听 MCP 连接。

应用场景

AI 代理自动建模：配置 Claude Code 等 MCP 客户端，添加 solidcraft-cli mcp 作为 MCP 服务器。用户用自然语言描述需求（"创建一个 50x30x10mm 的支架，两端各打 6mm 孔"），AI 代理调用 execute 工具发送 sketch.create、line.create、dimension.distance、extrude.create、hole.create 等命令序列。solidcraft --control PORT 模式下 AI 可连接到已打开的 App 实例，用户实时看到模型构建过程。

无头批量测量导出：硬件外壳设计团队维护一批 JSON 脚本文件，每个脚本定义不同尺寸的变体。CI 流水线运行 solidcraft-cli run 批量生成 STEP 文件，用 solidcraft-cli eval 输出每个变体的体积、质心、表面积到 CSV，snapshot 命令渲染缩略图嵌入文档。

浏览器快速验证：销售或技术支持人员在客户现场无法安装桌面软件，访问 bherbruck.github.io/solidcraft/app 打开 Web 版本，URL 参数 ?sample 加载内置示例或从本地文件系统选择 .solidcraft 文件。WebGPU 或 WebGL2 渲染 3D 视图，修改参数后浏览器内完成增量重建和导出 STEP。

独立分析

约束求解器混合精确几何构造和数值优化是务实选择。固定点用 loci 交点和刚性簇分解 exactly by construction，避免数值法累积误差。剩余自由度用 Levenberg–Marquardt 求解，因为通用几何约束系统（距离、角度、相切）无法全部用解析公式表达。

truck 原版布尔运算库存在几何缺陷，SolidCraft 维护本地补丁。Cargo.toml 用 patch.crates-io 将 truck-shapeops 替换为 vendor/truck-shapeops，README 注释 "SolidCraft fixes"。这意味着上游 truck 库的某些边界情况会生成无效 B-rep 或崩溃，SolidCraft 团队修复后未及时合并到上游。

项目处于早期但简单件可用阶段。README Status 段落明确说明 "early but usable for simple parts"，75/76 参考件通过 oracle 对照测试（体积面积匹配 FreeCAD 计算值），但 Open Issues 112 表明用户报告的边界情况、UI 交互问题或高级特征缺失仍在修复中。

与 FreeCAD 的对比是测试策略，不是直接竞争定位。SolidCraft 用 FreeCAD 作为 oracle 计算参考件的预期体积面积，但两者实现语言（Rust vs C++/Python）、B-rep 内核（truck vs OpenCASCADE）、架构设计完全不同。SolidCraft 创建于 2026 年 10 月仅数月，目标是提供现代化的 Rust 生态和 MCP 自动化接口。

局限与风险

二进制文件未签名需要手动信任。Windows 会触发 SmartScreen 警告需点击 "Run anyway"，macOS 需要右键选择 "Open" 并确认。企业环境可能禁止运行未签名二进制文件。

Sketch 容量限制最多 20000 点 40000 约束，坐标绝对值小于 1e9 毫米（1000 千米）。建筑或大型装配（如火箭）可能超出坐标范围，半径下限 1e-9 毫米限制微纳尺度设计。

debug-assertions 编译选项关闭是为了绕过 truck 原版的过严检查。这意味着 SolidCraft 在 debug 模式下可能遇到 truck 的 assert 失败，release 模式下绕过检查但隐藏潜在几何错误。

Flatpak 沙箱不支持 3D 鼠标 hidraw 设备访问。Flatpak 版本因沙箱限制无法访问 /dev/hidraw，SpaceMouse 等 3D 输入设备不可用，用户需要 AppImage、Snap 或本地编译版本。

结论卡片

适合：Rust 生态 CAD 算法研究者可以直接阅读 crates/sketch 约束求解器和 crates/kernel B-rep 封装。简单机械件参数化设计（支架、外壳、夹具）已经可用，75/76 参考件通过测试说明基础功能稳定。需要 AI 或脚本自动化建模的团队可以用 MCP 接口让 Claude Code 等代理生成零件。

不适合：需要企业级稳定性和代码签名的生产环境，二进制未签名且 Open Issues 112 表明边界情况仍在修复。依赖 Autodesk Fusion 插件生态（CAM、仿真、渲染插件）的用户无法迁移。复杂曲面设计（汽车外观、人体工学产品）超出当前 B-rep 内核能力。

关注要点：监控 GitHub Issues 112 的关闭速度判断项目活跃度和问题修复节奏。试用无头 CLI 或浏览器版本验证特定工作流可行性，再决定是否安装桌面版。

项目地址：https://github.com/bherbruck/solidcraft