@xinizai/pi-image-gen 0.1.0

package/src/tools/shared.ts

@@ -0,0 +1,235 @@
+import { ImageService } from "../core/image-service.js";
+import { ModelDiscoveryCache } from "../core/cache.js";
+import { resolveProvider } from "../core/provider.js";
+import { ModelRegistry } from "../core/model-registry.js";
+import { normalizeBaseUrl } from "../utils/config.js";
+import { GlobalConfigStore, PROVIDERS_FILE, resolveRuntimeConfig } from "../core/global-config.js";
+import { ImageGenError, maskApiKey } from "../core/errors.js";
+import { DEFAULT_MODEL_LIMIT, renderModelBrowser, renderRefreshSummary } from "../core/model-browser.js";
+import type { DiscoveryResult, ImageOperationResult, ModelBrowserOptions, ModelCapability, StoredProviderConfig } from "../core/types.js";
+
+export async function createService(providerId?: string, env = process.env): Promise<ImageService> {
+  const config = await resolveRuntimeConfig(providerId, env);
+  return new ImageService(config, resolveProvider(config));
+}
+
+export function resultText(title: string, result: ImageOperationResult): string {
+  const lines = [`${title}完成。`, `提供商：${result.provider}（${result.providerId}）`, `模型：${result.model}`, "图片："];
+  for (const image of result.images) lines.push(`- ${image.path}${image.url ? `（源地址：${image.url}）` : ""}`);
+  return lines.join("\n");
+}
+
+export function configErrorText(error: unknown): string {
+  if (error instanceof ImageGenError) return error.toUserMessage();
+  if (error instanceof Error) return error.message;
+  return String(error);
+}
+
+export async function modelsText(options: Partial<ModelBrowserOptions>, signal?: AbortSignal): Promise<string> {
+  const parsed: ModelBrowserOptions = { page: options.page ?? 1, limit: options.limit ?? DEFAULT_MODEL_LIMIT, refresh: Boolean(options.refresh), refreshAll: Boolean(options.refreshAll), includeText: Boolean(options.includeText) };
+  if (options.provider !== undefined) parsed.provider = options.provider;
+  if (options.search !== undefined) parsed.search = options.search;
+  const store = new GlobalConfigStore();
+  if (parsed.refreshAll) {
+    const config = await store.read();
+    if (config.providers.length === 0) return notConfiguredText();
+    const summaries: string[] = [];
+    for (const provider of config.providers) {
+      summaries.push(renderRefreshSummary(await refreshProvider(provider.id, store, signal)));
+    }
+    return summaries.join("\n\n");
+  }
+  const service = await createService(parsed.provider);
+  const result = await service.discover(parsed.refresh, signal);
+  return parsed.refresh ? renderRefreshSummary(result) : renderModelBrowser(result, parsed);
+}
+
+export async function configText(signal?: AbortSignal, store = new GlobalConfigStore()): Promise<string> {
+  const global = await store.read();
+  const lines: string[] = ["图片生成配置", `全局配置：${PROVIDERS_FILE}`, ""];
+  if (global.providers.length === 0) {
+    lines.push("还没有配置提供商。", "", "可用操作：", "→ 添加提供商");
+    return lines.join("\n");
+  }
+
+  const defaultProvider = global.defaultProviderId ? global.providers.find((provider) => provider.id === global.defaultProviderId) : undefined;
+  lines.push(`默认提供商：${defaultProvider ? `${defaultProvider.name} (${defaultProvider.id})` : "未设置"}`, "", "已配置提供商：");
+  let totalModels = 0;
+  let index = 1;
+  for (const provider of global.providers) {
+    const snapshot = await inspectProvider(provider.id, store, signal, false);
+    totalModels += snapshot.totalModels;
+    lines.push(`${index}. ${provider.name} (${provider.id})${global.defaultProviderId === provider.id ? " [默认]" : ""}`);
+    lines.push(`   状态：${snapshot.status}${snapshot.reason ? `，原因：${snapshot.reason}` : ""}`);
+    lines.push(`   模型来源：${provider.defaultModel && snapshot.totalModels === 1 && snapshot.summary.image_generation[0] === provider.defaultModel ? "手动指定或缓存 fallback" : "API 发现/缓存"}`);
+    lines.push(`   模型总数：${snapshot.totalModels}`);
+    lines.push(`   生图模型：${snapshot.summary.image_generation.length}`);
+    lines.push(`   图片编辑：${snapshot.summary.image_edit.length}`);
+    lines.push(`   图片变体：${snapshot.summary.image_variation.length}`);
+    lines.push(`   视觉理解：${snapshot.summary.vision.length}`);
+    lines.push("");
+    index += 1;
+  }
+  lines.push(`模型总数：${totalModels}`, "", "可用操作：", "→ 添加提供商", "→ 管理提供商", "→ 查看当前配置");
+  return lines.join("\n");
+}
+
+export async function providersText(signal?: AbortSignal): Promise<string> {
+  return configText(signal);
+}
+
+export async function discoverProviderCandidate(input: { name: string; baseUrl: string; apiKey: string; defaultModel?: string }, signal?: AbortSignal): Promise<DiscoveryResult> {
+  const now = new Date().toISOString();
+  const baseUrl = normalizeBaseUrl(input.baseUrl);
+  const config = await new GlobalConfigStore().toRuntimeConfig({
+    id: "pending-provider",
+    name: input.name,
+    providerType: "openai-compatible",
+    baseUrl,
+    apiKey: input.apiKey,
+    defaultModel: input.defaultModel,
+    defaultEditModel: undefined,
+    defaultVariationModel: undefined,
+    responseFormat: "auto",
+    manualCapabilities: {},
+    createdAt: now,
+    updatedAt: now,
+    apiKeyUpdatedAt: now,
+  });
+  const provider = resolveProvider(config);
+  const cache = new ModelDiscoveryCache();
+  return { providerId: config.providerId, providerName: config.providerName, providerType: provider.type, baseUrl: config.baseUrl, models: await provider.discoverModels(signal), discoveredAt: new Date().toISOString(), apiKeyFingerprint: cache.apiKeyFingerprint(config) };
+}
+
+export async function saveProviderWithDiscovery(input: { name: string; baseUrl: string; apiKey: string; defaultModel?: string; responseFormat?: "auto" | "url" | "b64_json"; setDefault?: boolean }, discovery: DiscoveryResult, store = new GlobalConfigStore()): Promise<string> {
+  const existing = await store.read();
+  const provider = await store.addProvider(input);
+  const shouldSetDefault = existing.providers.length === 0 || Boolean(input.setDefault);
+  if (shouldSetDefault) await store.setDefaultProvider(provider.id);
+  const runtime = await store.toRuntimeConfig(provider);
+  await new ModelDiscoveryCache().set(runtime, { ...discovery, providerId: provider.id, providerName: provider.name, baseUrl: provider.baseUrl });
+  const summary = new ModelRegistry(discovery.models).summary();
+  return [
+    `提供商已保存：${provider.name} (${provider.id})`,
+    `默认提供商：${shouldSetDefault ? `${provider.name} (${provider.id})` : "未变更"}`,
+    "连接：已连接",
+    "模型发现：成功",
+    `模型总数：${discovery.models.length}`,
+    `生图模型：${summary.image_generation.length}`,
+    `图片编辑：${summary.image_edit.length}`,
+    `图片变体：${summary.image_variation.length}`,
+    `视觉理解：${summary.vision.length}`,
+  ].join("\n");
+}
+
+export async function addProvider(input: { name: string; baseUrl: string; apiKey: string; defaultModel?: string; setDefault?: boolean }, signal?: AbortSignal, store = new GlobalConfigStore()): Promise<string> {
+  const existing = await store.read();
+  const provider = await store.addProvider(input);
+  const shouldSetDefault = existing.providers.length === 0 || Boolean(input.setDefault);
+  if (shouldSetDefault) await store.setDefaultProvider(provider.id);
+  const snapshot = await inspectProvider(provider.id, store, signal, true).catch((error) => ({ status: statusFromError(error), reason: reasonFromError(error), totalModels: 0, summary: emptySummary() }));
+  const lines = [
+    `提供商已保存：${provider.name} (${provider.id})`,
+    `默认提供商：${shouldSetDefault ? `${provider.name} (${provider.id})` : "未变更"}`,
+    `连接：${snapshot.status}${snapshot.reason ? `，原因：${snapshot.reason}` : ""}`,
+  ];
+  if (snapshot.status === "已连接") {
+    lines.push(`模型发现：成功`, `模型总数：${snapshot.totalModels}`, `生图模型：${snapshot.summary.image_generation.length}`, `图片编辑：${snapshot.summary.image_edit.length}`, `图片变体：${snapshot.summary.image_variation.length}`, `视觉理解：${snapshot.summary.vision.length}`);
+  } else {
+    lines.push(`模型发现：失败`, `原因：${snapshot.reason ?? "未知错误"}`);
+  }
+  return lines.join("\n");
+}
+
+export async function updateProvider(input: { id: string; name?: string; baseUrl?: string; apiKey?: string; defaultModel?: string; responseFormat?: "auto" | "url" | "b64_json" }, signal?: AbortSignal, store = new GlobalConfigStore(), refresh = true): Promise<string> {
+  const patch: Partial<StoredProviderConfig> = {};
+  if (input.name) patch.name = input.name;
+  if (input.baseUrl) patch.baseUrl = input.baseUrl;
+  if (input.apiKey) patch.apiKey = input.apiKey;
+  if (input.defaultModel) patch.defaultModel = input.defaultModel;
+  if (input.responseFormat) patch.responseFormat = input.responseFormat;
+  const provider = await store.updateProvider(input.id, patch);
+  const snapshot = await inspectProvider(provider.id, store, signal, refresh).catch((error) => ({ status: statusFromError(error), reason: reasonFromError(error), totalModels: 0, summary: emptySummary() }));
+  return [
+    `提供商已更新：${provider.name} (${provider.id})`,
+    `连接：${snapshot.status}${snapshot.reason ? `，原因：${snapshot.reason}` : ""}`,
+    `模型总数：${snapshot.totalModels}`,
+    `生图模型：${snapshot.summary.image_generation.length}`,
+    `图片编辑：${snapshot.summary.image_edit.length}`,
+  ].join("\n");
+}
+
+export async function deleteProvider(id: string, store = new GlobalConfigStore()): Promise<string> {
+  await store.deleteProvider(id);
+  return `提供商已删除：${id}`;
+}
+
+export async function setDefaultProvider(id: string, store = new GlobalConfigStore()): Promise<string> {
+  await store.setDefaultProvider(id);
+  return `默认提供商已设置：${id}`;
+}
+
+export async function providerStatus(id: string, signal?: AbortSignal, store = new GlobalConfigStore()): Promise<string> {
+  const snapshot = await inspectProvider(id, store, signal, true);
+  return [
+    `提供商：${snapshot.provider.name} (${snapshot.provider.id})`,
+    `状态：${snapshot.status}${snapshot.reason ? `，原因：${snapshot.reason}` : ""}`,
+    `模型总数：${snapshot.totalModels}`,
+    `生图模型：${snapshot.summary.image_generation.length}`,
+    `图片编辑：${snapshot.summary.image_edit.length}`,
+    `图片变体：${snapshot.summary.image_variation.length}`,
+    `视觉理解：${snapshot.summary.vision.length}`,
+  ].join("\n");
+}
+
+export function notConfiguredText(): string {
+  return `还没有配置图片提供商。\n请运行 /image-config 添加全局图片提供商。\n全局配置位置：${PROVIDERS_FILE}`;
+}
+
+async function refreshProvider(id: string, store: GlobalConfigStore, signal?: AbortSignal): Promise<DiscoveryResult> {
+  const provider = await store.resolveProvider(id);
+  if (!provider) throw new ImageGenError("missing_config", `提供商 ${id} 不存在。`, "请在 /image-config 中重新添加或选择其他提供商。");
+  const runtime = await store.toRuntimeConfig(provider);
+  const service = new ImageService(runtime, resolveProvider(runtime));
+  return service.discover(true, signal);
+}
+
+async function inspectProvider(id: string, store: GlobalConfigStore, signal?: AbortSignal, refresh = false): Promise<{ provider: StoredProviderConfig; status: string; reason?: string; totalModels: number; summary: Record<ModelCapability, string[]> }> {
+  const provider = await store.resolveProvider(id);
+  if (!provider) throw new ImageGenError("missing_config", `提供商 ${id} 不存在。`, "请在 /image-config 中重新添加或选择其他提供商。");
+  const runtime = await store.toRuntimeConfig(provider);
+  const service = new ImageService(runtime, resolveProvider(runtime));
+  try {
+    const registry = await service.registry(refresh, signal);
+    return { provider, status: "已连接", totalModels: registry.all().length, summary: registry.summary() };
+  } catch (error) {
+    return { provider, status: statusFromError(error), reason: reasonFromError(error), totalModels: 0, summary: emptySummary() };
+  }
+}
+
+function statusFromError(error: unknown): string {
+  if (error instanceof ImageGenError) {
+    if (error.code === "missing_config") return "未配置";
+    if (error.code === "timeout") return "网络超时";
+    if (error.code === "invalid_json") return "模型接口不兼容";
+    if (error.code === "unsupported_format") return "格式不支持";
+    return "连接失败";
+  }
+  return "连接失败";
+}
+
+function reasonFromError(error: unknown): string {
+  if (error instanceof ImageGenError) {
+    if (error.code === "auth_failed" || error.code === "forbidden") return "API Key 无效或无权限";
+    if (error.code === "not_found") return "API 地址可能不正确，无法找到模型接口";
+    if (error.code === "timeout") return "无法连接到 API，请检查 Base URL 和网络";
+    if (error.code === "unsupported_format") return error.message;
+    return error.toUserMessage();
+  }
+  if (error instanceof Error) return error.message;
+  return String(error);
+}
+
+function emptySummary(): Record<ModelCapability, string[]> {
+  return { text: [], vision: [], image_generation: [], image_edit: [], image_variation: [], unknown: [] };
+}

