dsh-pbr-material

dsh-pbr-material

把一张物体的照片变成一整套可平铺的 PBR 贴图（albedo / normal / height / roughness /

AO / curvature / metallic，数据贴图 16-bit），全程本地跑在 ComfyUI 上。

它是 skill pbr-material-from-photo 的插件化版本：判断力留在 skill 里，死板的管道搬进代码。

| 留在 SKILL.md（给模型看） | 搬进代码（确定性执行） |

|---|---|

| 四种失败模式、硬上限、"永远别写 macro photograph" | 19 节点 ComfyUI 图怎么连、怎么提交、怎么轮询、PNG 落在哪 |

| 提示词那 5 段结构为什么这么排 | 提示词模板本身 |

| 第二步顺序为什么不能变 | 固定管线：色相选择性调色 → MakeSeamless → PBRSynth → 16bit 落盘 |

| "指标过了也要看图" | 平铺量测（与 PBRLabTileValidator 逐字段一致）+ 3×3 预览 |

装好之后让 agent 自己部署

# ZIP：解压到任意目录；或 git clone https://github.com/zhangx413/dsh-pbr-material.git
node scripts\install-into-dsh.mjs
# 重启 DeepSeek Harness

然后在对话里说一句「看看 PBR 插件的环境」就行。agent 会自动做完这些：

pbr_setup_status                 查 ComfyUI / python / 模型库 / 磁盘 / 节点包，并报出每个路径是从哪发现的
pbr_setup_status(probe_speed)    真下几 MB 测速，推算 12.5 GB 要多久
pbr_setup_install                后台部署：验证环境 → 建自己的 run root → 链内置节点包
                                 → 下缺失权重（可续传、带镜像回退）→ 起真实例验证节点注册

前三件（发现路径 / 节点包 / run root）它自己解决；只有 ComfyUI 本身和 12.5 GB 权重

需要机器上有/要下载。插件从来不写进用户的 ComfyUI——它用自己独立的 run root 和端口。

装完插件后 agent 的 system prompt 里就有这段说明，所以你不需要解释它要干什么。

两种模式（选错是最常见的失败）

| | mode="direct"（直通） | mode="generate"（生成式，默认） |

|---|---|---|

| 是什么 | 照片就是 albedo，只做平铺 + 推导 | 先用 FLUX.2 Klein 把照片重绘成平面 albedo，再推导 |

| 耗时 | 约 3 秒 | 约 30 秒（1024px / 20 步） |

| 分辨率 | 照片原生分辨率（如 747×1328）原样保留 | 输出成 size×size 方图 |

| 细节 | 真实细节全留（缝、骨料、气孔、水渍、精确颜色） | 重新编造：真实细节被"看起来合理"的通用细节替换 |

| 需要描述 | 不需要（material 会被忽略） | 必须，而且要写清颜色 + 基底 + 磨损 |

| 什么时候用 | 照片本身已经是正面平铺贴图（墙、地面、金属板、布料样片、扫描件/下载的贴图） | 照片里有物体、有透视、有背景、有光照渐变、曲面 |

这组对比是实测的，用一张 747×1328 的混凝土墙照片（本来就是正面平铺贴图）：

| 模式 | 产出的 albedo |

|---|---|

| generate | 一整片均匀灰点 —— 模板竖缝没了、大片骨料外露没了、水渍色差没了 |

| direct | 就是那张照片：缝、骨料、气孔、水渍全在，747×1328 原生分辨率 |

也就是说，对一张已经拍好的贴图跑 step 1 不只是白等 26 秒，它会把你要的东西扔掉。

面板里这一步是显式选择，agent 侧是 pbr_material_from_photo 的 mode 参数。

五个工具

| 工具 | 作用 |

|---|---|

| pbr_comfy_status | install / python / 三个模型文件 / pbrlab 节点包 / run root / 空闲显存 / 有没有实例在跑 |

| pbr_material_from_photo | 全流程一条龙，mode="direct"/"generate"，返回贴图路径 + 平铺量测 |

| pbr_check_maps | 对任意已有贴图集做平铺量测并出 3×3 预览 |

| pbr_setup_status | 环境自检（路径来源 / 缺哪些权重 / 磁盘 / 测速推算耗时） |

| pbr_setup_install | 后台部署：验证环境 → run root → 节点包 → 下权重 → 起实例验证 |

实例策略：先用 attachPorts 找已经在跑的 ComfyUI（找的到就用你那个），找不到才自己起一个

headless 实例（端口 8288），跑完关掉。这条是刻意的——16 GB 显存装不下两份 Klein 4B + 文本编码器。

起实例前还会查一次空闲显存，低于 minFreeVramMiB（默认 9000 MiB）直接报错而不是 OOM。

前端（工作台面板）

侧边栏多一个 PBR 材质 图标，点开是一个整页工作台：

环境条   ComfyUI ✓ 模型 ✓ 已接入实例 :8288 空闲显存 13.1 GB
─────────────────────────────┬────────────────────────────────────────
① 参考图                     │ ② 怎么处理这张照片
  拖入 / 点击选择 / Ctrl+V   │   [① 照片已经是正面贴图 → 直接推导]（约 3 秒，保留原图细节）