@dsh-plus/image-studio 0.1.0

package/src/provider/openai-images.ts

@@ -0,0 +1,266 @@
+/**
+ * OpenAI Images API 适配器（首批协议实现）。
+ * - 请求构造是纯函数（单测覆盖 JSON/multipart 两种形态）；
+ * - 执行走 node:http(s)，https 目标代理经 https-proxy-agent（与 llm-pi 同约定）；
+ * - 响应统一取回字节（url → 下载 / b64_json → 解码），调用方零二次请求。
+ * 开发测试指向本地 mock，严禁真实调用产生费用。
+ * @module image-studio/provider/openai-images
+ */
+import { request as httpRequest } from 'node:http'
+import { request as httpsRequest, type IncomingMessage } from 'node:https'
+import { HttpsProxyAgent } from 'https-proxy-agent'
+import type { GeneratedImage, InputImage, NormalizedRequest, ProviderResult } from './types.ts'
+import { ProviderError } from './types.ts'
+
+/** 顶层响应体上限（4K PNG 约 10-20MB，放宽到 64MB 防滥用）。 */
+const MAX_RESPONSE_BYTES = 64 * 1024 * 1024
+
+const MIME_BY_FORMAT: Record<string, string> = {
+  png: 'image/png',
+  jpeg: 'image/jpeg',
+  webp: 'image/webp',
+}
+
+/** output_format 参数值 → MIME（b64 结果无 content-type 时兜底）。 */
+export function mimeOfFormat(format: unknown): string {
+  return MIME_BY_FORMAT[format as string] ?? 'image/png'
+}
+
+/** 官方端点路径。 */
+export function endpointPath(endpoint: NormalizedRequest['endpoint']): string {
+  return endpoint === 'generation' ? '/images/generations' : '/images/edits'
+}
+
+interface HeaderLike {
+  [key: string]: string
+}
+
+/** 公共请求头（鉴权 + 用户附加头）。 */
+function baseHeaders(apiKey: string, extra?: Record<string, string>): HeaderLike {
+  return { authorization: `Bearer ${apiKey}`, ...extra }
+}
+
+/** multipart 文本字段分片。 */
+function formField(name: string, value: string): string {
+  return `--BOUNDARY\r\ncontent-disposition: form-data; name="${name}"\r\n\r\n${value}\r\n`
+}
+
+/** multipart 文件分片头。 */
+function formFileHead(name: string, index: number, file: InputImage): string {
+  const ext = file.mime.split('/')[1] ?? 'png'
+  return (
+    `--BOUNDARY\r\ncontent-disposition: form-data; name="${name}"; filename="${name}-${index}.${ext}"\r\n` +
+    `content-type: ${file.mime}\r\n\r\n`
+  )
+}
+
+/** 构造 generations JSON 请求体（纯函数；params 已由 spec 层裁剪）。 */
+export function buildGenerationBody(request: NormalizedRequest): string {
+  return JSON.stringify({ prompt: request.prompt, n: request.n, ...request.params })
+}
+
+/** 构造 edits multipart 请求体（纯函数；image 官方上限 ≤16 张由边界校验）。 */
+export function buildEditBody(request: NormalizedRequest): {
+  headers: HeaderLike
+  body: Buffer
+} {
+  const chunks: Buffer[] = []
+  const pushText = (text: string): void => chunks.push(Buffer.from(text, 'utf8'))
+  pushText(formField('prompt', request.prompt))
+  pushText(formField('n', String(request.n)))
+  for (const [key, value] of Object.entries(request.params)) {
+    pushText(formField(key, String(value)))
+  }
+  request.images.forEach((file, index) => {
+    pushText(formFileHead('image', index, file))
+    chunks.push(Buffer.from(file.data), Buffer.from('\r\n', 'utf8'))
+  })
+  if (request.mask !== null) {
+    pushText(formFileHead('mask', 0, request.mask))
+    chunks.push(Buffer.from(request.mask.data), Buffer.from('\r\n', 'utf8'))
+  }
+  chunks.push(Buffer.from('--BOUNDARY--\r\n', 'utf8'))
+  return {
+    headers: { 'content-type': 'multipart/form-data; boundary=BOUNDARY' },
+    body: Buffer.concat(chunks),
+  }
+}
+
+interface RawReply {
+  status: number
+  contentType: string
+  body: Buffer
+}
+
+interface ExecOptions {
+  method: 'POST' | 'GET'
+  headers: HeaderLike
+  body?: Buffer
+  proxy: string
+  timeoutMs: number
+  signal: AbortSignal
+}
+
+/** 收集响应体（带字节上限；流错误结算防悬挂）。 */
+function collect(
+  req: import('node:http').ClientRequest,
+  response: IncomingMessage,
+  done: (reply: RawReply) => void,
+  fail: (error: Error) => void,
+): void {
+  const chunks: Buffer[] = []
+  let size = 0
+  response.on('data', (chunk: Buffer) => {
+    size += chunk.length
+    if (size <= MAX_RESPONSE_BYTES) {
+      chunks.push(chunk)
+      return
+    }
+    response.destroy(new Error('响应超过 64MB 上限'))
+  })
+  response.on('end', () =>
+    done({
+      status: response.statusCode ?? 0,
+      contentType: response.headers['content-type']?.split(';')[0] ?? '',
+      body: Buffer.concat(chunks),
+    }),
+  )
+  // 响应流自身出错不经请求转发：缺此监听 Promise 永不 settle。
+  response.on('error', fail)
+  req.on('error', fail)
+}
+
+/** HTTP(S) POST/GET 执行：代理 + 超时 + AbortSignal 贯穿。 */
+function execRequest(url: string, options: ExecOptions): Promise<RawReply> {
+  return new Promise((resolve, reject) => {
+    const target = new URL(url)
+    const doRequest = target.protocol === 'https:' ? httpsRequest : httpRequest
+    const agent =
+      target.protocol === 'https:' && options.proxy.length > 0
+        ? new HttpsProxyAgent(options.proxy)
+        : undefined
+    let settled = false
+    const fail = (error: Error): void => {
+      if (settled) return
+      settled = true
+      reject(error)
+    }
+    const done = (reply: RawReply): void => {
+      if (settled) return
+      settled = true
+      resolve(reply)
+    }
+    const req = doRequest(
+      url,
+      {
+        method: options.method,
+        headers: options.headers,
+        timeout: options.timeoutMs,
+        agent,
+        signal: options.signal,
+      },
+      (response) => collect(req, response, done, fail),
+    )
+    req.on('timeout', () => req.destroy(new Error(`请求超时（${options.timeoutMs}ms）`)))
+    req.on('error', fail)
+    req.end(options.body ?? Buffer.alloc(0))
+  })
+}
+
+/** 上游 Images API 响应的最小投影。 */
+interface ImagesReply {
+  created?: number
+  data?: Array<{ url?: string; b64_json?: string; revised_prompt?: string }> | null
+}
+
+/** url 形式结果图下载（同代理/超时策略；MIME 取响应头）。 */
+async function fetchImageBytes(
+  url: string,
+  proxy: string,
+  timeoutMs: number,
+  signal: AbortSignal,
+): Promise<{ data: Uint8Array; mime: string }> {
+  const reply = await execRequest(url, { method: 'GET', headers: {}, proxy, timeoutMs, signal })
+  if (reply.status !== 200) {
+    throw new ProviderError(reply.status, '', `结果图下载失败（HTTP ${reply.status}）`)
+  }
+  return { data: new Uint8Array(reply.body), mime: reply.contentType || 'image/png' }
+}
+
+/** 解析响应体为结果图列表（url 下载 / b64 解码统一为字节）。 */
+async function parseImagesReply(
+  bodyText: string,
+  fallbackMime: string,
+  proxy: string,
+  timeoutMs: number,
+  signal: AbortSignal,
+): Promise<ProviderResult> {
+  let doc: ImagesReply
+  try {
+    doc = JSON.parse(bodyText) as ImagesReply
+  } catch {
+    throw new ProviderError(502, bodyText.slice(0, 500), '上游响应不是合法 JSON')
+  }
+  const images: GeneratedImage[] = []
+  for (const item of doc.data ?? []) {
+    if (typeof item.b64_json === 'string' && item.b64_json.length > 0) {
+      images.push({
+        data: new Uint8Array(Buffer.from(item.b64_json, 'base64')),
+        mime: fallbackMime,
+        revisedPrompt: item.revised_prompt ?? null,
+      })
+      continue
+    }
+    if (typeof item.url === 'string' && item.url.length > 0) {
+      const fetched = await fetchImageBytes(item.url, proxy, timeoutMs, signal)
+      images.push({ ...fetched, revisedPrompt: item.revised_prompt ?? null })
+    }
+  }
+  if (images.length === 0)
+    throw new ProviderError(502, bodyText.slice(0, 500), '上游未返回任何图片')
+  return { images, createdAt: typeof doc.created === 'number' ? doc.created : null }
+}
+
+/** 适配器主入口：构造请求 → 执行 → 解析。 */
+export async function generateViaOpenAIImages(
+  request: NormalizedRequest,
+  signal: AbortSignal,
+): Promise<ProviderResult> {
+  const { target } = request
+  const url = `${target.baseUrl.replace(/\/+$/, '')}${endpointPath(request.endpoint)}`
+  const fallbackMime = mimeOfFormat(request.params.output_format)
+  const reply =
+    request.endpoint === 'generation'
+      ? await execRequest(url, {
+          method: 'POST',
+          headers: {
+            ...baseHeaders(target.apiKey, target.extraHeaders),
+            'content-type': 'application/json',
+          },
+          body: Buffer.from(buildGenerationBody(request), 'utf8'),
+          proxy: target.proxy,
+          timeoutMs: target.timeoutMs,
+          signal,
+        })
+      : await execRequest(url, {
+          method: 'POST',
+          headers: baseHeaders(target.apiKey, {
+            ...target.extraHeaders,
+            ...buildEditBody(request).headers,
+          }),
+          body: buildEditBody(request).body,
+          proxy: target.proxy,
+          timeoutMs: target.timeoutMs,
+          signal,
+        })
+  if (reply.status !== 200) {
+    throw new ProviderError(reply.status, reply.body.toString('utf8').slice(0, 2000))
+  }
+  return parseImagesReply(
+    reply.body.toString('utf8'),
+    fallbackMime,
+    target.proxy,
+    target.timeoutMs,
+    signal,
+  )
+}

