yingzao
Manifest validA dsh plugin for mechanical CAD — the agent generates, the plugin closes the loop.
营造 · Yingzao
Agent 负责生成,插件负责闭环。
dsh 的机械 CAD 插件:验收前替你把配合、运动与可制造性查一遍,最终判断留给你。
| 零件 | 装配 | 运动 |
|---|---|---|
![]() | ![]() | ![]() |
| 真实 M8×1.25 螺纹,约 5.2 圈啮合 | 24 实例 / 276 对,0 干涉,传动比 64.000 | 0→90° 行程,24/24 位姿,0 干涉 |
dsh plugin --profile <你的 profile> add dsh-cad-harness
目录
适合谁用,不适合谁用
营造的定位是为 Agent 提供场地:以规范、稳定的方式产出机械构件,并保留回看、复算与交付的通道。它不承担提升 Agent 3D 能力的职责。几何能力取决于模型本身,这不是单个插件能够承担的工作。
适合
- 你已有明确的设计意图和验收标准,愿意用文字描述需求,并接受 Agent 以参数化代码建模,而非拖拽特征。
- 你需要的是可制造、可装配、功能可实现的零件或装配体,而不只是视觉上成立的渲染图。
- 你主要做装配体,且复杂度处于 Agent 能力范围之内。复杂度越高,收益通常越明显:收益不在于让原本无法设计的对象变得可设计,而在于对“能够设计、却无法制造、无法装配或功能无法实现”的部分进行纠偏,并尽量在交付前发现。
- 你愿意依据证据判断:版本、数值报告、干涉与行程检查;同时接受最终判断仍由人作出。
- 你看重下限:减少 Agent 表现最差的情况,而不是依赖偶发的高水平输出。
不适合
- 希望获得“一句话出图”的演示效果,或将 3D 生成能力本身作为卖点。
- 需要原生 CAD 的交互方式:草图约束、特征树、拖拽编辑。
- 需要认证级精度:工业公差、工程图、精确 FEA/CFD、量产 BOM。这里提供趋势判断和边界内的数值,不提供认证。
- 期待插件降低 token 消耗,见下一节。
以上是使用预期,不是准入条件。需求若属于后者,专业工具通常更合适。
关于 token:不期待更省,而期待更可预期
(内部实测,样本有限。)同一任务中,使用插件的平均 token 消耗不低于不使用插件,反而略高;但消耗的方差显著更小,单轮成本可以提前估算,不易出现大幅波动。
降低 token 消耗在计划之内,但优先级低于能力建设:不会为了节省 token 而削减验证或必要的检查。合理的预期是成本可预期、投入有效,而不是成本更低。
关于本项目
几何生成已经不是瓶颈,确认结果是否正确才是。能生成但无法验证的系统,只能产出“看起来对”的结果。
营造把「生成 → 验证 → 迭代 → 交付」做成闭环:
- 生成:Agent 编写参数化代码(OpenSCAD),编译成不可变版本;
- 验证:尺寸、体积、壁厚、间隙、干涉、运动行程、流体趋势由引擎给出数值,而不是由语言模型“目测”;
- 迭代:每一版都能浏览、钉住、对比;旧版本和旧运行不会被覆盖;
- 交付:导出单个版本,或整个项目(每个零件的 STL + 装配清单 + 说明);也可按装配位姿合并成整机。
它面向的不是聊天框里“画一个零件”的演示。多模态大模型负责读写 SCAD、查看渲染图并决定下一步;DSH 插件提供 CAD 工具、不可变版本、数值验证和交付门。它不追求全自动建模:重复的生成和检查交给 Agent,设计判断留给你。
示例
三个例子分别覆盖基础零件、装配体和运动仿真。
基础零件:M8 螺栓与螺母

做一个 M8×30 六角螺栓和 M8 六角螺母;螺纹 M8×1.25,螺母对边 13、厚 6.5;要真实螺纹,不要光孔。
| 检查项 | 结果 |
|---|---|
| 螺纹 | M8×1.25,螺母 6.5 mm 高,约 5.2 圈啮合 |
| 螺母对边 / 高度 | 13.00 / 6.50 mm |
| 螺栓 | M8×30,六角头对边 13 |
| 外形包围盒 | 13.00 × 14.88 × 35.50 mm |
| 体积 | 2.44 cm³(STL 实测) |
| 螺纹几何 | BOSL2 threaded_rod / threaded_nut 生成的真实螺纹,不是光孔 |
源码:docs/readme-models/m8-bolt-nut.scad。渲染脚本:docs/readme-models/render.py。
装配体:三级直齿 64:1 减速器

