前言¶

生成式改图工具（如 inpainting、扩图、换主体、抹除物体）很容易出现一个隐蔽问题：模型或流水线声称「只动了蒙版区域」，但背景实际被悄悄重绘了。肉眼很难复核，整图 diff 又会被主体区域的大量变化淹没。本文介绍 DeepSeek Harness 的一个插件：dsh-mask-pixel-lock。它只回答一个可以被像素复核的问题：蒙版之外，是否每个像素都与原图相同。

它是什么¶

dsh-mask-pixel-lock 是一个 DeepSeek Harness 插件，维护者为 dingchenhui0618-arch。它提供两个部分：

• DSH 插件：在对话视图里出现「像素锁」Tab，agent 侧出现 mask_pixel_lock_verify 工具
• 零依赖 CLI：通过 node bin/mask-pixel-lock.mjs 运行

全部在本地完成：不调用模型、不联网、不上传图片。它只做确定性比较，不做内容识别，也不判断「改得好不好看」。

核心功能¶

三张图进，三样产出¶

输入三张 PNG：原图、生成图、蒙版。输出：

• 一句可 grep 的结论
• 一张差异热力图
• 一份可复算的 SHA-256 证明报告

工具参数¶

在 agent 侧调用 mask_pixel_lock_verify 工具时，可传入以下参数：

{
  "original": "D:\\shots\\before.png",
  "generated": "D:\\shots\\after.png",
  "mask": "D:\\shots\\mask.png",
  "maskMode": "edit",
  "label": "主体左移 12px，背景不动"
}

参数说明：

• original：原图 PNG 路径，必填。绝对路径或相对宿主进程 cwd
• generated：生成图 PNG 路径，必填。尺寸必须与原图一致
• mask：蒙版 PNG 路径，必填。尺寸必须与原图一致
• outputDir：报告输出目录，可选。默认为生成图旁的 mask-pixel-lock-<UTC 时间>；已存在时自动加 -2、-3
• maskMode：蒙版模式，可选。默认 edit。edit：蒙版内可改、蒙版外受保护；lock：蒙版内受保护、蒙版外可改
• maskThreshold：蒙版墨量阈值，可选。默认 127。墨量 = 亮度 × alpha / 255。纯白不透明 = 255，纯黑或全透明 = 0
• tolerance：通道差阈值，可选。默认 0。0 即严格逐字节比较
• ignoreAlpha：是否忽略 alpha 通道，可选。默认 false。为 true 时只比较 RGB
• label：报告说明，可选。默认空字符串

CLI 用法¶

零依赖 CLI 提供相同能力：

node bin/mask-pixel-lock.mjs \
  --original examples/before.png \
  --generated examples/after.png \
  --mask examples/mask.png \
  --out examples/report-pass \
  --label "主体缩小 18%，背景光影保持不变"

选项：--out、--mask-mode edit|lock、--threshold 0-255、--tolerance 0-255、--ignore-alpha、--label、--json、--help、--version。

退出码：

--json 把完整报告打到 stdout，适合接 CI：

node bin/mask-pixel-lock.mjs --original before.png --generated after.png --mask mask.png --json > report.json

输出¶

每次校验写三个文件：

• heatmap.png：差异热力图。近黑 = 受保护且未变；暗蓝灰 = 可编辑区；琥珀 → 红 = 受保护但变了，越红通道差越大。一级差异也会直接显示为琥珀色，不会被整图缩放吞掉
• report.json：机器可读的完整报告，schema 为 dsh-mask-pixel-lock/report@1
• report.html：自包含中文报告页，三张图以 base64 内嵌，断网也能打开

报告包含三组哈希：

• proof.files.original/generated/mask：文件字节的 SHA-256。换一张图、重新编码、改元数据都会变
• proof.protectedPixels.original/generated：受保护像素摘要。按「尺寸 + 比较通道 + RGBA 扫描线顺序」规范化，与 PNG 编码器、压缩级别、文件元数据无关
• proof.proofDigest：总摘要。把 schema、版本、策略、三个文件哈希、两个像素摘要绑在一起

蒙版语义¶

这是全插件最容易用错的部分。