package/src/utils/config.ts

@@ -0,0 +1,61 @@
+import { homedir } from "node:os";
+import { resolve } from "node:path";
+import { ImageGenError } from "../core/errors.js";
+import type { ImageGenConfig, ModelCapability } from "../core/types.js";
+
+export function normalizeBaseUrl(raw: string): string {
+  const trimmed = raw.trim().replace(/\/+$/, "");
+  let url: URL;
+  try { url = new URL(trimmed); } catch {
+    throw new ImageGenError("invalid_base_url", "IMAGE_BASE_URL 无效。", "使用完整 http/https URL，例如 https://example.com/v1。");
+  }
+  if (url.protocol !== "https:" && url.protocol !== "http:") {
+    throw new ImageGenError("invalid_base_url", "IMAGE_BASE_URL 协议不受支持。", "只允许 http 或 https。生产环境建议 https。");
+  }
+  if (/\/images\/(generations|edits|variations)$/i.test(url.pathname.replace(/\/+$/, ""))) {
+    throw new ImageGenError("invalid_base_url", "API Base URL 不应包含图片接口路径。", "请填写到 /v1，例如 https://xxx/v1；不要填写 https://xxx/v1/images/generations。");
+  }
+  return url.toString().replace(/\/+$/, "");
+}
+
+export function parseManualCapabilities(raw?: string): Record<string, ModelCapability[]> {
+  if (!raw?.trim()) return {};
+  const result: Record<string, ModelCapability[]> = {};
+  for (const entry of raw.split(/[;\n]/)) {
+    const [model, caps] = entry.split(":");
+    if (!model?.trim() || !caps?.trim()) continue;
+    const parsed = caps.split(",").map((c) => c.trim()).filter(isCapability);
+    if (parsed.length > 0) result[model.trim()] = parsed;
+  }
+  return result;
+}
+
+export function isCapability(value: string): value is ModelCapability {
+  return ["text", "vision", "image_generation", "image_edit", "image_variation", "unknown"].includes(value);
+}
+
+export function readConfig(env: NodeJS.ProcessEnv = process.env): ImageGenConfig {
+  const baseUrlRaw = env.IMAGE_BASE_URL;
+  const apiKey = env.IMAGE_API_KEY;
+  if (!baseUrlRaw) throw new ImageGenError("missing_config", "缺少 IMAGE_BASE_URL。", "设置 IMAGE_BASE_URL=https://example.com/v1。 ");
+  if (!apiKey) throw new ImageGenError("missing_config", "缺少 IMAGE_API_KEY。", "设置 IMAGE_API_KEY=sk-xxxx。 ");
+  const outputDir = env.IMAGE_OUTPUT_DIR ? resolve(env.IMAGE_OUTPUT_DIR) : resolve(homedir(), ".pi", "agent", "generated");
+  return {
+    providerId: "env",
+    providerName: "Environment",
+    baseUrl: normalizeBaseUrl(baseUrlRaw),
+    apiKey,
+    model: env.IMAGE_MODEL || undefined,
+    editModel: env.IMAGE_EDIT_MODEL || undefined,
+    variationModel: env.IMAGE_VARIATION_MODEL || undefined,
+    responseFormat: "auto",
+    providerType: "openai-compatible",
+    timeoutMs: Number(env.IMAGE_TIMEOUT_SECONDS ?? 60) * 1000,
+    cacheTtlMs: Number(env.IMAGE_CACHE_TTL_SECONDS ?? 600) * 1000,
+    outputDir,
+    maxResponseBytes: Number(env.IMAGE_MAX_RESPONSE_BYTES ?? 8_000_000),
+    maxDownloadBytes: Number(env.IMAGE_MAX_DOWNLOAD_BYTES ?? 25_000_000),
+    manualCapabilities: parseManualCapabilities(env.IMAGE_MODEL_CAPABILITIES),
+    apiKeyUpdatedAt: "env",
+  };
+}

