gpteam 0.1.21 → 0.1.23

package/README.md

@@ -27,7 +27,7 @@ The Image MCP exposes both a synchronous compatibility tool and a local async jo
 
 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`.
 
-The MCP supports normal text-to-image generation and image-to-image/edit inputs. Pass `images` as data URLs, HTTPS URLs, or local file paths. Pass `mask` the same way for masked edits. `input_fidelity` is accepted for compatibility but is not forwarded to the current GPTeam Image 2 bridge because upstream Codex image edits reject it. The MCP requests GPTeam image endpoints with `stream=true` and reads the final image event, so long image jobs get early stream bytes instead of sitting idle until the final JSON body. File writes create missing directories, avoid overwriting existing files by adding `-v2`, `-v3`, etc., and validate PNG/JPEG/WebP before returning success. `overwrite: true` is available for explicit replacement. `return_revised_prompt` controls whether the upstream revised prompt is included in the result.
+The MCP supports normal text-to-image generation and image-to-image/edit inputs. Pass `images` as data URLs, HTTPS URLs, or local file paths. For easier tool calling, `image`, `image_path`, `image_paths`, `input_image`, and `input_images` are accepted as aliases. Pass `mask` or `mask_path` the same way for masked edits. `input_fidelity` is accepted for compatibility but is not forwarded to the current GPTeam Image 2 bridge because upstream Codex image edits reject it. The MCP requests GPTeam image endpoints with `stream=true` and reads the final image event, so long image jobs get early stream bytes instead of sitting idle until the final JSON body. File writes create missing directories, avoid overwriting existing files by adding `-v2`, `-v3`, etc., and validate PNG/JPEG/WebP before returning success. `overwrite: true` is available for explicit replacement. `return_revised_prompt` controls whether the upstream revised prompt is included in the result.
 
 Claude Code is written to `~/.claude/settings.json` under the `env` section, using the GPTeam `/anthropic` base URL. OpenClaw writes `models.providers.gpteam` and also selects `gpteam/<model>` under `agents.defaults.model`, so the chosen model is active without an extra manual step.
 

package/lib/help.js

@@ -1,5 +1,5 @@
 export const PACKAGE_NAME = 'gpteam';
-export const PACKAGE_VERSION = '0.1.21';
+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,15 +55,16 @@ 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(input.images || input.image, imageOptions);
+  const images = normalizeInputImages(collectInputImageValues(input), imageOptions);
   if (images.length > 0) payload.images = images.map((imageURL) => ({ image_url: imageURL }));
-  const mask = normalizeImageReference(input.mask, imageOptions);
+  const mask = normalizeImageReference(firstPresentImageReference(input.mask, input.mask_path), imageOptions);
   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);
@@ -286,9 +307,20 @@ export function getCapabilities(options = {}) {
     supports_idempotency_key: true,
     supports_image_to_image: true,
     supports_mask: true,
-    sizes: ['1024x1024', '1536x1024', '1024x1536', 'auto'],
-    formats: ['png', 'jpeg', 'webp'],
-    quality: ['low', 'medium', 'high', 'auto'],
+    image_input_fields: ['images', 'image', 'image_path', 'image_paths', 'input_image', 'input_images'],
+    mask_input_fields: ['mask', 'mask_path'],
+    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,
@@ -299,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);
@@ -632,6 +680,36 @@ function normalizeInputImages(value, options = {}) {
   return rawImages.map((item) => normalizeImageReference(item, options)).filter(Boolean);
 }
 
+function collectInputImageValues(input = {}) {
+  const values = [];
+  appendImageAlias(values, input.images);
+  appendImageAlias(values, input.image);
+  appendImageAlias(values, input.image_path);
+  appendImageAlias(values, input.image_paths);
+  appendImageAlias(values, input.input_image);
+  appendImageAlias(values, input.input_images);
+  return values;
+}
+
+function appendImageAlias(target, value) {
+  if (Array.isArray(value)) {
+    for (const item of value) appendImageAlias(target, item);
+    return;
+  }
+  if (value) target.push(value);
+}
+
+function firstPresentImageReference(...values) {
+  for (const value of values) {
+    if (Array.isArray(value)) {
+      if (value.length > 0) return value[0];
+      continue;
+    }
+    if (value) return value;
+  }
+  return '';
+}
+
 function normalizeImageReference(value, options = {}) {
   if (!value) return '';
   if (typeof value === 'object') {
@@ -690,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,63 +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: '单张本地输入图片路径别名，用于图生图或编辑。'
+  },
+  image_paths: {
+    type: 'array',
+    items: { type: 'string' },
+    description: '多张本地输入图片路径别名，用于图生图或编辑。'
+  },
+  input_image: {
+    type: 'string',
+    description: '单张输入图片别名，支持 data URL、HTTPS URL 或本地文件路径。'
+  },
+  input_images: {
+    type: 'array',
+    items: { type: 'string' },
+    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: '本地遮罩图片路径别名。'
   },
   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
   }
 };
@@ -72,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,
@@ -82,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: {},
@@ -106,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.21",
+  "version": "0.1.23",
   "description": "GPTeam API interactive client configurator and ingress benchmark CLI.",
   "type": "module",
   "bin": {