@jojonadam/dsh-blender 0.0.0-stage → 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 JOJO & Adam
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,69 @@
-# Temporary Holding Version
+# dsh-blender · JOJO&Adam
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Blender 在 DeepSeek Harness 里的生产包：headless 跑 bpy 脚本、渲染、导出 glTF，外加建模技法、5.x 踩坑和程序化资产管线。
+
+不是“教你怎么点 Blender”，是让 agent 真的能把场景建出来、渲染出来、导出成游戏资产。
+
+## 安装
+
+```bash
+# 从 npm
+dsh plugin --profile web add @jojonadam/dsh-blender        # Web 版
+dsh plugin --profile desktop add @jojonadam/dsh-blender    # 桌面版
+
+# 本地开发
+dsh plugin --profile desktop add link:/absolute/path/to/dsh-blender
+```
+
+## 30 秒上手
+
+前置：本机装有 Blender 5.2 LTS（macOS 默认 `/Applications/Blender.app`）。
+
+```bash
+# 1. 体检
+python3 skills/blender-studio/scripts/blender_client.py doctor
+
+# 2. 冒烟渲染（默认立方体，256×256）
+python3 skills/blender-studio/scripts/blender_client.py smoke --res 256
+
+# 3. 跑示例：参数化地砖 → 渲染 → 保存 .blend → 导出 .glb
+python3 skills/blender-studio/scripts/blender_client.py run \
+  --script skills/blender-studio/examples/make_tiles.py \
+  --outdir outputs/blender/tiles
+```
+
+## 包含
+
+| 技能 | 用途 |
+|---|---|
+| `blender-studio` | 总入口：体检、headless 执行、渲染、导出（含客户端与示例） |
+| `blender-env` | 找不到 Blender、版本、METAL、黑图、权限、bpy 报错 |
+| `blender-sop` | 5.2 基线、Cycles/EEVEE 抉择、CC0 红线、导出纪律 |
+| `blender-modeling-cookbook` | 参数化建模、BMesh、修改器栈、拓扑、UV、选择性 Bevel |
+| `blender-5x-pitfalls` | 5.x 的 API 变更与已知坑 |
+| `blender-asset-pipeline` | 程序化资产、批量、LOD、glTF 导出、连续网格反模式 |
+| `blender-mcp-bridge` | 需要实时操控打开着的 Blender 时接 MCP |
+
+## 设计边界
+
+- 默认 headless：确定性任务（建模/材质/渲染/导出）可复现；
+- 雕刻、手动绑定、视觉微调交给 MCP 或人；
+- 不代装 Blender、不代下资产（CC0 规则见 SOP）；
+- 只在本机执行，不经过云端。
+
+## 验证
+
+```bash
+node test/provider.test.mjs
+python3 skills/blender-studio/scripts/blender_client.py doctor
+```
+
+实机验证：Blender 5.2.1 LTS · macOS · METAL，EEVEE 256×256 冒烟 3.5s；参数化地砖（9 块 + 选择性 Bevel + glTF）3.6s（2026-10-19）。
+
+## 品牌
+
+JOJO & Adam · <https://jojo-adam.com>
+
+## License
+
+MIT

package/cordis.patch.yml

@@ -0,0 +1,3 @@
+- insert:
+    - id: jojo-adam-blender
+      name: '@jojonadam/dsh-blender'

package/icon.svg

@@ -0,0 +1,14 @@
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 96 96" width="96" height="96" role="img" aria-label="dsh-blender">
+  <defs>
+    <linearGradient id="g" x1="0" y1="0" x2="96" y2="96" gradientUnits="userSpaceOnUse">
+      <stop offset="0" stop-color="#f59e0b"/>
+      <stop offset="1" stop-color="#3b82f6"/>
+    </linearGradient>
+  </defs>
+  <rect width="96" height="96" rx="22" fill="#0f1117"/>
+  <g fill="none" stroke="url(#g)" stroke-width="4" stroke-linejoin="round">
+    <path d="M48 18 78 34 48 50 18 34Z"/>
+    <path d="M18 34v28l30 16V50"/>
+    <path d="M78 34v28L48 78"/>
+  </g>
+</svg>

package/lib/index.js

@@ -0,0 +1,113 @@
+/**
+ * @jojonadam/dsh-blender — bundled skill provider.
+ *
+ * Discovers every skill bundle under `skills/<name>/SKILL.md` and serves it to
+ * the DSH skill registry, with the skill directory as its resource base so
+ * `scripts/` and `examples/` resolve normally.
+ *
+ * @module @jojonadam/dsh-blender
+ */
+import { readFileSync, readdirSync, statSync } from 'node:fs'
+import { basename, dirname, join } from 'node:path'
+import { fileURLToPath } from 'node:url'
+
+const PROVIDER_NAME = 'jojo-adam-blender'
+const SKILLS_DIR = fileURLToPath(new URL('../skills/', import.meta.url))
+/** Same rank as other bundled skill roots (dsh-skill-filesystem BUNDLED_SKILL_RANK). */
+const BUNDLED_SKILL_RANK = 600
+
+/** Split `---` YAML frontmatter from the body. Handles single-line quoted values. */
+function parseFrontmatter(text) {
+  if (!text.startsWith('---')) return { data: {}, body: text }
+  const end = text.indexOf('\n---', 3)
+  if (end === -1) return { data: {}, body: text }
+  const raw = text.slice(3, end).trim()
+  const body = text.slice(end + 4).replace(/^\r?\n/, '')
+  const data = {}
+  for (const line of raw.split(/\r?\n/)) {
+    const match = /^([A-Za-z][\w-]*):\s*(.*)$/.exec(line)
+    if (match === null) continue
+    let value = match[2].trim()
+    if (
+      (value.startsWith('"') && value.endsWith('"')) ||
+      (value.startsWith("'") && value.endsWith("'"))
+    ) {
+      value = value.slice(1, -1)
+    }
+    data[match[1]] = value
+  }
+  return { data, body }
+}
+
+function skillDirectories() {
+  let entries
+  try {
+    entries = readdirSync(SKILLS_DIR, { withFileTypes: true })
+  } catch {
+    return []
+  }
+  return entries
+    .filter((entry) => entry.isDirectory())
+    .map((entry) => join(SKILLS_DIR, entry.name))
+    .filter((dir) => {
+      try {
+        return statSync(join(dir, 'SKILL.md')).isFile()
+      } catch {
+        return false
+      }
+    })
+}
+
+function readSkill(dir) {
+  const locator = join(dir, 'SKILL.md')
+  const { data, body } = parseFrontmatter(readFileSync(locator, 'utf8'))
+  const name = data.name ?? basename(dir)
+  return {
+    candidate: {
+      name,
+      description: data.description ?? '',
+      ...(data.whenToUse === undefined ? {} : { whenToUse: data.whenToUse }),
+      invocation: { modelInvocable: true, userInvocable: true },
+      provider: PROVIDER_NAME,
+      source: 'bundled',
+      resourceBase: { kind: 'directory', path: dir },
+      rank: BUNDLED_SKILL_RANK,
+      locator,
+    },
+    content: body,
+  }
+}
+
+const provider = {
+  name: PROVIDER_NAME,
+  async list() {
+    return skillDirectories().map((dir) => readSkill(dir).candidate)
+  },
+  async get(candidate) {
+    const loaded = readSkill(dirname(candidate.locator))
+    return {
+      name: loaded.candidate.name,
+      description: loaded.candidate.description,
+      ...(loaded.candidate.whenToUse === undefined
+        ? {}
+        : { whenToUse: loaded.candidate.whenToUse }),
+      invocation: loaded.candidate.invocation,
+      provider: PROVIDER_NAME,
+      source: 'bundled',
+      resourceBase: loaded.candidate.resourceBase,
+      content: loaded.content,
+    }
+  },
+}
+
+/** Cordis plugin name. */
+const name = 'dsh-blender'
+/** Service required by the bundled provider. */
+const inject = ['skills']
+
+/** Register the bundled skill provider on `ctx.skills`. */
+function apply(ctx) {
+  ctx.skills.registerProvider(() => provider)
+}
+
+export { apply, inject, name }

package/package.json

