@jojonadam/dsh-blender 0.1.2 → 0.2.0

package/skills/blender-sop/scripts/check_table_consistency.py

@@ -0,0 +1,240 @@
+#!/usr/bin/env python3
+# -*- coding: utf-8 -*-
+"""跨表咬合检查（sop 纪律 3 的机器侧判据）。
+
+用法：
+    python3 scripts/check_table_consistency.py <表A.md> <表B.md>   # 双表对查，有矛盾 exit 1
+    python3 scripts/check_table_consistency.py --selftest          # 自测（5 真实矛盾全中 + 正常对 0 误报）
+
+口径（七项字段取六类可机查项）：
+    size 尺寸（米）/ tris 面数预算（目标+上限）/ uv UV 通道配置 / mat 材质名 /
+    fmt 导出格式（主件）/ asset 资产名
+规则：同类字段在两份表里**都有声明**且取值集合完全不相交 → 判矛盾（每条带文件行号）。
+范围限制（如实）：自由文本抽取，单主资产/同资产多表场景适用；多资产项目按资产分表分别跑。
+本判据的真阳性基准 = 2026-11-02 实机测试 5 处真实矛盾（见 --selftest fixtures 溯源注记）。
+"""
+import re
+import sys
+import tempfile
+import unicodedata
+from pathlib import Path
+
+
+def norm(s):
+    return unicodedata.normalize("NFKC", s)
+
+
+def num(tok):
+    try:
+        return str(float(tok)).rstrip("0").rstrip(".") if "." in tok else str(int(tok))
+    except ValueError:
+        return tok
+
+
+def lines_of(text):
+    return [(i + 1, ln) for i, ln in enumerate(norm(text).splitlines())]
+
+
+# —— 六类字段抽取器：返回 (value, lineno) 列表 ——————————————————————————
+
+def ex_size(rows):
+    out = []
+    ctx = re.compile(r"尺寸|外廓|大小|规格|尺度|箱体|尺寸参考")
+    tup = re.compile(r"(\d+(?:\.\d+)?)\s*[×xX\*]\s*(\d+(?:\.\d+)?)\s*[×xX\*]\s*(\d+(?:\.\d+)?)")
+    bare = re.compile(r"(\d+(?:\.\d+)?)\s*(?:m|米)\b")
+    for i, ln in rows:
+        if not ctx.search(ln):
+            continue
+        for m in tup.finditer(ln):
+            out.append(("x".join(num(g) for g in m.groups()), i))
+        for m in bare.finditer(ln):
+            out.append((num(m.group(1)), i))
+    return out
+
+
+def ex_tris(rows):
+    out = []
+    ctx = re.compile(r"面数|三角面|tri|预算|上限")
+    val = re.compile(r"(?:≤|<=|目标|上限)\s*(\d+)|(\d+)\s*tri\b")
+    for i, ln in rows:
+        if not ctx.search(ln):
+            continue
+        for m in val.finditer(ln):
+            out.append((num(m.group(1) or m.group(2)), i))
+    return out
+
+
+def ex_uv(rows):
+    """UV 配置声明：多通道表达式（UV0+UV1）或单通道声明（仅 UV0 / UV0 单通道）。"""
+    out = []
+    multi = re.compile(r"UV(\d+)\s*\+\s*UV(\d+)")
+    single = re.compile(r"仅\s*UV(\d+)|UV(\d+)\s*单通道")
+    for i, ln in rows:
+        for m in multi.finditer(ln):
+            out.append(("UV%s+UV%s" % (m.group(1), m.group(2)), i))
+        for m in single.finditer(ln):
+            out.append(("UV%s" % (m.group(1) or m.group(2)), i))
+    return out
+
+
+def ex_mat(rows):
+    out = []
+    ctx = re.compile(r"材质")
+    tok = re.compile(r"\bM_\w+")
+    for i, ln in rows:
+        if not ctx.search(ln):
+            continue
+        for m in tok.finditer(ln):
+            out.append((m.group(0), i))
+    return out
+
+
+def ex_fmt(rows):
+    out = []
+    ctx = re.compile(r"交付形态|导出格式|export_format|交付件|导出参数")
+    tok = re.compile(r"\b(FBX|GLB|glTF|USD|ABC)\b")
+    primary = re.compile(r"为主")
+    for i, ln in rows:
+        if not ctx.search(ln):
+            continue
+        found = tok.findall(ln)
+        if not found:
+            continue
+        if primary.search(ln):
+            out.append((found[0], i))
+        else:
+            for f in found:
+                out.append((f, i))
+    return out
+
+
+def ex_asset(rows):
+    out = []
+    tok = re.compile(r"\b(SM_\w+|SK_\w+)")
+    for i, ln in rows:
+        for m in tok.finditer(ln):
+            out.append((m.group(0).rstrip("_LOD123456789"), i))
+    return out
+
+
+CATEGORIES = [
+    ("size", "尺寸", ex_size),
+    ("tris", "面数预算", ex_tris),
+    ("uv", "UV 通道", ex_uv),
+    ("mat", "材质名", ex_mat),
+    ("fmt", "导出格式", ex_fmt),
+    ("asset", "资产名", ex_asset),
+]
+
+
+def extract(path):
+    rows = lines_of(Path(path).read_text(encoding="utf-8"))
+    return {key: fn(rows) for key, _label, fn in CATEGORIES}
+
+
+def compare(pa, pb, verbose=True):
+    """返回矛盾列表 [(category, label, valsA, linesA, valsB, linesB), ...]。"""
+    ea, eb = extract(pa), extract(pb)
+    bad = []
+    for key, label, _fn in CATEGORIES:
+        va = sorted(set(v for v, _i in ea[key]))
+        vb = sorted(set(v for v, _i in eb[key]))
+        if not va or not vb:
+            continue
+        if set(va).isdisjoint(set(vb)):
+            la = sorted(set(i for _v, i in ea[key]))
+            lb = sorted(set(i for _v, i in eb[key]))
+            bad.append((key, label, va, la, vb, lb))
+            if verbose:
+                print("[矛盾] %s：%s %s（%s 行 %s）↔ %s %s（%s 行 %s）" % (
+                    label, Path(pa).name, "/".join(va), Path(pa).name, ",".join(map(str, la)),
+                    Path(pb).name, "/".join(vb), Path(pb).name, ",".join(map(str, lb))))
+    return bad
+
+
+# —— 自测 fixtures：5 处真实矛盾（2026-11-02 实机测试，欧文表 vs 西奥表） ————
+
+FIX_A = """# 自测件 A（溯源：欧文_表格.md 五矛盾缩样）
+| 项 | 值 |
+|---|---|
+| 单位 | 场景单位 1.0 = 1 米；箱子尺寸假设 0.6×0.6×0.6 m |
+| 导出参数 export_format | 'GLB' |
+| 交付件 | SM_Crate_Wood_01.glb（GLB 自包含） |
+| 材质 | `M_Crate_Wood` |
+| 面数 | 三角面 ≤ 800（LOD0） |
+| UV 通道 | 仅 UV0 单通道 |
+| 资产 | SM_Crate_Wood_01 |
+"""
+
+FIX_B = """# 自测件 B（溯源：西奥_表格_v2.md 五矛盾缩样）
+| 项 | 值 |
+|---|---|
+| 交付形态 | FBX + 贴图为主（Unity 原生导入）；GLB 备选 |
+| 资产清单 | SM_Crate_Wood_01，目标 300 / 上限 400 |
+| model_spec | SM_Crate_Wood_01，尺寸 0.80 × 0.80 × 0.80，三角面上限 ≤ 400，UV0 + UV1 |
+| 材质槽 | 1（M_Crate_Wood_01） |
+| 外廓 | 外廓仍 0.80 m 等边 |
+"""
+
+FIX_CLEAN_A = """# 自测件（正常对 A）
+| 项 | 值 |
+|---|---|
+| 资产 | SM_Crate_Wood_01 |
+| 尺寸 | 0.8×0.8×0.8 m |
+| 面数 | 三角面 ≤ 800 |
+| UV | 仅 UV0 单通道 |
+| 材质 | M_Crate_Wood_01 |
+| 导出 | 导出参数 export_format 'GLB'；交付件 SM_Crate_Wood_01.glb |
+"""
+
+FIX_CLEAN_B = """# 自测件（正常对 B）
+| 项 | 值 |
+|---|---|
+| 资产清单 | SM_Crate_Wood_01 |
+| 尺寸 | 0.80 × 0.80 × 0.80 |
+| 面数 | 目标 600 / 上限 800 |
+| UV 通道 | UV0 单通道 |
+| 材质槽 | M_Crate_Wood_01 |
+| 交付形态 | GLB 为主 |
+"""
+
+
+def selftest():
+    d = Path(tempfile.mkdtemp(prefix="xcheck_"))
+    a, b = d / "A.md", d / "B.md"
+    a.write_text(FIX_A, encoding="utf-8")
+    b.write_text(FIX_B, encoding="utf-8")
+    bad = compare(str(a), str(b), verbose=True)
+    keys = set(k for k, *_ in bad)
+    want = {"size", "tris", "uv", "mat", "fmt"}
+    ok1 = want <= keys
+    print("真阳性（5 真实矛盾）：%s → %s" % (sorted(keys), "全中 ✅" if ok1 else "漏报 ❌"))
+    ca, cb = d / "clean_A.md", d / "clean_B.md"
+    ca.write_text(FIX_CLEAN_A, encoding="utf-8")
+    cb.write_text(FIX_CLEAN_B, encoding="utf-8")
+    bad2 = compare(str(ca), str(cb), verbose=False)
+    ok2 = not bad2
+    print("正常对误报：%d 条 → %s" % (len(bad2), "0 误报 ✅" if ok2 else "误报 ❌ %s" % bad2))
+    if ok1 and ok2:
+        print("SELFTEST PASS（真阳性全中 + 正常表 0 误报）")
+        return 0
+    print("SELFTEST FAIL")
+    return 1
+
+
+def main(argv):
+    if len(argv) == 2 and argv[1] == "--selftest":
+        return selftest()
+    if len(argv) != 3:
+        print(__doc__)
+        return 2
+    bad = compare(argv[1], argv[2])
+    if bad:
+        print("共 %d 处矛盾——不许宣称「表已咬合」；改到一致或标「待拍板」。" % len(bad))
+        return 1
+    print("咬合 ✅（六类可机查项双方声明一致；七项中的「交付形态主/备件」含在 fmt）")
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main(sys.argv))

