cad

CAD 建模与检查

来源：由 earthtojake/text-to-cad 维护。 请使用当前接口对应的本地已安装技能文件。

从任务入手

只阅读请求所需的参考资料。

任务	首要操作	参考资料
创建或编辑零件或装配体	查找现有的 Python 模型，或创建下方带装饰器的模型；编辑源代码并运行 python <model>.py。	模型契约、形状构建；装配体请参阅定位
组织 CAD 项目	遵循现有布局；对于新的多模型项目，请使用 src/、格式化后的输出文件夹和模型目录。	项目布局、最简起步模板
导出 STL、3MF 或 GLB	添加网格装饰器以输出持续维护的文件，或运行该格式的 build INPUT.step OUT 命令进行一次性导出。	网格导出
根据提示词解析引用	找到已保存的 STEP/STP 文档，使用 read_scene 打开，并按下方所示调用 scene.resolve(ref)。	引用语法与检查
测量或检查几何体	使用原生 build123d 几何功能编写 Python 检查，并在适用时使用 cadgen.geometry。	检查与验证
根据图像或图纸建模	提取指定尺寸并记录有意义的假设。	解读需求
打开现有 STEP/STP、STL、3MF 或 GLB	向用户展示。	展示模型
检查外观或运动	对已保存的文档进行快照；使用已声明的运动学或动画来生成姿态和片段。	快照、运动学
诊断故障	阅读错误信息，并检查相关的模型、几何体或命令契约。	修复流程、版本迁移
消息提示需要迁移	立即执行迁移；未迁移的模型会在不提示的情况下丢失运动学、材质和动画。	版本迁移

对于 2D DXF 图纸，请使用 $dxf；此技能负责该图纸所投影的任何 3D 零件。 对于 URDF、SRDF 或 SDF，请使用相应的机器人描述技能。

设置与路径

通过 uv 运行 cadgen，这样此技能的命令便会与 CAD 应用的服务端共用一套安装及其预热后的构建守护进程：

• 下文中的 cadgen 指 uvx --no-config --managed-python --python 3.13 --from cadgen==0.7.26 cadgen
• 下文中的 python 指 uvx --no-config --managed-python --python 3.13 --from cadgen==0.7.26 python

首次运行时会下载该安装包，首次创建快照时会下载其无头浏览器；之后的运行会重复使用这两者。

cadgen doctor <skill-dir> 会报告当前使用的安装，并检查它是否为此技能固定的版本，以及 CAD 内核能否加载；遇到安装或内核加载错误时请使用该命令。使用相关子命令的 --help 查看其他标志。

请从 CAD 项目根目录运行项目命令。CLI 的输入/输出路径以及 read_scene/read_step 的路径均相对于工作目录；装饰器的 out= 路径则相对于模型脚本。如果模型需要从任意目录运行，请使用 __file__ 来定位文件输入。

创建或编辑模型

模型是一个普通的 Python 脚本，其中包含一个无参数的装饰函数，该函数返回一个 build123d 形状。每个入口点使用一个模型，脚本与其声明的输出共用相同的文件名主干。例如，src/bracket.py：

from cadgen import build123d as bd
from cadgen import step

WIDTH = 40.0


@step(out="../STEP/bracket.step")
def bracket():
    body = bd.Box(WIDTH, 20, 6)
    body.label = "bracket"
    return body


if __name__ == "__main__":
    bracket()

python src/bracket.py

• 如果模型源文件已存在，请先编辑，再运行以重新生成输出。文档导出和快照命令使用已保存的文件，不会运行源文件。
• 明确写出有意义的尺寸。使用毫米和 XY/+Z，除非任务或项目另有约定；选择实用的功能基准。对于实体零件，优先使用闭合且体积为正的实体，同时遵循对曲面或构造几何的要求。
• 将参数化几何放在普通工厂函数中；装饰模型用于选择配置。保持模块主体开销低：在模型或其辅助函数中创建几何并读取 CAD 输入。使用上方的惰性 bd 导入；注解中提及 bd 类型时，使用延迟注解。
• 在装配模型中调用子模型。使用 .moved() 或 Location * shape 放置其结果，以保留共享几何。使用有意义的实例标签和源文件中定义的放置方式。重新运行父装配，以纳入子模型的更改。
• 使用 cadgen.read_step 读取供应商提供的 STEP 输入。构建过程中打开的每个文件都是独立输入，无论使用什么方式读取（json.load、np.load、bd.import_step、项目字体）：这些都不会被声明。切勿将模型自身的输出作为输入读取。几何不得依赖未跟踪的时间、随机值、环境变量或工作目录。
• 需要指定可购买的零件时，先搜索 $step-parts，再制作占位件。记录未找到结果的搜索情况以及任何占位件假设。

对于不熟悉的尺寸或接口，请记录建模和验证所需的假设。如果缺失的信息会实质性影响所需结果，请进行询问。检查和导出请求不需要建模说明。

网格导出

在模型上叠加 @stl、@threemf 或 @glb，以声明每次运行都应维护的输出。模型可以只声明网格；STEP 为可选项。要从现有的生成或导入的 STEP 进行一次性导出：

cadgen stl build STEP/bracket.step STL/bracket.stl
cadgen 3mf build STEP/bracket.step 3MF/bracket.3mf
cadgen glb build STEP/bracket.step GLB/bracket.glb

