@gobing-ai/knowledge-kit 0.0.12 → 0.0.14

package/plugins/generations/image-gen/src/providers/seedream.ts

@@ -0,0 +1,128 @@
+import { Buffer } from 'node:buffer';
+import { readBytes } from '../bytes';
+import type { ImageProvider, ImageRequest, ImageResult, ProviderFactory, ProviderOptions } from './types';
+
+/**
+ * Seedream adapter (0107 R2) — the first wire-speaking 0103 adapter.
+ * Wire prior art: vendors/baoyu-skills/skills/baoyu-image-gen/scripts/providers/seedream.ts
+ * (MIT © 2026 Jim Liu). POST `{base}/images/generations`, Bearer ARK_API_KEY.
+ */
+
+const DEFAULT_BASE_URL = 'https://ark.cn-beijing.volces.com/api/v3';
+const DEFAULT_MODEL = 'doubao-seedream-5-0-260128';
+const REF_MODEL_FRAGMENTS = ['doubao-seedream-5-0', 'doubao-seedream-4-5-', 'doubao-seedream-4-0-'];
+
+interface SeedreamResponse {
+    data?: Array<{ url?: string; b64_json?: string; error?: { code?: string; message?: string } }>;
+    error?: { code?: string; message?: string };
+}
+
+/** ARK `size`: explicit pixels win; the aspect ratio rides verbatim (seedream 4.x accepts '21:9'); else 2K. */
+export function mapSize(req: ImageRequest): string {
+    if (req.width !== undefined && req.height !== undefined) {
+        return `${req.width}x${req.height}`;
+    }
+    if (req.aspectRatio !== undefined) {
+        return req.aspectRatio;
+    }
+    return '2K';
+}
+
+export function extensionFromUrl(url: string): string {
+    // data.b64_json path carries no extension — default png; URL paths end ?sig=… so take the last clean segment.
+    const match = /(?:png|jpe?g|webp)/i.exec(url.split('?')[0] ?? '');
+    return match === null ? 'jpg' : match[0].toLowerCase().replace(/^jpeg$/, 'jpg');
+}
+
+export const createSeedream: ProviderFactory = (options?: ProviderOptions): ImageProvider => {
+    const fetchFn = options?.fetch ?? fetch;
+    const env = options?.env ?? process.env;
+    const readEnv = (key: string): string => env[key] ?? '';
+    const supportsRef = (model: string): boolean => REF_MODEL_FRAGMENTS.some((fragment) => model.includes(fragment));
+
+    return {
+        name: 'seedream',
+        defaultModel: () => DEFAULT_MODEL,
+        isAvailable: () => readEnv('ARK_API_KEY') !== '',
+        supportsReferenceImages: supportsRef,
+        validate(req: ImageRequest): void {
+            if (req.referenceImages !== undefined && req.referenceImages.length > 0 && !supportsRef(req.model)) {
+                throw new Error(
+                    `seedream model '${req.model}' does not accept reference images; use a doubao-seedream 4.x+ model`,
+                );
+            }
+        },
+        async generate(req: ImageRequest): Promise<ImageResult> {
+            const apiKey = readEnv('ARK_API_KEY');
+            if (apiKey === '') {
+                throw new Error("Provider 'seedream' requires ARK_API_KEY");
+            }
+            const base = readEnv('SEEDREAM_BASE_URL') || DEFAULT_BASE_URL;
+            const body: Record<string, unknown> = {
+                model: req.model,
+                prompt: req.prompt,
+                size: mapSize(req),
+                response_format: 'url',
+                watermark: false,
+            };
+            if (req.referenceImages !== undefined && req.referenceImages.length > 0) {
+                // Local paths cannot ride the wire: lift each to a base64 data URI.
+                const lifted = await Promise.all(
+                    req.referenceImages.map(async (path) => {
+                        const bytes = await readBytes(path);
+                        return `data:image/png;base64,${Buffer.from(bytes).toString('base64')}`;
+                    }),
+                );
+                body.image = lifted.length === 1 ? lifted[0] : lifted;
+                body.response_format = 'b64_json';
+            }
+            const resp = await fetchFn(`${base}/images/generations`, {
+                method: 'POST',
+                headers: { authorization: `Bearer ${apiKey}`, 'content-type': 'application/json' },
+                body: JSON.stringify(body),
+            });
+            const text = await resp.text();
+            if (!resp.ok) {
+                throw new Error(`seedream HTTP ${resp.status}: ${text.slice(0, 200)}`);
+            }
+            let parsed: SeedreamResponse;
+            try {
+                parsed = JSON.parse(text) as SeedreamResponse;
+            } catch {
+                throw new Error(`seedream returned non-JSON: ${text.slice(0, 120)}`);
+            }
+            const image = parsed.data?.[0];
+            if (parsed.error !== undefined) {
+                throw new Error(`seedream error ${parsed.error.code ?? ''}: ${parsed.error.message ?? ''}`);
+            }
+            if (image === undefined) {
+                throw new Error('seedream returned no image data');
+            }
+            if (image.b64_json !== undefined) {
+                return {
+                    bytes: Uint8Array.from(Buffer.from(image.b64_json, 'base64')),
+                    extension: 'png',
+                    provider: 'seedream',
+                    model: req.model,
+                };
+            }
+            if (image.url !== undefined) {
+                const r = await fetchFn(image.url);
+                if (!r.ok) {
+                    throw new Error(`seedream fetch URL HTTP ${r.status}`);
+                }
+                return {
+                    bytes: new Uint8Array(await r.arrayBuffer()),
+                    extension: extensionFromUrl(image.url),
+                    provider: 'seedream',
+                    model: req.model,
+                };
+            }
+            throw new Error(
+                image.error === undefined
+                    ? 'seedream returned neither url nor b64_json'
+                    : `seedream image error ${image.error.code ?? ''}: ${image.error.message ?? ''}`,
+            );
+        },
+    };
+};