package/skills/blender-sop/scripts/check_templates.py

@@ -0,0 +1,165 @@
+#!/usr/bin/env python3
+"""离线模板自检（blender-studio v1.3.4）。
+
+## 这是什么、不是什么
+
+**不是生成器**——不产出任何内容，只回答一件事：
+**包里这四份模板，是不是都能真的填、且彼此不打架、SKILL 里也指得到？**
+
+为什么需要：这一版把「没装 Blender 也能交付」落成了四份表。模板最容易出的问题不是缺失，
+而是**「在但没用」**——表头列数与示例行对不上（填进去就错位）、SKILL 里没引用（agent 想不到调）。
+任何一条都会让买家拿到「看起来有、实际不能用」的东西。
+
+## 判据
+
+1. 六份模板都在且非空
+2. 每张 md 表的**表头列数 == 分隔行列数 == 示例行列数**（对不上就会填错位）
+3. 每份顶部都有「本表不需要 Blender 即可填写交付」声明
+4. SKILL 里确实引用了六个路径（防「模板在但没人用」）
+5. **反向**：删一份模板 / 把示例行列数改坏 → 必须报错
+   （只做正向断言，判据坏了也照样绿）
+"""
+import pathlib
+import re
+import sys
+
+try:  # 控制台编码兜底：中文 Windows 控制台是 cp936，打不出 ✅/❌
+    import _console
+
+    _console.ensure_utf8()
+except Exception:                                                # noqa: BLE001
+    pass
+
+PKG = pathlib.Path(__file__).resolve().parents[1]
+TPL = {
+    "asset_list.md": "资产清单表",
+    "model_spec.md": "建模参数表",
+    "naming_export.md": "命名与导出规范",
+    "delivery_checklist.md": "交付检查表",
+    "uv_unwrap.md": "UV 展开打包工序单",
+    "lighting_exposure.md": "布光/曝光工序单",
+}
+DECL = "不需要 Blender 即可填写交付"
+
+
+def _tables(path: pathlib.Path) -> list[tuple[list[str], list[str], list[str], int]]:
+    """→ [(表头列, 分隔行列, 示例行列, 行号)]；只取带分隔行（|---|）的真表。"""
+    lines = path.read_text(encoding="utf-8").splitlines()
+    out = []
+    for i in range(len(lines) - 2):
+        head, sep, first = lines[i].strip(), lines[i + 1].strip(), lines[i + 2].strip()
+        if not (head.startswith("|") and sep.startswith("|") and first.startswith("|")):
+            continue
+        if not re.fullmatch(r"\|[\s:|-]+\|", sep):
+            continue
+        cell = lambda s: [c for c in s.strip().strip("|").split("|")]
+        out.append((cell(head), cell(sep), cell(first), i + 1))
+    return out
+
+
+def check_all(root: pathlib.Path | None = None) -> list[str]:
+    """→ 问题清单（空 = 通过）。root 可替换，便于反向测试。"""
+    root = root or PKG
+    tdir = root / "templates"
+    bad: list[str] = []
+
+    # ① 四份都在且非空
+    for name, label in TPL.items():
+        f = tdir / name
+        if not f.is_file():
+            bad.append(f"缺模板：{name}（{label}）")
+        elif not f.read_text(encoding="utf-8").strip():
+            bad.append(f"模板为空：{name}（{label}）")
+    if bad:
+        return bad
+
+    # ② 表头 / 分隔行 / 示例行列数一致
+    for name in TPL:
+        tabs = _tables(tdir / name)
+        if not tabs:
+            bad.append(f"{name} 里没有可填的表（没找到「表头+分隔行+示例行」）")
+            continue
+        for head, sep, first, ln in tabs:
+            if not (len(head) == len(sep) == len(first)):
+                bad.append(f"{name}:{ln} 列数不一致：表头 {len(head)} / 分隔行 {len(sep)} / "
+                           f"示例行 {len(first)}（填进去会错位）")
+
+    # ③ 顶部声明
+    for name in TPL:
+        head_text = "\n".join((tdir / name).read_text(encoding="utf-8").splitlines()[:6])
+        if DECL not in head_text:
+            bad.append(f"{name} 顶部缺「{DECL}」声明")
+
+    # ④ SKILL 引用
+    corpus = "\n".join(s.read_text(encoding="utf-8")
+                       for s in (root / "skills").rglob("SKILL.md"))
+    for name in TPL:
+        if name not in corpus:
+            bad.append(f"没有任何 SKILL.md 引用 templates/{name}（模板在但没人用）")
+
+    return bad
+
+
+def main() -> int:
+    if "--selftest" not in sys.argv:
+        bad = check_all()
+        if bad:
+            print("❌ 模板自检未通过：")
+            for b in bad:
+                print(f"   · {b}")
+            return 1
+        print("✅ 模板自检通过：六份齐全、表头与示例对齐、顶部声明在、SKILL 已引用")
+        return 0
+
+    print("==== 离线模板自检（blender-studio）====")
+    fails, checks = [], []
+
+    def ck(label, cond, detail=""):
+        checks.append(label)
+        print(("  ✅ " if cond else "  ❌ ") + label + ("" if cond else f"   —— {detail}"))
+        if not cond:
+            fails.append(label)
+
+    bad = check_all()
+    ck("① 六份模板齐全且非空", not [b for b in bad if "缺模板" in b or "模板为空" in b],
+       [b for b in bad if "模板" in b][:3])
+    ck("② 表头列数 == 示例行列数（每张表）",
+       not [b for b in bad if "列 vs 示例行" in b or "没有可填的表" in b],
+       [b for b in bad if "列" in b][:3])
+    ck("③ 六份顶部都有「不需要 Blender 即可填写交付」声明",
+       not [b for b in bad if "声明" in b], [b for b in bad if "声明" in b][:3])
+    ck("④ SKILL 引用了六个模板路径", not [b for b in bad if "SKILL" in b],
+       [b for b in bad if "SKILL" in b][:3])
+
+    # 反向：判据必须能失败
+    import shutil
+    import tempfile
+    tmp = pathlib.Path(tempfile.mkdtemp(prefix="btpl_"))
+    try:
+        shutil.copytree(PKG / "templates", tmp / "templates")
+        shutil.copytree(PKG / "skills", tmp / "skills")
+
+        (tmp / "templates" / "model_spec.md").unlink()
+        ck("⑤ 反向：删一份模板 → 必须报错", bool(check_all(tmp)), "删了却没报错")
+        shutil.copy(PKG / "templates" / "model_spec.md", tmp / "templates" / "model_spec.md")
+
+        _f = tmp / "templates" / "asset_list.md"
+        _t = _f.read_text(encoding="utf-8")
+        # 把某张表的分隔行多切一列 → 表头与示例行列数仍相等，但分隔行不一致（格错位）
+        _t = _t.replace("|---|---|---|---|---|---|---|", "|---|---|---|---|---|---|---|---|", 1)
+        _f.write_text(_t, encoding="utf-8")
+        ck("⑥ 反向：分隔行列数与表头不一致 → 必须报错", bool(check_all(tmp)), "列数错了却没报错")
+    finally:
+        shutil.rmtree(tmp, ignore_errors=True)
+
+    print()
+    print(f"断言数：{len(checks)}")
+    if fails:
+        print(f"❌ {len(fails)} 项失败：{fails}")
+        return 1
+    print("── 离线模板自检全部通过")
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())

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

