references/codex-imagegen.md
3.7 KB查看排版效果| 1 | # `codex-imagegen` Wrapper Invocation |
| 2 | |
| 3 | Load this reference only when the [Image Generation Tools](../SKILL.md#image-generation-tools) rule has resolved to `codex-imagegen` — i.e., the current runtime exposes no native `imagegen` skill but `codex` CLI is on `PATH` with an active `codex login`. |
| 4 | |
| 5 | ## Preferred path: route through `baoyu-image-gen` |
| 6 | |
| 7 | If the `baoyu-image-gen` skill is available in this runtime, **always** invoke through it rather than calling the wrapper directly. It handles retry/cache/batch/EXTEND.md preferences uniformly with every other provider. |
| 8 | |
| 9 | ```bash |
| 10 | ${BUN_X} <baoyu-image-gen-base>/scripts/main.ts \ |
| 11 | --provider codex-cli \ |
| 12 | --image <ABSOLUTE_output> \ |
| 13 | --promptfiles <ABSOLUTE_prompts/NN-{type}-[slug].md> \ |
| 14 | --ar <ratio> \ |
| 15 | [--ref <ABSOLUTE_file>]... |
| 16 | ``` |
| 17 | |
| 18 | Resolve `<baoyu-image-gen-base>` the same way you resolve any sibling skill — through your runtime's skill registry (`Skill` tool, plugin marketplace, or `$HOME/.baoyu-skills/baoyu-image-gen/`). |
| 19 | |
| 20 | ## Fallback: spawn the wrapper directly |
| 21 | |
| 22 | Only when `baoyu-image-gen` is NOT installed in the current runtime. Discover the wrapper's location at runtime — do NOT hard-code `../../packages/...` from this skill: |
| 23 | |
| 24 | 1. **Honor explicit override**: if `$BAOYU_CODEX_IMAGEGEN_BIN` is set and points to a real file, use that path. It may be `.ts` (spawn `bun <path>`) or `.sh`/binary (spawn directly). |
| 25 | 2. **Search the plugin root**: walk up from this skill's directory looking for `packages/baoyu-codex-imagegen/src/main.ts`. If found, that is the wrapper. Spawn it with `bun`. |
| 26 | 3. **Last resort**: tell the user that `codex-imagegen` is not available in this runtime and ask whether to install the `baoyu-skills` plugin (or set `BAOYU_CODEX_IMAGEGEN_BIN`) or pick another backend. |
| 27 | |
| 28 | Once located, the invocation shape is: |
| 29 | |
| 30 | ```bash |
| 31 | bun <WRAPPER>/main.ts \ |
| 32 | --image <ABSOLUTE_output> \ |
| 33 | --prompt-file <ABSOLUTE_prompts/NN-{type}-[slug].md> \ |
| 34 | --aspect <ratio> \ |
| 35 | [--ref <ABSOLUTE_file>]... \ |
| 36 | [--timeout <ms>] \ |
| 37 | [--cache-dir ~/.cache/baoyu-codex-imagegen] \ |
| 38 | [--log-file <ABSOLUTE_jsonl_log_path>] |
| 39 | ``` |
| 40 | |
| 41 | If `bun` is missing, `npx -y bun <WRAPPER>/main.ts ...` works as a fallback. |
| 42 | |
| 43 | ## Parameter notes |
| 44 | |
| 45 | - **All filesystem inputs** are auto-resolved against `process.cwd()` when relative, but agents should pass absolute paths to be robust against cwd drift. |
| 46 | - **`--timeout`** defaults to `300000` (5 min) per `codex exec` attempt. Raise (e.g. `--timeout 600000` for 10 min) on slow networks or large prompts. |
| 47 | - **`--cache-dir`** is off by default. Enable for repeatable runs to skip redundant generations of the same prompt+aspect+refs. |
| 48 | - **Authentication**: the wrapper uses the user's Codex subscription — no `OPENAI_API_KEY` is read or sent. |
| 49 | |
| 50 | ## Stdout contract |
| 51 | |
| 52 | Single JSON line: |
| 53 | |
| 54 | - Success: `{"status":"ok","path":"...","bytes":N,"elapsed_seconds":N,"thread_id":"...","attempts":N,"cached":bool,...}` |
| 55 | - Failure: `{"status":"error","path":"...","bytes":0,"error":"...","error_kind":"..."}` |
| 56 | |
| 57 | `error_kind` values: `codex_not_installed`, `invalid_args`, `prompt_file_missing`, `spawn_failed`, `timeout`, `no_image_gen_tool_use`, `output_missing`, `invalid_png`, `agent_refused`, `lock_busy`. |
| 58 | |
| 59 | On retryable errors (timeout, spawn_failed, no_image_gen_tool_use, output_missing, invalid_png, agent_refused), ask the user whether to retry or fall back to another backend. |
| 60 | |
| 61 | ## Batch semantics |
| 62 | |
| 63 | - Codex `image_gen` returns **one image per call** (`n=1` only). Multi-image jobs must dispatch one wrapper call per image. |
| 64 | - The wrapper does NOT accept a `--sessionId` flag. Chain/scene consistency must come from `--ref` reference images. |
| 65 | - `--size` and `--quality` are silently ignored — Codex picks pixel dimensions from `--aspect`. |
文件内容是平台检查时读出的文本，只供查看。平台不会运行包里的任何脚本或程序。
