Skip to content

armgit / cindy

Public Imported from GitHub
0

Consider it done. The open-source AI agent that works out of the box · 想到,就能做到。开源、开箱即用的 AI Agent。

fix(media): preserve native image options and save large base64 results (#4693)

Chris Zhanga1f677a49013
diff --git a/apps/desktop/src/main/cindy-brain/__tests__/codexImageClient.test.ts b/apps/desktop/src/main/cindy-brain/__tests__/codexImageClient.test.ts
index d226a9d8e4..dcc3e49a7c 100644
--- a/apps/desktop/src/main/cindy-brain/__tests__/codexImageClient.test.ts
+++ b/apps/desktop/src/main/cindy-brain/__tests__/codexImageClient.test.ts
@@ -48,7 +48,7 @@ describe('codexImageClient', () => {
await channel.generateImage({ model: 'openai-account-a/gpt-image-2', prompt: 'p' });
expect(JSON.parse(String(doFetch.mock.calls[0]?.[1]?.body)).tools[0].model).toBe('gpt-image-2');
expect(doFetch.mock.calls[0]?.[1]?.headers).toMatchObject({ Authorization: 'Bearer account-a-token', 'ChatGPT-Account-Id': 'account-a' });
- await expect(channel.generateImage({ model: 'openai/gpt-image-2', prompt: 'p' })).rejects.toThrow();
+ await expect(channel.generateImage({ model: 'openai/gpt-image-2', prompt: 'p' })).rejects.toThrow('不支持模型');
expect(doFetch).toHaveBeenCalledTimes(1);
});
it('用 Codex OAuth hosted image_generation tool 生成 gpt-image-2', async () => {
@@ -65,6 +65,7 @@ describe('codexImageClient', () => {
model: 'openai/gpt-image-2',
prompt: '一只猫',
aspectRatio: '3:2',
+ quality: 'medium',
});
expect(result.data[0]?.b64_json).toBe('aW1hZ2U=');
@@ -86,6 +87,22 @@ describe('codexImageClient', () => {
expect(body.tool_choice).toBeUndefined();
});
+ it('forwards custom dimensions and highest quality without downgrading', async () => {
+ const doFetch = vi.fn<typeof fetch>(async () => sseResponse([{ type: 'image_generation_call', result: 'final' }]));
+ await makeChannel(doFetch).generateImage({
+ model: 'openai/gpt-image-2.5-sunburst', prompt: 'wallpaper', size: '1760x3824', quality: 'max',
+ });
+ expect(JSON.parse(String(doFetch.mock.calls[0]?.[1]?.body)).tools[0]).toMatchObject({ size: '1760x3824', quality: 'max' });
+ await expect(makeChannel(doFetch).generateImage({ model: 'openai/gpt-image-2.5-sunburst', prompt: 'p', size: '1320x2868' })).rejects.toThrow('divisible by 16');
+ expect(doFetch).toHaveBeenCalledTimes(1);
+ });
+
+ it.each(['eof', 'response.failed', 'response.incomplete'])('never delivers a preview as a completed high-resolution image (%s)', async (ending) => {
+ const tail = ending === 'eof' ? [] : [{ type: ending }];
+ const channel = makeChannel(vi.fn<typeof fetch>(async () => sseResponse([{ partial_image_b64: 'preview' }, ...tail])));
+ await expect(channel.generateImage({ model: 'openai/gpt-image-2', prompt: 'p' })).rejects.toThrow(ending === 'eof' ? '没有图片' : 'did not complete');
+ });
+
it('未指定画幅时保留 auto 语义;拒绝目录外模型', async () => {
const doFetch = vi.fn<typeof fetch>(async () =>
sseResponse([{ type: 'image_generation_call', result: 'aW1hZ2U=' }]),
@@ -96,6 +113,7 @@ describe('codexImageClient', () => {
tools: Array<Record<string, unknown>>;
};
expect(body.tools[0]).not.toHaveProperty('size');
+ expect(body.tools[0]).not.toHaveProperty('quality');
await expect(
channel.generateImage({ model: 'another/future-image', prompt: 'p' }),
@@ -111,9 +129,9 @@ describe('codexImageClient', () => {
expect(beforeDispatch).toHaveBeenCalledWith('openai/future-image');
});
- it('保留流中最新 partial image;派发前重查可阻止出网', async () => {
+ it('只交付最终图片;派发前重查可阻止出网', async () => {
const doFetch = vi.fn<typeof fetch>(async () =>
- sseResponse([{ partial_image_b64: 'first' }, { partial_image_b64: 'final' }]),
+ sseResponse([{ partial_image_b64: 'first' }, { type: 'image_generation_call', result: 'final' }, { partial_image_b64: 'late-preview' }]),
);
const channel = makeChannel(doFetch);
expect(
@@ -157,7 +175,7 @@ describe('codexImageClient', () => {
it('兼容单 CR 的 SSE 事件与行结束符', async () => {
const body = [
'data: {bad json}\r\r',
- `data: ${JSON.stringify({ partial_image_b64: 'cr-only' })}\r\r`,
+ `data: ${JSON.stringify({ type: 'image_generation_call', result: 'cr-only' })}\r\r`,
'data: [DONE]\r\r',
].join('');
const channel = makeChannel(
diff --git a/apps/desktop/src/main/cindy-brain/__tests__/geminiImageClient.test.ts b/apps/desktop/src/main/cindy-brain/__tests__/geminiImageClient.test.ts
index 265956159f..4dbbad737d 100644
--- a/apps/desktop/src/main/cindy-brain/__tests__/geminiImageClient.test.ts
+++ b/apps/desktop/src/main/cindy-brain/__tests__/geminiImageClient.test.ts
@@ -5,6 +5,7 @@
*/
import { describe, expect, it, vi } from 'vitest';
+import fs from 'node:fs/promises';
import { createGeminiImageChannel } from '../geminiImageClient';
@@ -52,6 +53,27 @@ describe('geminiImageClient', () => {
expect(without.generationConfig).toEqual({ responseModalities: ['TEXT', 'IMAGE'] });
});
+ it('transmits 4K image size for generation and editing, preserving cancellation', async () => {
+ const doFetch = fetchMock();
+ const channel = createGeminiImageChannel({ getApiKey: () => 'test-key', fetchImplementation: doFetch as typeof fetch });
+ const signal = new AbortController().signal;
+ const readFile = vi.spyOn(fs, 'readFile').mockResolvedValue(Buffer.from('reference image'));
+ try {
+ for (const edit of [false, true]) {
+ const params = { model: 'gemini/gemini-3-pro-image', prompt: 'p', aspectRatio: '16:9', resolution: '4K', signal };
+ if (edit) await channel.editImage({ ...params, imagePaths: ['/test/reference.png'] });
+ else await channel.generateImage(params);
+ }
+ for (const [, init] of doFetch.mock.calls) {
+ expect(JSON.parse(String(init?.body)).generationConfig.imageConfig).toEqual({ aspectRatio: '16:9', imageSize: '4K' });
+ expect(init?.signal).toBe(signal);
+ }
+ expect(JSON.parse(String(doFetch.mock.calls[1]?.[1]?.body)).contents[0].parts[1].inlineData).toMatchObject({ mimeType: 'image/png' });
+ } finally {
+ readFile.mockRestore();
+ }
+ });
+
it('ready = key 已配置;null 或空白串均视为未配置(不出网)', async () => {
const doFetch = fetchMock();
for (const key of [null, '', ' ']) {
diff --git a/apps/desktop/src/main/cindy-brain/__tests__/xaiImageClient.test.ts b/apps/desktop/src/main/cindy-brain/__tests__/xaiImageClient.test.ts
index 5666d309a2..f429a43b9b 100644
--- a/apps/desktop/src/main/cindy-brain/__tests__/xaiImageClient.test.ts
+++ b/apps/desktop/src/main/cindy-brain/__tests__/xaiImageClient.test.ts
@@ -65,7 +65,7 @@ describe('xaiImageClient', () => {
const result = await channel(doFetch).generateImage({
model: 'xai/grok-imagine-image',
prompt: '一只猫',
- aspectRatio: '3:2',
+ aspectRatio: '3:2', resolution: '1k',
});
expect(result).toEqual({ data: [{ b64_json: 'aW1hZ2U=' }], output_format: 'jpeg' });
@@ -81,6 +81,15 @@ describe('xaiImageClient', () => {
});
});
+ it('transmits native 2K resolution and phone ratios without injecting defaults', async () => {
+ const doFetch = vi.fn<typeof fetch>(async () => new Response(JSON.stringify({ data: [{ b64_json: 'image' }] })));
+ const imageChannel = channel(doFetch);
+ await imageChannel.generateImage({ model: 'xai/grok-imagine-image', prompt: 'p', aspectRatio: '9:19.5', resolution: '2k' });
+ for (const [, init] of doFetch.mock.calls) expect(JSON.parse(String(init?.body))).toMatchObject({ aspect_ratio: '9:19.5', resolution: '2k' });
+ await imageChannel.generateImage({ model: 'xai/grok-imagine-image', prompt: 'p' });
+ expect(JSON.parse(String(doFetch.mock.calls[1]?.[1]?.body))).not.toHaveProperty('resolution');
+ });
+
it('直接转发类型发现得到的未来图片模型,不依赖型号名白名单', async () => {
const doFetch = vi.fn<typeof fetch>(
async () =>
@@ -121,12 +130,14 @@ describe('xaiImageClient', () => {
model: 'xai/grok-imagine-image-quality',
prompt: '合成一张图',
imagePaths: paths,
- aspectRatio: '2:3',
+ aspectRatio: '9:19.5',
+ resolution: '2k',
});
const [url, init] = doFetch.mock.calls[0]!;
expect(String(url)).toBe('https://api.x.ai/v1/images/edits');
const body = JSON.parse(String(init?.body)) as { images: Array<{ type: string; url: string }> };
+ expect(body).toMatchObject({ aspect_ratio: '9:19.5', resolution: '2k' });
expect(body.images).toHaveLength(2);
expect(body.images.every((image) => image.type === 'image_url')).toBe(true);
expect(body.images.every((image) => image.url.startsWith('data:image/png;base64,'))).toBe(true);
diff --git a/apps/desktop/src/main/cindy-brain/codexImageClient.ts b/apps/desktop/src/main/cindy-brain/codexImageClient.ts
index f51b89cc72..a8b6192185 100644
--- a/apps/desktop/src/main/cindy-brain/codexImageClient.ts
+++ b/apps/desktop/src/main/cindy-brain/codexImageClient.ts
@@ -10,6 +10,7 @@
import { randomUUID } from 'node:crypto';
import fs from 'node:fs/promises';
+import { normalizeImageParameters, type ImageParameters } from '../cindy-media/imageParameters.js';
import type { ImageChannel, ImageChannelResult } from './imageChannelRegistry.js';
import { mediaRequestParamsForLog, mediaRequestUrlForLog } from '../cindy-media/mediaRequestLog.js';
import { sniffMediaMime } from '../cindy-media/sniffMediaMime.js';
@@ -21,12 +22,6 @@ const USER_AGENT = `codex_cli_rs/cindy (${process.platform}; ${process.arch})`;
const SSE_EVENT_BOUNDARY = /(?:\r\n|\r|\n){2}/;
const SSE_LINE_ENDING = /\r\n|\r|\n/;
const log = createLogger('codex-image');
-const SIZE_BY_ASPECT = {
- '1:1': '1024x1024',
- '3:2': '1536x1024',
- '2:3': '1024x1536',
-} as const;
-
export interface CreateCodexImageChannelOptions {
providerId?: string;
hasOAuthLogin(): boolean;
@@ -52,7 +47,8 @@ function extractImageB64(value: unknown): string | null {
if (!value || typeof value !== 'object') return null;
const item = value as Record<string, unknown>;
if (item.type === 'image_generation_call' && typeof item.result === 'string') return item.result;
- if (typeof item.partial_image_b64 === 'string') return item.partial_image_b64;
+ // Preview frames are not final assets: never return one after a failed/truncated stream.
+ if (typeof item.partial_image_b64 === 'string') return null;
for (const child of Object.values(item)) {
const found = extractImageB64(child);
if (found) return found;
@@ -74,12 +70,18 @@ async function collectImageB64(response: Response): Promise<string | null> {
.map((line) => line.slice(5).trimStart())
.join('\n');
if (!data || data === '[DONE]') return;
+ let event: Record<string, unknown>;
try {
- const found = extractImageB64(JSON.parse(data) as unknown);
- if (found) latest = found;
+ event = JSON.parse(data) as Record<string, unknown>;
} catch {
- // SSE 允许夹杂未知事件;坏帧不能让后续合法图片结果一起丢失。
+ // Unknown/malformed SSE frames may precede a valid completed result.
+ return;
+ }
+ if (event?.type === 'error' || event?.type === 'response.failed' || event?.type === 'response.incomplete') {
+ throw new Error('Codex image generation did not complete; preview images are not final results');
}
+ const found = extractImageB64(event);
+ if (found) latest = found;
};
try {
@@ -99,6 +101,7 @@ async function collectImageB64(response: Response): Promise<string | null> {
}
}
} finally {
+ await reader.cancel().catch(() => undefined);
reader.releaseLock();
}
return latest;
@@ -140,13 +143,13 @@ async function httpError(
export function createCodexImageChannel(opts: CreateCodexImageChannelOptions): ImageChannel {
const doFetch = opts.fetchImplementation ?? fetch;
- async function generate(params: {
+ async function generate(params: ImageParameters & {
model: string;
prompt: string;
imagePaths?: string[];
- aspectRatio?: '1:1' | '3:2' | '2:3';
signal?: AbortSignal;
}): Promise<ImageChannelResult> {
+ const options = normalizeImageParameters('openai', params.model, params);
const modelPrefix = `${opts.providerId ?? 'openai'}/`;
if (!params.model.startsWith(modelPrefix) || !params.model.slice(modelPrefix.length).trim()) {
throw new Error(`Codex 图像通道不支持模型:${params.model}`);
@@ -177,8 +180,7 @@ export function createCodexImageChannel(opts: CreateCodexImageChannelOptions): I
{
type: 'image_generation',
model: params.model.slice(modelPrefix.length),
- ...(params.aspectRatio ? { size: SIZE_BY_ASPECT[params.aspectRatio] } : {}),
- quality: 'medium',
+ ...options,
output_format: 'png',
background: 'opaque',
partial_images: 1,
@@ -234,10 +236,9 @@ export function createCodexImageChannel(opts: CreateCodexImageChannelOptions): I
}
return {
+ imageProtocol: 'openai',
ready: opts.hasOAuthLogin,
- generateImage: ({ model, prompt, aspectRatio, signal }) =>
- generate({ model, prompt, aspectRatio, signal }),
- editImage: ({ model, prompt, imagePaths, aspectRatio, signal }) =>
- generate({ model, prompt, imagePaths, aspectRatio, signal }),
+ generateImage: generate,
+ editImage: generate,
};
}
diff --git a/apps/desktop/src/main/cindy-brain/geminiImageClient.ts b/apps/desktop/src/main/cindy-brain/geminiImageClient.ts
index d0a4fa4baf..7ab70e63c0 100644
--- a/apps/desktop/src/main/cindy-brain/geminiImageClient.ts
+++ b/apps/desktop/src/main/cindy-brain/geminiImageClient.ts
@@ -21,7 +21,7 @@
import fs from 'node:fs/promises';
import path from 'node:path';
-import type { GhostImageAspectRatio } from '../../shared/ghost.js';
+import { normalizeImageParameters, type ImageParameters } from '../cindy-media/imageParameters.js';
import type { ImageChannel, ImageChannelResult } from './imageChannelRegistry.js';
const GEMINI_API_BASE = 'https://generativelanguage.googleapis.com/v1beta';
@@ -120,12 +120,13 @@ export function createGeminiImageChannel(opts: CreateGeminiImageChannelOptions):
return key;
}
- async function callGenerateContent(params: {
+ async function callGenerateContent(params: ImageParameters & {
model: string;
prompt: string;
- aspectRatio?: GhostImageAspectRatio;
imagePaths?: string[];
+ signal?: AbortSignal;
}): Promise<ImageChannelResult> {
+ const options = normalizeImageParameters('gemini', params.model, params);
const apiKey = requireApiKey();
const upstream = upstreamModelId(params.model);
const parts: Array<Record<string, unknown>> = [{ text: params.prompt }];
@@ -139,7 +140,10 @@ export function createGeminiImageChannel(opts: CreateGeminiImageChannelOptions):
contents: [{ parts }],
generationConfig: {
responseModalities: ['TEXT', 'IMAGE'],
- ...(params.aspectRatio ? { imageConfig: { aspectRatio: params.aspectRatio } } : {}),
+ ...(options.aspectRatio || options.resolution ? { imageConfig: {
+ ...(options.aspectRatio ? { aspectRatio: options.aspectRatio } : {}),
+ ...(options.resolution ? { imageSize: options.resolution } : {}),
+ } } : {}),
},
};
// 停用轴派发前重查:参考图 fs.readFile 是 await,窗口内被停用即拒(同 gatewayImageClient)。
@@ -151,6 +155,7 @@ export function createGeminiImageChannel(opts: CreateGeminiImageChannelOptions):
'Content-Type': 'application/json',
},
body: JSON.stringify(body),
+ signal: params.signal,
});
if (!res.ok) await humanizeGeminiHttpError(res, params.model);
const parsed = (await res.json()) as GeminiGenerateContentResponse;
@@ -158,10 +163,9 @@ export function createGeminiImageChannel(opts: CreateGeminiImageChannelOptions):
}
return {
+ imageProtocol: 'gemini',
ready: () => (opts.getApiKey()?.trim() ?? '') !== '',
- generateImage: ({ model, prompt, aspectRatio }) =>
- callGenerateContent({ model, prompt, aspectRatio }),
- editImage: ({ model, prompt, imagePaths, aspectRatio }) =>
- callGenerateContent({ model, prompt, imagePaths, aspectRatio }),
+ generateImage: callGenerateContent,
+ editImage: callGenerateContent,
};
}
diff --git a/apps/desktop/src/main/cindy-brain/imageChannelRegistry.ts b/apps/desktop/src/main/cindy-brain/imageChannelRegistry.ts
index 208758d744..859dd9a7f8 100644
--- a/apps/desktop/src/main/cindy-brain/imageChannelRegistry.ts
+++ b/apps/desktop/src/main/cindy-brain/imageChannelRegistry.ts
@@ -18,7 +18,7 @@
* (规则 14),单测直测。
*/
-import type { GhostImageAspectRatio } from '../../shared/ghost.js';
+import type { ImageParameters, ImageProtocol } from '../cindy-media/imageParameters.js';
import { sniffMediaMime } from '../cindy-media/sniffMediaMime.js';
import { isLibraryBlobRelPath, isLibrarySidecarRelPath } from './librarySlot.js';
@@ -60,11 +60,10 @@ export function decodeImageResponse(res: ImageChannelResult): { buffer: Buffer;
}
/**
- * 单条图像执行通道。参数面收敛为「意识意图」级(aspectRatio 而非具体尺寸):
- * 意图 → 各家 wire 参数(gpt-image 的 size 枚举 / Gemini 的 imageConfig.aspectRatio)
- * 的翻译是通道自己的知识,不外泄给派发端。
+ * 图像执行通道保留尺寸、质量与分辨率;各通道按自身协议序列化。
*/
export interface ImageChannel {
+ imageProtocol?: ImageProtocol;
/** 执行凭证是否就绪。false ⇒ 该来源整段不进 cindy 白名单。 */
ready(): boolean;
/**
@@ -79,17 +78,15 @@ export interface ImageChannel {
* 改图派发路径在出网前早失效。
*/
supportsEdit?: boolean;
- generateImage(params: {
+ generateImage(params: ImageParameters & {
model: string;
prompt: string;
- aspectRatio?: GhostImageAspectRatio;
signal?: AbortSignal;
}): Promise<ImageChannelResult>;
- editImage(params: {
+ editImage(params: ImageParameters & {
model: string;
prompt: string;
imagePaths: string[];
- aspectRatio?: GhostImageAspectRatio;
signal?: AbortSignal;
}): Promise<ImageChannelResult>;
}
diff --git a/apps/desktop/src/main/cindy-brain/index.ts b/apps/desktop/src/main/cindy-brain/index.ts
index 51e28512aa..fd9d96f6ae 100644
--- a/apps/desktop/src/main/cindy-brain/index.ts
+++ b/apps/desktop/src/main/cindy-brain/index.ts
@@ -59,7 +59,6 @@ import {
isValidGhostId,
layoutWithGhostPanel,
type GhostHostNoticeKey,
- type GhostImageAspectRatio,
type GhostManifest,
type GhostCindyPreferenceResult,
type GhostMediaCapability,
@@ -425,6 +424,7 @@ import {
import { createXaiImageChannel } from './xaiImageClient.js';
import { getCindyProxyMediaService, getCindyVideoProviderRegistry } from '../mcp-integrations/cindyProxyMedia.js';
import { getCindyProxySearchService } from '../mcp-integrations/cindyProxySearch.js';
+import { normalizeImageParameters } from '../cindy-media/imageParameters.js';
import { ImageChannelRegistry, decodeImageResponse } from './imageChannelRegistry.js';
import { createGeminiImageChannel } from './geminiImageClient.js';
import { createCodexImageChannel } from './codexImageClient.js';
@@ -4067,17 +4067,6 @@ function getGhostImageCapabilities(
}
}
-/**
- * 意识画幅意图 → XD Gateway size。三档尺寸是 gpt-image 系的原生枚举
- * (1024x1024 / 1536x1024 / 1024x1536,比例即枚举名);Gemini 系由网关按
- * 比例转译。意识侧枚举扩值域时此表必须同步补齐(Record 穷尽性由类型锁住)。
- */
-const GHOST_ASPECT_TO_GATEWAY_SIZE: Record<GhostImageAspectRatio, string> = {
- '1:1': '1024x1024',
- '3:2': '1536x1024',
- '2:3': '1024x1536',
-};
-
/**
* 图像执行通道注册表单例(见 imageChannelRegistry.ts 头注)。xd 通道在此登记:
* ready 跟随网关能力(canUseCindyGateway;key 缺失时 requireApiKey 在派发时人话拒,
@@ -4091,21 +4080,20 @@ function getImageChannelRegistry(): ImageChannelRegistry {
if (!imageChannelRegistrySingleton) {
const registry = new ImageChannelRegistry();
registry.register('xd', {
+ imageProtocol: 'openai',
ready: () => getAppCapabilities().canUseCindyGateway,
- generateImage: ({ model, prompt, aspectRatio }) =>
+ generateImage: (params) =>
getCindyProxyMediaService().backend.generateImage({
- model,
- prompt,
- // 不带画幅意图时不传 size,网关缺省 'auto'(模型自定)。
- ...(aspectRatio ? { size: GHOST_ASPECT_TO_GATEWAY_SIZE[aspectRatio] } : {}),
+ model: params.model,
+ prompt: params.prompt,
+ ...normalizeImageParameters('openai', params.model, params),
}),
- editImage: ({ model, prompt, imagePaths, aspectRatio }) =>
+ editImage: (params) =>
getCindyProxyMediaService().backend.editImage({
- model,
- prompt,
- imagePaths,
- // 改图的 auto 语义 = 跟随源图画幅,与放开之前行为一致。
- ...(aspectRatio ? { size: GHOST_ASPECT_TO_GATEWAY_SIZE[aspectRatio] } : {}),
+ model: params.model,
+ prompt: params.prompt,
+ imagePaths: params.imagePaths,
+ ...normalizeImageParameters('openai', params.model, params),
}),
});
const readXaiApiImageKey = (): string | null => {
@@ -4197,6 +4185,7 @@ function getImageChannelRegistry(): ImageChannelRegistry {
beforeDispatch: (model) => assertMediaModelStillEnabled('image', model, 'openai'),
});
registry.register('openai', {
+ imageProtocol: 'openai',
// 用户明确配置 Platform key 时优先走确定性的 public Images API;否则复用
// 已连接的 ChatGPT/Codex 订阅 OAuth hosted tool,不要求再付一份 API 费。
ready: () => hasOpenaiPlatformKey() || codexImagesClient.ready(),
@@ -4206,9 +4195,7 @@ function getImageChannelRegistry(): ImageChannelRegistry {
{
model: stripOpenaiPrefix(params.model),
prompt: params.prompt,
- ...(params.aspectRatio
- ? { size: GHOST_ASPECT_TO_GATEWAY_SIZE[params.aspectRatio] }
- : {}),
+ ...normalizeImageParameters('openai', params.model, params),
},
params.signal,
)
@@ -4220,9 +4207,7 @@ function getImageChannelRegistry(): ImageChannelRegistry {
model: stripOpenaiPrefix(params.model),
prompt: params.prompt,
imagePaths: params.imagePaths,
- ...(params.aspectRatio
- ? { size: GHOST_ASPECT_TO_GATEWAY_SIZE[params.aspectRatio] }
- : {}),
+ ...normalizeImageParameters('openai', params.model, params),
},
params.signal,
)
@@ -4317,6 +4302,7 @@ function listLocalProviderMediaModels(respectDisplaySwitch = false) {
name: model.name,
providerId: provider.id,
mode: 'image_generation' as const,
+ imageProtocol: getImageChannelRegistry().resolve(provider.id).imageProtocol,
modalities: { input, output: [...modalities.output] },
...(model.officialDocs ? { officialDocs: model.officialDocs } : {}),
},
@@ -4394,13 +4380,13 @@ configureProviderMediaRuntime({
model: request.modelId,
prompt: request.prompt,
imagePaths: request.imagePaths,
- ...(request.aspectRatio ? { aspectRatio: request.aspectRatio } : {}),
+ ...normalizeImageParameters(channel.imageProtocol, request.modelId, request),
signal: request.signal,
})
: await channel.generateImage({
model: request.modelId,
prompt: request.prompt,
- ...(request.aspectRatio ? { aspectRatio: request.aspectRatio } : {}),
+ ...normalizeImageParameters(channel.imageProtocol, request.modelId, request),
signal: request.signal,
});
return decodeImageResponse(response);
diff --git a/apps/desktop/src/main/cindy-brain/xaiImageClient.ts b/apps/desktop/src/main/cindy-brain/xaiImageClient.ts
index 16549eaf6e..f88dbdafa7 100644
--- a/apps/desktop/src/main/cindy-brain/xaiImageClient.ts
+++ b/apps/desktop/src/main/cindy-brain/xaiImageClient.ts
@@ -8,7 +8,7 @@
import fs from 'node:fs/promises';
-import type { GhostImageAspectRatio } from '../../shared/ghost.js';
+import { normalizeImageParameters, type ImageParameters } from '../cindy-media/imageParameters.js';
import { sniffMediaMime } from '../cindy-media/sniffMediaMime.js';
import type { ImageChannel, ImageChannelResult } from './imageChannelRegistry.js';
@@ -194,12 +194,13 @@ export function createXaiImageChannel(opts: CreateXaiImageChannelOptions): Image
? Math.min(requestedDownloadLimit, MAX_IMAGE_DOWNLOAD_BYTES)
: MAX_IMAGE_DOWNLOAD_BYTES;
- async function call(params: {
+ async function call(params: ImageParameters & {
model: string;
prompt: string;
- aspectRatio?: GhostImageAspectRatio;
imagePaths?: string[];
+ signal?: AbortSignal;
}): Promise<ImageChannelResult> {
+ const options = normalizeImageParameters('xai', params.model, params);
const paths = params.imagePaths ?? [];
if (paths.length > MAX_EDIT_SOURCES) {
throw new Error(`xAI 图像编辑最多支持 ${MAX_EDIT_SOURCES} 张源图`);
@@ -223,8 +224,9 @@ export function createXaiImageChannel(opts: CreateXaiImageChannelOptions): Image
model: upstreamModelId(params.model),
prompt: params.prompt,
response_format: 'b64_json',
- resolution: '1k',
- ...(params.aspectRatio ? { aspect_ratio: params.aspectRatio } : {}),
+ ...(options.resolution ? { resolution: options.resolution } : {}),
+ ...(options.quality ? { quality: options.quality } : {}),
+ ...(options.aspectRatio ? { aspect_ratio: options.aspectRatio } : {}),
};
if (isEdit) {
if (images.length === 1) body.image = images[0];
@@ -241,6 +243,7 @@ export function createXaiImageChannel(opts: CreateXaiImageChannelOptions): Image
Accept: 'application/json',
},
body: JSON.stringify(body),
+ signal: params.signal,
});
const responseText = await response.text();
assertStillCurrent();
@@ -302,8 +305,8 @@ export function createXaiImageChannel(opts: CreateXaiImageChannelOptions): Image
return {
ready: () => opts.hasApiKey?.() === true || opts.hasOAuthLogin(),
maxEditImages: MAX_EDIT_SOURCES,
- generateImage: ({ model, prompt, aspectRatio }) => call({ model, prompt, aspectRatio }),
- editImage: ({ model, prompt, imagePaths, aspectRatio }) =>
- call({ model, prompt, imagePaths, aspectRatio }),
+ imageProtocol: 'xai',
+ generateImage: call,
+ editImage: call,
};
}
diff --git a/apps/desktop/src/main/cindy-media/__tests__/imageParameters.test.ts b/apps/desktop/src/main/cindy-media/__tests__/imageParameters.test.ts
new file mode 100644
index 0000000000..0fa8b2274d
--- /dev/null
+++ b/apps/desktop/src/main/cindy-media/__tests__/imageParameters.test.ts
@@ -0,0 +1,89 @@
+import { describe, expect, it } from 'vitest';
+import { imageParameterSchema, normalizeImageParameters } from '../imageParameters.js';
+
+describe('image options use the selected channel and model', () => {
+ it('keeps supported large native sizes and all Sunburst quality levels', () => {
+ for (const quality of ['auto', 'low', 'medium', 'high', 'xhigh', 'max']) {
+ expect(
+ normalizeImageParameters('openai', 'account/gpt-image-2.5-sunburst', {
+ size: '1760x3824',
+ quality,
+ }),
+ ).toEqual({ size: '1760x3824', quality });
+ }
+ expect(normalizeImageParameters('openai', 'openai/gpt-image-2', { size: '2160x3840' })).toEqual(
+ { size: '2160x3840' },
+ );
+ });
+
+ it.each(['1320x2868', '16x16', '4096x4096', '512x2048', '0x1024', '1024', '999999x999999'])(
+ 'rejects invalid size %s before submission',
+ (size) => {
+ expect(() =>
+ normalizeImageParameters('openai', 'openai/gpt-image-2.5-flare', { size }),
+ ).toThrow();
+ },
+ );
+
+ it('preserves legacy ratios and supports widescreen without changing the ratio', () => {
+ expect(
+ normalizeImageParameters('openai', 'openai/gpt-image-2', { aspectRatio: '3:2' }),
+ ).toEqual({ size: '1536x1024' });
+ for (const aspectRatio of ['16:9', '9:16', '4:3', '19.5:9', '110:239']) {
+ const { size } = normalizeImageParameters('openai', 'openai/gpt-image-2', { aspectRatio });
+ const [w, h] = size!.split('x').map(Number);
+ const [a, b] = aspectRatio.split(':').map(Number);
+ expect(w / h).toBeCloseTo(a / b, 8);
+ expect(w % 16).toBe(0);
+ expect(h % 16).toBe(0);
+ }
+ expect(() =>
+ normalizeImageParameters('openai', 'openai/gpt-image-1.5', { aspectRatio: '16:9' }),
+ ).toThrow();
+ expect(() =>
+ normalizeImageParameters('openai', 'openai/gpt-image-2', {
+ size: '1024x1024',
+ aspectRatio: '16:9',
+ }),
+ ).toThrow('conflict');
+ });
+
+ it('does not silently drop wrong-provider fields or explicit unsupported values', () => {
+ expect(() =>
+ normalizeImageParameters('gemini', 'gemini-3-pro-image', { size: '2048x2048' }),
+ ).toThrow('not supported');
+ expect(() =>
+ normalizeImageParameters('xai', 'grok-imagine-image', { quality: 'high' }),
+ ).toThrow('not supported');
+ expect(() =>
+ normalizeImageParameters('xai', 'grok-imagine-image', { resolution: '4k' }),
+ ).toThrow();
+ expect(() => normalizeImageParameters('openai', 'gpt-image-2', { quality: 'max' })).toThrow();
+ expect(() =>
+ normalizeImageParameters('gemini', 'gemini-2.5-flash-image', { resolution: '4K' }),
+ ).toThrow();
+ expect(
+ normalizeImageParameters('gemini', 'gemini-3-pro-image', {
+ resolution: '4k',
+ aspectRatio: '16:9',
+ }),
+ ).toEqual({ resolution: '4K', aspectRatio: '16:9' });
+ expect(normalizeImageParameters('xai', 'grok-imagine-image', { resolution: '2K' })).toEqual({
+ resolution: '2k',
+ });
+ });
+
+ it('does not inject defaults and keeps older guides executable', () => {
+ expect(normalizeImageParameters('openai', 'gpt-image-2.5-flare', {})).toEqual({});
+ expect(normalizeImageParameters(undefined, 'old-model', { aspectRatio: '2:3' })).toEqual({
+ aspectRatio: '2:3',
+ });
+ expect(imageParameterSchema('openai', 'gpt-image-2.5-sunburst').quality.enum).toContain('max');
+ expect(imageParameterSchema('gemini', 'gemini-3-pro-image').resolution.enum).toContain('4K');
+ expect(imageParameterSchema('xai', 'grok-imagine-image-2.0').quality.enum).toEqual([
+ 'auto',
+ 'low',
+ 'medium',
+ ]);
+ });
+});
diff --git a/apps/desktop/src/main/cindy-media/__tests__/invocationService.test.ts b/apps/desktop/src/main/cindy-media/__tests__/invocationService.test.ts
index 3a3fc32674..d0e60d2873 100644
--- a/apps/desktop/src/main/cindy-media/__tests__/invocationService.test.ts
+++ b/apps/desktop/src/main/cindy-media/__tests__/invocationService.test.ts
@@ -361,6 +361,42 @@ describe('Cindy Core media invocation state and security boundary', () => {
expect(mocks.ingestMedia).toHaveBeenCalledTimes(1);
});
+ it.each([0, 1, 2])('materializes large base64 images with %i trailing padding characters', async (padding) => {
+ const op = operation({
+ mode: 'sync',
+ media: [{ path: ['data'], encoding: 'base64', kind: 'image' }],
+ });
+ op.request.maxResponseBytes = 32 * 1024 * 1024;
+ mocks.guide.mockResolvedValue(resolvedGuide(op));
+ // Only the decoder and MIME probe are under test; ingestion is mocked.
+ const bytes = Buffer.alloc(6 * 1024 * 1024 - padding);
+ PNG.copy(bytes);
+ const encoded = bytes.toString('base64');
+ mocks.outboundFetch.mockResolvedValue(new Response(JSON.stringify({
+ data: padding === 0 ? encoded : `data:image/png;base64,\n${encoded}\n`,
+ }), { status: 200 }));
+
+ const invocationId = await prepare();
+ await expect(callCindyMedia({
+ action: 'request', invocationId, body: { prompt: 'large image' },
+ })).resolves.toMatchObject({ ok: true, status: 'complete' });
+ expect(mocks.ingestMedia).toHaveBeenCalledTimes(1);
+ expect(mocks.ingestMedia.mock.calls[0][0].buffer.equals(bytes)).toBe(true);
+ });
+
+ it.each(['A', 'AAA', 'AAAA=', 'A===', 'AA=A', '====', 'AA-_', 'AAA!'])('rejects malformed base64 %s before ingestion', async (encoded) => {
+ mocks.guide.mockResolvedValue(resolvedGuide(operation({
+ mode: 'sync',
+ media: [{ path: ['data'], encoding: 'base64', kind: 'image' }],
+ })));
+ mocks.outboundFetch.mockResolvedValue(new Response(JSON.stringify({ data: encoded }), { status: 200 }));
+ const invocationId = await prepare();
+ await expect(callCindyMedia({
+ action: 'request', invocationId, body: { prompt: 'image' },
+ })).resolves.toMatchObject({ ok: false, errorCode: 'MEDIA_RESULT_INVALID' });
+ expect(mocks.ingestMedia).not.toHaveBeenCalled();
+ });
+
it('Guide 查询键无前缀时仍持久化并提交完整 Gateway modelId', async () => {
const fullModelId = 'openai/gpt-image-2';
mocks.models.mockResolvedValue([
@@ -460,6 +496,50 @@ describe('Cindy Core media invocation state and security boundary', () => {
expect(mocks.providerInvoke).toHaveBeenCalledTimes(1);
});
+ it.each([
+ ['openai', 'account/gpt-image-2.5-sunburst', { size: '1760x3824', quality: 'max' }, { size: '1760x3824', quality: 'max' }],
+ ['gemini', 'gemini/gemini-3-pro-image', { aspect_ratio: '16:9', resolution: '4k' }, { aspectRatio: '16:9', resolution: '4K' }],
+ ['xai', 'xai/grok-imagine-image', { aspect_ratio: '9:19.5', resolution: '2K' }, { aspectRatio: '9:19.5', resolution: '2k' }],
+ ] as const)('carries %s image parameters from prepare to dispatch', async (imageProtocol, id, body, expected) => {
+ const model = { id, name: id, providerId: 'custom-account', mode: 'image_generation', imageProtocol,
+ modalities: { input: ['text'], output: ['image'] } };
+ mocks.models.mockResolvedValue([model]);
+ mocks.providerModel.mockReturnValue(model);
+ mocks.providerInvoke.mockResolvedValue({ buffer: PNG, mimeType: 'image/png' });
+ const prepared = await callCindyMedia({ action: 'prepare', providerId: model.providerId, modelId: id, capability: 'image.generate' });
+ expect(prepared.ok).toBe(true);
+ for (const key of Object.keys(body)) expect((prepared.input_schema as Record<string, unknown>).properties).toHaveProperty(key);
+ const result = await callCindyMedia({ action: 'request', invocationId: prepared.invocation_id as string, body: { prompt: 'image', ...body } });
+ expect(result.ok).toBe(true);
+ expect(mocks.providerInvoke).toHaveBeenCalledWith(expect.objectContaining(expected));
+ });
+
+ it('invalid native size remains editable before claiming a paid invocation', async () => {
+ const model = { id: 'openai/gpt-image-2.5-sunburst', name: 'Sunburst', providerId: 'openai', imageProtocol: 'openai',
+ mode: 'image_generation', modalities: { input: ['text'], output: ['image'] } };
+ mocks.models.mockResolvedValue([model]);
+ mocks.providerModel.mockReturnValue(model);
+ mocks.providerInvoke.mockResolvedValue({ buffer: PNG, mimeType: 'image/png' });
+ const prepared = await callCindyMedia({ action: 'prepare', providerId: 'openai', modelId: model.id, capability: 'image.generate' });
+ const invocationId = prepared.invocation_id as string;
+ expect(await callCindyMedia({ action: 'request', invocationId, body: { prompt: 'p', size: '1320x2868' } })).toMatchObject({ ok: false, errorCode: 'REQUEST_INVALID' });
+ expect(mocks.providerInvoke).not.toHaveBeenCalled();
+ expect(mocks.rows.get(invocationId)?.state).toBe('prepared');
+ expect(await callCindyMedia({ action: 'request', invocationId, body: { prompt: 'p', size: '1760x3824', quality: 'max' } })).toMatchObject({ ok: true });
+ expect(mocks.providerInvoke).toHaveBeenCalledTimes(1);
+ });
+
+ it('validates Gateway GPT Image geometry without a paid round trip', async () => {
+ const id = 'openai/gpt-image-2.5-sunburst';
+ mocks.models.mockResolvedValue([{ id, name: 'Sunburst', providerId: 'xd', mode: 'image_generation' }]);
+ const guide = resolvedGuide(operation({ mode: 'sync', media: [{ path: ['data'], encoding: 'base64', kind: 'image' }] }));
+ guide.modelId = id;
+ mocks.guide.mockResolvedValue(guide);
+ const prepared = await callCindyMedia({ action: 'prepare', providerId: 'xd', modelId: id, capability: 'image.generate' });
+ expect(await callCindyMedia({ action: 'request', invocationId: prepared.invocation_id as string, body: { prompt: 'p', size: '1320x2868' } })).toMatchObject({ ok: false, errorCode: 'REQUEST_INVALID' });
+ expect(mocks.outboundFetch).not.toHaveBeenCalled();
+ });
+
it('本机准备期间同 owner 代次变化时不保存调用', async () => {
mocks.localMode = true;
mocks.models.mockImplementationOnce(async () => {
diff --git a/apps/desktop/src/main/cindy-media/imageParameters.ts b/apps/desktop/src/main/cindy-media/imageParameters.ts
new file mode 100644
index 0000000000..531ad47295
--- /dev/null
+++ b/apps/desktop/src/main/cindy-media/imageParameters.ts
@@ -0,0 +1,192 @@
+/** Image options shared by the invocation guide and the actual provider serializers. */
+export type ImageProtocol = 'openai' | 'gemini' | 'xai';
+export interface ImageParameters {
+ aspectRatio?: string;
+ size?: string;
+ resolution?: string;
+ quality?: string;
+}
+
+const LEGACY_SIZES: Record<string, string> = {
+ '1:1': '1024x1024',
+ '3:2': '1536x1024',
+ '2:3': '1024x1536',
+};
+const GEMINI_RATIOS = ['1:1', '2:3', '3:2', '3:4', '4:3', '4:5', '5:4', '9:16', '16:9', '21:9'];
+const XAI_RATIOS = [
+ 'auto',
+ '1:1',
+ '16:9',
+ '9:16',
+ '4:3',
+ '3:4',
+ '3:2',
+ '2:3',
+ '2:1',
+ '1:2',
+ '19.5:9',
+ '9:19.5',
+ '20:9',
+ '9:20',
+ '21:9',
+ '5:2',
+];
+const SIZE_RULE =
+ 'size must have edges divisible by 16, each <= 3840, aspect ratio <= 3:1, and 655360–8294400 total pixels. Use a supported generation size, then resize separately if exact final dimensions are needed.';
+const modelName = (model: string) => model.slice(model.lastIndexOf('/') + 1);
+const customSizes = (model: string) => /^gpt-image-2(?:$|\.)/.test(modelName(model));
+const oldGptImage = (model: string) => /^gpt-image-1(?:$|[.-])/.test(modelName(model));
+
+function choices(values: string[], description?: string): Record<string, unknown> {
+ return { type: 'string', enum: values, ...(description ? { description } : {}) };
+}
+
+/** Protocol comes from the selected execution channel, never inferred from account IDs. */
+export function imageParameterSchema(
+ protocol: ImageProtocol | undefined,
+ model: string,
+): Record<string, Record<string, unknown>> {
+ if (!protocol) return { aspect_ratio: choices(Object.keys(LEGACY_SIZES)) };
+ if (protocol === 'openai') {
+ return {
+ aspect_ratio: {
+ type: 'string',
+ description:
+ 'Optional width:height ratio. Prefer size for exact dimensions; do not combine conflicting size and ratio.',
+ },
+ size: oldGptImage(model)
+ ? choices(['auto', ...Object.values(LEGACY_SIZES)])
+ : {
+ type: 'string',
+ description: customSizes(model)
+ ? `auto or WIDTHxHEIGHT. ${SIZE_RULE}`
+ : 'auto or WIDTHxHEIGHT, subject to the selected model limits.',
+ },
+ quality: choices(
+ /^gpt-image-2\.5(?:-|$)/.test(modelName(model))
+ ? ['auto', 'low', 'medium', 'high', 'xhigh', 'max']
+ : ['auto', 'low', 'medium', 'high'],
+ 'draft → low; standard → medium; best → highest supported quality. Omit when unspecified.',
+ ),
+ };
+ }
+ if (protocol === 'gemini') {
+ const name = modelName(model);
+ const flash31 = /^gemini-3\.1-flash-image/.test(name);
+ const fixed1k = /^gemini-2\.5-/.test(name);
+ return {
+ aspect_ratio: choices([...GEMINI_RATIOS, ...(flash31 ? ['1:4', '4:1', '1:8', '8:1'] : [])]),
+ ...(!fixed1k
+ ? {
+ resolution: choices(
+ [...(flash31 ? ['512'] : []), '1K', '2K', '4K'],
+ 'Maps to imageConfig.imageSize. Preserve an explicit resolution; for quality intent use draft/standard → 1K and best → highest supported resolution.',
+ ),
+ }
+ : {}),
+ };
+ }
+ return {
+ aspect_ratio: choices(XAI_RATIOS),
+ resolution: choices(
+ ['1k', '2k'],
+ 'draft/standard → 1k; best → 2k unless an explicit resolution was requested.',
+ ),
+ ...(modelName(model) === 'grok-imagine-image-2.0'
+ ? { quality: choices(['auto', 'low', 'medium'], 'draft → low; standard/best → medium.') }
+ : {}),
+ };
+}
+
+function validateSize(model: string, size: string): void {
+ if (size === 'auto') return;
+ const match = /^(\d{1,6})x(\d{1,6})$/.exec(size);
+ if (!match) throw new Error('size must be auto or WIDTHxHEIGHT');
+ const width = Number(match[1]);
+ const height = Number(match[2]);
+ if (width <= 0 || height <= 0) throw new Error('size dimensions must be positive');
+ if (
+ customSizes(model) &&
+ (width % 16 ||
+ height % 16 ||
+ Math.max(width, height) > 3840 ||
+ Math.max(width, height) / Math.min(width, height) > 3 ||
+ width * height < 655360 ||
+ width * height > 8294400)
+ ) {
+ throw new Error(SIZE_RULE);
+ }
+}
+
+function aspectSize(model: string, aspect: string): string {
+ if (aspect === 'auto') return 'auto';
+ if (LEGACY_SIZES[aspect]) return LEGACY_SIZES[aspect];
+ if (oldGptImage(model))
+ throw new Error(
+ 'This model supports only 1:1, 3:2 and 2:3; choose another model for this aspect ratio.',
+ );
+ if (!/^\d{1,5}(?:\.\d{1,2})?:\d{1,5}(?:\.\d{1,2})?$/.test(aspect))
+ throw new Error('aspect_ratio must be width:height');
+ const [a, b] = aspect.split(':').map(Number);
+ if (!a || !b) throw new Error('aspect_ratio dimensions must be positive');
+ const gcd = (a: number, b: number): number => (b ? gcd(b, a % b) : a);
+ const divisor = gcd(Math.round(a * 100), Math.round(b * 100));
+ const width = (Math.round(a * 100) / divisor) * 16;
+ const height = (Math.round(b * 100) / divisor) * 16;
+ const multiple = Math.max(1, Math.round(Math.sqrt((1536 * 1024) / (width * height))));
+ const size = `${width * multiple}x${height * multiple}`;
+ validateSize(model, size);
+ return size;
+}
+
+/** Reject unsupported explicit options before paying; never silently strip or downscale them. */
+export function normalizeImageParameters(
+ protocol: ImageProtocol | undefined,
+ model: string,
+ input: ImageParameters,
+): ImageParameters {
+ const result: ImageParameters = {};
+ const schema = imageParameterSchema(protocol, model);
+ for (const key of ['aspectRatio', 'size', 'resolution', 'quality'] as const) {
+ let value = input[key];
+ if (value === undefined) continue;
+ if (typeof value !== 'string' || !value.trim() || value.length > 100)
+ throw new Error(`${key} must be a nonempty string`);
+ value = value.trim();
+ if (key === 'resolution')
+ value = protocol === 'gemini' ? value.toUpperCase() : value.toLowerCase();
+ if (key === 'size') value = value.toLowerCase().replace('×', 'x');
+ const field = schema[key === 'aspectRatio' ? 'aspect_ratio' : key];
+ if (!field)
+ throw new Error(
+ `${key} is not supported by this channel; use the parameters from prepare.input_schema.`,
+ );
+ if (Array.isArray(field.enum) && !field.enum.includes(value))
+ throw new Error(`${key} must be one of: ${field.enum.join(', ')}`);
+ result[key] = value;
+ }
+ if (protocol === 'openai') {
+ if (result.size) validateSize(model, result.size);
+ if (
+ result.aspectRatio &&
+ result.aspectRatio !== 'auto' &&
+ result.size &&
+ result.size !== 'auto'
+ ) {
+ const [w, h] = result.size.split('x').map(Number);
+ const ratio = /^(\d+(?:\.\d+)?):(\d+(?:\.\d+)?)$/.exec(result.aspectRatio);
+ if (
+ !ratio ||
+ !Number(ratio[1]) ||
+ !Number(ratio[2]) ||
+ Math.abs(w / h - Number(ratio[1]) / Number(ratio[2])) > 0.001
+ ) {
+ throw new Error('size and aspect_ratio conflict; use size alone for exact dimensions.');
+ }
+ }
+ if (result.aspectRatio && (!result.size || result.size === 'auto'))
+ result.size = aspectSize(model, result.aspectRatio);
+ delete result.aspectRatio;
+ }
+ return result;
+}
diff --git a/apps/desktop/src/main/cindy-media/invocationService.ts b/apps/desktop/src/main/cindy-media/invocationService.ts
index deb0ce39ac..90f8f8278c 100644
--- a/apps/desktop/src/main/cindy-media/invocationService.ts
+++ b/apps/desktop/src/main/cindy-media/invocationService.ts
@@ -12,7 +12,7 @@ import type {
ResolvedMediaInvocationGuide,
} from '../../shared/mediaInvocation.js';
import { MODEL_ACCESS_INVOCATION_GUIDE_SCHEMA_VERSION } from '../../shared/mediaInvocation.js';
-import { GHOST_IMAGE_ASPECT_RATIOS, type GhostImageAspectRatio } from '../../shared/ghost.js';
+import { imageParameterSchema, normalizeImageParameters, type ImageParameters } from './imageParameters.js';
import { getAppCapabilities } from '../appCapabilities.js';
import * as authManager from '../authManager.js';
import * as imageCacheStore from '../imageCacheStore.js';
@@ -197,7 +197,7 @@ function providerImageGuide(
schemaVersion: MODEL_ACCESS_INVOCATION_GUIDE_SCHEMA_VERSION,
guideId: CLIENT_PROVIDER_IMAGE_GUIDE_ID,
modelId: model.id,
- revision: '1',
+ revision: '2',
connection: { providerId: model.providerId },
capability,
request: {
@@ -214,8 +214,8 @@ function providerImageGuide(
media: [{ path: ['image'], encoding: 'base64', kind: 'image' }],
},
instructions: edit
- ? '必填 prompt 和 image。image 可传一条 Cindy 本地媒体引用或引用数组;可选 aspect_ratio。'
- : '必填 prompt;可选 aspect_ratio。model 与凭证由 Cindy 注入。',
+ ? '必填 prompt 和 image。image 可传一条 Cindy 本地媒体引用或引用数组。尺寸与质量参数见 inputSchema;不要丢弃用户的明确要求。'
+ : '必填 prompt。尺寸与质量参数见 inputSchema;不指定时由上游决定。model 与凭证由 Cindy 注入。',
exampleBody: {
prompt: edit ? '描述希望如何修改图片' : '描述希望生成的图片',
...(edit ? { image: 'cindy-media://blobs/<hash>.png' } : {}),
@@ -236,7 +236,7 @@ function providerImageGuide(
},
}
: {}),
- aspect_ratio: { type: 'string', enum: [...GHOST_IMAGE_ASPECT_RATIOS] },
+ ...imageParameterSchema(model.imageProtocol, model.id),
},
},
officialDocs: model.officialDocs ?? 'https://platform.openai.com/docs/guides/images',
@@ -698,27 +698,29 @@ async function localImagePath(
async function providerImageRequest(
invocation: StoredMediaInvocation,
body: Record<string, unknown>,
-): Promise<{
+ model: ProviderMediaRuntimeModel,
+): Promise<ImageParameters & {
prompt: string;
imagePaths: string[];
- aspectRatio?: GhostImageAspectRatio;
}> {
const prompt = body.prompt;
if (typeof prompt !== 'string' || prompt.trim().length === 0 || prompt.length > 100_000) {
throw new MediaInvocationError('REQUEST_INVALID', 'prompt 必须是非空字符串');
}
- let aspectRatio: GhostImageAspectRatio | undefined;
- if (body.aspect_ratio !== undefined) {
- if (
- typeof body.aspect_ratio !== 'string' ||
- !(GHOST_IMAGE_ASPECT_RATIOS as readonly string[]).includes(body.aspect_ratio)
- ) {
- throw new MediaInvocationError(
- 'REQUEST_INVALID',
- `aspect_ratio 只支持 ${GHOST_IMAGE_ASPECT_RATIOS.join(' / ')}`,
- );
+ let options: ImageParameters;
+ try {
+ const fields = new Set(['model', 'prompt', 'image', 'aspect_ratio', 'size', 'resolution', 'quality']);
+ for (const key of Object.keys(body)) {
+ if (!fields.has(key)) throw new Error(`Unsupported image parameter: ${key}; use prepare.input_schema.`);
}
- aspectRatio = body.aspect_ratio as GhostImageAspectRatio;
+ options = normalizeImageParameters(model.imageProtocol, model.id, {
+ aspectRatio: body.aspect_ratio as string | undefined,
+ size: body.size as string | undefined,
+ resolution: body.resolution as string | undefined,
+ quality: body.quality as string | undefined,
+ });
+ } catch (error) {
+ throw new MediaInvocationError('REQUEST_INVALID', (error as Error).message);
}
const imagePaths: string[] = [];
if (invocation.capability === 'image.edit') {
@@ -736,7 +738,7 @@ async function providerImageRequest(
return {
prompt,
imagePaths,
- ...(aspectRatio ? { aspectRatio } : {}),
+ ...options,
};
}
@@ -800,7 +802,9 @@ async function mediaBytes(
if (encoded.length > Math.ceil((maxResultBytes(extractor.kind) * 4) / 3) + 16) {
throw new MediaInvocationError('MEDIA_RESULT_TOO_LARGE', '上游 base64 媒体超过大小限制');
}
- if (!/^(?:[A-Za-z0-9+/]{4})*(?:[A-Za-z0-9+/]{2}==|[A-Za-z0-9+/]{3}=)?$/.test(encoded)) {
+ // Repeating four-character groups exhausts V8's regexp stack on large images.
+ // Check quartet length separately so the alphabet scan uses constant stack space.
+ if (encoded.length % 4 !== 0 || !/^[A-Za-z0-9+/]*={0,2}$/.test(encoded)) {
throw new MediaInvocationError('MEDIA_RESULT_INVALID', '上游 base64 媒体编码不合法');
}
buffer = Buffer.from(encoded, 'base64');
@@ -969,7 +973,7 @@ async function submitProviderInvocation(
if (!providerModel) {
return failure('MODEL_NOT_AVAILABLE', '该第三方媒体模型或执行来源已不可用,本次生成未发出');
}
- const input = await providerImageRequest(invocation, body);
+ const input = await providerImageRequest(invocation, body, providerModel);
assertAuthScope(scope, invocation.owner);
const claimed = await transitionMediaInvocation(
{
@@ -1326,7 +1330,18 @@ async function submitInvocation(
if (!models.some((model) => model.providerId === 'xd' && model.id === invocation.modelId)) {
return failure('MODEL_NOT_AVAILABLE', '该模型已下架或被停用,本次生成未发出');
}
- const requestBody = await prepareRequestBody(body, invocation.guide);
+ let validatedBody = body;
+ if (invocation.capability.startsWith('image.') && /^openai\/gpt-image-[12]/.test(invocation.modelId)) {
+ try {
+ validatedBody = { ...body, ...normalizeImageParameters('openai', invocation.modelId, {
+ size: body.size as string | undefined,
+ quality: body.quality as string | undefined,
+ }) };
+ } catch (error) {
+ throw new MediaInvocationError('REQUEST_INVALID', (error as Error).message);
+ }
+ }
+ const requestBody = await prepareRequestBody(validatedBody, invocation.guide);
assertAuthScope(scope, invocation.owner);
let connection: MediaConnection;
try {
diff --git a/apps/desktop/src/main/cindy-media/providerMediaRuntime.ts b/apps/desktop/src/main/cindy-media/providerMediaRuntime.ts
index 5b4aff3273..ebd5f4e896 100644
--- a/apps/desktop/src/main/cindy-media/providerMediaRuntime.ts
+++ b/apps/desktop/src/main/cindy-media/providerMediaRuntime.ts
@@ -1,5 +1,5 @@
import type { MediaCapability } from '@cindy/model-providers';
-import type { GhostImageAspectRatio } from '../../shared/ghost.js';
+import type { ImageParameters, ImageProtocol } from './imageParameters.js';
import { supportsMediaCapability } from './mediaCapabilities.js';
export interface ProviderMediaRuntimeModel {
@@ -9,15 +9,15 @@ export interface ProviderMediaRuntimeModel {
mode: 'image_generation' | 'video_generation';
modalities: { input: string[]; output: string[] };
officialDocs?: string;
+ imageProtocol?: ImageProtocol;
}
-export interface ProviderMediaRuntimeRequest {
+export interface ProviderMediaRuntimeRequest extends ImageParameters {
providerId: string;
modelId: string;
capability: MediaCapability;
prompt: string;
imagePaths: string[];
- aspectRatio?: GhostImageAspectRatio;
signal?: AbortSignal;
}
diff --git a/apps/desktop/src/main/cindy-proxy-media/types.ts b/apps/desktop/src/main/cindy-proxy-media/types.ts
index c8b9767d3e..e757d015b6 100644
--- a/apps/desktop/src/main/cindy-proxy-media/types.ts
+++ b/apps/desktop/src/main/cindy-proxy-media/types.ts
@@ -93,7 +93,7 @@ export interface GatewayImageGenerateParams {
model: string;
prompt: string;
size?: string;
- quality?: 'low' | 'medium' | 'high';
+ quality?: string;
n?: number;
}
@@ -103,7 +103,7 @@ export interface GatewayImageEditParams {
prompt: string;
imagePaths: string[];
size?: string;
- quality?: 'low' | 'medium' | 'high';
+ quality?: string;
n?: number;
}
diff --git a/docs/dev-rules/media-storage-and-protocols.md b/docs/dev-rules/media-storage-and-protocols.md
index 86be8269eb..33870c838e 100644
--- a/docs/dev-rules/media-storage-and-protocols.md
+++ b/docs/dev-rules/media-storage-and-protocols.md
@@ -102,6 +102,23 @@
- 真实 MIME 识别、账号/任务归属、受管入库规则持续有效。下载授权不包含执行文件、
安装程序或覆盖用户文件的授权。旧 Guide 快照与 base64 结果保持兼容。
+## 图像参数与最终结果
+
+- Art 返回的画幅、成品尺寸、分辨率和质量意图不得在客户端适配层静默丢弃。
+ 第三方图像通道声明自己的协议,`cindy-media/imageParameters.ts` 同时生成调用指南和
+ 验证实际请求;账号 ID 不参与协议推断。旧调用省略新增参数仍然可用。
+- `size` 表示生成像素尺寸,`resolution` 表示供应商的分辨率档,`quality` 是原生质量。
+ 不把不同来源的枚举互相套用,不强制 `medium` 或 `1k`。明确参数优先,省略时由上游决定。
+ 已知 GPT Image 尺寸约束在付费提交前检查;不合法时保留 prepared 调用供更正。
+ 目标成品尺寸不满足模型约束时,由 Agent 选择合法生成尺寸并单独完成成品缩放,不能谎报
+ 请求尺寸就是实际输出尺寸。没有自动缩放或偷偷裁切。
+- Codex SSE 的 partial image 仅为预览,不能在失败、未完成或只有预览的断流中当成成品。
+ 大 Base64 响应的字符校验必须采用常量栈空间,避免分组重复正则导致已生成图片收取失败。
+- 参数依据:[OpenAI](https://developers.openai.com/api/docs/guides/image-generation)、
+ [Gemini](https://ai.google.dev/gemini-api/docs/generate-content/image-generation)、
+ [xAI](https://docs.x.ai/developers/model-capabilities/images/generation)。
+ 回归覆盖 `imageParameters.test.ts`、`invocationService.test.ts` 和各图像通道测试。
+
## 多端与远程
- 媒体记录必须保留设备、会话、插件或远程主机等真实归属信息,不能相信调用方自报的