CAD 建模命令行 liwuzhan/cad-tool

CAD CLI v2.0 - 模型包架构

AI 原生 CAD 命令行工具，支持模型包（.456d）

v2.0 的新特性

主要改进

1. 模型包（.456d） - 自包含的包结构，取代 .cad 目录
2. STEP 产物 - 使用可靠的 STEP 文件，取代不稳定的 pickle 缓存
3. JSON 元数据 - 渲染输出包含相机参数和时间戳
4. JSONL 历史记录 - 以 JSONL 格式高效记录提交历史
5. 产物管理 - 可配置的清理策略，用于管理存储
6. 装配包 - kind=assembly、多实体验证、聚合指标，以及感知组件的无头 PNG
7. 可选标准件 - 渐进式 cadparts 目录查询和可复用的装配代理
8. 模型导向的审查图纸 - 可选的尺寸标注、引线标注、隐藏线和剖视图，且不改变模型

从 v1.0 迁移

v1.0 已归档至 src/cad_cli/v1/。不提供自动迁移——请以 v2.0 重新开始。

安装

Codex 插件

codex plugin marketplace add liwuzhan/cad-tool --ref main
codex plugin add cad-tool@cad-tool

安装后请启动新的 Codex 会话。该插件本身没有安装钩子；在首次真正的 CAD 请求时，它会检查本地运行时，并在创建隔离依赖环境之前进行询问。

DSH 插件包

这个自包含包将 16 个 Host 工具、浏览器结果卡片以及完整的 Python CLI 打包在一个 tarball 中。该插件尚未在 DSH 市场上架，因此请直接安装最新的 GitHub Release：

macOS / Linux
curl -fL https://github.com/liwuzhan/cad-tool/releases/latest/download/dsh-cad-studio.tgz \
-o dsh-cad-studio.tgz
dsh plugin --profile add ./dsh-cad-studio.tgz

Windows PowerShell
Invoke-WebRequest
-Uri https://github.com/liwuzhan/cad-tool/releases/latest/download/dsh-cad-studio.tgz
-OutFile dsh-cad-studio.tgz
dsh plugin --profile add ./dsh-cad-studio.tgz

latest URL 始终指向最新发布的包。在市场条目被接受后，CAD Studio 也可以从 DSH 插件市场安装。包源码仍位于 packages/dsh-cad-studio。

无头 Linux 会自动使用进程安全的 Matplotlib 渲染器，并分别对装配实体着色。在不稳定的 Windows 远程/熄屏会话中，请设置 CAD_RENDER_BACKEND=matplotlib。仅当自动化应完全省略 PNG 时，才使用 CAD_SKIP_RENDER=1；几何检查、STEP、指标和历史记录仍保持启用。

一行安装

git clone https://github.com/liwuzhan/cad-tool
cd cad-tool
bash install.sh # macOS / Linux
Windows: powershell -ExecutionPolicy Bypass -File install.ps1

该脚本需要 Python 3.11–3.14，会在仓库内创建一个隔离的 .venv （约 300 MB 下载：build123d + OCP + pyvista），通过冒烟测试验证安装，并且绝不触碰你的全局 site-packages。

可选： 将此仓库旁边的 cad-parts 参数化标准件库克隆下来——install.sh（以及 DSH 插件的 cad_env_bootstrap）会自动检测并将其作为软依赖安装（可用 CAD_PARTS_ROOT=/path 覆盖）。没有它一切也能正常工作；有了它，模型脚本可以直接 from cadparts import gear, deep_groove_bearing, ...，并通过 cadparts CLI 查询目录。

AI 辅助安装

将这段提示粘贴给任何编码代理（Claude Code、DSH、Cursor……）——它可以通过阅读此 README 自行完成安装：