package/src/utils/download.ts

@@ -0,0 +1,103 @@
+import { ImageGenError, errorFromStatus } from "../core/errors.js";
+import { isIP } from "node:net";
+import { lookup } from "node:dns/promises";
+import { detectImageFormat, extensionForMime, saveImageBuffer } from "./files.js";
+
+export function assertSafeHttpUrl(raw: string): URL {
+  let url: URL;
+  try { url = new URL(raw); } catch { throw new ImageGenError("invalid_image", "图片 URL 无效。", "使用有效 https/http URL。 "); }
+  if (url.protocol !== "https:" && url.protocol !== "http:") throw new ImageGenError("invalid_image", "图片 URL 协议不受支持。", "只允许 http/https。 ");
+  if (!url.hostname || isBlockedHost(url.hostname)) throw new ImageGenError("invalid_image", "图片 URL 目标地址不安全。", "不能访问 localhost、内网地址或云元数据地址。 ");
+  return url;
+}
+
+export async function fetchWithTimeout(url: string, init: RequestInit, timeoutMs: number): Promise<Response> {
+  const controller = new AbortController();
+  const timer = setTimeout(() => controller.abort(), timeoutMs);
+  try {
+    const signal = init.signal ? AbortSignal.any([init.signal, controller.signal]) : controller.signal;
+    return await fetch(url, { ...init, signal });
+  } catch (e) {
+    if (controller.signal.aborted) throw new ImageGenError("timeout", "请求超时。", "稍后重试或增大 IMAGE_TIMEOUT_SECONDS。 ");
+    if (e instanceof Error && e.name === "AbortError") throw new ImageGenError("network_error", "请求已取消。", "重新发起操作即可。 ");
+    throw new ImageGenError("network_error", "网络请求失败。", e instanceof Error ? e.message : "检查网络连接。 ");
+  } finally {
+    clearTimeout(timer);
+  }
+}
+
+export async function readResponseTextLimited(response: Response, maxBytes: number): Promise<string> {
+  const len = Number(response.headers.get("content-length") ?? 0);
+  if (len > maxBytes) throw new ImageGenError("response_too_large", "API 响应超过安全大小限制。", "降低 n 或联系服务商。 ");
+  const text = await response.text();
+  if (Buffer.byteLength(text) > maxBytes) throw new ImageGenError("response_too_large", "API 响应超过安全大小限制。", "降低 n 或联系服务商。 ");
+  return text;
+}
+
+export async function parseJsonLimited(response: Response, maxBytes: number): Promise<unknown> {
+  const text = await readResponseTextLimited(response, maxBytes);
+  try { return JSON.parse(text) as unknown; } catch { throw new ImageGenError("invalid_json", "API 返回了无效 JSON。", "确认服务商是否兼容 OpenAI 风格 API。 "); }
+}
+
+function isBlockedHost(hostname: string): boolean {
+  const host = hostname.toLowerCase().replace(/[.]$/, "");
+  if (host === "localhost" || host.endsWith(".localhost") || host === "metadata.google.internal") return true;
+  const ip = isIP(host);
+  if (ip === 4) { const p = host.split(".").map(Number); return p.length === 4 && p[0] !== undefined && p[1] !== undefined && (p[0] === 10 || p[0] === 127 || (p[0] === 169 && p[1] === 254) || (p[0] === 192 && p[1] === 168) || (p[0] === 172 && p[1] >= 16 && p[1] <= 31)); }
+  if (ip === 6) return host === "::1" || host.startsWith("fc") || host.startsWith("fd") || host.startsWith("fe80:");
+  return false;
+}
+
+async function resolvesToPrivateHost(hostname: string): Promise<boolean> {
+  if (isBlockedHost(hostname)) return true;
+  try { const records = await lookup(hostname, { all: true }); return records.some((record) => isBlockedHost(record.address)); }
+  catch { return false; }
+}
+
+function rejectHtml(buffer: Buffer): void {
+  const prefix = buffer.subarray(0, 256).toString("utf8").trimStart().toLowerCase();
+  if (prefix.startsWith("<!doctype html") || prefix.startsWith("<html") || prefix.startsWith("<head") || prefix.startsWith("<body")) throw new ImageGenError("invalid_image", "下载内容不是图片，可能是鉴权页或错误页面。", "检查 Provider 图片 URL 和权限。 ");
+}
+
+export async function downloadImage(url: string, outputDir: string, timeoutMs: number, maxBytes: number, authorization?: string): Promise<{ path: string; mimeType: string }> {
+  let target = assertSafeHttpUrl(url);
+  if (await resolvesToPrivateHost(target.hostname)) throw new ImageGenError("invalid_image", "图片 URL 解析到不安全的内网地址。", "不能访问 localhost、内网地址或云元数据地址。 ");
+  const origin = target.origin;
+  let response: Response | undefined;
+  for (let redirects = 0; redirects <= 3; redirects += 1) {
+    const init: RequestInit = { method: "GET", redirect: "manual" };
+    if (authorization && target.origin === origin) init.headers = { Authorization: authorization };
+    response = await fetchWithTimeout(target.toString(), init, timeoutMs);
+    if (![301, 302, 303, 307, 308].includes(response.status)) break;
+    const location = response.headers.get("location");
+    if (!location) throw new ImageGenError("invalid_image", "图片下载重定向缺少目标地址。", "检查 Provider 返回的图片 URL。 ");
+    target = assertSafeHttpUrl(new URL(location, target).toString());
+    if (await resolvesToPrivateHost(target.hostname)) throw new ImageGenError("invalid_image", "图片重定向目标地址不安全。", "不能重定向到内网地址。 ");
+    if (redirects === 3) throw new ImageGenError("network_error", "图片下载重定向次数过多。", "使用稳定的图片 URL。 ");
+  }
+  if (!response) throw new ImageGenError("network_error", "图片下载失败。", "检查图片 URL。 ");
+  if (!response.ok) throw errorFromStatus(response.status, "下载图片");
+  const len = Number(response.headers.get("content-length") ?? 0);
+  if (len > maxBytes) throw new ImageGenError("download_too_large", "下载图片超过大小限制。", "设置更小输出或增大 IMAGE_MAX_DOWNLOAD_BYTES。 ");
+  const chunks: Uint8Array[] = [];
+  let total = 0;
+  if (!response.body) throw new ImageGenError("invalid_image", "下载响应没有内容。", "检查图片 URL。 ");
+  const reader = response.body.getReader();
+  while (true) {
+    const { done, value } = await reader.read();
+    if (done) break;
+    if (value) {
+      total += value.byteLength;
+      if (total > maxBytes) throw new ImageGenError("download_too_large", "下载图片超过大小限制。", "设置更小输出或增大 IMAGE_MAX_DOWNLOAD_BYTES。 ");
+      chunks.push(value);
+    }
+  }
+  const content = Buffer.concat(chunks);
+  rejectHtml(content);
+  const declaredMime = response.headers.get("content-type")?.split(";")[0];
+  const detected = detectImageFormat(content);
+  if (!detected) throw new ImageGenError("invalid_image", "下载内容不是有效图片。", "检查 Provider 图片 URL 和响应内容。 ");
+  const mimeType = declaredMime?.startsWith("image/") && extensionForMime(declaredMime) === detected.ext ? declaredMime : detected.mimeType;
+  const path = await saveImageBuffer(content, outputDir, detected.ext);
+  return { path, mimeType };
+}

