Imgcli

imgcli

用于指导 Agent 直接执行 imgcli，而不是解释底层图像算法实现。

项目边界

• imgcli 不负责生成图片。
• 图片生成应由外部工具完成，例如 Gemini、GPT Image 或其他 provider CLI/API。
• imgcli 负责对已经存在的图片做检查、加工、排版、打包和导出。

执行前检查

1. 先检查是否已构建：imgcli version 或 ./bin/imgcli version 2. 如果未安装但仓库存在，优先执行：

make build
./bin/imgcli version

3. 默认使用 JSON 输出，不要关闭 --json 4. 输入路径必须存在；输出扩展名必须与目标格式匹配

常用工作流

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：检查 --preset
• INVALID_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 或调低分卷阈值