@@ -1,6 +1,54 @@
 {
   "name": "@jojonadam/dsh-blender",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.0",
+  "description": "Blender production pack for DeepSeek Harness: headless bpy runner, render/export helpers, modeling cookbook, 5.x pitfalls and procedural asset pipeline. 本地建模 · 零依赖客户端 · 5.2 LTS 校准。",
+  "type": "module",
+  "main": "lib/index.js",
+  "exports": {
+    ".": "./lib/index.js",
+    "./cordis.patch.yml": "./cordis.patch.yml",
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "lib",
+    "skills",
+    "cordis.patch.yml",
+    "icon.svg",
+    "README.md",
+    "LICENSE"
+  ],
+  "keywords": [
+    "dsh-plugin",
+    "deepseek-harness",
+    "blender",
+    "bpy",
+    "3d",
+    "gltf",
+    "procedural-assets"
+  ],
+  "license": "MIT",
+  "author": "JOJO & Adam",
+  "homepage": "https://jojo-adam.com",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/JOJO-Adam/dsh-blender.git"
+  },
+  "engines": {
+    "dsh": ">=0.2.0-rc.2",
+    "node": ">=20"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "bugs": {
+    "url": "https://github.com/JOJO-Adam/dsh-blender/issues"
+  },
+  "peerDependencies": {
+    "@deepseek-ai/cordis": "~4.0.5"
+  },
+  "dsh": {
+    "bundle": {
+      "patch": "./cordis.patch.yml"
+    }
+  }
+}

package/skills/blender-5x-pitfalls/SKILL.md

@@ -0,0 +1,42 @@
+---
+name: blender-5x-pitfalls
+description: "Blender 5.x 踩坑清单（锚定 5.2 LTS）：Bevel 引用与限角陷阱、bevel_weight 移除、材质节点创建、Principled 无 Transmission、glTF 丢色 bug、transform_apply 方向陷阱。"
+whenToUse: "Blender 5.x / 版本升级 / Bevel / 材质 / glTF 导出 / transform_apply 时"
+license: MIT
+---
+
+
+# Blender 5.x 踩坑清单（blender-5x-pitfalls）
+
+> DSH 执行层（headless 跑 Blender、渲染、导出）：见 `blender-studio` 技能。
+
+
+**锚定 5.2 LTS。** 本环境已踩过的真实 bug，建脚本前先查，避免重蹈。详见 `blender-sop` / `blender-asset-pipeline` / `blender-modeling-cookbook`。
+
+## 🔴 致命级（必踩无疑，先读）
+
+1. **Bevel 引用**：用 `obj.modifiers.new(name="Bevel", type='BEVEL')` 拿引用，不用 `bpy.ops.object.modifier_add(type='BEVEL')` 后按名 `obj.modifiers["Bevel"]` 取 —— 5.x 报 `key "Bevel" not found`。
+2. **Bevel 必须限角**：`limit_method='ANGLE'` + `angle_limit`（如 40°）。默认 `NONE` 会把**所有边（含平顶内部网格线）全倒角** → 平顶重引缝。限角后只磨圆崖壁/外缘（90°），平顶 0° 不动。
+3. **glTF 色导出 bug（5.2）**：顶点色→白色 `COLOR_0`(ubyte)+畸形 `COLOR_1`(ushort)；纯色材质→无 `pbrMetallicRoughness`。**对策：GLB 只出几何，颜色全在下游引擎侧套。** `export_scene.gltf` **无 `export_colors` 参数**（5.x 已移除）→ 用 `export_format='GLB', export_materials='EXPORT'`。
+4. **`transform_apply(location=True)` 把 `obj.location` 归零**：apply 之后用 `obj.location.x/y` 判方向会符号全翻 → 整块所有竖直棱被误选。**改用顶点包围盒中心** `0.5*(min+max)` 判方向。
+
+## 🟠 高频级
+
+5. **`MeshEdge.bevel_weight` 已移除**（5.x）：改成网格属性 `bevel_weight_edge`，但 Bevel `limit_method='WEIGHT'` 实测 flaky。最稳 = `bmesh.ops.bevel(geom=[选中棱], affect='EDGES', ...)` 直接倒角，版本无关。
+6. **新材质无自动命名**：`node_tree.nodes.clear()` 后显建 Output + BSDF。
+7. **`ColorRamp` element `.color` 需 RGBA 四元组**（4 个分量）。
+8. **5.x Principled BSDF 无 `Transmission` 输入**：透明水面只调 `blend_method='BLEND'` + Alpha，别找 Transmission 插槽。
+9. **Eevee 已重写（EEVEE-Next）**：不假设 4.x 旧 Eevee 行为；灯光/材质节点差异。
+10. **`look` 回传被过滤**：部分环境 "model does not support images" → agent 无法视觉自检，靠客观 DIAG/PROOF（法线分布/坐标/渐变顶点数）+ 用户眼睛终审。
+
+## 🟡 架构级（反模式）
+
+11. **逐立方体各自顶点色 = 缝 + 色糊**：地面/地形必须用一整张连续 heightfield，顶点色 splat 只在边界带、块中心纯色。
+12. **bmesh 跨会话 bevel 报 `BMEdge has been removed`**：选中+bevel+to_mesh+free 必须在**单 bmesh 会话内**完成。
+13. **过渡名无拓扑后缀互相覆盖**：加 `_inland/_side/_corner` 区分。
+
+## 关联
+
+- 版本/渲染器/导出纪律总纲 → `blender-sop` §1/§2/§4。
+- 连续网格 + Bevel 算法 + 选择性倒角 → `blender-asset-pipeline` / `blender-modeling-cookbook` §3–§5。
+- 工具名对齐（mcp-for-blender vs 旧 blender-mcp）→ `blender-mcp-bridge`。

package/skills/blender-asset-pipeline/SKILL.md