package/src/utils/files.ts

@@ -0,0 +1,78 @@
+import { randomUUID } from "node:crypto";
+import { mkdir, readFile, writeFile } from "node:fs/promises";
+import { basename, extname, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+import { ImageGenError } from "../core/errors.js";
+
+const allowed = new Set([".png", ".jpg", ".jpeg", ".webp"]);
+
+export function detectImageFormat(buffer: Buffer): { mimeType: string; ext: string } | undefined {
+  if (buffer.length >= 8 && buffer.subarray(0, 8).equals(Buffer.from([137, 80, 78, 71, 13, 10, 26, 10]))) return { mimeType: "image/png", ext: "png" };
+  if (buffer.length >= 3 && buffer[0] === 0xff && buffer[1] === 0xd8 && buffer[2] === 0xff) return { mimeType: "image/jpeg", ext: "jpg" };
+  if (buffer.length >= 12 && buffer.toString("ascii", 0, 4) === "RIFF" && buffer.toString("ascii", 8, 12) === "WEBP") return { mimeType: "image/webp", ext: "webp" };
+  return undefined;
+}
+
+export function extensionForMime(mime: string, fallback = "png"): string {
+  if (mime.includes("jpeg") || mime.includes("jpg")) return "jpg";
+  if (mime.includes("webp")) return "webp";
+  if (mime.includes("png")) return "png";
+  return fallback.replace(/^\./, "");
+}
+
+export async function saveImageBuffer(buffer: Buffer, outputDir: string, ext: string): Promise<string> {
+  if (buffer.length === 0) throw new ImageGenError("invalid_image", "图片内容为空。", "检查 API 返回或输入文件。 ");
+  validateImageSignature(buffer, ext);
+  const cleanExt = ext.toLowerCase().replace(/^\./, "");
+  if (!["png", "jpg", "jpeg", "webp"].includes(cleanExt)) throw new ImageGenError("unsupported_format", `不支持的图片格式：${ext}`, "使用 png、jpg、jpeg 或 webp。 ");
+  await mkdir(outputDir, { recursive: true });
+  const date = new Date().toISOString().slice(0, 10);
+  const path = resolve(outputDir, `${date}-${randomUUID().slice(0, 8)}.${cleanExt === "jpeg" ? "jpg" : cleanExt}`);
+  await writeFile(path, buffer, { flag: "wx" });
+  return path;
+}
+
+export async function loadLocalImage(input: string): Promise<{ name: string; buffer: Buffer; mimeType: string }> {
+  const path = normalizeImagePath(input);
+  const ext = extname(path).toLowerCase();
+  if (!allowed.has(ext)) throw new ImageGenError("unsupported_format", `不支持的图片格式：${ext || "未知"}`, "仅支持 .png、.jpg、.jpeg、.webp。 ");
+  const buffer = await readFile(path).catch((cause: unknown) => {
+    throw new ImageGenError("invalid_image", `无法读取图片：${path}`, cause instanceof Error ? cause.message : "确认路径存在且可读。 ");
+  });
+  validateImageSignature(buffer, ext);
+  return { name: basename(path), buffer, mimeType: mimeFromExt(ext) };
+}
+
+export function normalizeImagePath(input: string): string {
+  const clean = input.startsWith("@") ? input.slice(1) : input;
+  if (clean.startsWith("file://")) return fileURLToPath(clean);
+  if (/^https?:\/\//i.test(clean)) throw new ImageGenError("unsupported_format", "此处需要本地图片路径。", "远程图片会由下载模块处理。 ");
+  return resolve(clean);
+}
+
+export function mimeFromExt(ext: string): string {
+  switch (ext.toLowerCase()) {
+    case ".jpg":
+    case ".jpeg": return "image/jpeg";
+    case ".webp": return "image/webp";
+    case ".png": return "image/png";
+    default: throw new ImageGenError("unsupported_format", `不支持的图片格式：${ext}`, "仅支持 png、jpg、jpeg、webp。 ");
+  }
+}
+
+function validateImageSignature(buffer: Buffer, ext: string): void {
+  const clean = ext.toLowerCase().replace(/^\./, "");
+  const png = buffer.length >= 8 && buffer.subarray(0, 8).equals(Buffer.from([137, 80, 78, 71, 13, 10, 26, 10]));
+  const jpg = buffer.length >= 3 && buffer[0] === 0xff && buffer[1] === 0xd8 && buffer[2] === 0xff;
+  const webp = buffer.length >= 12 && buffer.toString("ascii", 0, 4) === "RIFF" && buffer.toString("ascii", 8, 12) === "WEBP";
+  if ((clean === "png" && !png) || ((clean === "jpg" || clean === "jpeg") && !jpg) || (clean === "webp" && !webp)) throw new ImageGenError("invalid_image", "内容不是有效的图片文件。", "Provider 可能返回了鉴权页或错误页面。 ");
+}
+
+export function decodeBase64Image(data: string): { buffer: Buffer; mimeType: string; ext: string } {
+  const match = data.match(/^data:(image\/(png|jpeg|jpg|webp));base64,(.+)$/i);
+  const mimeType = match?.[1] ?? "image/png";
+  const payload = match?.[3] ?? data;
+  const buffer = Buffer.from(payload, "base64");
+  if (buffer.length === 0) throw new ImageGenError("invalid_image", "API 返回了空 base64 图片。", "检查服务商响应。 ");
+  return { buffer, mimeType, ext: extensionForMime(mimeType) };
+}