@dickpy/dsh-imagegen 1.0.0

package/src/client/settings-scope.ts

@@ -0,0 +1,227 @@
+/**
+ * Browser-side settings scope for the dsh-imagegen namespace, served by the
+ * plugin's own loopback bridge routes (/api/dsh-imagegen/settings). The
+ * official rc.6 settings scope answers "unavailable" for every third-party
+ * namespace (the host-apiproxy allowlist is hard-coded), so this package
+ * re-serves its namespace through the host settings seam over a same-origin,
+ * loopback-only HTTP pair — the same pattern the dsh-web-ui family bridge
+ * uses, self-contained per plugin.
+ */
+
+import {
+  createSnapshotStore,
+  type SettingsScope,
+  type SettingsScopeSnapshot,
+  type SnapshotStore,
+} from '@deepseek-ai/dsh-client-runtime/client'
+import { SETTINGS_API } from '../protocol.ts'
+
+/** The fields this plugin's settings card edits. */
+export interface ImageGenConfig {
+  enabled?: boolean
+  announceToAgent?: boolean
+  apiUrl?: string
+  apiKey?: string
+}
+
+/** Wire shape of one namespace view from the bridge. */
+interface BridgeView {
+  ns: string
+  value: unknown
+  base?: unknown
+  user?: unknown
+  revision: number
+  secrets?: Array<{ path: string[]; set: boolean }>
+}
+
+/** The bridge response envelope ({ ok: true, value } | { ok: false, code, message }). */
+type BridgeEnvelope =
+  | { ok: true; value: { namespaces?: BridgeView[]; writable?: boolean } | BridgeView }
+  | { ok: false; code: string; message: string }
+
+/** Settings wire face over the bridge routes (fetch-backed). */
+function createBridgeApi(fetchFn: typeof fetch): {
+  settings: {
+    describe(payload: Record<string, never>): Promise<{ result: BridgeEnvelope }>
+    mutate(payload: { ns: string; ops: unknown[]; expectedRevision?: number }): Promise<{ result: BridgeEnvelope }>
+  }
+} {
+  const post = async (path: string, body: unknown): Promise<{ result: BridgeEnvelope }> => {
+    try {
+      const response = await fetchFn(path, {
+        method: 'POST',
+        headers: { 'content-type': 'application/json' },
+        body: JSON.stringify(body),
+      })
+      if (!response.ok) {
+        return { result: { ok: false, code: 'internal', message: `bridge HTTP ${response.status}` } }
+      }
+      return { result: await response.json() as BridgeEnvelope }
+    } catch {
+      return { result: { ok: false, code: 'internal', message: 'settings bridge unreachable' } }
+    }
+  }
+  return {
+    settings: {
+      describe: async payload => post(SETTINGS_API.describe, payload),
+      mutate: async payload => post(SETTINGS_API.mutate, payload),
+    },
+  }
+}
+
+/**
+ * A SettingsScope over the bridge face: serialized queue, revision-fenced
+ * writes, recovery read after a refusal. Mirrors the official controller's
+ * ordering but trusts the Host-seam value without re-running the wire-schema
+ * validation — the seam already validated it.
+ */
+class BridgeScopeController<T> implements SettingsScope<T> {
+  private readonly store: SnapshotStore<SettingsScopeSnapshot<T>>
+  /** Whether the namespace currently holds a stored secret (e.g. apiKey). */
+  private readonly keySet: SnapshotStore<boolean>
+  private tail: Promise<void> = Promise.resolve()
+  private disposed = false
+
+  constructor(
+    private readonly api: ReturnType<typeof createBridgeApi>['settings'],
+    private readonly spec: { namespace: string },
+  ) {
+    this.store = createSnapshotStore<SettingsScopeSnapshot<T>>({
+      status: 'loading',
+      value: undefined,
+      base: undefined,
+      user: undefined,
+      revision: undefined,
+      writable: false,
+      mode: 'host',
+    })
+    this.keySet = createSnapshotStore(false)
+  }
+
+  getSnapshot(): SettingsScopeSnapshot<T> {
+    return this.store.getSnapshot()
+  }
+
+  /** Whether a stored secret exists (from the redacted view's secrets list). */
+  getKeySetSnapshot(): boolean {
+    return this.keySet.getSnapshot()
+  }
+
+  /** Observe the secret-set flag. */
+  subscribeKeySet(listener: () => void): () => void {
+    return this.keySet.subscribe(listener)
+  }
+
+  subscribe(listener: () => void): () => void {
+    return this.store.subscribe(listener)
+  }
+
+  /** Queue a bridge refresh. */
+  load(): Promise<void> {
+    return this.enqueue(() => this.read())
+  }
+
+  set(field: string, value: unknown): Promise<void> {
+    return this.enqueue(() => this.write({ op: 'set', path: [field], value }))
+  }
+
+  unset(field: string): Promise<void> {
+    return this.enqueue(() => this.write({ op: 'unset', path: [field] }))
+  }
+
+  async dispose(): Promise<void> {
+    this.disposed = true
+    await this.tail
+  }
+
+  private enqueue(operation: () => Promise<void>): Promise<void> {
+    if (this.disposed) return Promise.resolve()
+    const task = this.tail.then(async () => {
+      if (this.disposed) return
+      await operation()
+    })
+    this.tail = task.catch(() => {})
+    return task
+  }
+
+  private async read(): Promise<void> {
+    let response
+    try {
+      response = await this.api.describe({})
+    } catch {
+      if (!this.disposed) this.store.update(draft => { draft.status = 'unavailable' })
+      return
+    }
+    if (!response.result.ok || this.disposed) {
+      if (!this.disposed) this.store.update(draft => { draft.status = 'unavailable' })
+      return
+    }
+    const { namespaces, writable } = response.result.value as { namespaces?: BridgeView[]; writable?: boolean }
+    const view = namespaces?.find(candidate => candidate.ns === this.spec.namespace)
+    if (view === undefined) {
+      this.store.update(draft => {
+        draft.status = 'unavailable'
+        draft.writable = writable === true
+      })
+      this.keySet.set(false)
+      return
+    }
+    this.accept(view, writable)
+  }
+
+  private async write(op: { op: 'set' | 'unset'; path: string[]; value?: unknown }): Promise<void> {
+    const revision = this.getSnapshot().revision
+    let response
+    try {
+      response = await this.api.mutate({
+        ns: this.spec.namespace,
+        ops: [op],
+        ...revision === undefined ? {} : { expectedRevision: revision },
+      })
+    } catch {
+      await this.read()
+      return
+    }
+    if (!response.result.ok || this.disposed) {
+      await this.read()
+      return
+    }
+    this.accept(response.result.value as BridgeView, undefined)
+  }
+
+  private accept(view: BridgeView, writable: boolean | undefined): void {
+    this.store.update(draft => {
+      draft.revision = view.revision
+      draft.base = view.base
+      draft.user = view.user
+      if (writable !== undefined) draft.writable = writable
+      draft.status = 'ready'
+      // Trust the Host-seam value: the seam already validated it, and the
+      // card binds without a narrowing decoder.
+      draft.value = view.value as T
+    })
+    this.keySet.set(Array.isArray(view.secrets) && view.secrets.some(secret => secret.set))
+  }
+}
+
+/** The bound scope plus the secret-set flag, as the card and panel consume it. */
+export interface ImageGenScope extends SettingsScope<ImageGenConfig> {
+  /** Queue a bridge refresh (the invalidation path re-reads the namespace). */
+  load(): Promise<void>
+  getKeySetSnapshot(): boolean
+  subscribeKeySet(listener: () => void): () => void
+}
+
+/**
+ * Bind the dsh-imagegen settings scope over the bridge routes and start its
+ * initial read (the caller mounts nothing until the scope settles).
+ * @param fetchFn - the fetch implementation (the global fetch on loopback).
+ * @returns the scope; unavailable when the bridge is unreachable.
+ */
+export function bindImageGenScope(fetchFn: typeof fetch = fetch): ImageGenScope {
+  const controller = new BridgeScopeController<ImageGenConfig>(createBridgeApi(fetchFn).settings, {
+    namespace: 'dsh-imagegen',
+  })
+  void controller.load()
+  return controller
+}

