gpteam 0.1.16 → 0.1.18

package/README.md

@@ -16,6 +16,16 @@ 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:
+
+- `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.
+- `cancel_image_job`: cancels a queued/running local job.
+- `download_image_result`: returns the completed file metadata and image content.
+- `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.
+
 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.
 
 Supported clients:

package/lib/cli.js

@@ -71,8 +71,8 @@ export async function runCli(argv = []) {
     for (const filePath of written) console.log(`- ${filePath}`);
     console.log(`入口：${formatNodeLabel(selectedNode)}`);
     console.log(`地址：${selectedNode.baseUrl}`);
-    if (client.id === 'codex') {
-      printHint(theme, '已写入 GPTeam Image MCP。Codex 对话里需要生图时可调用 generate_image，MCP 使用专用环境变量读取 API key。');
+    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。');
     }
   } finally {
     rl.close();

package/lib/client-install.js

@@ -89,7 +89,7 @@ export function resolveSpawnInvocation(command, args, platform = process.platfor
   if (platform === 'win32' && command === 'npm') {
     return {
       command: 'cmd.exe',
-      args: ['/d', '/s', '/c', windowsCommandLine('npm.cmd', args)]
+      args: ['/d', '/c', windowsCommandLine('npm.cmd', args)]
     };
   }
   return { command, args };
@@ -123,7 +123,9 @@ function windowsCommandLine(command, args) {
 }
 
 function windowsQuoteArg(value) {
-  return `"${String(value).replace(/"/g, '\\"')}"`;
+  const text = String(value);
+  if (!/[\s&()^|<>"]/.test(text)) return text;
+  return `"${text.replace(/"/g, '\\"')}"`;
 }
 
 function shellQuote(value) {

package/lib/config.js

@@ -8,6 +8,13 @@ const PROVIDER_ID = 'gpteam';
 const IMAGE_MCP_ID = 'gpteam_image';
 const IMAGE_MCP_PACKAGE = 'gpteam';
 const IMAGE_MCP_BIN = 'gpteam-image-mcp';
+const IMAGE_MCP_ENABLED_TOOLS = [
+  'create_image_job',
+  'get_image_job_status',
+  'download_image_result',
+  'cancel_image_job',
+  'generate_image'
+];
 
 export const CLIENTS = [
   { id: 'codex', label: 'Codex' },
@@ -56,7 +63,7 @@ export function writeCodexConfig(settings) {
     `args = [${mcpCommand.args.map((arg) => tomlString(arg)).join(', ')}]`,
     'startup_timeout_sec = 20',
     'tool_timeout_sec = 300',
-    'enabled_tools = ["generate_image"]',
+    `enabled_tools = [${IMAGE_MCP_ENABLED_TOOLS.map((name) => tomlString(name)).join(', ')}]`,
     'default_tools_approval_mode = "prompt"',
     '',
     `[mcp_servers.${IMAGE_MCP_ID}.env]`,

package/lib/help.js

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

package/lib/image-mcp/errors.js

@@ -0,0 +1,116 @@
+import { formatNetworkError } from '../errors.js';
+
+export class ImageMCPError extends Error {
+  constructor(message, options = {}) {
+    super(String(message || 'GPTeam image MCP error'));
+    this.name = 'ImageMCPError';
+    this.code = String(options.code || 'image_mcp_error');
+    this.category = String(options.category || 'unknown');
+    this.retryable = Boolean(options.retryable);
+    this.http_status = Number.isFinite(options.http_status) ? options.http_status : undefined;
+    this.details = options.details || undefined;
+  }
+}
+
+export async function imageErrorFromHTTPResponse(response, apiKey) {
+  const status = Number(response && response.status) || 0;
+  const rawText = typeof response.text === 'function' ? await response.text() : '';
+  const detail = parseUpstreamError(rawText);
+  const upstreamCode = String(detail.code || detail.type || '').trim();
+  const bodyMessage = detail.message || rawText || '';
+  const message = redactSecret(bodyMessage ? `HTTP ${status}: ${bodyMessage}` : `HTTP ${status}`, apiKey);
+  if (status === 429) {
+    return new ImageMCPError(message, {
+      code: upstreamCode || 'rate_limit_exceeded',
+      category: 'upstream_rate_limit',
+      http_status: status,
+      retryable: true
+    });
+  }
+  if (status >= 500 || status === 408) {
+    return new ImageMCPError(message, {
+      code: upstreamCode || 'upstream_server_error',
+      category: status === 408 ? 'timeout' : 'upstream_server',
+      http_status: status,
+      retryable: true
+    });
+  }
+  if (isContentSafetyError(upstreamCode, message)) {
+    return new ImageMCPError(message, {
+      code: upstreamCode || 'content_safety_rejected',
+      category: 'content_safety',
+      http_status: status,
+      retryable: false
+    });
+  }
+  return new ImageMCPError(message, {
+    code: upstreamCode || (status === 401 || status === 403 ? 'authentication_failed' : 'invalid_request_error'),
+    category: status === 401 || status === 403 ? 'authentication' : 'parameter',
+    http_status: status,
+    retryable: false
+  });
+}
+
+export function imageErrorFromFetch(error, options = {}) {
+  if (options.cancelled) {
+    return new ImageMCPError('图片生成任务已取消。', {
+      code: 'job_cancelled',
+      category: 'cancelled',
+      retryable: false
+    });
+  }
+  const message = redactSecret(formatNetworkError(error), options.apiKey);
+  const timeoutLike = options.timedOut || /timeout|timedout|etimedout/i.test(message);
+  return new ImageMCPError(message, {
+    code: timeoutLike ? 'network_timeout' : 'network_error',
+    category: timeoutLike ? 'timeout' : 'network',
+    retryable: true
+  });
+}
+
+export function serializeImageError(error) {
+  if (error instanceof ImageMCPError) {
+    return {
+      code: error.code,
+      category: error.category,
+      retryable: error.retryable,
+      http_status: error.http_status,
+      message: error.message
+    };
+  }
+  return {
+    code: 'image_mcp_error',
+    category: 'unknown',
+    retryable: false,
+    message: error && error.message ? String(error.message) : String(error || 'unknown error')
+  };
+}
+
+export function redactSecret(text, secret) {
+  let result = String(text || '');
+  if (secret) result = result.split(secret).join('[redacted]');
+  result = result.replace(/sk-[A-Za-z0-9_-]{6,}/g, 'sk-[redacted]');
+  return result;
+}
+
+function parseUpstreamError(text) {
+  try {
+    const parsed = JSON.parse(String(text || ''));
+    const error = parsed && typeof parsed === 'object' ? parsed.error : null;
+    if (error && typeof error === 'object') {
+      return {
+        code: error.code,
+        type: error.type,
+        message: error.message
+      };
+    }
+  } catch {
+    return {};
+  }
+  return {};
+}
+
+function isContentSafetyError(code, message) {
+  const text = `${code || ''} ${message || ''}`.toLowerCase();
+  return /content|safety|policy|moderation/.test(text);
+}

package/lib/image-mcp/files.js

@@ -0,0 +1,244 @@
+import crypto from 'node:crypto';
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import { ImageMCPError } from './errors.js';
+
+export const DEFAULT_IMAGE_FORMAT = 'png';
+
+export function writeImageOutput(input = {}, options = {}) {
+  const bytes = decodeBase64Image(input.b64);
+  const image = inspectImage(bytes);
+  const format = image.format || normalizeImageFormat(input.format || input.output_format || DEFAULT_IMAGE_FORMAT);
+  const outputPath = writeImageFileNonOverwriting(input.output_path, format, bytes, options);
+  return {
+    file: outputPath,
+    path: outputPath,
+    bytes: bytes.length,
+    sha256: crypto.createHash('sha256').update(bytes).digest('hex'),
+    mime_type: image.mime_type,
+    mimeType: image.mime_type,
+    width: image.width,
+    height: image.height,
+    format,
+    output_format: format
+  };
+}
+
+function writeImageFileNonOverwriting(rawOutputPath, format, bytes, options) {
+  let lastConflict;
+  for (let attempt = 0; attempt < 10000; attempt += 1) {
+    const outputPath = resolveAvailableOutputPath(rawOutputPath, format, options);
+    fs.mkdirSync(path.dirname(outputPath), { recursive: true });
+    try {
+      atomicWriteFile(outputPath, bytes);
+      return outputPath;
+    } catch (error) {
+      if (!isOutputPathConflict(error)) throw error;
+      lastConflict = error;
+    }
+  }
+  throw lastConflict || new ImageMCPError('无法生成不覆盖现有文件的输出路径。', {
+    code: 'output_path_conflict',
+    category: 'file_system',
+    retryable: false
+  });
+}
+
+export function normalizeImageFormat(value) {
+  const normalized = String(value || DEFAULT_IMAGE_FORMAT).trim().toLowerCase();
+  if (normalized === 'jpg') return 'jpeg';
+  if (['png', 'jpeg', 'webp'].includes(normalized)) return normalized;
+  return DEFAULT_IMAGE_FORMAT;
+}
+
+function decodeBase64Image(value) {
+  const text = String(value || '').trim();
+  if (!text) {
+    throw new ImageMCPError('GPTeam 图片接口没有返回 b64_json 图片数据。', {
+      code: 'image_data_missing',
+      category: 'response_invalid',
+      retryable: false
+    });
+  }
+  const bytes = Buffer.from(text, 'base64');
+  if (bytes.length === 0) {
+    throw new ImageMCPError('GPTeam 图片接口返回的图片数据为空。', {
+      code: 'image_data_empty',
+      category: 'response_invalid',
+      retryable: false
+    });
+  }
+  return bytes;
+}
+
+function inspectImage(bytes) {
+  const png = inspectPNG(bytes);
+  if (png) return png;
+  const jpeg = inspectJPEG(bytes);
+  if (jpeg) return jpeg;
+  const webp = inspectWebP(bytes);
+  if (webp) return webp;
+  throw new ImageMCPError('写入前图片校验失败：无法识别 PNG/JPEG/WebP。', {
+    code: 'image_mime_invalid',
+    category: 'response_invalid',
+    retryable: false
+  });
+}
+
+function inspectPNG(bytes) {
+  if (bytes.length < 24) return null;
+  const signature = '89504e470d0a1a0a';
+  if (bytes.subarray(0, 8).toString('hex') !== signature) return null;
+  return {
+    format: 'png',
+    mime_type: 'image/png',
+    width: bytes.readUInt32BE(16),
+    height: bytes.readUInt32BE(20)
+  };
+}
+
+function inspectJPEG(bytes) {
+  if (bytes.length < 4 || bytes[0] !== 0xff || bytes[1] !== 0xd8) return null;
+  let offset = 2;
+  while (offset + 9 < bytes.length) {
+    if (bytes[offset] !== 0xff) {
+      offset += 1;
+      continue;
+    }
+    const marker = bytes[offset + 1];
+    const length = bytes.readUInt16BE(offset + 2);
+    if (length < 2) break;
+    if ([0xc0, 0xc1, 0xc2, 0xc3].includes(marker)) {
+      return {
+        format: 'jpeg',
+        mime_type: 'image/jpeg',
+        height: bytes.readUInt16BE(offset + 5),
+        width: bytes.readUInt16BE(offset + 7)
+      };
+    }
+    offset += 2 + length;
+  }
+  return { format: 'jpeg', mime_type: 'image/jpeg', width: undefined, height: undefined };
+}
+
+function inspectWebP(bytes) {
+  if (bytes.length < 16) return null;
+  if (bytes.subarray(0, 4).toString('ascii') !== 'RIFF') return null;
+  if (bytes.subarray(8, 12).toString('ascii') !== 'WEBP') return null;
+  if (bytes.subarray(12, 16).toString('ascii') === 'VP8X' && bytes.length >= 30) {
+    return {
+      format: 'webp',
+      mime_type: 'image/webp',
+      width: 1 + readUInt24LE(bytes, 24),
+      height: 1 + readUInt24LE(bytes, 27)
+    };
+  }
+  return { format: 'webp', mime_type: 'image/webp', width: undefined, height: undefined };
+}
+
+function readUInt24LE(bytes, offset) {
+  return bytes[offset] + (bytes[offset + 1] << 8) + (bytes[offset + 2] << 16);
+}
+
+function resolveAvailableOutputPath(rawOutputPath, format, options) {
+  const resolved = resolveOutputPath(rawOutputPath, format, options);
+  if (!fs.existsSync(resolved)) return resolved;
+  const parsed = path.parse(resolved);
+  for (let version = 2; version < 10000; version += 1) {
+    const candidate = path.join(parsed.dir, `${parsed.name}-v${version}${parsed.ext}`);
+    if (!fs.existsSync(candidate)) return candidate;
+  }
+  throw new ImageMCPError('无法生成不覆盖现有文件的输出路径。', {
+    code: 'output_path_conflict',
+    category: 'file_system',
+    retryable: false
+  });
+}
+
+function resolveOutputPath(rawOutputPath, format, options) {
+  const env = options.env || process.env;
+  const home = options.home || os.homedir();
+  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);
+  }
+  const outputDir = expandHome(firstNonEmpty(env.GPTEAM_IMAGE_OUTPUT_DIR, defaultImageOutputDir(home)), home);
+  return path.join(outputDir, name);
+}
+
+function atomicWriteFile(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.linkSync(tempPath, outputPath);
+    try {
+      fs.rmSync(tempPath, { force: true });
+    } catch {
+      // 目标文件已通过独占链接落盘，临时文件清理失败不影响返回结果。
+    }
+  } catch (error) {
+    if (fd !== undefined) {
+      try {
+        fs.closeSync(fd);
+      } catch {
+        // 忽略关闭临时文件失败，下面会清理临时路径。
+      }
+    }
+    try {
+      fs.rmSync(tempPath, { force: true });
+    } catch {
+      // 忽略清理失败，返回主要写入错误。
+    }
+    const conflict = error && error.code === 'EEXIST';
+    throw new ImageMCPError(conflict ? '输出文件已存在，正在重新选择不覆盖路径。' : `图片文件写入失败：${error.message}`, {
+      code: conflict ? 'output_path_conflict' : 'file_write_failed',
+      category: 'file_system',
+      retryable: false
+    });
+  }
+}
+
+function isOutputPathConflict(error) {
+  return error instanceof ImageMCPError && error.code === 'output_path_conflict';
+}
+
+function defaultImageOutputDir(home) {
+  const desktop = path.join(home, 'Desktop');
+  return fs.existsSync(desktop) ? desktop : process.cwd();
+}
+
+function isDirectoryLike(value) {
+  return /[\\/]$/.test(value) || (fs.existsSync(value) && fs.statSync(value).isDirectory());
+}
+
+function firstNonEmpty(...values) {
+  for (const value of values) {
+    const text = String(value || '').trim();
+    if (text) return text;
+  }
+  return '';
+}
+
+function expandHome(value, home) {
+  const text = String(value || '');
+  if (text === '~') return home;
+  if (text.startsWith(`~${path.sep}`)) return path.join(home, text.slice(2));
+  if (text.startsWith('~/')) return path.join(home, text.slice(2));
+  return text;
+}
+
+function withImageExtension(filePath, format) {
+  const parsed = path.parse(filePath);
+  const ext = parsed.ext.toLowerCase();
+  const normalizedExt = ext === '.jpg' ? '.jpeg' : ext;
+  if (normalizedExt === `.${format}`) return filePath;
+  return path.join(parsed.dir, `${parsed.name}.${format}`);
+}

package/lib/image-mcp/image.js

@@ -1,10 +1,24 @@
 import fs from 'node:fs';
 import os from 'node:os';
 import path from 'node:path';
+import {
+  ImageMCPError,
+  imageErrorFromFetch,
+  imageErrorFromHTTPResponse,
+  redactSecret,
+  serializeImageError
+} from './errors.js';
+import { DEFAULT_IMAGE_FORMAT, normalizeImageFormat, writeImageOutput } from './files.js';
 
 export const DEFAULT_BASE_URL = 'https://api.gpteamservices.com/v1';
 export const DEFAULT_IMAGE_MODEL = 'gpt-image-2';
-export const DEFAULT_IMAGE_FORMAT = 'png';
+export { DEFAULT_IMAGE_FORMAT };
+
+const defaultMaxAttempts = 3;
+const defaultRetryDelayMs = 800;
+const defaultRequestTimeoutMs = 5 * 60 * 1000;
+
+const defaultJobStore = createImageJobStore();
 
 export function buildImageGenerationPayload(input = {}) {
   return {
@@ -25,7 +39,11 @@ export function loadGPTeamCredentials(options = {}) {
   const configuredBaseUrl = parseGPTeamBaseUrl(configText);
   const apiKey = firstNonEmpty(env.GPTEAM_API_KEY);
   if (!apiKey) {
-    throw new Error('没有找到 GPTeam API key。请在 MCP 配置 env 中设置 GPTEAM_API_KEY，或先运行 npx gpteam 完成本地配置。');
+    throw new ImageMCPError('没有找到 GPTeam API key。请在 MCP 配置 env 中设置 GPTEAM_API_KEY，或先运行 npx gpteam 完成本地配置。', {
+      code: 'api_key_missing',
+      category: 'configuration',
+      retryable: false
+    });
   }
   const baseUrl = normalizeBaseUrl(firstNonEmpty(env.GPTEAM_BASE_URL, configuredBaseUrl, DEFAULT_BASE_URL));
   return { apiKey, baseUrl, codexHome };
@@ -55,107 +73,331 @@ export function normalizeBaseUrl(value) {
 }
 
 export async function generateImage(input = {}, options = {}) {
+  const startedAt = now(options);
   const prompt = String(input.prompt || '').trim();
-  if (!prompt) throw new Error('prompt 不能为空');
+  if (!prompt) {
+    throw new ImageMCPError('prompt 不能为空', {
+      code: 'prompt_required',
+      category: 'parameter',
+      retryable: false
+    });
+  }
   const credentials = loadGPTeamCredentials(options);
   const payload = buildImageGenerationPayload(input);
   const fetchImpl = options.fetch || globalThis.fetch;
   if (typeof fetchImpl !== 'function') {
-    throw new Error('当前 Node.js 运行时不支持 fetch，请升级到 Node.js 18.18 或更高版本。');
+    throw new ImageMCPError('当前 Node.js 运行时不支持 fetch，请升级到 Node.js 18.18 或更高版本。', {
+      code: 'fetch_unavailable',
+      category: 'environment',
+      retryable: false
+    });
   }
-  const response = await fetchImpl(`${credentials.baseUrl}/images/generations`, {
-    method: 'POST',
-    headers: {
-      Authorization: `Bearer ${credentials.apiKey}`,
-      'Content-Type': 'application/json'
-    },
-    body: JSON.stringify(payload)
+  const jobID = String(input.job_id || options.jobID || makeID('img'));
+  const traceID = String(input.trace_id || options.traceID || makeID('tr'));
+  const result = await fetchImageWithRetry(fetchImpl, credentials, payload, options);
+  const format = normalizeImageFormat(payload.output_format);
+  const file = writeImageOutput({
+    b64: result.b64,
+    output_path: input.output_path,
+    format
+  }, options);
+  const includeRevisedPrompt = resolveRevisedPromptFlag(input);
+  const durationMs = now(options) - startedAt;
+  return buildSuccessResult({
+    jobID,
+    traceID,
+    payload,
+    file,
+    b64: result.b64,
+    revisedPrompt: includeRevisedPrompt ? result.revisedPrompt : '',
+    retryCount: result.retryCount,
+    durationMs
   });
-  if (!response.ok) {
-    const detail = typeof response.text === 'function' ? await response.text() : '';
-    throw new Error(`GPTeam /v1/images/generations 返回 HTTP ${response.status}${detail ? `：${redactSecret(detail, credentials.apiKey)}` : ''}`);
+}
+
+export function createImageJobStore(options = {}) {
+  return {
+    jobs: new Map(),
+    now: typeof options.now === 'function' ? options.now : Date.now,
+    ttlMs: Number(options.ttlMs || 30 * 60 * 1000)
+  };
+}
+
+export function createImageJob(input = {}, options = {}) {
+  const store = options.store || defaultJobStore;
+  cleanupImageJobs(store);
+  const jobID = makeID('img');
+  const traceID = makeID('tr');
+  const controller = new AbortController();
+  const job = {
+    job_id: jobID,
+    trace_id: traceID,
+    status: 'queued',
+    ok: true,
+    created_at: new Date(store.now()).toISOString(),
+    updated_at: new Date(store.now()).toISOString(),
+    controller,
+    result: null,
+    error: null
+  };
+  store.jobs.set(jobID, job);
+  queueMicrotask(() => runImageJob(store, job, input, options));
+  return publicJobStatus(job);
+}
+
+export function getImageJobStatus(input = {}, options = {}) {
+  const store = options.store || defaultJobStore;
+  cleanupImageJobs(store);
+  const job = store.jobs.get(String(input.job_id || ''));
+  if (!job) return missingJobResult(input.job_id);
+  return publicJobStatus(job);
+}
+
+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);
+  job.controller.abort();
+  job.status = 'cancelled';
+  job.ok = false;
+  job.updated_at = new Date(store.now()).toISOString();
+  job.error = {
+    code: 'job_cancelled',
+    category: 'cancelled',
+    retryable: false,
+    message: '图片生成任务已取消。'
+  };
+  return { ...publicJobStatus(job), ok: true };
+}
+
+export function downloadImageResult(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') return publicJobStatus(job);
+  return { ...job.result, status: 'succeeded' };
+}
+
+export function structuredToolResult(result) {
+  if (!result || typeof result !== 'object') {
+    return { ok: false, error: { code: 'empty_result', category: 'unknown', retryable: false, message: 'empty result' } };
   }
-  const data = await response.json();
-  const first = Array.isArray(data && data.data) ? data.data[0] : null;
-  const b64 = first && typeof first.b64_json === 'string' ? first.b64_json : '';
-  if (!b64) {
-    throw new Error('GPTeam 图片接口没有返回 b64_json 图片数据。');
+  const clone = { ...result };
+  delete clone.b64;
+  delete clone.mimeType;
+  delete clone.revisedPrompt;
+  delete clone.path;
+  return clone;
+}
+
+export function toolResultContent(result) {
+  const structured = structuredToolResult(result);
+  const content = [{ type: 'text', text: JSON.stringify(structured, null, 2) }];
+  if (result && result.ok && result.b64 && result.mimeType) {
+    content.push({ type: 'image', data: result.b64, mimeType: result.mimeType });
   }
-  const format = normalizeImageFormat(payload.output_format);
-  const outputPath = resolveOutputPath(input.output_path, format, options);
-  fs.mkdirSync(path.dirname(outputPath), { recursive: true });
-  fs.writeFileSync(outputPath, Buffer.from(b64, 'base64'));
+  return content;
+}
+
+export function resultFromError(error, meta = {}) {
   return {
-    path: outputPath,
-    mimeType: mimeTypeForFormat(format),
-    b64,
-    model: payload.model,
-    size: payload.size,
-    quality: payload.quality,
-    format,
-    revisedPrompt: first && typeof first.revised_prompt === 'string' ? first.revised_prompt : ''
+    ok: false,
+    job_id: meta.job_id || '',
+    trace_id: meta.trace_id || '',
+    status: 'failed',
+    error: serializeImageError(error)
   };
 }
 
-export function toolResultContent(result) {
-  const text = [
-    'GPTeam Image 2 生成完成。',
-    `文件：${result.path}`,
-    `模型：${result.model}`,
-    `规格：${result.size} / ${result.quality} / ${result.format}`
-  ];
-  if (result.revisedPrompt) text.push(`修订提示词：${result.revisedPrompt}`);
-  return [
-    { type: 'text', text: text.join('\n') },
-    { type: 'image', data: result.b64, mimeType: result.mimeType }
-  ];
+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);
+  let lastError;
+  for (let attempt = 1; attempt <= maxAttempts; attempt += 1) {
+    try {
+      const response = await fetchImageOnce(fetchImpl, credentials, payload, options);
+      return { ...response, retryCount: attempt - 1 };
+    } catch (error) {
+      const classified = error instanceof ImageMCPError ? error : imageErrorFromFetch(error, { apiKey: credentials.apiKey });
+      lastError = classified;
+      if (!classified.retryable || attempt >= maxAttempts) throw classified;
+      await delay(retryDelayMs * Math.max(1, attempt), options);
+    }
+  }
+  throw lastError;
 }
 
-function resolveCodexHome(env, home) {
-  return expandHome(firstNonEmpty(env.GPTEAM_CODEX_HOME, env.CODEX_HOME, path.join(home, '.codex')), home);
+async function fetchImageOnce(fetchImpl, credentials, payload, options) {
+  const requestSignal = createRequestSignal(options);
+  try {
+    const response = await fetchImpl(`${credentials.baseUrl}/images/generations`, {
+      method: 'POST',
+      headers: {
+        Authorization: `Bearer ${credentials.apiKey}`,
+        'Content-Type': 'application/json'
+      },
+      body: JSON.stringify(payload),
+      signal: requestSignal.signal
+    });
+    if (!response.ok) throw await imageErrorFromHTTPResponse(response, credentials.apiKey);
+    const data = await response.json();
+    const first = Array.isArray(data && data.data) ? data.data[0] : null;
+    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
+      });
+    }
+    return {
+      b64,
+      revisedPrompt: first && typeof first.revised_prompt === 'string' ? first.revised_prompt : ''
+    };
+  } catch (error) {
+    if (error instanceof ImageMCPError) throw error;
+    throw imageErrorFromFetch(error, {
+      apiKey: credentials.apiKey,
+      timedOut: requestSignal.timedOut(),
+      cancelled: Boolean(options.signal && options.signal.aborted)
+    });
+  } finally {
+    requestSignal.clear();
+  }
 }
 
-function safeRead(filePath, readFile) {
+function buildSuccessResult(input) {
+  const result = {
+    ok: true,
+    status: 'succeeded',
+    file: input.file.file,
+    path: input.file.file,
+    model: input.payload.model,
+    size: input.payload.size,
+    format: input.file.format,
+    output_format: input.file.format,
+    quality: input.payload.quality,
+    mime_type: input.file.mime_type,
+    mimeType: input.file.mime_type,
+    bytes: input.file.bytes,
+    sha256: input.file.sha256,
+    width: input.file.width,
+    height: input.file.height,
+    duration_ms: input.durationMs,
+    retry_count: input.retryCount,
+    job_id: input.jobID,
+    trace_id: input.traceID,
+    b64: input.b64
+  };
+  if (input.revisedPrompt) {
+    result.revised_prompt = input.revisedPrompt;
+    result.revisedPrompt = input.revisedPrompt;
+  }
+  return result;
+}
+
+async function runImageJob(store, job, input, options) {
+  if (job.status === 'cancelled') return;
+  job.status = 'running';
+  job.updated_at = new Date(store.now()).toISOString();
   try {
-    return readFile(filePath);
-  } catch {
-    return '';
+    const result = await generateImage({ ...input, job_id: job.job_id, trace_id: job.trace_id }, {
+      ...options,
+      signal: job.controller.signal
+    });
+    if (job.status === 'cancelled') return;
+    job.status = 'succeeded';
+    job.ok = true;
+    job.result = result;
+  } catch (error) {
+    if (job.status !== 'cancelled') {
+      job.status = 'failed';
+      job.ok = false;
+      job.error = serializeImageError(error);
+    }
+  } finally {
+    job.updated_at = new Date(store.now()).toISOString();
   }
 }
 
-function resolveOutputPath(rawOutputPath, format, options) {
-  const env = options.env || process.env;
-  const home = options.home || os.homedir();
-  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 expanded;
+function publicJobStatus(job) {
+  const base = {
+    ok: job.status !== 'failed' && job.status !== 'cancelled',
+    job_id: job.job_id,
+    trace_id: job.trace_id,
+    status: job.status,
+    created_at: job.created_at,
+    updated_at: job.updated_at
+  };
+  if (job.result) return { ...base, ...structuredToolResult(job.result) };
+  if (job.error) return { ...base, error: job.error };
+  return base;
+}
+
+function missingJobResult(jobID) {
+  return {
+    ok: false,
+    job_id: String(jobID || ''),
+    status: 'not_found',
+    error: {
+      code: 'job_not_found',
+      category: 'not_found',
+      retryable: false,
+      message: '没有找到这个图片任务。'
+    }
+  };
+}
+
+function cleanupImageJobs(store) {
+  const threshold = store.now() - store.ttlMs;
+  for (const [jobID, job] of store.jobs.entries()) {
+    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);
   }
-  const outputDir = expandHome(firstNonEmpty(env.GPTEAM_IMAGE_OUTPUT_DIR, defaultImageOutputDir(home)), home);
-  return path.join(outputDir, name);
 }
 
-function defaultImageOutputDir(home) {
-  const desktop = path.join(home, 'Desktop');
-  return fs.existsSync(desktop) ? desktop : process.cwd();
+function createRequestSignal(options = {}) {
+  const timeoutMs = resolveBoundedInt(1, options.requestTimeoutMs, options.env && options.env.GPTEAM_IMAGE_REQUEST_TIMEOUT_MS, defaultRequestTimeoutMs);
+  const controller = new AbortController();
+  let timedOut = false;
+  const timer = setTimeout(() => {
+    timedOut = true;
+    controller.abort();
+  }, timeoutMs);
+  if (typeof timer.unref === 'function') timer.unref();
+  const parent = options.signal;
+  if (parent) {
+    if (parent.aborted) controller.abort();
+    else parent.addEventListener('abort', () => {
+      clearTimeout(timer);
+      controller.abort();
+    }, { once: true });
+  }
+  return {
+    signal: controller.signal,
+    timedOut: () => timedOut,
+    clear: () => clearTimeout(timer)
+  };
 }
 
-function isDirectoryLike(value) {
-  return /[\\/]$/.test(value) || (fs.existsSync(value) && fs.statSync(value).isDirectory());
+function resolveRevisedPromptFlag(input) {
+  if (Object.prototype.hasOwnProperty.call(input, 'include_revised_prompt')) return Boolean(input.include_revised_prompt);
+  if (Object.prototype.hasOwnProperty.call(input, 'return_revised_prompt')) return Boolean(input.return_revised_prompt);
+  return true;
 }
 
-function normalizeImageFormat(value) {
-  const normalized = String(value || DEFAULT_IMAGE_FORMAT).trim().toLowerCase();
-  if (normalized === 'jpg') return 'jpeg';
-  if (['png', 'jpeg', 'webp'].includes(normalized)) return normalized;
-  return DEFAULT_IMAGE_FORMAT;
+function resolveCodexHome(env, home) {
+  return expandHome(firstNonEmpty(env.GPTEAM_CODEX_HOME, env.CODEX_HOME, path.join(home, '.codex')), home);
 }
 
-function mimeTypeForFormat(format) {
-  if (format === 'jpeg') return 'image/jpeg';
-  if (format === 'webp') return 'image/webp';
-  return 'image/png';
+function safeRead(filePath, readFile) {
+  try {
+    return readFile(filePath);
+  } catch {
+    return '';
+  }
 }
 
 function firstNonEmpty(...values) {
@@ -178,9 +420,29 @@ function unescapeTomlString(value) {
   return String(value || '').replace(/\\"/g, '"').replace(/\\\\/g, '\\');
 }
 
-function redactSecret(text, secret) {
-  let result = String(text || '');
-  if (secret) result = result.split(secret).join('[redacted]');
-  result = result.replace(/sk-[A-Za-z0-9_-]{6,}/g, 'sk-[redacted]');
-  return result;
+function makeID(prefix) {
+  return `${prefix}_${Date.now().toString(36)}_${Math.random().toString(36).slice(2, 10)}`;
+}
+
+function now(options = {}) {
+  return typeof options.now === 'function' ? options.now() : Date.now();
+}
+
+function resolveBoundedInt(min, ...values) {
+  for (const value of values) {
+    if (value === undefined || value === null || value === '') continue;
+    const parsed = Number.parseInt(String(value), 10);
+    if (Number.isFinite(parsed) && parsed >= min) return parsed;
+  }
+  return min;
+}
+
+async function delay(ms, options = {}) {
+  if (ms <= 0) return;
+  if (typeof options.sleep === 'function') return options.sleep(ms);
+  await new Promise((resolve) => setTimeout(resolve, ms));
+}
+
+export function redactImageSecret(text, secret) {
+  return redactSecret(text, secret);
 }

package/lib/image-mcp/server.js

@@ -1,45 +1,88 @@
 import { Server } from '@modelcontextprotocol/sdk/server/index.js';
 import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
-import { CallToolRequestSchema, ListToolsRequestSchema } from '@modelcontextprotocol/sdk/types.js';
+import { CallToolRequestSchema, ErrorCode, ListToolsRequestSchema, McpError } from '@modelcontextprotocol/sdk/types.js';
 import fs from 'node:fs';
-import { generateImage, toolResultContent } from './image.js';
+import {
+  cancelImageJob,
+  createImageJob,
+  downloadImageResult,
+  generateImage,
+  getImageJobStatus,
+  resultFromError,
+  structuredToolResult,
+  toolResultContent
+} from './image.js';
 
-const GENERATE_IMAGE_TOOL = {
-  name: 'generate_image',
-  description: 'Generate an image through GPTeam Image 2 and save it to a local file.',
-  inputSchema: {
-    type: 'object',
-    properties: {
-      prompt: {
-        type: 'string',
-        description: 'Image prompt.'
-      },
-      size: {
-        type: 'string',
-        description: 'Image size, for example 1024x1024.',
-        default: '1024x1024'
-      },
-      quality: {
-        type: 'string',
-        description: 'Image quality.',
-        default: 'high'
-      },
-      format: {
-        type: 'string',
-        description: 'Output image format.',
-        enum: ['png', 'jpeg', 'webp'],
-        default: 'png'
-      },
-      output_path: {
-        type: 'string',
-        description: 'Optional output file path or directory.'
-      }
-    },
-    required: ['prompt'],
-    additionalProperties: false
+const imageInputProperties = {
+  prompt: {
+    type: 'string',
+    description: 'Image prompt.'
+  },
+  size: {
+    type: 'string',
+    description: 'Image size, for example 1024x1024.',
+    default: '1024x1024'
+  },
+  quality: {
+    type: 'string',
+    description: 'Image quality.',
+    default: 'high'
+  },
+  format: {
+    type: 'string',
+    description: 'Output image format.',
+    enum: ['png', 'jpeg', 'webp'],
+    default: 'png'
+  },
+  output_path: {
+    type: 'string',
+    description: 'Optional output file path or directory.'
+  },
+  return_revised_prompt: {
+    type: 'boolean',
+    description: 'Return upstream revised prompt when available.',
+    default: true
   }
 };
 
+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.',
+    inputSchema: {
+      type: 'object',
+      properties: imageInputProperties,
+      required: ['prompt'],
+      additionalProperties: false
+    }
+  },
+  {
+    name: 'get_image_job_status',
+    description: 'Get the status of a local GPTeam Image 2 job.',
+    inputSchema: jobIDSchema()
+  },
+  {
+    name: 'cancel_image_job',
+    description: 'Cancel a local GPTeam Image 2 job when it is still queued or running.',
+    inputSchema: jobIDSchema()
+  },
+  {
+    name: 'download_image_result',
+    description: 'Return the saved local file metadata and image content for a completed image job.',
+    inputSchema: jobIDSchema()
+  },
+  {
+    name: 'generate_image',
+    description: 'Compatibility tool. Generate an image through GPTeam Image 2, wait for completion, and save it locally.',
+    inputSchema: {
+      type: 'object',
+      properties: imageInputProperties,
+      required: ['prompt'],
+      additionalProperties: false
+    }
+  }
+];
+
 export function createServer(deps = {}) {
   const server = new Server({
     name: 'gpteam-image-mcp',
@@ -50,18 +93,14 @@ export function createServer(deps = {}) {
     }
   });
 
-  server.setRequestHandler(ListToolsRequestSchema, async () => ({
-    tools: [GENERATE_IMAGE_TOOL]
-  }));
+  server.setRequestHandler(ListToolsRequestSchema, async () => ({ tools }));
 
   server.setRequestHandler(CallToolRequestSchema, async (request) => {
-    const toolName = request.params && request.params.name;
-    if (toolName !== GENERATE_IMAGE_TOOL.name) {
-      throw new Error(`未知工具：${toolName}`);
-    }
-    const result = await generateImage(request.params.arguments || {}, deps);
+    const result = await callImageTool(request.params && request.params.name, request.params && request.params.arguments, deps);
     return {
-      content: toolResultContent(result)
+      content: toolResultContent(result),
+      structuredContent: structuredToolResult(result),
+      isError: result && result.ok === false
     };
   });
 
@@ -83,3 +122,39 @@ export function resolvePackageVersion(deps = {}) {
     return '0.0.0';
   }
 }
+
+export async function callImageTool(toolName, args = {}, deps = {}) {
+  try {
+    switch (toolName) {
+    case 'create_image_job':
+      return createImageJob(args || {}, deps);
+    case 'get_image_job_status':
+      return getImageJobStatus(args || {}, deps);
+    case 'cancel_image_job':
+      return cancelImageJob(args || {}, deps);
+    case 'download_image_result':
+      return downloadImageResult(args || {}, deps);
+    case 'generate_image':
+      return await generateImage(args || {}, deps);
+    default:
+      throw new McpError(ErrorCode.InvalidParams, `未知工具：${toolName}`);
+    }
+  } catch (error) {
+    if (error instanceof McpError) throw error;
+    return resultFromError(error);
+  }
+}
+
+function jobIDSchema() {
+  return {
+    type: 'object',
+    properties: {
+      job_id: {
+        type: 'string',
+        description: 'Image job id returned by create_image_job.'
+      }
+    },
+    required: ['job_id'],
+    additionalProperties: false
+  };
+}

package/package.json

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