dsh-skill-blender-modeling

Blender 建模与装配流程 skill（DSH / Claude 风格的 skills/<name>/SKILL.md 目录）
把「捏一个物体」和「多个 agent 造一台机器」都写成可执行流程 + 可跑的判据。

这是什么

一份给 AI agent 读的建模作业指导书：先按决策树选形，再走流水线，每一步都要有画面或数字证据。
与常见的「Blender 入门教程」不同，它按实测反馈写成 —— 每一条都是踩过之后才加进去的：

载体不匹配就换路子：分面装甲板禁止上 SubSurf（会把棱边圆成肥皂）；编辑模式 bpy.ops.mesh.*
在 blender -b 下 context 很脆 → 改 bmesh；
展示拼接 ≠ 真实连接：面贴面必见缝，所以展示模型用隐藏交叠（不改可见轮廓、不捅穿薄壳），交叠量由
本项目 spec 明文定、装配后按 spec 复核 —— 没有通用倍数或下限；能不能承载由设计配合 / 标准 /
承载工况 / 制造工艺 / 运动间隙规定，几何脚本不给强度结论；
判据必须有前提：法线朝内会让所有"穿模 / 内含"判据整体反号（实测把贴合件误报成深入 150mm）；
指标必须有适用范围：IoU 只是单视轮廓的必要条件（看不见深度/内部特征/面感）；单应只校正
取点那一个平面（离平面 0.5m 实测误差 543mm）；跨深度误差不是固定 ±5% 而是 Δz/(D+Δz)；
验收不能靠肉眼：形体要「同机位对照图 + 数值 bbox」两条证据。

内容（SKILL.md）

章节	一句话
§0 工具与通道语义	`blender_rt_*` 直连链怎么用、什么时候走 headless、写租约怎么拿
§0.5 多 Agent 分工范式	冻结 `spec.py`（尺寸+接口表+命名）· 写作用域协议 · 接口表五要素（含逐接口 `overlap_mm`，来自 spec 明文）· 隐藏交叠+装配后复检 · 数值门 · 交接前必跑清单 + 可复制的验收回执 · 可并行性判据 + `COL_<agent>`/`dsh.owner` 归属 + 单 builder 回滚
§0.6 参考图形体还原	三视图标定（逐视独立最小二乘；跨视互检换算成毫米再比，因为正交不推出三视共享 `px_per_mm` —— 实测差 300% 全是正交）+ IoU 只是单视轮廓的必要条件 + 双证据验收 + 读图纪律（420/900 与 hash）；脚本见 `references/multiview-calibration.md`
§1–§2 六步总纲 / 决策树	冻结规格 → 场景准备 → Blockout → 精修 → 修改器栈 → 清理 → 交接
§3 配方（22 个编号，含 2a/2b/3b/6b）	基本体 · 分面装甲板 · 光滑硬表面栈 · 编辑模式 · bmesh 等价写法 · 布尔 · 镜像 · Array · 销轴弦长节距闭合阵列（模板契约①–⑤：原点在起点销轴 / 局部 +X 指下一销 / 下一销在 `(+pitch,0,0)` / 销轴 = 局部 +Z / 只有 z 被沿用；自带从零建可视单节） · 装配审计门 · 双证据验收 · 程序化雕刻 · 网格修复 · 打印检查 · 沿路径扫掠 · 人形素体 · 头型 · 车辆/参考图放样 · 照片校正 · 折线族拟合 · 特征线层；§3.0「参数块 + 生成脚本」（2a/4/5/6b/9 五条接 `generator_save/run/list/get/diff`；改参直接调工具、`args` 嵌套一层，旧插件见迁移说明）
§4 六条坑	长/宽/薄轴语义 · 可视拼接用隐藏交叠、结构连接不由脚本裁定 · 收尖压中线 · headless 慎用 bpy.ops · 法线前提（逐连通壳判 `normals_state` ∈ pass/fail/unknown，`nested` 空腔豁免） · 预览光照；§4.0 分流表（法线/浮块/穿模 → 验收门；语义类 → 写代码前 checklist）
§5 修改器栈 + 症状表	没有固定链（同一网格换顺序：Bevel→SubSurf 864 面 / SubSurf→Bevel 96 面，bbox 差 15%）→ 按目标排 + 用求值回执核对；§5.1 删内部面的正确做法（`Delete Loose` 一个面都不删）
§6 数值门清单	0 非流形 / 0 开边 / 0 孤立点 / 0 悬空 / 0 穿模 / 逐接口按 spec 的 `overlap_mm` / 形体双证据；三态口径（`pass`/`fail`/`degraded`；`clean=false` 有两种成因，先读 `state`）；§6.1 交接前必跑（三条命令 + 一张回执；`audit_scene` 交付验收必须 `self_intersect:true`）
§9 / §10 / §11 / §12 / §13 更新对照	每条反馈落在哪一节（§9 = v2 · §10 = v3 · §11 = v4 · §12 = v5 · §13 = v6）