三级直齿串联,齿数比 48:12,总传动比 64.000;6 个齿轮、4 根 Ø5 轴、8 个 685ZZ 轴承,箱体 106×48×42 mm,壳体为 FDM 尼龙,输入与输出位于对侧。
| 检查项 | 结果 |
|---|---|
| 总传动比 | 64.000(三级,精确) |
| 中心距 | 24.0 mm(三级相同) |
| 齿轮 | 3 × z12 / 3 × z48,m0.8,齿宽 8 |
| 装配规模 | 24 个实例,276 对 |
| 静态干涉 | 0 干涉、0 过紧 |
| 装配契约 | 23 条接口全部通过,0 硬冲突 |
装配检查只回答静态干涉与接口配合,不回答齿面受力、效率、噪声。
运动仿真:DN100 球阀

球阀从全开到全关,90° 行程,24 个位姿。
| 检查项 | 结果 |
|---|---|
| 行程 | 0→90° |
| 采样 | 24/24 |
| 干涉 | 0 |
| 关节漂移 | 0 |
运动检查只回答“转得动、不撞、行程够”,不回答密封、扭矩和压降。
示例用于展示能力;材料强度、磨损、噪声、打印方向仍需单独验证。
技术栈
| 层 | 使用 |
|---|---|
| 几何内核 | OpenSCAD + Manifold 后端;BOSL2 提供螺纹、齿轮等标准件 |
| 数值检查 | Python、trimesh、manifold3d、numpy、shapely |
| 宿主 | DeepSeek Harness 插件;Node.js ≥ 20、TypeScript |
| 面板 | React + WebGL 视口,随 DSH Web GUI 运行 |
| 证据 | 不可变版本、JSON 报告、六类证据、claims / policy / delivery audit |
快速开始
setup --openscad=auto 会准备 OpenSCAD(2021.01 可运行但 doctor 报 degraded;推荐 2025.06+ / Manifold)。已有 2025.06+ 系统版本则直接使用;否则优先下载官方快照,官方源不可达或持续低于 256 KB/s 时才切换到 OSS 镜像。
版本不是偏好,是能力:同一个 plate.scad,2021.01(CGAL)实测 2467 ms,带 Manifold 的构建 69 ms——差 36 倍,模型越复杂差距越大。低于 2025.06 时 doctor 会给出这条实测数据,compile.ts 也会在首次解析到旧版时提示一次。
网络与离线(三个开关,都不改分发形态):
| 环境变量 | 作用 |
|---|---|
CAD_OPENSCAD_BIN | 已有二进制,跳过下载 |
CAD_OPENSCAD_MIRROR | 覆盖镜像地址(内网/区域镜像),仍按固定 sha256 校验 |
CAD_OPENSCAD_ARCHIVE | 本地离线归档,等同 --from,完全不走网络 |
LICENSE.GPL-2.0、SOURCE-OFFER.md(GPL-2.0 §3(b) 源码书面要约)和 manifest.json(逐文件 sha256)随二进制发布在同一镜像前缀下;仓库里只保留后两者,避免第二个许可证文件干扰 SPDX 识别,见 dsh-cad-harness/mirror/。
OpenSCAD 在
setup时准备;Python 运行时约 400MB,在首次计算时安装。两者都不随 tarball 分发。
安装(推荐:npm)
dsh plugin --profile <你的 profile> add dsh-cad-harness
装完后跑一次准备,把预设和 OpenSCAD 就位:
npx dsh-cad-setup --openscad=auto # 预设 + 自动准备 OpenSCAD
npx dsh-cad-doctor # kind=ok,或有解释的 degraded
pnpm 12 首次安装会提示
Agent skills awaiting approval: dsh-cad-harness——这是它对包内 skills 的审批提示,不是安装失败;pnpm approve可以查看。
国内网络建议把 npm 源设为 npmmirror,安装会走镜像缓存;OpenSCAD 本身仍从官方快照或本项目镜像下载(见上文三个开关)。
备选:源码 checkout(贡献者)
git clone https://github.com/songsenand/yingzao.git
cd yingzao/dsh-cad-harness && pnpm install && npm run build
dsh plugin --profile <你的 profile> add -w "$PWD"
node scripts/setup.mjs --openscad=auto
npx dsh-cad-doctor
开启营造模式
- 新建会话时选择预设 「营造模式」;普通会话看不到 CAD 工具,这是有意为之。
- 在右侧打开 CAD 预览 标签页。如果标签页不存在,先重启 dsh,再新建一个营造模式会话。
- 直接描述需求:
做一个 60×40×8 的安装板,四角 M3 沉头孔,中心一个 20 mm 通孔。
打开后界面如下(示例为发条青蛙装配,12 个零件 / 12 个版本):