墨量：对蒙版每个像素，ink = 亮度 × alpha / 255。纯白不透明 = 255，纯黑或全透明 = 0。灰度蒙版可以用 maskThreshold 调整「算不算画上」的界线。

edit 模式（默认）：蒙版是「可编辑区」，蒙版之外是受保护区。适合「只允许改这一块」的局部改图。

lock 模式：蒙版是「受保护区」，蒙版之外可改。适合「这块不能动，其他随便」的场景，例如保护 Logo、水印区、人物身份证件。

受保护的像素集合会以 policy 与 comparison.editablePixels 写进报告；EMPTY 表示受保护像素为 0，它不等于 PASS——没有被保护的对象，就什么都没证明。

与 dsh-vision-diff 的区别¶

本机已有 dsh-vision-diff，比较两张截图，回答「同一屏两次渲染变没变」，用忽略矩形排除时钟、光标等区域，服务的是视觉回归。

本插件比较原图 + 蒙版 + 生成图三张图，回答「蒙版外有没有被改」，服务的是改图交付验收：

两者互补，不存在替代关系。本插件没有复用 dsh-vision-diff 的代码；它的 PNG 编解码、比较、证明和报告都是本仓库独立实现的。

PNG 支持范围¶

解码器是零依赖实现（只用 node:zlib 与 node:crypto），支持：

• 颜色类型 0（灰度）、2（RGB）、3（调色板）、4（灰度 + alpha）、6（RGBA）
• 位深 1 / 2 / 4 / 8 / 16（调色板与灰度支持亚字节采样）
• 五种扫描线过滤器（None / Sub / Up / Average / Paeth）
• Adam7 隔行
• tRNS 调色板透明度
• 单张图片最多 64 兆像素，单个输入文件最多 128 MB

明确不支持：APNG 动画、JPEG/WebP/GIF、ICC 色彩管理（iCCP/cICP 不参与换算，比较的是文件里的样本值）、EXIF 方向。16 位样本取高 8 位参与比较。

这是字节级比较，不是感知比较。两张视觉上一样但色彩空间/编码不同的图，会被判为不同；这符合「证明背景没被改」的目标。

已知边界¶

• 一次只校验一对图；不做批量、不做目录递归
• 蒙版必须与原图同尺寸；原图与生成图尺寸不同会返回 FAIL / dimensions-differ，proof 为 null，不会假装证明成功
• 只比较像素，不判断「改得对不对」；主体是否自然、边缘是否合理，仍然要人看
• 报告页内嵌原图/生成图/蒙版，大图会让 HTML 变大；单张超过约 4 MB 时不做内嵌，改为文字提示，避免生成几十 MB 的页面
• 面板里输入的是本地路径，不做文件选择器；这是有意的：宿主侧只信任进程能读到的路径
• 证明是本地完整性证明，不是签名

安装与启用¶

GitHub 直装：

dsh plugin --profile <你的 profile> add github:dingchenhui0618-arch/dsh-mask-pixel-lock

本地开发目录：

dsh plugin --profile <你的 profile> add D:\Projects\dsh-mask-pixel-lock

桌面端在应用内的插件管理里安装本地目录或 GitHub 地址即可，profile 由应用管理，不需要手敲上面的命令。

装好后：对话视图里出现「像素锁」Tab；agent 侧出现 mask_pixel_lock_verify 工具。

适用场景与注意¶

适合需要严格保证「蒙版外未被修改」的场景，如：

• 局部改图交付验收
• 保护 Logo、水印区、人物身份证件等关键区域
• 需要可复算的证明报告

插件以当前 DSH 进程权限运行，安装前应检查源码与许可证（MIT）。

短结尾¶

dsh-mask-pixel-lock 通过字节级比较和 SHA-256 证明，让局部改图变得可验证。它不替代人工审核，但能快速发现背景被悄悄重绘的问题。如果你需要证明「蒙版外的像素未被修改」，可以用它。项目主页见下。

• 目录页：https://www.skillhub.cn/plugins/dingchenhui0618-arch/dsh-mask-pixel-lock
• GitHub：https://github.com/dingchenhui0618-arch/dsh-mask-pixel-lock