gpteam 0.1.22 → 0.1.24

package/README.md

@@ -16,14 +16,14 @@ Client config writing follows the same safety pattern as cc-switch: keep Codex t
 
 The Image MCP config uses cc-switch-style per-client env blocks. Codex writes `[mcp_servers.gpteam_image.env]`, OpenCode writes `mcp.gpteam_image.environment`, and Claude Code writes `mcpServers.gpteam_image.env` in `~/.claude.json`. The MCP receives `GPTEAM_API_KEY` and `GPTEAM_BASE_URL` from that MCP config, so it does not depend on Codex `auth.json` or inherited `OPENAI_API_KEY`.
 
-The Image MCP exposes both a synchronous compatibility tool and a local async job flow:
+The Image MCP exposes an async-first local job flow plus a legacy compatibility alias:
 
 - `create_image_job`: recommended for normal use. It starts a local background image job and returns `job_id` quickly, which avoids losing the whole generation when a VPN, proxy, or client has a 60-second idle timeout.
 - `get_image_job_status`: checks whether the local job is queued, running, succeeded, failed, canceled, or expired.
 - `cancel_image_job`: cancels a queued/running local job.
 - `download_image_result`: returns the completed file metadata and image content. Use `metadata_only`, `include_image`, and `include_revised_prompt` to control large result payloads.
 - `get_capabilities`: returns supported sizes, formats, quality values, async support, cancellation semantics, queue limits, and image-to-image support.
-- `generate_image`: waits for completion and writes the image file immediately. This is kept for synchronous compatibility.
+- `generate_image`: legacy compatibility alias. It now creates the same async job and returns `job_id` immediately instead of blocking until the image is complete.
 
 Image MCP results are returned as stable JSON text and MCP `structuredContent`. Successful results include final file path, model, action, size, format, quality, byte size, SHA-256, MIME type, image dimensions, duration, retry count, `job_id`, `trace_id`, and optional `idempotency_key`. Error results use stable `error.code`, `error.message`, `error.retryable`, `error.stage`, `error.upstream_status`, and `error.trace_id` fields while keeping compatibility fields such as `category` and `http_status`.
 

package/lib/config.js