面板里能看到:
- 版本历史:
v001、v002……每次生成/修改都是不可变版本,可以点开对比、钉住、回看; - 三维视口:旋转、缩放、平移;按顶/前/侧/等轴查看,旁边给包围盒数字;
- 测量与标注:两点距离、壁厚、剖切、红框标注问题,再把这些指认带回会话;
- 运行回放:机构运动、刚体物理、流体趋势的时间线,可以停在某一帧;
- 验证状态:装配检查、打印性、交付审计的结果和“待复核”提示;
- 导出入口:单版本 STL/3MF/OBJ/OFF/WRL,或整个项目 ZIP;被交付审计拦住时会弹窗要求确认。
面板是只读视口 + 人的指认通道:它不替代 Agent 写代码,也不替代引擎给真值;它让人能看见、能量、能指出问题。
用法
一次典型的对话分五步:
- 你描述需求、约束和验收标准;
- Agent 生成参数化 SCAD,登记为
v001; - 引擎运行尺寸、壁厚、间隙、打印性、装配等检查,并把结果写成报告;
- Agent 读渲染图和报告,发现问题后生成
v002; - 你确认后导出单版本(STL / 3MF 等)或整机装配,也可以交给下游。
版本不可变:v002 不会改写 v001;检查报告绑定到它实际检查的版本,旧版本的报告不会自动成为当前版本的证据。
验证
# tarball 安装后
npx dsh-cad-verify /path/to/project --advisory
npx dsh-cad-verify /path/to/project --block --strict
# 源码 checkout
cd dsh-cad-harness
node scripts/verify.mjs /path/to/project --advisory
verify 只读:检查 requirements / model / fit / make / review / delivery
六行,报告缺失/过期的证据和 claim witness;不跑 CAD、不写 run、不判设计。
- 默认 advisory(exit 0);
--block时 pass 0 / warn 1 / blocked|fail 2 / 用法错误 3;--strict让 warn 也返回 2。 - claims:
<project>/claims.json或--claims <file>;policy:<project>/evidence-policy.json或--policy <file>;没有 policy 就是 advisory。 - 项目特定判据放在
<project>/checks/<id>/:先check-register注册,再用--checks启用。注册时会跑负样本,负样本通过则拒收;每条判据都要有 finding 或 skipped;检查不得写项目。 - 详见 docs/llm/verify.md。
已知边界
- 不是原生 CAD:没有特征树、草图约束和拖拽编辑,几何源头是代码,STEP 能进不能出。
- 起点是个人自用:效果超出预期后才补文档和验收,早期提交历史比较乱。
- 题库没有正式基线:
examples/bench只有一轮 N=1 探索运行,6 题机检通过数均为 0,03 因服务端配额上限(429)未完成,不是可比较的 benchmark。 - 工具成熟度不齐:打印性检查 / 装配检查相对成熟,CNC、EDM、钣金、车削、压铸等仍是
partial,动态仿真受求解器限制。 - 示例不能全部一键复跑:
examples/*/cad-data/被 gitignore,历史示例只保留文档、源码和渲染。 - 英文是机器翻译:英文用户文档、
docs/en/llm、HARNESS.en.md未经人工润色;客户端 UI 已英文化,模型侧输出仍可能为中文。 - 成本不低:那一轮探索消耗 81.41M tokens;长任务的上下文成本是真实成本。
文档
| 文档 | 讲什么 |
|---|---|
| docs/user/ | 用户指南:安装、流程、验证、边界、排错 |
| docs/llm/ | Agent 参考:引擎边界、陷阱、交付纪律 |
| docs/dev/ | 维护者入口:架构、设计、决策、计划、审计 |
| examples/README.md | 样例索引:当前 / 历史 / 夹具 / 题库 / 沙箱 |
| HARNESS.md | 它是什么、不是什么、边界与取舍原则 |
| DESIGN.md | 当前设计:架构、模块、接口、环境变量全集 |
| docs/README.md | 文档地图与“同一事实一个权威”的规则 |
参与贡献
- 完整规则见 CONTRIBUTING.md:每次提交都要
git commit -s签名(DCO 1.1);DCO 不是 CLA。 - 提交信息按 AGENTS.md 写
Why/Verified/Risk(有方向取舍时加Decision);Verified必须能指名一个可证伪的观察。 - 方向性决策写进 docs/DECISION-LOG.md(append-only)。
- 题库里的第三方素材一律物化使用、不入库(见 examples/bench/ATTRIBUTION.md)。
许可证
Apache License 2.0。全文见 LICENSE,第三方声明见 NOTICE,审计明细见 docs/THIRD-PARTY-AUDIT.md。
允许商业使用、修改、闭源再分发与售卖;条件是随分发附上许可证副本、保留版权与 NOTICE 声明,并在修改过的文件中标注改动。另含显式专利授权与专利报复条款。
BOSL2(BSD-2-Clause)不随仓库分发:自行下载放到 lib/BOSL2/(已 gitignore)。
Comments
Loading…