@@ -0,0 +1,113 @@
+---
+name: blender-asset-pipeline
+description: "Agent 驱动的程序化资产管线：先设计再动手，AI 写参数化 bpy 脚本 + 自检 + glTF 导出，人负责美术方向。覆盖三硬限制、Bevel 圆角、CC0 拉取、LOD 导出与连续网格反模式。"
+whenToUse: "Blender 资产管线 / 程序化生成 / 游戏资产 / glTF / LOD / 批量 时"
+license: MIT
+---
+
+
+# Blender 资产管线 · 设计优先的协作建模
+
+> DSH 执行层（headless 跑 Blender、渲染、导出）：见 `blender-studio` 技能。
+
+
+**先设计，再动手；代码即资产表征，用户定美术方向。**
+
+本技能把「Agent 用 Blender 建模」的圈内先进经验固化为可复用流程。核心思想来自 LL3M（arXiv 2508，把 3D 生成重定义为写可解释 bpy 代码）、AAA Blender Modeling Playbook（参数化优先 + 精修循环）、StraySpark（数百小时实战的三条硬限制）。**本版已通用化**：剥离了原 Seele 小岛项目的 6×6 演示夹具、TYPE_MAP/HEIGHT_MAP 硬编码、Godot 侧上色段落与项目红线，仅保留可复用的技法与纪律。
+
+## 适用场景
+
+- 为游戏 / AR 批量生成 low-poly / 圆润风格 3D 模块：地形 tile、props（树/灌丛/礁石/小屋）、角色占位。
+- 已接 Blender MCP（mcp-for-blender），想用 agent 脚本化批量建模，而非手动点菜单。
+- 要把程序化方块占位升级为圆润 low-poly 视觉（逃离 Minecraft 感）。
+- 需要「参考图 → Spec → 参数化生成 → 截图检视 → 导出 → 引擎实测」的闭环。
+
+## 核心原则：先设计，再动手
+
+绝不在没有 brief/spec 的情况下动网格。每个资产走：
+
+```
+简报&参考 → Spec 表(锚定数值) → 参数化构建 → 截图检视 → 导出 → 引擎实测 → 修订
+```
+
+- **Reference-grounded**：动手前定 1–3 张参考图（动森/朋友生活/GoGoTown 截图，或 Poly Pizza CC0 模型，或用户给的方向）。无参考不建模。
+- **Spec 表锚定数值**：尺寸（如 1×1 grid 单位）、三角预算（tile ≤ 200、树 ≤ 1500）、配色、pivot。数值写死 → agent 行为确定、可复现。
+- **参数化 > 生成式 > 基元**：优先用参数化库/脚本；外部 AI 生成（`generate_3d` / Hunyuan3D）次之；纯基元 blockout 仅做占位。
+
+## 三条硬限制（必守，来自 StraySpark）
+
+1. **创意拓扑不是 agent 的活**：LLM 出不了生产级拓扑。agent 只出 blockout / 占位 / low-poly 代理；圆润比例、轮廓、配色由用户定。手动重拓扑/UV/绑定/动画必须人审。
+2. **重操作会超时**：细分(Subsurf)、重拓扑、纹理烘焙可能超过 MCP 工具超时（通常 60–120s）。大任务拆小步；或手动跑长任务。
+3. **agent 视觉反馈有限**：靠 `look` 渲图 / `get_scene_info` 拓扑事实，而非自己"看到"渲染。最终裁判是**用户眼睛 + 游戏引擎实跑**，不是 agent 自认。
+
+## 标准闭环（Phase A–E）
+
+| 阶段 | 做什么 | 谁 | 出口 |
+|---|---|---|---|
+| A 简报+参考 | 定 1–3 张参考图 + 写 Spec 表（尺寸/三角预算/配色/pivot） | 用户给方向 | Spec 表 |
+| B 参数化构建 | bpy + Bevel 生成 low-poly，或 `generate_3d` 拉云端模型进来精修 | agent | .blend |
+| C 截图检视 | `look` 渲 turntable/接触表，对照 Spec 自检 3 个最高影响问题 | agent | 截图+缺陷清单 |
+| D 导出 | glb → 资产目录，apply transform + 可选 Decimate LOD | agent | .glb（几何-only） |
+| E 引擎实测 | 引擎内替换占位、跑场景看比例/锚点/视觉 | 用户+agent | 修订项 |
+
+> ⚠️ 工具名对齐 mcp-for-blender：阶段 C 用 `look`（非旧版 `get_viewport_screenshot`）；阶段 B 云端造模用 `generate_3d`（非旧版 `generate_hyper3d_model`）；CC0 直拉用 `search_assets`（非旧版 `get_polyhaven_assets`）。
+
+## 关键技术（逃离 Minecraft 方块感）
+
+- **Bevel 倒角修改器**给 tile/道具圆角 → 立刻脱离立方体棱角（圆润 low-poly 关键一招）。
+- **BMesh `from_pydata`** 从顶点/面数据建网格；`bmesh.ops` 做 extrude/subdivide/translate。改完 `bm.to_mesh()` + `bm.free()`。
+- **修改器栈**（脚本化）：Bevel(圆角) / Solidify(厚度) / Subdivision(平滑，省用) / Array(阵列) / Mirror(对称)。
+- **fBm/Perlin 噪声**（`mathutils/noise` 或 `noise` 库）做地形起伏；**L-system 思路**做树。
+- **glTF 2.0 二进制导出** `bpy.ops.export_scene.gltf(...)`；**Decimate** 生成 LOD 层级（LOD1=50%、LOD2=75%、LOD3=90% 缩减）。
+- **Flat shading** 切换可出风格化块面（是「风格化」不是「像素化」）。
+
+## 缝消除 & Blender 5.x 踩坑（实战沉淀 · 高复用）
+
+### 地面/地形必须「合并连续网格」，不能用「一堆独立方块各自做顶点色」
+- **反模式（踩过）**：每个格子一个独立 cube mesh，各自 `bevel` + 各自顶点色向邻居渐变。两根打脸：① 每格独立 mesh → 倒角后每格成独立圆枕，枕间露沟槽 → **网格缝更明显**；② 草块贴沙边染向沙、沙块贴草边染向草，两边同染 → 1 格宽沙环被草色吃掉、水边糊成 muddy 窄带。
+- **正确架构（对标动森/朋友生活/GoGoTown）**：地面 = **一整张连续网格（heightfield）**，不是一堆独立方块。
+  - 平地区域是一张连续平面 → **根本没有网格缝**。
+  - 顶点色 splat 混合**只在边界带**做、块中心保持纯色（每格 SUB×SUB 子顶点，中心顶点纯色）→ 沙不被吃、水边干净。
+  - 高度差处才生**崖壁/岸壁**（earth 材质，double-sided 免法线朝向烦恼）。
+  - 倒角只对**整张合并 mesh** 做且**限角** → 只磨圆崖壁/外缘，平顶 0° 绝不倒角 → 平顶无缝、圆润感留在该在处。
+- 同高邻居**共享顶点**（字典 key 复用）→ 顶面对接无缝；只有临不同地形类型（非水）的邻居才 smoothstep 边界带渐变。水作为独立平面，陆地颜色**绝不向水晕染**。
+
+### Blender 5.x 三个必记坑
+1. **Bevel 用 `obj.modifiers.new(name="Bevel", type='BEVEL')` 拿回引用**，不用 `bpy.ops.object.modifier_add(type='BEVEL')` 后按名 `obj.modifiers["Bevel"]` 取（5.x 报 `key "Bevel" not found`）。
+2. **Bevel 必须 `limit_method='ANGLE'` + `angle_limit`（如 40°）**：默认 `NONE` 会**把所有边（含平顶内部网格线）全倒角** → 平顶重引缝。限角后只磨圆崖壁/外缘（90°），平顶 0° 不动。
+3. **5.x 材质/导出**：① 新材质 `node_tree.nodes.clear()` 后显建 Output+BSDF（无自动命名）；② `ColorRamp` element `.color` 需 RGBA 四元组；③ 5.x Principled BSDF **无 `Transmission`** 输入 → 透明水面只调 `blend_method='BLEND'` + Alpha；④ `export_scene.gltf` **无 `export_colors` 参数**（5.x 已移除）→ 直接 `export_format='GLB', export_materials='EXPORT'`。
+4. **顶点色连续网格优于逐立方体**：连续网格上 splat 顶点色才能跨边界无缝衔接；逐立方体各自顶点色无法跨 mesh 衔接（同反模式①）。
+5. `look`/`get_viewport_screenshot` 在部分环境回传被过滤（"model does not support images"）→ **AI 无法自检视觉**，靠客观 DIAG/PROOF（面法线分布、坐标、渐变顶点数）佐证 + 用户眼睛终审。
+6. **`transform_apply(location=True)` 会把 `obj.location` 重置为 0**（位置已烘进顶点数据）。凡在 apply 之后用 `obj.location.x/y` 判定方向（如"哪条竖直棱属于哪一侧"）都会退化：坐标全相对 0 → 符号全为负 → **整块所有竖直棱被误选**。**修复**：方向判定改用网格顶点真实包围盒中心 `ocx=0.5*(min+max x)`, `ocy=0.5*(min+max y)`。强烈建议：倒角/方向相关逻辑一律用顶点包围盒中心，不碰 `obj.location`。
+
+### 选择性倒角实现（实测坑）
+- `MeshEdge.bevel_weight` 属性在 5.x **已移除**；改成网格属性 `bevel_weight_edge`，但 Bevel 修改器 `limit_method='WEIGHT'` 实测 `slant=0` 未生效（flaky）。
+- **最稳做法**：用 `bmesh.ops.bevel(bm, geom=[选中的竖直棱], affect='EDGES', offset=BEVEL_W, segments=2, profile=0.5, clamp_overlap=True)` 直接对选中棱倒角 → 版本无关、确定性强。倒角后 `bm.to_mesh(mesh)` 回写，按法线重排材质，顶点色在倒角后上色（含新增顶点防黑边）。
+- 判竖直棱：两顶点 `abs(x1-x2)<eps and abs(y1-y2)<eps`（忽略 z 差）→ 竖直；其 `xs=sign(x-中心x)`、`ys=sign(y-中心y)` 决定属于哪侧。
+
+### 导出坑（已修）
+- **Blender 5.2 glTF 色导出 bug**：顶点色→白色 `COLOR_0`(ubyte)+畸形 `COLOR_1`(ushort)；纯色材质→无 `pbrMetallicRoughness`。**对策：GLB 只出几何，颜色全在下游引擎（Godot/Maya/Unity）侧套** `StandardMaterial3D` / PBR。不要在 Blender 侧烤色。
+- bmesh 跨会话 bevel 报 `BMEdge has been removed` → 选中+bevel+to_mesh+free 必须在**单 bmesh 会话内**完成。
+- 过渡名无拓扑后缀互相覆盖 → 加 `_inland/_side/_corner` 后缀区分。
+
+## 连接与工具（mcp-for-blender）
+
+- MCP 配置：`~/.workbuddy/mcp.json` 的 `blender` 节点（`command: uvx blender-mcp`, `BLENDER_PORT=9876`）。
+- 插件：`~/Library/Application Support/Blender/5.2/scripts/addons/blender_mcp_addon.py`（Blender 内 Edit→Preferences→Add-ons 启用 "Blender MCP"，N 面板 BlenderMCP → Start MCP Server）。
+- **可复用 helper**：`/Users/jojo/AI_Projects/Seele/tools/blender_mcp_exec.py` — 读 .py 脚本或 stdin，经 `uvx blender-mcp` 桥在 Blender 内执行并返回输出：`python3 blender_mcp_exec.py script.py`（需 Blender 已开 + 插件服务端已启动）。
+- 视觉自检：`look`（rendered 通道，返回场景渲图）替代旧 `get_viewport_screenshot`。
+
+## CC0 素材直拉（mcp-for-blender 内集成）
+
+- **Poly Pizza**：~10,600 免费 low-poly CC0 模型，适合风格化游戏；让 agent 搜索+过滤+直接导入。
+- **Poly Haven**：HDRI 环境光照 + PBR 纹理；适合离开 Blender 配光照/材质。
+- **Hunyuan3D / Tripo**（经 `generate_3d`，需 API key）：文本/图像生成带贴图 3D 模型，用于素材库没有的独有道具，再进 Blender 精修。
+- 策略：AI 生成与 CC0 拉取混合——先拉 CC0 基线对齐视觉语言，再参数化自研专属模块。CC-BY 须署名登记来源（资产红线见 `blender-sop` §3）。
+
+## 迭代完善纪律
+
+本技能 v1.0.0 为通用化初版，使用中逐步修订：
+- 每次建模发现的新技法/坑/好用的 Spec 模板 → 回写本 SKILL.md。
+- 新资产类别（树/屋/角色）沉淀为可复用 bpy 函数片段，附在本技能或独立参考文件。
+- 用户美术方向偏好（配色、轮廓、圆角强度）→ 记入 Spec 表默认模板。
+- 不擅自推翻 `blender-sop` 级红线；涉及决策变更先与主理人（艾芙琳）对齐。