安装

git clone https://github.com/sixtysevenlf/dsh-skill-blender-modeling.git
cd dsh-skill-blender-modeling

# 方式 A（推荐）：软链，改一处两边同步
ln -s "$PWD" ~/.dsh/skills/blender-modeling

# 方式 B：直接拷贝
cp -r . ~/.dsh/skills/blender-modeling

⚠ SKILL.md 必须保留 YAML frontmatter（name / description / license）——
加载器靠它建目录；frontmatter 一掉，技能会直接从技能目录里消失（踩过）。

配套插件

本技能里的 blender_rt_* / blender_viewport 工具来自配套插件（v0.9.4 起）：

https://github.com/sixtysevenlf/dsh-blender-plugin

插件负责"通道"（看视口 / 跑 Python / 无头批处理 / 作业层 / 事务回滚 / 装配审计 / 一键拉起 Blender），
本技能负责"流程与判据"（选形、配方、坑、数值门）。两个一起用才完整。

相对 v1 的改动（2026-09-25）

v1 是"单人单线捏一个物体"的手册；v2 加上了大件 / 多 agent 真正需要的东西：

v1	v2
无并行建模章节	+ §0.5 多 Agent 分工范式（冻结规格 / 写作用域 / 接口表 / 数值门）
无参考图章节	+ §0.6 参考图驱动的形体还原（比例标定 + 双证据）
配方 2 = Bevel+SubSurf	拆 2a 分面 / 2b 光滑（分面件上 SubSurf = 毁形）
配方 3 = 编辑模式 ops	保留 GOI 版 + 新增 3b bmesh 版（headless 稳）
配方 6 = Array 沿曲线	保留装饰用途 + 新增 6b 参数化节距阵列（履带 83 节 / 0.176；v4 已重写为可运行的闭合路径 + 销轴弦长口径；v5 补模板契约与从零建单节）
三条坑	六条坑（+ headless bpy.ops / 法线前提 / 预览光照）
清理清单	数值门清单（10 条判据 + 对应工具）

相对 v2 的改动（2026-09-26 · v3）

按《实测驱动的通道 + Skill 优化方案》的 §4 Skill 侧做定点增补，流程骨架不动（六步总纲 / 决策树 / 配方编号 / 修改器栈 / 症状表保持 v2 原样）：

条目	改了什么
P0-4 验收门必跑清单	交接前必跑写成清单 + 可复制的验收回执模板（`boundary_edges=0 / nonmanifold_edges=0 / loose_verts=0 / self_intersections=0 / closed=true` + `.blend` md5）+ 三条硬纪律
P0-5 读图纪律	迭代 420px、验收 900px + 固定机位；只在新 hash 时看图（回执带 hash，同 hash = 画面没变）
P1-3 多视角联合标定	§0.6.1 扩成三视联立标定 + 判据（残差 >2% 或两两比例互差 >3% ⇒ 非正交/透视，退回单视）+ 新增 `references/multiview-calibration.md`
P1-5 归属 + 可并行性	可并行性判据表（共享对象 / 文件 / 材质 ⇒ 不可并行）+ `COL_<agent>` + `dsh.owner` + `rt_txn mark(objects=...)/revert` 只回滚一个 builder
P1-4 参数化配方	5 条高频配方升级为「参数块 + 生成脚本」，接插件已有的 `generator_*`
P2-3 六条坑分流	机械可判的接验收门，语义类的写进「写代码前 checklist」

相对 v3 的改动（2026-09-26 · v4）：纠正被写死的错口径

按实测反馈纠正 v3 里写错了的几条"通则"。每条都先用本机 headless 量过再改（证据见下）：

