新增 img-utils 技能:Pillow 确定性图像处理(转换/缩放/裁剪/压缩/水印/切片/拼图)

This commit is contained in:
2026-09-02 17:24:23 +08:00
parent 2302f363cc
commit fdb5dea4ac
4 changed files with 556 additions and 0 deletions
+2
View File
@@ -257,6 +257,8 @@ A:目前所有技能共享同一个 `deps` 目录,建议锁定精确版本
查看现有的 `md2pdf` 技能(位于 `skills/md2pdf/`)可以了解一个较为完整的实现,包括如何处理系统级依赖和字体等。但请根据自身技能的实际需求进行设计,不必拘泥于该示例。
图像处理类需求可参考 `skills/img-utils/`:它演示了一个纯 Python + 预装 Pillow 的实现(转换/缩放/裁剪/压缩/水印/切片/拼图,无 requirements.txt,仅靠 install.sh 保证中文字体),并明确区分“确定性图像处理”与“AI 生成/修图”的能力边界。
---
遵循以上规范,你的技能将能够被 Agent 自动发现、正确调用,并在不同环境中稳定运行。如有疑问,请参考现有技能或联系维护者。
+110
View File
@@ -0,0 +1,110 @@
---
name: img-utils
description: 图像处理(Pillow):查看图片信息、格式转换、缩放、裁剪、压缩、文字水印、九宫格切片、多图拼图。仅做确定性图像处理,不做 AI 生成/修图
input_schema:
type: object
properties:
action:
type: string
description: 操作类型:info | convert | resize | crop | compress | watermark | slice | grid
input:
type: string
description: 输入图片路径(grid 时为图片所在目录)
output:
type: string
description: 输出文件路径(可选;slice 时为输出目录,grid 时也可省略)
width:
type: integer
description: resize 目标宽 / crop 裁切宽
height:
type: integer
description: resize 目标高 / crop 裁切高
keep_ratio:
type: boolean
description: resize 是否保持宽高比(默认 true;false 时需同时给 width 与 height)
left:
type: integer
description: crop 起始横坐标(默认 0)
top:
type: integer
description: crop 起始纵坐标(默认 0)
quality:
type: integer
description: JPEG/WebP 输出质量 1-95(默认 85)
max_dim:
type: integer
description: compress 可选:长边先缩到该值以内再压缩
text:
type: string
description: watermark 水印文字
font:
type: string
description: watermark 字体 TTF/TTC 路径(可选;中文缺省自动找系统文泉驿/Noto 字体)
font_size:
type: integer
description: watermark 字号(默认取图片宽的 1/20)
position:
type: string
description: watermark 位置 tl/tc/tr/ml/mc/mr/bl/bc/br(默认 br 右下)
color:
type: string
description: watermark 颜色 white/black/red 等或 #RRGGBB(默认 white)
opacity:
type: integer
description: watermark 不透明度 0-255(默认 200)
margin:
type: integer
description: watermark 距边缘像素(默认 20)
rows:
type: integer
description: slice 行数(默认 3;只给 rows 或 cols 时按方形推算)
cols:
type: integer
description: slice 列数(默认 3)
cell:
type: integer
description: grid 每格缩略图长边像素(默认 800)
padding:
type: integer
description: grid 格间距与外边距像素(默认 10)
background:
type: string
description: grid 背景色 white/black 等或 #RRGGBB(默认 white)
required: [action, input]
output_schema:
type: string
description: 操作结果描述;需要保存的动作会返回输出文件路径(slice 返回全部切片文件清单)
---
## 功能
- `info`:查看图片尺寸、色彩模式、格式、文件大小(需要裁剪/拼图前先看尺寸时很有用)
- `convert`:格式转换(按 `output` 的扩展名输出,支持 jpg/jpeg/png/webp/bmp/gif/tiff)
- `resize`:缩放,默认保持宽高比(fit);`keep_ratio=false` 时为精确宽高
- `crop`:按 `left/top/width/height` 裁剪,默认从 (0,0) 裁到右下角
- `compress`:压缩图片体积(`quality`;可选 `max_dim` 先缩长边);PNG 用 optimize 无损优化
- `watermark`:给图片加文字水印(支持中文;默认右下、白色、80% 不透明度)
- `slice`:等分切片(默认 3×3 九宫格),输出到独立目录,方便朋友圈/小红书九图
- `grid`:把同一目录下多张图拼成一张 contact sheet(缩略图网格)
## 使用说明
通过 `run_skill` 调用,参数 `input_args`:
- `action`:操作类型(必填)
- `input`:输入图片或目录(必填;相对会话工作目录的路径即可,会自动转绝对路径)
- `output`:输出路径(建议给全;不给时自动生成 `<原名>_<动作>.<原扩展名>`,绝不覆盖原图)
- 其余参数见上方 schema,按动作选用
示例:
```json
{"action": "resize", "input": "photo.jpg", "width": 800, "output": "photo_800.jpg"}
{"action": "compress", "input": "big.png", "quality": 80}
{"action": "watermark", "input": "pic.png", "text": "内部资料", "position": "tr", "color": "white", "opacity": 180}
{"action": "grid", "input": ".", "output": "contact.jpg", "cols": 3}
{"action": "slice", "input": "nine.png", "rows": 3, "cols": 3, "output": "nine_slice"}
```
## 注意事项
- 本技能**只做确定性图像处理**(转换/缩放/裁剪/压缩/水印/拼图),不含 AI 生成、抠图、换脸、扩图、修复等生成式/语义编辑能力。
- 若用户的需求属于"文生图 / AI 修图"等生成式范畴,不要用本技能硬凑,应说明能力边界并推荐第三方工具(豆包、即梦、可灵、Photoshop 等)。
- 任何操作都不会覆盖输入原图;输出目录不存在时自动创建。
- 中文水印需要字体:优先用 `font` 参数指定;否则依赖系统字体(install.sh 会自动装文泉驿)或同仓 md2pdf 技能准备过的字体。
- 输入依赖预装的 Pillow,无需额外 Python 依赖;系统级字体依赖见 install.sh。
+25
View File
@@ -0,0 +1,25 @@
#!/bin/bash
set -e
# 确保存在可用的中文字体(watermark 中文水印需要)。
# 命中即幂等退出;依赖缓存由 Skill Manager 依据本脚本内容哈希管理。
for f in \
/usr/share/fonts/truetype/wqy/wqy-zenhei.ttc \
/usr/share/fonts/truetype/wqy/wqy-microhei.ttc \
/usr/share/fonts/opentype/noto/NotoSansCJK-Regular.ttc; do
if [ -f "$f" ]; then
echo "中文字体已存在:$f"
exit 0
fi
done
if [ "$(id -u)" -eq 0 ]; then
echo "未找到中文字体,安装 fonts-wqy-zenhei..."
apt-get update -y -qq
apt-get install -y -qq fonts-wqy-zenhei
else
echo "错误:非 root 用户且系统无中文字体,无法自动安装" >&2
exit 1
fi
echo "中文字体就绪"
+419
View File
@@ -0,0 +1,419 @@
#!/usr/bin/env python3
# -*- coding: utf-8 -*-
"""
img-utils 技能主入口:用 Pillow 做确定性的图像处理(不含 AI 生成/语义修图)。
支持动作 action:
- info 查看图片信息(尺寸/模式/格式/体积)
- convert 格式转换(按 output 扩展名)
- resize 缩放(keep_ratio 默认保持宽高比)
- crop 裁剪(left/top/width/height)
- compress 压缩(quality;可选 max_dim 先缩长边)
- watermark 文字水印(text;中文需系统字体或 font 参数)
- slice 等分切片(rows/cols,默认 3×3,输出到独立目录)
- grid 多图拼图 contact sheet(input 为图片所在目录)
约定:输出绝不覆盖输入原图;相对路径由 Skill Manager 预先转成绝对路径。
"""
import json
import sys
from pathlib import Path
from PIL import Image, ImageDraw, ImageFont, ImageOps
IMAGE_EXTS = {'.jpg', '.jpeg', '.png', '.webp', '.bmp', '.gif', '.tif', '.tiff'}
POSITIONS = {
'tl': ('l', 't'), 'tc': ('c', 't'), 'tr': ('r', 't'),
'ml': ('l', 'm'), 'mc': ('c', 'm'), 'mr': ('r', 'm'),
'bl': ('l', 'b'), 'bc': ('c', 'b'), 'br': ('r', 'b'),
}
NAMED_COLORS = {
'white': (255, 255, 255), 'black': (0, 0, 0), 'red': (255, 0, 0),
'green': (0, 128, 0), 'blue': (0, 0, 255), 'yellow': (255, 255, 0),
'gray': (128, 128, 128), 'grey': (128, 128, 128), 'orange': (255, 165, 0),
'purple': (128, 0, 128), 'cyan': (0, 255, 255),
}
CJK_FONT_CANDIDATES = [
'/usr/share/fonts/truetype/wqy/wqy-zenhei.ttc',
'/usr/share/fonts/truetype/wqy/wqy-microhei.ttc',
'/usr/share/fonts/opentype/noto/NotoSansCJK-Regular.ttc',
]
def to_int(v, default=0):
if v is None or v == '':
return default
try:
return int(v)
except (TypeError, ValueError):
raise ValueError('参数应为整数:%r' % (v,))
def to_bool(v, default=True):
if v is None or v == '':
return default
if isinstance(v, bool):
return v
if isinstance(v, str):
return v.strip().lower() in ('1', 'true', 'yes', 'y', 'on')
return bool(v)
def parse_color(s, default=(255, 255, 255)):
s = (s or '').strip().lower()
if not s:
return default
if s in NAMED_COLORS:
return NAMED_COLORS[s]
if s.startswith('#'):
h = s[1:]
if len(h) == 3:
h = ''.join(c * 2 for c in h)
if len(h) == 6:
try:
return tuple(int(h[i:i + 2], 16) for i in (0, 2, 4))
except ValueError:
pass
raise ValueError('无法识别的颜色:%s(支持 white/black/red/... 或 #RRGGBB)' % s)
def open_image(path):
"""打开图片并按 EXIF 方向摆正;返回 (img, 原始格式名)。"""
img = Image.open(str(path))
fmt = img.format or ''
img.load()
img = ImageOps.exif_transpose(img)
return img, fmt
def ensure_rgb(img):
if img.mode in ('RGBA', 'LA', 'P'):
return img.convert('RGB')
return img
def save_image(img, out_path, quality=None):
"""按输出扩展名保存;JPEG/WebP 用 quality,PNG 走 optimize。"""
p = Path(out_path)
p.parent.mkdir(parents=True, exist_ok=True)
fmt = (p.suffix or '').lstrip('.').upper()
q = to_int(quality, 90)
q = max(1, min(95, q))
if fmt in ('JPG', 'JPEG'):
ensure_rgb(img).save(str(p), format='JPEG', quality=q, optimize=True)
elif fmt == 'WEBP':
img.save(str(p), format='WEBP', quality=q)
elif fmt == 'PNG':
img.save(str(p), format='PNG', optimize=True)
elif fmt in ('BMP', 'GIF', 'TIFF', 'TIF', 'ICO'):
img.save(str(p))
else:
raise ValueError('不支持的输出扩展名:%s(支持 jpg/jpeg/png/webp/bmp/gif/tiff)'
% (p.suffix or '(无)'))
def default_out(input_path, tag):
"""缺省输出:同目录 <原名>_<tag><原扩展名>,不覆盖原图。"""
p = Path(input_path)
return str(p.parent / ('%s_%s%s' % (p.stem, tag, p.suffix if p.suffix else '.png')))
def ensure_different(src, dst):
if Path(src).resolve() == Path(dst).resolve():
raise ValueError('输出路径与输入相同:%s,不允许覆盖原图,请指定新的 output' % src)
def resample():
return getattr(Image, 'Resampling', Image).LANCZOS
# ---------- 各动作实现 ----------
def action_info(img, fmt, args):
w, h = img.size
lines = ['图片信息:']
lines.append('- 文件:%s' % args['_input'])
lines.append('- 尺寸:%dx%d 像素' % (w, h))
lines.append('- 色彩模式:%s' % img.mode)
lines.append('- 格式:%s' % (fmt or '未知'))
try:
kb = Path(args['_input']).stat().st_size / 1024.0
lines.append('- 文件大小:%.1f KB' % kb)
except OSError:
pass
return '\n'.join(lines)
def action_convert(img, fmt, args):
out = args.get('output')
if not out:
raise ValueError('convert 需要 output 参数(带目标扩展名,如 out.png)')
ensure_different(args['_input'], out)
save_image(img, out, quality=args.get('quality'))
return '格式转换完成:%s -> %s' % (args['_input'], out)
def action_resize(img, fmt, args):
w = to_int(args.get('width'))
h = to_int(args.get('height'))
keep = to_bool(args.get('keep_ratio'), True)
if not w and not h:
raise ValueError('resize 需要 width 或 height(至少一个)')
iw, ih = img.size
if keep:
if w and h:
scale = min(w / iw, h / ih)
nw, nh = max(1, round(iw * scale)), max(1, round(ih * scale))
elif w:
nw, nh = w, max(1, round(ih * (w / iw)))
else:
nw, nh = max(1, round(iw * (h / ih))), h
else:
if not (w and h):
raise ValueError('keep_ratio=false 时 width 与 height 都要提供')
nw, nh = w, h
img2 = img.resize((max(1, nw), max(1, nh)), resample())
out = args.get('output') or default_out(args['_input'], 'resized')
ensure_different(args['_input'], out)
save_image(img2, out, quality=args.get('quality'))
return '缩放完成:%dx%d -> %dx%d,输出 %s' % (iw, ih, img2.size[0], img2.size[1], out)
def action_crop(img, fmt, args):
iw, ih = img.size
left = to_int(args.get('left'))
top = to_int(args.get('top'))
width = to_int(args.get('width'), max(1, iw - left))
height = to_int(args.get('height'), max(1, ih - top))
if width < 1 or height < 1:
raise ValueError('crop 的 width/height 必须 >= 1')
left = max(0, left)
top = max(0, top)
right = min(iw, left + width)
bottom = min(ih, top + height)
if right <= left or bottom <= top:
raise ValueError('裁剪区域超出图片范围(图片 %dx%d)' % (iw, ih))
out = args.get('output') or default_out(args['_input'], 'cropped')
ensure_different(args['_input'], out)
save_image(img.crop((left, top, right, bottom)), out, quality=args.get('quality'))
return '裁剪完成:区域 (%d,%d)-(%d,%d),输出 %s' % (left, top, right, bottom, out)
def action_compress(img, fmt, args):
img2 = img
md = to_int(args.get('max_dim'))
if md > 0 and max(img2.size) > md:
img2 = ImageOps.contain(img2, (md, md), resample())
out = args.get('output') or default_out(args['_input'], 'compressed')
ensure_different(args['_input'], out)
q = to_int(args.get('quality'), 85)
try:
before = Path(args['_input']).stat().st_size
except OSError:
before = 0
save_image(img2, out, quality=q)
try:
after = Path(out).stat().st_size
except OSError:
after = 0
pct = (100.0 * after / before) if before else 0
return '压缩完成:%.1f KB -> %.1f KB(%.0f%%),输出 %s' % (before / 1024.0, after / 1024.0, pct, out)
def find_font(explicit):
"""字体查找:显式 font > 系统 CJK 候选 > 同仓 md2pdf 技能准备的字体。"""
if explicit:
p = Path(explicit)
if not p.exists():
raise ValueError('指定的字体不存在:%s' % explicit)
return str(p)
skill_root = Path(__file__).resolve().parent.parent
candidates = list(CJK_FONT_CANDIDATES)
candidates.append(str(skill_root / 'md2pdf' / 'fonts' / 'cjk.ttf'))
for c in candidates:
if Path(c).exists():
return c
return None
def action_watermark(img, fmt, args):
text = (args.get('text') or '').strip()
if not text:
raise ValueError('watermark 需要 text 参数')
w, h = img.size
font_size = to_int(args.get('font_size'), max(14, w // 20))
font_size = max(8, min(400, font_size))
need_cjk = any(ord(ch) > 0x2E80 for ch in text)
font_path = find_font((args.get('font') or '').strip())
if font_path:
font = ImageFont.truetype(font_path, font_size)
elif need_cjk:
raise ValueError('中文水印缺少字体:请传 font 参数(TTF/TTC 路径),或确认系统已装文泉驿/Noto 字体')
else:
try:
font = ImageFont.load_default(size=font_size)
except TypeError:
font = ImageFont.load_default()
pos = (args.get('position') or 'br').strip().lower()
if pos not in POSITIONS:
raise ValueError('position 必须是 tl/tc/tr/ml/mc/mr/bl/bc/br 之一')
align_x, align_y = POSITIONS[pos]
margin = max(0, to_int(args.get('margin'), 20))
color = parse_color(args.get('color'), (255, 255, 255))
opacity = max(0, min(255, to_int(args.get('opacity'), 200)))
# 在透明层上画字再合成,保证半透明水印且边缘平滑
layer = Image.new('RGBA', (w, h), (0, 0, 0, 0))
draw = ImageDraw.Draw(layer)
bbox = draw.textbbox((0, 0), text, font=font)
tw, th = bbox[2] - bbox[0], bbox[3] - bbox[1]
if align_x == 'l':
ox = margin - bbox[0]
elif align_x == 'c':
ox = (w - tw) / 2.0 - bbox[0]
else:
ox = w - margin - bbox[2]
if align_y == 't':
oy = margin - bbox[1]
elif align_y == 'm':
oy = (h - th) / 2.0 - bbox[1]
else:
oy = h - margin - bbox[3]
draw.text((ox, oy), text, font=font, fill=color + (opacity,))
base = img.convert('RGBA')
composed = Image.alpha_composite(base, layer)
out = args.get('output') or default_out(args['_input'], 'watermarked')
ensure_different(args['_input'], out)
save_image(composed, out, quality=args.get('quality'))
return '水印完成(位置 %s,字号 %d,不透明度 %d):%s' % (pos, font_size, opacity, out)
def action_slice(img, fmt, args):
w, h = img.size
rows = to_int(args.get('rows'))
cols = to_int(args.get('cols'))
if rows and not cols:
cols = rows
if cols and not rows:
rows = cols
rows = max(1, min(20, rows or 3))
cols = max(1, min(20, cols or 3))
src = Path(args['_input'])
out_dir = Path(args.get('output')) if args.get('output') else src.parent / (src.stem + '_slice')
out_dir.mkdir(parents=True, exist_ok=True)
ext = src.suffix.lower()
if ext not in IMAGE_EXTS:
ext = '.png'
cw = max(1, w // cols)
chh = max(1, h // rows)
files = []
for r in range(rows):
for c in range(cols):
box = (c * cw, r * chh, min(w, (c + 1) * cw), min(h, (r + 1) * chh))
tile = img.crop(box)
name = '%s_%02d_%02d%s' % (src.stem, r + 1, c + 1, ext)
save_image(tile, str(out_dir / name))
files.append(str(out_dir / name))
return '切片完成:%d×%d 共 %d 块,输出目录 %s\n%s' % (cols, rows, len(files), out_dir, '\n'.join(files))
def action_grid(args):
in_dir = Path(args.get('input'))
if not in_dir.is_dir():
raise ValueError('grid 的 input 应为图片所在目录:%s' % in_dir)
out = args.get('output')
if not out:
out = str(in_dir / ('%s_grid.jpg' % (in_dir.name or 'images')))
imgs = sorted(
p for p in in_dir.iterdir()
if p.is_file() and p.suffix.lower() in IMAGE_EXTS
and not p.name.startswith('.')
and Path(p).resolve() != Path(out).resolve()
)
if not imgs:
raise ValueError('目录中没有可拼图的图片:%s' % in_dir)
n = len(imgs)
cols = to_int(args.get('cols'))
if not cols:
cols = max(1, int(n ** 0.5 + 0.999)) # 缺省近似正方形网格
cols = max(1, min(20, cols))
rows = (n + cols - 1) // cols
cell = max(50, min(2048, to_int(args.get('cell'), 800)))
pad = max(0, to_int(args.get('padding'), 10))
bg = parse_color(args.get('background'), (255, 255, 255))
sheet = Image.new('RGB', (cols * cell + (cols + 1) * pad, rows * cell + (rows + 1) * pad), bg)
placed = []
for i, p in enumerate(imgs):
try:
im, _ = open_image(p)
except Exception as e:
print('跳过无法读取的图片:%s(%s)' % (p, e))
continue
thumb = im.copy()
thumb.thumbnail((cell, cell), resample())
thumb = ensure_rgb(thumb)
x = pad + (i % cols) * cell + (cell - thumb.size[0]) // 2
y = pad + (i // cols) * cell + (cell - thumb.size[1]) // 2
sheet.paste(thumb, (x, y))
im.close()
placed.append(p.name)
if not placed:
raise ValueError('目录中的图片都无法读取:%s' % in_dir)
save_image(sheet, out)
return '拼图完成:%d/%d 张 -> %s(网格 %d×%d,每格长边 %dpx)' % (len(placed), n, out, cols, rows, cell)
ACTIONS = {
'info': action_info,
'convert': action_convert,
'resize': action_resize,
'crop': action_crop,
'compress': action_compress,
'watermark': action_watermark,
'slice': action_slice,
'grid': action_grid,
}
def main():
if len(sys.argv) != 2:
print("Usage: python3 run.py '<json_string>'", file=sys.stderr)
sys.exit(1)
try:
args = json.loads(sys.argv[1])
except json.JSONDecodeError as e:
print('参数不是合法 JSON:%s' % e, file=sys.stderr)
sys.exit(1)
action = (args.get('action') or '').strip().lower()
if not action:
print('Error: 缺少 action(可选:%s)' % '/'.join(sorted(ACTIONS)), file=sys.stderr)
sys.exit(1)
if action not in ACTIONS:
print('Error: 不支持的 action:%s(可选:%s)' % (action, '/'.join(sorted(ACTIONS))), file=sys.stderr)
sys.exit(1)
try:
if action == 'grid':
text = action_grid(args)
else:
input_path = (args.get('input') or '').strip()
if not input_path:
raise ValueError('缺少 input 参数')
if not Path(input_path).exists():
raise ValueError('输入文件不存在:%s' % input_path)
img, fmt = open_image(input_path)
try:
args['_input'] = input_path
text = ACTIONS[action](img, fmt, args)
finally:
img.close()
print(text)
except Exception as e:
print('Error: %s' % e, file=sys.stderr)
sys.exit(1)
if __name__ == '__main__':
main()