package/skills/blender-env/SKILL.md

@@ -0,0 +1,78 @@
+---
+name: blender-env
+description: "Blender 环境体检与排障：找不到可执行文件、版本不对、GPU/METAL、EEVEE 黑图、输出目录无权限、bpy 脚本报错、MCP 插件没连上。当 doctor 失败或用户说 Blender 跑不起来时使用。"
+whenToUse: "Blender 找不到 / 版本 / METAL / GPU / 黑图 / 权限 / bpy 报错 / 插件连接 时"
+license: MIT
+---
+
+# Blender 环境体检
+
+> 先 doctor，再怀疑脚本。多数“脚本有问题”最后是路径、版本或 GPU 后端。
+
+## 1. 体检顺序
+
+| 步 | 检查 | 命令 | 失败含义 |
+|---|---|---|---|
+| 1 | 可执行文件 | `python3 scripts/blender_client.py doctor` | 没装 / 路径不对 |
+| 2 | 版本 | 同上，看 `Blender 5.x` | 4.x 的引擎标识不同 |
+| 3 | GPU 后端 | 同上，看 `METAL` | 回落到软件渲染，极慢 |
+| 4 | 引擎列表 | 同上，应含 `BLENDER_EEVEE` | 版本或构建异常 |
+| 5 | 冒烟 | `... smoke --res 256` | 能出图 = 链路通 |
+
+## 2. 常见故障
+
+### 找不到 Blender
+
+- macOS 默认在 `/Applications/Blender.app/Contents/MacOS/Blender`；
+- 其他位置：`export BLENDER_BIN=/path/to/Blender`，或每次 `--blender /path/to/Blender`；
+- 不要指望 `blender` 在 PATH 里——App 安装通常不会建符号链接。
+
+### 版本不对（4.x vs 5.x）
+
+- 5.x 的 EEVEE 标识是 `BLENDER_EEVEE`（4.2–4.x 曾用 `BLENDER_EEVEE_NEXT`）；
+- 部分 API 在 5.x 变更（Bevel、材质节点、`bevel_weight` 移除），见 `blender-5x-pitfalls`；
+- 混用版本时，先统一到 5.2 LTS 再排查脚本。
+
+### 渲染黑图 / 全黑
+
+- headless 下 EEVEE 依赖 GPU；先确认 `doctor` 的 GPU 后端是 `METAL`；
+- 没有相机 → 黑图；没有灯光 → 暗图（不是黑）；
+- 世界背景为纯黑且没有灯光时，默认立方体也会接近黑；
+- 先在 `smoke` 上验证，再怀疑场景。
+
+### 输出目录无权限
+
+- 错误形如 `Permission denied` / `Operation not permitted` 写 PNG；
+- 用 `--outdir` / `--out` 指到可写目录（工作区内最稳）；
+- 受限进程启动的 Blender 也受同样限制——必要时用可写目录重启。
+
+### bpy 脚本报错
+
+- 先看完整 traceback：客户端失败时会打印最后 25 行；
+- 常见：API 名称在 5.x 改名、上下文对象为空（headless 没有 UI 上下文）、`bpy.ops` 需要正确的 active object；
+- headless 下避免依赖 `screen`/`area` 的操作。
+
+### MCP 连不上（交互模式）
+
+- 需要 Blender 正在运行 + 装好 addon + `uvx blender-mcp`；
+- headless 不需要 MCP；只有“实时操控打开着的 Blender”才需要；
+- 详见 `blender-mcp-bridge`。
+
+## 3. 体检输出怎么读
+
+```
+✅ Blender: Blender 5.2.1 LTS
+   路径: /Applications/Blender.app/Contents/MacOS/Blender
+   GPU 后端: METAL
+   引擎: BLENDER_EEVEE
+```
+
+- 版本不是 5.x → 先对齐版本或接受差异；
+- GPU 不是 METAL → 检查是否被 `--factory-startup` 之外的配置改过；
+- 引擎列表缺 EEVEE → 构建异常，重装。
+
+## 4. 边界
+
+- 不代装 Blender、不改系统级配置；
+- 不承诺渲染耗时——同一场景在不同 GPU 上差异很大；
+- 环境修不好时，明确告诉用户卡在哪一步，而不是继续调脚本。

package/skills/blender-mcp-bridge/SKILL.md

