gpteam 0.1.22 → 0.1.23

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.23';
 
 export function getHelpText() {
   return [

package/lib/image-mcp/image.js

@@ -14,6 +14,29 @@ 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;
@@ -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);
@@ -288,9 +309,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 +331,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 +768,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

@@ -8,85 +8,118 @@ import {
   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 = '调用前请先确认用户真实需求：尺寸或比例、质量、输出格式、保存目录或文件名。缺少这些关键信息时应先追问，不要直接默认生成。';
+
 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 +127,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 +137,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 +161,7 @@ const tools = [
   },
   {
     name: 'generate_image',
-    description: 'Compatibility tool. Generate an image through GPTeam Image 2, wait for completion, and save it locally.',
+    description: `兼容同步工具。通过 GPTeam Image 2 生成图片，等待完成并保存到本地。${imageToolPromptingInstruction}耗时较长时优先使用 create_image_job。`,
     inputSchema: {
       type: 'object',
       properties: imageInputProperties,

package/package.json

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