Community图像github.com

CAD 零件 (通过 CadQuery 子进程)

通过 CadQuery 设计物理 3D 零件,生成本地 .stl/.step 文件,并作为受看门狗监控的一次性子进程运行。适用于任何需要设计、建模、创建、调整尺寸、修剪或修改可打印零件的场景。

CAD 零件 (通过 CadQuery 子进程) 是什么?

该技能通过将 CadQuery 脚本作为受内存和时间限制的看门狗子进程执行,提供本地、可脚本化的 CAD 设计能力。它旨在设计物理 3D 零件,生成 STL/STEP 文件,并确保输出的可打印性,尤其适用于 FDM 3D 打印场景。其核心运行机制严格遵守一系列不可妥协的规则:强制使用一次性子进程,避免长期运行的 CAD 服务器导致内存耗尽;冻结已证明可行的零件文件,任何变体必须创建新文件;所有导出操作必须通过 `cq_helpers.export_checked` 进行,以确保网格的完整性和水密性;以及通过 `h.islands` 进行悬空部件检查,这是打印方向的关键检查。该技能支持 Claude Code,在 Windows 上的 `C:\cadquery-venv` Python 虚拟环境中运行。它明确定义了软件架构、脚本约定(如版本号步进为 0.1)、零件文件夹结构和链式编辑流程。通过强制性的预执行业务逻辑和全面的验证(包括尺寸报告、渲染比对和几何差异分析),它确保零件修改的可靠性,并防范常见陷阱,例如由非均匀缩放导致的 B-Rep 面失效或错误的帽高设置。

兼容平台✓Claude Code~Codex CLI~Cursor
npx skills add https://github.com/ColinE0/cad-parts/tree/HEAD/cad-parts

Installed? Explore more 图像 skills: steipete/songsee, affaan-m/frontend-design, mattpocock/improve-codebase-architecture · View all 6 →

在你喜欢的 AI 中提问

打开一个已预加载此 Agent Skill 的新对话。

文档

版权 2026 Colin Ezra Wilder。根据 Apache 许可证 2.0 版授权 (包含于本技能的 LICENSE 和 NOTICE 文件中)。

通过 CadQuery 子进程实现 CAD 零件

本地、可脚本化的 CAD:Python 脚本构建实体,受看门狗监控的子进程执行它,cq_helpers 控制导出,6 视图 PNG 验证形状。用户在 FDM 打印机上打印结果,因此这里的每个 STL 都必须能干净地切片。

不可妥协的规则

  1. 仅使用一次性子进程。 在 2026-07-14,一个长期运行的 CAD 服务器进程因跨调用累积导入模型而导致整个机器内存耗尽崩溃(2026-11-14 的重放首先澄清了非均匀缩放的问题;见注意事项)。子进程崩溃最多丢失一次运行;进程内操作崩溃则会拖垮整台机器。每次构建都通过 scripts/run_watchdogged.ps1 运行,其他虚拟环境脚本(绘图探测、网格检查)也是如此,无论是否使用 CadQuery。当 hooks/require_runner.py 被注册为 Claude Code 钩子(见 README)时,直接调用虚拟环境的 Python 会被拒绝,并提示应使用的 runner 命令:此拒绝是规则在起作用,而非需要绕过的错误。
  2. 绝不编辑已证明可行的零件文件。 其打印件已被测试且工作正常的脚本将被冻结。变体必须创建一个新文件(例如在 adapter_hex.py 旁边创建 adapter_hex_trim.py),并在文档字符串中准确说明更改内容和原因。每个脚本都包含一个 STATUS: 行(见脚本约定),以便将“已证明”的状态记录下来,而非仅凭记忆。
  3. 每次导出都必须通过 cq_helpers.export_checked。 仅凭 BRep isValid() 无法保证网格清洁;切片器会拒绝那些通过有效性检查但非水密的 STL 文件。此检查点已经捕获了一个已发布的不良零件。
  4. 每个将要打印的零件都必须在打印方向上进行悬空部件检查。 h.islands(solid, up="+z")(或计划的向上轴)会找到那些初始不接触打印平台、直到较高层才与主体连接的悬空材料,从而确保它们从始至终都由支撑结构支撑。高悬空部件是设计问题,必须修复或提交给用户决定,绝不能心存“支撑能搞定”的侥幸。在 2026-10-09,一个机器人的外壳轮拱支柱(在树状支撑上高 36.8 毫米,薄处 6.52 毫米)就是一个悬空部件,在通过所有配合检查后,在一个 22 小时的三色打印中途断裂。配合检查问的是“是否合适”;而此检查问的是“能否从下到上建造”。

工作流程

  1. 确认提示中未明确的部分。 一个完整的规格说明(“高 12 毫米,外径 9,孔径 4.3”)无需检查点。当需要做出负载相关的选择时(哪些孔,"15 mm proud"是从哪里测量的,上面安装什么,使用哪种硬件,存在哪个文件夹),请以简短建议的形式说明您的理解并询问用户。参考图片始终需要此检查点(见下文)。
  2. 编写脚本。 交付物零件:脚本应与其输出文件一起放在零件的文件夹中(脚本本身就是零件的记录;见“零件存放位置”)。探测与实验:放在 scratch 文件夹中。
  3. 运行脚本:
    & "$env:USERPROFILE\.claude\skills\cad-parts\scripts\run_watchdogged.ps1" -Script "C:\path\to\part.py" -Tail 40
    
    默认值:超时 300 秒,内存上限 4 GB,轮询间隔 500 毫秒,解释器为 C:\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,任务对象会连带终止构建:运行会丢失,但不会产生孤儿进程。
  4. 读取输出。 runner 会打印脚本的 stdout、stderr、实际用时以及进程树的峰值提交内存。必须出现 DONE 哨兵;没有此哨兵意味着运行未完成。返回码 137 = 看门狗终止(最后一行说明是超时还是达到上限);返回码 3 = 看门狗无法就绪(或解释器缺失),因此脚本从未运行。<script>.out.txt 是构建的运行日志(README 会引用它);<script>.err.txt 仅在 stderr 有内容时才存在。 发生上限终止时,在调整任何限制之前要先排查问题(注意事项:“排查上限终止”)。
  5. 在报告前进行验证。 查看 render6 PNG 并核对轮廓是否与意图一致。根据脚本打印的 bbox/体积报告尺寸,而非凭记忆。通过测量构建的实体来检查每个特征(describe、面 bbox、穿过墙体的切片剖面);一个将输入常量与自身比较的断言证明不了什么。然后按照零件的打印方向运行 h.islands(不可妥协的规则 4),并报告其与零件一起标记的内容。
  6. 记录。 更新文件夹的 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

……[翻译时截断]

相关技能