@@ -0,0 +1,68 @@
+---
+name: blender-mcp-bridge
+description: "把 mcp-for-blender 接到 DSH：uvx 启动、Blender 5.2 插件、连接前提、真实工具名对齐、连通性验证与按需加载。用于需要实时操控 Blender 的交互场景。"
+whenToUse: "Blender MCP / 实时操控 / 交互式 / uvx / 插件 / 连接失败 时"
+license: MIT
+---
+
+
+# Blender MCP 接线（blender-mcp-bridge）
+
+> DSH 执行层（headless 跑 Blender、渲染、导出）：见 `blender-studio` 技能。
+
+
+让团队能**在运行中的 Blender 5.2 内**被智能体驱动。本机操控层是增强版 **mcp-for-blender**（经 `uvx blender-mcp` 安装，工具命名空间 `mcp__blender__*`），**不是**社区基础版 `blender-mcp`（ahujasid）。
+
+## 配置现状（本机已就绪）
+
+- **MCP 配置**：`~/.workbuddy/mcp.json` 的 `blender` 节点：`command: uvx blender-mcp`，`BLENDER_PORT=9876`，`disabled:false`。
+- **本地插件**：`~/Library/Application Support/Blender/5.2/scripts/addons/blender_mcp_addon.py`（175KB，2026-09-14）。
+- **连接前提**：Blender 必须**开着**且插件服务端**已启动**（N 面板 → BlenderMCP → Start MCP Server）。当前没开 → 实测 `get_addon_status` 返回「Could not connect to Blender」。这与 Godot 当初"误判无 MCP"同一剧本——操控层存在，只是需用户先开软件。
+- **没有** Godot 那种编辑器自动拉起；Blender MCP 需用户在 Blender 内手动点启动（或后续研究能否 CLI 拉起 + 触发服务端）。
+
+## 连接证明（Phase 0.5 闸门）
+
+- 先 `get_addon_status` 确认插件/版本匹配、库与生成器开关；返回已连才算"本机 Blender 已接入"。
+- 或 `execute_blender_code` 跑 `import bpy; print(bpy.app.version)` 能回显版本即证明通道通。
+- **无连接证明前，任何成员不得声称能操控 Blender**——只能输出纯设计/文档产出并显式告知阻塞。
+
+## 真实工具矩阵（对齐 mcp-for-blender，别照基础版写旧名）
+
+| 工具 | 能力 | 团队用途 |
+|---|---|---|
+| `get_addon_status` | 版本/插件匹配/库与生成器开关/telemetry | **环境审计入口** |
+| `get_scene_info` | 场景事实：对象数/位置/尺寸/拓扑健康/权重 | 读回场景树 |
+| `execute_blender_code` | 在用户活 Blender 跑 bpy/bmesh/mathutils | **逃逸舱**：一切结构化工具够不到的都写 Python |
+| `look` | 渲图看场景：viewport/camera/多角度/帧序列，solid/material/rendered/wireframe/xray | **视觉反馈通道**（替代旧 `get_viewport_screenshot`，更强） |
+| `search_assets` | 搜 polyhaven(CC0)/sketchfab/Polypizza(CC0/CC-BY) | CC0 资产直拉 |
+| `generate_3d` | 文本/图像→带贴图 3D 模型，tripo/hunyuan3d/hyper3d，Premium 档 | AI 造模（独有道具），再进 Blender 精修 |
+| （导出/导入） | glTF/GLB/FBX/OBJ/STL/USD/ABC/PLY | 资产出 Blender → 引擎/AR/打印 |
+
+> ⚠️ **与旧基础版 blender-mcp 的工具名差异**（建脚本/技能时务必对齐本表）：
+> 旧 `get_viewport_screenshot` → 现 `look`；旧 `get_polyhaven_assets` → 现 `search_assets`；旧 `generate_hyper3d_model` → 现 `generate_3d`。直接照搬旧名会调不到工具。
+
+## 每成员工具配方
+
+| 成员 | 常用工具 |
+|---|---|
+| blender-tech-mcp | get_addon_status / execute_blender_code / 导出全系 / search_assets / generate_3d |
+| blender-modeling | execute_blender_code / get_scene_info / look / generate_3d / export glTF |
+| blender-shading | execute_blender_code / get_scene_info / look / search_assets |
+| blender-rig-anim | execute_blender_code / get_scene_info / look |
+| blender-light-render | execute_blender_code / get_scene_info / look |
+| blender-sim-vfx | execute_blender_code / get_scene_info / look |
+
+## 按需加载（对抗小模型幻觉）
+
+- 只亮少量核心工具（get_addon_status / get_scene_info / execute_blender_code / look），重工具经 `search_assets` / `generate_3d` 调用。
+- 范本来例：StraySpark Blender MCP Server v4.0（556 工具/39 类，只开 22 个开门工具，其余经 search 按需加载，上下文压到 9.5K token）。这套技能不照搬其 556 工具，但**同一哲学**：工具多 ≠ 全塞上下文。
+- 复用 Godot 团教训：seele-godot 131 工具全量注入小模型 → 幻觉。Blender 团避免。
+
+## 可复用 helper
+
+`/Users/jojo/AI_Projects/Seele/tools/blender_mcp_exec.py` — 读 .py 或 stdin，经 `uvx blender-mcp` 桥在 Blender 内执行并返回输出：`python3 blender_mcp_exec.py script.py`。可作团队脚本资源（注意：需 Blender 已开 + 插件服务端已启动）。
+
+## 红线
+- 默认本地优先（127.0.0.1）；云端造模（`generate_3d` / fal.ai）经 `uvx` 运行时，须显式告知用户数据出站。
+- 无连接证明不得声称已操控。
+- 截图/`look` 仅用于自动化自检，不替代人的视觉终裁。

package/skills/blender-modeling-cookbook/SKILL.md

@@ -0,0 +1,68 @@
+---
+name: blender-modeling-cookbook
+description: "Blender 建模技法库：参数化 bpy 构建、BMesh 操作、修改器栈、拓扑规则、UV 展开，以及让 low-poly 资产圆润的选择性 Bevel 配方。"
+whenToUse: "Blender 建模 / bpy / BMesh / 修改器 / 拓扑 / UV / Bevel 时"
+license: MIT
+---
+
+
+# 建模技法库（blender-modeling-cookbook）
+
+> DSH 执行层（headless 跑 Blender、渲染、导出）：见 `blender-studio` 技能。
+
+
+**沉淀实战建模技法，供 `blender-modeling` 与全员复用。** 锚定 Blender 5.2 LTS；语法不假设 4.x。
+
+## §1 参数化 bpy 构建范式
+
+- **代码即资产**：优先 bpy 参数化脚本（可版本化、可 diff、可复现）。模板：
+  ```python
+  import bpy, bmesh, mathutils
+  mesh = bpy.data.meshes.new("prop"); obj = bpy.data.objects.new("prop", mesh)
+  bpy.context.collection.objects.link(obj)
+  bm = bmesh.new(); # ... from_pydata / ops ... ; bm.to_mesh(mesh); bm.free()
+  ```
+- **LL3M 自批判循环**：生成 → `execute_blender_code` 执行 → `get_scene_info`/`look` 读回 → 修正。结构化操作优先落脚本而非依赖不可控的结构化工具。
+
+## §2 BMesh 操作
+
+- 建网格：`bm.from_mesh(mesh)` 或 `bm.from_pydata(verts, edges, faces)`。
+- 常用 ops：`bmesh.ops.create_cube` / `extrude_face_region` / `subdivide_edges` / `translate` / `bevel`（直接对选中几何）。
+- 倒角（最稳）：`bmesh.ops.bevel(bm, geom=[选中棱], affect='EDGES', offset=W, segments=2, profile=0.5, clamp_overlap=True)` —— 选中+bevel+to_mesh+free 必须在**单 bmesh 会话内**。
+- 判竖直棱：两顶点 `abs(x1-x2)<eps and abs(y1-y2)<eps`；方向用**顶点包围盒中心**（`0.5*(min+max)`），**不碰 `obj.location`**（`transform_apply(location=True)` 会把它归零导致符号全部翻转）。
+
+## §3 修改器栈（脚本化）
+
+| 修改器 | 用途 |
+|---|---|
+| Bevel | 圆角，逃离方块感（限角 `ANGLE` + `angle_limit`） |
+| Solidify | 厚度（墙面/叶片） |
+| Subdivision | 平滑（省用，重） |
+| Array | 阵列（重复元素） |
+| Mirror | 对称（角色/道具） |
+| WeightedNormal | 法线平滑（低模关键） |
+
+- 加 Bevel 务必 `obj.modifiers.new(name="Bevel", type='BEVEL')` 拿引用，不用 `bpy.ops.object.modifier_add` 后按名取（5.x `key "Bevel" not found`）。
+- Bevel `limit_method='ANGLE'` + `angle_limit`（如 40°）：平顶内部网格线（0°）不倒角，只磨圆崖壁/外缘（90°）。
+
+## §4 拓扑规则
+
+- **连续网格优于逐立方体**：地面/地形用一整张 heightfield，顶点色 splat 只在边界带、块中心纯色 → 无缝、色不糊。逐立方体各自顶点色无法跨 mesh 衔接（缝 + 色糊反模式）。
+- **低模代理**：quad 优先、拓扑干净、三角预算写死（tile ≤ 200、树 ≤ 1500）。
+- **重拓扑/UV/绑定必须人审**（StraySpark 硬限制 #1）。
+
+## §5 UV 展开
+
+- 智能 UV 投影 / 展 UV（Unwrap）/ 打包（Pack Islands）；命名规范，避免重叠。
+- 接缝（seam）沿结构暗线；对称模型用 Mirror 同步 UV。
+
+## §6 LOD 与导出
+
+- Decimate 生成 LOD（LOD1=50% / LOD2=75% / LOD3=90% 缩减）。
+- glTF/GLB 只出几何（5.2 丢色），颜色下游引擎套（见 `blender-5x-pitfalls` / `blender-sop` §4）。
+
+## §7 复用资产
+
+- `generate_3d`（tripo/hunyuan3d/hyper3d）云端造模独有道具 → 进 Blender 精修。
+- `search_assets` 直拉 Poly Pizza CC0 low-poly 作基线，对齐视觉语言后参数化自研。
+- helper：`/Users/jojo/AI_Projects/Seele/tools/blender_mcp_exec.py` 本地执行 bpy 脚本。