package/src/client/sidebar-entry.ts

@@ -0,0 +1,144 @@
+/**
+ * Sidebar entry injection.
+ *
+ * dsh's sidebar shell exposes no slot an external plugin can register into,
+ * so — following the dsh-ssh / task-board precedent of DOM-level extension —
+ * the entry row is injected after the shell's New Session button (after the
+ * sibling plugin family block). The injection self-heals: a MutationObserver
+ * watches the sidebar root and re-inserts the row whenever a React re-render
+ * displaces it (re-insertion happens in the same frame, before paint).
+ *
+ * The row is plain DOM (no React tree) so it can never disturb the shell's
+ * reconciliation; the panel view it toggles is a separate React root mounted
+ * in the center column (see mount.tsx).
+ */
+
+import type { ImageGenController } from './controller.ts'
+import css from './panel.module.css'
+
+/** Stable data attribute identifying the injected entry row. */
+export const ENTRY_SELECTOR = '[data-dsh-imagegen-entry]'
+
+/** Inline icon (matches the shell's 16px nav-icon look): a picture glyph. */
+const ICON = '<svg viewBox="0 0 16 16" width="14" height="14" fill="none" stroke="currentColor" stroke-width="1.3" stroke-linecap="round" stroke-linejoin="round" aria-hidden="true"><rect x="2" y="2.5" width="12" height="11" rx="1.5"/><circle cx="5.6" cy="5.8" r="1"/><path d="M2.5 12.5l3.6-3.4 2.4 2.2 3-3 2 2.4"/></svg>'
+
+/** Family entry selectors of sibling plugins (relative placement anchor). */
+const FAMILY_ENTRY_SELECTOR = '[data-dsh-taskboard-entry], [data-dsh-ssh-entry], [data-dsh-imagegen-entry]'
+
+/** Find the sidebar shell root element, or undefined while not yet mounted. */
+function sidebarRoot(): HTMLElement | undefined {
+  const column = document.querySelector<HTMLElement>('[data-pane="sidebar"], [class*="sidebarCol"]')
+  if (column === null) return undefined
+  const logoOwner = column.querySelector<HTMLElement>('[class*="logoRow"]')?.parentElement
+  return logoOwner ?? (column.firstElementChild as HTMLElement | undefined)
+}
+
+/** The New Session button: nested in the logo row on current shells, a direct child on legacy shells. */
+function newSessionButton(root: HTMLElement): HTMLButtonElement | undefined {
+  const nested = root.querySelector<HTMLButtonElement>('button[class*="newSession"]')
+  if (nested !== null) return nested
+  for (const child of root.children) {
+    if (child.tagName === 'BUTTON') return child as HTMLButtonElement
+  }
+  return undefined
+}
+
+/** Build the entry row (a detached button; insert once the shell is up). */
+function createEntry(controller: ImageGenController, label: string, tooltip: string): HTMLButtonElement {
+  const entry = document.createElement('button')
+  entry.type = 'button'
+  entry.dataset.dshImagegenEntry = ''
+  entry.className = css.entry
+  entry.setAttribute('aria-label', label)
+  entry.setAttribute('title', tooltip)
+  entry.innerHTML = '<span class="' + css.entryIcon + '">' + ICON + '</span><span class="' + css.entryLabel + '">' + label + '</span>'
+  entry.addEventListener('click', () => { controller.toggle() })
+  return entry
+}
+
+/** Re-insert the entry after the family block (task board → ssh → imagegen). */
+function placeEntry(root: HTMLElement, entry: HTMLButtonElement): boolean {
+  const button = newSessionButton(root)
+  if (button === undefined) return false
+  if (entry.parentElement !== root) {
+    // Position relative to the family block, never relative to transient
+    // logoRow geometry: every family plugin that self-heals during a
+    // re-render then lands in the same relative order.
+    const row = button.closest('[class*="logoRow"]')
+    const base = (row !== null && row.parentElement === root) ? row : button
+    const family = Array.from(root.children).filter(
+      (el): el is HTMLElement => el instanceof HTMLElement && el.matches(FAMILY_ENTRY_SELECTOR),
+    )
+    const anchor = family.length > 0 ? family[family.length - 1].nextElementSibling : base.nextElementSibling
+    root.insertBefore(entry, anchor)
+  }
+  return true
+}
+
+/**
+ * Mount the sidebar entry, waiting for the shell to render and self-healing
+ * on later React re-renders.
+ * @param controller - the panel controller the entry toggles.
+ * @param label - the entry label (localized).
+ * @param tooltip - the entry tooltip (localized).
+ * @returns disposer removing the entry and its observers.
+ */
+export function mountSidebarEntry(controller: ImageGenController, label: string, tooltip: string): () => void {
+  const entry = createEntry(controller, label, tooltip)
+  let root: HTMLElement | undefined
+  let placed = false
+
+  const tryPlace = (): void => {
+    if (root !== undefined && !root.isConnected) {
+      rootObserver.disconnect()
+      root = undefined
+      placed = false
+    }
+    if (placed) {
+      if (document.body.contains(entry)) return
+      rootObserver.disconnect()
+      root = undefined
+      placed = false
+    }
+    root ??= sidebarRoot()
+    if (root === undefined) return
+    placed = placeEntry(root, entry)
+    if (placed) {
+      rootObserver.observe(root, { childList: true, subtree: true })
+    }
+  }
+
+  // Body-level watcher retained as the "whole rebuild" fallback.
+  const waitObserver = new MutationObserver(() => { tryPlace() })
+  waitObserver.observe(document.body, { childList: true, subtree: true })
+
+  // Self-heal: if a React re-render displaces the row, re-insert it in the
+  // same frame (microtask before paint -> no visible flicker).
+  const rootObserver = new MutationObserver(() => {
+    if (root === undefined || !root.isConnected) {
+      placed = false
+      tryPlace()
+      return
+    }
+    if (!root.contains(entry)) {
+      placed = placeEntry(root, entry)
+    }
+  })
+
+  // Reflect the panel's open state on the row (active highlight).
+  const syncActive = () => {
+    if (controller.getSnapshot().panelOpen) entry.dataset.active = 'true'
+    else delete entry.dataset.active
+  }
+  const unsubscribe = controller.subscribe(syncActive)
+  syncActive()
+
+  tryPlace()
+
+  return () => {
+    waitObserver.disconnect()
+    rootObserver.disconnect()
+    unsubscribe()
+    entry.remove()
+  }
+}

