mirror of
https://github.com/JimLiu/baoyu-skills.git
synced 2026-07-12 05:51:44 +08:00
Yelban
e98fa33bc2
Implements the preferred_image_backend: codex-imagegen config key
already referenced in several SKILL.md files but with no corresponding
backend. Bridges non-Codex runtimes (Claude Code, etc.) to Codex CLI's
built-in image_gen tool via 'codex exec'. Uses the user's Codex
subscription — no OPENAI_API_KEY required.
Reliability:
- Retry with exponential backoff (default 2 retries, configurable)
- 9 classified error kinds (retryable vs non-retryable)
- Node child_process timeout with SIGTERM→SIGKILL ladder
Correctness:
- Verifies image_gen was actually invoked (not bypassed) by checking
$CODEX_HOME/generated_images/{thread_id}/ for a PNG
- PNG magic byte validation
- Output file size sanity check
Observability:
- Structured JSONL logging with --log-file
- Verbose stderr mode with --verbose
- Returns thread_id, tool_calls, token usage in result JSON
- Raw codex event stream preserved per attempt for debugging
Efficiency:
- Idempotency cache via --cache-dir (sha256 of prompt+aspect+refs)
- Cache hit returns in <0.3s vs 50-90s cold
Features:
- --ref reference images (repeatable, passed through to codex exec --image)
- --retries, --retry-delay, --timeout all configurable
- File lock serializes concurrent invocations
Testing:
- 16 Bun unit tests across parser, cache, validator
- Path-filtered CI workflow at .github/workflows/codex-imagegen-tests.yml
- Composes with existing test.yml without conflicts
Architecture:
- scripts/codex-imagegen.sh: thin bash entrypoint (bun → npx -y bun fallback)
- scripts/codex-imagegen/: TypeScript module
- main.ts (orchestrator), types.ts (CliOptions/GenerateResult/GenError),
spawn.ts (child_process), parser.ts (JSONL events), validator.ts
(image_gen check + PNG magic), cache.ts (sha256 cache + FileLock),
logger.ts (JSONL structured logger)
Trade-offs documented in docs/codex-imagegen-backend.md:
- 5-10x slower than direct OpenAI API (or near-free on cache hit)
- ToS gray area: image_gen is documented for interactive use; non-
interactive invocation via codex exec is not explicitly addressed.
Suitable for personal low-volume use; users are responsible for
ensuring their usage complies with applicable terms of service.
56 lines
2.0 KiB
TypeScript
56 lines
2.0 KiB
TypeScript
import { stat, readdir } from "node:fs/promises";
|
|
import { homedir } from "node:os";
|
|
import path from "node:path";
|
|
import { GenError } from "./types.ts";
|
|
import type { ToolCall } from "./types.ts";
|
|
|
|
const PNG_MAGIC = Buffer.from([0x89, 0x50, 0x4e, 0x47, 0x0d, 0x0a, 0x1a, 0x0a]);
|
|
|
|
export function codexHome(): string {
|
|
return process.env.CODEX_HOME ?? path.join(homedir(), ".codex");
|
|
}
|
|
|
|
export async function verifyImageGenWasInvoked(threadId: string | null): Promise<{ ok: boolean; reason?: string }> {
|
|
if (!threadId) return { ok: false, reason: "no thread id" };
|
|
const dir = path.join(codexHome(), "generated_images", threadId);
|
|
try {
|
|
const entries = await readdir(dir);
|
|
const pngs = entries.filter((e) => e.toLowerCase().endsWith(".png"));
|
|
if (pngs.length === 0) return { ok: false, reason: `no PNG in ${dir}` };
|
|
return { ok: true };
|
|
} catch (e: any) {
|
|
return { ok: false, reason: `cannot read ${dir}: ${e?.code ?? e?.message}` };
|
|
}
|
|
}
|
|
|
|
export function findCpToTarget(toolCalls: ToolCall[], target: string): boolean {
|
|
return toolCalls.some(
|
|
(tc) =>
|
|
tc.tool === "shell" &&
|
|
typeof tc.command === "string" &&
|
|
(tc.command.includes(target) || tc.command.includes(path.basename(target))) &&
|
|
/\b(cp|mv|cat)\b/.test(tc.command) &&
|
|
tc.command.includes("generated_images"),
|
|
);
|
|
}
|
|
|
|
export async function verifyOutput(outputPath: string): Promise<{ bytes: number }> {
|
|
let s;
|
|
try {
|
|
s = await stat(outputPath);
|
|
} catch {
|
|
throw new GenError("output_missing", `Output file not created: ${outputPath}`);
|
|
}
|
|
if (s.size < 1000) {
|
|
throw new GenError("invalid_png", `Output file too small (${s.size} bytes)`);
|
|
}
|
|
const file = Bun.file(outputPath);
|
|
const head = new Uint8Array(await file.slice(0, 8).arrayBuffer());
|
|
for (let i = 0; i < PNG_MAGIC.length; i++) {
|
|
if (head[i] !== PNG_MAGIC[i]) {
|
|
throw new GenError("invalid_png", `Output is not a valid PNG (magic mismatch)`);
|
|
}
|
|
}
|
|
return { bytes: s.size };
|
|
}
|