@dickpy/dsh-imagegen 1.5.4 → 1.5.6

package/src/engine.ts

@@ -184,8 +184,14 @@ function requestSignal(source: AbortSignal | undefined, timeoutMs: number): { si
   }
 }
 
-/** Content-type extension hints for URL-fetched images. */
-function mimeOfExtension(path: string): string | undefined {
+/** Whether an error was produced by a requestSignal budget timeout. These can
+ * surface from the fetch call itself or from reading the response body, so the
+ * budget must stay armed until the body has been consumed. */
+function isBudgetTimeout(error: unknown): boolean {
+  return (error instanceof DOMException || error instanceof Error) && error.name === 'TimeoutError'
+}
+
+/** 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()) {
@@ -358,29 +364,32 @@ async function normalizeItem(
     return { b64: parsed.base64, mime: detectImageMime(Buffer.from(parsed.base64, 'base64')) ?? parsed.mime, revisedPrompt }
   }
   const budget = requestSignal(signal, IMAGE_FETCH_TIMEOUT_MS)
-  let response: Response
   try {
-    response = await fetch(url, {
-      ...isPresignedUrl(url) || upstream.apiKey === ''
-        ? {}
-        : { headers: { authorization: `Bearer ${upstream.apiKey}` } },
-      signal: budget.signal,
-    })
-  } catch (error) {
-    throw new ImageGenError(`failed to fetch the generated image url: ${error instanceof Error ? error.message : String(error)}`)
+    let response: Response
+    try {
+      response = await fetch(url, {
+        ...isPresignedUrl(url) || upstream.apiKey === ''
+          ? {}
+          : { headers: { authorization: `Bearer ${upstream.apiKey}` } },
+        signal: budget.signal,
+      })
+    } 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}`)
+    }
+    // Budget stays armed through the body read so a stalled download cannot hang the task.
+    const buffer = Buffer.from(await response.arrayBuffer())
+    const contentType = response.headers.get('content-type')
+    const mime = detectImageMime(buffer)
+      ?? (contentType !== null && contentType !== ''
+      ? contentType.split(';')[0]!.trim()
+      : mimeOfExtension(url) ?? 'image/png')
+    return { b64: buffer.toString('base64'), mime, revisedPrompt }
   } finally {
     budget.dispose()
   }
-  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 = detectImageMime(buffer)
-    ?? (contentType !== null && contentType !== ''
-    ? contentType.split(';')[0]!.trim()
-    : mimeOfExtension(url) ?? 'image/png')
-  return { b64: buffer.toString('base64'), mime, revisedPrompt }
 }
 
 /** Expand a provider image item whose URL may be a string or an array. */
@@ -477,52 +486,54 @@ async function pollAsyncTask(
   while (Date.now() < deadline) {
     const remaining = deadline - Date.now()
     const budget = requestSignal(signal, Math.min(ASYNC_POLL_REQUEST_TIMEOUT_MS, remaining))
-    let response: Response
     try {
-      response = await fetch(`${baseUrl}/tasks/${encodeURIComponent(taskId)}`, {
-        method: 'GET',
-        headers: { authorization: `Bearer ${upstream.apiKey.trim()}` },
-        signal: budget.signal,
-      })
-    } catch (error) {
-      if (signal?.aborted === true) throw new ImageGenError('任务已取消', 'cancelled')
-      const message = error instanceof Error ? error.message : String(error)
-      if (/timeout|abort/i.test(message)) throw new ImageGenError('上游异步任务轮询超时', 'upstream-timeout')
-      throw new ImageGenError(`无法轮询上游异步任务：${message}`, 'upstream-unreachable')
+      let response: Response
+      try {
+        response = await fetch(`${baseUrl}/tasks/${encodeURIComponent(taskId)}`, {
+          method: 'GET',
+          headers: { authorization: `Bearer ${upstream.apiKey.trim()}` },
+          signal: budget.signal,
+        })
+      } catch (error) {
+        if (signal?.aborted === true) throw new ImageGenError('任务已取消', 'cancelled')
+        if (isBudgetTimeout(error)) throw new ImageGenError('上游异步任务轮询超时', 'upstream-timeout')
+        throw new ImageGenError(`无法轮询上游异步任务：${error instanceof Error ? error.message : String(error)}`, 'upstream-unreachable')
+      }
+      let payload: unknown
+      try {
+        payload = await response.json()
+      } catch (error) {
+        if (isBudgetTimeout(error)) throw new ImageGenError('上游异步任务轮询超时', 'upstream-timeout')
+        throw new ImageGenError(`上游任务接口返回了非 JSON 响应（HTTP ${response.status}）`, 'upstream-invalid')
+      }
+      if (!response.ok || payload === null || typeof payload !== 'object') {
+        throw new ImageGenError(asyncErrorMessage(payload, `上游任务轮询失败（HTTP ${response.status}）`), 'upstream-rejected')
+      }
+      const record = payload as Record<string, unknown>
+      const data = record.data
+      const statusRecord = Array.isArray(data) ? data[0] : data !== null && typeof data === 'object' ? data : record
+      const statusValue = statusRecord !== null && typeof statusRecord === 'object'
+        ? (statusRecord as Record<string, unknown>).status
+        : undefined
+      const status = typeof statusValue === 'string' ? statusValue.toLowerCase() : ''
+      if (ASYNC_FAILED_STATUSES.has(status)) {
+        throw new ImageGenError(asyncErrorMessage(payload, `上游异步任务失败（${status || 'unknown'}）`), 'upstream-rejected')
+      }
+      const nested = statusRecord !== null && typeof statusRecord === 'object' ? statusRecord as Record<string, unknown> : record
+      const result = nested.result ?? (nested.output !== null && typeof nested.output === 'object' ? (nested.output as Record<string, unknown>).result : undefined) ?? record.result
+      const resultRecord = result !== null && typeof result === 'object' ? result as Record<string, unknown> : undefined
+      const images = resultRecord?.images ?? (nested.images ?? record.images)
+      if (ASYNC_COMPLETED_STATUSES.has(status) || images !== undefined) {
+        const items = Array.isArray(images) ? images.flatMap(imageItemsOf) : imageItemsOf(images)
+        if (items.length > 0) return items
+        if (ASYNC_COMPLETED_STATUSES.has(status)) throw new ImageGenError('上游异步任务完成但没有图片结果', 'upstream-empty')
+      }
+      if (status !== '' && !ASYNC_PENDING_STATUSES.has(status) && !ASYNC_COMPLETED_STATUSES.has(status)) {
+        throw new ImageGenError(`上游返回了未知异步任务状态：${status}`, 'upstream-invalid')
+      }
     } finally {
       budget.dispose()
     }
-    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(asyncErrorMessage(payload, `上游任务轮询失败（HTTP ${response.status}）`), 'upstream-rejected')
-    }
-    const record = payload as Record<string, unknown>
-    const data = record.data
-    const statusRecord = Array.isArray(data) ? data[0] : data !== null && typeof data === 'object' ? data : record
-    const statusValue = statusRecord !== null && typeof statusRecord === 'object'
-      ? (statusRecord as Record<string, unknown>).status
-      : undefined
-    const status = typeof statusValue === 'string' ? statusValue.toLowerCase() : ''
-    if (ASYNC_FAILED_STATUSES.has(status)) {
-      throw new ImageGenError(asyncErrorMessage(payload, `上游异步任务失败（${status || 'unknown'}）`), 'upstream-rejected')
-    }
-    const nested = statusRecord !== null && typeof statusRecord === 'object' ? statusRecord as Record<string, unknown> : record
-    const result = nested.result ?? (nested.output !== null && typeof nested.output === 'object' ? (nested.output as Record<string, unknown>).result : undefined) ?? record.result
-    const resultRecord = result !== null && typeof result === 'object' ? result as Record<string, unknown> : undefined
-    const images = resultRecord?.images ?? (nested.images ?? record.images)
-    if (ASYNC_COMPLETED_STATUSES.has(status) || images !== undefined) {
-      const items = Array.isArray(images) ? images.flatMap(imageItemsOf) : imageItemsOf(images)
-      if (items.length > 0) return items
-      if (ASYNC_COMPLETED_STATUSES.has(status)) throw new ImageGenError('上游异步任务完成但没有图片结果', 'upstream-empty')
-    }
-    if (status !== '' && !ASYNC_PENDING_STATUSES.has(status) && !ASYNC_COMPLETED_STATUSES.has(status)) {
-      throw new ImageGenError(`上游返回了未知异步任务状态：${status}`, 'upstream-invalid')
-    }
     await waitForPoll(Math.min(delay, Math.max(1, deadline - Date.now())), signal)
     delay = Math.min(5000, delay * 2)
   }
@@ -548,17 +559,25 @@ async function requestOneImage(
     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 decodeReference = (dataUrl: string): { bytes: Buffer; mime: string; filename: string } => {
+      const parsed = parseDataUrl(dataUrl)
+      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')
+      }
+      return { bytes, mime: parsed.mime, filename: `reference.${extensionOf(parsed.mime)}` }
     }
+    const primary = decodeReference(request.image)
+    const extras = (request.images ?? [])
+      .filter(img => typeof img === 'string' && img !== '')
+      .slice(0, 4)
+      .map(decodeReference)
     // Grok Imagine /images/edits takes a JSON image_url object (a base64 data
     // URI is accepted) instead of OpenAI's multipart form-data upload.
     if (isGrokImagine(params.model)) {
@@ -574,7 +593,7 @@ async function requestOneImage(
       // Nano Banana OpenAI-compatible gateways accept the standard multipart
       // edit upload, with the family's own aspect_ratio / image_size knobs.
       const form = new FormData()
-      form.append('image', new Blob([bytes], { type: parsed.mime }), `reference.${extensionOf(parsed.mime)}`)
+      form.append('image', new Blob([primary.bytes], { type: primary.mime }), primary.filename)
       form.append('prompt', request.prompt)
       form.append('model', params.model)
       if (params.aspect_ratio !== undefined) form.append('aspect_ratio', params.aspect_ratio)
@@ -582,19 +601,28 @@ async function requestOneImage(
       body = form
     } else if (isSeedream(params.model)) {
       // Seedream unifies generation and editing on /images/generations; the
-      // reference image is a JSON URL / data-URL array, never multipart.
+      // reference image is a JSON URL / data-URL array, never multipart, and
+      // the protocol natively accepts several references.
       headers['content-type'] = 'application/json'
       body = JSON.stringify({
         model: params.model,
         prompt: request.prompt,
-        image: [request.image],
+        image: [request.image, ...(request.images ?? []).filter(img => typeof img === 'string' && img !== '').slice(0, 4)],
         ...params.size !== undefined ? { size: params.size } : {},
         ...params.resolution !== undefined ? { resolution: params.resolution } : {},
         response_format: isVolcSeedream(params.model) ? 'url' : 'b64_json',
       })
     } else {
       const form = new FormData()
-      form.append('image', new Blob([bytes], { type: parsed.mime }), `reference.${extensionOf(parsed.mime)}`)
+      if (extras.length > 0) {
+        // OpenAI-style multi-reference upload: repeat the image[] field so
+        // every connected canvas reference reaches the gateway.
+        for (const [index, reference] of [primary, ...extras].entries()) {
+          form.append('image[]', new Blob([reference.bytes], { type: reference.mime }), `reference-${index}.${extensionOf(reference.mime)}`)
+        }
+      } else {
+        form.append('image', new Blob([primary.bytes], { type: primary.mime }), primary.filename)
+      }
       form.append('prompt', request.prompt)
       form.append('model', params.model)
       if (params.size !== undefined) form.append('size', params.size)
@@ -608,53 +636,57 @@ async function requestOneImage(
   }
 
   const budget = requestSignal(signal, UPSTREAM_TIMEOUT_MS)
-  let response: Response
   try {
-    // Seedream has no /images/edits endpoint: both modes hit generations.
-    const endpoint = request.mode === 'edit' && !isSeedream(params.model)
-      ? '/images/edits'
-      : '/images/generations'
-    response = await fetch(`${baseUrl}${endpoint}`, {
-      method: 'POST',
-      headers,
-      body,
-      signal: budget.signal,
-    })
-  } 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')
+    let response: Response
+    try {
+      // Seedream has no /images/edits endpoint: both modes hit generations.
+      const endpoint = request.mode === 'edit' && !isSeedream(params.model)
+        ? '/images/edits'
+        : '/images/generations'
+      response = await fetch(`${baseUrl}${endpoint}`, {
+        method: 'POST',
+        headers,
+        body,
+        signal: budget.signal,
+      })
+    } catch (error) {
+      if (isBudgetTimeout(error)) throw new ImageGenError('上游接口响应超时（240 秒）', 'upstream-timeout')
+      if (signal?.aborted === true) throw new ImageGenError('任务已取消', 'cancelled')
+      throw new ImageGenError(`无法连接上游接口：${error instanceof Error ? error.message : String(error)}`, 'upstream-unreachable')
     }
-    throw new ImageGenError(`无法连接上游接口：${message}`, 'upstream-unreachable')
-  } finally {
-    budget.dispose()
-  }
 
-  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')
-  }
+    let payload: unknown
+    try {
+      // The budget stays armed through the body read: a gateway that returns
+      // headers but never completes the body must not hang the task forever.
+      payload = await response.json()
+    } catch (error) {
+      if (isBudgetTimeout(error)) throw new ImageGenError('上游接口响应超时（240 秒）', 'upstream-timeout')
+      if (signal?.aborted === true) throw new ImageGenError('任务已取消', 'cancelled')
+      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 = dataRecordsOf(record)
-  if (data === undefined) {
-    throw new ImageGenError('上游响应缺少 data 数组', 'upstream-invalid')
-  }
-  if (data.length === 0) {
-    throw new ImageGenError('上游返回了 0 张图片', 'upstream-empty')
-  }
-  const asyncEntries = data.filter(entry => typeof entry.task_id === 'string' && entry.task_id.trim() !== '')
-  if (asyncEntries.length > 0) {
-    const asyncRecords = (await Promise.all(asyncEntries.map(entry => pollAsyncTask(baseUrl, upstream, entry.task_id as string, signal)))).flat()
-    if (asyncRecords.length === 0) throw new ImageGenError('上游异步任务完成但没有图片结果', 'upstream-empty')
-    return Promise.all(asyncRecords.flatMap(imageItemsOf).map(item => normalizeItem(item, upstream, signal)))
+    const record = payload as Record<string, unknown>
+    const data = dataRecordsOf(record)
+    if (data === undefined) {
+      throw new ImageGenError('上游响应缺少 data 数组', 'upstream-invalid')
+    }
+    if (data.length === 0) {
+      throw new ImageGenError('上游返回了 0 张图片', 'upstream-empty')
+    }
+    const asyncEntries = data.filter(entry => typeof entry.task_id === 'string' && entry.task_id.trim() !== '')
+    if (asyncEntries.length > 0) {
+      const asyncRecords = (await Promise.all(asyncEntries.map(entry => pollAsyncTask(baseUrl, upstream, entry.task_id as string, signal)))).flat()
+      if (asyncRecords.length === 0) throw new ImageGenError('上游异步任务完成但没有图片结果', 'upstream-empty')
+      return Promise.all(asyncRecords.flatMap(imageItemsOf).map(item => normalizeItem(item, upstream, signal)))
+    }
+    return Promise.all(data.flatMap(imageItemsOf).map(item => normalizeItem(item, upstream, signal)))
+  } finally {
+    budget.dispose()
   }
-  return Promise.all(data.flatMap(imageItemsOf).map(item => normalizeItem(item, upstream, signal)))
 }
 
 /**
@@ -701,36 +733,36 @@ async function generateQwenImage(
   }
 
   const budget = requestSignal(options.signal, UPSTREAM_TIMEOUT_MS)
-  let response: Response
   try {
-    response = await fetch(`${baseUrl}/services/aigc/multimodal-generation/generation`, {
-      method: 'POST',
-      headers: {
-        authorization: `Bearer ${upstream.apiKey.trim()}`,
-        'content-type': 'application/json',
-      },
-      body: JSON.stringify(body),
-      signal: budget.signal,
-    })
-  } 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')
+    let response: Response
+    try {
+      response = await fetch(`${baseUrl}/services/aigc/multimodal-generation/generation`, {
+        method: 'POST',
+        headers: {
+          authorization: `Bearer ${upstream.apiKey.trim()}`,
+          'content-type': 'application/json',
+        },
+        body: JSON.stringify(body),
+        signal: budget.signal,
+      })
+    } catch (error) {
+      if (isBudgetTimeout(error)) throw new ImageGenError('上游接口响应超时（240 秒）', 'upstream-timeout')
+      if (options.signal?.aborted === true) throw new ImageGenError('任务已取消', 'cancelled')
+      throw new ImageGenError(`无法连接上游接口：${error instanceof Error ? error.message : String(error)}`, 'upstream-unreachable')
     }
-    throw new ImageGenError(`无法连接上游接口：${message}`, 'upstream-unreachable')
-  } finally {
-    budget.dispose()
-  }
 
-  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')
-  }
+    let payload: unknown
+    try {
+      // Budget stays armed through the body read (same rationale as the OpenAI path).
+      payload = await response.json()
+    } catch (error) {
+      if (isBudgetTimeout(error)) throw new ImageGenError('上游接口响应超时（240 秒）', 'upstream-timeout')
+      if (options.signal?.aborted === true) throw new ImageGenError('任务已取消', 'cancelled')
+      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')
+    }
 
   // output.choices[].message.content[] mixes text and { image: url } items.
   const record = payload as Record<string, unknown>
@@ -759,6 +791,9 @@ async function generateQwenImage(
     return { b64: normalized.b64, mime: normalized.mime }
   }))
   return { images }
+  } finally {
+    budget.dispose()
+  }
 }
 
 /**

package/src/gallery-store.ts

@@ -10,15 +10,15 @@
 
 import { promises as fs } from 'node:fs'
 import { createHash } from 'node:crypto'
-import { homedir } from 'node:os'
 import path from 'node:path'
 import type { GenerateMode, HistoryEntry, HistoryEntryInput } from './protocol.ts'
 import { notifyImageSaved } from './storage-sync.ts'
+import { imageDataRoot } from './image-storage-path.ts'
 
-const HISTORY_DIR = path.join(homedir(), '.dsh', 'dsh-imagegen')
-const GALLERY_DIR = path.join(HISTORY_DIR, 'gallery')
-const INDEX_PATH = path.join(GALLERY_DIR, 'index.json')
-const IMAGES_DIR = path.join(GALLERY_DIR, 'images')
+function historyDir(): string { return imageDataRoot() }
+function galleryDir(): string { return path.join(imageDataRoot(), 'gallery') }
+function indexPath(): string { return path.join(galleryDir(), 'index.json') }
+function imagesDir(): string { return path.join(galleryDir(), 'images') }
 
 /** One gallery entry carries the same wire shape as a history entry. */
 export interface GalleryAppendResult {
@@ -114,13 +114,13 @@ function fingerprint(input: HistoryEntryInput): string | undefined {
 
 /** Ensure the storage directories exist. */
 async function ensureDirs(): Promise<void> {
-  await fs.mkdir(IMAGES_DIR, { recursive: true })
+  await fs.mkdir(imagesDir(), { recursive: true })
 }
 
 /** Read the index, tolerating a missing/corrupt file. */
 async function readIndex(): Promise<StoredEntry[]> {
   try {
-    const raw = await fs.readFile(INDEX_PATH, 'utf8')
+    const raw = await fs.readFile(indexPath(), 'utf8')
     const parsed: unknown = JSON.parse(raw)
     if (parsed === null || typeof parsed !== 'object') return []
     const entries = (parsed as { entries?: unknown }).entries
@@ -135,9 +135,9 @@ async function readIndex(): Promise<StoredEntry[]> {
 async function writeIndex(entries: StoredEntry[]): Promise<void> {
   await ensureDirs()
   const payload: IndexFile = { entries }
-  const tmp = `${INDEX_PATH}.tmp-${process.pid}`
+  const tmp = `${indexPath()}.tmp-${process.pid}`
   await fs.writeFile(tmp, JSON.stringify(payload), 'utf8')
-  await fs.rename(tmp, INDEX_PATH)
+  await fs.rename(tmp, indexPath())
 }
 
 /** Structural guard for a stored entry. */
@@ -164,7 +164,7 @@ function isStoredEntry(value: unknown): value is StoredEntry {
 /** Remove one entry's image files (best effort). */
 async function removeEntryFiles(entry: StoredEntry): Promise<void> {
   for (const image of entry.images) {
-    try { await fs.rm(path.join(IMAGES_DIR, image.file), { force: true }) } catch { /* ignore */ }
+    try { await fs.rm(path.join(imagesDir(), image.file), { force: true }) } catch { /* ignore */ }
   }
 }
 
@@ -223,8 +223,8 @@ export async function appendGallery(input: HistoryEntryInput): Promise<GalleryAp
       for (let index = 0; index < input.images.length; index++) {
         const image = input.images[index]!
         const file = `${prefix}-${index}.${extensionOf(image.mime)}`
-        await fs.writeFile(path.join(IMAGES_DIR, file), Buffer.from(image.b64, 'base64'))
-        notifyImageSaved('gallery', path.join(IMAGES_DIR, file))
+        await fs.writeFile(path.join(imagesDir(), file), Buffer.from(image.b64, 'base64'))
+        notifyImageSaved('gallery', path.join(imagesDir(), file))
         storedImages.push({
           file,
           mime: image.mime,
@@ -303,7 +303,7 @@ export async function readGalleryImage(file: string): Promise<{ data: Buffer; mi
   // store writes — so the route can never escape the images directory.
   if (!/^[a-zA-Z0-9][a-zA-Z0-9-]*-[0-9]+\.(png|jpg|jpeg|webp|gif)$/.test(file)) return undefined
   try {
-    const data = await fs.readFile(path.join(IMAGES_DIR, file))
+    const data = await fs.readFile(path.join(imagesDir(), file))
     return { data, mime: mimeOfFile(file) }
   } catch {
     return undefined

package/src/generation-runtime.ts

@@ -38,8 +38,8 @@ export class ImageGenerationRuntime {
     private readonly resolve: () => ChannelsView,
     private readonly history: HistorySink = { append: appendHistory },
   ) {
-    // A comparison can contain up to four models; let those tasks run at the
-    // same time while still applying a small host-wide concurrency limit.
+    // Every task runs in parallel up to this small host-wide limit; a
+    // four-model comparison fits within it in a single wave.
     this.queue = new GenerationTaskQueue((request, signal) => this.run(request, signal), 4)
   }
 

package/src/history-store.ts

@@ -9,14 +9,14 @@
  */
 
 import { promises as fs } from 'node:fs'
-import { homedir } from 'node:os'
 import path from 'node:path'
 import { HISTORY_MAX, type GenerateMode, type HistoryEntry, type HistoryEntryInput } from './protocol.ts'
 import { notifyImageSaved } from './storage-sync.ts'
+import { imageDataRoot } from './image-storage-path.ts'
 
-const HISTORY_DIR = path.join(homedir(), '.dsh', 'dsh-imagegen')
-const INDEX_PATH = path.join(HISTORY_DIR, 'index.json')
-const IMAGES_DIR = path.join(HISTORY_DIR, 'images')
+function historyDir(): string { return imageDataRoot() }
+function indexPath(): string { return path.join(historyDir(), 'index.json') }
+function imagesDir(): string { return path.join(historyDir(), 'images') }
 
 // History mutations read and replace one shared index. Serialize them so
 // overlapping requests cannot each read an old index and lose the other's row.
@@ -95,13 +95,13 @@ function safeId(id: string): string {
 
 /** Ensure the storage directories exist. */
 async function ensureDirs(): Promise<void> {
-  await fs.mkdir(IMAGES_DIR, { recursive: true })
+  await fs.mkdir(imagesDir(), { recursive: true })
 }
 
 /** Read the index, tolerating a missing/corrupt file. */
 async function readIndex(): Promise<StoredEntry[]> {
   try {
-    const raw = await fs.readFile(INDEX_PATH, 'utf8')
+    const raw = await fs.readFile(indexPath(), 'utf8')
     const parsed: unknown = JSON.parse(raw)
     if (parsed === null || typeof parsed !== 'object') return []
     const entries = (parsed as { entries?: unknown }).entries
@@ -116,9 +116,9 @@ async function readIndex(): Promise<StoredEntry[]> {
 async function writeIndex(entries: StoredEntry[]): Promise<void> {
   await ensureDirs()
   const payload: IndexFile = { entries }
-  const tmp = `${INDEX_PATH}.tmp-${process.pid}`
+  const tmp = `${indexPath()}.tmp-${process.pid}`
   await fs.writeFile(tmp, JSON.stringify(payload), 'utf8')
-  await fs.rename(tmp, INDEX_PATH)
+  await fs.rename(tmp, indexPath())
 }
 
 /** Structural guard for a stored entry. */
@@ -145,7 +145,7 @@ function isStoredEntry(value: unknown): value is StoredEntry {
 /** Remove one entry's image files (best effort). */
 async function removeEntryFiles(entry: StoredEntry): Promise<void> {
   for (const image of entry.images) {
-    try { await fs.rm(path.join(IMAGES_DIR, image.file), { force: true }) } catch { /* ignore */ }
+    try { await fs.rm(path.join(imagesDir(), image.file), { force: true }) } catch { /* ignore */ }
   }
 }
 
@@ -196,8 +196,8 @@ export async function appendHistory(input: HistoryEntryInput): Promise<HistoryEn
       for (let index = 0; index < input.images.length; index++) {
         const image = input.images[index]!
         const file = `${prefix}-${index}.${extensionOf(image.mime)}`
-        await fs.writeFile(path.join(IMAGES_DIR, file), Buffer.from(image.b64, 'base64'))
-        notifyImageSaved('history', path.join(IMAGES_DIR, file))
+        await fs.writeFile(path.join(imagesDir(), file), Buffer.from(image.b64, 'base64'))
+        notifyImageSaved('history', path.join(imagesDir(), file))
         storedImages.push({
           file,
           mime: image.mime,
@@ -267,7 +267,7 @@ export async function readHistoryImage(file: string): Promise<{ data: Buffer; mi
   // store writes — so the route can never escape the images directory.
   if (!/^[a-zA-Z0-9][a-zA-Z0-9-]*-[0-9]+\.(png|jpg|jpeg|webp|gif)$/.test(file)) return undefined
   try {
-    const data = await fs.readFile(path.join(IMAGES_DIR, file))
+    const data = await fs.readFile(path.join(imagesDir(), file))
     return { data, mime: mimeOfFile(file) }
   } catch {
     return undefined

package/src/image-storage-path.ts

@@ -0,0 +1,12 @@
+import { homedir } from 'node:os'
+import path from 'node:path'
+
+const DEFAULT_ROOT = path.join(process.env.DSH_HOME?.trim() || path.join(homedir(), '.dsh'), 'dsh-imagegen')
+let root = DEFAULT_ROOT
+
+export function imageDataRoot(): string { return root }
+
+export function setImageDataRoot(value: string | undefined): void {
+  const trimmed = value?.trim()
+  root = trimmed === undefined || trimmed === '' ? DEFAULT_ROOT : path.resolve(trimmed)
+}

package/src/index.ts

@@ -37,6 +37,7 @@ function mimeOfPath(filePath: string): string {
 import { ImageGenerationRuntime, type ChannelsView, type RuntimeChannel } from './generation-runtime.ts'
 import { registerAgentImageTools } from './agent-image-tools.ts'
 import { registerEditImageCommand } from './edit-image-command.ts'
+import { setImageDataRoot } from './image-storage-path.ts'
 import { presetById } from './presets.ts'
 
 /** Stable cordis plugin name. */
@@ -89,6 +90,8 @@ export interface Config {
   promptApiKey?: string
   /** Chat model used to expand short image prompts. */
   promptModel?: string
+  /** Local root for generated/history/gallery/canvas images. Empty keeps the default under DSH_HOME. */
+  localStoragePath?: string
   /** Sync saved images to an S3-compatible object store (COS / OSS / Qiniu S3 …). */
   storageEnabled?: boolean
   /** S3-compatible endpoint URL including the bucket (virtual-hosted or path style). */
@@ -133,6 +136,7 @@ export const Config: z<Config> = z.object({
   promptApiUrl: z.string().default(''),
   promptApiKey: z.string().role('secret').default(''),
   promptModel: z.string().default(''),
+  localStoragePath: z.string().default(''),
   storageEnabled: z.boolean().default(false),
   storageEndpoint: z.string().default(''),
   storageRegion: z.string().default(''),
@@ -227,6 +231,7 @@ export function apply(ctx: Context, config?: Config): (() => void) | void {
   let current: () => Config = () => config ?? {}
   const resolve = (): EffectiveConfig => {
     const value = current() ?? {}
+    setImageDataRoot(value.localStoragePath)
     let channels = normalizeChannels(value.channels)
     // Settings scopes are deep-frozen by the host. Legacy migration adds the
     // synthesized default-channel secret, so always work on a detached copy.