package/plugins/generations/image-gen/src/providers/types.ts

@@ -0,0 +1,286 @@
+/**
+ * Task 0103 — the frozen `ImageProvider` contract: 0104 codes against it and the 12
+ * baoyu-derived adapters implement it. Wire-speaking adapters are later tickets; this
+ * file carries only the request/result types, the registry, and the selection order.
+ *
+ * Prior art: vendors/baoyu-skills/skills/baoyu-image-gen/scripts/ (MIT © 2026 Jim Liu).
+ * The deliberate differences from baoyu's `ProviderModule` (scripts/main.ts:15-20) —
+ * `ImageRequest` replaces `CliArgs`, `isAvailable()` and `supportsReferenceImages(model)`
+ * are new, `ImageResult` wraps the bytes — are recorded in the task Design.
+ */
+
+import { createAgnes } from './agnes';
+import { createAzure } from './azure';
+import { createCodexCli } from './codex-cli';
+import { createDashscope } from './dashscope';
+import { createGoogle } from './google';
+import { createHuggingface } from './huggingface';
+import { createJimeng } from './jimeng';
+import { createMinimax } from './minimax';
+import { createOpenai } from './openai';
+import { createOpenrouter } from './openrouter';
+import { createReplicate } from './replicate';
+import { createSeedream } from './seedream';
+import { createZai } from './zai';
+
+/** The two quality levels baoyu exposes (SKILL.md); every provider maps or ignores them. */
+export type ImageQuality = 'normal' | '2k';
+
+/** One generation request; a non-empty `referenceImages` means image-to-image (0105). */
+export interface ImageRequest {
+    prompt: string;
+    model: string;
+    /** e.g. '21:9' — from FormatPreset.aspectRatio (0102). */
+    aspectRatio?: string;
+    /** Optional exact pixels; providers that only take an aspect ratio ignore them. */
+    width?: number;
+    height?: number;
+    quality?: ImageQuality;
+    /** From StylePreset.negative (0102); providers without negative prompts ignore it. */
+    negative?: string;
+    /** Absolute paths; empty or undefined = text-to-image. */
+    referenceImages?: string[];
+    /** Default 1. v1 rule: a caller wanting N images issues N calls; adapters return the first. */
+    n?: number;
+}
+
+/** Adapters return bytes, never paths — 0104 owns file naming and writing. */
+export interface ImageResult {
+    bytes: Uint8Array;
+    /** 'png' | 'jpg' | 'webp' — the provider decides. */
+    extension: string;
+    provider: string;
+    model: string;
+}
+
+export interface ImageProvider {
+    readonly name: string;
+    defaultModel(): string;
+    /**
+     * Env-presence readiness — MUST NOT perform network or subprocess calls. A stale
+     * key still passes; it surfaces as the adapter's own auth error at generate()
+     * time, matching baoyu's throw-at-call-time behaviour (task Q&A, closed).
+     */
+    isAvailable(): boolean;
+    /** Queryable ref-image capability; 0105 routes `--ref` work on this fact. */
+    supportsReferenceImages(model: string): boolean;
+    /** Throw on an impossible combination (e.g. Imagen + referenceImages) before spending money. */
+    validate?(req: ImageRequest): void;
+    generate(req: ImageRequest): Promise<ImageResult>;
+}
+
+/** Injection seam for tests — mirrors `VoiceboxClientOptions.fetch` (voice-gen). */
+export interface ProviderOptions {
+    fetch?: typeof fetch;
+    /** Environment consulted instead of process.env (tests). */
+    env?: Record<string, string | undefined>;
+}
+
+export type ProviderFactory = (options?: ProviderOptions) => ImageProvider;
+
+/** Env var consulted for the provider name when no explicit request is passed (selection step 2). */
+const IMAGE_GEN_PROVIDER_ENV = 'IMAGE_GEN_PROVIDER';
+
+/** Providers that may never be auto-selected, even if listed in AUTO_ORDER later (task 0103 R3). */
+const NEVER_AUTO: ReadonlySet<string> = new Set(['codex-cli']);
+
+/** Registry row: the availability facts an adapter must honour, verbatim from its baoyu source. */
+interface ProviderSpec {
+    readonly name: string;
+    /** Env vars where any one present = usable (google's `A || B` fallback chains). */
+    readonly env: readonly string[];
+    /** Env vars where every one must be present (jimeng's access/secret key pair). */
+    readonly envAll?: readonly string[];
+    readonly defaultModel: string;
+    /** Model fragments that accept reference images; omit = every model does; empty = none. */
+    readonly refModels?: readonly string[];
+    /** Replaces the missing-credential text when readiness is not an env var (codex-cli). */
+    readonly note?: string;
+}
+
+type ProviderRegistration = ProviderSpec & { readonly create: ProviderFactory };
+
+/** The 12 baoyu adapters, one row each (task 0103 R1 inventory). Keys sorted alphabetically. */
+export const PROVIDERS: Readonly<Record<string, ProviderRegistration>> = {
+    agnes: {
+        name: 'agnes',
+        env: ['AGNES_API_KEY'],
+        defaultModel: 'agnes-image-2.1-flash',
+        create: createAgnes,
+    },
+    azure: {
+        name: 'azure',
+        env: ['AZURE_OPENAI_API_KEY'],
+        defaultModel: 'gpt-image-2',
+        create: createAzure,
+    },
+    'codex-cli': {
+        name: 'codex-cli',
+        env: [],
+        defaultModel: 'codex-image-gen',
+        note: "requires the 'codex' CLI on PATH with an active login (never auto-selected)",
+        create: createCodexCli,
+    },
+    dashscope: {
+        name: 'dashscope',
+        env: ['DASHSCOPE_API_KEY'],
+        defaultModel: 'qwen-image-2.0-pro',
+        refModels: ['wan2.7'],
+        create: createDashscope,
+    },
+    google: {
+        name: 'google',
+        env: ['GOOGLE_API_KEY', 'GEMINI_API_KEY'],
+        defaultModel: 'gemini-3-pro-image',
+        refModels: [
+            'gemini-3-pro-image',
+            'gemini-3.1-flash-image',
+            'gemini-3-pro-image-preview',
+            'gemini-3-flash-preview',
+            'gemini-3.1-flash-image-preview',
+        ],
+        create: createGoogle,
+    },
+    huggingface: {
+        name: 'huggingface',
+        env: ['HUGGINGFACE_API_TOKEN'],
+        defaultModel: 'stabilityai/stable-diffusion-xl-base-1.0',
+        create: createHuggingface,
+    },
+    jimeng: {
+        name: 'jimeng',
+        env: [],
+        envAll: ['JIMENG_ACCESS_KEY_ID', 'JIMENG_SECRET_ACCESS_KEY'],
+        defaultModel: 'jimeng_t2i_v40',
+        create: createJimeng,
+    },
+    minimax: {
+        name: 'minimax',
+        env: ['MINIMAX_API_KEY'],
+        defaultModel: 'image-01',
+        create: createMinimax,
+    },
+    openai: {
+        name: 'openai',
+        env: ['OPENAI_API_KEY'],
+        defaultModel: 'gpt-image-2',
+        refModels: ['gpt-image'],
+        create: createOpenai,
+    },
+    openrouter: {
+        name: 'openrouter',
+        env: ['OPENROUTER_API_KEY'],
+        defaultModel: 'google/gemini-3.1-flash-image',
+        create: createOpenrouter,
+    },
+    replicate: {
+        name: 'replicate',
+        env: ['REPLICATE_API_TOKEN'],
+        defaultModel: 'google/nano-banana-2',
+        create: createReplicate,
+    },
+    seedream: {
+        name: 'seedream',
+        env: ['ARK_API_KEY'],
+        defaultModel: 'doubao-seedream-5-0-260128',
+        refModels: ['doubao-seedream-5-0', 'doubao-seedream-4-5-', 'doubao-seedream-4-0-'],
+        // 0107: the first wire-speaking adapter — replaces the envOnly shell.
+        create: createSeedream,
+    },
+    zai: {
+        name: 'zai',
+        env: ['ZAI_API_KEY', 'BIGMODEL_API_KEY'],
+        defaultModel: 'glm-image',
+        refModels: [],
+        create: createZai,
+    },
+};
+
+/** Frozen auto-selection priority (task 0103 Design). `codex-cli` is absent on purpose. */
+export const AUTO_ORDER = [
+    'huggingface',
+    'google',
+    'openai',
+    'replicate',
+    'openrouter',
+    'dashscope',
+    'seedream',
+    'zai',
+    'minimax',
+    'jimeng',
+    'azure',
+    'agnes',
+] as const;
+
+/** Human-readable readiness requirement for one registry row. */
+function envSummary(reg: ProviderRegistration): string {
+    if (reg.note !== undefined) {
+        return reg.note;
+    }
+    // env entries are any-of alternatives (' or '); envAll entries are all-required (' and ');
+    // the two groups are both required when present (' and ' across groups).
+    const groups: string[] = [];
+    if (reg.env.length > 0) groups.push(reg.env.join(' or '));
+    if (reg.envAll !== undefined && reg.envAll.length > 0) groups.push(reg.envAll.join(' and '));
+    return groups.join(' and ');
+}
+
+function notConfiguredMessage(reg: ProviderRegistration): string {
+    if (reg.note !== undefined) {
+        return `Provider '${reg.name}' is not available: ${reg.note}`;
+    }
+    return `Provider '${reg.name}' is not configured: missing ${envSummary(reg)} (set it in plugins.generations.image-gen.env or process.env)`;
+}
+
+/**
+ * Resolve which provider name a generation job uses. First match wins:
+ * 1. `requested` — an explicit name from the job input; unknown throws listing all 12
+ *    valid names, known-but-unconfigured throws naming the missing env var (no silent
+ *    downgrade: that would change what the operator paid for).
+ * 2. `IMAGE_GEN_PROVIDER` in the environment, same two failure rules.
+ * 3. The first name in AUTO_ORDER whose provider `isAvailable()`.
+ * 4. Nothing available → throw listing every provider with what each one needs.
+ */
+export function selectProvider(
+    requested?: string,
+    options?: {
+        /** Environment consulted instead of process.env (tests). */
+        env?: Record<string, string | undefined>;
+        /** Availability override; default asks the registered provider's isAvailable(). */
+        isAvailable?: (name: string) => boolean;
+    },
+): string {
+    const env = options?.env ?? process.env;
+    const available =
+        options?.isAvailable ??
+        ((name: string): boolean => {
+            const reg = PROVIDERS[name];
+            return reg?.create({ env }).isAvailable() ?? false;
+        });
+    const names = Object.keys(PROVIDERS).sort();
+
+    const explicit = requested ?? env[IMAGE_GEN_PROVIDER_ENV];
+    if (explicit !== undefined && explicit !== '') {
+        const reg = PROVIDERS[explicit];
+        if (reg === undefined) {
+            throw new Error(`Unknown image provider '${explicit}'. Valid providers: ${names.join(', ')}`);
+        }
+        if (!available(reg.name)) {
+            throw new Error(notConfiguredMessage(reg));
+        }
+        return reg.name;
+    }
+
+    for (const name of AUTO_ORDER) {
+        if (!NEVER_AUTO.has(name) && available(name)) {
+            return name;
+        }
+    }
+    const wanted = names
+        .map((name) => {
+            const reg = PROVIDERS[name];
+            return reg === undefined ? name : `${name}: ${envSummary(reg)}`;
+        })
+        .join('; ');
+    throw new Error(`No image provider is configured. Credentials wanted — ${wanted}`);
+}

