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