docs: 标注 caption 与 point_mask 的权重差异，并加运行时警告

实测发现 SDMatte 与 SDMatte*(plus) 两个权重能力不同，根源是官方 README
所载的训练集差异：前者含 RefMatte（指代表达式抠图，点/文本提示的来源），
后者用 COCO-Matte 替换了它。

实测（官方效果图羊驼，MAD 越低越好）：
- point_mask：SDMatte 正常（0.0135）；SDMatte_plus 输出全黑（max 仅 0.079）
- caption   ：SDMatte 上语义有效，'alpaca' 0.01072 优于留空 0.01120、'tree' 0.01111；
              SDMatte_plus 上语义失效甚至反向，'alpaca' 0.01160 反差于 'tree' 0.01119，
              即仅为 cross-attention 的噪声扰动

据此：
- 补全 caption / point_radius / prompt_type 的 tooltip，写明各自的适用权重与含义
- README 增列两个权重的能力对照表与 caption 实测数据
- point_mask 输出接近全黑时打印警告 —— 该情形不报错，只会悄悄给出空结果

README.md

@@ -591,8 +591,9 @@ SDMatte 检查点覆盖。官方 HuggingFace 仓库本身也只发布 `.pth` 加
 | `prompt_type` | 视觉提示类型，见下表 |
 | `inference_size` | 默认 `1024`，与官方测试一致 |
 | `is_transparent` | 玻璃、纱、烟雾等透明物体**务必打开** |
-| `caption` | 可选文本描述，留空即官方默认行为 |
-| `point_radius` | 仅 `point_mask` 生效，默认 35 |
+| `caption` | 目标物体的英文描述。**仅 `SDMatte.pth` 有效，`SDMatte_plus.pth` 请留空**，见下文 |
+| `point_radius` | 仅 `point_mask` 生效。每个点晕开的高斯 sigma，默认 35 |
+| `seed` | 仅 `point_mask` 生效（10 个点是随机取的） |
 
 `prompt_type` 选择：
 
@@ -600,9 +601,35 @@ SDMatte 检查点覆盖。官方 HuggingFace 仓库本身也只发布 `.pth` 加
 |---|---|---|
 | `bbox_mask` | 取掩码外接框作为提示 | **默认，官方测试脚本的主路径，通常最稳** |
 | `mask` | 直接用掩码本身 | 已有较准的粗分割时 |
-| `point_mask` | 在掩码内随机取 10 个点 | 复现论文的点提示实验 |
+| `point_mask` | 在掩码内随机取 10 个点 | **仅 `SDMatte.pth` 支持**，见下文 |
 | `auto_mask` | 不给定位信息 | 画面只有单一主体 |
 
