mirror of
https://github.com/JimLiu/baoyu-skills.git
synced 2026-07-13 06:19:46 +08:00
Jim Liu 宝玉
23fac03691
Move the codex-imagegen wrapper out of scripts/ into its own workspace package alongside baoyu-md, baoyu-chrome-cdp, and baoyu-fetch. Drop the bash shim — src/main.ts now carries a `#\!/usr/bin/env bun` shebang and serves as the sole entrypoint. Add scripts/sync-codex-imagegen.sh so skills/baoyu-image-gen/scripts/codex-imagegen/ can be regenerated from packages/baoyu-codex-imagegen/src/ for skill self-containment. Update CLAUDE.md, docs/codex-imagegen-backend.md, and the CI workflow paths accordingly.
103 lines
3.5 KiB
Markdown
103 lines
3.5 KiB
Markdown
# baoyu-codex-imagegen
|
||
|
||
Generate images via Codex CLI's built-in `image_gen` tool from non-Codex runtimes (e.g., Claude Code). The wrapper spawns `codex exec --json` and lets the user's existing Codex subscription drive image generation — **no `OPENAI_API_KEY` required**.
|
||
|
||
This package implements the `preferred_image_backend: codex-imagegen` config key referenced across the `baoyu-skills` plugin and is the engine behind `baoyu-image-gen --provider codex-cli`.
|
||
|
||
## Layout
|
||
|
||
```
|
||
packages/baoyu-codex-imagegen/
|
||
├── src/
|
||
│ ├── main.ts # CLI orchestrator (executable via `#!/usr/bin/env bun`)
|
||
│ ├── spawn.ts # codex exec child-process wrapper
|
||
│ ├── parser.ts # JSONL event-stream parser
|
||
│ ├── validator.ts # Output PNG / image_gen-invocation verification
|
||
│ ├── cache.ts # SHA256 idempotency cache + file lock
|
||
│ ├── logger.ts # Structured JSONL logging
|
||
│ ├── types.ts # Shared types and `GenError`
|
||
│ └── *.test.ts # Bun unit tests
|
||
└── package.json # `bin` points to `src/main.ts`
|
||
```
|
||
|
||
## Prerequisites
|
||
|
||
```bash
|
||
npm install -g @openai/codex
|
||
codex login # signs in with your OpenAI account (subscription)
|
||
codex --version # confirm >= 0.130
|
||
```
|
||
|
||
`bun` is required for running the wrapper:
|
||
|
||
```bash
|
||
brew install oven-sh/bun/bun
|
||
```
|
||
|
||
If `bun` is not on `PATH`, `npx -y bun src/main.ts …` works as a fallback.
|
||
|
||
## Usage
|
||
|
||
```bash
|
||
# Inline prompt (executes via shebang once bun is on PATH)
|
||
./src/main.ts \
|
||
--image /tmp/cat.png \
|
||
--prompt "A friendly orange cat, watercolor"
|
||
|
||
# Or invoke bun explicitly
|
||
bun src/main.ts \
|
||
--image cover.png \
|
||
--prompt-file prompts/01-cover.md \
|
||
--aspect 16:9 \
|
||
--cache-dir ~/.cache/baoyu-codex-imagegen
|
||
|
||
# Without bun installed
|
||
npx -y bun src/main.ts --image cover.png --prompt "..."
|
||
```
|
||
|
||
Stdout emits a single JSON line:
|
||
|
||
```json
|
||
{"status":"ok","path":"…","bytes":1234567,"elapsed_seconds":62,"thread_id":"…","attempts":1,"cached":false,"usage":{…}}
|
||
```
|
||
|
||
On failure:
|
||
|
||
```json
|
||
{"status":"error","path":"…","bytes":0,"error":"…","error_kind":"timeout"}
|
||
```
|
||
|
||
`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`.
|
||
|
||
## Options
|
||
|
||
| Flag | Description |
|
||
|---|---|
|
||
| `--image <path>` | Output PNG path (required) |
|
||
| `--prompt <text>` | Prompt text |
|
||
| `--prompt-file <path>` | Read prompt from file (mutually exclusive with `--prompt`) |
|
||
| `--aspect <ratio>` | Aspect ratio (`1:1`, `16:9`, `9:16`, `4:3`, `2.35:1`). Default: `1:1` |
|
||
| `--ref <file>` | Reference image (repeatable) |
|
||
| `--timeout <ms>` | Codex exec timeout in ms. Default: `300000` |
|
||
| `--retries <n>` | Retry attempts on retryable errors. Default: `2` |
|
||
| `--retry-delay <ms>` | Base retry delay (exponential). Default: `1500` |
|
||
| `--cache-dir <path>` | Enable idempotency cache. Disabled by default. |
|
||
| `--log-file <path>` | Append structured JSONL log |
|
||
| `-v, --verbose` | Verbose stderr logging |
|
||
| `-h, --help` | Show help |
|
||
|
||
## Test
|
||
|
||
```bash
|
||
cd packages/baoyu-codex-imagegen
|
||
bun test
|
||
```
|
||
|
||
## Trade-offs
|
||
|
||
- 5–10× slower than direct OpenAI API calls (except on cache hits)
|
||
- Uses your Codex subscription — programmatic use of `codex exec` falls into the same terms as interactive use
|
||
- Requires `codex` CLI and active login session
|
||
|
||
See [`docs/codex-imagegen-backend.md`](../../docs/codex-imagegen-backend.md) for the full background.
|