安装 CAD CLI 工具：
1. git clone https://github.com/liwuzhan/cad-tool && cd cad-tool
2. macOS/Linux：运行 bash install.sh Windows： 运行 powershell -ExecutionPolicy Bypass -File install.ps1 （需要 Python 3.11-3.14。该脚本会构建一个隔离的 .venv；请勿
pip 安装到全局环境。）
3. 验证：.venv/bin/cad --help （Windows：.venv\Scripts\cad.exe --help）然后通过创建并运行一个临时包来对 CLI 进行冒烟测试：
cad init /tmp/smoke.456d --name=smoke && cd /tmp/smoke.456d && cad run
4. 报告已安装的版本以及冒烟测试结果。
如果 install.sh 失败，请遵循其打印的提示（Python 版本、pip 镜像）并重试；不要一次尝试后就放弃。

手动安装

使用 conda conda create -n cad-cli python=3.12 conda activate cad-cli conda install -c conda-forge build123d pyvista
pip install -e .

或者在 venv 中使用普通 pip
python3.12 -m venv .venv && source .venv/bin/activate
pip install -e .

快速开始

1. 创建模型包

cad init my_gear --name="Spur Gear"
cd my_gear.456d

对于装配体，请显式选择装配体模板：

cad init bearing_block --name="Bearing block assembly" --kind assembly

装配体工作流将组件保留为带标签的 Compound 子项，并允许多个有效实体。有关坐标、接口、标准件、验证和评审约定，请参见 docs/assembly_workflow.md。
如果普通的多视图评审发现某个区域存在歧义，请使用 docs/review_drawing.md 中描述的可选标注图纸输入。它仅生成证据；它不是强制关卡，也不是自动设计结论。

这会创建： my_gear.456d/ ├── manifest.json # 包元数据 ├── src/ │ └── main.py # 你的 CAD 脚本 ├── vcs/ │ └── commits.jsonl # 提交历史 ├── artifacts/ # 构建产物 └── runlog/ # 执行日志

2. 编写你的模型

编辑 src/main.py：

from build123d import *

创建你的模型
result = Box(100, 50, 20)

3. 运行并测试

执行脚本（内存中，无产物） cad run 验证几何体 cad validate

检查属性 cad inspect --prop=volume cad inspect --prop=bounds

对于无法从普通视图中定位的问题，请求选定的尺寸、标注或剖视图，而不更改源模型：

cad review --commit --drawing-spec review-request.json

请求格式和中性测量输出记录在 docs/review_drawing.md 中。

4. 提交你的工作

完整构建工作流：执行 + 验证 + STEP + 缩略图 + 指标 cad commit -m "Initial gear design"

这会在 artifacts// 处创建产物：
- model.step - STEP 文件（持久化）
- thumb_.png - 缩略图渲染
- thumb_.json - 渲染元数据
- metrics.json - 几何指标
- validate.json - 验证结果

5. 版本控制

显示提交历史 cad log

检查当前状态 cad status

检出之前的版本（加载 STEP） cad checkout abc123

导出到文件 cad export --format=step --output=gear_v1.step

6. 管理产物

列出所有产物及其大小 cad artifacts list

清理旧产物（使用清单策略） cad artifacts clean

命令参考

项目管理

- cad init --name= - 创建新的模型包
- cad status - 显示仓库状态
- cad log [--limit=N] - 显示提交历史

建模工作流

- cad run [script] - 执行脚本（仅内存中）
- cad build [script] - 构建工作流但不提交
- cad commit -m "msg" [script] - 完整构建 + 提交
- cad validate [script] - 验证几何体
- cad checkout - 加载提交的 STEP 产物

检查

- cad inspect --prop= - 查询几何属性
- 属性：volume、area、bounds、faces、edges、vertices
- cad inspect --list-targets - 列出所有拓扑目标
- cad inspect --target=face[0] --target-prop=center - 查询特定目标

输出

- cad render [--views=top,front,iso] - 生成渲染
- cad export --format= --output= - 导出模型

产物管理

- cad artifacts list - 列出产物及其大小
- cad artifacts clean [--policy=] - 清理产物
- 策略：all_commits、latest_per_branch、releases_only

分支管理

- cad branch list - 列出所有分支
- cad branch create - 创建新分支
- cad branch switch - 切换到分支（恢复 STEP + 脚本）
- cad branch delete - 删除分支

模型包结构