package/src/provider/registry.ts

@@ -0,0 +1,54 @@
+/**
+ * 协议注册表：协议 id → 适配器构造。封闭集合 + 统一注册入口，
+ * 新增协议（如 gemini、stable-diffusion 等）只增注册不改核心。
+ * @module image-studio/provider/registry
+ */
+import { ImageStudioError } from '../errors.ts'
+import { generateViaOpenAIImages } from './openai-images.ts'
+import type { ImageEndpoint, ImageProvider, NormalizedRequest } from './types.ts'
+
+type GenerateFn = (request: NormalizedRequest, signal: AbortSignal) => Promise<ProviderResult>
+
+interface ProtocolEntry {
+  /** 协议 id（settings 提供商预设的 protocol 字段取值）。 */
+  id: string
+  /** 协议名称（前端展示）。 */
+  label: string
+  /** 支持的端点。 */
+  endpoints: readonly ImageEndpoint[]
+  /** 生图执行函数。 */
+  generate: GenerateFn
+}
+
+const PROTOCOLS: readonly ProtocolEntry[] = Object.freeze([
+  {
+    id: 'openai-images',
+    label: 'OpenAI Images API',
+    endpoints: ['generation', 'edit'],
+    generate: generateViaOpenAIImages,
+  },
+])
+
+/** 全部已注册协议（前端下拉依据）。 */
+export function listProtocols(): Array<Pick<ProtocolEntry, 'id' | 'label' | 'endpoints'>> {
+  return PROTOCOLS.map(({ id, label, endpoints }) => ({ id, label, endpoints }))
+}
+
+/** 按协议 id 查条目；未知协议抛结构化错误。 */
+export function protocolOf(id: string): ProtocolEntry {
+  const found = PROTOCOLS.find((entry) => entry.id === id)
+  if (found === undefined) {
+    throw new ImageStudioError('unknown-protocol', `未知协议：${id}`)
+  }
+  return found
+}
+
+/** 构造适配器（当前实现无状态，直接包一层满足 ImageProvider 契约）。 */
+export function createProvider(id: string): ImageProvider {
+  const entry = protocolOf(id)
+  return {
+    id: entry.id,
+    endpoints: entry.endpoints,
+    generate: (request, signal) => entry.generate(request, signal),
+  }
+}

