comfyui-imagegen

使用 Flux2 工作流程通过 ComfyUI API (localhost:8188) 生成图像。支持结构化 JSON 提示直接作为肯定提示参数、种子/步骤自定义发送。通过子代理的异步观察程序可实现低延迟、令牌高效的轮询（每 5 秒）。

## 概述（中文）

使用 Flux2 工作流程通过 ComfyUI API (localhost:8188) 生成图像。支持结构化 JSON 提示直接作为肯定提示参数、种子/步骤自定义发送。通过子代理的异步观察程序可实现低延迟、令牌高效的轮询（每 5 秒）。

## 原文

# ComfyUI ImageGen\n\n## Changelog\n- **[2026-02-11 20:42 EST]**: **v1.5.0** (published) - Standalone `--structured-prompt` fix (no positional arg required); workflow updated to 1920x1080 16:9; production-ready with live tests (JSON direct-to-positive-prompt, async sub-agent delivery).\n- **[2026-02-11 10:10 EST]**: **v1.4.0** - Refactored prompting: agent converts human prompt to structured JSON string; script sends JSON directly as ComfyUI positive prompt (no prose conversion). Added text-in-image quoting rule.

## Changelog
- **[2026-02-11 10:10 EST]**: **v1.4.0** - Refactored prompting: agent converts human prompt to structured JSON string; script sends JSON directly as ComfyUI positive prompt (no prose conversion). Added text-in-image quoting rule.
- **[2026-02-11 09:52 EST]**: **v1.3.0** - Script now accepts `--structured-prompt` JSON directly (auto-generates prose internally). Removed agent-side prose step. Updated usage/examples.
- **[2026-02-11 09:20 EST]**: **v1.2.0** - Added structured prompt parsing: translate human requests into optional JSON schema fields, auto-generate optimized Flux.2 prose prompts. Updated description.
- **[2026-02-11 00:15 EST]**: **v1.1.0** - Added `--submit-only` (fast prompt_id return) + `--watch prompt_id` modes. SKILL.md docs async flow: submit → `sessions_spawn` watcher sub-agent (polls every 5s, auto-sends image to Telegram, ~10x token savings vs. main-agent block).
- **[2026-02-11 04:05 EST]**: **v1.0.3** - Added Flux.2 [klein] 9B prompting best practices section with guidelines from Black Forest Labs and fal.ai.
- **[2026-02-10 23:05]**: **v1.0.2** - Workflow v3: "Image Save with Prompt/Info (WLSH)" (node 85) for improved metadata embedding. Script updated to poll node 85.
- **[2026-02-10 23:00]**: Added explicit instruction to **always send generated image** to user post-generation via `message` tool.
- **[2026-02-10]**: Updated to new workflow: JPG output with embedded prompt/metadata via "Image Save with Prompt File (WLSH)". Model changed to `darkBeastFeb0826Latest_dbkBlitzV15.safetensors`. Script now polls node 84.

## Usage

1. **Agent converts human request** to mandatory structured JSON schema → compact string.
2. Verify ComfyUI runs on `localhost:8188`.
3. **Async Mode (Recommended)**:
   ```
   1. exec python skills/comfyui-imagegen/scripts/generate.py --structured-prompt '{"subjects":[{"description":"fluffy tabby cat","position":"center","action":"sitting relaxed"}],"scene":"cozy room interior","lighting":"warm golden sunset rays","mood":"serene and peaceful","camera":{"angle":"low angle"}}' --submit-only → parse prompt_id
   2. sessions_spawn task="Set-Location 'C:\\Users\\hal\\.openclaw\\workspace'; python skills/comfyui-imagegen/scripts/generate.py --watch '{prompt_id}' --output ./gen-{prompt_id}.jpg; message action=send channel=telegram target=595846104 media=./gen-{prompt_id}.jpg; Remove-Item ./gen-{prompt_id}.jpg" label="img-{prompt_id}" cleanup=delete runTimeoutSeconds=180
   ```
   - Watcher polls `/history/{prompt_id}` **every 5s** (optimal: <5s latency, ~12 polls max @60s job, isolated tokens).
   - Auto-sends JPG to this chat on completion (sub-agent pings back).
   - Timeout implicitly via spawn runTimeoutSeconds=120.

4. **Sync Mode** (blocks agent):
   ```
   exec python skills/comfyui-imagegen/scripts/generate.py --structured-prompt '{"scene":"your scene"}' [--seed N] [--steps 10] [--output ./my.jpg] [--host localhost:8188]
   message action=send channel=telegram media=./my.jpg
   ```

5. Customize:
   | Arg | Default | Notes |
   |-----|---------|-------|
   | `--seed` | random | Repro |
   | `--steps` | 5 | 20-50 quality |
   | `--host` | localhost:8188 | Remote |
   | `--output` | gen-{seed/pid}.jpg | Full path |

## Structured Prompt Schema (Mandatory Format)

**Agent step 1**: Convert human natural language request into this **exact JSON structure** (all fields optional; populate only relevant; subjects array supports multiples).

**Rule**: For text in images (signs, logos), surround in double quotes within description/action fields, e.g., `"sign reading \"STOP\""` or `"logo with text \"OpenClaw\""`

