diff --git a/docs/superpowers/plans/2026-07-21-uvpm-packing-utilization.md b/docs/superpowers/plans/2026-07-21-uvpm-packing-utilization.md
new file mode 100644
index 00000000..efdb0e1a
--- /dev/null
+++ b/docs/superpowers/plans/2026-07-21-uvpm-packing-utilization.md
@@ -0,0 +1,259 @@
+# UVPM 排布利用率优化实现计划（旋转 + 启发式搜索）
+
+> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking.
+
+**Goal:** 在 `_uvpm_repack` 中开启 UVPM4 的旋转与启发式搜索，把薄条 UV 岛塞得更紧，明显提升 gargoyle 3000 的 UV 利用率而不退化其他指标。
+
+**Architecture:** 改动集中在 `bl_decimate.py` 的 `_uvpm_repack`（Blender 脚本）。因 UVPM4 属性名/默认值随版本可能不同，先用一次性探针脚本确认确切属性名与取值，再据实设置；属性设置走防御式 `_uvpm_set`（`hasattr` 才设），单个属性名不匹配只跳过、不拖垮整个 UVPM 排布。无纯函数可 TDD，靠探针 + 端到端验证（沿用本仓库约定）。
+
+**Tech Stack:** Python 3、Blender 5.0 headless（`bpy`）、UVPackmaster 4 扩展。
+
+---
+
+## File Structure
+
+- `Tools/ModelTranslator/bl_decimate.py`（Modify）：新增常量 `UVPM_ROTATION_STEP`/`UVPM_HEURISTIC_TIME` 与辅助 `_uvpm_set`；在 `_uvpm_repack` 的 margin 设置后、pack 前开启旋转+启发式。
+- `Tools/ModelTranslator/README.md`（Modify）：注明 UVPM 排布已开旋转+启发式。
+- `Tools/ModelTranslator/tests/bl_probe_uvpm.py`（Create then Delete）：一次性探针，不入库。
+
+---
+
+## Task 1: UVPM4 属性探针（spike）
+
+确认 UVPM4 `default_main_props` 的旋转/启发式属性名、默认值、类型，并验证 headless 下开启后能跑通 pack。结果决定 Task 2 的确切属性名与取值。
+
+**Files:**
+- Create: `Tools/ModelTranslator/tests/bl_probe_uvpm.py`（用完删除，不入库）
+
+- [ ] **Step 1: 写探针脚本**
+
+Create `Tools/ModelTranslator/tests/bl_probe_uvpm.py`:
+
+```python
+"""探针：枚举 UVPM4 default_main_props 的旋转/启发式/边距属性，并在测试网格上
+验证 headless 开启后能跑通 pack。运行：
+blender -b --factory-startup --python tests/bl_probe_uvpm.py"""
+import bpy
+import addon_utils
+
+# headless GPU 补丁（同 _uvpm_enable：UVPM 导入期建视口 shader 会 SystemError）
+import gpu
+_orig = gpu.shader.from_builtin
+def _safe(*a, **k):
+    try:
+        return _orig(*a, **k)
+    except SystemError:
+        return None
+gpu.shader.from_builtin = _safe
+
+UVPM_EXT = "bl_ext.user_default.uvpackmaster4"
+if addon_utils.enable(UVPM_EXT, default_set=True) is None:
+    print("UVPM_PROBE {'error': 'enable failed'}")
+    raise SystemExit
+
+p = bpy.context.scene.uvpm4_props.default_main_props
+
+# 枚举与 旋转/启发式/搜索/边距 相关的属性名 + 当前值
+keys = ("rot", "heurist", "search", "margin", "iter")
+props = {}
+for n in dir(p):
+    if n.startswith("_"):
+        continue
+    if any(k in n.lower() for k in keys):
+        try:
+            props[n] = repr(getattr(p, n))
+        except Exception as e:
+            props[n] = "ERR:%r" % e
+print("UVPM_PROPS " + repr(props))
+
+# 测试 pack：UV 球 smart_project，尽力开启旋转/启发式，跑一次 pack
+bpy.ops.mesh.primitive_uv_sphere_add()
+obj = bpy.context.view_layer.objects.active
+bpy.ops.object.mode_set(mode='EDIT')
+bpy.ops.mesh.select_all(action='SELECT')
+bpy.ops.uv.smart_project()
+
+def try_set(name, val):
+    if not hasattr(p, name):
+        return "absent"
+    try:
+        setattr(p, name, val)
+        return "ok=%r" % getattr(p, name)
+    except Exception as e:
+        return "ERR:%r" % e
+
+tried = {
+    "rotation_enable": try_set("rotation_enable", True),
+    "rotation_step": try_set("rotation_step", 90),
+    "heuristic_enable": try_set("heuristic_enable", True),
+    "heuristic_search_time": try_set("heuristic_search_time", 3),
+    "heuristic_max_wait_time": try_set("heuristic_max_wait_time", 3),
+}
+bpy.context.scene.tool_settings.use_uv_select_sync = True
+try:
+    ret = bpy.ops.uvpackmaster4.pack(mode_id='pack.single_tile', pack_op_type='0')
+    tried["pack"] = sorted(ret)
+except Exception as e:
+    tried["pack"] = "ERR:%r" % e
+finally:
+    bpy.ops.object.mode_set(mode='OBJECT')
+print("UVPM_TRY " + repr(tried))
+```
+
+- [ ] **Step 2: 运行探针**
+
+Run:
+```bash
+cd "d:/UD/AI/AIC#Project/Tools/ModelTranslator" && "D:\tools\blender-5.0.0-windows-x64\blender.exe" -b --factory-startup --python tests/bl_probe_uvpm.py 2>&1 | grep -E "UVPM_PROPS|UVPM_TRY|UVPM_PROBE"
+```
+Expected: 两行 `UVPM_PROPS {...}`（可用属性名+默认值）与 `UVPM_TRY {...}`（各属性设置结果 + `pack` 返回 `['FINISHED']`）。
+
+- [ ] **Step 3: 记录结论**
+
+从输出确认并记录：
+- 旋转属性的确切名（`rotation_enable` 是否存在？步进属性名与类型/取值范围，如 `rotation_step` 是 int 度数还是 enum）。
+- 启发式属性的确切名（`heuristic_enable`？时间上限是 `heuristic_search_time` 还是 `heuristic_max_wait_time`？单位/类型）。
+- `pack` 是否返回 `FINISHED`（确认 headless 可跑）。
+- 若启发式需要非 `'0'` 的 `pack_op_type` 或专门 mode，记录之。
+这些结论用于 Task 2 的确切属性名与常量取值。
+
+- [ ] **Step 4: 删除探针脚本**
+
+```bash
+cd "d:/UD/AI/AIC#Project/Tools/ModelTranslator" && rm tests/bl_probe_uvpm.py
+```
+（探针一次性、不入库；结论写入 Task 2 的 commit 正文。）
+
+---
+
+## Task 2: `_uvpm_repack` 开启旋转 + 启发式
+
+新增防御式 `_uvpm_set` 辅助与常量，在 `_uvpm_repack` 的 margin 设置后、pack 前开启旋转与启发式搜索。**属性名与取值以 Task 1 探针结论为准**——下方代码用最可能的名字，执行时按探针实测替换/校正。
+
+**Files:**
+- Modify: `Tools/ModelTranslator/bl_decimate.py`（常量区 + `_uvpm_repack` 之前新增 `_uvpm_set` + `_uvpm_repack` 内部）
+
+- [ ] **Step 1: 新增常量**
+
+在 `bl_decimate.py` 常量区 `UVPM_TEX_SIZE = 2048` 那一行之后追加（取值以探针结论校正）：
+
+```python
+UVPM_ROTATION_STEP = 90    # UVPM 旋转步进（度）；探针确认类型/范围后校正
+UVPM_HEURISTIC_TIME = 5    # UVPM 启发式搜索秒数上限
+```
+
+- [ ] **Step 2: 新增 `_uvpm_set` 辅助**
+
+在 `bl_decimate.py` 的 `_uvpm_repack` 函数**之前**新增：
+
+```python
+def _uvpm_set(p, name, value, warnings):
+    """防御式设 UVPM 属性：属性存在才设，否则记警告跳过——
+    名字不匹配（UVPM 版本差异）时降级为按原 margin 跑 UVPM，不丢整个排布。"""
+    if hasattr(p, name):
+        try:
+            setattr(p, name, value)
+        except Exception as e:
+            warnings.append("UVPM 属性 %s 设置失败（%s），跳过" % (name, e))
+    else:
+        warnings.append("UVPM 属性 %s 不存在，跳过" % name)
+```
+
+- [ ] **Step 3: 在 `_uvpm_repack` 开启旋转 + 启发式**
+
+在 `_uvpm_repack` 中，现有三行 margin 设置（`p.pixel_margin_enable = True` / `p.pixel_margin = UVPM_PIXEL_MARGIN` / `p.pixel_margin_tex_size = UVPM_TEX_SIZE`）之后、`bpy.context.scene.tool_settings.use_uv_select_sync = True` 之前，插入（属性名以 Task 1 为准替换）：
+
+```python
+        _uvpm_set(p, "rotation_enable", True, warnings)
+        _uvpm_set(p, "rotation_step", UVPM_ROTATION_STEP, warnings)
+        _uvpm_set(p, "heuristic_enable", True, warnings)
+        _uvpm_set(p, "heuristic_search_time", UVPM_HEURISTIC_TIME, warnings)
+```
+
+注意：
+- 若 Task 1 发现时间上限属性名是 `heuristic_max_wait_time`（而非 `heuristic_search_time`），把最后一行的名字换成实测的；`hasattr` 守卫使写错的名字只被跳过、不报错，但**为让功能真正生效，必须用探针确认的正确名字**。
+- 若 Task 1 发现启发式需要非 `'0'` 的 `pack_op_type`，同时修改 `_uvpm_repack` 里 `bpy.ops.uvpackmaster4.pack(...)` 的 `pack_op_type` 实参，并在 commit 正文说明。
+- 这些设置在现有 `_uvpm_repack` 的 `try/except Exception` 内；`_uvpm_set` 的 `hasattr` 守卫确保单属性问题不触发整体回退。
+
+- [ ] **Step 4: 语法自检 + 单测不回归**
+
+Run:
+```bash
+cd "d:/UD/AI/AIC#Project/Tools/ModelTranslator" && python -c "import ast; ast.parse(open('bl_decimate.py', encoding='utf-8').read()); print('OK')" && python -m unittest tests.test_bl_decimate 2>&1 | tail -3
+```
+Expected: `OK`，随后单测全 PASS（本改动无纯函数，仅确认无破坏）。（排布效果在 Task 3 端到端验证。）
+
+- [ ] **Step 5: 提交**
+
+```bash
+cd "d:/UD/AI/AIC#Project" && git add Tools/ModelTranslator/bl_decimate.py && git commit -m "ModelTranslator: _uvpm_repack 开启旋转+启发式搜索（防御式设属性）
+
+Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>"
+```
+（在 commit 正文补一句 Task 1 探针确认的确切属性名/取值，便于追溯。）
+
+---
+
+## Task 3: 端到端验证 + README
+
+**Files:**
+- Modify: `Tools/ModelTranslator/README.md`
+
+- [ ] **Step 1: 全量单测**
+
+Run:
+```bash
+cd "d:/UD/AI/AIC#Project/Tools/ModelTranslator" && python -m unittest tests.test_bl_decimate tests.test_uv_preview tests.test_unity_assets 2>&1 | tail -3
+```
+Expected: 全部 PASS。
+
+- [ ] **Step 2: 端到端主验收（gargoyle 3000）+ 计时**
+
+Run:
+```bash
+cd "d:/UD/AI/AIC#Project/Tools/ModelTranslator" && rm -f src/gargoyle_low_uv.png && PYTHONIOENCODING=utf-8 python -c "import time,subprocess,sys; t=time.time(); r=subprocess.run([sys.executable,'model_decimate.py','src/gargoyle.fbx','--tris','3000','--max-overlap','0.15'],capture_output=True,text=True,encoding='utf-8'); print(r.stdout[-800:]); print('ELAPSED %.1fs'%(time.time()-t))"
+```
+Expected: `模式=seam@45+uvpm`；岛数≈390（排布不改岛数）；**利用率明显高于基线 52.3%**；翻转 0%；重叠 ≤13.3%（不高于基线）。记录利用率与 `ELAPSED` 秒数（pack 增量）。若有 `UVPM 属性 … 不存在` 警告说明属性名未对齐，需回 Task 2 用探针名校正。
+
+- [ ] **Step 3: 观察图肉眼确认**
+
+用 Read 工具打开 `src/gargoyle_low_uv.png`，确认薄条岛塞得更紧、空白（黑块）区域明显减少。
+
+- [ ] **Step 4: 回归 well1500（正常 seam@66 情形）**
+
+Run:
+```bash
+cd "d:/UD/AI/AIC#Project/Tools/ModelTranslator" && PYTHONIOENCODING=utf-8 python model_decimate.py src/well1500.fbx --tris 5000 2>&1 | tail -4
+```
+Expected: 成功，无异常退出；`模式=seam@NN+uvpm`；利用率不低于其历史水平（排布增强不应变差）。
+
+- [ ] **Step 5: 更新 README**
+
+在 `Tools/ModelTranslator/README.md` 的 `- **model_decimate.py**：…` 那条中，把 `排布默认用 UVPackmaster 4 重排（只在最终选定 UV 上跑一次）` 这一处描述扩写为：
+
+```markdown
+排布默认用 UVPackmaster 4 重排（只在最终选定 UV 上跑一次，已开旋转+启发式搜索以提升薄条岛的利用率）
+```
+
+（只改这一处短语，不动其余。）
+
+- [ ] **Step 6: 提交**
+
+```bash
+cd "d:/UD/AI/AIC#Project" && git add Tools/ModelTranslator/README.md && git commit -m "ModelTranslator: README 注明 UVPM 已开旋转+启发式搜索
+
+Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>"
+```
+
+- [ ] **Step 7: 汇报前后对比**
+
+在最终汇报里给出：基线（seam@45 / 390 岛 / 52.3% / 翻转 0% / 重叠 13.3%）vs 现在（利用率 / 岛数 / 翻转 / 重叠 / pack 耗时），并附观察图观察结论。
+
+---
+
+## Self-Review 记录
+
+- **Spec 覆盖**：①探针确认属性名→Task 1；②`_uvpm_repack` 开旋转+启发式（防御式 `_uvpm_set` + 常量）→Task 2；③验证（gargoyle 主验收 + well1500 回归 + 观察图）→Task 3 Step 2-4；README→Task 3 Step 5；错误处理（属性名不匹配跳过、整体失败回退、启发式时间上限）→Task 2 `_uvpm_set` 守卫 + 常量。全部有对应任务。
+- **占位符**：探针脚本、`_uvpm_set`、常量、各命令均为完整内容。属性名标注"以 Task 1 为准"是 spike-first 设计的必要性质（执行时由 Task 1 输出定稿），非未决占位——`hasattr` 守卫保证即便名字有出入也不崩，Task 3 Step 2 的"属性不存在"警告会兜住并要求回改。
+- **类型/命名一致**：`_uvpm_set(p, name, value, warnings)`（Task 2 Step 2 定义，Step 3 调用一致）；常量 `UVPM_ROTATION_STEP`/`UVPM_HEURISTIC_TIME`（Task 2 Step 1 定义，Step 3 使用一致）；`p` 即 `scene.uvpm4_props.default_main_props`（与现有 `_uvpm_repack` 一致）。
+- **已知风险**：UVPM4 属性名/取值由 Task 1 探针定；启发式若需特定 `pack_op_type` 在 Task 2 据实调整；薄条几何天然限制上限，验收以"明显上升"而非硬数字（spec 一致）。