package/skills/blender-sop/SKILL.md

@@ -0,0 +1,64 @@
+---
+name: blender-sop
+description: "Blender 专业标准：5.2 LTS 基线、Cycles/Eevee 抉择、CC0 资产红线、glTF/USD 导出纪律，以及 agent 驱动 Blender 协作的三条硬限制。所有管线判断的单一真相源。"
+whenToUse: "Blender / 渲染器选择 / Cycles / Eevee / CC0 / glTF / USD / 导出规范 时"
+license: MIT
+---
+
+
+# Blender 专业标准（blender-sop）
+
+> DSH 执行层（headless 跑 Blender、渲染、导出）：见 `blender-studio` 技能。
+
+
+**所有管线判断以此为准。** 本技能是 Blender 工作室的"大脑"，版本/渲染器/资产/导出/协作纪律的单一真相源。
+
+## §1 版本基线（务必写准，别犯 Godot 的版本错）
+
+- **最新稳定**：Blender **5.2 LTS**（2026-09-15 发布，支持到 2028-07）。本机已装 **5.2.1 LTS**（`/Applications/Blender.app`）。
+- **次选长期支持**：4.5 LTS（2025-07，支持到 2027-07）。4.2 LTS 已于 2026-07 EOL。
+- **结论**：团队默认目标 **5.2 LTS**；兼容下限 4.5 LTS。渲染器 **Cycles（写实）/ Eevee（实时）** 双轨，5.x Eevee 已重写（EEVEE-Next），**不再假设 4.x 旧 Eevee 行为**。
+- **红线**：脚本/修改器语法必须锚定 5.x；不假设 4.x。
+
+## §2 渲染器抉择
+
+| 场景 | 选 | 理由 |
+|---|---|---|
+| 写实 / 离线 / 产品图 | **Cycles** | 路径追踪，物理准确 |
+| 实时 / 预览 / 交互 / 风格化 | **Eevee（EEVEE-Next）** | 5.x 重写，快但近似 |
+| 动画序列批量出 | Cycles（降采样+降噪）或 Eevee | 看预算 |
+
+⚠️ 不假设 4.x Eevee 行为；5.x 材质/灯光节点有差异。
+
+## §3 资产红线（商用前置）
+
+- 商用前必须 **CC0 或已授权**，禁未授权素材进包。
+- `search_assets` 直拉的 **Poly Haven（CC0）/ Poly Pizza（CC0/CC-BY）/ Sketchfab（须看授权）**——CC-BY 须署名，登记来源。
+- 用户自有/自建模产可商用；AI 生成（`generate_3d`）须确认生成器授权（tripo/hunyuan3d/hyper3d 商用条款）。
+
+## §4 导出纪律（glTF/USD/FBX）
+
+- **glTF/GLB**：游戏/AR 默认。本环境 **5.2 glTF 导出器丢色**（顶点色→白色 `COLOR_0`+畸形 `COLOR_1`；纯色材质→无 `pbrMetallicRoughness`）→ **GLB 只出几何，颜色在下游引擎侧套**（Godot/Maya/Unity 建材质）。
+- **FBX**：Maya/Unity 互通。
+- **USD**：Blender→Unreal 一键管线（多 agent 跨软件）。
+- **Decimate** 生成 LOD（LOD1=50% / LOD2=75% / LOD3=90% 缩减）。
+- 导出参数（5.x）：`export_format='GLB'`、`export_materials='EXPORT'`（**无 `export_colors` 参数**，5.x 已移除）。
+
+## §5 Agent+MCP 协作三硬限制（StraySpark）
+
+1. **创意拓扑不是 agent 的活**：概念/大形/风格/轮廓决策由**人**做；agent 只接手可参数化、可验证子任务（blockout / 低模代理）。手动重拓扑/UV/绑定/动画必须人审。
+2. **重操作超时 60–120s**：细分/重拓扑/烘焙/模拟 bake 会超时——须拆小步、降分辨率、或交人手动在 Blender 内跑。
+3. **agent 无视觉反馈**：agent 看不到渲染结果，靠 `look`/`get_scene_info` 间接判断——**所有"看起来对不对"的终裁必须落回人**（agent 不自认已验证）。
+
+## §6 Blender-MCP 协作铁律
+
+- **连接前提**：Blender 必须开着且插件服务端已启动（N 面板 → BlenderMCP → Start MCP Server）。无连接证明（如 `get_addon_status` 已连）前，任何成员不得声称能操控 Blender。
+- **执行后必 `look` 自检**：`look` 是 agent 唯一视觉通道，是硬限制 #3 的补偿机制。
+- **代码即资产**：结构化操作优先落 bpy 脚本（`execute_blender_code`），可版本化、可 diff、可复现；LL3M 自批判循环 = 执行 → 读回 → 修正。
+- **工具按需加载**：只亮少量核心工具（get_addon_status / get_scene_info / execute_blender_code / look），重工具经 `search_assets`/`generate_3d` 调用，别全量塞（复用 Godot 团"131 工具全量注入→幻觉"教训）。
+- **造模上云、精修在本地**：`generate_3d`（tripo/hunyuan3d/hyper3d）云端造模绕开本地重算超时（硬限制 #2）；精修留本地 bpy。
+- **隐私**：默认本地优先（127.0.0.1）；云端造模经 `uvx` 运行时，须显式告知用户数据出站。
+
+## §7 修改与同步纪律
+
+本技能为团队标准基线。每次建模/渲染发现的新技法/坑/规范 → 回写本 SKILL.md 对应章节 + MEMORY.md（项目级）。不擅自推翻 §1–§6 级红线；涉及决策变更先与主理人（艾芙琳）对齐。

package/skills/blender-studio/SKILL.md

