jyw-watermark — 图片暗水印工具

基于 DCT 域差分编码算法的图片暗水印 CLI 工具，支持三层版权证据：圆角保护、DCT 暗水印、像素指纹。

环境与安装

> 详见 环境与安装指南

命令

embed — 单张图片嵌入（Buffer 管线，零临时文件）

将版权信息以三层证据形式嵌入到单张图片中：圆角 → DCT 暗水印 → 像素指纹。

用法：

jyw-watermark embed --input-image <path> --output-image <path> [--invisible-watermark-message <text>] [--pixel-fingerprint-message <text>] [--region-count <number>] [--rounded-radius <number>] [--skip-invisible-watermark] [--skip-rounded-corners] [--skip-pixel-fingerprint]

参数：

• --input-image — 原始图片路径（必填）
• --output-image — 输出图片路径（必填，输出固定为 PNG 格式）
• --invisible-watermark-message — DCT 暗水印消息（可选，默认 '玖月伍'）
• --pixel-fingerprint-message — 像素指纹消息（可选，默认 'JY'，最多 2 个字符）
• --region-count — DCT 水印嵌入区域数量（可选，1/2/4/9，默认 4）
• --rounded-radius — 圆角半径，支持 .0 / .5 精度（可选，默认 12.5px）
• --skip-invisible-watermark — 跳过暗水印嵌入
• --skip-rounded-corners — 跳过圆角处理
• --skip-pixel-fingerprint — 跳过像素指纹

示例：

jyw-watermark embed --input-image input.png --output-image output.png --invisible-watermark-message "Hello World"
jyw-watermark embed --input-image input.png --output-image output.png --invisible-watermark-message "版权" --pixel-fingerprint-message "CP"
jyw-watermark embed --input-image input.png --output-image output.png --rounded-radius 15.5 --region-count 9
jyw-watermark embed --input-image input.png --output-image output.png --skip-pixel-fingerprint

输出格式： 成功时输出 ✅ [圆角 xx | 暗水印 "xx" | 像素指纹 "xx"]（被 skip 的特性不显示）；输出路径非 .png 时会自动修正并输出 ⚠ 警告；失败时输出 JSON 错误并退出码 1。

embed-dir — 批量嵌入

批量为目录内所有图片嵌入三层版权证据，自动过滤不支持的格式，输出强制为 PNG。

用法：

jyw-watermark embed-dir --input-dir <path> --output-dir <path> [--invisible-watermark-message <text>] [--pixel-fingerprint-message <text>] [--region-count <number>] [--rounded-radius <number>] [--skip-invisible-watermark] [--skip-rounded-corners] [--skip-pixel-fingerprint]

示例：

jyw-watermark embed-dir --input-dir ./originals --output-dir ./watermarked
jyw-watermark embed-dir --input-dir ./images --output-dir ./output --invisible-watermark-message "版权" --pixel-fingerprint-message "CP"
jyw-watermark embed-dir --input-dir ./photos --output-dir ./out --skip-pixel-fingerprint

输出格式： 先输出 📁 找到 N 个文件，每处理一个文件输出 ✓ filename（无效文件输出 跳过: filename (原因)），最后输出 ✅ 完成 N 个 [tags] 或 ✅ 完成 N 个，跳过 M 个 [tags]。

extract — 综合提取单张图片（推荐用于 Agent）

从单张图片综合提取所有版权证据，输出 JSON 格式便于 Agent 解析。

用法：

jyw-watermark extract --image-path <path> [--invisible-watermark-char-count <number>] [--pixel-fingerprint-char-count <number>] [--region-count <number>] [--skip-rounded-corners] [--skip-invisible-watermark] [--skip-pixel-fingerprint]

参数：

• --image-path — 含水印的图片路径（必填）
• --invisible-watermark-char-count — 暗水印消息的字符数（可选，默认取 DEFAULT_INVISIBLE_WATERMARK_MESSAGE 长度；每个字符占 16 位）
• --pixel-fingerprint-char-count — 像素指纹消息的字符数（可选，默认取 DEFAULT_PIXEL_FINGERPRINT_MESSAGE 长度；每个字符占 16 位）
• --region-count — 嵌入区域数量（可选，1/2/4/9，默认 4）
• --skip-rounded-corners — 跳过圆角检测（如已知图片无 alpha 通道：JPG/BMP/TIFF 等）
• --skip-invisible-watermark — 跳过 DCT 水印提取
• --skip-pixel-fingerprint — 跳过像素指纹提取

输出示例：

{
  "roundedCorners":     { "success": true, "message": "检测到圆角", "data": { "radius": 12.5 } },
  "invisibleWatermark": { "success": true, "message": "提取成功", "data": { "message": "玖月伍" } },
  "pixelFingerprint":   { "success": true, "message": "提取成功", "data": { "message": "JY" } }
}

无圆角或无 alpha 通道时 roundedCorners.data.radius 为 0，success 为 false。

extract-rounded-corners — 独立圆角检测

仅检测图片圆角半径，输出 JSON。

jyw-watermark extract-rounded-corners --image-path <path>

输出：

{ "success": true, "message": "检测到圆角", "data": { "radius": 12.5 } }

extract-invisible-watermark — 独立 DCT 水印提取

仅提取 DCT 域暗水印，输出 JSON。

jyw-watermark extract-invisible-watermark --image-path <path> [--invisible-watermark-char-count <number>] [--region-count <number>]

输出：

{ "success": true, "message": "提取成功", "data": { "message": "玖月伍" } }

extract-pixel-fingerprint — 独立像素指纹提取

仅提取像素级指纹，输出 JSON。

jyw-watermark extract-pixel-fingerprint --image-path <path> [--pixel-fingerprint-char-count <number>]

输出：

{ "success": true, "message": "提取成功", "data": { "message": "JY" } }

Agent 使用场景

Agent 可根据实际场景灵活组合命令：

场景 1：怀疑 PNG 盗图（完整鉴定）

jyw-watermark extract --image-path suspect.png

→ 返回圆角 + 水印 + 指纹的综合 JSON

场景 2：怀疑 JPG 盗图（跳过圆角检测）

jyw-watermark extract --image-path suspect.jpg --skip-rounded-corners --skip-pixel-fingerprint

→ 跳过圆角（JPG 无 alpha），仅检测暗水印（像素指纹不抗压缩，JPG 下必然失败）

场景 3：仅需暗水印验证（最快）

jyw-watermark extract-invisible-watermark --image-path suspect.png --invisible-watermark-char-count 3

→ 仅返回水印提取结果，速度快

场景 4：仅需指纹验证

jyw-watermark extract-pixel-fingerprint --image-path suspect.png

→ 仅返回指纹提取结果

场景 5：仅需圆角检测

jyw-watermark extract-rounded-corners --image-path suspect.png

→ 仅返回圆角检测结果

场景 6：自定义编码组合（三命令并行）

jyw-watermark extract-rounded-corners --image-path suspect.png
jyw-watermark extract-invisible-watermark --image-path suspect.png --region-count 9
jyw-watermark extract-pixel-fingerprint --image-path suspect.png --pixel-fingerprint-char-count 2

→ 三个独立命令可并行执行，Agent 自行汇总判决

原理

> 详见 技术原理