package/plugins/generations/image-gen/src/providers/zai.ts

@@ -0,0 +1,237 @@
+import type { ImageProvider, ImageRequest, ImageResult, ProviderFactory, ProviderOptions } from './types';
+
+/**
+ * Z.AI GLM-image adapter (0115 R1) — port of
+ * vendors/baoyu-skills/skills/baoyu-image-gen/scripts/providers/zai.ts
+ * (MIT © 2026 Jim Liu). Text-to-image only; `CliArgs.size` becomes width/height.
+ */
+
+type ZaiModelFamily = 'glm' | 'legacy';
+
+const GLM_MAX_PIXELS = 2 ** 22;
+const LEGACY_MAX_PIXELS = 2 ** 21;
+const GLM_SIZE_STEP = 32;
+const LEGACY_SIZE_STEP = 16;
+
+const GLM_RECOMMENDED_SIZES: Record<string, string> = {
+    '1:1': '1280x1280',
+    '3:2': '1568x1056',
+    '2:3': '1056x1568',
+    '4:3': '1472x1088',
+    '3:4': '1088x1472',
+    '16:9': '1728x960',
+    '9:16': '960x1728',
+};
+
+const LEGACY_RECOMMENDED_SIZES: Record<string, string> = {
+    '1:1': '1024x1024',
+    '9:16': '768x1344',
+    '3:4': '864x1152',
+    '16:9': '1344x768',
+    '4:3': '1152x864',
+    '2:1': '1440x720',
+    '1:2': '720x1440',
+};
+
+export function buildZaiUrl(base: string): string {
+    const cleaned = base.replace(/\/+$/g, '');
+    if (cleaned.endsWith('/images/generations')) return cleaned;
+    if (cleaned.endsWith('/api/paas/v4') || cleaned.endsWith('/v4')) return `${cleaned}/images/generations`;
+    return `${cleaned}/api/paas/v4/images/generations`;
+}
+
+export function getModelFamily(model: string): ZaiModelFamily {
+    return model.trim().toLowerCase() === 'glm-image' ? 'glm' : 'legacy';
+}
+
+export function parseAspectRatio(ar: string): { width: number; height: number } | null {
+    const match = ar.match(/^(\d+(?:\.\d+)?):(\d+(?:\.\d+)?)$/);
+    if (match === null) return null;
+    const width = Number(match[1]);
+    const height = Number(match[2]);
+    if (!Number.isFinite(width) || !Number.isFinite(height) || width <= 0 || height <= 0) return null;
+    return { width, height };
+}
+
+export function parseSize(size: string): { width: number; height: number } | null {
+    const match = size.trim().match(/^(\d+)\s*[xX*]\s*(\d+)$/);
+    if (match === null) return null;
+    const width = Number.parseInt(match[1] as string, 10);
+    const height = Number.parseInt(match[2] as string, 10);
+    if (!Number.isFinite(width) || !Number.isFinite(height) || width <= 0 || height <= 0) return null;
+    return { width, height };
+}
+
+function roundToStep(value: number, step: number): number {
+    return Math.max(step, Math.round(value / step) * step);
+}
+
+const DEFAULT_MODEL = 'glm-image';
+
+function getRatioValue(ar: string): number | null {
+    const parsed = parseAspectRatio(ar);
+    return parsed === null ? null : parsed.width / parsed.height;
+}
+
+function findClosestRatioKey(ar: string, candidates: string[]): string | null {
+    const targetRatio = getRatioValue(ar);
+    if (targetRatio === null) return null;
+    let bestKey: string | null = null;
+    let bestDiff = Number.POSITIVE_INFINITY;
+    for (const candidate of candidates) {
+        const candidateRatio = getRatioValue(candidate);
+        if (candidateRatio === null) continue;
+        const diff = Math.abs(candidateRatio - targetRatio);
+        if (diff < bestDiff) {
+            bestDiff = diff;
+            bestKey = candidate;
+        }
+    }
+    return bestDiff <= 0.05 ? bestKey : null;
+}
+
+function fitToPixelBudget(
+    width: number,
+    height: number,
+    targetPixels: number,
+    maxPixels: number,
+    step: number,
+): { width: number; height: number } {
+    let nextWidth = width;
+    let nextHeight = height;
+    const pixels = nextWidth * nextHeight;
+    const scaleTo = pixels > maxPixels ? maxPixels : targetPixels;
+    const scale = Math.sqrt(scaleTo / pixels);
+    nextWidth *= scale;
+    nextHeight *= scale;
+
+    let roundedWidth = roundToStep(nextWidth, step);
+    let roundedHeight = roundToStep(nextHeight, step);
+    let roundedPixels = roundedWidth * roundedHeight;
+    while (roundedPixels > maxPixels && (roundedWidth > step || roundedHeight > step)) {
+        if (roundedWidth >= roundedHeight && roundedWidth > step) {
+            roundedWidth -= step;
+        } else if (roundedHeight > step) {
+            roundedHeight -= step;
+        } else {
+            break;
+        }
+        roundedPixels = roundedWidth * roundedHeight;
+    }
+    return { width: roundedWidth, height: roundedHeight };
+}
+
+export function resolveSizeForModel(
+    model: string,
+    args: { size: string | undefined; aspectRatio: string | undefined; quality: 'normal' | '2k' | undefined },
+): string {
+    const family = getModelFamily(model);
+    if (args.size !== undefined) {
+        const parsed = parseSize(args.size);
+        if (parsed === null) throw new Error('Z.AI --size must be in WxH format, for example 1280x1280.');
+        const widthStep = family === 'glm' ? GLM_SIZE_STEP : LEGACY_SIZE_STEP;
+        const minEdge = family === 'glm' ? 1024 : 512;
+        const maxPixels = family === 'glm' ? GLM_MAX_PIXELS : LEGACY_MAX_PIXELS;
+        if (parsed.width < minEdge || parsed.width > 2048 || parsed.height < minEdge || parsed.height > 2048) {
+            throw new Error(
+                family === 'glm'
+                    ? 'GLM-image custom size requires width and height between 1024 and 2048.'
+                    : 'Z.AI legacy image models require width and height between 512 and 2048.',
+            );
+        }
+        if (parsed.width % widthStep !== 0 || parsed.height % widthStep !== 0) {
+            throw new Error(
+                family === 'glm'
+                    ? 'GLM-image custom size requires width and height divisible by 32.'
+                    : 'Z.AI legacy image models require width and height divisible by 16.',
+            );
+        }
+        if (parsed.width * parsed.height > maxPixels) {
+            throw new Error(
+                family === 'glm'
+                    ? 'GLM-image custom size must not exceed 2^22 total pixels.'
+                    : 'Z.AI legacy image size must not exceed 2^21 total pixels.',
+            );
+        }
+        return `${parsed.width}x${parsed.height}`;
+    }
+
+    const recommended = family === 'glm' ? GLM_RECOMMENDED_SIZES : LEGACY_RECOMMENDED_SIZES;
+    const defaultSize = family === 'glm' ? '1280x1280' : '1024x1024';
+    if (args.aspectRatio === undefined) return defaultSize;
+
+    const recommendedRatio = findClosestRatioKey(args.aspectRatio, Object.keys(recommended));
+    if (recommendedRatio !== null) {
+        return recommended[recommendedRatio] as string;
+    }
+    const parsedRatio = parseAspectRatio(args.aspectRatio);
+    if (parsedRatio === null) return defaultSize;
+
+    const targetPixels = args.quality === 'normal' ? 1024 * 1024 : 1536 * 1536;
+    const maxPixels = family === 'glm' ? GLM_MAX_PIXELS : LEGACY_MAX_PIXELS;
+    const step = family === 'glm' ? GLM_SIZE_STEP : LEGACY_SIZE_STEP;
+    const fit = fitToPixelBudget(parsedRatio.width, parsedRatio.height, targetPixels, maxPixels, step);
+    return `${fit.width}x${fit.height}`;
+}
+
+interface ZaiResponse {
+    data?: Array<{ url?: string }>;
+}
+
+export const createZai: ProviderFactory = (options?: ProviderOptions): ImageProvider => {
+    const fetchFn = options?.fetch ?? fetch;
+    const env = options?.env ?? process.env;
+    const readEnv = (key: string): string => env[key] ?? '';
+
+    return {
+        name: 'zai',
+        defaultModel: () => DEFAULT_MODEL,
+        isAvailable: () => (readEnv('ZAI_API_KEY') || readEnv('BIGMODEL_API_KEY')) !== '',
+        supportsReferenceImages: () => false,
+        validate(req: ImageRequest): void {
+            if ((req.referenceImages?.length ?? 0) > 0) {
+                throw new Error(
+                    'Z.AI GLM-image currently supports text-to-image only in kk image-gen. Remove --ref or choose another provider.',
+                );
+            }
+        },
+        async generate(req: ImageRequest): Promise<ImageResult> {
+            const refs = req.referenceImages ?? [];
+            if (refs.length > 0) {
+                throw new Error(
+                    'Z.AI GLM-image currently supports text-to-image only in kk image-gen. Remove --ref or choose another provider.',
+                );
+            }
+            const apiKey = readEnv('ZAI_API_KEY') || readEnv('BIGMODEL_API_KEY');
+            if (apiKey === '') throw new Error('ZAI_API_KEY is required. Get one from https://docs.z.ai/.');
+
+            const size = resolveSizeForModel(req.model, {
+                size: req.width !== undefined && req.height !== undefined ? `${req.width}x${req.height}` : undefined,
+                aspectRatio: req.aspectRatio,
+                quality: req.quality,
+            });
+            const base = readEnv('ZAI_BASE_URL') || readEnv('BIGMODEL_BASE_URL') || 'https://api.z.ai/api/paas/v4';
+            const response = await fetchFn(buildZaiUrl(base), {
+                method: 'POST',
+                headers: { 'content-type': 'application/json', authorization: `Bearer ${apiKey}` },
+                body: JSON.stringify({
+                    model: req.model,
+                    prompt: req.prompt,
+                    quality: req.quality === 'normal' ? 'standard' : 'hd',
+                    size,
+                }),
+            });
+            if (!response.ok) throw new Error(`Z.AI API error (${response.status}): ${await response.text()}`);
+            const url = ((await response.json()) as ZaiResponse).data?.[0]?.url;
+            if (url === undefined) throw new Error('No image URL in Z.AI response');
+            const imageResponse = await fetchFn(url);
+            if (!imageResponse.ok) throw new Error(`Failed to download image from Z.AI: ${imageResponse.status}`);
+            return {
+                bytes: new Uint8Array(await imageResponse.arrayBuffer()),
+                extension: 'png',
+                provider: 'zai',
+                model: req.model,
+            };
+        },
+    };
+};

package/plugins/generations/image-gen/tsconfig.json

@@ -0,0 +1,8 @@
+{
+    "extends": "../../../tooling/typescript/base.json",
+    "compilerOptions": {
+        "rootDir": "./src",
+        "outDir": "./dist"
+    },
+    "include": ["src/**/*"]
+}