@jojonadam/dsh-blender 0.1.2 → 0.2.0

package/skills/blender-sop/templates/uv_unwrap.md

@@ -0,0 +1,38 @@
+# UV 展开打包工序单（标记缝合边 → 展开 → 打包优化）
+
+> 本表不需要 Blender 即可填写交付（执行工序时才开 Blender）。旧链路只给结论不给「怎么办」，本单是工序级配方。
+
+## 1. 工序（按序执行，不许跳步）
+
+| 步 | 动作 | 操作（Blender） | 自检 |
+|---|---|---|---|
+| 1 | 标记缝合边 | Edit 模式选边 → Mark Seam；曲面按参数方向切（如旋转体沿经线切一刀+收口环切） | 岛数与预期一致（复杂曲面 ≥3 岛） |
+| 2 | 展开 | 全选面 → UV → Unwrap（ANGLE_BASED；参数规整面可直接按参数矩形化铺 UV） | 每岛无拉伸（UV 边长比接近 1） |
+| 3 | 打包优化 | UV → Pack Islands（勾 Blend/Margin；栅格化曲面片做矩形化填满格子） | 打包率过验收线（见 §2） |
+| 4 | 去重叠 | Pack 后查重叠：栅格化统计重叠格数 | 重叠栅格 = 0 |
+
+## 2. 验收线（写死，不许放宽）
+
+| 判据 | 阈值 | 出处 |
+|---|---|---|
+| 打包率（UV 占用面积/图集面积） | **> 0.75** | 判据范式 C1（旧链路 ANGLE_BASED 直展实测仅 0.575；矩形化后 0.91） |
+| 重叠栅格（512² 栅格化） | **= 0** | C1「无重叠」 |
+| UV 面积/3D 面积比 | 0.85 ~ 1.15 | T2.4 判据范式 |
+| UV 边长比（mean/mean） | ≈ 网格整体比例（0.2~0.4 量级） | T2.4 判据范式 |
+| 逐面 UV 无重叠（per-face pair） | **0 对重叠** | T2.4 判据范式 |
+
+## 3. 填写（模型资产交付时）
+
+| 项目 | 值 | 备注 |
+|---|---|---|
+| 资产名 | | 与 asset_list.md 对齐 |
+| 岛数 | | ≥3 为复杂曲面 |
+| 打包率实测 | | 必须 > 0.75 |
+| 重叠栅格 | | 必须 = 0 |
+| 缝合边策略 | | 如「经线一刀+收口环切」 |
+
+## 4. 常见翻车
+
+- 只 Unwrap 不 Pack Islands → 打包率掉到 0.5x（实测 0.575）。
+- 缝合边不闭合 → 岛粘连、局部拉伸。
+- 曲面片直展只填满包围盒 ~79% → 参数矩形化铺满格子（margin 0.0015）。

package/skills/blender-studio/SKILL.md

@@ -76,12 +76,21 @@ python3 scripts/blender_client.py run --script my_export.py --blend scene.blend
 | 用户问题 | 调用技能 |
 |---|---|
 | 找不到 Blender / 版本不对 / 渲染报错 | `blender-env` |
-| 渲染器怎么选、导出规范、CC0 红线 | `blender-sop` |
+| 「渲染出来是黑的 / 导不出去 / 卡住」这类**症状** | `blender-triage`（按现象查，先定位再修） |
+| 渲染器怎么选、导出规范、CC0 红线、交付纪律 | `blender-sop` |
 | 建模、Bevel、修改器、拓扑、UV | `blender-modeling-cookbook` |
 | 5.x 的 API 变化与已知坑 | `blender-5x-pitfalls` |
 | 程序化资产生成、批量、LOD、glTF | `blender-asset-pipeline` |
 | 要实时操控打开着的 Blender | `blender-mcp-bridge` |
 
+## 5.1 交付前三条硬纪律（来自实机测试失分点，对应专家团 v1.3.6）
+
+1. **四个数字先锁死**：资产名 / 尺寸（米）/ 面数预算（目标+上限）/ 导出格式。多产物并行时先写进 asset_list 再动手；任一处想偏离先停下问，不许自改。
+2. **跨表咬合要跑出来**：`python3 skills/blender-sop/scripts/check_table_consistency.py <表A> <表B>`——exit 0 且无输出才算咬合；有输出就按行号改到一致或标「待拍板」。没跑过禁止说「基本一致」。
+3. **命令输出要落盘**：审计/验证类命令的输出重定向到文件（`> audit.log 2>&1`），正文只报「做了什么 + 产物路径」，不拿转述当证据。
+
+四份交付表（asset_list / model_spec / naming_export / delivery_checklist）与两份工序单（uv_unwrap / lighting_exposure）在 `skills/blender-sop/templates/`——不打开 Blender 也能填完交付。
+
 ## 6. 诚实边界
 
 - **headless 只适合确定性任务**：建模、材质、渲染、导出、批量。雕刻、手动绑定、视觉微调这类交互工作，要么用 MCP 接活着的 Blender，要么交给人。