@@ -13,8 +13,7 @@ const IMAGE_MCP_ENABLED_TOOLS = [
   'get_image_job_status',
   'download_image_result',
   'cancel_image_job',
-  'get_capabilities',
-  'generate_image'
+  'get_capabilities'
 ];
 
 export const CLIENTS = [
@@ -63,7 +62,7 @@ export function writeCodexConfig(settings) {
     `command = ${tomlString(mcpCommand.command)}`,
     `args = [${mcpCommand.args.map((arg) => tomlString(arg)).join(', ')}]`,
     'startup_timeout_sec = 20',
-    'tool_timeout_sec = 300',
+    'tool_timeout_sec = 900',
     `enabled_tools = [${IMAGE_MCP_ENABLED_TOOLS.map((name) => tomlString(name)).join(', ')}]`,
     'default_tools_approval_mode = "prompt"',
     '',

package/lib/help.js

@@ -1,5 +1,5 @@
 export const PACKAGE_NAME = 'gpteam';
-export const PACKAGE_VERSION = '0.1.22';
+export const PACKAGE_VERSION = '0.1.24';
 
 export function getHelpText() {
   return [

package/lib/image-mcp/image.js

@@ -14,9 +14,32 @@ export const DEFAULT_BASE_URL = 'https://api.gpteamservices.com/v1';
 export const DEFAULT_IMAGE_MODEL = 'gpt-image-2';
 export { DEFAULT_IMAGE_FORMAT };
 
+export const IMAGE_FORMATS = ['png', 'jpeg', 'webp'];
+export const IMAGE_QUALITY_LEVELS = ['low', 'medium', 'high', 'auto'];
+export const IMAGE_BACKGROUND_OPTIONS = ['auto', 'opaque'];
+export const IMAGE_MODERATION_OPTIONS = ['auto', 'low'];
+export const POPULAR_IMAGE_SIZES = [
+  { label: '1K 方图', size: '1024x1024', aspect_ratio: '1:1' },
+  { label: '1K 横图', size: '1536x1024', aspect_ratio: '3:2' },
+  { label: '1K 竖图', size: '1024x1536', aspect_ratio: '2:3' },
+  { label: '2K 方图', size: '2048x2048', aspect_ratio: '1:1' },
+  { label: '2K 宽屏', size: '2048x1152', aspect_ratio: '16:9' },
+  { label: '2K 竖幅', size: '1152x2048', aspect_ratio: '9:16' },
+  { label: '4K 横图', size: '3840x2160', aspect_ratio: '16:9' },
+  { label: '4K 竖图', size: '2160x3840', aspect_ratio: '9:16' },
+  { label: '自动', size: 'auto', aspect_ratio: 'auto' }
+];
+export const IMAGE_SIZE_CONSTRAINTS = {
+  max_edge_px: 3840,
+  edge_multiple_px: 16,
+  max_long_to_short_ratio: 3,
+  min_total_pixels: 655360,
+  max_total_pixels: 8294400
+};
+
 const defaultMaxAttempts = 3;
 const defaultRetryDelayMs = 800;
-const defaultRequestTimeoutMs = 5 * 60 * 1000;
+const defaultRequestTimeoutMs = 15 * 60 * 1000;
 const defaultMaxConcurrentJobs = 2;
 const defaultMaxQueuedJobs = 20;
 const defaultJobTTLMS = 30 * 60 * 1000;
@@ -32,7 +55,7 @@ export function buildImageGenerationPayload(input = {}, options = {}) {
     stream: true,
     size: String(input.size || '1024x1024'),
     quality: String(input.quality || 'high'),
-    output_format: normalizeImageFormat(input.format || input.output_format || DEFAULT_IMAGE_FORMAT)
+    output_format: resolveImageOutputFormat(input)
   };
   const imageOptions = { ...options, home: options.home };
   const images = normalizeInputImages(collectInputImageValues(input), imageOptions);
@@ -41,6 +64,7 @@ export function buildImageGenerationPayload(input = {}, options = {}) {
   if (mask) payload.mask = { image_url: mask };
   copyOptionalImageToolOption(payload, input, 'background');
   copyOptionalImageToolOption(payload, input, 'moderation');
+  copyOptionalImageToolOption(payload, input, 'output_compression');
   return payload;
 }
 
@@ -88,15 +112,7 @@ export function normalizeBaseUrl(value) {
 
 export async function generateImage(input = {}, options = {}) {
   const startedAt = now(options);
-  const prompt = String(input.prompt || '').trim();
-  if (!prompt) {
-    throw new ImageMCPError('prompt 不能为空', {
-      code: 'prompt_required',
-      category: 'parameter',
-      stage: 'validate',
-      retryable: false
-    });
-  }
+  validateImageInput(input, { requirePrompt: true });
   const credentials = loadGPTeamCredentials(options);
   const payload = buildImageGenerationPayload(input, options);
   const fetchImpl = options.fetch || globalThis.fetch;
@@ -147,6 +163,11 @@ export function createImageJobStore(options = {}) {
 }
 
 export function createImageJob(input = {}, options = {}) {
+  try {
+    validateImageInput(input, { requirePrompt: true });
+  } catch (error) {
+    return resultFromError(error);
+  }
   const store = options.store || defaultJobStore;
   configureJobStore(store, options);
   cleanupImageJobs(store);
@@ -280,6 +301,7 @@ export function getCapabilities(options = {}) {
     ok: true,
     model: DEFAULT_IMAGE_MODEL,
     default_model: DEFAULT_IMAGE_MODEL,
+    preferred_tool: 'create_image_job',
     supports_async: true,
     supports_cancel: true,
     cancel_semantics: 'best_effort',
@@ -288,9 +310,18 @@ export function getCapabilities(options = {}) {
     supports_mask: true,
     image_input_fields: ['images', 'image', 'image_path', 'image_paths', 'input_image', 'input_images'],
     mask_input_fields: ['mask', 'mask_path'],
-    sizes: ['1024x1024', '1536x1024', '1024x1536', 'auto'],
-    formats: ['png', 'jpeg', 'webp'],
-    quality: ['low', 'medium', 'high', 'auto'],
+    sizes: POPULAR_IMAGE_SIZES.map((item) => item.size),
+    popular_sizes: POPULAR_IMAGE_SIZES,
+    size_presets: ['1K', '2K', '4K', 'auto'],
+    size_constraints: IMAGE_SIZE_CONSTRAINTS,
+    aspect_ratios: ['1:1', '3:2', '2:3', '16:9', '9:16', 'custom'],
+    supports_custom_size: true,
+    formats: IMAGE_FORMATS,
+    output_formats: IMAGE_FORMATS,
+    quality: IMAGE_QUALITY_LEVELS,
+    background: IMAGE_BACKGROUND_OPTIONS,
+    moderation: IMAGE_MODERATION_OPTIONS,
+    supports_output_compression: true,
     max_prompt_length: 32000,
     statuses: ['queued', 'running', 'succeeded', 'failed', 'canceled', 'expired'],
     default_output_format: DEFAULT_IMAGE_FORMAT,
@@ -301,6 +332,22 @@ export function getCapabilities(options = {}) {
   };
 }
 
+export function validateImageInput(input = {}, options = {}) {
+  if (options.requirePrompt && !String(input.prompt || '').trim()) {
+    throw imageParamError('prompt_required', 'prompt 不能为空', 'prompt', input.prompt, {
+      hint: '请先让用户提供图片提示词。'
+    });
+  }
+  validateImageSize(input.size);
+  validateEnumImageParam('quality', input.quality, IMAGE_QUALITY_LEVELS);
+  validateImageFormatParam(input);
+  validateEnumImageParam('background', input.background, IMAGE_BACKGROUND_OPTIONS, {
+    hint: 'gpt-image-2 不支持 transparent，请使用 auto 或 opaque。'
+  });
+  validateEnumImageParam('moderation', input.moderation, IMAGE_MODERATION_OPTIONS);
+  validateOutputCompression(input.output_compression);
+}
+
 async function fetchImageWithRetry(fetchImpl, credentials, payload, options) {
   const maxAttempts = resolveBoundedInt(1, options.maxAttempts, options.env && options.env.GPTEAM_IMAGE_MAX_ATTEMPTS, defaultMaxAttempts);
   const retryDelayMs = resolveBoundedInt(0, options.retryDelayMs, options.env && options.env.GPTEAM_IMAGE_RETRY_DELAY_MS, defaultRetryDelayMs);
@@ -722,6 +769,107 @@ function resolveRevisedPromptFlag(input) {
   return true;
 }
 
+function validateImageSize(value) {
+  if (value === undefined || value === null || value === '') return;
+  const text = String(value).trim().toLowerCase();
+  if (text === 'auto') return;
+  const match = text.match(/^(\d{2,5})x(\d{2,5})$/);
+  if (!match) {
+    throw imageParamError('invalid_size', 'size 必须是 auto 或类似 1024x1024 的宽高格式。', 'size', value, {
+      supported_values: POPULAR_IMAGE_SIZES.map((item) => item.size),
+      hint: '常用：1024x1024、1536x1024、1024x1536、2048x2048、2048x1152、1152x2048、3840x2160、2160x3840。'
+    });
+  }
+  const width = Number(match[1]);
+  const height = Number(match[2]);
+  const longSide = Math.max(width, height);
+  const shortSide = Math.min(width, height);
+  const pixels = width * height;
+  const valid = width % IMAGE_SIZE_CONSTRAINTS.edge_multiple_px === 0 &&
+    height % IMAGE_SIZE_CONSTRAINTS.edge_multiple_px === 0 &&
+    longSide <= IMAGE_SIZE_CONSTRAINTS.max_edge_px &&
+    longSide / shortSide <= IMAGE_SIZE_CONSTRAINTS.max_long_to_short_ratio &&
+    pixels >= IMAGE_SIZE_CONSTRAINTS.min_total_pixels &&
+    pixels <= IMAGE_SIZE_CONSTRAINTS.max_total_pixels;
+  if (!valid) {
+    throw imageParamError('invalid_size', 'size 超出 gpt-image-2 支持范围。', 'size', value, {
+      constraints: IMAGE_SIZE_CONSTRAINTS,
+      supported_values: POPULAR_IMAGE_SIZES.map((item) => item.size),
+      hint: '宽高需为 16 的倍数，长边不超过 3840，长短边比例不超过 3:1。'
+    });
+  }
+}
+
+function validateEnumImageParam(field, value, supportedValues, extra = {}) {
+  if (value === undefined || value === null || value === '') return;
+  const normalized = String(value).trim().toLowerCase();
+  if (supportedValues.includes(normalized)) return;
+  throw imageParamError(`invalid_${field}`, `${field} 参数不支持。`, field, value, {
+    supported_values: supportedValues,
+    ...extra
+  });
+}
+
+function validateImageFormatParam(input) {
+  const formatValue = input.format;
+  const outputFormatValue = input.output_format;
+  const format = normalizeDeclaredImageFormat(formatValue);
+  const outputFormat = normalizeDeclaredImageFormat(outputFormatValue);
+  if (formatValue !== undefined && formatValue !== null && formatValue !== '' && !IMAGE_FORMATS.includes(format)) {
+    throw invalidImageFormatError('format', formatValue);
+  }
+  if (outputFormatValue !== undefined && outputFormatValue !== null && outputFormatValue !== '' && !IMAGE_FORMATS.includes(outputFormat)) {
+    throw invalidImageFormatError('output_format', outputFormatValue);
+  }
+  if (format && outputFormat && format !== outputFormat) {
+    throw imageParamError('invalid_format_conflict', 'format 和 output_format 不一致。', 'output_format', outputFormatValue, {
+      format,
+      output_format: outputFormat,
+      hint: '两个字段同时传入时必须表示同一种格式，例如 jpg 和 jpeg 可以同时使用。'
+    });
+  }
+}
+
+function validateOutputCompression(value) {
+  if (value === undefined || value === null || value === '') return;
+  const amount = Number(value);
+  if (Number.isInteger(amount) && amount >= 0 && amount <= 100) return;
+  throw imageParamError('invalid_output_compression', 'output_compression 必须是 0 到 100 的整数。', 'output_compression', value, {
+    supported_values: ['0-100']
+  });
+}
+
+function resolveImageOutputFormat(input = {}) {
+  return normalizeImageFormat(input.output_format || input.format || DEFAULT_IMAGE_FORMAT);
+}
+
+function normalizeDeclaredImageFormat(value) {
+  if (value === undefined || value === null || value === '') return '';
+  const normalized = String(value).trim().toLowerCase();
+  return normalized === 'jpg' ? 'jpeg' : normalized;
+}
+
+function invalidImageFormatError(field, received) {
+  return imageParamError('invalid_format', 'format/output_format 参数不支持。', field, received, {
+    supported_values: IMAGE_FORMATS,
+    hint: '支持 png、jpeg、webp，jpg 会按 jpeg 处理。'
+  });
+}
+
+function imageParamError(code, message, field, received, details = {}) {
+  return new ImageMCPError(message, {
+    code,
+    category: 'parameter',
+    stage: 'validate',
+    retryable: false,
+    details: {
+      field,
+      received,
+      ...details
+    }
+  });
+}
+
 function resolveCodexHome(env, home) {
   return expandHome(firstNonEmpty(env.GPTEAM_CODEX_HOME, env.CODEX_HOME, path.join(home, '.codex')), home);
 }

package/lib/image-mcp/server.js

@@ -6,87 +6,119 @@ import {
   cancelImageJob,
   createImageJob,
   downloadImageResult,
-  generateImage,
   getCapabilities,
+  IMAGE_BACKGROUND_OPTIONS,
+  IMAGE_FORMATS,
+  IMAGE_MODERATION_OPTIONS,
+  IMAGE_QUALITY_LEVELS,
+  POPULAR_IMAGE_SIZES,
   getImageJobStatus,
   resultFromError,
   structuredToolResult,
   toolResultContent
 } from './image.js';
 
+const imageToolPromptingInstruction = '调用前请先确认用户真实需求：尺寸或比例、质量、输出格式、保存目录或文件名。缺少这些关键信息时应先追问，不要直接默认生成。常规生图请优先用 create_image_job，避免长任务占住 MCP 连接。';
+
 const imageInputProperties = {
   prompt: {
     type: 'string',
-    description: 'Image prompt.'
+    description: '图片提示词。需要尽量具体，若用户只给模糊需求，应先追问风格、主体、场景和用途。'
   },
   size: {
     type: 'string',
-    description: 'Image size, for example 1024x1024.',
-    default: '1024x1024'
+    description: `图片尺寸。支持 auto、常用尺寸 ${POPULAR_IMAGE_SIZES.map((item) => `${item.label} ${item.size}`).join('、')}，也支持满足约束的自定义宽高，例如 9:16 可用 1152x2048 或 2160x3840。`
   },
   quality: {
     type: 'string',
-    description: 'Image quality.',
-    default: 'high'
+    description: '图片质量。生图前应让用户确认速度优先还是质量优先。',
+    enum: IMAGE_QUALITY_LEVELS
   },
   format: {
     type: 'string',
-    description: 'Output image format.',
-    enum: ['png', 'jpeg', 'webp'],
-    default: 'png'
+    description: '输出图片格式。',
+    enum: IMAGE_FORMATS
+  },
+  output_format: {
+    type: 'string',
+    description: '输出图片格式别名，和 format 等价。',
+    enum: IMAGE_FORMATS
   },
   output_path: {
     type: 'string',
-    description: 'Optional output file path or directory.'
+    description: '保存路径，可以是目录或完整文件路径。缺少时建议先询问用户想保存到哪里。'
   },
   overwrite: {
     type: 'boolean',
-    description: 'Overwrite output_path when it already exists. Defaults to false.',
+    description: '文件已存在时是否覆盖。默认 false，会自动生成 -v2、-v3 等新文件名。',
     default: false
   },
   idempotency_key: {
     type: 'string',
-    description: 'Optional idempotency key. Reusing it returns the same local job in this MCP process.'
+    description: '幂等键。客户端超时后用同一个 key 重试，会复用同一进程内的本地任务，避免重复生成。'
+  },
+  image: {
+    type: 'string',
+    description: '单张输入图片，支持 data URL、HTTPS URL 或本地文件路径，用于图生图或编辑。'
   },
   images: {
     type: 'array',
     items: { type: 'string' },
-    description: 'Optional input images for image-to-image or edit. Values may be data URLs, HTTPS URLs, or local file paths.'
+    description: '多张输入图片，支持 data URL、HTTPS URL 或本地文件路径，用于图生图或编辑。'
   },
   image_path: {
     type: 'string',
-    description: 'Optional single local image path alias for image-to-image or edit.'
+    description: '单张本地输入图片路径别名，用于图生图或编辑。'
   },
   image_paths: {
     type: 'array',
     items: { type: 'string' },
-    description: 'Optional local image path aliases for image-to-image or edit.'
+    description: '多张本地输入图片路径别名，用于图生图或编辑。'
   },
   input_image: {
     type: 'string',
-    description: 'Optional single input image alias. Accepts a data URL, HTTPS URL, or local file path.'
+    description: '单张输入图片别名，支持 data URL、HTTPS URL 或本地文件路径。'
   },
   input_images: {
     type: 'array',
     items: { type: 'string' },
-    description: 'Optional input image aliases. Accepts data URLs, HTTPS URLs, or local file paths.'
+    description: '多张输入图片别名，支持 data URL、HTTPS URL 或本地文件路径。'
   },
   mask: {
     type: 'string',
-    description: 'Optional mask image for image edit. Value may be a data URL, HTTPS URL, or local file path.'
+    description: '编辑遮罩图片，支持 data URL、HTTPS URL 或本地文件路径。'
   },
   mask_path: {
     type: 'string',
-    description: 'Optional local mask image path alias for image edit.'
+    description: '本地遮罩图片路径别名。'
   },
   input_fidelity: {
     type: 'string',
-    description: 'Accepted for compatibility. The GPTeam Image 2 bridge currently ignores this option because the upstream Codex image tool rejects it on edits.',
+    description: '兼容字段。当前 GPTeam Image 2 桥接会忽略该字段，因为上游 Codex 图片工具会拒绝 edits 中的该参数。',
     enum: ['low', 'high']
   },
+  background: {
+    type: 'string',
+    description: '背景策略。gpt-image-2 当前支持 auto 或 opaque。',
+    enum: IMAGE_BACKGROUND_OPTIONS
+  },
+  moderation: {
+    type: 'string',
+    description: '内容安全策略。通常保持 auto，需要更低过滤强度时可用 low。',
+    enum: IMAGE_MODERATION_OPTIONS
+  },
+  output_compression: {
+    type: 'integer',
+    description: '输出压缩比例，0 到 100 的整数。'
+  },
+  include_revised_prompt: {
+    type: 'boolean',
+    description: '是否返回上游修订后的提示词。',
+    default: true
+  },
   return_revised_prompt: {
     type: 'boolean',
-    description: 'Return upstream revised prompt when available.',
+    description: '是否返回上游修订后的提示词，兼容旧字段。',
     default: true
   }
 };
@@ -94,7 +126,7 @@ const imageInputProperties = {
 const tools = [
   {
     name: 'create_image_job',
-    description: 'Recommended for normal use. Create a local background GPTeam Image 2 job and return immediately with a job_id.',
+    description: `推荐常规使用。创建本地后台 GPTeam Image 2 任务并立即返回 job_id。${imageToolPromptingInstruction}`,
     inputSchema: {
       type: 'object',
       properties: imageInputProperties,
@@ -104,22 +136,22 @@ const tools = [
   },
   {
     name: 'get_image_job_status',
-    description: 'Get the status of a local GPTeam Image 2 job.',
+    description: '查询本地 GPTeam Image 2 图片任务状态。',
     inputSchema: jobIDSchema()
   },
   {
     name: 'cancel_image_job',
-    description: 'Cancel a local GPTeam Image 2 job when it is still queued or running.',
+    description: '取消仍在 queued 或 running 的本地 GPTeam Image 2 图片任务。取消是 best-effort，上游已开始生成时不保证同步取消。',
     inputSchema: jobIDSchema()
   },
   {
     name: 'download_image_result',
-    description: 'Return the saved local file metadata and image content for a completed image job.',
+    description: '下载已完成图片任务的本地文件元数据和图片内容，可选择只返回 metadata。',
     inputSchema: downloadSchema()
   },
   {
     name: 'get_capabilities',
-    description: 'Return GPTeam Image MCP capabilities, supported sizes, formats, quality levels, async support, and queue limits.',
+    description: '返回 GPTeam Image MCP 能力，包括支持尺寸、格式、质量、异步任务、取消语义、队列上限和参数约束。',
     inputSchema: {
       type: 'object',
       properties: {},
@@ -128,7 +160,7 @@ const tools = [
   },
   {
     name: 'generate_image',
-    description: 'Compatibility tool. Generate an image through GPTeam Image 2, wait for completion, and save it locally.',
+    description: `兼容旧调用的异步别名。为避免长图或高质量任务导致 MCP 连接断开，它不会等待图片完成，而是创建任务并立即返回 job_id；之后必须用 get_image_job_status 和 download_image_result 获取结果。${imageToolPromptingInstruction}`,
     inputSchema: {
       type: 'object',
       properties: imageInputProperties,
@@ -192,7 +224,7 @@ export async function callImageTool(toolName, args = {}, deps = {}) {
     case 'get_capabilities':
       return getCapabilities(deps);
     case 'generate_image':
-      return await generateImage(args || {}, deps);
+      return createImageJob(args || {}, deps);
     default:
       throw new McpError(ErrorCode.InvalidParams, `未知工具：${toolName}`);
     }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "gpteam",
-  "version": "0.1.22",
+  "version": "0.1.24",
   "description": "GPTeam API interactive client configurator and ingress benchmark CLI.",
   "type": "module",
   "bin": {