@@ -0,0 +1,43 @@
+# 资产清单表
+
+> **本表不需要 Blender 即可填写交付；填完即为可交产物。**
+> 用法：一行一个资产，先填「资产名 / 类型 / 用途」，再按用途给面数预算与命名。
+> 填完连同 `model_spec.md` / `naming_export.md` / `delivery_checklist.md` 一起交付。
+
+## 一 项目基本信息
+
+| 项 | 填写 |
+|---|---|
+| 项目 / 包名 | 【填】如 `lowpoly_props_pack_01` |
+| 交付形态 | 【填】单个 blend / glTF + 贴图 / 两者都要 |
+| 目标平台 | 【填】Unity / Unreal / 网页 / 移动端 |
+| 渲染风格 | 【填】low-poly / 写实 / 卡通 |
+| 单位约定 | 【填】1 单位 = 1 米（默认） |
+
+## 二 资产清单
+
+> 面数预算指**三角面**（tri），不是四边面。超出预算的资产必须写明原因。
+
+| # | 资产名 | 类型 | 用途 | 面数预算（tri） | 命名 | 备注 |
+|---|---|---|---|---|---|---|
+| 1 | 【填】SM_Sword_Proxy_01 | 道具 | 主手武器，第一人称可见 | 【填】≤ 800 | `SM_<名>_<变体>` | 【填】需 LOD1 |
+| 2 | 【填】SM_Crate_Wood_01 | 道具 | 场景可破坏物 | 【填】≤ 300 | 同上 | 【填】 |
+| 3 | 【填】ENV_Room_Corner_01 | 环境 | 模块化场景拼块 | 【填】≤ 2000 | `ENV_<名>_<尺寸>` | 【填】贴图可复用 |
+| 4 | 【填】CH_NPC_Merchant_01 | 角色 | 对话 NPC，不参与战斗 | 【填】≤ 6000 | `CH_<名>_<编号>` | 【填】需骨骼 |
+| — | **合计** | — | — | **【填】** | — | — |
+
+## 三 类型说明（照这个口径填，别自己造）
+
+| 类型 | 前缀 | 典型面数 | 是否含骨骼 |
+|---|---|---|---|
+| 道具（Prop） | `SM_` | 100–2000 | 否 |
+| 环境（Environment） | `ENV_` | 500–20000 | 否 |
+| 角色（Character） | `CH_` | 3000–50000 | 是 |
+
+## 四 缺失信息清单（没有就写"待客户确认"，别猜）
+
+| 项 | 状态 |
+|---|---|
+| 参考图 / 概念稿 | 【填】已提供 / 待提供 |
+| 尺寸参考（真实尺寸或比例） | 【填】 |
+| 数量与变体（是否要换色/换材质） | 【填】 |

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

