gpteam 0.1.18 → 0.1.19

package/README.md

@@ -19,12 +19,15 @@ The Image MCP config uses cc-switch-style per-client env blocks. Codex writes `[
 The Image MCP exposes both a synchronous compatibility tool and a local async job flow:
 
 - `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, or cancelled.
+- `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.
+- `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.
 
-Image MCP results are returned as stable JSON text and MCP `structuredContent`. Successful results include file path, model, size, format, quality, byte size, SHA-256, MIME type, image dimensions, duration, retry count, `job_id`, and `trace_id`. The image bytes are returned as MCP image content, not embedded in structured JSON. File writes create missing directories, avoid overwriting existing files by adding `-v2`, `-v3`, etc., and validate PNG/JPEG/WebP before returning success. `return_revised_prompt` controls whether the upstream revised prompt is included in the result.
+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, and use `input_fidelity` when needed. 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/cli.js

@@ -72,7 +72,7 @@ export async function runCli(argv = []) {
     console.log(`入口：${formatNodeLabel(selectedNode)}`);
     console.log(`地址：${selectedNode.baseUrl}`);
     if (['codex', 'opencode', 'claude-code'].includes(client.id)) {
-      printHint(theme, '已写入 GPTeam Image MCP。客户端对话里需要生图时优先调用 create_image_job，再用 get_image_job_status 和 download_image_result 取结果，MCP 使用专用环境变量读取 API key。');
+      printHint(theme, '已写入 GPTeam Image MCP。客户端对话里需要生图或图生图时优先调用 create_image_job，再用 get_image_job_status 和 download_image_result 取结果，get_capabilities 可查看支持能力，MCP 使用专用环境变量读取 API key。');
     }
   } finally {
     rl.close();

package/lib/config.js

@@ -13,6 +13,7 @@ const IMAGE_MCP_ENABLED_TOOLS = [
   'get_image_job_status',
   'download_image_result',
   'cancel_image_job',
+  'get_capabilities',
   'generate_image'
 ];
 

package/lib/help.js

@@ -1,5 +1,5 @@
 export const PACKAGE_NAME = 'gpteam';
-export const PACKAGE_VERSION = '0.1.18';
+export const PACKAGE_VERSION = '0.1.19';
 
 export function getHelpText() {
   return [
@@ -22,6 +22,6 @@ export function getHelpText() {
     '  --help                  显示帮助',
     '  --version               显示版本',
     '',
-    '说明：输入 key 后会先请求 /v1/models 校验，通过后才继续。选好客户端后会检测本机命令是否可用，缺失时提示安装。Windows 暂不支持自动配置 OpenClaw。测速会请求 GET /api/health 和流式 POST /v1/responses。入口之间并行测速，写新配置前会先备份旧配置。Codex、OpenCode、Claude Code 会写入 GPTeam Image MCP，生图工具从 MCP env 读取 key，长时间生图优先用 create_image_job 异步任务。'
+    '说明：输入 key 后会先请求 /v1/models 校验，通过后才继续。选好客户端后会检测本机命令是否可用，缺失时提示安装。Windows 暂不支持自动配置 OpenClaw。测速会请求 GET /api/health 和流式 POST /v1/responses。入口之间并行测速，写新配置前会先备份旧配置。Codex、OpenCode、Claude Code 会写入 GPTeam Image MCP，生图和图生图工具从 MCP env 读取 key，长时间任务优先用 create_image_job 异步任务，get_capabilities 可查看支持能力。'
   ].join('\n');
 }

package/lib/image-mcp/errors.js

@@ -6,8 +6,10 @@ export class ImageMCPError extends Error {
     this.name = 'ImageMCPError';
     this.code = String(options.code || 'image_mcp_error');
     this.category = String(options.category || 'unknown');
+    this.stage = String(options.stage || stageFromCategory(this.category));
     this.retryable = Boolean(options.retryable);
     this.http_status = Number.isFinite(options.http_status) ? options.http_status : undefined;
+    this.upstream_status = Number.isFinite(options.upstream_status) ? options.upstream_status : this.http_status;
     this.details = options.details || undefined;
   }
 }
@@ -23,6 +25,7 @@ export async function imageErrorFromHTTPResponse(response, apiKey) {
     return new ImageMCPError(message, {
       code: upstreamCode || 'rate_limit_exceeded',
       category: 'upstream_rate_limit',
+      stage: 'upstream',
       http_status: status,
       retryable: true
     });
@@ -31,6 +34,7 @@ export async function imageErrorFromHTTPResponse(response, apiKey) {
     return new ImageMCPError(message, {
       code: upstreamCode || 'upstream_server_error',
       category: status === 408 ? 'timeout' : 'upstream_server',
+      stage: 'upstream',
       http_status: status,
       retryable: true
     });
@@ -39,6 +43,7 @@ export async function imageErrorFromHTTPResponse(response, apiKey) {
     return new ImageMCPError(message, {
       code: upstreamCode || 'content_safety_rejected',
       category: 'content_safety',
+      stage: 'upstream',
       http_status: status,
       retryable: false
     });
@@ -46,6 +51,7 @@ export async function imageErrorFromHTTPResponse(response, apiKey) {
   return new ImageMCPError(message, {
     code: upstreamCode || (status === 401 || status === 403 ? 'authentication_failed' : 'invalid_request_error'),
     category: status === 401 || status === 403 ? 'authentication' : 'parameter',
+    stage: status === 401 || status === 403 ? 'upstream' : 'validate',
     http_status: status,
     retryable: false
   });
@@ -55,7 +61,8 @@ export function imageErrorFromFetch(error, options = {}) {
   if (options.cancelled) {
     return new ImageMCPError('图片生成任务已取消。', {
       code: 'job_cancelled',
-      category: 'cancelled',
+      category: 'canceled',
+      stage: 'cancel',
       retryable: false
     });
   }
@@ -64,25 +71,33 @@ export function imageErrorFromFetch(error, options = {}) {
   return new ImageMCPError(message, {
     code: timeoutLike ? 'network_timeout' : 'network_error',
     category: timeoutLike ? 'timeout' : 'network',
+    stage: 'network',
     retryable: true
   });
 }
 
-export function serializeImageError(error) {
+export function serializeImageError(error, meta = {}) {
   if (error instanceof ImageMCPError) {
     return {
       code: error.code,
-      category: error.category,
+      message: error.message,
       retryable: error.retryable,
+      stage: error.stage,
+      upstream_status: error.upstream_status,
+      trace_id: meta.trace_id || '',
+      category: error.category,
       http_status: error.http_status,
-      message: error.message
+      details: error.details
     };
   }
   return {
     code: 'image_mcp_error',
-    category: 'unknown',
+    message: error && error.message ? String(error.message) : String(error || 'unknown error'),
     retryable: false,
-    message: error && error.message ? String(error.message) : String(error || 'unknown error')
+    stage: 'unknown',
+    upstream_status: undefined,
+    trace_id: meta.trace_id || '',
+    category: 'unknown'
   };
 }
 
@@ -114,3 +129,33 @@ function isContentSafetyError(code, message) {
   const text = `${code || ''} ${message || ''}`.toLowerCase();
   return /content|safety|policy|moderation/.test(text);
 }
+
+function stageFromCategory(category) {
+  switch (String(category || '').toLowerCase()) {
+  case 'parameter':
+    return 'validate';
+  case 'configuration':
+  case 'environment':
+    return 'configuration';
+  case 'file_system':
+  case 'response_invalid':
+    return 'local';
+  case 'authentication':
+  case 'content_safety':
+  case 'upstream_rate_limit':
+  case 'upstream_server':
+    return 'upstream';
+  case 'timeout':
+  case 'network':
+    return 'network';
+  case 'canceled':
+  case 'cancelled':
+    return 'cancel';
+  case 'not_found':
+    return 'lookup';
+  case 'queue':
+    return 'queue';
+  default:
+    return 'unknown';
+  }
+}

package/lib/image-mcp/files.js

@@ -8,11 +8,15 @@ export const DEFAULT_IMAGE_FORMAT = 'png';
 
 export function writeImageOutput(input = {}, options = {}) {
   const bytes = decodeBase64Image(input.b64);
-  const image = inspectImage(bytes);
+  const image = inspectImageBytes(bytes);
   const format = image.format || normalizeImageFormat(input.format || input.output_format || DEFAULT_IMAGE_FORMAT);
-  const outputPath = writeImageFileNonOverwriting(input.output_path, format, bytes, options);
+  const outputPath = writeImageFile(input.output_path, format, bytes, {
+    ...options,
+    overwrite: Boolean(input.overwrite)
+  });
   return {
     file: outputPath,
+    final_file: outputPath,
     path: outputPath,
     bytes: bytes.length,
     sha256: crypto.createHash('sha256').update(bytes).digest('hex'),
@@ -25,6 +29,23 @@ export function writeImageOutput(input = {}, options = {}) {
   };
 }
 
+export function localImageToDataURL(rawPath, options = {}) {
+  const filePath = path.resolve(expandHome(String(rawPath || ''), options.home || os.homedir()));
+  const bytes = fs.readFileSync(filePath);
+  const image = inspectImageBytes(bytes);
+  return `data:${image.mime_type};base64,${bytes.toString('base64')}`;
+}
+
+function writeImageFile(rawOutputPath, format, bytes, options) {
+  if (options.overwrite) {
+    const outputPath = resolveOutputPath(rawOutputPath, format, options);
+    fs.mkdirSync(path.dirname(outputPath), { recursive: true });
+    atomicReplaceFile(outputPath, bytes);
+    return outputPath;
+  }
+  return writeImageFileNonOverwriting(rawOutputPath, format, bytes, options);
+}
+
 function writeImageFileNonOverwriting(rawOutputPath, format, bytes, options) {
   let lastConflict;
   for (let attempt = 0; attempt < 10000; attempt += 1) {
@@ -41,6 +62,7 @@ function writeImageFileNonOverwriting(rawOutputPath, format, bytes, options) {
   throw lastConflict || new ImageMCPError('无法生成不覆盖现有文件的输出路径。', {
     code: 'output_path_conflict',
     category: 'file_system',
+    stage: 'local',
     retryable: false
   });
 }
@@ -58,6 +80,7 @@ function decodeBase64Image(value) {
     throw new ImageMCPError('GPTeam 图片接口没有返回 b64_json 图片数据。', {
       code: 'image_data_missing',
       category: 'response_invalid',
+      stage: 'local',
       retryable: false
     });
   }
@@ -66,13 +89,14 @@ function decodeBase64Image(value) {
     throw new ImageMCPError('GPTeam 图片接口返回的图片数据为空。', {
       code: 'image_data_empty',
       category: 'response_invalid',
+      stage: 'local',
       retryable: false
     });
   }
   return bytes;
 }
 
-function inspectImage(bytes) {
+export function inspectImageBytes(bytes) {
   const png = inspectPNG(bytes);
   if (png) return png;
   const jpeg = inspectJPEG(bytes);
@@ -82,6 +106,7 @@ function inspectImage(bytes) {
   throw new ImageMCPError('写入前图片校验失败：无法识别 PNG/JPEG/WebP。', {
     code: 'image_mime_invalid',
     category: 'response_invalid',
+    stage: 'local',
     retryable: false
   });
 }
@@ -152,6 +177,7 @@ function resolveAvailableOutputPath(rawOutputPath, format, options) {
   throw new ImageMCPError('无法生成不覆盖现有文件的输出路径。', {
     code: 'output_path_conflict',
     category: 'file_system',
+    stage: 'local',
     retryable: false
   });
 }
@@ -162,11 +188,11 @@ function resolveOutputPath(rawOutputPath, format, options) {
   const name = `gpteam-image-${new Date().toISOString().replace(/[-:]/g, '').replace(/\..+/, '').replace('T', '-')}.${format}`;
   if (rawOutputPath) {
     const expanded = expandHome(String(rawOutputPath), home);
-    if (isDirectoryLike(expanded)) return path.join(expanded, name);
-    return withImageExtension(expanded, format);
+    if (isDirectoryLike(expanded)) return path.resolve(expanded, name);
+    return path.resolve(withImageExtension(expanded, format));
   }
   const outputDir = expandHome(firstNonEmpty(env.GPTEAM_IMAGE_OUTPUT_DIR, defaultImageOutputDir(home)), home);
-  return path.join(outputDir, name);
+  return path.resolve(outputDir, name);
 }
 
 function atomicWriteFile(outputPath, bytes) {
@@ -201,6 +227,39 @@ function atomicWriteFile(outputPath, bytes) {
     throw new ImageMCPError(conflict ? '输出文件已存在，正在重新选择不覆盖路径。' : `图片文件写入失败：${error.message}`, {
       code: conflict ? 'output_path_conflict' : 'file_write_failed',
       category: 'file_system',
+      stage: 'local',
+      retryable: false
+    });
+  }
+}
+
+function atomicReplaceFile(outputPath, bytes) {
+  const tempPath = path.join(path.dirname(outputPath), `.${path.basename(outputPath)}.${process.pid}.${Date.now()}.${crypto.randomBytes(6).toString('hex')}.tmp`);
+  let fd;
+  try {
+    fd = fs.openSync(tempPath, 'wx', 0o600);
+    fs.writeFileSync(fd, bytes);
+    fs.fsyncSync(fd);
+    fs.closeSync(fd);
+    fd = undefined;
+    fs.renameSync(tempPath, outputPath);
+  } catch (error) {
+    if (fd !== undefined) {
+      try {
+        fs.closeSync(fd);
+      } catch {
+        // 忽略关闭临时文件失败，下面会清理临时路径。
+      }
+    }
+    try {
+      fs.rmSync(tempPath, { force: true });
+    } catch {
+      // 忽略清理失败，返回主要写入错误。
+    }
+    throw new ImageMCPError(`图片文件写入失败：${error.message}`, {
+      code: 'file_write_failed',
+      category: 'file_system',
+      stage: 'local',
       retryable: false
     });
   }

package/lib/image-mcp/image.js

@@ -8,7 +8,7 @@ import {
   redactSecret,
   serializeImageError
 } from './errors.js';
-import { DEFAULT_IMAGE_FORMAT, normalizeImageFormat, writeImageOutput } from './files.js';
+import { DEFAULT_IMAGE_FORMAT, localImageToDataURL, normalizeImageFormat, writeImageOutput } from './files.js';
 
 export const DEFAULT_BASE_URL = 'https://api.gpteamservices.com/v1';
 export const DEFAULT_IMAGE_MODEL = 'gpt-image-2';
@@ -17,11 +17,15 @@ export { DEFAULT_IMAGE_FORMAT };
 const defaultMaxAttempts = 3;
 const defaultRetryDelayMs = 800;
 const defaultRequestTimeoutMs = 5 * 60 * 1000;
+const defaultMaxConcurrentJobs = 2;
+const defaultMaxQueuedJobs = 20;
+const defaultJobTTLMS = 30 * 60 * 1000;
+const terminalStatuses = new Set(['succeeded', 'failed', 'canceled', 'expired']);
 
 const defaultJobStore = createImageJobStore();
 
-export function buildImageGenerationPayload(input = {}) {
-  return {
+export function buildImageGenerationPayload(input = {}, options = {}) {
+  const payload = {
     model: String(input.model || DEFAULT_IMAGE_MODEL),
     prompt: String(input.prompt || '').trim(),
     response_format: 'b64_json',
@@ -29,6 +33,15 @@ export function buildImageGenerationPayload(input = {}) {
     quality: String(input.quality || 'high'),
     output_format: normalizeImageFormat(input.format || input.output_format || DEFAULT_IMAGE_FORMAT)
   };
+  const imageOptions = { ...options, home: options.home };
+  const images = normalizeInputImages(input.images || input.image, imageOptions);
+  if (images.length > 0) payload.images = images.map((imageURL) => ({ image_url: imageURL }));
+  const mask = normalizeImageReference(input.mask, imageOptions);
+  if (mask) payload.mask = { image_url: mask };
+  copyOptionalImageToolOption(payload, input, 'background');
+  copyOptionalImageToolOption(payload, input, 'moderation');
+  copyOptionalImageToolOption(payload, input, 'input_fidelity');
+  return payload;
 }
 
 export function loadGPTeamCredentials(options = {}) {
@@ -42,6 +55,7 @@ export function loadGPTeamCredentials(options = {}) {
     throw new ImageMCPError('没有找到 GPTeam API key。请在 MCP 配置 env 中设置 GPTEAM_API_KEY，或先运行 npx gpteam 完成本地配置。', {
       code: 'api_key_missing',
       category: 'configuration',
+      stage: 'configuration',
       retryable: false
     });
   }
@@ -79,16 +93,18 @@ export async function generateImage(input = {}, options = {}) {
     throw new ImageMCPError('prompt 不能为空', {
       code: 'prompt_required',
       category: 'parameter',
+      stage: 'validate',
       retryable: false
     });
   }
   const credentials = loadGPTeamCredentials(options);
-  const payload = buildImageGenerationPayload(input);
+  const payload = buildImageGenerationPayload(input, options);
   const fetchImpl = options.fetch || globalThis.fetch;
   if (typeof fetchImpl !== 'function') {
     throw new ImageMCPError('当前 Node.js 运行时不支持 fetch，请升级到 Node.js 18.18 或更高版本。', {
       code: 'fetch_unavailable',
       category: 'environment',
+      stage: 'configuration',
       retryable: false
     });
   }
@@ -99,6 +115,7 @@ export async function generateImage(input = {}, options = {}) {
   const file = writeImageOutput({
     b64: result.b64,
     output_path: input.output_path,
+    overwrite: input.overwrite,
     format
   }, options);
   const includeRevisedPrompt = resolveRevisedPromptFlag(input);
@@ -111,37 +128,65 @@ export async function generateImage(input = {}, options = {}) {
     b64: result.b64,
     revisedPrompt: includeRevisedPrompt ? result.revisedPrompt : '',
     retryCount: result.retryCount,
-    durationMs
+    durationMs,
+    idempotencyKey: normalizeIdempotencyKey(input.idempotency_key)
   });
 }
 
 export function createImageJobStore(options = {}) {
   return {
     jobs: new Map(),
+    queue: [],
+    runningCount: 0,
+    idempotency: new Map(),
     now: typeof options.now === 'function' ? options.now : Date.now,
-    ttlMs: Number(options.ttlMs || 30 * 60 * 1000)
+    ttlMs: Number(options.ttlMs || defaultJobTTLMS),
+    maxConcurrent: Number.isFinite(options.maxConcurrent) ? options.maxConcurrent : defaultMaxConcurrentJobs,
+    maxQueue: Number.isFinite(options.maxQueue) ? options.maxQueue : defaultMaxQueuedJobs
   };
 }
 
 export function createImageJob(input = {}, options = {}) {
   const store = options.store || defaultJobStore;
+  configureJobStore(store, options);
   cleanupImageJobs(store);
+  const idempotencyKey = normalizeIdempotencyKey(input.idempotency_key);
+  if (idempotencyKey) {
+    const existingJobID = store.idempotency.get(idempotencyKey);
+    const existingJob = existingJobID ? store.jobs.get(existingJobID) : null;
+    if (existingJob) return publicJobStatus(existingJob);
+    store.idempotency.delete(idempotencyKey);
+  }
+  if ((queuedJobCount(store) + store.runningCount) >= (store.maxConcurrent + store.maxQueue)) {
+    return resultFromError(new ImageMCPError('图片任务队列已满，请稍后重试。', {
+      code: 'queue_full',
+      category: 'queue',
+      stage: 'queue',
+      retryable: true
+    }));
+  }
   const jobID = makeID('img');
   const traceID = makeID('tr');
   const controller = new AbortController();
   const job = {
     job_id: jobID,
     trace_id: traceID,
+    idempotency_key: idempotencyKey,
     status: 'queued',
     ok: true,
     created_at: new Date(store.now()).toISOString(),
     updated_at: new Date(store.now()).toISOString(),
+    expires_at: new Date(store.now() + store.ttlMs).toISOString(),
     controller,
+    input: { ...input, idempotency_key: idempotencyKey },
+    options,
     result: null,
     error: null
   };
   store.jobs.set(jobID, job);
-  queueMicrotask(() => runImageJob(store, job, input, options));
+  if (idempotencyKey) store.idempotency.set(idempotencyKey, jobID);
+  store.queue.push(jobID);
+  queueMicrotask(() => scheduleImageJobs(store));
   return publicJobStatus(job);
 }
 
@@ -157,18 +202,26 @@ export function cancelImageJob(input = {}, options = {}) {
   const store = options.store || defaultJobStore;
   const job = store.jobs.get(String(input.job_id || ''));
   if (!job) return missingJobResult(input.job_id);
-  if (job.status === 'succeeded' || job.status === 'failed') return publicJobStatus(job);
+  if (isTerminalStatus(job.status)) return publicJobStatus(job);
   job.controller.abort();
-  job.status = 'cancelled';
+  job.status = 'canceled';
   job.ok = false;
   job.updated_at = new Date(store.now()).toISOString();
   job.error = {
     code: 'job_cancelled',
-    category: 'cancelled',
+    message: '图片生成任务已取消。',
     retryable: false,
-    message: '图片生成任务已取消。'
+    stage: 'cancel',
+    upstream_status: undefined,
+    trace_id: job.trace_id,
+    category: 'canceled'
+  };
+  return {
+    ...publicJobStatus(job),
+    ok: true,
+    cancellation_mode: 'best_effort',
+    cancellation_note: '已中止本地请求。若上游已经开始生成，无法保证上游也同步取消。'
   };
-  return { ...publicJobStatus(job), ok: true };
 }
 
 export function downloadImageResult(input = {}, options = {}) {
@@ -176,12 +229,23 @@ export function downloadImageResult(input = {}, options = {}) {
   const job = store.jobs.get(String(input.job_id || ''));
   if (!job) return missingJobResult(input.job_id);
   if (job.status !== 'succeeded') return publicJobStatus(job);
-  return { ...job.result, status: 'succeeded' };
+  return shapeDownloadResult(job.result, input);
 }
 
 export function structuredToolResult(result) {
   if (!result || typeof result !== 'object') {
-    return { ok: false, error: { code: 'empty_result', category: 'unknown', retryable: false, message: 'empty result' } };
+    return {
+      ok: false,
+      error: {
+        code: 'empty_result',
+        message: 'empty result',
+        retryable: false,
+        stage: 'unknown',
+        upstream_status: undefined,
+        trace_id: '',
+        category: 'unknown'
+      }
+    };
   }
   const clone = { ...result };
   delete clone.b64;
@@ -206,7 +270,32 @@ export function resultFromError(error, meta = {}) {
     job_id: meta.job_id || '',
     trace_id: meta.trace_id || '',
     status: 'failed',
-    error: serializeImageError(error)
+    error: serializeImageError(error, meta)
+  };
+}
+
+export function getCapabilities(options = {}) {
+  const env = options.env || process.env;
+  return {
+    ok: true,
+    model: DEFAULT_IMAGE_MODEL,
+    default_model: DEFAULT_IMAGE_MODEL,
+    supports_async: true,
+    supports_cancel: true,
+    cancel_semantics: 'best_effort',
+    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'],
+    max_prompt_length: 32000,
+    statuses: ['queued', 'running', 'succeeded', 'failed', 'canceled', 'expired'],
+    default_output_format: DEFAULT_IMAGE_FORMAT,
+    default_request_timeout_ms: resolveBoundedInt(1, env.GPTEAM_IMAGE_REQUEST_TIMEOUT_MS, defaultRequestTimeoutMs),
+    default_max_attempts: resolveBoundedInt(1, env.GPTEAM_IMAGE_MAX_ATTEMPTS, defaultMaxAttempts),
+    max_concurrent_jobs: resolveBoundedInt(1, env.GPTEAM_IMAGE_MAX_CONCURRENT, defaultMaxConcurrentJobs),
+    max_queued_jobs: resolveBoundedInt(0, env.GPTEAM_IMAGE_MAX_QUEUE, defaultMaxQueuedJobs)
   };
 }
 
@@ -230,8 +319,9 @@ async function fetchImageWithRetry(fetchImpl, credentials, payload, options) {
 
 async function fetchImageOnce(fetchImpl, credentials, payload, options) {
   const requestSignal = createRequestSignal(options);
+  const endpoint = imageEndpointFromPayload(payload);
   try {
-    const response = await fetchImpl(`${credentials.baseUrl}/images/generations`, {
+    const response = await fetchImpl(`${credentials.baseUrl}${endpoint}`, {
       method: 'POST',
       headers: {
         Authorization: `Bearer ${credentials.apiKey}`,
@@ -246,9 +336,10 @@ async function fetchImageOnce(fetchImpl, credentials, payload, options) {
     const b64 = first && typeof first.b64_json === 'string' ? first.b64_json : '';
     if (!b64) {
       throw new ImageMCPError('GPTeam 图片接口没有返回 b64_json 图片数据。', {
-        code: 'image_data_missing',
-        category: 'response_invalid',
-        retryable: false
+      code: 'image_data_missing',
+      category: 'response_invalid',
+      stage: 'local',
+      retryable: false
       });
     }
     return {
@@ -272,8 +363,10 @@ function buildSuccessResult(input) {
     ok: true,
     status: 'succeeded',
     file: input.file.file,
+    final_file: input.file.final_file,
     path: input.file.file,
     model: input.payload.model,
+    action: imageActionFromPayload(input.payload),
     size: input.payload.size,
     format: input.file.format,
     output_format: input.file.format,
@@ -288,6 +381,7 @@ function buildSuccessResult(input) {
     retry_count: input.retryCount,
     job_id: input.jobID,
     trace_id: input.traceID,
+    idempotency_key: input.idempotencyKey || undefined,
     b64: input.b64
   };
   if (input.revisedPrompt) {
@@ -297,38 +391,58 @@ function buildSuccessResult(input) {
   return result;
 }
 
-async function runImageJob(store, job, input, options) {
-  if (job.status === 'cancelled') return;
+function scheduleImageJobs(store) {
+  cleanupImageJobs(store);
+  while (store.runningCount < store.maxConcurrent && store.queue.length > 0) {
+    const jobID = store.queue.shift();
+    const job = store.jobs.get(jobID);
+    if (!job || job.status !== 'queued') continue;
+    store.runningCount += 1;
+    queueMicrotask(() => runImageJob(store, job));
+  }
+}
+
+async function runImageJob(store, job) {
+  if (job.status === 'canceled') {
+    store.runningCount = Math.max(0, store.runningCount - 1);
+    scheduleImageJobs(store);
+    return;
+  }
   job.status = 'running';
   job.updated_at = new Date(store.now()).toISOString();
   try {
-    const result = await generateImage({ ...input, job_id: job.job_id, trace_id: job.trace_id }, {
-      ...options,
+    const result = await generateImage({ ...job.input, job_id: job.job_id, trace_id: job.trace_id }, {
+      ...job.options,
       signal: job.controller.signal
     });
-    if (job.status === 'cancelled') return;
+    if (job.status === 'canceled') return;
     job.status = 'succeeded';
     job.ok = true;
     job.result = result;
   } catch (error) {
-    if (job.status !== 'cancelled') {
+    if (job.status !== 'canceled') {
       job.status = 'failed';
       job.ok = false;
-      job.error = serializeImageError(error);
+      job.error = serializeImageError(error, { trace_id: job.trace_id });
     }
   } finally {
     job.updated_at = new Date(store.now()).toISOString();
+    store.runningCount = Math.max(0, store.runningCount - 1);
+    scheduleImageJobs(store);
   }
 }
 
 function publicJobStatus(job) {
   const base = {
-    ok: job.status !== 'failed' && job.status !== 'cancelled',
+    ok: job.status !== 'failed' && job.status !== 'canceled' && job.status !== 'expired',
     job_id: job.job_id,
     trace_id: job.trace_id,
+    idempotency_key: job.idempotency_key || undefined,
     status: job.status,
+    legacy_status: job.status === 'canceled' ? 'cancelled' : undefined,
     created_at: job.created_at,
-    updated_at: job.updated_at
+    updated_at: job.updated_at,
+    expires_at: job.expires_at
   };
   if (job.result) return { ...base, ...structuredToolResult(job.result) };
   if (job.error) return { ...base, error: job.error };
@@ -342,9 +456,12 @@ function missingJobResult(jobID) {
     status: 'not_found',
     error: {
       code: 'job_not_found',
-      category: 'not_found',
+      message: '没有找到这个图片任务。',
       retryable: false,
-      message: '没有找到这个图片任务。'
+      stage: 'lookup',
+      upstream_status: undefined,
+      trace_id: '',
+      category: 'not_found'
     }
   };
 }
@@ -352,10 +469,116 @@ function missingJobResult(jobID) {
 function cleanupImageJobs(store) {
   const threshold = store.now() - store.ttlMs;
   for (const [jobID, job] of store.jobs.entries()) {
+    const created = Date.parse(job.created_at || '');
+    if (job.status === 'queued' && Number.isFinite(created) && created < threshold) {
+      job.status = 'expired';
+      job.ok = false;
+      job.updated_at = new Date(store.now()).toISOString();
+      job.error = {
+        code: 'job_expired',
+        message: '图片任务已过期，请重新创建任务。',
+        retryable: false,
+        stage: 'queue',
+        upstream_status: undefined,
+        trace_id: job.trace_id,
+        category: 'queue'
+      };
+    }
     if (job.status === 'queued' || job.status === 'running') continue;
     const updated = Date.parse(job.updated_at || job.created_at || '');
-    if (Number.isFinite(updated) && updated < threshold) store.jobs.delete(jobID);
+    if (Number.isFinite(updated) && updated < threshold) removeImageJob(store, jobID, job);
   }
+  store.queue = store.queue.filter((jobID) => {
+    const job = store.jobs.get(jobID);
+    return job && job.status === 'queued';
+  });
+}
+
+function configureJobStore(store, options = {}) {
+  const env = options.env || process.env;
+  store.maxConcurrent = resolveBoundedInt(1, options.maxConcurrent, env.GPTEAM_IMAGE_MAX_CONCURRENT, store.maxConcurrent || defaultMaxConcurrentJobs);
+  store.maxQueue = resolveBoundedInt(0, options.maxQueue, env.GPTEAM_IMAGE_MAX_QUEUE, store.maxQueue || defaultMaxQueuedJobs);
+}
+
+function queuedJobCount(store) {
+  return store.queue.filter((jobID) => {
+    const job = store.jobs.get(jobID);
+    return job && job.status === 'queued';
+  }).length;
+}
+
+function removeImageJob(store, jobID, job) {
+  store.jobs.delete(jobID);
+  if (job && job.idempotency_key && store.idempotency.get(job.idempotency_key) === jobID) {
+    store.idempotency.delete(job.idempotency_key);
+  }
+}
+
+function isTerminalStatus(status) {
+  return terminalStatuses.has(String(status || ''));
+}
+
+function normalizeIdempotencyKey(value) {
+  return String(value || '').trim().slice(0, 200);
+}
+
+function shapeDownloadResult(result, input = {}) {
+  const includeImage = !input.metadata_only && input.include_image !== false;
+  const includeRevisedPrompt = input.include_revised_prompt !== false;
+  const output = {
+    ...result,
+    status: 'succeeded'
+  };
+  if (!includeImage) {
+    delete output.b64;
+    delete output.mimeType;
+  }
+  if (!includeRevisedPrompt) {
+    delete output.revised_prompt;
+    delete output.revisedPrompt;
+  }
+  return output;
+}
+
+function imageEndpointFromPayload(payload) {
+  return imageActionFromPayload(payload) === 'edit' ? '/images/edits' : '/images/generations';
+}
+
+function imageActionFromPayload(payload) {
+  return Array.isArray(payload.images) && payload.images.length > 0 ? 'edit' : 'generate';
+}
+
+function normalizeInputImages(value, options = {}) {
+  const rawImages = Array.isArray(value) ? value : (value ? [value] : []);
+  return rawImages.map((item) => normalizeImageReference(item, options)).filter(Boolean);
+}
+
+function normalizeImageReference(value, options = {}) {
+  if (!value) return '';
+  if (typeof value === 'object') {
+    return normalizeImageReference(value.image_url || value.url || value.path || value.file, options);
+  }
+  const text = String(value || '').trim();
+  if (!text) return '';
+  if (/^data:image\/[a-z0-9.+-]+;base64,/i.test(text)) return text;
+  if (/^https?:\/\//i.test(text)) return text;
+  try {
+    return localImageToDataURL(text, options);
+  } catch (error) {
+    throw new ImageMCPError(`读取输入图片失败：${error.message}`, {
+      code: 'input_image_read_failed',
+      category: 'file_system',
+      stage: 'local',
+      retryable: false
+    });
+  }
+}
+
+function copyOptionalImageToolOption(payload, input, key) {
+  if (!Object.prototype.hasOwnProperty.call(input, key)) return;
+  const value = input[key];
+  if (value === undefined || value === null || value === '') return;
+  payload[key] = value;
 }
 
 function createRequestSignal(options = {}) {

package/lib/image-mcp/server.js

@@ -7,6 +7,7 @@ import {
   createImageJob,
   downloadImageResult,
   generateImage,
+  getCapabilities,
   getImageJobStatus,
   resultFromError,
   structuredToolResult,
@@ -38,6 +39,29 @@ const imageInputProperties = {
     type: 'string',
     description: 'Optional output file path or directory.'
   },
+  overwrite: {
+    type: 'boolean',
+    description: 'Overwrite output_path when it already exists. Defaults to false.',
+    default: false
+  },
+  idempotency_key: {
+    type: 'string',
+    description: 'Optional idempotency key. Reusing it returns the same local job in this MCP process.'
+  },
+  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.'
+  },
+  mask: {
+    type: 'string',
+    description: 'Optional mask image for image edit. Value may be a data URL, HTTPS URL, or local file path.'
+  },
+  input_fidelity: {
+    type: 'string',
+    description: 'Optional image edit fidelity.',
+    enum: ['low', 'high']
+  },
   return_revised_prompt: {
     type: 'boolean',
     description: 'Return upstream revised prompt when available.',
@@ -69,7 +93,16 @@ const tools = [
   {
     name: 'download_image_result',
     description: 'Return the saved local file metadata and image content for a completed image job.',
-    inputSchema: jobIDSchema()
+    inputSchema: downloadSchema()
+  },
+  {
+    name: 'get_capabilities',
+    description: 'Return GPTeam Image MCP capabilities, supported sizes, formats, quality levels, async support, and queue limits.',
+    inputSchema: {
+      type: 'object',
+      properties: {},
+      additionalProperties: false
+    }
   },
   {
     name: 'generate_image',
@@ -134,6 +167,8 @@ export async function callImageTool(toolName, args = {}, deps = {}) {
       return cancelImageJob(args || {}, deps);
     case 'download_image_result':
       return downloadImageResult(args || {}, deps);
+    case 'get_capabilities':
+      return getCapabilities(deps);
     case 'generate_image':
       return await generateImage(args || {}, deps);
     default:
@@ -145,6 +180,26 @@ export async function callImageTool(toolName, args = {}, deps = {}) {
   }
 }
 
+function downloadSchema() {
+  const schema = jobIDSchema();
+  schema.properties.metadata_only = {
+    type: 'boolean',
+    description: 'Return only metadata without MCP image content.',
+    default: false
+  };
+  schema.properties.include_image = {
+    type: 'boolean',
+    description: 'Include image content when the job succeeded.',
+    default: true
+  };
+  schema.properties.include_revised_prompt = {
+    type: 'boolean',
+    description: 'Include revised prompt when available.',
+    default: true
+  };
+  return schema;
+}
+
 function jobIDSchema() {
   return {
     type: 'object',

package/package.json

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