版权 2026 Colin Ezra Wilder。根据 Apache 许可证 2.0 版授权 (包含于本技能的 LICENSE 和 NOTICE 文件中)。
通过 CadQuery 子进程实现 CAD 零件
本地、可脚本化的 CAD:Python 脚本构建实体,受看门狗监控的子进程执行它,cq_helpers 控制导出,6 视图 PNG 验证形状。用户在 FDM 打印机上打印结果,因此这里的每个 STL 都必须能干净地切片。
不可妥协的规则
- 仅使用一次性子进程。 在 2026-07-14,一个长期运行的 CAD 服务器进程因跨调用累积导入模型而导致整个机器内存耗尽崩溃(2026-11-14 的重放首先澄清了非均匀缩放的问题;见注意事项)。子进程崩溃最多丢失一次运行;进程内操作崩溃则会拖垮整台机器。每次构建都通过
scripts/run_watchdogged.ps1运行,其他虚拟环境脚本(绘图探测、网格检查)也是如此,无论是否使用 CadQuery。当hooks/require_runner.py被注册为 Claude Code 钩子(见 README)时,直接调用虚拟环境的 Python 会被拒绝,并提示应使用的 runner 命令:此拒绝是规则在起作用,而非需要绕过的错误。 - 绝不编辑已证明可行的零件文件。 其打印件已被测试且工作正常的脚本将被冻结。变体必须创建一个新文件(例如在
adapter_hex.py旁边创建adapter_hex_trim.py),并在文档字符串中准确说明更改内容和原因。每个脚本都包含一个STATUS:行(见脚本约定),以便将“已证明”的状态记录下来,而非仅凭记忆。 - 每次导出都必须通过
cq_helpers.export_checked。 仅凭 BRepisValid()无法保证网格清洁;切片器会拒绝那些通过有效性检查但非水密的 STL 文件。此检查点已经捕获了一个已发布的不良零件。 - 每个将要打印的零件都必须在打印方向上进行悬空部件检查。
h.islands(solid, up="+z")(或计划的向上轴)会找到那些初始不接触打印平台、直到较高层才与主体连接的悬空材料,从而确保它们从始至终都由支撑结构支撑。高悬空部件是设计问题,必须修复或提交给用户决定,绝不能心存“支撑能搞定”的侥幸。在 2026-10-09,一个机器人的外壳轮拱支柱(在树状支撑上高 36.8 毫米,薄处 6.52 毫米)就是一个悬空部件,在通过所有配合检查后,在一个 22 小时的三色打印中途断裂。配合检查问的是“是否合适”;而此检查问的是“能否从下到上建造”。
工作流程
- 确认提示中未明确的部分。 一个完整的规格说明(“高 12 毫米,外径 9,孔径 4.3”)无需检查点。当需要做出负载相关的选择时(哪些孔,"15 mm proud"是从哪里测量的,上面安装什么,使用哪种硬件,存在哪个文件夹),请以简短建议的形式说明您的理解并询问用户。参考图片始终需要此检查点(见下文)。
- 编写脚本。 交付物零件:脚本应与其输出文件一起放在零件的文件夹中(脚本本身就是零件的记录;见“零件存放位置”)。探测与实验:放在 scratch 文件夹中。
- 运行脚本:
默认值:超时 300 秒,内存上限 4 GB,轮询间隔 500 毫秒,解释器为& "$env:USERPROFILE\.claude\skills\cad-parts\scripts\run_watchdogged.ps1" -Script "C:\path\to\part.py" -Tail 40C:\cadquery-venv\Scripts\python.exe(可通过-Python <路径>或CADPARTS_PYTHON环境变量覆盖)。内存上限是整个进程树提交内存的限制,通过 Windows 任务对象在内核层面强制执行:超出上限的分配将被拒绝(脚本会看到MemoryError或 OCCT 分配失败),然后 runner 会终止整个进程树,返回码 137。仅导入 cadquery 就需要约 0.7 GB 提交内存,因此上限切勿低于约 1 GB。仅在已知有繁重任务时有意识地提高限制,切勿作为应对终止的第一反应;看门狗终止通常意味着几何错误(见注意事项),而非内存上限不足。-Tail N仅打印 stdout 的最后 N 行;完整日志始终保存在脚本旁的<script>.out.txt中。在日志冗长的脚本上使用此选项,可避免整个日志占据上下文。摘要行会报告实际用时:据此选择-TimeoutSec,而非凭空猜测。 通过 PowerShell 工具,将该工具自身的超时时间设置得高于-TimeoutSec。如果工具先终止了 runner,任务对象会连带终止构建:运行会丢失,但不会产生孤儿进程。 - 读取输出。 runner 会打印脚本的 stdout、stderr、实际用时以及进程树的峰值提交内存。必须出现
DONE哨兵;没有此哨兵意味着运行未完成。返回码 137 = 看门狗终止(最后一行说明是超时还是达到上限);返回码 3 = 看门狗无法就绪(或解释器缺失),因此脚本从未运行。<script>.out.txt是构建的运行日志(README 会引用它);<script>.err.txt仅在 stderr 有内容时才存在。 发生上限终止时,在调整任何限制之前要先排查问题(注意事项:“排查上限终止”)。 - 在报告前进行验证。 查看
render6PNG 并核对轮廓是否与意图一致。根据脚本打印的 bbox/体积报告尺寸,而非凭记忆。通过测量构建的实体来检查每个特征(describe、面 bbox、穿过墙体的切片剖面);一个将输入常量与自身比较的断言证明不了什么。然后按照零件的打印方向运行h.islands(不可妥协的规则 4),并报告其与零件一起标记的内容。 - 记录。 更新文件夹的 README(要打印哪个文件),设置 STATUS 行,并写下下次会话所需的任何经验教训(见“记录”)。
零件存放位置及零件文件夹内容
零件根目录:询问(如果这里仍然写着 ASK,请询问用户零件应存放在哪里,例如 C:\Users\<用户名>\Documents\cad-parts,并提供将其写入此处的选项)。每个零件在其根目录下有自己的文件夹;将相关零件分组在子文件夹中(机器人的底盘零件在一起,单独打印件在一起)。如果零件位置不明确,请询问;不要猜测。
一个零件文件夹包含:
- 脚本、STEP 文件和渲染图放在顶层;每个 STL 文件放入
stl/子文件夹(使用stl_dir="stl"导出)。在链式编辑文件夹中(见“链式编辑”),顶层只存放零件的 ONE 个活版本:如果顶层零件的stl/中有 STL 文件,那就是要打印的那个。他人交付的损坏 STL 文件放在顶层,绝不放入stl/,因为stl/意味着可打印。 README.md:零件是什么,演变轨迹(“在用:v12,最新:v16 试验”),以及明确的“要打印的文件”行。未经用户同意,不得将任何内容移至archived/。如果尚无 README:请创建一个。同系列不同尺寸而非不同版本(例如 11 毫米和 14 毫米的支撑柱)的,每个尺寸一行。archived/:已废弃的版本,每个版本或链步骤一个文件夹,包含其脚本、STEP、STL、渲染图和运行日志,以及归档根目录下的WHY-ARCHIVED.md。归档的链步骤不会在原位重新运行(其源路径假定为旧布局);请先将其复制回顶层。DEAD-*.md标记,用于识别绝不能再次使用的功能(例如CRUSH-RIBS-DEAD-DO-NOT-REBUILD.md:曾毁坏两个电机的挤压筋)。在修改零件前,请先阅读文件夹中的任何 DEAD 文件。- 打印计划(如果已编写),关联到一个 STL 文件名;当零件更新时,将其标记为过期。
<script>.out.txt,构建的运行日志。- 链式文件夹中的
current.json(下节说明)。
脚本约定
- 模块文档字符串:零件是什么、为什么存在、如何运行,以及
STATUS:行(当包含 Windows 路径时,请使用原始文档字符串r""":CPython 3.14 会警告\c、\s转义):STATUS: printed 2026-09-08, fitted, FROZEN或STATUS: trial, unprinted。FROZEN 是“不可妥协的规则 2”对“已证明”的定义;当打印结果返回时更新此行。 - 文档字符串包含当前版本的变更及其原因。演变历史和要打印的文件属于 README。请勿将先前版本的注释粘贴到新脚本中(有一个脚本这样做后达到了 50 KB)。
- 版本号以十分之一递增:版本化零件系列的每次新构建都是 +0.1,
v22->v22.1...v22.9->v23,除非用户指定,否则不得跳级。文件名中,点号以下划线表示(chassis_v22_1.py、.step、stl/..._v22_1.stl),因为后续脚本会将早期版本作为模块导入(import chassis_v12 as V12),而带点号的模块名无法被导入;文档字符串和 README 中使用“v22.1”。现有文件保留其编号。链步骤(step8、step11e)保留其自身方案,零件上刻印的任何版本号的唯一来源只能是用户自己的计数。 - 所有尺寸命名常量放在顶部,以毫米为单位,一个地方即可编辑。
import cq_helpers as h(安装在虚拟环境的 site-packages 中)。- 说明是哪一侧:每当写“左”或“右”时,请注明是机器人/零件自身的左侧(假设你是它,面向前方)还是观察者从其正面看的左侧。两者是相反的;在文档字符串、README 或消息中单独一个“左”字是缺陷。在任何多零件项目的顶部写明轴约定(哪个方向是前方、+x、向上)并保持一致。
- 断言
solid.isValid()并断言包围盒与预期尺寸匹配;同时也将公式作为断言进行保护(例如孔深必须超过轴突出部分),这样错误的参数编辑会在打印废品前失败并报错。 - 配合的硬件以实体建模,并通过
h.interference检查。尺寸来自数据手册或卡尺,并在每个常量的注释中注明是测量值还是假设值,以及数值来源。当没有更好的信息时,默认紧固件值:M3 内六角头 5.5 x 3.0,M3 通孔直径 D3.30,M2 自攻螺纹在 PLA 中的底孔直径 D1.7 至 1.8。其他标准紧固件:ISO 261 螺纹和 ISO 273 通孔,标记为假设值。 print(..., flush=True)用于进度;以print("DONE", flush=True)结尾。- 导出:
h.export_checked(solid, str(OUT / "part_name"), stl_dir="stl")然后h.render6(solid, str(OUT / "part_name.png"))。 - 每个导出文件对应一个零件;零件是单独打印的。
对导入 STEP 文件的链式编辑
许多零件是对导入的父级 STEP 文件进行的增量修改(一个基板通过九个此类增量达到了 step 10c)。规则:
- 将步骤命名为
step<N>,分支添加后缀字母(step7c),重新基线添加后缀r(step5r);文档字符串的 SRC 行指明父级文件。重新基线需要在文件夹中添加 WHY 注释。 - 链文件夹包含
current.json,指明当前有效的父级文件。当用户指定要打印的零件时,使用h.set_current(folder, "part.step", note="2026-09-22: ...")写入,或者在步骤脚本中,紧接在export_checked之后写入。README 中的“要打印的文件”行必须与current.json一致。 - 依赖项通过
plate = h.import_current(PLATE_DIR, pin="base_plate_step10c")导入父级,绝不使用硬编码的文件名。当链向前移动时,被固定的构建会失败,并同时显示两个零件的名称;针对新父级重新运行每个配合检查,然后移动固定点。如果 STEP 文件在未使用set_current的情况下被替换,指纹检查也会失败。(原因:依赖项曾因父级 STEP 文件消失而停止运行,并且有一个依赖项在固定于旧父级时通过了所有检查,而更新的父级才应该是要打印的零件。) - 证明增量:在前后使用
h.diff,并断言编辑框外的所有内容都未更改。 - 一个新的依赖零件(例如用螺栓固定在板上的支架)至少要断言:完全贴合(到配合面间隙为零,无重叠)、其孔轴线与父级上的一致、两个孔内均有足够的螺杆间隙、头部和工具操作空间充足(每个头部上方有一个内六角扳手所需的空间),并且它不能阻挡的任何父级特征仍然可用。从父级 B-rep 中读取其孔信息,通过轴方向过滤圆柱面,因为倒角也是一个圆柱面。
- 仅参数不同的脚本变体(14 毫米版本的 11 毫米支撑柱):通过两个脚本的文本差异来证明“没有其他更改”(仅文档字符串、NAME 和参数不同),以及对分析体积使用
describe()。无需几何差异探测工具。 - 非均匀缩放会将导入 B-rep 的每个面变为 B 样条曲面(注意事项):之后偏移操作可能失败。应重建,或缩放网格。
cq_helpers API(虚拟环境 site-packages)
export_checked(shape, basepath, stl=True, step=True, stl_dir=None, mesh=None, agree_tol=0.015):接受 Workplane 或 Shape;要求isValid();写入.step/.stl(当设置了stl_dir时,STL 写入<dir of basepath>/<stl_dir>/,此处始终为"stl");对 STL 进行 trimesh 水密 + 绕组检查,包含自动修复(merge_vertices精度先 5 后 4,fill_holes,fix_normals,仅当体积漂移 < 0.5% 时接受);然后 STL 必须与从磁盘读回的 STEP 一致(或当step=False时,与 shape 一致):每个方向的包围盒差值在max(0.05 mm, 零件最大尺寸的 0.5 %)以内,体积差值在agree_tol以内。返回 trimesh 网格。任何失败的检查都会引发h.GateError(AssertionError的子类,显式引发,因此python -O无法跳过它),从而停止运行。每写入一个文件,打印一行export ok:、完整路径及扩展名,以及一行export check:和一致性数值。 自动修复会在有效 B-rep 上闭合细微的三角剖分裂纹;它无法闭合缺失的面(见“修复用户交付的网格”部分)。STL 在副本上进行网格划分(shape 保持未网格化状态),因此任何先在 shape 上固定的网格都会被丢弃:使用mesh=(deflection, angular)固定网格(毫米绝对值,弧度;包含窄面的供应商零件需要(0.05, 0.2),见注意事项)。render6(shape, png_path, color="#b25563", tol=0.3):6 个标准着色视图(正面/背面/左/右/顶/前-3/4)到一个 PNG。使用深度缓冲的 VTK 离屏渲染(matplotlib 的画家排序会导致组件假透视,见注意事项),平行投影,每个视图框在零件上;如果是 Workplane,则渲染其栈上的每个 Shape;tol是三角剖分线性偏差(毫米),大组件用 0.6。render_compare(shape, ref_image_path, p
……[翻译时截断]