@@ -0,0 +1,60 @@
+# 交付检查表
+
+> **本表不需要 Blender 即可填写交付；填完即为可交产物。**
+> 用法：交付前逐项打勾。**没做过的项不能打勾**——宁可写「未做，原因：」，也不要空着或写「已检查」。
+
+## 一 资产与命名
+
+| # | 检查项 | 判据 | 结果 |
+|---|---|---|---|
+| 1 | 命名全部符合前缀规则 | 无中文、无空格、无 `final`/`副本` | 【填】✅ / ❌ |
+| 2 | 资产数量与 `asset_list.md` 一致 | 行数对得上，无遗漏或多出 | 【填】 |
+| 3 | 集合/层级按类型分组 | 道具/环境/角色分开 | 【填】 |
+| 4 | 无隐藏的无用物体 | 空物体、冻结的参考图已删 | 【填】 |
+
+## 二 面数与几何
+
+| # | 检查项 | 判据 | 结果 |
+|---|---|---|---|
+| 5 | 每个资产面数 ≤ 预算 | 与 `model_spec.md` 逐行对照 | 【填】 |
+| 6 | 已三角化（导出前） | 导出 glb 后读回检查 | 【填】 |
+| 7 | 变换已应用 | 位置/旋转/缩放均为 1.0 / 0 | 【填】 |
+| 8 | 原点位置符合约定 | 中心 / 底部 / 轴心（见规范） | 【填】 |
+| 9 | 无重叠面、无翻转法线 | 视图层里看背面剔除 | 【填】 |
+
+## 三 UV 与材质
+
+| # | 检查项 | 判据 | 结果 |
+|---|---|---|---|
+| 10 | UV 无重叠（除镜像） | UV 编辑器重叠检查 | 【填】 |
+| 11 | 贴图密度一致 | 各资产 texel 密度接近 | 【填】 |
+| 12 | 材质槽数与规范一致 | 与 `model_spec.md` 对照 | 【填】 |
+| 13 | 贴图命名 `T_` 前缀 | 与 `naming_export.md` 一致 | 【填】 |
+| 14 | 无法线贴图时切线已关 | 避免无谓体积 | 【填】 |
+
+## 四 导出可回读（**这一项最容易被跳过**）
+
+| # | 检查项 | 判据 | 结果 |
+|---|---|---|---|
+| 15 | glb/gltf 能导入空场景 | New File → Import，无报错 | 【填】 |
+| 16 | 尺寸与朝向正确 | 量包围盒、确认 +Y up | 【填】 |
+| 17 | 材质与贴图完整 | 导入后颜色/法线都在 | 【填】 |
+| 18 | 动画（若含）能播放 | 时间轴播放无错位 | 【填】 |
+| 19 | 文件体积在预期内 | 与预算对照，异常大先查贴图 | 【填】 |
+
+## 五 交付包
+
+| # | 检查项 | 判据 | 结果 |
+|---|---|---|---|
+| 20 | 目录结构符合规范 | `source/` `export/` `textures/` `docs/` | 【填】 |
+| 21 | 四份文档齐全 | asset_list / model_spec / naming_export / 本表 | 【填】 |
+| 22 | 预览图已出 | 至少一张，命名 preview_编号.png（例 preview_01.png） | 【填】 |
+| 23 | 无临时文件 | 无 `.blend1`、`.DS_Store`、`新建文件夹` | 【填】 |
+
+## 六 签字
+
+| 项 | 填写 |
+|---|---|
+| 检查人 | 【填】 |
+| 检查日期 | 【填】 |
+| 未完成项及原因 | 【填】如「第 18 项未做：本包不含动画」 |

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

