参数化 CAD 建模（text-to-cad / cad 0.10.0）
一个模型就是一个 Python 函数；运行它的脚本会在 text-to-cad 的常驻服务器里重建模型，
你打开的页面随之更新。文件是导出动作，按需才写。
环境准备（一次性）
cad 命令（Windows 上为 cad.cmd）驱动一个常驻服务器：第一次运行会启动它，之后每次
cad run / cad export / cad snapshot / cad inspect 都走这个服务器。服务器在
127.0.0.1 本地运行，不需要联网账号。
方式 A — 官方安装脚本（用户机器上推荐）
curl -fsSL https://texttocad.dev/install.sh | sh
# Windows PowerShell：irm https://www.texttocad.dev/install.ps1 | iex
装好后 ~/.local/bin/cad（cad.cmd）即可用。若刚装完报找不到命令，等 5 秒重试，
最多一分钟。
方式 B — 本机托管运行时（离线 / 沙箱）
本技能使用 ~/.workbuddy/cadgen-runtime/venv 这个本机托管的
Python 3.14 venv（已装 cad[build123d]==0.10.0 + cad-server==0.10.0）。用技能启动器
scripts/cadgen.py 即可，它优先用这个 venv 里的 cad.exe：
python scripts/cadgen.py --check # 报告 cad 命令位置、版本与服务器状态
python scripts/cadgen.py --doctor # 注册安装并启动服务器（首次需要）
无论哪种方式，安装后都要跑一次 cad doctor（或 cadgen.py --doctor）：
它注册安装、写 cad 启动器、并启动服务器。把遥测关掉：
"venv/Scripts/python.exe" -m cad_server.cli telemetry off
> 本技能锁定的版本是 0.10.0（cad 与 cadgen 别名同版本）。scripts/cadgen.py --pin
> 可打印该版本。版本只由启动器持有，文档不必在每个调用点重复写版本。
写模型并运行
零件或装配是一个无参函数，用 @model 装饰（或用文件装饰器，见下），返回 build123d 形状。
尺寸是普通辅助函数的参数，每个配置各是一个 @model；多个模型共享的常量放在它们 import 的
模块里。调用它会在服务器里构建并返回一个文档：带 .id、.url、.shape（构建出的形状）和
.export(...)。例：src/bracket.py：
import build123d as bd
from cad import model
def bracket_body(width, thickness, bore):
body = bd.Box(width, 20, thickness)
hole = bd.Cylinder(bore / 2, thickness)
body = body - hole
body.label = "bracket"
body.color = "#4a6fa5"
return body
@model
def bracket():
return bracket_body(40, 6, 8)
@model
def bracket_wide():
return bracket_body(60, 6, 8)
if __name__ == "__main__":
bracket()
bracket_wide()
cad run src/bracket.py
每次 __main__ 里的调用会打印该模型如何构建、其下的增量（零件数、包围盒、关节、序列）、
文档 id: 与页面 view:。把页面链接给用户一次（见「展示模型」），之后的命令都用这个 id。
- 运行脚本就是重建：它不写任何文件，只是把模型在热服务器里重放。
@model只声明，
真正的调用放在if __name__ == "__main__":下，这样别的脚本也能 import 这些模型。 import build123d as bd，属性式使用（bd.Box）。import 是惰性的：内核在 Worker 里
首次用到时才加载。module顶层不要写bd.Align.CENTER这类惰性内核属性——把用到它们的
元组下沉进函数体，否则一 import 就加载内核。- 颜色是 sRGB：
part.color = "#4a6fa5"或 0–255 整数；from bd_materials import metals
后用part.material = metals.aluminum()赋原生材料。 - 输入是体体内的
read_step/read_xbf/read_mesh，以及 Python 自己打开的文件，
都按字节追踪。用调用组合项目模型，不要去读项目导出的文件。 - 模型单位是毫米，+Z 朝上。
围绕导出文件的项目（0.7 风格）
如果一个项目本来就以导出的文件为中心（用户要求迭代文件本身、或有消费文件的下游），可以让脚本
每次运行直接写文件：用 @step("相对路径.step") 文件装饰器代替 @model（路径相对脚本）。
本技能支持的写法：
import build123d as bd
from cad import step, stl
@step("box_30x20x10.step")
@stl("box_30x20x10.stl")
def box_30x20x10():
body = bd.Box(30, 20, 10, align=(bd.Align.CENTER, bd.Align.CENTER, bd.Align.CENTER))
body.label = "box_30x20x10"
return body
if __name__ == "__main__":
box_30x20x10()
cad run box_30x20x10.step.py 会一次性写出 .step 与 .stl。校验就读文件本身：
cad snapshot / cad inspect 指向该路径，或在检查脚本里 read_step。代价是每次迭代都要重算
文件的几何与重读页面，且文件不记录模型来源（Quick Edit 无法回写到代码）。默认仍推荐 @model
+ cad export。
导出文件（按需）
文件是对服务器持有文档的一次动作，不是模型的一部分：不改代码、不重建，随写随有。在用户要文件时
才写：
cad export "$ID" STEP/bracket.step STL/bracket.stl GLB/bracket.glb 3MF/bracket.3mf
有固定交付物的项目可以写一个 exports.py，import 各模型并对每个调用 export(x, path, ...)；
运行它就重写全部交付物（见 Exports）。
xbf 是 text-to-cad 自有文档（Save As），仅在「不带代码分享模型」或「用 read_xbf 在别的项目
里组合」时才导出。厂商 STEP 转一次 xbf（cad export vendor/motor.step vendor/motor.xbf），
之后用 read_xbf 读，比反复解析 STEP 快得多。
审阅与量测
跑完模型，先读它的输出行和下面的增量，发现与意图矛盾先改掉。用户给的数字，要在模型体体内用
assert 量测几何（包围盒、距离、体积）来核对，或用 cad inspect——不要复述常量，也不要在
调用之后的代码里读（见 Inspection）。
cad snapshot "$ID" tmp/review.png
cad snapshot "$ID" tmp/top.png --camera top --display hidden-line
cad snapshot 按查看器的方式用 OCCT 渲染文档，只写 PNG。选项决定画法：相机（--camera top）、
显示、网格、姿态（--pose open）、尺寸。它展示布局与外观，不标尺寸。
需要解析几何引用时，用 cad inspect：
cad inspect "$ID" "bracket/face 7"
它用 JSON 回答该引用指代什么、放在哪：元素的规范 ref、类别、序号与名称，内核事实（面的面积、
质心、半径；边长与端点），以及 made_by——写出它的函数、文件与行号；装配的体积与质量。按
made_by 改代码，或在体内用 build123d 的选择器（body.faces().sort_by(bd.Axis.Z)[-1]）选中
同一元素（见 Inspection）。
展示模型
在 WorkBuddy 里没有托管的 CAD 查看器页面，按以下方式把模型交给用户：
- STEP / STL 文件：用 present_files 作为交付物给出路径，不要截图查看器来自证；
用户会在 FreeCAD 里打开 STEP，用渲染器看 STL。 - 快照图：
cad snapshot生成的 PNG 用 present_files 展示，用于人工核对布局/外观/姿态。 - 装配/机构：对每个改动涉及的零件出一张快照即可，不要习惯性地多角度出图；大模型就只框选
改动涉及的零件，而不是整模型出图。
每个创建或改动的模型、每个导出的文件、跑过的检查及其结果、未覆盖的检查、所有假设与偏离，都是
你回复里要交代的内容。
参考文档
| 主题 | 文件 |
|---|---|
模型契约（@model / @step、运行、输入、引用） |
model-contract |
| build123d 建模（体素、草图、孔、倒角/圆角、布尔、定位、颜色/材料） | build123d-modeling |
| 导出 STEP/STL/GLB/3MF/xbf、exports.py、模型页 vs 文件页 | exports |
| 检查与校验：量测、干涉、引用解析语法、检查脚本 | inspection-and-validation |
| 运动学：joints、cad.ap242 机构状态与配对 | kinematics |
| 动画：cad.gltf 的 animation() | animation |
| 定位：子零件放置、坐标系与对齐 | positioning |
| 项目布局：多模型/多文件工程组织 | project-layout |
| 快照审阅：cad snapshot 出图与标注、Quick Edit 视图 | snapshot-review |
更新本技能
上游发布在 https://github.com/earthtojake/text-to-cad 。升级时：
- 改
scripts/cadgen.py顶部的PIN到新版本（同时是cad与cadgen别名版本）。 - 按上游
skills/cad/重新拉取 SKILL.md 与references/九篇文档（逐字 + 顶部中文导读）。 - 升级本机托管运行时：在
~/.workbuddy/cadgen-runtime/venv里
uv pip install "cad[build123d]==<新版本>" "cad-server==<新版本>"，再cad doctor。 - 把 7 个用户模型脚本（
*.step.py）按本文件「写模型并运行」迁移到新契约。 - bump 技能版本号（frontmatter
version与 CHANGELOG），重新打包发布。
> 本技能的「对外包自洽」约定：发布包仅描述当前 v0.10.0 契约与 cad 命令，不提及
> 0.4.x / 0.7.x 旧契约的迁移细节，也不引用内部维护用的私有术语。
