Visual Prompt Compiler IMG2

This skill is a thin compiler and evidence wrapper for comic image generation. It does not call Responses/Codex image tools. Actual image creation is delegated to:

python3 skills/zm-img2-generation-direct/scripts/run.py

With reference images present, that direct skill routes to /images/edits on the configured Happy OpenAI-compatible image provider (https://sub2api.happyhourse.cn/v1, model gpt-image-2).

Purpose

Use this when a comic page has a long editorial brief but the image API needs a short, hard, clear prompt.

The compiler accepts structured JSON/YAML or CLI fields:

• page_id
• title
• scene
• dialogues / dialogue
• screen_text
• reminder
• characters
• forbidden
• style_ref_text
• reference_images

It produces a concise prompt, normally about 200-500 Chinese/English characters for simple comic pages, and avoids embedding long review standards.

Reference image policy

Default behavior is minimal:

• use only explicit character reference images from reference_images;
• do not add a style page image by default;
• optional --style-image <path> can add one style reference, for example P1;
• reject any input image whose path/name matches a forbidden term, such as P2;
• require non-empty input_images by default (--require-character-refs, default true);
• cap input images with --max-input-images, default 2.

Artifacts

Each compiler run creates a directory under:

<openclaw-home>/generated-images/zm-visual-prompt-img2-workflow/_compiler_runs/<task>-<timestamp>/

Artifacts:

• compiled_prompt.txt
• request.json
• result.json
• run_command.md
• stdout.txt
• stderr.txt
• summary.json

For actual runs, summary.json also points to the underlying zm-img2-generation-direct run directory and output image.

Dry-run

Compile and validate only:

python3 skills/zm-visual-prompt-img2-workflow/scripts/compile_and_run.py \
  skills/zm-visual-prompt-img2-workflow/examples/ai_hallucination_p03.json \
  --task-name ai-hallucination-p03-compiler-test \
  --dry-run

Check:

cat <openclaw-home>/generated-images/zm-visual-prompt-img2-workflow/_compiler_runs/<run>/compiled_prompt.txt
cat <openclaw-home>/generated-images/zm-visual-prompt-img2-workflow/_compiler_runs/<run>/summary.json

Actual img2img run

Single attempt, 600000ms timeout:

python3 skills/zm-visual-prompt-img2-workflow/scripts/compile_and_run.py \
  skills/zm-visual-prompt-img2-workflow/examples/ai_hallucination_p03.json \
  --task-name ai-hallucination-p03-compiler-test \
  --run \
  --timeout-ms 600000 \
  --max-attempts 1

Expected proof for acceptance:

• summary.json.ok: true
• summary.json.used_direct_endpoint_actual: /images/edits
• summary.json.actual_mode: edit
• summary.json.input_images contains only the cat and husky references;
• no P2, no logo/QR/lobster/OpenClaw input image;
• underlying result.json has provider: happy, model: gpt-image-2, mode: edit, input_images populated.

Lightweight checks

python3 -m py_compile skills/zm-visual-prompt-img2-workflow/scripts/compile_and_run.py
python3 skills/zm-visual-prompt-img2-workflow/scripts/compile_and_run.py --help
python3 skills/zm-visual-prompt-img2-workflow/scripts/compile_and_run.py \
  skills/zm-visual-prompt-img2-workflow/examples/ai_hallucination_p03.json --dry-run

Notes

• This skill has no delivery/upload behavior.
• It does not mutate zm-img2-generation-direct.
• It intentionally favors short prompts and minimal references to reduce slow or interrupted upstream requests.