@@ -0,0 +1,40 @@
+# 布光/曝光工序单（三点布光 → 曝光校准 → 渲染观感自检）
+
+> 本表不需要 Blender 即可填写交付（执行工序时才开 Blender）。配方从 C4 成品渲染（✅6/6）抽成，复用到材质预览/资产展示渲染。
+
+## 1. 三点布光（照抄 C4 配方，锚 C4 EEVEE/Cycles 占比 0.68 ✓）
+
+| 灯 | 类型 | 位置 | 能量 | 尺寸 | 要点 |
+|---|---|---|---|---|---|
+| 主光 | SUN | (4, -6, 8) | 3.0 | — | 斜上方 45° 打主体 |
+| 补光 | AREA | (-5, -3, 3) | 40.0 | 4.0 | 补暗部，尺寸大则阴影软 |
+| 轮廓光 | AREA | (5, 4, 2) | 15.0 | 4.0 | 从后侧勾边 |
+
+- **灯光默认朝 -Z，必须逐灯旋转指向目标点**（`to_track_quat("-Z","Y")`），否则侧面全黑。
+- 相机参考（单物体）：loc=(3.0, -3.2, 2.1)，lens=60，指向原点。
+- `film_transparent = True`（透明背景，方便量构图占比/合成）。
+
+## 2. 曝光/观感验收线（写死）
+
+| 判据 | 阈值 | 出处 |
+|---|---|---|
+| 明暗层次（luma_std） | **> 0.02** | C2 判据范式；缺布光实测 0.012 全黑 |
+| 明暗跨度（luma_max − luma_min） | **> 0.08** | C2 判据范式；缺布光实测 0.006 |
+| 非纯色（unique_rgb_ratio） | > 0.05 | C2 判据范式 |
+| EEVEE/Cycles 占比 | ≥ 0.6 | C4 实测 0.68 ✓ |
+
+## 3. 填写（模型资产渲染交付时）
+
+| 项目 | 值 | 备注 |
+|---|---|---|
+| 资产名 | | 与 asset_list.md 对齐 |
+| 用途 | | 材质预览/成品渲染/展示图 |
+| 三灯能量（主/补/轮廓） | / / | 默认 3.0 / 40.0 / 15.0 |
+| luma_std 实测 | | 必须 > 0.02 |
+| 明暗跨度实测 | | 必须 > 0.08 |
+
+## 4. 常见翻车
+
+- 只加灯不旋转指向目标 → 侧面全黑（灯光默认朝 -Z）。
+- 没灯直接渲染 → luma_std 0.012、mean 0.006，判据必挂（C2 现状）。
+- 单灯硬光 → 明暗跨度够但 luma_std 偏低，按 §1 三灯配齐。

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