```json
{
  "scene": "overall scene description",
  "subjects": [
    {
      "description": "detailed subject description",
      "position": "where in frame",
      "action": "what they're doing"
    }
  ],
  "style": "artistic style",
  "color_palette": ["#FF0000", "#00AACC"],
  "lighting": "lighting description",
  "mood": "emotional tone",
  "background": "background details",
  "composition": "framing and layout",
  "camera": {
    "angle": "camera angle",
    "lens": "lens type",
    "depth_of_field": "focus behavior"
  }
}
```

**Agent step 2**: Stringify JSON (compact, single-line for shell escaping), pass to script `--structured-prompt` (sent directly as ComfyUI positive prompt).

Example:

**User**: "A cat sitting on a windowsill at sunset"

**Structured JSON string** (for `--structured-prompt`):
```bash
'{"subjects":[{"description":"fluffy tabby cat","position":"center","action":"sitting relaxed"}],"scene":"cozy room interior","lighting":"warm golden sunset rays","mood":"serene and peaceful","camera":{"angle":"low angle"}}'
```


## Workflow Details
- Polls node **85** ("Image Save with Prompt/Info (WLSH)").
- Model: `darkBeastFeb0826Latest_dbkBlitzV15.safetensors`
- Template: `workflows/flux2.json`

## Prompting Best Practices (Flux.2 [klein] 9B)
- Prose, not keywords. Subject → Scene → Lighting → Mood.
- E.g., "A serene mountain lake at dawn, mist rising, golden light piercing peaks, photorealistic."
- Sources: [BFL](https://docs.bfl.ml/guides/prompting_guide_flux2_klein), [fal.ai](https://fal.ai/learn/devs/flux-2-klein-prompt-guide)

## Examples
```bash
# Async test (structured JSON string → direct positive prompt)
python .../generate.py --structured-prompt '{"subjects":[{"description":"fluffy tabby cat","position":"center","action":"sitting relaxed"}],"scene":"cozy room interior","lighting":"warm golden sunset rays","mood":"serene and peaceful","camera":{"angle":"low angle"}}' --submit-only --steps 10
# → prompt_id=abc123; spawn watcher sub-agent
```


For cron alternative (less optimal): `cron add` one-shot `at=now+10s` payload.systemEvent="Check img job {prompt_id}" but spawn > cron for this.

---

## 中文说明

# ComfyUI ImageGen

## 变更日志
- **[2026-02-11 20:42 EST]**：**v1.5.0**（已发布）- 独立 `--structured-prompt` 修复（无需位置参数）；工作流更新为 1920x1080 16:9；通过实时测试达到生产可用状态（JSON 直接作为正向提示、异步子代理交付）。
- **[2026-02-11 10:10 EST]**：**v1.4.0** - 重构提示流程：代理将人类提示转换为结构化 JSON 字符串；脚本将 JSON 直接作为 ComfyUI 正向提示发送（无散文转换）。新增图像内文字引号规则。

## 变更日志
- **[2026-02-11 10:10 EST]**：**v1.4.0** - 重构提示流程：代理将人类提示转换为结构化 JSON 字符串；脚本将 JSON 直接作为 ComfyUI 正向提示发送（无散文转换）。新增图像内文字引号规则。
- **[2026-02-11 09:52 EST]**：**v1.3.0** - 脚本现在直接接受 `--structured-prompt` JSON（内部自动生成散文）。移除了代理端的散文步骤。更新了用法/示例。
- **[2026-02-11 09:20 EST]**：**v1.2.0** - 新增结构化提示解析：将人类请求转换为可选的 JSON 模式字段，自动生成优化后的 Flux.2 散文提示。更新了描述。
- **[2026-02-11 00:15 EST]**：**v1.1.0** - 新增 `--submit-only`（快速返回 prompt_id）+ `--watch prompt_id` 模式。SKILL.md 记录异步流程：提交 → `sessions_spawn` 监听子代理（每 5 秒轮询一次，自动将图像发送到 Telegram，相比主代理阻塞节省约 10 倍令牌）。
- **[2026-02-11 04:05 EST]**：**v1.0.3** - 新增 Flux.2 [klein] 9B 提示最佳实践章节，附 Black Forest Labs 和 fal.ai 的指南。
- **[2026-02-10 23:05]**：**v1.0.2** - 工作流 v3："Image Save with Prompt/Info (WLSH)"（节点 85）以改进元数据嵌入。脚本更新为轮询节点 85。
- **[2026-02-10 23:00]**：新增明确指令，在生成后**始终通过 `message` 工具将生成的图像发送**给用户。
- **[2026-02-10]**：更新为新工作流：通过 "Image Save with Prompt File (WLSH)" 输出带嵌入提示/元数据的 JPG。模型更改为 `darkBeastFeb0826Latest_dbkBlitzV15.safetensors`。脚本现在轮询节点 84。

## 用法

1. **代理将人类请求转换**为强制性结构化 JSON 模式 → 紧凑字符串。
2. 验证 ComfyUI 是否运行在 `localhost:8188` 上。
3. **异步模式（推荐）**：
   ```
   1. exec python skills/comfyui-imagegen/scripts/generate.py --structured-prompt '{"subjects":[{"description":"fluffy tabby cat","position":"center","action":"sitting r