gpteam 0.1.17 → 0.1.19

package/README.md

@@ -16,6 +16,19 @@ 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, canceled, or expired.
+- `cancel_image_job`: cancels a queued/running local job.
+- `download_image_result`: returns the completed file metadata and image content. Use `metadata_only`, `include_image`, and `include_revised_prompt` to control large result payloads.
+- `get_capabilities`: returns supported sizes, formats, quality values, async support, cancellation semantics, queue limits, and image-to-image support.
+- `generate_image`: waits for completion and writes the image file immediately. This is kept for synchronous compatibility.
+
+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.
 
 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 取结果，get_capabilities 可查看支持能力，MCP 使用专用环境变量读取 API key。');
     }
   } finally {
     rl.close();

package/lib/config.js

@@ -8,6 +8,14 @@ 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',
+  'get_capabilities',
+  'generate_image'
+];
 
 export const CLIENTS = [
   { id: 'codex', label: 'Codex' },
@@ -56,7 +64,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.17';
+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。'
+    '说明：输入 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

@@ -0,0 +1,161 @@
+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.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;
+  }
+}
+
+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',
+      stage: 'upstream',
+      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',
+      stage: 'upstream',
+      http_status: status,
+      retryable: true
+    });
+  }
+  if (isContentSafetyError(upstreamCode, message)) {
+    return new ImageMCPError(message, {
+      code: upstreamCode || 'content_safety_rejected',
+      category: 'content_safety',
+      stage: 'upstream',
+      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',
+    stage: status === 401 || status === 403 ? 'upstream' : 'validate',
+    http_status: status,
+    retryable: false
+  });
+}
+
+export function imageErrorFromFetch(error, options = {}) {
+  if (options.cancelled) {
+    return new ImageMCPError('图片生成任务已取消。', {
+      code: 'job_cancelled',
+      category: 'canceled',
+      stage: 'cancel',
+      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',
+    stage: 'network',
+    retryable: true
+  });
+}
+
+export function serializeImageError(error, meta = {}) {
+  if (error instanceof ImageMCPError) {
+    return {
+      code: error.code,
+      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,
+      details: error.details
+    };
+  }
+  return {
+    code: 'image_mcp_error',
+    message: error && error.message ? String(error.message) : String(error || 'unknown error'),
+    retryable: false,
+    stage: 'unknown',
+    upstream_status: undefined,
+    trace_id: meta.trace_id || '',
+    category: 'unknown'
+  };
+}
+
+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);
+}
+
+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

@@ -0,0 +1,303 @@
+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 = inspectImageBytes(bytes);
+  const format = image.format || normalizeImageFormat(input.format || input.output_format || DEFAULT_IMAGE_FORMAT);
+  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'),
+    mime_type: image.mime_type,
+    mimeType: image.mime_type,
+    width: image.width,
+    height: image.height,
+    format,
+    output_format: format
+  };
+}
+
+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) {
+    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',
+    stage: 'local',
+    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',
+      stage: 'local',
+      retryable: false
+    });
+  }
+  const bytes = Buffer.from(text, 'base64');
+  if (bytes.length === 0) {
+    throw new ImageMCPError('GPTeam 图片接口返回的图片数据为空。', {
+      code: 'image_data_empty',
+      category: 'response_invalid',
+      stage: 'local',
+      retryable: false
+    });
+  }
+  return bytes;
+}
+
+export function inspectImageBytes(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',
+    stage: 'local',
+    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',
+    stage: 'local',
+    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.resolve(expanded, name);
+    return path.resolve(withImageExtension(expanded, format));
+  }
+  const outputDir = expandHome(firstNonEmpty(env.GPTEAM_IMAGE_OUTPUT_DIR, defaultImageOutputDir(home)), home);
+  return path.resolve(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',
+      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
+    });
+  }
+}
+
+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}`);
+}