@jojonadam/dsh-blender 0.1.2 → 0.2.0

package/skills/blender-mcp-bridge/scripts/blender_mcp_exec.py

@@ -0,0 +1,331 @@
+#!/usr/bin/env python3
+# -*- coding: utf-8 -*-
+"""
+blender_mcp_exec.py — 经 Blender MCP 在运行中的 Blender 里执行任意 bpy 代码
+=========================================================================
+随包分发版（v1.3.3）。零第三方依赖，只用标准库，macOS / Linux / Windows 通用。
+
+命令面已对上游核实（PyPI mcp-for-blender 2.2.2 的 --help 实测）：
+  · `--host` / `--port` 真实存在，且帮助原文写「overrides BLENDER_HOST/BLENDER_PORT」
+    → 本脚本显式传 --port 即可，**不需要**再给子进程注入 BLENDER_PORT 环境变量。
+  · `install-addon` / `addon-paths` / `setup` / `update` 四个子命令真实存在。
+
+前置：
+  1. Blender 已安装并**开着**（建议 5.2 LTS）
+  2. 已装 uv（含 uvx）：`pip install uv` 或见 https://docs.astral.sh/uv/
+  3. Blender 内 N 面板 → MCP for Blender → **Start MCP Server**（默认端口 9876）
+     插件没装/版本过旧 → 先跑 `uvx mcp-for-blender install-addon`
+
+用法：
+  python  blender_mcp_exec.py path/to/script.py
+  echo "import bpy; print(len(bpy.data.objects))" | python blender_mcp_exec.py
+  python  blender_mcp_exec.py script.py --timeout 300     # 重场景/渲染给足时间
+  python  blender_mcp_exec.py script.py --port 9877       # Blender 插件换了端口
+
+退出码：0 有输出 / 1 连接或执行失败 / 2 用法错误（stderr 给原因，绝不静默挂死）
+  归 2 的具体情形：脚本路径不存在、BLENDER_PORT 填错（非整数 / 空串 / 超 1-65535）、
+  找不到 uvx —— 凡是「还没开始连 Blender 就已经确定跑不通」的都算用法错误，方便脚本判错。
+
+--timeout 是**硬超时**：到点无条件退出并给诊断，不等子进程自然返回。
+"""
+import argparse
+import json
+import os
+import queue
+import shutil
+import signal
+import subprocess
+import sys
+import threading
+import time
+
+DEFAULT_TIMEOUT = 90
+DEFAULT_PORT = 9876
+# 优先用新包名；blender-mcp 是官方兼容 wrapper，仍可用但会往 stderr 打迁移提示
+PKG = "mcp-for-blender"
+
+DIAG = (
+    "  1) Blender 是否开着？\n"
+    "  2) N 面板 → MCP for Blender → 是否点了 Start MCP Server？\n"
+    "  3) 先问一句 `get_addon_status`——它一句话就能说清插件在不在、版本对不对；\n"
+    "     版本不一致就 `uvx mcp-for-blender install-addon`，再到 Preferences → Add-ons\n"
+    "     里禁用再启用 'Interface: MCP for Blender'\n"
+    "  4) 若你改过端口，用 --port 指定实际端口（脚本当前用 {port}）\n"
+    "  5) 插件装在哪个目录：`uvx mcp-for-blender addon-paths`"
+)
+
+
+def find_uvx():
+    """按 PATH → 常见安装位 → 报错。不写死任何一台机器的路径。"""
+    p = shutil.which("uvx")
+    if p:
+        return p
+    cands = [
+        os.path.expanduser("~/.local/bin/uvx"),
+        os.path.expanduser("~/.cargo/bin/uvx"),
+        "/opt/homebrew/bin/uvx",
+        "/usr/local/bin/uvx",
+        os.path.expanduser("~/AppData/Roaming/Python/Scripts/uvx.exe"),
+        os.path.expanduser("~/AppData/Local/Programs/uv/uvx.exe"),
+    ]
+    for c in cands:
+        if os.path.isfile(c):
+            return c
+    # 走 stderr + 退出码 2（用法/前置条件错），与 docstring 声明的退出码一致。
+    # 旧版 sys.exit("字符串") 实际返回 1，买家按 docstring 判码会判错。
+    sys.stderr.write(
+        "❌ 找不到 uvx。请先安装 uv：\n"
+        "   macOS/Linux:  curl -LsSf https://astral.sh/uv/install.sh | sh\n"
+        "   Windows:      powershell -c \"irm https://astral.sh/uv/install.ps1 | iex\"\n"
+        "   或 pip install uv\n"
+        "装完确认 `uvx --version` 可用，再重跑本脚本。\n"
+    )
+    sys.exit(2)
+
+
+def _port_from_env():
+    """读 BLENDER_PORT 并校验；不设该变量时返回 DEFAULT_PORT。
+
+    v1.3.1 的缺陷：`default=int(os.environ.get("BLENDER_PORT", DEFAULT_PORT))`
+    在 argparse 构造期就 int()，环境变量为 `9876abc` 或空串时用户直接吃到
+    Python traceback（看不出是自己环境变量填错）。这里改成
+    「先取值 → 校验 → 人话报错 + exit 2」。
+
+    刻意**不静默回退默认端口**：静默回退会让用户以为连上了 9876，
+    实际 Blender 开在别的端口，症状变成「连不上」而不是「变量填错」，更难查。
+    """
+    raw = os.environ.get("BLENDER_PORT")
+    if raw is None:
+        return DEFAULT_PORT
+    hint = ("   怎么办：要么删掉这个环境变量（回到默认端口 %d），"
+            "要么把它设成正确的整数端口号。\n" % DEFAULT_PORT)
+    s = raw.strip()
+    if not s:
+        sys.stderr.write(
+            "❌ 环境变量 BLENDER_PORT 是空字符串，不是端口号。\n" + hint)
+        sys.exit(2)
+    try:
+        v = int(s)
+    except ValueError:
+        sys.stderr.write(
+            "❌ 环境变量 BLENDER_PORT=%r 不是整数。\n" % raw + hint)
+        sys.exit(2)
+    if not 1 <= v <= 65535:
+        sys.stderr.write(
+            "❌ 环境变量 BLENDER_PORT=%r 超出端口范围（1-65535）。\n" % raw + hint)
+        sys.exit(2)
+    return v
+
+
+class _Reader(threading.Thread):
+    """把 stdout 逐行读进队列，让主线程能带超时地等。
+
+    readline 本身是阻塞调用，直接在主线程 readline 会让 --timeout 形同虚设——
+    这正是 v1.2 的缺陷：Blender 卡死时脚本无限挂住，外部强杀才结束。
+    """
+
+    def __init__(self, stream):
+        super().__init__(daemon=True)
+        self.stream = stream
+        self.q = queue.Queue()
+
+    def run(self):
+        try:
+            for line in self.stream:
+                self.q.put(line)
+        except Exception:
+            pass
+        finally:
+            self.q.put(None)  # 哨兵：流结束
+
+
+class _ErrReader(threading.Thread):
+    """stderr 同样必须异步读。若在主线程 read() 到 EOF，而孙进程还握着管道，
+    就会二次挂死（v1.3 开发期实测踩到）。这里只累积，永不阻塞主线程。"""
+
+    def __init__(self, stream, limit=400):
+        super().__init__(daemon=True)
+        self.stream = stream
+        self.limit = limit
+        self.buf = ""
+
+    def run(self):
+        try:
+            for line in self.stream:
+                if len(self.buf) < self.limit:
+                    self.buf += line
+        except Exception:
+            pass
+
+
+def _stop(p):
+    """整组杀掉。uvx 会再起子进程，只 terminate 直接子进程不足以断开管道。
+
+    分平台：
+      · POSIX：run_code 用 start_new_session=True 让 uvx 自成一个进程组，
+        这里 killpg 整组收掉，孙进程不会漏。
+      · Windows：没有进程组可杀。`p.kill()` 只结束 uvx 本身，uvx 再起的
+        python / mcp 子进程会变孤儿并继续握着管道 → 优先 `taskkill /T /F`
+        （/T 连子孙进程树一起杀），失败或进程已退才退回 p.kill()。
+    """
+    try:
+        if os.name == "nt":
+            try:
+                subprocess.run(
+                    ["taskkill", "/T", "/F", "/PID", str(p.pid)],
+                    stdout=subprocess.DEVNULL, stderr=subprocess.DEVNULL,
+                    timeout=10, check=False,
+                )
+            except Exception:
+                pass
+            if p.poll() is None:
+                p.kill()
+            return
+        if hasattr(os, "killpg"):
+            os.killpg(os.getpgid(p.pid), signal.SIGKILL)
+        else:
+            p.kill()
+    except Exception:
+        try:
+            p.kill()
+        except Exception:
+            pass
+
+
+def run_code(code, timeout=DEFAULT_TIMEOUT, port=DEFAULT_PORT):
+    cmd = [find_uvx(), PKG, "--port", str(port)]
+    kw = {}
+    if os.name == "posix":
+        kw["start_new_session"] = True  # 让 killpg 能收掉 uvx 的整组子进程
+    try:
+        p = subprocess.Popen(
+            cmd, stdin=subprocess.PIPE, stdout=subprocess.PIPE, stderr=subprocess.PIPE,
+            text=True, encoding="utf-8", errors="replace", bufsize=1, **kw,
+        )
+    except FileNotFoundError as e:
+        return "ERROR: 无法启动 uvx " + PKG + " → " + str(e), 1
+
+    reader = _Reader(p.stdout)
+    ereader = _ErrReader(p.stderr)
+    reader.start()
+    ereader.start()
+
+    def send(msg):
+        try:
+            p.stdin.write(json.dumps(msg) + "\n")
+            p.stdin.flush()
+        except Exception:
+            pass
+
+    def read(deadline):
+        """硬超时：到点返回 'TIMEOUT'，不等阻塞读自然返回。"""
+        while True:
+            remain = deadline - time.time()
+            if remain <= 0:
+                return "TIMEOUT"
+            try:
+                line = reader.q.get(timeout=remain)
+            except queue.Empty:
+                return "TIMEOUT"
+            if line is None:
+                return None  # 子进程已退出
+            line = line.strip()
+            if not line:
+                continue
+            try:
+                return json.loads(line)
+            except Exception:
+                continue  # 日志行 / 迁移提示，跳过继续等
+
+    def err_text():
+        _stop(p)
+        ereader.join(timeout=1.0)
+        return (ereader.buf or "").strip()
+
+    deadline = time.time() + timeout
+
+    send({"jsonrpc": "2.0", "id": 1, "method": "initialize",
+          "params": {"protocolVersion": "2024-11-05", "capabilities": {},
+                     "clientInfo": {"name": "blender-studio-exec", "version": "1.3.3"}}})
+    init = read(deadline)
+    if init is None or init == "TIMEOUT":
+        err = err_text()
+        return (f"CONNECT-FAIL（{timeout}s 内没完成 MCP 握手）。逐条诊断：\n"
+                + DIAG.format(port=port) + f"\nstderr: {err}"), 1
+    if isinstance(init, dict) and "error" in init:
+        err_text()
+        return "ERROR: 握手失败 → " + json.dumps(init["error"], ensure_ascii=False), 1
+
+    server = (init.get("result", {}).get("serverInfo", {}) or {})
+    send({"jsonrpc": "2.0", "method": "notifications/initialized"})
+    send({"jsonrpc": "2.0", "id": 2, "method": "tools/call",
+          "params": {"name": "execute_blender_code", "arguments": {"code": code}}})
+    res = read(deadline)
+
+    if res == "TIMEOUT":
+        err = err_text()
+        return (f"TIMEOUT（硬超时 {timeout}s，已强制退出）。握手成功"
+                f"（{server.get('name', '?')} {server.get('version', '?')}），"
+                f"但 execute_blender_code 没在时限内返回。\n"
+                f"常见原因：Blender 主线程被模态框/大渲染阻塞、插件服务端卡死，\n"
+                f"或脚本本身跑得久 → 渲染/模拟/大场景请加 --timeout 300 以上。\n"
+                + DIAG.format(port=port) + f"\nstderr: {err}"), 1
+    if res is None:
+        err = err_text()
+        return ("CONNECT-FAIL：服务进程提前退出。\n" + DIAG.format(port=port)
+                + f"\nstderr: {err}"), 1
+    if "error" in res:
+        err_text()
+        return "ERROR: " + json.dumps(res["error"], ensure_ascii=False), 1
+
+    txt = ""
+    for part in res.get("result", {}).get("content", []):
+        if part.get("type") == "text":
+            txt += part.get("text", "")
+    err_text()
+
+    # MCP 把「连不上 Blender」包装成正常文本返回，rc 会被误判为 0。
+    # 买家看到绿色的“跑完了”其实一次都没连上——必须翻成失败。
+    low = txt.lower()
+    if "could not connect to blender" in low or low.startswith("error executing code"):
+        return (f"CONNECT-FAIL：服务起来了，但连不上 Blender。\n"
+                f"服务端原话：{txt.strip()[:300]}\n" + DIAG.format(port=port)), 1
+    return txt, 0
+
+
+def main():
+    ap = argparse.ArgumentParser(
+        description="经 Blender MCP 在运行中的 Blender 内执行 bpy 代码")
+    ap.add_argument("script", nargs="?", help="要执行的 .py 文件；省略则从 stdin 读")
+    ap.add_argument("--timeout", type=int, default=DEFAULT_TIMEOUT,
+                    help=f"硬超时秒数（默认 {DEFAULT_TIMEOUT}；渲染/模拟给 300+）")
+    ap.add_argument("--port", type=int, default=None,
+                    help=f"Blender MCP 端口（默认 {DEFAULT_PORT}；可用 BLENDER_PORT 环境变量覆盖）")
+    a = ap.parse_args()
+    # 显式 --port 优先；否则才去校验 BLENDER_PORT（校验失败 → 人话 + exit 2，不是 traceback）
+    port = a.port if a.port is not None else _port_from_env()
+
+    if a.script and os.path.exists(a.script):
+        with open(a.script, encoding="utf-8") as f:
+            code = f.read()
+    elif a.script:
+        # 走 stderr + 退出码 2（用法错误），与 docstring 一致；旧版 sys.exit(str) 实际返回 1
+        sys.stderr.write(
+            "❌ 文件不存在: %s\n"
+            "   检查路径拼写；或者省略脚本参数，改用 stdin 传代码：\n"
+            "   echo \"import bpy; print(len(bpy.data.objects))\" | python blender_mcp_exec.py\n"
+            % a.script)
+        return 2
+    else:
+        if sys.stdin.isatty():
+            ap.print_help()
+            return 2
+        code = sys.stdin.read()
+
+    out, rc = run_code(code, a.timeout, port)
+    print(out)
+    return rc
+
+
+if __name__ == "__main__":
+    sys.exit(main())

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