package/src/engine.ts

@@ -0,0 +1,284 @@
+/**
+ * Upstream proxy engine: forwards a generate request to the configured
+ * OpenAI-compatible image endpoint (/images/generations for text-to-image,
+ * /images/edits for image-to-image) and normalizes the response to base64
+ * images so the browser never fetches the upstream itself.
+ *
+ * Framework-free (no cordis imports) so the route layer and tests can drive
+ * it directly.
+ */
+
+import type { GeneratedImage, GenerateRequest, GenerateResult } from './protocol.ts'
+
+/** The upstream credentials the panel's settings card configures. */
+export interface UpstreamConfig {
+  /** Base URL of the OpenAI-compatible endpoint, e.g. https://api.openai.com/v1 */
+  apiUrl: string
+  /** Bearer API key. */
+  apiKey: string
+}
+
+/** A generation failure with a user-presentable message. */
+export class ImageGenError extends Error {
+  /** Stable wire code. */
+  readonly code: string
+
+  constructor(message: string, code = 'generate-failed') {
+    super(message)
+    this.name = 'ImageGenError'
+    this.code = code
+  }
+}
+
+/** Total budget for the upstream generation call (image models are slow). */
+const UPSTREAM_TIMEOUT_MS = 240_000
+
+/** Budget for downloading one result image URL. */
+const IMAGE_FETCH_TIMEOUT_MS = 60_000
+
+/** Cap on the reference image payload (edit mode), in bytes. */
+const MAX_EDIT_IMAGE_BYTES = 10 * 1024 * 1024
+
+/** Sizes dall-e-3 accepts; anything else falls back to its square default. */
+const DALLE3_SIZES = new Set(['1024x1024', '1792x1024', '1024x1792'])
+
+/** Content-type extension hints for URL-fetched images. */
+function mimeOfExtension(path: string): string | undefined {
+  const match = /\.([a-z0-9]+)$/i.exec(path)
+  if (match === null) return undefined
+  switch (match[1]!.toLowerCase()) {
+    case 'png': return 'image/png'
+    case 'jpg':
+    case 'jpeg': return 'image/jpeg'
+    case 'webp': return 'image/webp'
+    case 'gif': return 'image/gif'
+    default: return undefined
+  }
+}
+
+/** Parse `data:<mime>;base64,<payload>` into its parts; undefined when malformed. */
+function parseDataUrl(dataUrl: string): { mime: string; base64: string } | undefined {
+  const match = /^data:([^;,]+)?(;base64)?,(.*)$/s.exec(dataUrl.trim())
+  if (match === null || match[3] === undefined) return undefined
+  if (match[2] === undefined) {
+    // Plain (non-base64) data URLs are not supported for reference images.
+    return undefined
+  }
+  return { mime: match[1] ?? 'application/octet-stream', base64: match[3] }
+}
+
+/** Strip a data: prefix from an upstream b64 payload if a gateway added one. */
+function bareBase64(value: string): string {
+  const parsed = parseDataUrl(value)
+  return parsed !== undefined && parsed.base64 !== undefined ? parsed.base64 : value
+}
+
+/** Clamp the requested image count into the API-accepted range. */
+function clampCount(n: number): number {
+  if (!Number.isFinite(n)) return 1
+  return Math.min(4, Math.max(1, Math.round(n)))
+}
+
+/** Pick the effective per-model request parameters. Never includes `n`: the
+ *  batch parameter is rejected by Responses-API-based gateways (tools[0].n),
+ *  so the count is satisfied by parallel single-image requests instead. */
+function effectiveParams(request: GenerateRequest): {
+  model: string
+  size?: string
+  quality?: string
+  detail?: string
+} {
+  const model = request.model.trim() === '' ? 'gpt-image-2' : request.model.trim()
+  // dall-e-3 has no quality/detail knobs and only produces one image.
+  if (model === 'dall-e-3') {
+    const size = DALLE3_SIZES.has(request.size) ? request.size : '1024x1024'
+    return { model, size }
+  }
+  return {
+    model,
+    ...request.size !== '' && request.size !== 'auto' ? { size: request.size } : {},
+    ...request.quality !== '' && request.quality !== 'auto' ? { quality: request.quality } : {},
+    ...request.detail !== '' ? { detail: request.detail } : {},
+  }
+}
+
+/** How many single-image requests to issue for the requested image count. */
+function effectiveCount(request: GenerateRequest): number {
+  const model = request.model.trim() === '' ? 'gpt-image-2' : request.model.trim()
+  if (model === 'dall-e-3') return 1
+  return clampCount(request.n)
+}
+
+/** Normalize one upstream data item into a base64 image. */
+async function normalizeItem(
+  item: Record<string, unknown>,
+  upstream: UpstreamConfig,
+): Promise<{ b64: string; mime: string; revisedPrompt?: string }> {
+  const revisedPrompt = typeof item.revised_prompt === 'string' ? item.revised_prompt : undefined
+  if (typeof item.b64_json === 'string') {
+    return { b64: bareBase64(item.b64_json), mime: 'image/png', revisedPrompt }
+  }
+  if (typeof item.url !== 'string' || item.url === '') {
+    throw new ImageGenError('upstream image item has neither b64_json nor url')
+  }
+  const url = item.url
+  if (url.startsWith('data:')) {
+    const parsed = parseDataUrl(url)
+    if (parsed === undefined) throw new ImageGenError('upstream returned a malformed data: url')
+    return { b64: parsed.base64, mime: parsed.mime, revisedPrompt }
+  }
+  let response: Response
+  try {
+    response = await fetch(url, {
+      headers: {
+        ...upstream.apiKey === '' ? {} : { authorization: `Bearer ${upstream.apiKey}` },
+      },
+      signal: AbortSignal.timeout(IMAGE_FETCH_TIMEOUT_MS),
+    })
+  } catch (error) {
+    throw new ImageGenError(`failed to fetch the generated image url: ${error instanceof Error ? error.message : String(error)}`)
+  }
+  if (!response.ok) {
+    throw new ImageGenError(`failed to fetch the generated image url: HTTP ${response.status}`)
+  }
+  const buffer = Buffer.from(await response.arrayBuffer())
+  const contentType = response.headers.get('content-type')
+  const mime = contentType !== null && contentType !== ''
+    ? contentType.split(';')[0]!.trim()
+    : mimeOfExtension(url) ?? 'image/png'
+  return { b64: buffer.toString('base64'), mime, revisedPrompt }
+}
+
+/**
+ * Issue one single-image request (never sends `n`). The response is kept as a
+ * list so a gateway that happens to return several images per call still works.
+ */
+async function requestOneImage(
+  baseUrl: string,
+  upstream: UpstreamConfig,
+  request: GenerateRequest,
+  params: ReturnType<typeof effectiveParams>,
+): Promise<GeneratedImage[]> {
+  const headers: Record<string, string> = {
+    authorization: `Bearer ${upstream.apiKey.trim()}`,
+  }
+  let body: BodyInit
+  if (request.mode === 'edit') {
+    if (typeof request.image !== 'string' || request.image === '') {
+      throw new ImageGenError('图生图需要上传参考图片', 'edit-image-missing')
+    }
+    const parsed = parseDataUrl(request.image)
+    if (parsed === undefined) throw new ImageGenError('参考图片格式无效', 'edit-image-invalid')
+    let bytes: Buffer
+    try {
+      bytes = Buffer.from(parsed.base64, 'base64')
+    } catch {
+      throw new ImageGenError('参考图片数据无法解码', 'edit-image-invalid')
+    }
+    if (bytes.byteLength > MAX_EDIT_IMAGE_BYTES) {
+      throw new ImageGenError('参考图片超过 10MB 上限', 'edit-image-too-large')
+    }
+    const form = new FormData()
+    form.append('image', new Blob([bytes], { type: parsed.mime }), `reference.${extensionOf(parsed.mime)}`)
+    form.append('prompt', request.prompt)
+    form.append('model', params.model)
+    if (params.size !== undefined) form.append('size', params.size)
+    if (params.quality !== undefined) form.append('quality', params.quality)
+    if (params.detail !== undefined) form.append('detail', params.detail)
+    body = form
+  } else {
+    headers['content-type'] = 'application/json'
+    body = JSON.stringify({ prompt: request.prompt, ...params } as Record<string, unknown>)
+  }
+
+  let response: Response
+  try {
+    response = await fetch(`${baseUrl}/images/${request.mode === 'edit' ? 'edits' : 'generations'}`, {
+      method: 'POST',
+      headers,
+      body,
+      signal: AbortSignal.timeout(UPSTREAM_TIMEOUT_MS),
+    })
+  } catch (error) {
+    const message = error instanceof Error ? error.message : String(error)
+    if (/aborter/i.test(message) || /timeout/i.test(message)) {
+      throw new ImageGenError('上游接口响应超时（240 秒）', 'upstream-timeout')
+    }
+    throw new ImageGenError(`无法连接上游接口：${message}`, 'upstream-unreachable')
+  }
+
+  let payload: unknown
+  try {
+    payload = await response.json()
+  } catch {
+    throw new ImageGenError(`上游接口返回了非 JSON 响应（HTTP ${response.status}）`, 'upstream-invalid')
+  }
+  if (!response.ok || payload === null || typeof payload !== 'object') {
+    throw new ImageGenError(upstreamMessage(payload, response.status), 'upstream-rejected')
+  }
+
+  const record = payload as Record<string, unknown>
+  const data = Array.isArray(record.data)
+    ? record.data
+    : Array.isArray(record.images)
+      ? record.images
+      : Array.isArray(record.output)
+        ? record.output
+        : undefined
+  if (data === undefined) {
+    throw new ImageGenError('上游响应缺少 data 数组', 'upstream-invalid')
+  }
+  if (data.length === 0) {
+    throw new ImageGenError('上游返回了 0 张图片', 'upstream-empty')
+  }
+  return Promise.all(data.map(async (entry) => {
+    if (entry === null || typeof entry !== 'object') {
+      throw new ImageGenError('上游响应包含无效的图片条目', 'upstream-invalid')
+    }
+    return normalizeItem(entry as Record<string, unknown>, upstream)
+  }))
+}
+
+/**
+ * Forward one generate request to the configured endpoint. The requested image
+ * count is satisfied with N parallel single-image requests (the `n` batch
+ * parameter is never sent, because Responses-API-based gateways reject it as
+ * `tools[0].n`), then the results are flattened in order.
+ */
+export async function generateImage(upstream: UpstreamConfig, request: GenerateRequest): Promise<GenerateResult> {
+  const baseUrl = upstream.apiUrl.trim().replace(/\/+$/, '')
+  if (baseUrl === '') throw new ImageGenError('api_url 未配置：请先在「设置 → 插件 → 可配置」中填写', 'config-missing')
+  if (upstream.apiKey.trim() === '') throw new ImageGenError('api_key 未配置：请先在「设置 → 插件 → 可配置」中填写', 'config-missing')
+  const params = effectiveParams(request)
+  const count = effectiveCount(request)
+  const batches = await Promise.all(
+    Array.from({ length: count }, () => requestOneImage(baseUrl, upstream, request, params)),
+  )
+  return { images: batches.flat() }
+}
+
+/** Human-readable failure message from an upstream error payload. */
+function upstreamMessage(payload: unknown, status: number): string {
+  if (payload !== null && typeof payload === 'object') {
+    const record = payload as Record<string, unknown>
+    const error = record.error
+    if (error !== null && typeof error === 'object') {
+      const message = (error as Record<string, unknown>).message
+      if (typeof message === 'string' && message !== '') return message
+    }
+    if (typeof record.message === 'string' && record.message !== '') return record.message
+    if (typeof record.error === 'string' && record.error !== '') return record.error
+  }
+  return `上游接口拒绝请求（HTTP ${status}）`
+}
+
+/** File extension for a MIME type (multipart reference image). */
+function extensionOf(mime: string): string {
+  switch (mime.split(';')[0]!.trim()) {
+    case 'image/jpeg': return 'jpg'
+    case 'image/webp': return 'webp'
+    case 'image/gif': return 'gif'
+    case 'image/png':
+    default: return 'png'
+  }
+}