@@ -0,0 +1,82 @@
+---
+name: blender-studio
+description: "Blender 在 DSH 里的总入口：环境体检、headless 跑 bpy 脚本、渲染 .blend、导出 glTF，以及建模/踩坑/资产管线/MCP 的路由。当用户要建模、渲染、做游戏资产、批量生成或接 Blender 时使用。"
+whenToUse: "Blender / bpy / 渲染 / render / glTF / GLB / 建模 / 资产 / headless 时"
+license: MIT
+---
+
+# Blender × DSH
+
+> 本技能是执行层：怎么在 DSH 里用 headless Blender 跑脚本、渲染、导出。
+> 领域知识（SOP、建模、踩坑、资产管线）在另外几个技能里，见第 5 节路由。
+
+## 0. 先决条件
+
+- Blender **5.2 LTS**（本包按 5.2 校准；4.x 的引擎标识与 API 有差异）；
+- macOS 默认路径 `/Applications/Blender.app/Contents/MacOS/Blender`；
+- 用 `BLENDER_BIN` 或 `--blender` 指定其他路径；
+- 客户端零依赖（Python 3.8+），不需要在系统 Python 里装 bpy。
+
+## 1. 30 秒体检
+
+```bash
+python3 scripts/blender_client.py doctor
+```
+
+输出：版本、可执行文件路径、GPU 后端（macOS 应为 `METAL`）、可用渲染引擎。
+连不上/找不到时先看 `blender-env`，不要改脚本。
+
+## 2. 冒烟渲染（证明链路是通的）
+
+```bash
+python3 scripts/blender_client.py smoke --outdir outputs/blender/smoke --res 256
+```
+
+会新建默认场景、用 EEVEE 渲染一张 256×256 PNG。3–5 秒内出图即正常。
+
+## 3. 跑 bpy 脚本（主要工作方式）
+
+```bash
+python3 scripts/blender_client.py run \
+  --script skills/blender-studio/examples/make_tiles.py \
+  --outdir outputs/blender/tiles
+```
+
+- 脚本通过环境变量 `DSH_BLENDER_OUTDIR` 拿到输出目录；
+- 需要从已存工程开始时加 `--blend path/to/scene.blend`；
+- 额外参数：`--arg key=value`（追加到 `--` 之后，脚本用 `sys.argv` 读）。
+
+示例 `examples/make_tiles.py` 演示了完整闭环：参数化建模 → 选择性 Bevel → 相机灯光 → EEVEE 渲染 → 保存 `.blend` → 导出 `.glb`。
+
+## 4. 渲染已有工程 / 导出
+
+```bash
+# 渲染单帧
+python3 scripts/blender_client.py render \
+  --blend outputs/blender/tiles/scene.blend \
+  --out outputs/blender/tiles/final.png \
+  --samples 64 --res 1024
+
+# 更复杂的导出（glTF / USD / FBX）直接在脚本里做，不要在命令行拼
+python3 scripts/blender_client.py run --script my_export.py --blend scene.blend
+```
+
+输出统一放 `outputs/blender/<主题>/`，文件名带版本或日期；生成后用 `present` 把图片给用户看。
+
+## 5. 领域路由
+
+| 用户问题 | 调用技能 |
+|---|---|
+| 找不到 Blender / 版本不对 / 渲染报错 | `blender-env` |
+| 渲染器怎么选、导出规范、CC0 红线 | `blender-sop` |
+| 建模、Bevel、修改器、拓扑、UV | `blender-modeling-cookbook` |
+| 5.x 的 API 变化与已知坑 | `blender-5x-pitfalls` |
+| 程序化资产生成、批量、LOD、glTF | `blender-asset-pipeline` |
+| 要实时操控打开着的 Blender | `blender-mcp-bridge` |
+
+## 6. 诚实边界
+
+- **headless 只适合确定性任务**：建模、材质、渲染、导出、批量。雕刻、手动绑定、视觉微调这类交互工作，要么用 MCP 接活着的 Blender，要么交给人。
+- 不代装 Blender、不代下资产（CC0 规则见 `blender-sop`）。
+- 渲染质量与速度取决于本机 GPU；同一场景的耗时不能直接跨机器比较。
+- 所有操作只在本机执行，不经过云端。

package/skills/blender-studio/examples/make_tiles.py

@@ -0,0 +1,98 @@
+"""
+示例：参数化 low-poly 地砖 + 选择性 Bevel + 渲染 + glTF 导出。
+
+在 DSH 里跑：
+  python3 skills/blender-studio/scripts/blender_client.py run \
+    --script skills/blender-studio/examples/make_tiles.py \
+    --outdir outputs/blender/tiles
+
+输出（默认 <outdir>）：
+  scene.blend   可继续编辑的场景
+  tiles.png     512×512 EEVEE 渲染
+  tiles.glb     glTF 导出（游戏资产）
+"""
+import os
+import math
+
+import bpy
+from mathutils import Vector
+
+OUTDIR = os.environ.get("DSH_BLENDER_OUTDIR", "outputs/blender/tiles")
+os.makedirs(OUTDIR, exist_ok=True)
+
+# 1. 空场景
+bpy.ops.wm.read_factory_settings(use_empty=True)
+scene = bpy.context.scene
+
+# 2. 参数：3×3 地砖，间隙与厚度
+GRID = 3
+SIZE = 1.6
+GAP = 0.08
+HEIGHT = 0.18
+BEVEL = 0.045
+
+mat = bpy.data.materials.new("Tile")
+mat.use_nodes = True
+bsdf = mat.node_tree.nodes.get("Principled BSDF")
+bsdf.inputs["Base Color"].default_value = (0.62, 0.66, 0.72, 1.0)
+bsdf.inputs["Roughness"].default_value = 0.55
+
+for ix in range(GRID):
+    for iy in range(GRID):
+        bpy.ops.mesh.primitive_cube_add(size=1)
+        obj = bpy.context.active_object
+        obj.name = f"tile_{ix}_{iy}"
+        obj.scale = (SIZE / 2, SIZE / 2, HEIGHT / 2)
+        obj.location = (
+            (ix - (GRID - 1) / 2) * (SIZE + GAP),
+            (iy - (GRID - 1) / 2) * (SIZE + GAP),
+            HEIGHT / 2,
+        )
+        bpy.ops.object.transform_apply(location=False, rotation=False, scale=True)
+        obj.data.materials.append(mat)
+
+        bevel = obj.modifiers.new("Bevel", "BEVEL")
+        bevel.width = BEVEL
+        bevel.segments = 3
+        bevel.limit_method = "ANGLE"
+
+# 3. 相机与灯光
+bpy.ops.object.camera_add(location=(4.2, -4.8, 4.0))
+cam = bpy.context.active_object
+cam.rotation_euler = (math.radians(52), 0, math.radians(42))
+scene.camera = cam
+
+bpy.ops.object.light_add(type="SUN", location=(3, -2, 6))
+sun = bpy.context.active_object
+sun.data.energy = 3.2
+sun.rotation_euler = (math.radians(35), 0, math.radians(30))
+
+# 4. 世界背景
+world = bpy.data.worlds.new("World")
+scene.world = world
+world.use_nodes = True
+world.node_tree.nodes["Background"].inputs[0].default_value = (0.05, 0.06, 0.08, 1.0)
+
+# 5. 渲染设置（EEVEE + 512）
+scene.render.engine = "BLENDER_EEVEE"
+scene.render.resolution_x = 512
+scene.render.resolution_y = 512
+scene.render.resolution_percentage = 100
+scene.render.image_settings.file_format = "PNG"
+scene.eevee.taa_render_samples = 32
+
+# 6. 保存工程 + 渲染
+blend_path = os.path.join(OUTDIR, "scene.blend")
+bpy.ops.wm.save_as_mainfile(filepath=blend_path)
+
+scene.render.filepath = os.path.join(OUTDIR, "tiles.png")
+bpy.ops.render.render(write_still=True)
+
+# 7. 导出 glTF（游戏资产）
+bpy.ops.export_scene.gltf(
+    filepath=os.path.join(OUTDIR, "tiles.glb"),
+    export_format="GLB",
+    use_selection=False,
+)
+
+print("DSH_EXAMPLE_OK", OUTDIR)

package/skills/blender-studio/scripts/blender_client.py