@@ -1,16 +1,12 @@
 ---
 name: blender-modeling-cookbook
-description: "Blender 建模技法库：参数化 bpy 构建、BMesh 操作、修改器栈、拓扑规则、UV 展开，以及让 low-poly 资产圆润的选择性 Bevel 配方。"
-whenToUse: "Blender 建模 / bpy / BMesh / 修改器 / 拓扑 / UV / Bevel 时"
+description: "Blender 建模技法库：参数化 bpy 构建、BMesh 操作、修改器栈、拓扑规则、UV 展开、选择性 Bevel 配方（圆润 low-poly 来源）。锚定 5.2 LTS。"
+whenToUse: "Blender 建模 / 渲染 / 导出 / 排障 / MCP 接线 时"
 license: MIT
 ---
 
-
 # 建模技法库（blender-modeling-cookbook）
 
-> DSH 执行层（headless 跑 Blender、渲染、导出）：见 `blender-studio` 技能。
-
-
 **沉淀实战建模技法，供 `blender-modeling` 与全员复用。** 锚定 Blender 5.2 LTS；语法不假设 4.x。
 
 ## §1 参数化 bpy 构建范式
@@ -49,7 +45,7 @@ license: MIT
 
 - **连续网格优于逐立方体**：地面/地形用一整张 heightfield，顶点色 splat 只在边界带、块中心纯色 → 无缝、色不糊。逐立方体各自顶点色无法跨 mesh 衔接（缝 + 色糊反模式）。
 - **低模代理**：quad 优先、拓扑干净、三角预算写死（tile ≤ 200、树 ≤ 1500）。
