实战复盘：用cad-skill为Logitech MX Master 3打造3x3对角收纳盒

cad-skill 是一个基于 CadQuery 的 Claude Code 技能（skill），让你用自然语言描述想要打印的物体，AI 就会自动生成参数化建模脚本、导出 STL 并渲染预览图。这篇文章以真实案例复盘整个过程：如何用 cad-skill 为罗技 MX Master 3 鼠标制作一个3x3 规格的 Gridfinity 对角收纳盒——从 3D 扫描提取鼠标轮廓，到旋转 43.9° 塞进更小的格子里，再到拇指凹槽的倾斜坡道设计，全程无需打开任何 CAD 软件。

案例背景：为什么是"对角"放法

Gridfinity 是 42mm 格距的模块化抽屉收纳系统。MX Master 3 的机身长约 125mm，如果正着放，光长度就需要占用4x3的格位（4x42=168mm 跨度）。

但鼠标的外形是"两头尖、中间胖"的流线型。把轮廓旋转一个角度后，外接正方形的边长会显著变小。cad-skill 自带工具 outline_from_scan.py 通过--rotate-min-square参数暴力搜索 0°~180°（0.1° 步进），找到了43.9°这个最优角：旋转后外接正方形含间隙仅120.6mm，小于 3x3 格位可用宽度 123.1mm——于是 4x3 的格子直接省成了3x3，抽屉空间立刻省出一格。

上图是同款工作流的另一个成品（D110 标签打印机卡座），可见"扫描→轮廓→卡槽"这套流程对不同形状的物品都通用。

快速上手：安装 cad-skill

整个项目只依赖 Python 3.10–3.12（CadQuery 的 OCC 内核没有 3.13+ 的 wheel），五分钟装好：

mkdir -p ~/.claude/skills git clone https://gitcode.com/gh_mirrors/ca/cad-skill ~/.claude/skills/parametric-3d-printing python3.12 -m venv .venv && source .venv/bin/activate pip install -r ~/.claude/skills/parametric-3d-printing/requirements.txt

安装后在 Claude Code 里有两种触发方式：

• 自动触发：描述需求即可，提到 "3D print"、"STL"、"Gridfinity"、"enclosure" 等关键词时技能自动激活；
• 斜杠命令：输入/parametric-3d-printing直接调用。

之后 Claude 会按"基础外形 → 功能细节 → 最终打磨"三个阶段推进，每阶段都先渲染预览给你确认，而不是闷头做完才交差——这是 SKILL.md 里定义的核心协作流程。

核心管线：扫描 → 轮廓 → 对角卡槽

这个案例最能体现 cad-skill 特色的部分是scan-to-pocket（扫描到卡槽）管线，完整脚本见 examples/mx_master3_bin_3x3.py：

第一步：从 3D 扫描提取鼠标轮廓

鼠标轮廓不能靠量尺寸近似，因为流线型机身"最胖截面"才是卡槽真正要包裹的形状。流程是：

1. 取一份公开的 MX Master 3 3D 扫描模型（STL）；
2. 运行 outline_from_scan.py：PCA 对齐主轴 → 按真实尺寸--dims 128.2x88.4x50.8缩放 → 截取底部 19mm 内每毫米一个截面（正是 Gridfinity 卡槽包裹的区域）→ 布尔并集 → 简化成 52 个点的闭合轮廓。

其中--dims故意比官方尺寸放大了几个百分点（128.2mm vs 124.9mm），实测让鼠标在槽内每边有约 3mm 松弛，拿取更顺手。

第二步：旋转 43.9° 并重新居中

脚本拿到最优角度后，对 52 个轮廓点和拇指凹槽中心做同样的旋转变换，再按旋转后的包围盒重新居中——这样"旋转"这个操作在参数区只体现为一个angle_deg = 43.9的数字，轮廓重新生成后只需粘贴一次。

第三步：构建 Gridfinity 盒子