@@ -0,0 +1,245 @@
+#!/usr/bin/env python3
+"""
+blender_client.py — 零依赖 Blender headless 客户端（仅标准库）。
+
+用法：
+  python3 blender_client.py doctor [--blender PATH]
+  python3 blender_client.py smoke  [--outdir DIR] [--res 256]
+  python3 blender_client.py render --blend SCENE.blend --out PNG [--engine BLENDER_EEVEE]
+                                  [--samples 32] [--res 512] [--frame 1] [--timeout 600]
+  python3 blender_client.py run --script SCRIPT.py [--blend SCENE.blend] [--outdir DIR]
+                               [--timeout 600] [--arg KEY=VALUE ...]
+
+默认自动查找 Blender（BLENDER_BIN 环境变量 → /Applications/Blender.app → PATH）。
+退出码：0 成功；2 找不到 Blender；4 Blender 执行失败或超时。
+"""
+from __future__ import annotations
+
+import argparse
+import json
+import os
+import re
+import shutil
+import subprocess
+import sys
+import tempfile
+import time
+from pathlib import Path
+
+CANDIDATES = [
+    os.environ.get("BLENDER_BIN"),
+    "/Applications/Blender.app/Contents/MacOS/Blender",
+    shutil.which("blender"),
+]
+
+
+def fail(message: str, code: int):
+    print(message, file=sys.stderr)
+    raise SystemExit(code)
+
+
+def find_blender(explicit: str | None = None) -> str:
+    for candidate in ([explicit] if explicit else []) + CANDIDATES:
+        if candidate and Path(candidate).exists():
+            return candidate
+    fail(
+        "❌ 找不到 Blender。用 --blender 指定路径，或设置 BLENDER_BIN。\n"
+        "   macOS 默认路径：/Applications/Blender.app/Contents/MacOS/Blender",
+        2,
+    )
+
+
+def run_blender(cmd: list[str], timeout: float) -> subprocess.CompletedProcess:
+    try:
+        return subprocess.run(cmd, capture_output=True, text=True, timeout=timeout)
+    except subprocess.TimeoutExpired:
+        fail(f"❌ Blender 超时（{timeout}s），已终止。", 4)
+
+
+def tail(text: str, n: int = 25) -> str:
+    lines = [line for line in (text or "").splitlines() if line.strip()]
+    return "\n".join(lines[-n:])
+
+
+def run_expr(blender: str, expr: str, timeout: float = 120) -> subprocess.CompletedProcess:
+    return run_blender([blender, "-b", "--factory-startup", "--python-expr", expr], timeout)
+
+
+def probe(blender: str) -> dict:
+    expr = (
+        "import bpy, json;"
+        "print('DSH_PROBE' + json.dumps({"
+        "'version': bpy.app.version_string,"
+        "'engines': [e.identifier for e in bpy.types.RenderSettings.bl_rna.properties['engine'].enum_items],"
+        "'gpu': bpy.context.preferences.system.gpu_backend"
+        "}))"
+    )
+    result = run_expr(blender, expr, timeout=120)
+    for line in (result.stdout or "").splitlines():
+        if line.startswith("DSH_PROBE"):
+            return json.loads(line[len("DSH_PROBE"):])
+    fail("❌ 无法从 Blender 读取环境信息：\n" + tail(result.stdout + result.stderr), 4)
+
+
+def version_of(blender: str) -> str:
+    result = run_blender([blender, "--version"], timeout=60)
+    first = (result.stdout or "").splitlines()[0] if result.stdout else ""
+    return first.strip() or "?"
+
+
+def cmd_doctor(args) -> int:
+    blender = find_blender(args.blender)
+    info = probe(blender)
+    print("✅ Blender:", version_of(blender))
+    print("   路径:", blender)
+    print("   GPU 后端:", info.get("gpu", "?"))
+    print("   引擎:", ", ".join(info.get("engines") or []))
+    return 0
+
+
+def resolution(value: str) -> tuple[int, int]:
+    match = re.fullmatch(r"(\d+)(?:[xX](\d+))?", value.strip())
+    if not match:
+        fail(f"❌ 分辨率格式不对：{value}（例：512 或 768x512）", 3)
+    w = int(match.group(1))
+    h = int(match.group(2) or w)
+    return w, h
+
+
+def run_python_script(blender: str, script_path: Path, blend: str | None, timeout: float, extra: list[str]) -> subprocess.CompletedProcess:
+    cmd = [blender, "-b"]
+    cmd += [blend] if blend else ["--factory-startup"]
+    cmd += ["--python", str(script_path)]
+    if extra:
+        cmd += ["--"] + extra
+    return run_blender(cmd, timeout)
+
+
+def cmd_smoke(args) -> int:
+    blender = find_blender(args.blender)
+    outdir = Path(args.outdir).expanduser().resolve()
+    outdir.mkdir(parents=True, exist_ok=True)
+    out = outdir / "smoke.png"
+    w, h = resolution(str(args.res))
+    script = f"""
+import bpy
+scene = bpy.context.scene
+scene.render.engine = 'BLENDER_EEVEE'
+scene.render.resolution_x = {w}
+scene.render.resolution_y = {h}
+scene.render.resolution_percentage = 100
+scene.render.image_settings.file_format = 'PNG'
+scene.render.filepath = {str(out)!r}
+bpy.ops.render.render(write_still=True)
+print('DSH_RENDER_OK')
+"""
+    started = time.time()
+    with tempfile.NamedTemporaryFile("w", suffix=".py", delete=False, encoding="utf-8") as tmp:
+        tmp.write(script)
+        tmp_path = Path(tmp.name)
+    try:
+        result = run_python_script(blender, tmp_path, None, args.timeout, [])
+    finally:
+        tmp_path.unlink(missing_ok=True)
+    if result.returncode != 0 or not out.exists():
+        fail("❌ 冒烟渲染失败：\n" + tail(result.stdout + result.stderr), 4)
+    print(f"✅ 冒烟渲染完成（{time.time() - started:.1f}s）")
+    print("   ", out)
+    return 0
+
+
+def cmd_render(args) -> int:
+    blender = find_blender(args.blender)
+    blend = Path(args.blend).expanduser().resolve()
+    if not blend.exists():
+        fail(f"❌ 找不到 .blend：{blend}", 3)
+    out = Path(args.out).expanduser().resolve()
+    out.parent.mkdir(parents=True, exist_ok=True)
+    w, h = resolution(str(args.res))
+    script = f"""
+import bpy
+scene = bpy.context.scene
+scene.render.engine = {args.engine!r}
+scene.render.resolution_x = {w}
+scene.render.resolution_y = {h}
+scene.render.resolution_percentage = 100
+scene.render.image_settings.file_format = 'PNG'
+scene.render.filepath = {str(out)!r}
+scene.frame_set({int(args.frame)})
+try:
+    scene.eevee.taa_render_samples = {int(args.samples)}
+except Exception:
+    pass
+bpy.ops.render.render(write_still=True)
+print('DSH_RENDER_OK')
+"""
+    started = time.time()
+    with tempfile.NamedTemporaryFile("w", suffix=".py", delete=False, encoding="utf-8") as tmp:
+        tmp.write(script)
+        tmp_path = Path(tmp.name)
+    try:
+        result = run_python_script(blender, tmp_path, str(blend), args.timeout, [])
+    finally:
+        tmp_path.unlink(missing_ok=True)
+    if result.returncode != 0 or not out.exists():
+        fail("❌ 渲染失败：\n" + tail(result.stdout + result.stderr), 4)
+    print(f"✅ 渲染完成（{time.time() - started:.1f}s）")
+    print("   ", out)
+    return 0
+
+
+def cmd_run(args) -> int:
+    blender = find_blender(args.blender)
+    script = Path(args.script).expanduser().resolve()
+    if not script.exists():
+        fail(f"❌ 找不到脚本：{script}", 3)
+    blend = str(Path(args.blend).expanduser().resolve()) if args.blend else None
+    if blend and not Path(blend).exists():
+        fail(f"❌ 找不到 .blend：{blend}", 3)
+    if args.outdir:
+        os.environ["DSH_BLENDER_OUTDIR"] = str(Path(args.outdir).expanduser().resolve())
+    started = time.time()
+    result = run_python_script(blender, script, blend, args.timeout, args.arg)
+    if result.returncode != 0:
+        fail("❌ 脚本执行失败：\n" + tail(result.stdout + result.stderr), 4)
+    print(f"✅ 执行完成（{time.time() - started:.1f}s）")
+    if args.outdir:
+        print("   输出目录:", Path(args.outdir).expanduser().resolve())
+    return 0
+
+
+def main() -> int:
+    ap = argparse.ArgumentParser(description="Blender headless 零依赖客户端")
+    ap.add_argument("--blender", default=None, help="Blender 可执行文件路径")
+    sub = ap.add_subparsers(dest="cmd", required=True)
+
+    sub.add_parser("doctor")
+
+    p_smoke = sub.add_parser("smoke")
+    p_smoke.add_argument("--outdir", default="outputs/blender/smoke")
+    p_smoke.add_argument("--res", default="256")
+    p_smoke.add_argument("--timeout", type=float, default=300)
+
+    p_render = sub.add_parser("render")
+    p_render.add_argument("--blend", required=True)
+    p_render.add_argument("--out", required=True)
+    p_render.add_argument("--engine", default="BLENDER_EEVEE")
+    p_render.add_argument("--samples", type=int, default=32)
+    p_render.add_argument("--res", default="512")
+    p_render.add_argument("--frame", type=int, default=1)
+    p_render.add_argument("--timeout", type=float, default=900)
+
+    p_run = sub.add_parser("run")
+    p_run.add_argument("--script", required=True)
+    p_run.add_argument("--blend", default=None)
+    p_run.add_argument("--outdir", default=None)
+    p_run.add_argument("--timeout", type=float, default=900)
+    p_run.add_argument("--arg", action="append", default=[])
+
+    args = ap.parse_args()
+    handlers = {"doctor": cmd_doctor, "smoke": cmd_smoke, "render": cmd_render, "run": cmd_run}
+    return handlers[args.cmd](args)
+
+
+if __name__ == "__main__":
+    sys.exit(main())