-- **重拓扑/UV/绑定必须人审**（StraySpark 硬限制 #1）。
+- **重拓扑/UV/绑定必须人审**（三硬限制 #1）。
 
 ## §5 UV 展开
 
@@ -59,10 +55,20 @@ license: MIT
 ## §6 LOD 与导出
 
 - Decimate 生成 LOD（LOD1=50% / LOD2=75% / LOD3=90% 缩减）。
-- glTF/GLB 只出几何（5.2 丢色），颜色下游引擎套（见 `blender-5x-pitfalls` / `blender-sop` §4）。
+- 顶点色须接进材质再导出（否则 `COLOR_0` 降为 ubyte），见 `blender-5x-pitfalls` 致命级 3 / `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 脚本。
+- helper：`scripts/blender_mcp_exec.py` 本地执行 bpy 脚本。
+
+## 无 Blender 时的参数交付
+
+建模跑不了，**参数照样必须给全** —— 按 `templates/model_spec.md` 填：
+
+- 尺寸（X×Y×Z，米）、三角面上限、UV 通道数、材质槽数、LOD 级数
+- 全局约定写死：+Y up 导出、变换必须应用、导出前三角化
+- 材质与贴图：贴图尺寸、是否共用图集、**移动端尽量不用 Alpha Blend**
+
+**参数给到能被照着做**，而不是"这个模型大概八百面左右"。

package/skills/blender-sop/SKILL.md

@@ -1,19 +1,50 @@
 ---
 name: blender-sop
-description: "Blender 专业标准：5.2 LTS 基线、Cycles/Eevee 抉择、CC0 资产红线、glTF/USD 导出纪律，以及 agent 驱动 Blender 协作的三条硬限制。所有管线判断的单一真相源。"
-whenToUse: "Blender / 渲染器选择 / Cycles / Eevee / CC0 / glTF / USD / 导出规范 时"
+description: "Blender 工作室专业标准大脑：5.2 LTS 基线、Cycles/Eevee 抉择、CC0 资产红线、glTF/USD 导出纪律、Agent+MCP 协作三硬限制。一切管线判断的单一真相源。"
+whenToUse: "Blender 建模 / 渲染 / 导出 / 排障 / MCP 接线 时"
 license: MIT
 ---
 
-
 # Blender 专业标准（blender-sop）
 
-> DSH 执行层（headless 跑 Blender、渲染、导出）：见 `blender-studio` 技能。
+> **DSH 适配**：本技能来自专家团 v1.3.6。文中的「主理人」= 你本人，「成员 / 派单」= 你的子任务或子代理，「回执」= 你的交付记录。单 agent 场景下这些纪律同样成立。
 
 
 **所有管线判断以此为准。** 本技能是 Blender 工作室的"大脑"，版本/渲染器/资产/导出/协作纪律的单一真相源。
 
-## §1 版本基线（务必写准，别犯 Godot 的版本错）
+## §0 没有 Blender 时的标准交付（先给东西，再要东西）
+
+**没装 Blender、MCP 连不上、或用户只想先看方案时，本团不是"等环境"，而是先把能用的东西交出去。**
+
+按 `templates/` 下四份表填写，**填完即为可交产物，不需要打开 Blender**：
+
+| 模板 | 填什么 | 交付形态 |
+|---|---|---|
+| `templates/asset_list.md` | 资产清单：资产名 / 类型 / 用途 / 面数预算 / 命名 | md（可交给建模的人直接开工） |
+| `templates/model_spec.md` | 建模参数：尺寸（米）/ 三角面上限 / UV 通道 / 材质槽 / LOD | md |
+| `templates/naming_export.md` | 命名前缀 + **glTF 导出参数**（+Y up / 单位 / 三角化 / 切线 / 动画）+ 目录结构 | md |
+| `templates/delivery_checklist.md` | 交付检查表：命名 / 面数 / UV / 材质 / **导出可回读** / 预览图 | md |
+
+另有两份**工序单**（做 UV / 布光时照单执行，填写同样不需要 Blender）：
+
+| 模板 | 填什么 | 交付形态 |
+|---|---|---|
+| `templates/uv_unwrap.md` | UV 展开打包工序：标记缝合边 → 展开 → 打包优化；**打包率验收线 0.75** | md（工序单+实测值） |
+| `templates/lighting_exposure.md` | 布光/曝光工序：三点布光 → 曝光校准 → 观感自检（复用 C4 成品渲染配方） | md（工序单+实测值） |
+
+**纪律（四条）**：
+
+1. **不许只回「请先安装 Blender」就结束** —— 那是把工作推回给买家，而他要的是方案。
+2. **不许编造"已建模 / 已渲染 / 已导出"** —— 没连上就不说做了，但**方案必须交付**。
+3. **四份表跨表咬合检查（交付前必跑，可执行步骤）**：以 `asset_list` 为基准表，与 `model_spec` / `naming_export` / `checklist`（含成员并行产出的表）逐资产核对**七项字段**：资产名（逐字）/ 尺寸（米）/ 面数预算（目标+上限）/ UV 通道 / 材质名 / 导出格式 / 交付形态（主件与备件）。机器检查：`python3 scripts/check_table_consistency.py <表A> <表B>`（exit 0 且无输出 = 咬合；有输出 = 矛盾清单，每条带文件行号）；表单自由到机器查不动时，人肉对同七项。**任何一项不一致 = 不许宣称「表已咬合」**，处置只有两种：改到一致，或标「待拍板」挂给老板拍板。没跑过这项检查，禁止使用「基本咬合」「只剩一处遗留」这类状态词。
+4. **共同前提卡（并行派单前必锁）**：并行给两个及以上成员派单前，先发**共同前提卡**锁死 **4 个数字：资产名 / 尺寸（米）/ 面数预算（目标+上限）/ 导出格式**，随派单一起下发。成员回报必须逐项回显这 4 个数字；任何成员想偏离其中任一项，必须先请示主理人转老板拍板，**不许自改**。实机测试（2026-11-02）暴露的教训：无此卡时同批表会出现尺寸 0.6/0.8、上限 ≤800/≤400、UV0/UV0+UV1、材质名带不带 `_01`、FBX/GLB 主件各写各的——5 处矛盾全因此而起。
+
+**自检**：`python3 scripts/check_templates.py --selftest`（验四份齐全、表头与示例对齐、顶部声明、SKILL 已引用）。
+
+**装好 Blender + MCP 之后**：这四份表就是施工图 —— 按 `asset_list` 建对象、按 `model_spec` 控参数、
+按 `naming_export` 命名与导出、用 `delivery_checklist` 逐项验收。
+
+## §1 版本基线（务必写准版本号）
 
 - **最新稳定**：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。
@@ -38,13 +69,13 @@ license: MIT
 
 ## §4 导出纪律（glTF/USD/FBX）
 
-- **glTF/GLB**：游戏/AR 默认。本环境 **5.2 glTF 导出器丢色**（顶点色→白色 `COLOR_0`+畸形 `COLOR_1`；纯色材质→无 `pbrMetallicRoughness`）→ **GLB 只出几何，颜色在下游引擎侧套**（Godot/Maya/Unity 建材质）。
+- **glTF/GLB**：游戏/AR 默认。**顶点色默认导出会降位**（`COLOR_0` 变 ubyte + 多出畸形 `COLOR_1`），根因是顶点色没被材质节点树引用；**解法：把顶点色接进材质（ShaderNodeVertexColor → Base Color）或导出时 `export_vertex_color='ACTIVE'`**。精确控色要求高时，仍可「GLB 只出几何、颜色到引擎侧套」（最稳，非唯一解）。纯色材质实测 `pbrMetallicRoughness` 正常，不受影响。**能不能不自认倒霉请先自测** → `blender-5x-pitfalls` 致命级第 3 条附 10 秒自检脚本。
 - **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）
+## §5 Agent+MCP 协作三硬限制
 
 1. **创意拓扑不是 agent 的活**：概念/大形/风格/轮廓决策由**人**做；agent 只接手可参数化、可验证子任务（blockout / 低模代理）。手动重拓扑/UV/绑定/动画必须人审。
 2. **重操作超时 60–120s**：细分/重拓扑/烘焙/模拟 bake 会超时——须拆小步、降分辨率、或交人手动在 Blender 内跑。
@@ -52,13 +83,47 @@ license: MIT
 
 ## §6 Blender-MCP 协作铁律
 
-- **连接前提**：Blender 必须开着且插件服务端已启动（N 面板 → BlenderMCP → Start MCP Server）。无连接证明（如 `get_addon_status` 已连）前，任何成员不得声称能操控 Blender。
+- **连接前提**：Blender 必须开着且插件服务端已启动（N 面板 → `MCP for Blender`（旧版显示为 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 工具全量注入→幻觉"教训）。
+- **工具按需加载**：只亮少量核心工具（get_addon_status / get_scene_info / execute_blender_code / look），重工具经 `search_assets`/`generate_3d` 调用，别全量塞（工具全量注入会显著抬高小模型的幻觉率）。
 - **造模上云、精修在本地**：`generate_3d`（tripo/hunyuan3d/hyper3d）云端造模绕开本地重算超时（硬限制 #2）；精修留本地 bpy。
 - **隐私**：默认本地优先（127.0.0.1）；云端造模经 `uvx` 运行时，须显式告知用户数据出站。
 
 ## §7 修改与同步纪律
 
 本技能为团队标准基线。每次建模/渲染发现的新技法/坑/规范 → 回写本 SKILL.md 对应章节 + MEMORY.md（项目级）。不擅自推翻 §1–§6 级红线；涉及决策变更先与主理人（艾芙琳）对齐。
+
+## §8 工序条目（建模/雕刻/导出前的硬工序）
+
+> 以下工序是**非过不可的步骤**，不是建议。每条都带可断言的验收线——做完必须自检数字，不许「看起来没问题」。
+
+### §8.1 雕刻基底密度门槛
+
+- **雕刻/有机形基底一律高细分球**：`u_segments=128 × v_segments=96`（≈1.2 万顶点），不许用默认球（默认 32×16 只有 2562 顶点，撑不住雕刻级形变）。
+- 断言：基底顶点数 **≥1 万**再开始形变。
+
+### §8.2 导出前冻结变换 + 应用修改器
+
+- 导出前必做：`bpy.ops.object.transform_apply(location=True, rotation=True, scale=True)` + `modifier_apply` 逐个应用栈内修改器。
+- 断言：回读尺寸差 **= 0.0**（不冻结时实测漂移 8.2%）。
+
+### §8.3 布尔/倒角后拓扑卫生
+
+- `boolean` / `bevel` 后必做三件：`bmesh.ops.remove_doubles(dist=1e-5)` → `bmesh.ops.recalc_face_normals` → **winding 冲突断言 = 0**（两面共享边被同向遍历即冲突）。
+- 断言：winding 冲突 0、signed volume > 0。
+
+### §8.4 修改器栈组合后断言流形
+
+- 多修改器（ARRAY/MIRROR 等）组合后，取**求值网格**（`evaluated_depsgraph_get`）断言非流形边 = 0；重叠实例处先焊接（remove_doubles）再断言。
+- 重叠缝不焊 → 求值网格非流形边暴涨（实测 1728 条）。
+
+### §8.5 旋成体封口规范
+
+- 旋成（spin）封口用 **spin + merge**（`use_merge=True` + `remove_doubles`），**禁止裸 ngon 封口**——裸 ngon 被细分后在盖面内部产生大价极点。
+- 断言：大价极点（价 >8）只允许出现在**旋转轴上**，轴外大价极点 = 0。
+
+### §8.6 对称雕刻镜像约束
+
+- 对称形体的形变权重**只用 `|x|`**（或镜像修改器约束），禁止左右各算一套。
+- 断言：镜像配对顶点最大偏差 **< 1e-3**（理想 1e-6）。