imgcli
用于指导 Agent 直接执行 imgcli，而不是解释底层图像算法实现。
项目边界
imgcli不负责生成图片。- 图片生成应由外部工具完成，例如 Gemini、GPT Image 或其他 provider CLI/API。
imgcli负责对已经存在的图片做检查、加工、排版、打包和导出。
执行前检查
- 先检查是否已构建：
imgcli version或./bin/imgcli version - 如果未安装但仓库存在，优先执行：
make build
./bin/imgcli version
- 默认使用 JSON 输出，不要关闭
--json - 输入路径必须存在；输出扩展名必须与目标格式匹配
常用工作流
Inspect
./bin/imgcli inspect \
--input input.jpg \
--hash \
--color-stats
可选：
--input-dir ./images--limit 10
Compose
./bin/imgcli compose \
--input input.jpg \
--output poster.jpg \
--width 1080 \
--height 1440 \
--layout poster \
--title "Launch Day" \
--subtitle "A fixed-layout creator card"
可选：
--logo brand.png--badge NEW--background-color '#f3efe7'--safe-area 64,64,64,64
Convert
./bin/imgcli convert \
--input alpha.png \
--output out.jpg \
--flatten-background "#ffffff" \
--max-width 1600 \
--quality 82 \
--strip-metadata
Run
./bin/imgcli run \
--recipe recipe.json \
--dry-run
./bin/imgcli run \
--recipe recipe.json
引用规则：
input:<name>引用顶层输入step:<id>引用前置 step 产出的文件
Variants
./bin/imgcli variants \
--input poster.jpg \
--output-dir dist \
--preset-set creator-basic
可选：
--preset xiaohongshu --preset wechat_cover--background blur|solid--filename-template '{base}_{preset}{ext}'
SmartPad
./bin/imgcli smartpad \
--input input.jpg \
--output output.jpg \
--preset xiaohongshu
可选：
--background blur|solid--blur-sigma 5--quality 85
Images to PDF
./bin/imgcli topdf \
--input page1.jpg \
--input page2.jpg \
--output bundle.pdf \
--watermark-text "internal" \
--watermark-position tile
可选：
--input-dir ./images--watermark-opacity 0.25--watermark-size 42
Vertical Stitch
./bin/imgcli stitch \
--input a.jpg \
--input b.jpg \
--output stitched.jpg \
--width 1080
可选：
--input-dir ./images--part-height-limit 65535--quality 85
真实烟测
如果本机已经配置 baoyu-image-gen，执行：
make real-smoke
该流程会：
- 生成 3 张真实测试图
- 跑通
inspect - 跑通
compose - 跑通
convert - 跑通
variants - 跑通
run - 跑通
smartpad、topdf、stitch - 校验输出文件类型并打印产物目录
输出契约
成功：
{"ok":true,"command":"smartpad","data":{}}
失败：
{"error":"reason","code":"INVALID_ARGUMENT","exit_code":2}
失败时最小处理
PRESET_NOT_FOUND：检查--presetINVALID_ARGUMENT：检查必填 flag 与输入模式冲突CONFIG_ERROR：检查--recipe文件扩展名和 JSON/YAML 语法PLAN_INVALID：检查 step 引用、重复 step id、必填字段OUTPUT_CONFLICT：检查 recipe 是否把多个 step 写到同一路径，或覆盖顶层输入DECODE_FAILED：检查图片是否损坏或格式不支持PDF_WRITE_FAILED：检查输出路径是否可写CANVAS_TOO_LARGE：减小--width或调低分卷阈值