前言¶
在 DeepSeek Harness（DSH）里做 3D 或游戏向资产时，常见需求是把一张现场照片变成引擎可用的 PBR 贴图（albedo、normal、roughness 等），还要能无缝平铺。手工在 DCC 里拆通道、做 MakeSeamless、再导出多套贴图，步骤多且难在对话里稳定复现。社区里已有 skill 思路（pbr-material-from-photo）：模型负责判断与提示，管道用 ComfyUI 本地跑。插件 dsh-pbr-material（维护者 zhangx413，分类：模型推理）把同一套能力做成 DSH 插件：确定性管线进代码，GUI 工作台和 agent 工具一并带上，ComfyUI 与约 12.5 GB 权重在本地完成推理，不依赖云端出图 API。
这是什么¶
dsh-pbr-material 是 DSH 插件：输入一张物体或材质表面的照片，输出一整套可平铺的 PBR 贴图（albedo / normal / height / roughness / AO / curvature / metallic，数据贴图 16-bit），全程在 ComfyUI 上本地执行。生成式路径使用 FLUX.2 Klein 4B 做指令编辑得到平面 albedo，再经固定管线（色相选择性调色 → MakeSeamless → PBRSynth → 16-bit 落盘）推导其余通道；并提供平铺量测与 3×3 预览。插件自带 GUI 工作台、五个 agent 工具，以及能发现 ComfyUI、独立 run root、续传下载权重的部署工具；不写进用户已有的 ComfyUI 目录，使用自己的 run root 与端口。
- 目录页：https://www.skillhub.cn/plugins/zhangx413/dsh-pbr-material
- 源码：https://github.com/zhangx413/dsh-pbr-material（MIT，当前 package 版本 0.2.0，需 Node >= 20）
核心功能¶
Skill 与代码的分工¶
README 用一张表说明边界：失败模式、硬上限、提示词结构顺序等判断力留在 skill（SKILL.md）；19 节点 ComfyUI 图如何提交与轮询、提示词模板、固定后处理管线、平铺量测与预览等确定性步骤搬进插件代码。这样 agent 仍可按 skill 做决策，执行层不会每次在对话里重连一遍图。
两种模式（选错是最常见的失败）¶
mode="direct"（直通） |
mode="generate"（生成式，默认） |
|
|---|---|---|
| 含义 | 照片即 albedo，只做平铺 + 推导 | 先用 FLUX.2 Klein 重绘成平面 albedo，再推导 |
| 耗时 | 约 3 秒 | 约 1024px / 20 步时约 30 秒 |
| 分辨率 | 保留照片原生分辨率 | 输出为 size×size 方图 |
| 细节 | 保留真实缝、骨料、污渍等 | 细节会被「看起来合理」的通用纹理替换 |
| 描述 | 不需要（material 会被忽略） |
需要写清颜色、基底、磨损 |
| 适用 | 已是正面平铺贴图（墙、地面、扫描件等） | 有物体、透视、背景或光照渐变 |
对一张本来就是正面平铺的混凝土墙照片，README 记载：generate 会抹掉竖缝、骨料与水渍色差；direct 则保留原图。面板里第二步显式选择；agent 侧通过 pbr_material_from_photo 的 mode 参数指定。
五个 agent 工具¶
| 工具 | 作用 |
|---|---|
pbr_comfy_status |
安装、Python、模型文件、节点包、run root、空闲显存、是否有实例在跑 |
pbr_material_from_photo |
全流程，mode="direct" / "generate"，返回贴图路径与平铺量测 |
pbr_check_maps |
对已有贴图集做平铺量测并出 3×3 预览 |
pbr_setup_status |
环境自检（路径来源、缺失权重、磁盘；可选 probe_speed 测速推算下载时间） |
pbr_setup_install |
后台部署：验证环境 → run root → 节点包 → 下载权重 → 起实例验证 |
实例策略：优先通过 attachPorts 附着已在运行的 ComfyUI；找不到才在独立端口（默认 8288）起 headless 实例，跑完关闭。起实例前检查空闲显存，低于 minFreeVramMiB（默认 9000 MiB）直接报错，避免 OOM。
GUI 工作台¶
侧边栏 PBR 材质 打开整页工作台：环境条、参考图拖入或 Ctrl+V、模式选择（直通时隐藏中文意图与英文 FLUX 描述区）、输出目录与资产命名、高级参数、后台任务进度与结果区（每张贴图 PASS / veto / FAIL、3×3 平铺预览）。生成按钮直连宿主 REST，不阻塞对话。写英文材质描述时调用 DSH 的 llm 服务（ctx.get('llm')），插件本身不持有 API key；多模态模型由宿主配置决定。
输出命名与文件布局¶
面板填写资源类别 / 名称 / 版本后，通过 GET api/naming 与宿主对齐文件计划。一套材质一个文件夹，例如 T_Military_SandBag_01 下含 _C、_N、_R、_AO、_M、_H、_CURV 及引擎合图 _CA、_CH、_NRM，以及 manifest.json 与 preview/ 中的参考图与 3×3 预览。后缀来自 config.json 的 naming.suffixes。
安装与启用¶
插件以 bundle 形式装入 DSH profile，官方 README 给出的步骤如下（ZIP 解压或 clone 到任意目录后执行）：
node scripts\install-into-dsh.mjs --dry-run # 先看将要修改的内容
node scripts\install-into-dsh.mjs # 正式安装
# 然后重启 DeepSeek Harness
脚本会把本目录 junction 到 <profile>\node_modules\dsh-pbr-material，并写入 profile 的 dsh.profile.bundles 与 dependencies；修改 package.json 前会备份。
装好后在对话里说「看看 PBR 插件的环境」，agent 可依次调用 pbr_setup_status、pbr_setup_status(probe_speed)、pbr_setup_install 完成发现路径、节点包、run root，以及缺失权重的下载与验证。前三项由插件自动处理；机器上仍需有 ComfyUI 本体，并准备约 12.5 GB 模型权重（可续传、带镜像回退）。
典型用法¶
用 agent 跑一条龙¶
环境就绪后，让 agent 调用 pbr_material_from_photo：参考图已是平铺贴图时用 mode="direct"；有透视或物体时用 mode="generate" 并写好材质描述。需要只检查已有贴图时调用 pbr_check_maps。
用面板不占用对话¶
- 打开 PBR 材质工作台，确认环境条中 ComfyUI、模型与实例状态。
- 导入参考图，选择「直接推导」或「先生成再推导」。
- 生成式模式下填写中文意图（可选「让模型看图写英文描述」）并确认 FLUX 用的英文句。
- 选择输出父目录，填写类别 / 名称 / 版本，点击生成；在结果区查看量测与 3×3 预览，必要时「打开输出文件夹」。
面板 REST 入口包括 POST api/generate（后台任务）、POST api/draft（多模态写描述）、POST api/check（量测已有集）等，与 agent 工具共用同一套管线逻辑。
适用场景与注意¶
适合：需要在本机从照片批量或交互式产出可平铺 PBR 集、且愿意维护 ComfyUI 与显存（README 提到 16 GB 显存下不宜同时跑两份 Klein 4B + 文本编码器）的团队或个人。
注意：
- 插件以当前 DSH 进程权限运行，安装前请阅读源码与 MIT 许可证，并确认权重来源与磁盘占用。
- 不要对已是成品贴图误开
generate，会浪费时间并损失细节。 - 社区目录 SkillHub 与 DeepSeek / 幻方无官方从属关系；DSH 生态是「一切皆插件」，本插件是社区维护的模型推理类扩展之一。
结尾¶
dsh-pbr-material 把「照片 → 可平铺 PBR 贴图集」收成 DSH 内可对话、可面板、可本地 ComfyUI 执行的一条链路，并区分直通与生成两种模式，避免把已有贴图再画成通用 AI 纹理。进一步了解能力与安装细节，见目录页与 GitHub README。
- 目录：https://www.skillhub.cn/plugins/zhangx413/dsh-pbr-material
- 仓库：https://github.com/zhangx413/dsh-pbr-material
