---
name: product-image-batch-workflow
description: Product image batch generation workflow for marketplace listings. Use when the user provides folders of product images and asks Codex to classify products, improve or persist category prompts, run the Geeknow/OpenAI-compatible image API batch generator, monitor long-running generation, prevent sleep, create titles, QA outputs, repair failed or low-quality images, package complete groups, or clean desktop artifacts.
---

# Product Image Batch Workflow

Use this skill to run the user's established product-image workflow end to end.

The current local implementation normally lives in the active workspace and uses:

- `product_batch_runner.py` for classification, title writing, and API calls.
- `image_api_tester.py` for Geeknow/OpenAI-compatible image edit requests.
- `category_prompts.example.json` as the prompt bank.
- `config.local.json` for API configuration. Never print or hard-code the API key.

If any required project file is missing, search the workspace with `rg --files` before recreating it.

## Workflow

1. Inspect the input folder.
   - Count direct images and image-containing subfolders.
   - Determine whether each image is one product or whether multiple reference images belong to one product.
   - If multiple references belong to one product, choose one main reference unless the user explicitly asks to use all.

2. Normalize input.
   - Create a temporary classified input folder on Desktop or under `work/`.
   - Use one subfolder per product group, e.g. `软品服饰/001/001.jpg`.
   - Use stable three-digit group IDs unless the user provided existing IDs.
   - Preserve source files. Do not modify or delete the original input folder.

3. Classify with the smallest useful category set.
   - Prefer broad categories: `软品服饰`, `配饰`, `耳环`, `宠物用品`, `家居百货`, `玩具手办`.
   - Treat 围巾/丝巾/方巾/披肩 as `软品服饰`, not `配饰`.
   - For ambiguous small goods, use `家居百货` unless a specific category matters for prompting.

4. Prompt-bank maintenance.
   - When the user gives reference images or feedback that implies a reusable scene or display pattern, summarize the proposed prompt change first.
   - Write it to `category_prompts.example.json` only after the user confirms, unless the user explicitly asks to proceed automatically.
   - Remove contradictions in prompt rules. Example: if clothes must use hangers, do not leave a common rule that bans hangers.

5. Run generation.
   - Use `product_batch_runner.py --dry-run` first to verify group count, categories, output names, and per-group image count.
   - Start 3-4 `screen` workers for medium batches. Use non-overlapping `--start/--end` ranges.
   - Use `caffeinate -dimsu` in a named `screen` session when the user asks not to sleep.
   - Set `SSL_CERT_FILE=/opt/homebrew/etc/ca-certificates/cert.pem` when calling the API.
   - If a worker stops after "生成成功，但图片下载连续失败" or SSL EOF, resume only the affected range. Existing images are skipped unless `--force` is needed.

6. Monitor long-running work.
   - Check every 5-10 minutes when requested.
   - Report: groups complete/total, images complete/total, titles, active incomplete groups, and errors.
   - Do not repeatedly restart slow but active requests. Wait unless there is a clear failure.

7. QA in three passes after generation.
   - Pass 1: count groups/images/titles and verify images can open.
   - Pass 2: verify expected filenames and title text. Flag empty/too-short titles and forbidden secondhand wording such as `used`, `preloved`, or `二手` when the user has banned it.
   - Pass 3: generate contact sheets and visually inspect for product drift, wrong category, multiple variants, floating/suspended objects, added props, watermarks/text, inconsistent straps/material/color, and bad composition.
   - Use `scripts/audit_product_output.py` for deterministic passes and contact sheets when helpful.

8. Repair.
   - Move bad images/groups to `商品输出_质检不合格_待重做` before regenerating.
   - For isolated failures, remove only the bad image and rerun that group without `--force`; the runner skips existing files and fills missing slots.
   - For same-group product drift, move and regenerate the whole group with a group-specific override in `category_prompts.example.json`.
   - Explain root cause in concrete terms when the user asks: prompt contradiction, insufficient group identity lock, model over-completing accessories, background/support ambiguity, or network download failure.

9. Package complete results.
   - For up to 25 complete product groups, copy to `~/Desktop/商品输出_可提交`.
   - For larger batches, split into `商品输出_可提交`, `商品输出_可提交_02`, etc., usually 25 groups per folder.
   - Keep the active `商品输出` folder only while work is in progress.

10. Clean up.
   - On request, move generated outputs, temporary classified folders, backups, and zip artifacts to `~/.Trash`; do not permanently delete.
   - Do not delete original source folders unless the user explicitly includes them.
   - Stop generation and `caffeinate` screen sessions when work is complete.

## Category prompting standards

### Soft goods / clothing

Use `软品服饰`.

- Clothes, dresses, tops, coats: 1 complete hanger main photo + 4 detail photos.
- Use real visible hanger/hook/rail support. No body, mannequin, hand, or floating.
- Detail photos should show neckline/strap/upper body, sleeve/side/waist, hem/skirt edge, fabric/workmanship.
- Keep straps, neckline, buttons, lace, print, material, color, and silhouette identical across the group.

### Scarves

Treat scarves as `软品服饰`, but apply scarf-specific structure.

- 第1张: complete flat-lay or natural fold main photo.
- 第2-5张: edge/rolled hem/fringe, print area, corner/border, fabric texture/folds/wear.
- Never generate clothing, bra, corset, camisole, pants, skirt, sleeves, neckline, or straps.
- Avoid hanger shots unless the source itself is clearly a hanging scarf and the result is still a scarf, not clothing.

### Accessories / jewelry

Use `配饰` or `耳环`.

- Prefer acrylic boards, trays, ceramic dishes, wood tables, balcony/window light, or simple cloth.
- Keep a single product or one original pair/set only.
- Do not add unrelated jewelry, flowers, cards, labels, hands, bodies, watermarks, or text.
- For items without a stable base, use flat-lay or fully supported low-angle shots.

### Toys / figures

Use `玩具手办`.

- Acrylic board/display stand, wood table, balcony/window light, or display shelf are acceptable.
- If the original product includes packaging, one original package box may appear behind the figure.
- Keep one character/product, same base, same outfit, same accessories. No extra figures or variants.

### Household / pet products

Use `家居百货` or `宠物用品`.

- Use acrylic boards, balcony/window table, laundry/bathroom counter, workbench, wood table, or clean floor.
- If there is no real base/support, do not stand the product up. Use flat-lay or fully supported placement.
- No hands, pets, phones, screens, labels, packaging, unrelated props, watermarks, or text unless the source product itself contains that component.

## Useful scripts

- `scripts/prepare_product_input.py`: create a classified one-reference-per-product input folder.
- `scripts/audit_product_output.py`: run count/title validation and generate contact sheets.

Read the script help with `python3 <script> --help` before first use.