@@ -0,0 +1,40 @@
+# 建模参数表
+
+> **本表不需要 Blender 即可填写交付；填完即为可交产物。**
+> 用法：与 `asset_list.md` 一一对应，一个资产一行。**参数要能给到建模的人直接照着做**。
+
+## 一 全局约定
+
+| 项 | 值 |
+|---|---|
+| 单位 | 【填】米（Blender 默认 1 unit = 1 m） |
+| 朝向 | 【填】+Y up（导出时）；Blender 内 -Y 朝前 |
+| 缩放 | 【填】`Ctrl+A → Scale` 必须应用（1.0,1.0,1.0） |
+| 变换 | 【填】原点在世界中心 / 物体底部 / 轴心 |
+| 三角化 | 【填】导出前三角化（glTF 必须） |
+
+## 二 分资产参数
+
+| # | 资产名 | 尺寸（X×Y×Z, 米） | 三角面上限 | UV 通道 | 材质槽数 | LOD 级数 | 备注 |
+|---|---|---|---|---|---|---|---|
+| 1 | 【填】SM_Sword_Proxy_01 | 【填】0.06 × 1.10 × 0.12 | 【填】800 | UV0（贴图） | 1 | 【填】2（LOD0/LOD1） | 【填】握柄与刃口分开材质 |
+| 2 | 【填】SM_Crate_Wood_01 | 【填】0.80 × 0.80 × 0.80 | 【填】300 | UV0 | 1 | 1 | 【填】 |
+| 3 | 【填】ENV_Room_Corner_01 | 【填】4.00 × 4.00 × 3.00 | 【填】2000 | UV0 + UV1（光照图） | 2 | 【填】2 | 【填】模块化，4 边可拼 |
+| 4 | 【填】CH_NPC_Merchant_01 | 【填】0.60 × 0.45 × 1.75 | 【填】6000 | UV0 | 3 | 【填】3 | 【填】含骨骼，无表情 |
+
+## 三 材质与贴图
+
+| 项 | 填写 |
+|---|---|
+| 贴图尺寸 | 【填】2048×2048（主体）/ 1024（小件） |
+| 贴图类型 | 【填】BaseColor + Normal + ORM（R=AO/G=Rough/B=Metal） |
+| 是否共用图集 | 【填】是 / 否；若共用，列出同图集资产 |
+| 透明 | 【填】无 / Alpha Clip / Alpha Blend（**移动端尽量不用 Blend**） |
+
+## 四 建模要点（给动手的人）
+
+1. **先做 blockout 再细化**：比例对不上时，细化越细返工越大
+2. **保持四边面**，只在硬表面棱边加支撑线；导出前统一三角化
+3. **法线**：硬表面用自定义法线或加权重法线，别直接 Shade Smooth
+4. **UV**：接缝放在背面或不常看的一侧；贴图密度各资产之间尽量一致
+5. **命名与集合**：按 `naming_export.md` 的前缀分集合，方便一次选中导出

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