省略 OUT 时，会在同一目录写入一个扩展名为所请求格式的文件。该命令不会查找已声明的模型变体。有关装饰器示例、网格公差和动画 GLB，请参阅网格导出。

提示词参考与检查

类似 /work/robot/STEP/assembly.step#o1.2.f7 的引用用于标识特定已保存文档中的几何体。文件部分是 CAD 查看器复制的文档绝对路径，包含文件的真实名称和扩展名（如果名称中含空格或 #，则会加引号）。多个实体的选区会复制为一行，引用之间以逗号分隔（/work/robot/STEP/assembly.step#o1.2.f7,o1.2.f8）。用 read_scene 打开该路径，并将整行传给 resolve()；它会按顺序返回一个由各引用对应选区组成的元组：

from cadgen import read_scene

scene = read_scene("/work/robot/STEP/assembly.step")
for selection in scene.resolve("/work/robot/STEP/assembly.step#o1.2.f7,o1.2.f8"):
    face = selection.shape()  # owned native geometry, in document world coordinates
    print(selection.ref, face.area)

(selection,) = scene.resolve("/work/robot/STEP/assembly.step#o1.2.f7")  # one ref

Quick Edit 提示词会在 File: 下列出文档，在 References: 下列出选中的实体，并以内嵌 JSON 或 .snapshot.json 路径的形式提供快照上下文。若要渲染，将内嵌 JSON 保存到临时 .snapshot.json 文件，然后运行 cadgen snapshot --job <snapshot file>（--job 接受文件路径）。编辑前检查提供的标注。若无标注，捕获的视图仅作为可选上下文；在有助于完成请求时再渲染。编辑后，重放相关视图以检查改动。数据包架构和捕获行为请参阅标注和 Quick Edit 视图。

对于非 STEP 文件中的引用，它表示查看器以该文件自身的术语选中的对象（这些引用都不是 read_scene 可以解析的 STEP 选择器）：

文件	引用	含义
URDF、SRDF、SDF	/work/arm/arm.urdf#upper_arm	链接 upper_arm
GLB	/work/out/model.glb#n12	glTF 节点 nodes[12]（从 0 开始，使用文件自身的索引）
3MF	/work/out/plate.3mf#o2.1	第 2 个 <build><item> 中第 1 个 <component>（从 1 开始）；#o3 是第 3 个 build 项
STL	仅在 File: 中指定文件	一个网格：其中没有选中任何内容

对于单独的 #o1.2.f7，请使用已确定的目标文件。不要在存在歧义的文件或标签之间猜测。数字引用对应于该已保存版本；重新构建后，请重新打开文件并重新选择。检查参考涵盖标签别名、枚举、测量和小型可复用操作。

没有 inspect CLI。将探索性检查放在项目被忽略的 tmp/（或系统 /tmp/）中；将可复用检查保留在 checks/ 或现有测试目录中。请勿将其放入模型源文件夹或原始输出文件夹。

验证与交付

根据请求中的尺寸、间隙和拓扑选择检查项。对于 STEP 输出，使用 read_scene 或 read_step 检查已保存的构件。对于仅含网格的模型，检查模型返回的原生几何体并审查网格输出；不要仅为满足工作流而添加 STEP。报告单位、阈值、选中的几何体和未测试的要求。计算失败不算通过。

创建几何体或对几何体进行可见更改后，至少生成并审查一张结果 STEP 或网格的快照。快照用于你自己的审查：务必亲自渲染并读取，绝不要依赖查看器代劳。选择其他视图以展示正在审查的特征；请参阅快照策略与选项。

cadgen step snapshot STEP/bracket.step tmp/review.png
cadgen stl snapshot STL/bracket.stl tmp/mesh.png

修复源文件中的失败项，并重新运行受影响的检查。比较 CAD 时使用几何体和图像；针对路径的 git status 只是记录操作，不是几何证据。cadgen store why <model>.py 可说明意外重建的原因；python <model>.py --force 强制重建单个模型，cadgen daemon status 显示构建进度。更多诊断信息请参阅模型约定。

在最终回复中列出输出文件、实际运行的检查，以及材料假设或限制。用户会在查看器中看到模型（Show the model），因此除非用户要求提供图像，否则不要附上快照。若跳过快照或生成失败，请根据快照参考中的情形说明原因。

展示模型

向用户展示你创建或更改的每个文件，以及用户要求查看的文件。快照和验证不能替代此操作。

• 如果你的工具包含 cad_show（宿主环境可能会为其添加前缀），请使用文件的绝对路径调用它，并根据其说明判断何时再次调用。cad_view 会读取用户选定的内容；cad_screenshot 会展示用户看到的内容。二者都不能用于检查你自己的工作。

• 否则，请从任意文件夹运行 CAD Viewer：

  cadgen viewer --host 127.0.0.1 --json --detach
  

  --detach 会在查看器开始响应请求后返回，并让其在后台继续运行：始终传入此参数，因为前台查看器不会退出（将其输出通过管道传给 tail 还可能导致 URL 永久丢失）。它会启动本机唯一的查看器，或复用已有查看器。从单行 JSON 中读取 url（切勿猜测端口），并为每个文件返回 url?file=<其经过 URL 编码的绝对路径>。如果无法启动，请说明。

先生成已更改的工件：查看器不会运行模型脚本。需要时，现有 STEP 文件会在打开时编译。精确的拓扑选择和测量需要 STEP；支持的网格查看器也可以在三角形网格上进行近似测量。