前言¶
在 DeepSeek Harness（DSH）的智能体开发场景里，经常需要批量处理图片：把商品图统一压缩到 1920 宽以内、给交付图加公司水印、把 PNG 转成 WebP 节省流量、把带 EXIF 的照片清掉再发外网。这些任务机械且量大，手动一张张用修图软件操作容易漏、慢，而且一旦覆盖原图就难以回退。DSH 的理念是「一切皆插件」，插件化地处理这类重复性工作，能显著减少手动步骤。
插件简介¶
这个插件是 feely0208/dsh-image-batch，由温州深鲸智能科技有限公司维护。它通过命令行对整个目录的图片做批量处理：压缩、按比例改尺寸、加文字水印、转格式、去 EXIF。所有操作只读输入、产物写入单独目录，不覆盖原文件，适合商品图批量处理、朋友圈九宫格压缩、交付图打水印等场景。
核心功能¶
插件提供以下子命令，共同约定：不修改输入文件；产物默认写到输入目录的 _输出 子目录；同名不覆盖；目录递归处理 jpg/jpeg/png/webp；一张坏图不会拖垮整批；--json 输出结构化结果。
压缩图片¶
dsh-image-batch compress --input <目录> --out <输出目录> [--max-width <宽度>] [--quality <质量>]
- 支持 JPEG/PNG/WebP，
--max-width默认 1920，--quality默认 82。 - 压缩后的图片与 JSON 报告（压缩前后字节数）。
- PNG 使用
--quality映射调色板颜色数（属于减色，不是无损）。
改尺寸¶
dsh-image-batch resize --input <目录> --out <输出目录> [--max-width <宽度>] [--max-height <高度>]
- 按
--max-width/--max-height等比缩放，只缩小不放大。 - JSON 报告给出原尺寸 → 新尺寸。
加文字水印¶
dsh-image-batch watermark --input <目录> --out <输出目录> --text <水印文字> [--position <位置>] [--opacity <透明度>] [--font <字体文件>]
--text必填，--position默认右下，--opacity默认 0.55，字号默认短边 4%。- JSON 报告给出实际字号、位置、字体。
- 只支持一行文字；纯英文可用 Pillow 内置字体兜底。
转格式¶
dsh-image-batch convert --input <目录> --out <输出目录> --format <jpg|png|webp>
- 支持批量转换格式；透明图转 JPG 时背景填白。
- JSON 报告给出 from → to 格式。
去 EXIF¶
dsh-image-batch strip --input <目录> --out <输出目录> [--keep-exif]
- 去掉 EXIF/元数据（拍摄设备、时间、GPS）；
--keep-exif可保留做对照。 - JSON 报告给出 EXIF 标签数。
安装与启用¶
插件通过 DSH 官方命令安装，需本机已安装 python3 + Pillow（插件不会自动安装依赖）：
dsh plugin --profile web add @deepwhale-cn/dsh-image-batch
若缺少依赖，CLI 会打印安装命令并以退出码 3 结束：
python3 -m pip install Pillow
# macOS 没有 python3 时
brew install python3
中文水印使用系统中文字体，优先 /System/Library/Fonts/PingFang.ttc，缺失时回退；全部找不到时会报错并退出码 3。
典型用法¶
# 整目录压缩到 1920 以内，质量 80
dsh-image-batch compress --input ./商品图 --out ./商品图_压缩 --max-width 1920 --quality 80
# 压缩并转成 WebP（PNG 照片常用）
dsh-image-batch compress --input ./截图 --format webp --quality 78
# 统一缩到 1280 宽
dsh-image-batch resize --input ./照片 --max-width 1280
# 右下角打中文水印
dsh-image-batch watermark --input ./交付图 --text "© 深鲸科技" --opacity 0.5
# 转格式 / 去 EXIF
dsh-image-batch convert --input ./素材 --format jpg
dsh-image-batch strip --input ./外发 --out ./外发_干净
运行 --help 和 --demo 可查看帮助与样例流程：
dsh-image-batch --help
dsh-image-batch --demo
退出码：0 成功，1 部分或全部文件处理失败，2 参数/输入错误，3 缺依赖。
适用场景与注意¶
适合需要批量压缩、改尺寸、加水印、转格式、去 EXIF 的开发者与智能体开发者。插件在本地由 Pillow 处理，不联网、不上传图片。
注意事项：
- 不是修图软件：不做抠图、去水印、磨皮、调色、智能裁剪；
resize只做等比缩放。 - 不支持
.gif、.heic、.heif、.bmp、.tiff、.svg、.psd、.avif；手机 HEIC 请先用预览导出为 JPG。 - 不是无损压缩：JPEG/WebP 重新编码有损；PNG 的
--quality映射调色板颜色数，属于减色。 - 不保留元数据：
compress/resize/watermark/convert默认丢掉 EXIF 与 ICC；需要保留时用--keep-exif，但方向会被去掉。 - 不处理 CMYK 专色印刷输出；水印只支持一行文字、不换行不旋转不平铺；不支持图片/logo 水印。
- 不批量重命名、不整理目录、不处理 PDF / 视频 / RAW；
--input不接受通配符（交给 shell 展开）。
结语¶
这个插件把图片批量处理的重复劳动交给命令行，适合 DSH 智能体与开发者快速集成。安装与使用都保持简单，适合需要批量压缩、改尺寸、加水印、转格式、去 EXIF 的场景。