+#### ⚠ 两个权重的能力不同（实测）
+
+官方 README 里，**SDMatte** 与 **SDMatte\***（即 `SDMatte_plus`）的训练集不同：
+前者含 **RefMatte**（指代表达式抠图数据集，点提示与文本提示的来源），
+后者用 **COCO-Matte** 替换了它。这导致 plus 版**不具备点提示与文本指代能力**：
+
+| | `SDMatte.pth` | `SDMatte_plus.pth` |
+|---|---|---|
+| `bbox_mask` / `mask` / `auto_mask` | ✅ | ✅ |
+| `point_mask` | ✅ MAD 0.0135 | ❌ **输出全黑**（max 仅 0.079） |
+| `caption` 语义 | ✅ 填对小幅提升 | ❌ 无作用，填了反而更差 |
+
+`caption` 实测（羊驼图，MAD 越低越好）：
+
+| caption | `SDMatte` | `SDMatte_plus` |
+|---|---|---|
+| `""`（留空） | 0.01120 | **0.01135** ← 最好 |
+| `"alpaca"`（语义正确） | **0.01072** ← 最好 | 0.01160 ← 最差 |
+| `"tree"`（语义错误） | 0.01111 | 0.01119 |
+
+在 `SDMatte` 上，语义正确的描述确实更准；在 `plus` 上语义完全失效甚至反向，
+说明它只是给 cross-attention 注入了噪声扰动，并非在理解文本。
+
+**结论**：用 `SDMatte_plus.pth` 时保持 `caption` 留空、`prompt_type` 用 `bbox_mask`；
+想用点提示或文本指代，请换 `SDMatte.pth`。节点在 `point_mask` 输出接近全黑时会打印警告。
+
 #### 典型接法
 
 ```

sdmatte_node.py

@@ -218,7 +218,9 @@ class RuiSDMatte:
                     "tooltip": "视觉提示类型。\n"
                                "bbox_mask：取掩码外接框作为提示，官方测试脚本的默认路径，通常最稳；\n"
                                "mask：直接用掩码本身，适合已有较准的粗分割；\n"
-                               "point_mask：在掩码内随机取 10 个点；\n"
+                               "point_mask：在掩码内随机取 10 个点。\n"
+                               "  ⚠ 仅 SDMatte.pth 支持；SDMatte_plus.pth 用它会输出全黑，\n"
+                               "  因为 SDMatte*(plus) 的训练集用 COCO-Matte 替换了 RefMatte，未训练点提示；\n"
                                "auto_mask：不给定位信息，全图自动，画面只有单一主体时可用。"
                 }),
                 "inference_size": ([512, 640, 768, 896, 1024, 1152, 1280], {
@@ -234,11 +236,19 @@ class RuiSDMatte:
             "optional": {
                 "caption": ("STRING", {
                     "default": "", "multiline": False,
-                    "tooltip": "可选的文本描述（对应 RefMatte 的表达式）。留空即为官方测试时的默认行为。"
+                    "tooltip": "目标物体的英文描述（对应 RefMatte 的指代表达式），经 CLIP 编码后\n"
+                               "注入 UNet 的下采样/上采样两段 cross-attention。\n"
+                               "· SDMatte.pth：有语义作用，填对能小幅提升（实测羊驼图 MAD 0.01120→0.01072）\n"
+                               "· SDMatte_plus.pth：无语义作用，填了反而更差，请留空\n"
+                               "  （plus 的训练集用 COCO-Matte 替换了 RefMatte，未学过文本指代）\n"
+                               "留空即官方测试时的默认行为。"
                 }),
                 "point_radius": ("INT", {
                     "default": 35, "min": 5, "max": 100,
-                    "tooltip": "仅 point_mask 生效。官方测试期取 35（训练 radius 25 + 10）。"
+                    "tooltip": "仅 prompt_type=point_mask 时生效，其余模式完全不参与运算。\n"
+                               "含义：在提示区域随机取 10 个点，每点用 sigma=该值的高斯核晕开成光斑，\n"
+                               "再逐像素取最大值合成提示图 —— 即每个点的影响半径。\n"
+                               "官方训练用 25，测试期用 25+10=35，故默认 35。"
                 }),
                 "seed": ("INT", {"default": 0, "min": 0, "max": 0xFFFFFFFF}),
             },
@@ -325,6 +335,15 @@ class RuiSDMatte:
             alphas.append(torch.from_numpy(np.clip(a, 0.0, 1.0)))
         alpha = torch.stack(alphas)  # [B,H,W]
 
+        # SDMatte*（即 SDMatte_plus）的训练集以 COCO-Matte 替换了 RefMatte，未学过点提示，
+        # 喂 point_mask 会输出接近全黑。这不会报错，只会悄悄给出空结果，故主动提示。
+        if prompt_type == "point_mask" and float(alpha.max()) < 0.1:
+            print(
+                "[Ruinode-SDMatte] 警告：point_mask 提示下输出接近全黑。"
+                "官方 SDMatte_plus(SDMatte*) 不支持点提示（其训练集用 COCO-Matte 替换了 RefMatte）。"
+                "请改用 bbox_mask，或换成 SDMatte.pth。"
+            )
+
         cutout = image.detach().cpu().float() * alpha.unsqueeze(-1)
 
         return (alpha, cutout)