sd-operation-rules

Files (3)

• SKILL.md
• manifest.json
• material_analysis.md · references/

SKILL.md (first lines)

# SD 操作规则

> 📋 **通用节点图工作流**（伪代码→映射→分组创建→验证→布局）见 `dcc-node-graph-workflow` skill。
> 本 skill 专注 SD 的 **API 约束、截图验证流程和致命陷阱**。

---

## 🔴 代码拆分规则

**每次 run_python 调用做一个逻辑步骤**（通常 3-5 个节点操作）。

**避免：**
- ⛔ 一次调用创建整个图（10+ 节点 + 全部设参 + 全部连线）→ 中间报错后续全丢
- ⛔ 截图和预写分析放同一次调用 → 分析不是基于真实观察

**推荐模式：**
```
调用1: 创建 mesh_1 + levels，设参连线
调用2: save_preview(levels) ← 只截图，不写分析
       → 看到图后分析 → 通过则继续
调用3: 创建 transformation × 2 + blend
调用4: save_preview(blend) → 分析 → 通过则继续
```

---

## 🔴 参数设置规则

**⛔ 禁止猜测参数名和类型！创建节点后第一步永远是动态查询。**

```python
# ✅ 正确：先查询，再设值
node = graph.newNode("sbs::compositing::levels")
for p in node.getProperties(SDPropertyCategory.Input):
    pid = p.getId()
    if pid.startswith("$"): continue
    v = node.getPropertyValue(p)
    if v is None: print(f"  PORT: {pid}")      # 连接端口
    else: print(f"  PARAM: {pid} = {v.get()} ({type(v).__name__})")
```

**已知陷阱：**

| 节点 | 参数名 | 正确类型 | 常见错误 |
|------|--------|---------|---------|
| levels | `levelinlow/levelinhigh/levelinmid` | **Float4** | 猜成 `inlow` + Float |
| blend | `opacitymult` (标量) | SDValueFloat | 猜成 `opacity`（那是连接端口） |
| uniform | `colorswitch` | SDValueBool | ⛔ 不设 = 输出永远灰色 |
| 库节点 Enum | — | **SDValueInt.sNew(n)** | 无 SDValueEnum.sNew |

---

## 🔴 截图驱动的迭代循环

### 截图两步法（⛔ 必须分两次调用）

**步骤 1** (run_python): 只截图
```python
save_preview(node, "CP1_structure")
```

**步骤 2** (看到图后): 逐维度分析，写出判断

#### 4 个必须分析的维度

| 维度 | 检查点 | 问题信号 |
|------|--------|---------|
| **亮度/对比度** | 是否有足够动态范围？ | 全黑→立即向上游追查 |
| **图案正确性** | 是否符合预期？ | artifact/意外图案 |
| **密度/比例尺** | 基于物理尺度声明检查 | 太稀/太密 → 调 scale |
| **CG 感** | 看起来是否过于规则？ | 需要 warp/噪波打破 |

**分析输出格式：**
```
[CP1] 分析 (attempt N/3):
  亮度: 正常/全黑/...
  图案: 正确/有artifact/...
  密度: 合理/过密/...
  CG感: 无/有...
  判定: ✅通过 / ⛔需修复
  修复: [根因 → 具体改法]
```

**修复循环（⛔ 最多 3 次，超出则报告并停止）：**
```
截图 → 分析 → 有问题?
  → 向上游逐节点截图追查 → 找第一个出问题的节点
  → 修复 → 重新截图验证 → retry_count++
  → retry_count >= 3? 停！汇报，请求人工指导
```

---

## 🔴 参考工程优先原则

**⛔ 禁止从零构建功能模块！先查参考工程有没有可复用的。**

| 优先级 | 方式 | 示例 |
|--------|------|------|
| 1⃣ 加载参考工程子图 | loadUserPackage → newInstanceNode | Creases_Filter、fabric_weathering |
| 2⃣ 复制参考工程节点链参数 | 按参考工程参数值重建 | fabric_009 的 mesh_1+transformation 编织链 |
| 3⃣ 复用参考工程管线架构 | 替换纹理源，保留管线结构 | fabric_009 的 5层着色架构 |
| 4⃣ 自己构建 | 仅当参考工程完全没有时 | — |

**Phase 1.5 必须声明：**
```
功能模块拆解:
  1. [编织结构] → 来源: fabric_009 mesh_1+transformation 链 (搬运)
  2. [褶皱效果] → 来源: fabric_002 Creases_Filter 子图 (加载实例)
  3. [着色管线] → 来源: fabric_009 5层着色架构 (复用结构, 调整颜色)
  4. [xxx]     → 来源: 无参考, 需自行构建
```

---

## API 速查

### 预注入变量（直接用）
`sd`, `app`, `graph`, `S`, `W`, `SDPropertyCategory`, `float2/3/4`, `ColorRGBA`

From IvanYangYangXi/artclaw_bridge, MIT.

More from IvanYangYangXi/artclaw_bridge