@xinizai/pi-image-gen 0.1.0

package/src/index.ts

@@ -0,0 +1,394 @@
+import { Type } from "@earendil-works/pi-ai";
+import type { ExtensionAPI, ExtensionCommandContext } from "@earendil-works/pi-coding-agent";
+import { configErrorText, configText, createService, deleteProvider, discoverProviderCandidate, modelsText, providerStatus, providersText, resultText, saveProviderWithDiscovery, setDefaultProvider, updateProvider } from "./tools/shared.js";
+import { GlobalConfigStore } from "./core/global-config.js";
+import { maskApiKey } from "./core/errors.js";
+import { ModelRegistry } from "./core/model-registry.js";
+import type { DiscoveryResult, StoredProviderConfig } from "./core/types.js";
+
+const OutputFormat = Type.Union([Type.Literal("png"), Type.Literal("jpeg"), Type.Literal("jpg"), Type.Literal("webp")]);
+
+export default function imageGenExtension(pi: ExtensionAPI): void {
+  pi.registerTool({
+    name: "image_generate",
+    label: "图片生成",
+    description: "根据文字描述生成图片。自动选择已配置的图片生成提供商和模型。",
+    promptSnippet: "根据文字描述生成图片。必要时自动使用已配置的全局提供商。",
+    promptGuidelines: ["当用户要求生成、创建或绘制图片时使用 image_generate。若尚未配置提供商，请引导用户运行 /image-config。不要请求或泄露 API Key。"],
+    parameters: Type.Object({
+      prompt: Type.String({ description: "图片生成提示词" }),
+      provider: Type.Optional(Type.String({ description: "可选，Provider ID 或名称" })),
+      model: Type.Optional(Type.String({ description: "可选，精确模型 ID；留空则自动选择" })),
+      size: Type.Optional(Type.String({ description: "可选，图片尺寸，例如 1024x1024" })),
+      aspect_ratio: Type.Optional(Type.String({ description: "可选，宽高比，例如 16:9" })),
+      quality: Type.Optional(Type.String({ description: "可选，质量，例如 standard、hd、high" })),
+      output_format: Type.Optional(OutputFormat),
+      n: Type.Optional(Type.Number({ description: "图片数量", minimum: 1, maximum: 10 })),
+    }),
+    async execute(_id, params, signal) {
+      try { return { content: [{ type: "text", text: resultText("图片生成", await (await createService(params.provider)).generate(params, signal)) }], details: {} }; }
+      catch (e) { throw new Error(configErrorText(e)); }
+    },
+  });
+
+  pi.registerTool({
+    name: "image_edit",
+    label: "图片编辑",
+    description: "根据参考图片和文字要求编辑图片。",
+    promptSnippet: "根据参考图片和文字要求编辑图片。",
+    promptGuidelines: ["当用户提供参考图片并希望编辑时使用 image_edit。"],
+    parameters: Type.Object({
+      image: Type.String({ description: "Windows/Linux 本地路径、file:// URL 或 https URL" }),
+      prompt: Type.String({ description: "图片编辑要求" }),
+      provider: Type.Optional(Type.String({ description: "可选，Provider ID 或名称" })),
+      model: Type.Optional(Type.String({ description: "可选，模型 ID" })),
+      size: Type.Optional(Type.String({ description: "可选，图片尺寸" })),
+      output_format: Type.Optional(OutputFormat),
+    }),
+    async execute(_id, params, signal) {
+      try { return { content: [{ type: "text", text: resultText("图片编辑", await (await createService(params.provider)).edit(params, signal)) }], details: {} }; }
+      catch (e) { throw new Error(configErrorText(e)); }
+    },
+  });
+
+  pi.registerTool({
+    name: "image_variation",
+    label: "图片变体",
+    description: "根据参考图片生成新的图片变体。",
+    promptSnippet: "根据参考图片生成新的图片变体。",
+    parameters: Type.Object({
+      image: Type.String({ description: "Windows/Linux 本地路径、file:// URL 或 https URL" }),
+      provider: Type.Optional(Type.String({ description: "可选，Provider ID 或名称" })),
+      model: Type.Optional(Type.String({ description: "可选，模型 ID" })),
+      size: Type.Optional(Type.String({ description: "可选，图片尺寸" })),
+      n: Type.Optional(Type.Number({ minimum: 1, maximum: 10 })),
+    }),
+    async execute(_id, params, signal) {
+      try { return { content: [{ type: "text", text: resultText("图片变体", await (await createService(params.provider)).variation(params, signal)) }], details: {} }; }
+      catch (e) { throw new Error(configErrorText(e)); }
+    },
+  });
+
+  pi.registerTool({
+    name: "image_models",
+    label: "图片模型",
+    description: "查询当前已配置提供商支持的图片模型。结果会自动限制长度，避免上下文过长。",
+    promptSnippet: "查询当前已配置提供商支持的图片模型。",
+    parameters: Type.Object({
+      provider: Type.Optional(Type.String({ description: "提供商 ID 或名称" })),
+      search: Type.Optional(Type.String({ description: "搜索关键词" })),
+      page: Type.Optional(Type.Number({ minimum: 1 })),
+      limit: Type.Optional(Type.Number({ minimum: 1, maximum: 50 })),
+      refresh: Type.Optional(Type.Boolean({ description: "刷新当前选择的提供商" })),
+      refresh_all: Type.Optional(Type.Boolean({ description: "刷新所有已配置提供商" })),
+      include_text: Type.Optional(Type.Boolean({ description: "显示文本模型" })),
+    }),
+    async execute(_id, params, signal) {
+      try {
+        const opts = parseModelArgs("");
+        if (params.provider !== undefined) opts.provider = params.provider;
+        if (params.search !== undefined) opts.search = params.search;
+        if (params.page !== undefined) opts.page = params.page;
+        if (params.limit !== undefined) opts.limit = params.limit;
+        opts.refresh = Boolean(params.refresh);
+        opts.refreshAll = Boolean(params.refresh_all);
+        opts.includeText = Boolean(params.include_text);
+        return { content: [{ type: "text", text: await modelsText(opts, signal) }], details: {} };
+      }
+      catch (e) { throw new Error(configErrorText(e)); }
+    },
+  });
+
+  pi.registerTool({
+    name: "image_config",
+    label: "图片生成配置",
+    description: "管理全局图片生成提供商、API 配置、模型和默认设置。",
+    promptSnippet: "管理全局图片生成提供商、API 配置、模型和默认设置。",
+    parameters: Type.Object({}),
+    async execute(_id, _params, signal) {
+      try { return { content: [{ type: "text", text: await configText(signal) }], details: {} }; }
+      catch (e) { throw new Error(configErrorText(e)); }
+    },
+  });
+
+  pi.registerTool({
+    name: "image_providers",
+    label: "提供商列表",
+    description: "列出已配置的图片提供商及其状态。",
+    promptSnippet: "列出已配置的图片提供商及其状态。",
+    parameters: Type.Object({}),
+    async execute(_id, _params, signal) {
+      try { return { content: [{ type: "text", text: await providersText(signal) }], details: {} }; }
+      catch (e) { throw new Error(configErrorText(e)); }
+    },
+  });
+
+  pi.registerCommand("image-config", { description: "图片生成配置：添加提供商、获取模型、设置默认提供商。", handler: async (_args, ctx) => handleConfigCommand(ctx) });
+}
+
+function parseModelArgs(args: string) {
+  const parts = args.trim().split(/\s+/).filter(Boolean);
+  const result: { provider?: string; search?: string; page?: number; limit?: number; refresh?: boolean; refreshAll?: boolean; includeText?: boolean } = {};
+  for (let i = 0; i < parts.length; i += 1) {
+    const p = parts[i]!;
+    if (p === "--refresh") result.refresh = true;
+    else if (p === "--refresh-all") result.refreshAll = true;
+    else if (p === "--include-text") result.includeText = true;
+    else if (p === "--provider") {
+      const value = parts[++i];
+      if (value !== undefined) result.provider = value;
+    }
+    else if (p === "--page") result.page = Number(parts[++i]);
+    else if (p === "--limit") result.limit = Number(parts[++i]);
+    else result.search = result.search ? `${result.search} ${p}` : p;
+  }
+  return result;
+}
+
+async function handleConfigCommand(ctx: ExtensionCommandContext): Promise<void> {
+  // 与 Vision 配置面板相同：始终在本 command 内循环，取消或“返回”才关闭。
+  while (true) {
+    const global = await new GlobalConfigStore().read();
+    const current = global.defaultProviderId ? global.providers.find((provider) => provider.id === global.defaultProviderId) : undefined;
+    const options = global.providers.length === 0
+      ? ["+ 添加提供商", "取消"]
+      : [
+        ...global.providers.map((provider) => `${provider.id === global.defaultProviderId ? "●" : "○"} ${provider.name} — ${provider.defaultModel ?? "未设置默认模型"} [${provider.id}]`),
+        "+ 添加提供商", "查看当前配置", "取消",
+      ];
+    const picked = await ctx.ui.select(`图片生成 Provider 设置\n当前：${current ? `${current.name} (${current.defaultModel ?? "未设置默认模型"})` : "未配置"}`, options);
+    if (!picked || picked === "取消") return;
+    if (picked === "+ 添加提供商") { await interactiveAddProvider(ctx); continue; }
+    if (picked === "查看当前配置") { ctx.ui.notify(await configText(ctx.signal), "info"); continue; }
+    const id = picked.match(/\[([^\]]+)\]$/)?.[1];
+    const provider = id ? global.providers.find((item) => item.id === id) : undefined;
+    if (provider) await handleProviderActions(ctx, provider.id);
+  }
+}
+
+async function interactiveAddProvider(ctx: ExtensionCommandContext): Promise<void> {
+  const store = new GlobalConfigStore();
+  const before = await store.read();
+  const name = await ctx.ui.input("添加图片提供商 - 提供商名称", "例如：OpenAI");
+  if (!name) return;
+  const baseUrl = await ctx.ui.input("添加图片提供商 - API Base URL", "例如：https://api.openai.com/v1");
+  if (!baseUrl) return;
+  const apiKey = await ctx.ui.input("添加图片提供商 - API Key", "请输入 API Key");
+  if (!apiKey) return;
+
+  ctx.ui.notify("正在测试连接并获取模型，请稍候……", "info");
+  try {
+    const discovery = await discoverProviderCandidate({ name, baseUrl, apiKey }, ctx.signal);
+    ctx.ui.notify(renderDiscoveryChoiceText(discovery), "info");
+    const defaultModel = await selectDefaultImageModel(ctx, discovery);
+    if (!defaultModel) { ctx.ui.notify("已取消添加：未选择默认图片模型。", "info"); return; }
+    let setDefault = before.providers.length === 0;
+    if (!setDefault && before.defaultProviderId) setDefault = await ctx.ui.confirm("设置默认提供商", `是否将 ${name} 设置为默认图片提供商？`);
+    const responseFormat = await chooseResponseFormat(ctx, "自动兼容（推荐）");
+    if (!responseFormat) return;
+    const input: { name: string; baseUrl: string; apiKey: string; defaultModel?: string; responseFormat?: "auto" | "url" | "b64_json"; setDefault?: boolean } = { name, baseUrl, apiKey, responseFormat, setDefault };
+    if (defaultModel) input.defaultModel = defaultModel;
+    ctx.ui.notify(await saveProviderWithDiscovery(input, discovery, store), "info");
+    ctx.ui.notify(await configText(ctx.signal), "info");
+  } catch (e) {
+    ctx.ui.notify(configErrorText(e), "error");
+    const next = await ctx.ui.select("模型发现失败", ["重试", "手动指定模型", "返回"]);
+    if (next === "重试") await interactiveAddProvider(ctx);
+    else if (next === "手动指定模型") {
+      const defaultModel = await ctx.ui.input("手动指定默认图片模型", "例如：flux-pro");
+      if (!defaultModel) return;
+      const setDefault = before.providers.length === 0 || await ctx.ui.confirm("设置默认提供商", `是否将 ${name} 设置为默认图片提供商？`);
+      ctx.ui.notify(await saveProviderWithoutDiscovery({ name, baseUrl, apiKey, defaultModel, setDefault }, store), "info");
+      ctx.ui.notify(await configText(ctx.signal), "info");
+    }
+  }
+}
+
+async function handleProvidersCommand(ctx: ExtensionCommandContext): Promise<void> {
+  // 兼容旧调用入口；实际 Provider 选择已经收进主配置面板。
+  await handleConfigCommand(ctx);
+}
+
+async function handleProviderActions(ctx: ExtensionCommandContext, id: string): Promise<void> {
+  while (true) {
+    const provider = await new GlobalConfigStore().resolveProvider(id);
+    if (!provider) { ctx.ui.notify(`提供商不存在：${id}`, "warning"); return; }
+    const action = await ctx.ui.select(`图片提供商：${provider.name}`, ["✎ 编辑提供商", "选择默认图片模型", "设为默认提供商", "✕ 删除提供商", "返回"]);
+    if (!action || action === "返回") return;
+    try {
+      if (action === "✎ 编辑提供商") await interactiveEditProvider(ctx, provider.id);
+      else if (action === "选择默认图片模型") await chooseProviderModel(ctx, provider.id);
+      else if (action === "设为默认提供商") ctx.ui.notify(await setDefaultProvider(provider.id), "info");
+      else if (action === "✕ 删除提供商" && await ctx.ui.confirm("删除图片提供商？", `确定删除 “${provider.name}” 吗？`)) { ctx.ui.notify(await deleteProvider(provider.id), "warning"); return; }
+    } catch (error) { ctx.ui.notify(configErrorText(error), "error"); }
+  }
+}
+
+async function interactiveEditProvider(ctx: ExtensionCommandContext, id: string): Promise<void> {
+  const store = new GlobalConfigStore();
+  const provider = await store.resolveProvider(id);
+  if (!provider) { ctx.ui.notify(`提供商不存在：${id}`, "error"); return; }
+
+  // 直接打开回填后的表单；Provider ID 是唯一身份，空输入不会覆盖已保存的值。
+  const name = await prefilledInput(ctx, "编辑提供商 - 提供商名称", provider.name);
+  if (name === undefined) return;
+  const baseUrl = await prefilledInput(ctx, "编辑提供商 - API Base URL", provider.baseUrl);
+  if (baseUrl === undefined) return;
+  const apiKeyInput = await prefilledInput(ctx, "编辑提供商 - API Key", maskApiKey(provider.apiKey));
+  if (apiKeyInput === undefined) return;
+  const modelInput = provider.defaultModel ?? "";
+  const nextName = name || provider.name;
+  const nextBaseUrl = baseUrl || provider.baseUrl;
+  const nextApiKey = normalizeEditedApiKey(apiKeyInput, provider.apiKey);
+  const urlChanged = nextBaseUrl !== provider.baseUrl;
+  const keyChanged = nextApiKey !== provider.apiKey;
+
+  try {
+    const discovery = urlChanged || keyChanged
+      ? await discoverProviderCandidate({ name: nextName, baseUrl: nextBaseUrl, apiKey: nextApiKey }, ctx.signal)
+      : await (await createService(provider.id)).discover(false, ctx.signal);
+    ctx.ui.notify(renderDiscoveryChoiceText(discovery), "info");
+    const defaultModel = await selectDefaultImageModel(ctx, discovery, modelInput || provider.defaultModel);
+    if (!defaultModel) { ctx.ui.notify("已取消编辑：未选择默认图片模型。", "info"); return; }
+    const responseFormat = await chooseResponseFormat(ctx, responseFormatLabel(provider.responseFormat ?? "auto"));
+    if (!responseFormat) return;
+    const input: { id: string; name?: string; baseUrl?: string; apiKey?: string; defaultModel?: string; responseFormat?: "auto" | "url" | "b64_json" } = { id: provider.id, responseFormat };
+    if (nextName !== provider.name) input.name = nextName;
+    if (nextBaseUrl !== provider.baseUrl) input.baseUrl = nextBaseUrl;
+    if (nextApiKey !== provider.apiKey) input.apiKey = nextApiKey;
+    if (defaultModel && defaultModel !== provider.defaultModel) input.defaultModel = defaultModel;
+    ctx.ui.notify("正在保存提供商配置……", "info");
+    ctx.ui.notify(await updateProvider(input, ctx.signal, store, urlChanged || keyChanged), "info");
+    if ((await store.read()).defaultProviderId !== provider.id && await ctx.ui.confirm("默认提供商", "是否设为默认图片提供商？")) ctx.ui.notify(await setDefaultProvider(provider.id), "info");
+    ctx.ui.notify(await configText(ctx.signal), "info");
+  } catch (e) {
+    ctx.ui.notify(configErrorText(e), "error");
+    const fallback = await ctx.ui.select("无法自动获取模型", ["手动输入模型 ID", "返回"]);
+    if (fallback === "手动输入模型 ID") {
+      const defaultModel = await prefilledInput(ctx, "手动输入默认图片模型 ID", provider.defaultModel ?? "例如：flux-pro");
+      if (!defaultModel) return;
+      const responseFormat = await chooseResponseFormat(ctx, responseFormatLabel(provider.responseFormat ?? "auto"));
+      if (!responseFormat) return;
+      const input: { id: string; name?: string; baseUrl?: string; apiKey?: string; defaultModel?: string; responseFormat?: "auto" | "url" | "b64_json" } = { id: provider.id, defaultModel, responseFormat };
+      if (nextName !== provider.name) input.name = nextName;
+      if (nextBaseUrl !== provider.baseUrl) input.baseUrl = nextBaseUrl;
+      if (nextApiKey !== provider.apiKey) input.apiKey = nextApiKey;
+      ctx.ui.notify(await updateProvider(input, ctx.signal, store, false), "info");
+    }
+  }
+}
+
+async function chooseProviderModel(ctx: ExtensionCommandContext, id: string): Promise<void> {
+  const store = new GlobalConfigStore();
+  const provider = await store.resolveProvider(id);
+  if (!provider) { ctx.ui.notify(`提供商不存在：${id}`, "error"); return; }
+  try {
+    ctx.ui.notify("正在测试连接并获取模型，请稍候……", "info");
+    const discovery = await discoverProviderCandidate({ name: provider.name, baseUrl: provider.baseUrl, apiKey: provider.apiKey }, ctx.signal);
+    const model = await selectDefaultImageModel(ctx, discovery, provider.defaultModel, () => discoverProviderCandidate({ name: provider.name, baseUrl: provider.baseUrl, apiKey: provider.apiKey }, ctx.signal));
+    if (model && model !== provider.defaultModel) ctx.ui.notify(await updateProvider({ id: provider.id, defaultModel: model }, ctx.signal, store, false), "info");
+    else ctx.ui.notify("默认图片模型未改变。", "info");
+  } catch (error) {
+    ctx.ui.notify(configErrorText(error), "error");
+    const fallback = await ctx.ui.select("无法自动获取模型", ["手动输入模型 ID", "返回"]);
+    if (fallback === "手动输入模型 ID") {
+      const model = await prefilledInput(ctx, "手动输入默认图片模型 ID", provider.defaultModel ?? "");
+      if (model) ctx.ui.notify(await updateProvider({ id: provider.id, defaultModel: model }, ctx.signal, store, false), "info");
+    }
+  }
+}
+
+async function prefilledInput(ctx: ExtensionCommandContext, title: string, value: string): Promise<string | undefined> {
+  return ctx.ui.editor(title, value);
+}
+
+async function safeProviderStatus(id: string, signal?: AbortSignal): Promise<string> {
+  try { return await providerStatus(id, signal); }
+  catch (error) { return configErrorText(error); }
+}
+
+const MODEL_PAGE_SIZE = 20;
+const MODEL_LABEL_LIMIT = 72;
+
+async function selectDefaultImageModel(ctx: ExtensionCommandContext, discovery: DiscoveryResult, current?: string, refresh?: () => Promise<DiscoveryResult>): Promise<string | undefined> {
+  let activeDiscovery = discovery;
+  if (new ModelRegistry(activeDiscovery.models).byCapability("image_generation").length === 0) {
+    ctx.ui.notify("/models 未返回可确认的图片生成模型。", "warning");
+    const fallback = await ctx.ui.select("选择默认图片模型", ["手动输入模型 ID", "取消"]);
+    if (fallback !== "手动输入模型 ID") return undefined;
+    const manual = await prefilledInput(ctx, "默认图片模型 ID", current ?? "");
+    return manual?.trim() || undefined;
+  }
+
+  let query = "";
+  let page = 0;
+  while (true) {
+    const models = new ModelRegistry(activeDiscovery.models).byCapability("image_generation").map((model) => model.id);
+    const filtered = query ? models.filter((model) => model.toLowerCase().includes(query.toLowerCase())) : models;
+    const pageCount = Math.max(1, Math.ceil(filtered.length / MODEL_PAGE_SIZE));
+    page = Math.min(page, pageCount - 1);
+    const visible = filtered.slice(page * MODEL_PAGE_SIZE, (page + 1) * MODEL_PAGE_SIZE);
+    const options = visible.map((model, index) => `${model === current ? "●" : "○"} ${modelLabel(model)} [#${index + 1}]`);
+    if (current && !filtered.includes(current)) options.unshift(`● 当前模型：${modelLabel(current)}${models.includes(current) ? "（被筛选隐藏）" : "（API 未返回）"}`);
+    if (page > 0) options.push("‹ 上一页模型");
+    if (page + 1 < pageCount) options.push("下一页模型 ›");
+    options.push("⌕ 搜索/过滤模型", "↻ 重新获取模型", "取消");
+    const picked = await ctx.ui.select(`选择默认图片模型（${filtered.length}/${models.length}，第 ${page + 1}/${pageCount} 页）`, options);
+    if (!picked || picked === "取消") return undefined;
+    if (picked === "⌕ 搜索/过滤模型") {
+      const next = await ctx.ui.input("搜索模型（留空显示全部）", query || "例如：flux 或 gpt-image");
+      if (next === undefined) return undefined;
+      query = next.trim(); page = 0; continue;
+    }
+    if (picked === "‹ 上一页模型") { page--; continue; }
+    if (picked === "下一页模型 ›") { page++; continue; }
+    if (picked === "↻ 重新获取模型") {
+      if (!refresh) { ctx.ui.notify("当前流程无法重新获取模型，请返回后再试。", "info"); continue; }
+      ctx.ui.notify("正在重新获取模型，请稍候……", "info");
+      try { activeDiscovery = await refresh(); query = ""; page = 0; }
+      catch (error) { ctx.ui.notify(configErrorText(error), "error"); }
+      continue;
+    }
+    if (picked.startsWith("● 当前模型：")) return current;
+    const match = picked.match(/\[#(\d+)\]$/);
+    const selected = match ? visible[Number(match[1]) - 1] : undefined;
+    if (selected) return selected;
+  }
+}
+
+function modelLabel(model: string): string {
+  return model.length > MODEL_LABEL_LIMIT ? `${model.slice(0, MODEL_LABEL_LIMIT - 3)}...` : model;
+}
+
+function renderDiscoveryChoiceText(discovery: DiscoveryResult): string {
+  const summary = new ModelRegistry(discovery.models).summary();
+  return [
+    "连接成功 ✓",
+    `发现模型：${discovery.models.length} 个`,
+    `图片生成模型：${summary.image_generation.length} 个`,
+    `图片编辑模型：${summary.image_edit.length} 个`,
+    `图片变体模型：${summary.image_variation.length} 个`,
+    `视觉理解模型：${summary.vision.length} 个`,
+  ].join("\n");
+}
+
+async function chooseResponseFormat(ctx: ExtensionCommandContext, current: string): Promise<"auto" | "url" | "b64_json" | undefined> {
+  const picked = await ctx.ui.select(`图片响应格式（当前：${current}）`, ["自动兼容（推荐）", "仅 URL", "仅 Base64 JSON", "取消"]);
+  if (!picked || picked === "取消") return undefined;
+  return picked === "仅 URL" ? "url" : picked === "仅 Base64 JSON" ? "b64_json" : "auto";
+}
+
+function responseFormatLabel(format: "auto" | "url" | "b64_json"): string {
+  return format === "url" ? "仅 URL" : format === "b64_json" ? "仅 Base64 JSON" : "自动兼容（推荐）";
+}
+
+function normalizeEditedApiKey(input: string | undefined, current: string): string {
+  if (!input || input === maskApiKey(current) || input === "已配置") return current;
+  return input;
+}
+
+async function saveProviderWithoutDiscovery(input: { name: string; baseUrl: string; apiKey: string; defaultModel: string; setDefault: boolean }, store: GlobalConfigStore): Promise<string> {
+  const provider = await store.addProvider(input);
+  if (input.setDefault) await store.setDefaultProvider(provider.id);
+  return [`提供商已保存：${provider.name} (${provider.id})`, `默认模型：${provider.defaultModel ?? "未设置"}`, "模型发现：未执行，已手动指定模型。"].join("\n");
+}

package/src/providers/openai-compatible.ts

@@ -0,0 +1,198 @@
+import { detectCapabilities } from "../core/capabilities.js";
+import { ImageGenError, errorFromStatus, sanitizeSecret } from "../core/errors.js";
+import type { EditParams, GenerateParams, ImageGenConfig, ImageOperationResult, ImageProvider, ModelInfo, VariationParams } from "../core/types.js";
+import { downloadImage, fetchWithTimeout, parseJsonLimited, readResponseTextLimited } from "../utils/download.js";
+import { decodeBase64Image, loadLocalImage, saveImageBuffer } from "../utils/files.js";
+
+interface OpenAIModelResponse { data?: unknown[]; object?: string }
+interface OpenAIImageItem { url?: string; image_url?: string; image?: string; b64_json?: string; revised_prompt?: string }
+interface OpenAIImageResponse { data?: OpenAIImageItem[]; created?: number }
+
+export class OpenAICompatibleProvider implements ImageProvider {
+  readonly type = "openai-compatible";
+  readonly name = "OpenAI-compatible";
+  constructor(private readonly config: ImageGenConfig) {}
+
+  async discoverModels(signal?: AbortSignal): Promise<ModelInfo[]> {
+    const response = await this.request("GET", "/models", undefined, "获取模型列表", signal);
+    if (response.status === 404) {
+      if (this.config.model) return [this.modelFromId(this.config.model, { fallback: true })];
+      throw errorFromStatus(404, "获取模型列表");
+    }
+    if (!response.ok) {
+      if (this.config.model && (response.status === 404 || response.status === 405)) return [this.modelFromId(this.config.model, { fallback: true })];
+      throw errorFromStatus(response.status, "获取模型列表");
+    }
+    let json: OpenAIModelResponse;
+    try {
+      json = await parseJsonLimited(response, this.config.maxResponseBytes) as OpenAIModelResponse;
+    } catch (error) {
+      if (this.config.model && error instanceof ImageGenError && error.code === "invalid_json") return [this.modelFromId(this.config.model, { fallback: true })];
+      throw error;
+    }
+    if (!Array.isArray(json.data)) {
+      if (this.config.model) return [this.modelFromId(this.config.model, { fallback: true })];
+      throw new ImageGenError("invalid_json", "/models 响应不包含 data 数组。", "该服务商可能不支持 /models；请在添加 Provider 时手动指定模型 ID。 ");
+    }
+    const models = json.data.map((item) => this.modelFromRaw(item)).filter((m): m is ModelInfo => Boolean(m));
+    if (models.length === 0 && this.config.model) return [this.modelFromId(this.config.model, { fallback: true })];
+    return models;
+  }
+
+  async generate(params: GenerateParams, signal?: AbortSignal): Promise<ImageOperationResult> {
+    // auto 优先 URL（便于流式/CDN 服务），仅在服务端明确拒绝时降级为 b64_json。
+    const responseFormat = this.config.responseFormat === "b64_json" ? "b64_json" : "url";
+    const caps = params.modelCapabilities;
+    const body = compact({ model: params.model, prompt: params.prompt, size: caps?.supportsSize === false ? undefined : params.size, quality: caps?.supportsQuality === false ? undefined : params.quality, n: caps?.supportsMultipleImages === false ? 1 : params.n ?? 1, response_format: responseFormat, output_format: params.output_format, aspect_ratio: caps?.supportsAspectRatio === false ? undefined : params.aspect_ratio });
+    const json = await this.postImage("/images/generations", body, "生成图片", signal);
+    return this.saveImageResponse(json, params.model ?? "unknown");
+  }
+
+  async edit(params: EditParams, signal?: AbortSignal): Promise<ImageOperationResult> {
+    const image = await resolveImageInput(params.image, this.config, signal);
+    const form = new FormData();
+    form.set("model", params.model ?? "");
+    form.set("prompt", params.prompt);
+    if (params.size && params.modelCapabilities?.supportsSize !== false) form.set("size", params.size);
+    if (params.output_format) form.set("output_format", params.output_format);
+    form.set("image", new Blob([toArrayBuffer(image.buffer)], { type: image.mimeType }), image.name);
+    const json = await this.postImage("/images/edits", form, "编辑图片", signal);
+    return this.saveImageResponse(json, params.model ?? "unknown");
+  }
+
+  async variation(params: VariationParams, signal?: AbortSignal): Promise<ImageOperationResult> {
+    const image = await resolveImageInput(params.image, this.config, signal);
+    const form = new FormData();
+    form.set("model", params.model ?? "");
+    if (params.size && params.modelCapabilities?.supportsSize !== false) form.set("size", params.size);
+    if (params.n && params.modelCapabilities?.supportsMultipleImages !== false) form.set("n", String(params.n));
+    form.set("image", new Blob([toArrayBuffer(image.buffer)], { type: image.mimeType }), image.name);
+    const json = await this.postImage("/images/variations", form, "生成图片变体", signal);
+    return this.saveImageResponse(json, params.model ?? "unknown");
+  }
+
+  private async postImage(path: string, body: BodyInit | Record<string, unknown>, action: string, signal?: AbortSignal): Promise<OpenAIImageResponse> {
+    const isForm = body instanceof FormData;
+    let response = await this.request("POST", path, isForm ? body : JSON.stringify(body), action, signal, isForm ? undefined : "application/json");
+    let detail = response.ok ? undefined : await responseErrorDetail(response, this.config);
+    // 不同 OpenAI-compatible 服务对 response_format 的支持不一致；仅在服务端明确拒绝该字段时做一次无费用重试。
+    const jsonBody = !isForm && typeof body === "object" && body !== null && !ArrayBuffer.isView(body) && !(body instanceof ArrayBuffer) && !(body instanceof Blob) && !(body instanceof URLSearchParams) ? body as Record<string, unknown> : undefined;
+    if (!response.ok && this.config.responseFormat !== "url" && this.config.responseFormat !== "b64_json" && jsonBody?.response_format === "url" && isResponseFormatError(detail)) {
+      const retryBody = { ...jsonBody, response_format: "b64_json" };
+      response = await this.request("POST", path, JSON.stringify(retryBody), action, signal, "application/json");
+      detail = response.ok ? undefined : await responseErrorDetail(response, this.config);
+    }
+    if (!response.ok) throw errorFromStatus(response.status, action, detail);
+    const json = await parseJsonLimited(response, this.config.maxResponseBytes) as OpenAIImageResponse;
+    if (!Array.isArray(json.data)) throw new ImageGenError("invalid_json", `${action}响应不包含 data 数组。`, "确认服务商图片接口响应是否 OpenAI-compatible。 ");
+    return json;
+  }
+
+  private async request(method: string, path: string, body: BodyInit | undefined, action: string, signal?: AbortSignal, contentType?: string): Promise<Response> {
+    const headers: Record<string, string> = { Authorization: `Bearer ${this.config.apiKey}` };
+    if (contentType) headers["content-type"] = contentType;
+    try {
+      const init: RequestInit = { method, headers };
+      if (body !== undefined) init.body = body;
+      if (signal !== undefined) init.signal = signal;
+      return await fetchWithTimeout(`${this.config.baseUrl}${path}`, init, this.config.timeoutMs);
+    } catch (e) {
+      if (e instanceof ImageGenError) throw new ImageGenError(e.code, sanitizeSecret(e.message, this.config.apiKey), e.suggestion, e.status);
+      throw e;
+    }
+  }
+
+  private modelFromRaw(item: unknown): ModelInfo | undefined {
+    if (!item || typeof item !== "object") return undefined;
+    const record = item as Record<string, unknown>;
+    const id = typeof record.id === "string" ? record.id : typeof record.name === "string" ? record.name : undefined;
+    if (!id) return undefined;
+    return this.modelFromId(id, record);
+  }
+
+  private modelFromId(id: string, metadata: Record<string, unknown>): ModelInfo {
+    // fallback 仅由用户在配置界面明确手动指定默认模型时产生，视为图片生成模型。
+    const fallback = metadata.fallback === true;
+    const caps = detectCapabilities(id, metadata, this.config.manualCapabilities[id] ?? (fallback ? ["image_generation"] : undefined));
+    return { id, provider: this.type, rawMetadata: metadata, ...caps };
+  }
+
+  private async saveImageResponse(json: OpenAIImageResponse, model: string): Promise<ImageOperationResult> {
+    const images = [];
+    for (const [index, item] of json.data?.entries() ?? []) {
+      if (item.b64_json) {
+        const decoded = decodeBase64Image(item.b64_json);
+        images.push({ path: await saveImageBuffer(decoded.buffer, this.config.outputDir, decoded.ext), mimeType: decoded.mimeType, index });
+      } else {
+        const rawUrl = extractImageValue(item.url) ?? extractImageValue(item.image_url) ?? extractImageValue(item.image) ?? extractImageValue((item as Record<string, unknown>).image_base64);
+        if (!rawUrl) continue;
+        if (rawUrl.startsWith("data:")) {
+          const decoded = decodeBase64Image(rawUrl);
+          images.push({ path: await saveImageBuffer(decoded.buffer, this.config.outputDir, decoded.ext), mimeType: decoded.mimeType, index });
+          continue;
+        }
+        const imageUrl = resolveImageUrl(rawUrl, this.config.baseUrl);
+        const authorization = isSameOrigin(imageUrl, this.config.baseUrl) ? `Bearer ${this.config.apiKey}` : undefined;
+        const saved = await downloadImage(imageUrl, this.config.outputDir, this.config.timeoutMs, this.config.maxDownloadBytes, authorization);
+        images.push({ path: saved.path, url: imageUrl, mimeType: saved.mimeType, index });
+      }
+    }
+    if (images.length === 0) throw new ImageGenError("invalid_image", "API 未返回可保存的图片。", "确认响应包含 url 或 b64_json。 ");
+    return { provider: this.config.providerName, providerId: this.config.providerId, model, images, rawInfo: { created: json.created } };
+  }
+}
+
+async function resolveImageInput(input: string, config: ImageGenConfig, signal?: AbortSignal): Promise<{ name: string; buffer: Buffer; mimeType: string }> {
+  if (/^https?:\/\//i.test(input)) {
+    const authorization = isSameOrigin(input, config.baseUrl) ? `Bearer ${config.apiKey}` : undefined;
+    const saved = await downloadImage(input, config.outputDir, config.timeoutMs, config.maxDownloadBytes, authorization);
+    const local = await loadLocalImage(saved.path);
+    return local;
+  }
+  return loadLocalImage(input);
+}
+
+async function responseErrorDetail(response: Response, config: ImageGenConfig): Promise<string | undefined> {
+  try {
+    const raw = await readResponseTextLimited(response, Math.min(config.maxResponseBytes, 32_768));
+    let detail = raw;
+    try {
+      const json = JSON.parse(raw) as { error?: { message?: unknown }; message?: unknown };
+      detail = typeof json.error?.message === "string" ? json.error.message : typeof json.message === "string" ? json.message : raw;
+    } catch { /* 非 JSON 错误页仅保留单行短摘要。 */ }
+    const safe = sanitizeSecret(detail, config.apiKey).replace(/\s+/g, " ").trim();
+    return safe ? safe.slice(0, 500) : undefined;
+  } catch { return undefined; }
+}
+
+function extractImageValue(value: unknown): string | undefined {
+  if (typeof value === "string") return value;
+  if (value && typeof value === "object") {
+    const record = value as Record<string, unknown>;
+    if (typeof record.url === "string") return record.url;
+    if (typeof record.b64_json === "string") return `data:image/png;base64,${record.b64_json}`;
+  }
+  return undefined;
+}
+
+function isResponseFormatError(detail?: string): boolean {
+  return Boolean(detail && /response_format|b64_json|base64.*format/i.test(detail));
+}
+
+function isSameOrigin(imageUrl: string, baseUrl: string): boolean {
+  try { return new URL(imageUrl).origin === new URL(baseUrl).origin; }
+  catch { return false; }
+}
+
+function resolveImageUrl(raw: string, baseUrl: string): string {
+  try { return new URL(raw, `${baseUrl}/`).toString(); }
+  catch { throw new ImageGenError("invalid_image", "Provider 返回的图片地址无效。", "确认响应中的图片 URL 或图片字段是有效 http/https 地址。 "); }
+}
+
+function compact(obj: Record<string, unknown>): Record<string, unknown> {
+  return Object.fromEntries(Object.entries(obj).filter(([, v]) => v !== undefined && v !== ""));
+}
+
+function toArrayBuffer(buffer: Buffer): ArrayBuffer {
+  return buffer.buffer.slice(buffer.byteOffset, buffer.byteOffset + buffer.byteLength) as ArrayBuffer;
+}