@@ -0,0 +1,61 @@
+# 命名与导出规范
+
+> **本表不需要 Blender 即可填写交付；填完即为可交产物。**
+> 用法：先定命名前缀，再核对导出参数。**导出的东西别人要能一次导进去，参数必须写全**。
+
+## 一 命名规则
+
+```
+<前缀>_<主体名>_<变体/尺寸>[_LOD<级别>]
+例：SM_Sword_Proxy_01        ENV_Room_Corner_4x4_01_LOD1
+```
+
+| 项 | 规则 |
+|---|---|
+| 前缀 | 【填】`SM_`（道具）/ `ENV_`（环境）/ `CH_`（角色）/ `MAT_`（材质）/ `T_`（贴图） |
+| 大小写 | 【填】全大写主体 + 首字母大写变体（**不用中文、不用空格**） |
+| 分隔符 | 【填】下划线 `_`，不用 `-`、不用 `.` |
+| 变体编号 | 【填】两位数字 `01` 起 |
+| LOD 后缀 | 【填】`_LOD0/_LOD1/...`，**LOD0 是最高精度** |
+| 禁止 | 【填】`final`、`最终版`、`copy`、`new`、个人缩写 |
+
+## 二 导出参数（glTF / glb）
+
+| 参数 | 值 | 为什么 |
+|---|---|---|
+| 格式 | 【填】`.glb`（单文件）/ `.gltf + .bin + 贴图` | 【填】glb 便于分发，gltf 便于改 |
+| +Y up | 【填】**开启**（Apply +Y up） | 引擎与 glTF 标准都是 Y 轴向上 |
+| 单位 | 【填】米（Scale 1.0） | 【填】Unity/UE 导入时按 1 米对应 |
+| 应用变换 | 【填】**导出前必做**（位置/旋转/缩放归零） | 否则引擎里尺寸错乱 |
+| 三角化 | 【填】开启 | glTF 只支持三角面 |
+| 法线 | 【填】导出 | 【填】不做则引擎自己算法线，硬表面会脏 |
+| 切线 | 【填】开启（有法线贴图时必须） | 无法线贴图则不需要 |
+| 动画 | 【填】含 / 不含 | 【填】角色含骨骼动画，道具不含 |
+| 材质 | 【填】导出 Principled BSDF → PBR | 【填】复杂节点树不会被导出 |
+| 贴图 | 【填】嵌进 glb / 单独放 textures/ | 【填】 |
+| 压缩 | 【填】不压缩 / Draco（注明需引擎支持） | 【填】Draco 能小 60%，但部分旧引擎不支持 |
+
+## 三 交付文件结构
+
+```
+【填】包名/
+  ├─ source/                    # 源文件
+  │   └─ 【填】包名.blend
+  ├─ export/
+  │   ├─ 【填】SM_xxx.glb
+  │   └─ 【填】CH_xxx.glb
+  ├─ textures/
+  │   └─ 【填】T_xxx_basecolor.png
+  └─ docs/
+      ├─ asset_list.md / model_spec.md
+      ├─ naming_export.md / delivery_checklist.md
+      └─ preview_01.png（预览图）
+```
+
+**规则**：源文件与导出物**分开放**；贴图单独目录；文档随包；**不要出现 `新建文件夹`、`副本`**。
+
+## 四 导出后必做的三件
+
+1. **重新导入一次**（New File → Import glTF），确认能读、尺寸与朝向正确
+2. **检查材质是否丢**（贴图路径、Principled 参数）
+3. **量一下面数与包围盒**，与 `model_spec.md` 的上限对齐