.456d/
├── manifest.json # 包元数据 │ ├── name, version │ ├── head (current commit) │ ├── branches │ ├── artifact_policy │ └── render settings │ ├── src/ │ └── main.py # 主脚本 │ ├── vcs/ │ └── commits.jsonl # 线性提交历史 │ ├── artifacts/ │ └── / │ ├── model.step # STEP 产物 │ ├── thumb_.png # 缩略图 │ ├── thumb_.json # 渲染元数据 │ ├── metrics.json # 几何指标 │ └── validate.json # 验证结果 │ └── runlog/ └── .jsonl # 执行日志

配置

编辑 manifest.json 进行配置：

{
"name": "My Model",
"unit": "mm",
"timeout_seconds": 60,
"artifact_policy": "latest_per_branch",
"render": {
"default_views": ["top", "front", "right", "iso"],
"resolution": [800, 600],
"image_format": "png"
}
}

输出格式

所有命令输出 JSONL（JSON Lines）：

{"event": "run_start", "ts": "2026-01-31T10:30:00", "payload": {"script": "src/main.py"}}
{"event": "run_success", "ts": "2026-01-31T10:30:01", "payload": {"metrics": {...}}}

脚本约定

脚本必须将最终形状赋值给 result 变量：

from build123d import *

Create geometry
box = Box(100, 50, 20)
cylinder = Cylinder(30, 100)

Assign to result
result = box - cylinder

特征级检查点

检查点是检测布尔运算失败的可靠方法。在每个特征操作之后添加检查点：

from build123d import *
from cad_cli.feedback import Checkpoint

Checkpoint.reset()

with BuildPart() as part:
Cylinder(30, 10)
Checkpoint(part, "base").expect_volume(28274, tolerance=100).expect_solids(1).verify()

Cylinder(10, 10, mode=Mode.SUBTRACT)
Checkpoint(part, "hole").expect_volume_decreased().expect_solids(1).verify()

result = part.part

检查点方法

| 方法 | 描述 |
| .expect_volume(value, tolerance=1.0) | 断言特定体积 |
| .expect_volume_decreased() | 断言体积较上一个检查点减少 |
| .expect_volume_increased() | 断言体积较上一个检查点增加 |
| .expect_solids(count) | 断言实体数量（始终验证 = 1） |
| .expect_faces(count) | 断言面数量 |
| .expect_bbox_size(x, y, z, tolerance=1.0) | 断言边界框尺寸 |
| .verify() | 执行所有检查，失败时抛出异常 |

检查点结果在 JSONL 输出中显示为 checkpoint_passed 或 checkpoint_failed 事件。

测试

运行测试套件：

pytest # All tests
pytest --cov=cad_cli # With coverage
pytest test/test_package.py -v # Specific test

架构亮点

v2.0 与 v1.0

| 特性 | v1.0 | v2.0 |
| 项目结构 | .cad/ 目录 | .456d 包 |
| 形状缓存 | Pickle（不可靠） | STEP 产物 |
| 提交存储 | 单个 JSON 文件 | 单个 JSONL 文件 |
| 渲染元数据 | 无 | 带相机参数的 JSON |
| 产物清理 | 手动 | 基于策略 |
| 复杂模型 | 超过 150 个面时失败 | 使用 STEP 时可靠 |

错误代码

- E-SYNTAX - Python 语法错误
- E-RUNTIME - 运行时错误
- E-CONSTRAINT - 约束违反
- E-BREP - BRep 验证失败
- E-RENDER - 渲染错误
- E-IO - 文件 I/O 错误

开发

pip install -e ".[dev]" # 安装开发依赖
pytest # 运行测试 black src/ test/ # 格式化代码 mypy src/ # 类型检查

要求

- Python 3.11+
- build123d 0.5.0+
- cadquery-ocp 7.7.0+
- pyvista 0.43.0+
- click 8.1.0+
- numpy 1.24.0+

许可证

MIT

故障排除

“未找到模型包” 确保你位于 .456d 目录中，或先运行 cad init。

“未找到 STEP 工件” 该提交可能已被清理。请检查 cad artifacts list。

渲染失败确保已安装 pyvista：pip install pyvista

导入错误确保已安装 build123d：conda install -c conda-forge build123d