package/skills/blender-triage/SKILL.md

@@ -0,0 +1,139 @@
+---
+name: blender-triage
+description: "按症状查的 Blender 排障表：用户看到的现象→真实原因→具体解法，覆盖渲染/模型/材质/导出/性能/绑定。附「本团做不到什么」的诚实清单。"
+whenToUse: "Blender 建模 / 渲染 / 导出 / 排障 / MCP 接线 时"
+license: MIT
+---
+
+# 排障速查（按症状查）
+
+> **DSH 适配**：本技能来自专家团 v1.3.6。文中的「主理人」= 你本人，「成员 / 派单」= 你的子任务或子代理，「回执」= 你的交付记录。单 agent 场景下这些纪律同样成立。
+
+
+> 用户不会说"我的法线反了"，他会说"渲染出来是黑的"。
+> **先按症状定位，再讲原因。**
+
+## 一 · 三分钟定位（先问这三个）
+
+```
+① 哪个环节出问题？（视图 / 渲染 / 导出 / 导入后）
+② 之前正常过吗？（正常过 → 是改了什么；从没正常 → 是设置问题）
+③ 用什么渲染器？（Eevee / Cycles / 视图只是 Solid）
+```
+
+**这三个答完，80% 的问题能定位。**
+
+---
+
+## 二 · 渲染类
+
+| 症状 | 真实原因 | 解法 |
+|---|---|---|
+| **渲染出来一片黑** | ① 没打灯 ② 世界背景强度 0 ③ 材质输出没接 Surface | 加一盏 Area Light → 检查 World 的 Strength ≥ 0.3 → 检查材质节点有没有连到 `Material Output` |
+| **渲染巨慢** | 采样过高 / 分辨率 4K / 开了体积雾 | 采样先降到 64 试渲；分辨率降到 50% 试；关掉 Volumetrics |
+| **噪点多** | 采样不够 / 没开降噪 | Cycles 开 `Denoise`（OpenImageDenoise），采样 128 就够 |
+| **渲染结果和视图不一样** | 视图是 Solid 或 Material Preview | 按 `Z` 切到 `Rendered`，这才是真实结果 |
+| **Eevee 和 Cycles 差很多** | 两者光照模型完全不同 | Eevee 快但假，Cycles 准但慢。**出成品用 Cycles，试构图用 Eevee** |
+| **渲染到一半崩了** | 内存不足（大纹理/高细分） | 开 `Simplify`（渲染时降细分）；减纹理尺寸到 2K |
+
+---
+
+## 三 · 模型类
+
+| 症状 | 真实原因 | 解法 |
+|---|---|---|
+| **模型看起来是黑的/透明的** | 法线反了 | 编辑模式 `A` 全选 → `Shift+N` 重算法线 |
+| **面数爆炸（几百万面）** | 细分修改器层级太高 / 布尔后没清理 | 细分降到 2-3 级；布尔后跑 `Mesh → Clean Up → Degenerate Dissolve` |
+| **布尔运算失败/破面** | 有非流形边 / 两物体共面 | 先 `Shift+N` 重算法线；把两个物体错开 0.001 避免共面 |
+| **倒角爆掉（模型炸开）** | Bevel 宽度大于局部厚度 | 宽度降到厚度的 1/3 以下；或用 `Clamp Overlap` |
+| **贴图严重拉伸** | 没展 UV / UV 重叠 | `U → Smart UV Project`，先有个能用的 UV |
+| **模型在编辑模式变形异常** | 开了 Proportional Editing | 按 `O` 关掉 |
+| **骨骼绑定后模型撕裂** | 权重自动分配失败（模型有重叠几何） | 先合并重叠点（`M → By Distance`）再自动权重 |
+
+---
+
+## 四 · 材质类
+
+| 症状 | 真实原因 | 解法 |
+|---|---|---|
+| **材质在视图正常，渲染是黑的** | 材质节点没接到 Output / 用了不支持的类型 | 检查 `Principled BSDF` 有没有连到 `Material Output → Surface` |
+| **材质完全没显示** | 视图在 Solid 模式 / 材质槽是空的 | `Z → Material Preview`；检查物体有没有赋材质 |
+| **透明材质不透明** | 5.x 没有 `Transmission` 插槽 | 用 `Alpha` + `Settings → Blend Mode → Blend` |
+| **颜色偏灰/发白** | 色彩空间设错 | 纹理节点 `Color Space` 设 `sRGB`（贴图）或 `Non-Color`（法线/粗糙度） |
+| **程序纹理导出后消失** | glTF 不支持节点纹理 | 把程序纹理**烘焙**成贴图（`Bake → Diffuse`）再导出 |
+
+---
+
+## 五 · 导出类
+
+| 症状 | 真实原因 | 解法 |
+|---|---|---|
+| **glTF 导不进引擎** | 有非流形 / 材质不支持 | 先 `Shift+N` + 清理；材质用 Principled 基础参数 |
+| **导出的模型没材质** | 材质没打包 / 用了节点纹理 | 导出时勾 `Materials`；纹理**打包进文件**（`File → External Data → Pack Resources`） |
+| **导出后颜色不对** | 顶点色没被材质节点树引用 → `COLOR_0` 被降为 ubyte；或色彩空间设置不对 | 把顶点色接进材质（或导出时 `export_vertex_color='ACTIVE'`）；再查色调映射与引擎 gamma（见 `blender-5x-pitfalls` 致命级 3 的自检脚本） |
+| **FBX 导入 Unity 缩放过小/过大** | Blender 单位 vs Unity 单位（0.01） | 导出 FBX 时 `Scale = 1.0`，或在 Unity 里 Import Settings 改 Scale Factor |
+| **USD 丢材质** | USD 材质绑定方式不同 | 改用 glTF 或 FBX；USD 只用于纯几何交换 |
+| **导出文件巨大** | 纹理没压缩 / 面数太高 | 纹理转 JPG（不带 alpha 的）；加 Decimate 减面 |
+
+---
+
+## 六 · 性能类
+
+| 症状 | 真实原因 | 解法 |
+|---|---|---|
+| **视图转不动（卡）** | 细分修改器在视图也生效 | 修改器面板把细分 `Viewport` 降到 1，`Render` 保持 3 |
+| **打开文件要几分钟** | 场景物体太多 / 纹理太大 | 用 Collection 分组，隐藏不用的；纹理降到 2K |
+| **布料/流体模拟崩了** | 参数太激进 / 碰撞体太薄 | 降 `Quality Steps`；碰撞体加厚；先小规模试跑 |
+| **GPU 没被用上** | Cycles 设备没设成 GPU | `Preferences → System → CUDA/OptiX/Metal` 勾上，渲染设置里选 GPU |
+
+---
+
+## 七 · 动画类
+
+| 症状 | 真实原因 | 解法 |
+|---|---|---|
+| **导出动画丢失** | 没烘焙 / Action 没推入 NLA | 导出前 `Bake Action`；或把 Action 推到 NLA 轨道 |
+| **动画在引擎里速度不对** | 帧率不一致 | Blender 场景 FPS 和引擎 FPS 对齐（通常 30 或 24） |
+| **静止姿势就变形** | 绑定时的 rest pose 不是建模姿势 | 绑定前 `Apply → All Transforms`，再设 rest pose |
+
+---
+
+## 八 · 我们做不到的（重要）
+
+**写清楚做不到，比写清楚能做到更能建立信任。**
+
+```
+❌ 不能判断"好不好看"
+   审美是人的事。我们能保证结构正确、参数合理，不能保证好看。
+
+❌ 不能保证物理模拟一定成功
+   布料/流体/刚体是非线性系统，同样的参数换台机器结果可能不同。
+   我们能帮你排查，不能保证一定不崩。
+
+❌ 不能绕过硬件
+   8K 纹理 + 500 万面 + Cycles 4K，就是要渲很久。换谁都一样。
+
+❌ 不能保证 glTF 在所有引擎里完美
+   glTF 是通用格式，但每个引擎的实现有差异。
+   复杂材质在 Unity/UE/Godot 里表现会不同。
+
+❌ 不能替代美术基础
+   我们能告诉你"这里光影平了"，不能告诉你"该怎么设计才好看"。
+
+❌ 不能保证 MCP 一定连通
+   Blender MCP 需要你在 Blender 里手动启动服务端（N 面板 → Start MCP Server）。
+   环境不通时，我们只做设计和文档，不谎称已经操控了 Blender。
+```
+
+---
+
+## 九 · 什么时候该换方案
+
+**这比"怎么修"更重要。**
+
+| 情况 | 该换什么 |
+|---|---|
+| 模型面数 > 500 万，且需要实时 | 别在 Blender 里硬撑，走 LOD + 烘焙 |
+| 需要影视级特效 | Blender 能做，但成本高于 Houdini |
+| 只需要简单几何 | 用参数化建模（Grasshopper / OpenSCAD）更快 |
+| 目标是网页 3D | 先定引擎（Three.js / Babylon），按它的限制建模 |