- name
- image-editor
- description
- 专业图像后期处理工具。支持多种修图风格（末日大片、日系清新、复古胶片等），自动检测并安装 ImageMagick，支持 RAW/JPG/PNG 等多种格式，提供批量处理和自定义预设功能。Use when: (1)用户需要修图/调色/加滤镜, (2)处理 RAW 格式照片, (3)批量处理图片, (4)创建自定义修图预设
专业图像后期处理工具
功能特性
- ✅ 自动检测并安装 ImageMagick
- ✅ 多种修图风格预设
- ✅ 支持 RAW/JPG/PNG/TIFF 等格式
- ✅ 批量处理支持
- ✅ 自定义预设保存
- ✅ 中间文件隔离管理
修图风格预设
| 风格 | 特点 | 适用场景 |
|---|---|---|
apocalyptic | 低饱和、青橙色调、暗角、颗粒 | 末日、科幻、电影感 |
japanese | 高明度、低对比、偏青绿 | 日系清新、日常记录 |
vintage | 暖色调、褪色感、柔焦 | 复古、怀旧 |
bw-high | 黑白、高对比 | 纪实、艺术 |
custom | 用户自定义参数 | 个性化需求 |
使用方法
单张处理
from scripts.editor import ImageEditor
editor = ImageEditor()
result = editor.process(
input_path="photo.dng",
style="apocalyptic",
output_name="my_photo"
)批量处理
editor.batch_process(
input_dir="./photos",
style="japanese",
output_dir="./output"
)自定义预设
# 创建自定义预设
editor.create_preset(
name="my_style",
params={
"brightness_contrast": "-10x30",
"modulate": "100,70",
"tint": "#3a5a4a",
"gamma": 0.95,
"sharpen": "0x1.2",
"noise": 0.3,
"vignette": True
}
)工作流程（迭代式分步修图法）
核心原则
- 必须采用迭代式分步修图法，确保每一步效果达标后再进行下一步，最终从原始图一次性生成无压缩损失的最终图像。
- 除非风格指定偏向高对比，否则不要增加对比度指令。
- 除非风格偏向，否则尽可能保证图像明暗的顺滑过渡，保留高光和暗部细节。
- 多模态模型在检验中间和最终图像时，要注意有没有因为过度拉参数导致的颜色断层，杂色，色斑色块等不正常现象。
详细步骤
1. 初始化
- 检测 ImageMagick，未安装则提示安装
- 分析原始图片（分辨率、格式、色彩空间）
- 根据原始图片文件名创建独立工作目录（避免不同图片的文件混淆，如果有重名就加-001,-002...这样的后缀）：
workspace/image-editor-work/
├── {filename}/ # 以原始图片文件名命名的目录
│ ├── temp/ # 中间处理文件
│ │ ├── step01.jpg
│ │ ├── step02.jpg
│ │ └── params/ # 每步成功参数记录
│ │ ├── step01_params.txt
│ │ ├── step02_params.txt
│ │ └── ...
│ └── final/ # 最终输出
│ └── xxx_final.jpg
├── {filename2}/ # 另一张图片的独立目录
└── ...- 示例：处理
IMG_20260329_111232.dng时，创建image-editor-work/IMG_20260329_111232/目录
2. 迭代式分步修图（关键流程）
核心原则：保留原图动态范围和色深
对于所有图片（不论是RAW还是其他格式图片），每步都必须从原始文件开始处理，叠加之前已验证的参数，避免中间JPG丢失动态范围和色深。
Step A - 生成中间JPG（仅用于验证，不参与修图流程）
核心原则：始终从原始文件开始
每步处理都从原始文件开始，带上之前所有已验证的参数 + 当前步骤新参数，生成中间JPG仅用于多模态验证。
- 命令格式示例：
# Step 1: 从原始图开始（不降低亮度，避免暗部死黑）
magick original.dng -brightness-contrast 0x15 -quality 100 step01.jpg
# Step 2: 仍从原始图开始，叠加Step1参数 + 新参数
magick original.dng -brightness-contrast 0x15 -modulate 105,65 -quality 100 step02.jpg
# Step 3: 继续从原始图开始，叠加Step1+Step2参数 + 新参数
magick original.dng -brightness-contrast 0x15 -modulate 105,65 -fill "#3a5a6a" -tint 20 -quality 100 step03.jpg- JPG质量必须设为最高：
-quality 100 - 严禁使用
-resize或-crop：除非用户明确要求改变尺寸，否则不得改变原始分辨率 - 注意：ImageMagick 7+ 使用
magick命令即可，不需要magick convert
重要：中间JPG仅用于多模态模型验证效果，绝不作为下一步的输入。
Step B - 多模态效果验证
- 使用多模态模型查看生成的中间JPG
- 判断是否达到该步骤的修图目标
- 如果未达到目标：
- 分析原因，调整 magick 参数 - 重新从原始文件开始，带上之前所有已验证参数 + 调整后新参数 - 循环此步骤直到达标
- 如果达到目标：
- 将该步骤的新增 magick 参数写入 temp/params/stepXX_params.txt - 继续从原始文件开始处理下一步，带上所有已验证参数（包括刚记录的）
关键记忆：
- 每步都重新读取原始文件
- 参数是累积的：Step N = 原始图 + param1 + param2 + ... + paramN
- 中间JPG只看不用，下一步仍从原始图开始
3. 循环执行
- 对下一个修图步骤重复"Step A → Step B"流程
- 每步达标后记录参数到对应的
stepXX_params.txt - 直到所有修图步骤完成
4. 生成最终图像（关键步骤）
严禁使用最后一步的中间JPG作为最终输出。
正确做法：
- 读取原始图片
- 依次读取每步记录的参数文件
stepXX_params.txt - 构建一条完整的 magick 命令链，按修图步骤顺序拼接所有参数
- 从原始图一次性生成最终图像：
magick original.dng \
-brightness-contrast 0x15 \
-modulate 105,65 -fill "#2a5a6a" -tint 20 \
-sharpen 0x1.2 \
-attenuate 0.4 +noise gaussian \
-size 4096x3072 radial-gradient:black-white -level 0%,50% -compose blend -define compose:args=25 -composite \
-quality 100 final_xxx.jpg为什么这样做？
- 中间JPG经过多次保存，存在JPEG压缩损失
- 从原始图一次性应用所有参数，避免层层压缩
- 最终图像画质最高
5. 收尾与交付
文件保存：
- 将最终图像复制到
final/目录 - 可选：清理中间文件或保留供复查
- 记录处理日志
交付给用户：
由于 open_result_view 工具在某些环境下可能无法直接展示图片预览，必须同时提供以下信息：
- 最终文件路径（必须提供）
最终图像已保存至：C:\Users\z9z\WorkBuddy\Claw\image-editor-work\final\xxx_final.jpg- 尝试使用 open_result_view（可选）
from tools import open_result_view
open_result_view(target_file=final_path)- 直接展示图片（如果环境支持）
- 使用 read_file 读取图片文件，系统可能会自动渲染预览
完整交付示例：
final_path = "C:\\Users\\z9z\\WorkBuddy\\Claw\\image-editor-work\\final\\xxx_final.jpg"
# 告知用户文件位置
print(f"修图完成！最终图像保存至：{final_path}")
#将图片发送给用户
# 尝试打开结果视图
try:
open_result_view(target_file=final_path)
except:
pass
# 尝试直接展示图片
try:
read_file(filePath=final_path)
except:
pass重要：无论 open_result_view 是否成功显示，都必须明确告知用户文件的本地路径，确保用户能找到成品。
流程图示
统一处理流程（所有格式）：
原始图
│
├──► Step 1 参数 ──► 生成中间JPG ──► [多模态检查] ──► 达标?
│ │
│ 否 ──► 调整参数 ──► 重新从原始图生成
│ │
│ 是 ──► 记录参数到 step01_params.txt
│
├──► Step 1+2 参数 ──► 生成中间JPG ──► [多模态检查] ──► 达标?
│ │
│ 否 ──► 调整参数 ──► 重新从原始图生成
│ │
│ 是 ──► 记录参数到 step02_params.txt
│
├──► Step 1+2+3 参数 ──► 生成中间JPG ──► [多模态检查] ──► 达标?
│ │
│ ...
▼
[最终生成] ──► 从原始图一次性应用所有参数 ──► 最终图像 (最高画质)核心要点：
- 每步都从原始文件开始
- 参数累积：Step N = 原始图 + param1 + param2 + ... + paramN
- 中间JPG仅用于验证，绝不参与下一步处理
目录结构
workspace/
└── image-editor-work/
├── {filename1}/ # 图片1的独立工作目录
│ ├── temp/
│ │ ├── step01.jpg
│ │ ├── step02.jpg
│ │ └── params/
│ │ ├── step01_params.txt
│ │ └── step02_params.txt
│ └── final/
│ └── {filename1}_final.jpg
├── {filename2}/ # 图片2的独立工作目录
│ ├── temp/
│ │ ├── step01.jpg
│ │ └── params/
│ │ └── step01_params.txt
│ └── final/
│ └── {filename2}_final.jpg
└── ...命名规范：
- 工作目录名：
{原始文件名（不含扩展名）} - 中间文件：
step{NN}.jpg - 参数文件：
step{NN}_params.txt - 最终文件：
{原始文件名}_final.jpg
注意事项
- 处理 RAW 格式需要 ImageMagick 支持 RAW 解码
- 大分辨率图片处理耗时较长
- 建议先处理预览图确认效果
修图步骤判定标准（给Agent的指引）
多模态检查要点
查看中间JPG时，需关注：
| 步骤类型 | 检查要点 | 达标标准 |
|---|---|---|
| 对比度调整 | 高光/阴影细节、整体通透感 | 暗部有细节、亮部不过曝、画面有层次感 |
| 色调调整 | 色温、饱和度、色彩倾向 | 符合目标风格（如青橙色调的青蓝阴影+暖黄高光） |
| 暗角 | 四角压暗程度、过渡自然度 | 四角适度压暗、边缘到中心过渡平滑、不突兀 |
| 暗部保护 | 阴影区域是否死黑、有无细节 | 暗部不发死黑，能分辨出纹理和层次；若整体偏暗导致难以判断，需主动提亮检查暗部 |
| 锐化 | 边缘清晰度、噪点控制 | 主体边缘清晰、无明显锯齿或噪点增加 |
| 颗粒 | 颗粒均匀度、自然感 | 胶片质感自然、不破坏细节、颗粒分布均匀 |
| 破坏性修图 | 过度拉参数导致的颜色断层，杂色，色斑色块等 | 颜色自然过度，没有断层，没有非额外添加颗粒效果的噪点，没有杂色和色斑色块 |
参数调整策略
- 效果不足：增加参数强度（如对比度从15提升到25）
- 效果过度：降低参数强度（如暗角从80%降低到60%）
- 色彩偏差：调整色相或更换色调填充色
- 暗部过黑：
- 优先去掉 -brightness-contrast 中的负亮度值（如 -5x20 改为 0x20） - 避免使用 gamma < 1.0（如 gamma 0.9/0.95），改用 modulate 或 level 控制影调 - 降低暗角强度（compose:args 从 60 降到 30-40） - 如暗部实在看不清，可临时生成一张 +modulate 150 的版本辅助检查细节
- 局部问题：考虑是否需要分区域处理
重要提醒
- 质量优先：所有中间JPG必须使用
-quality 100 - 保留原始：严禁覆盖或修改原始图片
- 参数记录：每步达标后立即写入参数文件，防止丢失
- 始终从原始图开始：每步处理都从原始文件出发，叠加之前所有已验证参数
- 中间JPG仅用于验证：绝不使用中间JPG作为下一步的输入
- 最终生成：从原始图一次性应用所有参数生成最终图像
- 暗部保护（避免过黑）：
- 严禁用 -brightness-contrast 的负亮度值压暗（如 -5x20、-10x40）。如需暗调，用 modulate（如 95）或后期 level 实现，避免线性偏移杀死暗部。 - 慎用 gamma < 1.0（如 0.9、0.95），gamma 压缩会吞掉暗部层次。 - 暗角用 blend 替代 multiply：multiply 会让整张图（不仅是四角）被渐变灰色压暗；改用 -compose blend -define compose:args=强度，建议强度 30-50。