随包建模 skill 拆解:dsh-blender-plugin blender-modeling 三层技能结构与设计思路
随包建模 skill 拆解:dsh-blender-plugin blender-modeling 三层技能结构与设计思路
dsh-blender-plugin 随包携带的 blender-modeling 建模 skill,把"AI 驱动 Blender 建模"的完整作业流程打包进插件:装插件即自动注册,无需单独 clone。本文拆解它的三层技能结构(随包分发层 / SKILL.md 主作业层 / references 深水参考层),并讲清背后的设计思路,帮你看懂这套"架构优先"的建模方法论是怎么落地的。
📌 一句话定位:把建模 SOP 写成机器能照抄的作业指导书,再让它随插件走。 你不需要背 Blender 配方,模型会按目录里的能力自己选工具、每步留证据、过门再交付。
一、先看全貌:一套 skill,三层分工
很多人第一次打开 skills/blender-modeling/ 会以为是"一个文档"。其实它是三层各司其职的结构——分发、作业、参考分开,既省 token 又不丢细节。
| 层级 | 载体 | 角色 | 什么时候被读到 |
|---|---|---|---|
| 🔧 第一层 · 随包分发层 | skills/blender-modeling/ 目录 + 插件注册逻辑 | 把 skill 自动注册为 bundled skill | 装插件、找技能列表时 |
| 📖 第二层 · SKILL.md 主作业层 | SKILL.md | 建模/装配的架构优先作业指导书 | 真正动手建模、走流程时 |
| 🗂️ 第三层 · references 深水参考层 | references/ 4 份文档 | 深水参考 + 独立验证者专用清单 | 配方不够用、做验收时 |
这种"主文档瘦身、深水知识外置"的拆法,是整套 skill 最值得学的一点:模型平时只吃最少的上下文,需要时才翻对应的层。
二、第一层拆解:随包分发——装插件就有,不用再 clone
这一层解决"skill 怎么到模型手里"的问题,藏在插件的 bundled 注册逻辑里(见 src/index.ts 与编译产物 lib/index.js)。
2.1 核心机制:v2.2.0 起自动注册为 bundled skill
- skill 从独立仓库并进插件包,落在
skills/blender-modeling/; - 宿主有 skills 服务时,插件启动即注册一个
source: 'bundled'的 provider,读取 SKILL.md 的 YAML frontmatter(name/description/license)建技能目录; - 结果:装插件并重启后,会话技能列表里直接出现
blender-modeling,遇到"建一个 / 按参考图还原 / 多件装配"类任务会自动加载。
⚠️ 关键细节:
SKILL.md必须保留 YAML frontmatter,加载器靠它建目录。frontmatter 缺失或不合法只会打一条 warn,不影响工具面——这就是"skill 在,但可能没注册上"的常见原因。
2.2 优先级与移植
- 优先级规则:若你此前在
~/.dsh/skills/blender-modeling(user 级)放过独立副本,它会优先于包内 bundled 副本(rank:user 400 < bundled 600)。两份内容一致,不影响使用;想强制包内版,删掉用户级目录即可。 - 给别的宿主用(Claude Code / Codex / Cursor…):包目录就是一份标准
skills/<name>/SKILL.md,直接软链/拷贝,或用 install.sh 装到~/.dsh/skills/。
这一层的设计意图很清楚:降低"技能可达性"的门槛——让建模能力像插件工具一样随装随有,而不是让每个用户各自 clone 一个"只有作者知道"的仓库。
三、第二层拆解:SKILL.md——一份"架构优先"的作业指导书
这是整套 skill 的心脏,约 82KB / 1146 行(SKILL.md)。它不是"Blender 教程合集",而是先定流程、再选工具、每步留证据的作业规范。
3.1 先选形,再走流水线
开宗明义一句话(SKILL.md):先定形状,再走流程,改一步看一眼。
- 按决策树先选形:分面硬表面 / 光滑硬表面 / 有机 / 重复阵列 / 布尔;
- 再走流水线:冻结规格 → 场景准备 → 白模 → 粗形精修 → 修改器栈 → 清理 → 装配/验收 → 交付;
- 硬规则:不要一口气写完整个模型再回来看,每一步都要有画面或数字证据。
3.2 三条铁律:op-first / evidence-first / verdict-first
这是全文最能体现"设计思路"的段落(SKILL.md §1.2):
| 铁律 | 含义 | 一句话 |
|---|---|---|
| A · op-first | 有 plan op 就不许手写等价几何/检查 | 有工具就用工具,别重复造轮子 |
| B · evidence-first | 每步至少一种证据(图/数字/文件) | "看起来对"不算证据 |
| C · verdict-first | 先看 verdict(pass/fail/degraded),不只看 ok |
ok=true 只代表"跑完了" |
💡 为什么强调"先看 verdict 不看 ok":这套体系所有门(audit/gate/asm/visualreport/eval)都是三态而非红绿二态——
degraded表示"没查完/证据不足",绝不是通过。这条纪律直接避免了"把跳过检查误读成检查通过"这类典型事故。
3.3 标准状态机:S0–S8,每步都有输入/输出/门
SKILL.md §2 把建模切成 9 个阶段,不许跳阶段:
| 阶段 | 目标 | 出门条件(门) |
|---|---|---|
| S0 规格/草稿 | 定范围、单位、接口、验收门 | 字段完整、无 mm 级臆造 |
| S1 参考量测 | 把图变成 px_per_mm + 尺寸 | 标定可复算;无标定只做比例 |
| S2 白模/基线 | 快速出形体比例 | 3 视图可看、bbox 合理 |
| S3 形体精修 | 放样/截面/特征线/雕刻 | 尺寸/比例达标 |
| S4 硬表面细节 | 倒角/布尔/阵列/扫掠 | 无退化面、法线正确 |
| S5 单件体检 | 网格/法线/UV/打印 | state=pass |
| S6 装配 | 清单/扫描/修复/门 | gate verdict=pass |
| S7 视觉验收 | 同机位像不像 | verdict=pass 或明确 unresolved |
| S8 交付 | 导出/参考包/账本 | manifest+md5+gate 回执齐全 |
配一张工具选择矩阵(§3):每个任务列"第一选择(插件架构)/ 第二选择(仅当无 op)/ 验收"。判据只有一条:能用第一选择就不用第二选择——第二选择必须在回执里写明"为什么不用插件 op"。
这套"先查目录、再选通路"的结构,本质上是在对抗自由发挥的不可复现:同一个任务,不同人/不同会话走出来的路径应该一致。
四、第三层拆解:references/——深水知识与"验证专用"清单
主文档只放"架构优先"的默认路径,深水知识全部外置到 references/,4 份文档各管一块:
| 文档 | 用途 | 什么时候读 |
|---|---|---|
| modeling-overview.md | 上游英文原文深水参考(bpy.ops vs bmesh、基本体、硬表面、修改器、坑) | 配方不够用、要 bmesh 级精度时 |
| multiview-calibration.md | 三视图联立标定脚本(纯标准库,带 --selftest) |
走参考图量测(§0.6.1)时 |
| 参考图通用还原SOP.md | 参考图还原九步(先量→放样→特征线→同机位验收) | 有外轮廓的对象(车辆/人形/家具…) |
| 验收清单.md | 独立验证子代理专用,只读这一份 | 起"干净验证者"时 |
4.1 验收清单是"token 预算"的样板工程
验收清单.md 开头就点明动机:验证者不该加载整本 82KB 的 SKILL.md(约 20–25k tokens)。
- 把单次验证输入压到:工具 schema ≈2.8k + 本文件 ≈4.2k + 回执,对比加载整本的 27–34k;
- 只给"数值门表 + 输出格式",要求数值门脚本自己跑、关键项换一条计算通路复核(反 Goodhart),证据不足就写
unresolved,不许硬判。
🎯 这体现了一个成熟 skill 的通用做法:按"谁来读、读多少"分层设预算。构建者读全量,验证者读精简——既保证独立复核,又不把上下文撑爆。
五、设计思路提炼:这套 skill 到底"聪明"在哪
把三层串起来看,能总结出 5 条可迁移的设计原则:
- 架构优先(op-first):有插件 op 就不许手写等价逻辑。建模流程被"插件架构"约束住,结果才可复现。
- 证据链强制:画面是证据、数字是判据、
verdict是结论;没有数字的"完成了"一律视为未完成。 - 三态门(pass/fail/degraded):比红绿二态多一个"没查完"态,逼你补查而不是放过——
skipped不是通过。 - GUI 优先、无头备用:默认开 GUI 走交互回路;GUI 不可用时用持久 worker 做"改一步、同步看一步",不退化成无反馈批处理。
- 上下文分层预算:主文档瘦身、深水外置、验证者专用精简清单——让模型平时吃最少,需要时翻对应层。
来源与许可
该 skill 由两个 MIT 项目的"建模流程部分"融合改写而成(完整归属见 NOTICE.md),工具调用统一换成本插件 blender_rt_* 直连链:
- RobLe3/cc-blender-skill:决策树、配方、坑表、深水参考;
- arjun988/blender-skills:六步总纲、集合结构、修改器规则、清理清单、MUST / MUST NOT。
本目录同样以 MIT 提供(见 LICENSE),v2.6 起以本仓库为真源维护(见 README.md)。
六、怎么开始用 / 适合谁
- 新手:装插件重启 DSH,在会话里让模型加载
blender-modeling,直接说"给我建个 XX / 按这张参考图还原",技能会自动接管流程。 - 进阶 / 多 Agent 并行:先冻结
spec.py/manifest.json,按写作用域分工,装配后统一走asm_scan → asm_repair → asm_gate(§0.5)。 - 验收/交付:对照 SKILL.md §12 交付前最终清单 逐条打勾,独立验证者只读 验收清单.md。
✅ 小结:blender-modeling 的三层结构,本质是把"建模经验"工程化——分发层让能力随装随有,主作业层把流程钉成可复现的架构,参考层把深水知识按需外置。看懂这三层,你就拿到了自己给任意领域写"架构优先 skill"的模板。