图片加水印工具箱
成品文件公式:用户给图片 → 直接拿到带水印的成品图片文件(不是教程,不是参数建议)。核心刚需:电商卖家给自家商品图打上店铺 logo / 版权文字防盗图(用户本人就是电商卖家,主场需求);摄影师、设计师给作品加署名。全程本地处理(Pillow),无需网络与 API Key。
功能
| 子命令 | 作用 | 典型场景 |
|---|---|---|
| text | 文字水印 | ©张三 版权所有、盗图必究、店铺名 |
| logo | 图片水印 | 店铺 logo、品牌标志(推荐透明 PNG) |
位置(--position)六选一:bottom-right(默认)/ top-left / top-right / bottom-left / center / tile(平铺)。
脚本内置策略(agent 无需操心):
- 平铺防盗图(
--position tile):文字/logo 旋转 -30° 后铺满整图并隔行错开(brick),间隔自动;这是防盗图的核心功能——水印铺满全图,截图盗用也难裁掉。 - 描边保证可见(文字用
--stroke):叠加黑色描边,水印在任意背景(尤其浅色/白底商品图)上都清晰可辨。 - 字号自动:文字水印字号按图宽比例计算(单点 4%×图宽,平铺 3%×图宽),小图自动保底 14px;
--size可覆盖。 - 透明度:
--opacity0-1,建议先做淡(0.2~0.35)做小,避免影响商品图美观。 - 格式保持:输出尽量跟随原格式;透明 PNG/WebP 输入保留 alpha 通道,不破坏透明背景。
- 批量:传目录即批量处理(不递归子目录),自动建输出目录,逐张报告成功/失败并汇总。
工作流程
- 拿三要素:①图片来源(文件路径 / 目录)②水印内容(文字内容 或 logo 路径)③位置与浓度(不指定则默认右下角 + opacity 0.3)。
- 电商防盗图场景默认建议:先问一句"要单个角标还是整图平铺(防盗更强但更挡图)",多数卖家角落 logo + 平台平铺版权文字二选一。
- 执行命令(一律用绝对路径):
SKILL_DIR="$HOME/.workbuddy/skills/img-watermark-toolbox"
[ -f "$SKILL_DIR/scripts/watermark.py" ] || SKILL_DIR="$PWD/.workbuddy/skills/img-watermark-toolbox"
[ -f "$SKILL_DIR/scripts/watermark.py" ] || SKILL_DIR="/sandbox/workspace/skills/img-watermark-toolbox"
S="$SKILL_DIR/scripts/watermark.py"
python3 $S text /path/商品图.jpg --text "©张三" --position bottom-right --opacity 0.3 --stroke -o /path/商品图_wm.jpg
- 交付:命令会打印
✅ 完成:原文件 → 输出路径及尺寸/模式变化,把输出文件绝对路径报给用户即可,无需解释技术细节。 - 目录 → 输出目录(
-d),交付时报告汇总行(成功/失败张数)和输出目录。 - 用户嫌水印太明显 → 调低
--opacity(如 0.2)/ 调小--size;嫌太淡 → 提高--opacity(如 0.5)。 - 出现
⚠️ 未找到可用 TrueType 字体时,说明水印可能无法显示中文,应告知用户可传--font /path/xxx.ttf。
命令参考
S="$SKILL_DIR/scripts/watermark.py"
# 1) 文字水印(单张,右下角)
python3 $S text 图.jpg --text "©张三" --position bottom-right --opacity 0.3 --stroke -o out.jpg
# --text 水印文字(必填),如 "©张三 盗图必究"
# --position 位置,默认 bottom-right;可选 top-left/top-right/center/bottom-left/tile
# --opacity 不透明度 0-1,默认 0.3
# --size 字号像素(默认按图宽自动:单点 4%×宽 / 平铺 3%×宽)
# --color 文字颜色,默认 #FFFFFF(支持 #RRGGBB / #RGB / #RRGGBBAA / white 等)
# --stroke 加黑色描边(任意背景可见,强烈建议)
# --font 自定义字体 .ttf/.ttc(默认自动选中文字体)
# --margin 四角位置距边缘像素(默认按图宽 2% 自动)
# --angle 平铺旋转角度,默认 -30
# --gap 平铺间隔像素(默认按图尺寸自动)
# -o 输出路径(默认:原名_wm.扩展名)
# 2) 平铺水印(防盗图核心)
python3 $S text 图.jpg --text "©张三 盗图必究" --position tile --opacity 0.25 --stroke -o out.jpg
# 3) logo 图片水印
python3 $S logo 图.jpg --logo logo.png --position bottom-right --scale 0.15 --opacity 0.6 -o out.jpg
# --logo logo 路径(必填,推荐透明 PNG)
# --scale logo 宽度占主图宽度比例,默认 0.15
# logo 也支持 --position tile 做平铺
# 4) 批量(整个目录)
python3 $S text ./商品图 --text "©张三" --position tile --opacity 0.3 --stroke -d ./商品图_wm
# 位置参数传目录 或 --input ./商品图; -d 输出目录(默认:<目录名>_watermarked)
# 不递归子目录;输出名与原名一致
示例对话
例 1:单张商品图加版权文字
用户:给这张商品图右下角加个"©张三"水印,淡一点
Agent:(执行 text 商品图.jpg --text "©张三" --position bottom-right --opacity 0.25 --stroke -o 商品图_wm.jpg)
"已完成:水印加在右下角,文件在 ./商品图_wm.jpg,可以直接用。"
例 2:整目录防盗图(平铺)
用户:我这个文件夹 50 张图都要防别人盗用,帮我铺满水印
Agent:(执行 text ./商品图 --text "©张三 盗图必究" --position tile --opacity 0.3 --stroke -d ./商品图_wm)
"50 张全部处理完成(-30° 平铺),输出在 ./商品图_wm。水印铺满全图,别人截走也难裁掉。"
例 3:加店铺 logo
用户:把这些图都加上我的店铺 logo,放中间
Agent:(确认 logo 路径后执行 logo ./商品图 --logo ./店铺logo.png --position center --scale 0.12 --opacity 0.5 -d ./商品图_wm)
"已批量加上 logo(居中,宽度为主图 12%,半透明),输出在 ./商品图_wm。"
运行环境
- 脚本：
scripts/watermark.py（相对技能根目录） - Python：3.9+
- 第三方库：
Pillow（pip install Pillow）
开工前先跑一次自检，缺什么当场补，别等跑到一半报错：
python3 -c "import PIL" 2>/dev/null || echo "缺 Pillow，请执行 pip install Pillow"
> 缺依赖时用中文告诉用户缺什么、装完就能用，不要把 Python 的英文 traceback 原样贴给用户。
注意事项
- 先淡后浓、先小后大:建议默认
--opacity 0.2~0.35起步;实物商品图水印过重会遮挡卖点、影响转化,交付时提醒用户"觉得不明显可以再调浓"。 - 透明 PNG 支持:logo 推荐用透明背景 PNG;输出端 PNG/WebP 会保留 alpha,透明背景不会被填白。
- 描边:文字水印在浅色/白底图上若不明显,加
--stroke(自动黑色描边),无需手动调颜色。 - 平铺是防盗图核心:
--position tile旋转 -30° 铺满全图,防裁剪;但会明显遮挡画面,适合"防盗优先"的图,不适合主图/详情首图。 - 格式:支持 jpg/jpeg/png/webp/bmp/tif/tiff;GIF 动图不在范围内(请先转静态图)。jpg 以 quality 95 保存。
- 批量为非递归:只处理目录下第一层图片;带
_wm后缀的文件会自动跳过,避免重复处理。 - 字体:默认自动选中文字体(NotoSansSC 等);若输出中文变方块,用
--font指定 .ttf/.ttc。 - 不支持:图片压缩(用 img-compress-toolbox)、去水印/抠图、裁剪美颜、视频水印(用 video-toolbox)。
- 依赖:仅 Pillow(Pillow 11.3.0,当前运行环境自带)与标准库。