#	原来写的（错）	改成	实测证据
1	拼件必须互相插入 5–15mm	嵌入深度按接口类型与尺度定（`1–2×` 接口特征尺寸）；5–15mm 只是"特征尺寸 5–30mm"那一档 —— ⚠ 本行已被 v6 取代（固定倍数 / 下限与 5–30mm 推导全部撤回，见下节）	3mm 薄板搭接 = 1.5mm 合格；Ø6 轴 = 6mm；10mm 浮块也满足 `overlap_bbox=true`，会被当成合格嵌入（`audit_measure` 回执）
2	三视必须共享同一个 px_per_mm；比例互差 >3% ⇒ 判透视	正交不推出共享比例 —— 三张图可以各缩放却都是正交；跨视互检要换算成毫米再比，`s` 互差只决定"能不能合并"	三个正交相机 `ortho_scale` 4/8/2：视差全 0px，`px_per_mm` = 0.48/0.24/0.96（差 300%）
3	跨深度尺寸公差放宽到 ±5%	误差是 `Δz/(D+Δz)`，随深度线性放大；估不出 `D`/`Δz` 记 `unresolved`	D=8m：Δz=0.5m → −5.88%；1m → −11.1%；3m → −27.3%（与解析式逐行吻合）
4	照片"必须先做透视校正（求单应），否则尺寸全错"	单应只校正取点那个平面；平面参考完全正确，立体物只有该平面准	平面内 0px；离平面 0.05m → 52mm；0.2m → 211mm；0.5m → 543mm
5	用 IoU 判「像不像」	IoU 是单视轮廓的必要不充分条件；看不见深度/内部特征/面感，且填满轮廓就能刷高	补进 §0.6.2 的盲区表 + SOP/验收清单同步
6	修改器顺序背下来一条固定链	不存在固定链 —— 按目标排，用求值回执核对	同一立方体：Bevel→SubSurf 864 面 bbox 0.9904 vs SubSurf→Bevel 96 面 bbox 0.8395；Solidify↔Bevel 54 vs 6 面
7	内部面 → `Delete Loose`	`Delete Loose` 一个面都不删；`select_interior_faces` 对 join 重叠壳也选 0 → 用 Boolean UNION 或射线法找埋面（§5.1）	Blender 打印 `Removed: … 0 faces`（两种场景）；join 重叠对 `select_interior_faces` 选中 0
8	配方 6b 是"恒原点"占位、节距用等弧长、`bbox ≈ n*pitch`	改成真正可运行的闭合赛道形；区分等弧长与销轴弦长节距；修正 bbox 与对象数	弦长口径 `max

验收表（§0.5.5 / §6 / §6.1）与轻量清单（references/验收清单.md）已同步到新口径；
references/modeling-overview.md（上游英文收录）里同样的两处旧说法已就地标注纠正。

相对 v4 的改动（2026-09-26 · v5）：对齐插件 v0.9.6 与当前配方边界

并行修复完成后做的技能集成：只改技能（SKILL.md / README.md / references/验收清单.md），不动插件。

#	原来写的	改成	依据
1	§3.0：改参"只能走 Python 内核"，且警告"不要写 `op="generator_run"` + 嵌套 `args`"	首选工具直调（`args` 这一层就是 `PARAMS`）；内核写法降为备选；保留旧版迁移说明（v0.9.5 及更早会把 `args` 摊平成顶层 kwarg ⇒ `unexpected keyword argument`，旧插件上照内核写法）	插件 v0.9.6 `generator.py::generator_dispatch` 已修：`op="run"` 时 `args` 原样传；本会话直调实测 `supported`
2	只有 `clean=true/false` 二态	`audit_mesh` / `audit_scene` 顶层 `state`（= `verdict`）三态 `pass`/`fail`/`degraded`；`clean` 收紧为"查完了且没缺陷" ⇒ `clean=false` 有两种成因（确有缺陷 / 没查完），先读 `state`+`reason`，`degraded` 去补查	插件 v0.9.6 `audit.py`：跳过/抛异常的自交检查、`normals_state=unknown`、超面数上限都 → `degraded`
3	`audit_scene` 可当门用（`clean=true`）	默认 `self_intersect=false` ⇒ 只能给 `degraded`；交付验收一律传 `self_intersect:true`；只做"哪几个最脏"的初筛才不开	同上的性能契约 + `warn`/`hint` 原文；`references/验收清单.md` 同步
4	门④写"一致朝外（闭合件有符号体积 > 0）"	逐连通壳判：`normals_state` ∈ `pass`/`fail`/`unknown`/`n/a` + `normals_shells[]`（逐壳 `state`/`signed_volume`/`nested`，合法空腔豁免）；聚合 `signed_volume` 会被"大正向壳 + 小反向壳"抵消成正数，不能当充分条件	插件 v0.9.6 `_shell_normals()`；`unknown` 不许当 pass
5	Recipe 6b 依赖场景里先有 `GEO-track_link`（空场景直接 `KeyError`）	补模板契约①–⑤（原点在起点销轴 / 局部 +X 指下一销 / 下一销在 `(+pitch,0,0)` / 销轴 = 局部 +Z / 只有 z 沿用）+ 从零建可视单节 `build_link_template()` + 链节装配口径表（见 #8）；并写明本配方只解"节距 + 闭合"（相邻节端面贴合；内/外板交替不在范围内）	headless 原样复跑：空场景即可运行，`N=24`、`max\|弦长−p\|` 仍为浮点噪声级
6	"Array 做不到精确节距闭合"、"写实人脸零素材做不到"	改成当前配方边界：Array 的短板是 `FIT_CURVE` 沿曲线的精确弦长节距 + 闭环（直线等距阵列不受影响）；写实人脸是本技能 22 条配方 + 零素材这条路的边界（有参考照片走 Recipe 20 校正，或换外部素材/雕刻素材）	无依据的绝对表述一律收窄到"本配方口径"
7	文档自述体量（`68,823 字符 ≈ 23–29k tokens` / 清单 `3,117 字符`）	更新为编辑后实测的近似值（SKILL.md 约 81k 字符 ≈ 27–34k / 清单约 4.2k 字符 ≈ 1.4–1.8k）	`wc` / `len()` 实测
8	Recipe 6b 验收"履带是一条连通分量"、"共面贴合 ⇒ `audit_overlap` 不报"	按实测改成链节装配口径表：`floaters=[]` + `gate.state` 才是"不散架"（`audit_connectivity` 顶层无 `state`；分量数实测 14）；相邻节 `pair_count=1`（端面共用边）、`audit_interference=unresolved` ⇒ 设计接触白名单化，别拿 `pair_count` 当穿模开关	headless 实测 + `验收清单.md` 连通/干涉两行同步

⚠ 正交/透视公式范围未新增任何数字：v4 已有的 Δz/(D+Δz)、单应跨平面误差逐字保留；
v4 那条"嵌入深度接口表（1–2× 特征尺寸）"已由 v6 取代并删除（见下节），不再是现行口径。

相对 v5 的改动（2026-09-26 · v6）：撤回"固定倍数 / 下限"通则

Lead 复查发现：v4/v5 只是把 5–15mm 换成"1–2× 接口特征尺寸"，仍是同一种规范性固定倍数，且与示例数字互相矛盾（"3mm 板最少 3mm" vs "1.5mm 合格"）。
本次只做定点文本修订（SKILL.md / README.md）：不重跑几何、不动插件、不动 references/验收清单.md。

#	改成
1	删除所有规范性固定倍数 / 百分比 / 下限，以及"5–15mm = 特征尺寸 5–30mm 那一档"的推导：展示拼接可在不改变可见轮廓、不捅穿薄壳下选择隐藏交叠，交叠量由本项目 spec 明文规定并按 spec 复核
2	真实连接不由可视脚本裁定：由设计配合、标准、承载工况、制造工艺与运动间隙规定；几何脚本只答"叠没叠 / 浮没浮 / 穿没穿"，不给结构强度结论
3	示例数字（Ø6→6mm、3mm 板→1.5mm）只属于写明它的那份示例 spec，不是通则
4	`axis_overlap_mm` 的 AABB 读法补前提：仅接口法线与世界轴一致且轴对齐盒适用时才作粗筛；旋转 / 斜置接口沿真实接口的局部坐标量测真实表面，不能挑一根世界轴当深度

历史复盘（§9–§12 与上面的 v4 表）已就地标注被 v6 取代；正文改动清单见 SKILL.md §13。

许可与来源

MIT。派生自两个 MIT 项目（决策树 / 配方 / 坑表 / 六步总纲等），工具调用已改写为本机 blender_rt_* 直连链：

完整归属与本地改动见 NOTICE.md；references/modeling-overview.md 为上游英文原文收录 ——
其中「固定修改器顺序」与「内部面 → Delete Loose」两处旧说法已就地标注纠正（v4，见上表 #6/#7）。