CLI-Anything GIMP基于 Pillow 的无 GUI 有状态图像编辑命令行工具实战指南【免费下载链接】CLI-AnythingCLI-Anything: Making ALL Software Agent-Native -- CLI-Hub: https://clianything.cc/项目地址: https://gitcode.com/GitHub_Trending/cl/CLI-Anything导读本文围绕 skills/cli-anything-gimp/SKILL.md 展开深入讲解cli-anything-gimp——一个专为 AI Agent 与命令行重度用户设计的有状态图像编辑 CLI。它以 Pillow 为默认渲染引擎支持项目化图层合成、滤镜链、渲染期绘制操作与 50 层撤销历史并可在安装 GIMP 后自动切换到原生 Script-Fu 批处理后端。读完本文你将掌握从项目创建、图层与滤镜操作、导出渲染到 Agent 化 JSON 输出的完整实战方法并理解双渲染后端的底层实现原理。安装与前置条件cli-anything-gimp以 Python 包形式分发安装命令如下pip install cli-anything-gimp根据 gimp/agent-harness/cli_anything/gimp/README.md 与 SKILL 文档运行依赖为Python 3.10硬性要求Pillow图像处理核心引擎也是默认渲染路径的依赖clickCLI 框架负责命令分组与参数解析numpy混合模式blend modes的像素级计算与直方图分析prompt_toolkit可选交互式 REPL 模式下提供补全与历史记录。手动安装依赖可使用pip install Pillow click numpy prompt_toolkit关于 GIMP 本身的定位需要特别说明GIMP 是可选的推荐项而非必须项。SKILL 文档明确指出GIMP 用于原生批处理渲染但当 GIMP 不可用或项目中存在延迟draw操作时分层合成会走内置的 Pillow 渲染路径。从源码看export.py 中的渲染函数会先探测 GIMP 后端失败后自动降级到 Pillow整个过程对使用者透明。快速上手基本命令与 REPL 模式一次性命令One-shot# 查看帮助 cli-anything-gimp --help # 创建新项目 cli-anything-gimp project new -o project.json # 以 JSON 输出运行供 Agent 消费 cli-anything-gimp --json project info -p project.json交互式 REPL不带子命令直接启动即可进入 REPL 会话cli-anything-gimp # 交互式输入命令支持 tab 补全与历史记录 # 输入 help 查看可用命令quit 退出REPL 的核心实现在 gimp_cli.py 中当 click 主组检测到未调用子命令时会自动ctx.invoke(repl, ...)。REPL 使用shlex.split解析输入行因此带空格的文本参数可安全使用引号每条命令通过cli.main(args, standalone_modeFalse)复用于命令管线且help、quit为 REPL 层内建命令。全局选项选项说明--json输出结构化 JSON供机器/Agent 解析--project PATH指定.gimp-cli.json项目文件命令执行前自动加载--dry-run执行命令但不将状态变更写入磁盘值得注意的实现细节CLI 注册了result_callback在一次一次性命令结束后若会话状态被修改且未处于--dry-run或 REPL 模式会自动调用sess.save_session()落盘实现命令即保存的体验见 gimp_cli.py 中的auto_save_on_exit。命令组全景解析SKILL 文档将全部命令划分为八个组。以下结合源码逐一展开参数与行为细节。Project项目管理命令描述new创建新项目open打开已有项目save保存当前项目info显示项目信息profiles列出可用画布模板json打印原始项目 JSONproject new支持--width、--height、--modeRGB/RGBA/L/LA、--background默认#ffffff、--dpi默认 72、--name默认 untitled以及--profile。当指定--profile时会从 project.py 中的PROFILES字典直接覆盖宽高与 DPI模板名尺寸DPIhd1080p1920×108072hd720p1280×720724k3840×216072square10801080×108072a4_300dpi2480×3508300a4_150dpi1240×1754150letter_300dpi2550×3300300web_banner1200×62872instagram_post1080×108072instagram_story1080×192072twitter_header1500×50072youtube_thumb1280×72072icon_256256×25672icon_512512×51272项目文件是带版本号的 JSONversion: 1.0包含canvas、layers、selection、guides与metadata字段open会校验version与canvas字段是否存在否则视为无效项目文件。Layer图层管理命令描述new新建空白图层add-from-file从图片文件添加图层list列出全部图层remove按索引删除图层duplicate复制图层move移动图层到新位置set设置图层属性name、opacity、visible、mode、offset_x、offset_y天然接受负偏移值flatten展平所有可见图层merge-down与下方图层合并图层索引从 0 开始0 代表堆栈顶层。layer new的--type可选image/text/solid--fill支持transparent、white、black或十六进制颜色--opacity取值 0.0–1.0--mode为混合模式。layer set的底层实现位于 layers.py 的set_layer_property各属性的校验规则为opacity浮点必须落在 0.0–1.0visibletrue/1/yes视为可见其余为不可见mode或blend_mode必须是BLEND_MODES列表中的合法值name直接替换字符串offset_x/offset_y转为整数存储支持负值SKILL 文档特别强调命令模式与 REPL 模式均支持负偏移。flatten与merge-down采用延迟执行策略命令只是打上_flatten_pending/_merge_down_pending标记真正的像素合并发生在export render阶段。add-from-file有一个实用细节它会先通过纯 Python 的头解析读取图片尺寸支持 PNG/JPEG/GIF/BMP/WEBP/TIFF因此图层尺寸无需依赖 Pillow 即可准确记录。Canvas画布操作命令描述info显示画布信息resize调整画布尺寸不缩放内容scale等比缩放画布与全部内容crop裁剪画布到指定矩形mode设置画布色彩模式dpi设置画布 DPIcanvas resize --width W --height H [--anchor ...]仅增删画布空间而不缩放内容。--anchor决定原内容在新画布中的锚定方位支持center、top-left、top-right、bottom-left、bottom-right、top、bottom、left、right。源码会计算(dx, dy)偏移量并累加到每个图层的offset_x/offset_y上见 canvas.py。canvas scale --width W --height H [--resample lanczos|bicubic|bilinear|nearest]等比缩放画布与内容。与 resize 不同它记录每层的_scale_x/_scale_y缩放因子并在渲染期执行重采样同时按比例更新图层宽高与偏移。canvas crop --left L --top T --right R --bottom B裁剪后自动为各图层偏移减去(left, top)保持内容的相对位置正确。canvas mode可在RGB、RGBA、L、LA、CMYK、P之间切换。canvas dpi设置打印分辨率canvas info会据此计算物理尺寸英寸与百万像素数。Filter滤镜管理命令描述list-available列出全部可用滤镜可按类别过滤info查看滤镜详情add为图层添加滤镜remove按索引移除滤镜set设置滤镜参数list列出图层上的滤镜滤镜注册表定义在 filters.py 的FILTER_REGISTRY中按四类组织Adjustment调整brightness、contrast、saturation、sharpness、autocontrast、equalize、invert、posterize、solarize、grayscale、sepiaBlur模糊/锐化gaussian_blur、box_blur、unsharp_mask、smoothStylize风格化find_edges、emboss、contour、detailTransform变换渲染期应用rotate、flip_h、flip_v、resize、crop每个滤镜都声明了参数的类型、默认值与取值范围。例如brightness/contrast/saturation/sharpnessfactorfloat默认 1.0范围 0.0–10.01.0 为中性大于 1 增强小于 1 减弱gaussian_blur/box_blurradius默认 2.0范围 0.1–100.0unsharp_maskradius默认 2.0、percent默认 150、threshold默认 3posterizebits默认 41–8solarizethreshold默认 1280–255sepiastrength默认 0.80.0–1.0rotateangle-360 到 360、expandbool默认 True。filter add --param keyvalue支持重复传参参数会先被尝试解析为数字含小数点转为 float否则转 int随后经validate_params做类型转换、范围校验与默认值填充未知参数会直接报错。filter set同样走校验逻辑确保滤镜链在任何时候都处于合法状态。Media媒体文件操作命令描述probe分析图片文件list列出项目引用的媒体文件check检查所有引用的媒体文件是否存在histogram显示图片直方图分析media probe优先使用 Pillow 提取丰富元数据尺寸、模式、格式、DPI、EXIF 的 Make/Model/ISO/快门等信息、动图帧数、调色板数量、位深当 Pillow 不可用时降级为纯 Python 头部解析。media histogram返回 RGB 或亮度通道的最小/最大/均值统计见 media.py。media check对 Agent 尤其重要——它能在渲染前发现丢失的源图片避免导出时出现空白层。Export导出/渲染命令描述presets列出导出预设preset-info查看预设详情render渲染项目为图片文件延迟 draw 操作在渲染期应用export render的签名export render output [--preset name] [--overwrite] [--quality Q] [--format F]。可用预设定义于 export.py 的EXPORT_PRESETS预设格式参数pngPNGcompress_level6png-maxPNGcompress_level9jpeg-highJPEGquality95, subsampling0jpeg-mediumJPEGquality80jpeg-lowJPEGquality60webpWEBPquality85webp-losslessWEBPlosslessTruetiffTIFFcompressionlzwtiff-noneTIFF无bmpBMP无gifGIF无pdfPDF无icoICO无--overwrite用于覆盖已存在文件否则报FileExistsError--quality与--format可覆盖预设参数。渲染结果会返回输出路径、格式、尺寸、文件大小含人类可读形式、使用的预设、渲染方法与实际渲染的图层数。Session会话管理命令描述status显示会话状态undo撤销上一个操作redo重做已撤销的操作history显示撤销历史Draw绘制渲染期应用命令描述text在图层上绘制文本转为文本图层操作rect绘制矩形存储为绘制操作draw text的参数--layer L --text ... [--x X] [--y Y] [--font F] [--size S] [--color C]draw rect的参数--layer L --x1 --y1 --x2 --y2 [--fill C] [--outline C] [--width N]。两者均写入图层的draw_ops列表在渲染时由渲染管线统一应用。实战示例分层合成工作流创建新项目cli-anything-gimp project new -o myproject.json # 或指定尺寸/模板 cli-anything-gimp project new --width 1920 --height 1080 --profile hd1080p -o myproject.json # 程序化使用 JSON 输出 cli-anything-gimp --json project new -o myproject.json交互式 REPL 会话cli-anything-gimp # 交互式输入命令 # 输入 help 查看可用命令 # 使用 undo 和 redo 进行历史导航导出项目cli-anything-gimp --project myproject.json export render output.png --overwrite叠加型合成工作流SKILL 文档核心示例cli-anything-gimp --project poster.gimp-cli.json layer set 0 offset_x -48 cli-anything-gimp --project poster.gimp-cli.json layer set 0 offset_y 24 cli-anything-gimp --project poster.gimp-cli.json draw text --layer 0 --text Launch Night --x 96 --y 120 --size 72 --color #f6f1e8 cli-anything-gimp --project poster.gimp-cli.json export render output.png --overwrite使用要点SKILL 文档原注layer set在命令模式与 REPL 模式下均接受负的offset_x/offset_y值draw text与draw rect是渲染期操作——应以导出的图片而非项目 JSON 作为审查对象存在延迟 draw 操作的项目即使安装了 GIMP也默认走 Pillow 渲染路径更稳定。完整照片处理流程摘自包内 README# 创建项目 cli-anything-gimp project new --width 1920 --height 1080 --profile hd1080p -o edit.json # 添加图片图层 cli-anything-gimp --project edit.json layer add-from-file photo.jpg --name Background # 应用滤镜链 cli-anything-gimp --project edit.json filter add brightness --layer 0 --param factor1.2 cli-anything-gimp --project edit.json filter add contrast --layer 0 --param factor1.1 cli-anything-gimp --project edit.json filter add saturation --layer 0 --param factor1.3 # 添加文本叠加 cli-anything-gimp --project edit.json layer new --type text --name Title cli-anything-gimp --project edit.json draw text --layer 0 --text My Photo --size 48 --color #ffffff # 查看图层堆栈 cli-anything-gimp --project edit.json layer list # 保存并渲染 cli-anything-gimp --project edit.json project save cli-anything-gimp --project edit.json export render output.jpg --preset jpeg-high --overwrite混合模式图层合成支持的混合模式共 15 种normal、multiply、screen、overlay、soft_light、hard_light、difference、darken、lighten、color_dodge、color_burn、addition、subtract、grain_merge、grain_extract。Pillow 路径下由 export.py 中的_blend_with_mode使用 numpy 逐通道实现GIMP 路径则映射到等价的 Script-Fu 图层模式常量。状态管理有状态的会话模型CLI 的有状态特性由 session.py 的Session类实现Undo/Redo最多保留 50 层历史。每次变更前调用snapshot()深拷贝当前项目快照含描述与时间戳压入撤销栈并清空重做栈undo()将当前状态存入重做栈后回滚redo()反向操作Project persistence项目状态以 JSON 持久化保存时使用fcntl文件锁进行原子写入_locked_save_json避免并发写坏文件Session trackingstatus命令返回是否有项目、项目路径、是否修改、撤销/重做栈深度与项目名自动保存一次性命令结束后若会话被修改会自动将项目写回磁盘见前文auto_save_on_exit。输出格式人类可读与机器可读双模式所有命令都支持两种输出人类可读默认以缩进表格、键值对、颜色化的格式化文本输出_print_dict/_print_list实现机器可读--json输出缩进的结构化 JSON供 Agent 直接解析。# 人类输出 cli-anything-gimp project info -p project.json # Agent 用 JSON 输出 cli-anything-gimp --json project info -p project.json错误处理同样双轨在--json模式下错误会被序列化为{error: ..., type: ...}结构非 JSON 模式则输出到 stderr一次性命令失败时进程以非零码退出而 REPL 模式下仅打印错误并继续会话。双渲染后端原理GIMP Script-Fu 与 Pillow 回退这是本工具最值得深入理解的部分。渲染管线的调度逻辑位于 export.py 的render()先探测 GIMP 后端is_available()检查gimp、gimp-2.10、gimp-2.99是否在 PATH 中见 gimp_backend.py若 GIMP 可用且项目不含draw_ops则生成一段完整的 Script-Fu 表达式通过gimp -i -b批处理模式完成创建画布 → 自底向上插入可见图层含混合模式、透明度、偏移、滤镜链→ 展平 → 按预设导出其余情况无 GIMP、或项目含延迟 draw 操作一律回退到 Pillow 路径。Pillow 路径的关键步骤见_render_via_pillow按画布背景色与色彩模式创建基底图像RGBA/LA 支持透明背景合成自底向上reversed(layers)遍历可见图层跳过隐藏层每层经过_load_layerimage 层读源文件或填充色、solid 层生成纯色块、text 层渲染文本、_apply_filters按滤镜注册表引擎逐个应用pillow_enhance对应ImageEnhance系列、pillow_ops对应ImageOps系列、pillow_filter对应ImageFilter系列、pillow_transform对应旋转/翻转/缩放/裁剪、custom实现 sepia、_apply_draw_ops应用延迟的 rect/text 绘制操作应用_scale_x/_scale_y缩放与偏移再以对应混合模式合成到画布JPEG 输出前将 RGBA 合到白底GIF 输出前量化到 256 色调色板DPI 信息写入导出参数。从源码结构可以推断这种GIMP 原生优先、Pillow 兜底的设计既能在 GIMP 环境中获得原生的图像处理质量又能保证在任何仅有 Python 依赖的环境中稳定渲染出图。For AI Agents程序化调用规范SKILL 文档为 Agent 集成给出六条明确规范始终使用--json标志获取可解析的结构化输出检查返回码——0 为成功非零为失败解析 stderr——失败时的错误信息位于 stderr所有文件操作使用绝对路径导出操作后验证输出文件存在在偏移、绘制、混合模式或滤镜变更后审查渲染输出而不是只信任保存的项目状态因为 flatten/merge-down/draw 均为渲染期生效项目 JSON 只记录意图不反映最终像素。这套规范与项目内的端到端测试相互印证例如 tests/test_full_e2e.py 会创建真实测试图片逐像素验证亮度滤镜确实提升了像素值、验证图层堆叠顺序新图层默认在顶层等行为保证了命令语义的可信度。运行测试在仓库内可运行包自带的测试套件验证行为cd gimp/agent-harness python3 -m pytest cli/tests/test_core.py -v # 单元测试无需图片 python3 -m pytest cli/tests/test_full_e2e.py -v # 端到端测试会生成测试图片 python3 -m pytest cli/tests/ -v # 全部测试测试覆盖项目生命周期往返create→save→open、图层操作、滤镜渲染的像素级结果、画布缩放/裁剪、媒体探测与会话撤销栈等核心能力可作为理解命令语义与验证环境可用性的直接参考。更多信息完整命令参考与开发指南gimp/agent-harness/cli_anything/gimp/README.md测试说明gimp/agent-harness/cli_anything/gimp/tests/TEST.md方法论cli-anything-plugin的 HARNESS.md见 cli-anything-plugin/HARNESS.md当前版本1.0.0结语cli-anything-gimp用一个 JSON 项目文件承载图层的编辑意图图层栈、滤镜链、偏移、绘制操作把像素级的重计算推迟到渲染阶段并通过 GIMP/Pillow 双后端保证了环境适应性。对于 AI Agent 而言配合--json、返回码与渲染期审查规范它可以被可靠地编排进自动化图像生产流水线对于命令行用户而言它也提供了脚本化、可复现的图像编辑能力是让软件 Agent 原生可用理念在图像编辑领域的落地实践。【免费下载链接】CLI-AnythingCLI-Anything: Making ALL Software Agent-Native -- CLI-Hub: https://clianything.cc/项目地址: https://gitcode.com/GitHub_Trending/cl/CLI-Anything创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考