package/src/provider/types.ts

@@ -0,0 +1,86 @@
+/**
+ * 图像生成 provider 抽象：协议无关的请求/结果模型 + 适配器契约。
+ * 首批实现 openai-images；后续协议经 ImageProviderRegistry 挂载，不改核心。
+ * @module image-studio/provider/types
+ */
+
+/** 生图端点（官方 Images API 两类；新增协议可扩展联合）。 */
+export type ImageEndpoint = 'generation' | 'edit'
+
+/** 提供商预设经用户层配置实例化后的请求基础（协议、地址、模型、鉴权）。 */
+export interface ProviderTarget {
+  /** 协议 id（provider registry 键，首批 'openai-images'）。 */
+  protocol: string
+  /** API 基础地址（如 https://api.openai.com/v1，兼容中转填中转地址）。 */
+  baseUrl: string
+  /** 模型 id（gpt-image-1 等）。 */
+  model: string
+  /** 已 resolve 的 API key（每次任务即时 resolve，不缓存）。 */
+  apiKey: string
+  /** 额外请求头（部分中转要求自定义头）。 */
+  extraHeaders?: Record<string, string>
+  /** HTTP 代理（空 = 直连）。 */
+  proxy: string
+  /** 单请求超时毫秒。 */
+  timeoutMs: number
+}
+
+/** 输入图片（图生图）：宿主持有的字节数据 + MIME。 */
+export interface InputImage {
+  data: Uint8Array
+  mime: string
+}
+
+/** 协议无关的归一化生图请求（参数面已按目录裁剪完毕）。 */
+export interface NormalizedRequest {
+  target: ProviderTarget
+  endpoint: ImageEndpoint
+  prompt: string
+  /** 文生图张数（edits 端点同样合法）。 */
+  n: number
+  /** 图生图输入图（edit 时 ≥1；generation 恒空）。 */
+  images: InputImage[]
+  /** 可选 PNG mask（仅 edit；与 images[0] 配对）。 */
+  mask: InputImage | null
+  /** 除 prompt/n/image/mask 外的协议参数（key → 已验证值，仅含启用项）。 */
+  params: Record<string, unknown>
+}
+
+/** 单张结果图。 */
+export interface GeneratedImage {
+  /** 图片字节（宿主已把 url/b64 统一拉取解码）。 */
+  data: Uint8Array
+  mime: string
+  /** 上游改写后的提示词（部分模型返回）。 */
+  revisedPrompt: string | null
+}
+
+/** 协议适配器解析出的结果。 */
+export interface ProviderResult {
+  images: GeneratedImage[]
+  /** 上游原始 created 时间戳（秒），缺省 null。 */
+  createdAt: number | null
+}
+
+/** 适配器向上抛的结构化错误：HTTP 状态 + 上游响应摘要。 */
+export class ProviderError extends Error {
+  readonly status: number
+  readonly upstreamBody: string
+
+  constructor(status: number, upstreamBody: string, message?: string) {
+    super(message ?? `上游返回 HTTP ${status}`)
+    this.name = 'ProviderError'
+    this.status = status
+    this.upstreamBody = upstreamBody
+  }
+}
+
+/**
+ * 协议适配器契约：registry 按协议 id 构造；适配器只关心
+ * NormalizedRequest → HTTP 调用 → ProviderResult 的翻译。
+ */
+export interface ImageProvider {
+  readonly id: string
+  readonly endpoints: readonly ImageEndpoint[]
+  generate(request: NormalizedRequest, signal: AbortSignal): Promise<ProviderResult>
+}