cad-skill 内置了经过打印验证的 gridfinity.py 模块，严格遵循 Gridfinity 规范（42mm 格距、41.5mm 盒脚、堆叠唇边、6x2mm 磁铁孔位），并提供参数校验——口袋太大、壁厚太薄、地板太浅都会抛出带具体信息的GridfinityError，而不是给你一份打印不出来的几何体：

bin = GridfinityBin(grid_x=3, grid_y=3, height_units=3, stacking_lip=True) bin.add_polygon_pocket(mouse_outline, clearance=fit_clearance + easy_grab) bin.add_cylinder_pocket(diameter=22.0, center=well_center, tilt=35.0, round_bottom=True) result = bin.build()

三个关键参数值得注意：

拇指凹槽是细节亮点：鼠标尾部有一个突出的"拇指翼"，正着拔不出来。方案是让 22mm 的圆形凹槽倾斜 35° 靠在翼下方——拇指顺着半球坡面一勾，就能把鼠标整个顶出卡槽。

验证与交付：预览-分析-迭代循环

每完成一个阶段，cad-skill 都会运行 run_cadquery_model.py 一条龙：

python3 run_cadquery_model.py model.py --preview --strict

它执行脚本、找到输出的 STL、调用 preview.py 渲染六视角预览，并以 JSON 返回success、stderr、watertight等字段——失败时 Claude 直接读stderr自我修正，形成闭环。--strict会把"非水密网格"当作硬错误：本案例最终 STL 共 20,318 个三角面，通过水密性检查。

预览图页脚还自动标注了包围盒（125.5 x 125.5 x 25.5mm）、体积和 PLA 重量估算（约 236g），对照 design-review.md 里的检查清单做最后的可打印性审查。

打印设置与参数微调

最终交付时 cad-skill 会给出针对该模型的简短切片建议（不重复切片器已有的默认值）：

打印设置：PLA、0.2mm 层高、立式打印（底部贴床）、无需支撑、15% 填充即可。原因：模型为敞口浅盒，无超过 45° 的悬垂；对角接触点处壁厚约 1.2mm，是抽屉盒可接受的下限。

如果想自己微调，examples/mx_master3_bin_3x3.py 顶部 PARAMETERS 区就是全部入口：

fit_clearance = 0.3 # mm - 每边装配间隙 easy_grab = 1.0 # mm - 额外拿取余量 angle_deg = 43.9 # 最小外接正方形的旋转角 well_d = 22.0 # mm - 拇指凹槽直径 well_tilt = 35.0 # 凹槽倾斜角（度）

改完重跑一次脚本，新的 STL 和预览图就都出来了——这就是"参数化"的意义：改数字，而不是重画模型。

这套方法能复用到什么？

只要你的需求是"给一个真实物品做一个严丝合缝（或刚好松快）的卡座"，scan-to-pocket 管线都适用：

• 🖱️ 鼠标、键盘、游戏手柄等桌面设备
• 🖨️ 标签打印机、充电器底座（参考 examples/gridfinity_d110_bin.py）
• 🔌 线缆收纳：把线材盘成圈，扫描后提取环形截面

配合 stl_to_3mf.py 还能把 STL 直接转成 Bambu Studio / PrusaSlicer 的 3MF 格式，少一步手动导入。

小结

这次复盘展示了 cad-skill 的三个能力点：规范级模块（gridfinity.py 保证与标准底座/底板兼容）、数据驱动的轮廓（outline_from_scan.py 从真实扫描提取而非目测）、闭环验证（预览渲染 + 水密性检查 + JSON 化错误自动修复）。最终成果是一个 3x3 格位、对角卡槽带 35° 拇指坡道的 MX Master 3 收纳盒，全程没有打开过传统 CAD 软件。

下次想在抽屉里放点东西时，不妨先问一句："帮我用 Gridfinity 给 XX 做个收纳盒"——剩下的交给 cad-skill。