@dickpy/dsh-imagegen 1.0.9 → 1.0.19

package/src/gallery-store.ts

@@ -0,0 +1,266 @@
+/**
+ * Host-persisted gallery (user-curated favorites): mirrors the history store
+ * (image files + an index.json under ~/.dsh/dsh-imagegen/gallery/) but with no
+ * size cap — every entry is an explicit user choice. Appends are deduplicated
+ * by image content so adding the same generated image twice is a no-op.
+ *
+ * Framework-free (node:fs + node:crypto only) so the route layer can drive it
+ * directly.
+ */
+
+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'
+
+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')
+
+/** One gallery entry carries the same wire shape as a history entry. */
+export interface GalleryAppendResult {
+  /** The full gallery list after the append (newest first). */
+  entries: HistoryEntry[]
+  /** Whether a new entry was added (false = a content-identical image was
+   *  already in the gallery, so the append was skipped). */
+  added: boolean
+}
+
+// Gallery mutations read and replace one shared index. Serialize them so
+// overlapping requests cannot each read an old index and lose the other's row.
+let pendingMutation: Promise<void> = Promise.resolve()
+
+function mutateGallery<T>(operation: () => Promise<T>): Promise<T> {
+  const next = pendingMutation.then(operation, operation)
+  pendingMutation = next.then(() => undefined, () => undefined)
+  return next
+}
+
+/** One image's on-disk record (file name + mime, never base64). */
+interface StoredImage {
+  file: string
+  mime: string
+  revisedPrompt?: string
+}
+
+/** One entry's on-disk record. `hash` fingerprints the first image so the
+ *  store can refuse duplicate appends cheaply. */
+interface StoredEntry {
+  id: string
+  createdAt: number
+  mode: GenerateMode
+  model: string
+  prompt: string
+  size: string
+  quality: string
+  detail: string
+  n: number
+  images: StoredImage[]
+  hash?: string
+  refName?: string
+}
+
+/** The index.json shape. */
+interface IndexFile {
+  entries: StoredEntry[]
+}
+
+/** File extension for a MIME type (image file names). */
+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'
+    default: return 'png'
+  }
+}
+
+/** MIME type for a stored image file name (image route responses). */
+function mimeOfFile(file: string): string {
+  const ext = path.extname(file).toLowerCase()
+  switch (ext) {
+    case '.jpg':
+    case '.jpeg': return 'image/jpeg'
+    case '.webp': return 'image/webp'
+    case '.gif': return 'image/gif'
+    default: return 'image/png'
+  }
+}
+
+/** Sanitize an entry id for use as a file-name prefix. */
+function safeId(id: string): string {
+  const cleaned = id.replace(/[^a-zA-Z0-9-]/g, '-')
+  return cleaned === '' ? 'entry' : cleaned
+}
+
+/** Short content fingerprint of the entry's first image. */
+function fingerprint(input: HistoryEntryInput): string | undefined {
+  const first = input.images[0]
+  if (first === undefined) return undefined
+  return createHash('sha1').update(first.b64).digest('hex')
+}
+
+/** Ensure the storage directories exist. */
+async function ensureDirs(): Promise<void> {
+  await fs.mkdir(IMAGES_DIR, { 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 parsed: unknown = JSON.parse(raw)
+    if (parsed === null || typeof parsed !== 'object') return []
+    const entries = (parsed as { entries?: unknown }).entries
+    if (!Array.isArray(entries)) return []
+    return entries.filter(isStoredEntry)
+  } catch {
+    return []
+  }
+}
+
+/** Persist the index. */
+async function writeIndex(entries: StoredEntry[]): Promise<void> {
+  await ensureDirs()
+  const payload: IndexFile = { entries }
+  const tmp = `${INDEX_PATH}.tmp-${process.pid}`
+  await fs.writeFile(tmp, JSON.stringify(payload), 'utf8')
+  await fs.rename(tmp, INDEX_PATH)
+}
+
+/** Structural guard for a stored entry. */
+function isStoredEntry(value: unknown): value is StoredEntry {
+  if (value === null || typeof value !== 'object') return false
+  const entry = value as Record<string, unknown>
+  return typeof entry.id === 'string'
+    && typeof entry.createdAt === 'number'
+    && (entry.mode === 'text' || entry.mode === 'edit')
+    && typeof entry.prompt === 'string'
+    && Array.isArray(entry.images)
+    && entry.images.every(image => {
+      if (image === null || typeof image !== 'object') return false
+      const record = image as Record<string, unknown>
+      return typeof record.file === 'string' && typeof record.mime === 'string'
+    })
+}
+
+/** 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 */ }
+  }
+}
+
+/** Project a stored entry onto the wire shape (image URLs). */
+function toWire(entry: StoredEntry): HistoryEntry {
+  return {
+    id: entry.id,
+    createdAt: entry.createdAt,
+    mode: entry.mode,
+    model: entry.model,
+    prompt: entry.prompt,
+    size: entry.size,
+    quality: entry.quality,
+    detail: entry.detail,
+    n: entry.n,
+    images: entry.images.map(image => ({
+      url: `/api/dsh-imagegen/gallery/image/${image.file}`,
+      mime: image.mime,
+      ...image.revisedPrompt === undefined ? {} : { revisedPrompt: image.revisedPrompt },
+    })),
+    ...entry.refName === undefined ? {} : { refName: entry.refName },
+  }
+}
+
+/** List the persisted gallery, newest first, as wire entries. */
+export async function listGallery(): Promise<HistoryEntry[]> {
+  const entries = await readIndex()
+  return entries.map(toWire)
+}
+
+/** Append one image to the gallery. Deduplicates by first-image content —
+ *  appending an image already in the gallery returns `added: false` with the
+ *  list unchanged. No size cap: every entry is an explicit user choice. */
+export async function appendGallery(input: HistoryEntryInput): Promise<GalleryAppendResult> {
+  return mutateGallery(async () => {
+    await ensureDirs()
+    const hash = fingerprint(input)
+    if (hash !== undefined) {
+      const existing = await readIndex()
+      if (existing.some(entry => entry.hash === hash)) {
+        return { entries: existing.map(toWire), added: false }
+      }
+    }
+    const prefix = safeId(input.id)
+    const storedImages: StoredImage[] = []
+    try {
+      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'))
+        storedImages.push({
+          file,
+          mime: image.mime,
+          ...image.revisedPrompt === undefined ? {} : { revisedPrompt: image.revisedPrompt },
+        })
+      }
+    } catch (error) {
+      await removeEntryFiles({ images: storedImages } as StoredEntry)
+      throw error
+    }
+    const entry: StoredEntry = {
+      id: input.id,
+      createdAt: input.createdAt,
+      mode: input.mode,
+      model: input.model,
+      prompt: input.prompt,
+      size: input.size,
+      quality: input.quality,
+      detail: input.detail,
+      n: input.n,
+      images: storedImages,
+      ...hash === undefined ? {} : { hash },
+      ...input.refName === undefined ? {} : { refName: input.refName },
+    }
+    const merged = [entry, ...await readIndex()]
+    await writeIndex(merged)
+    return { entries: merged.map(toWire), added: true }
+  })
+}
+
+/** Remove one entry (and its image files). */
+export async function removeGallery(id: string): Promise<HistoryEntry[]> {
+  return mutateGallery(async () => {
+    const previous = await readIndex()
+    const target = previous.find(entry => entry.id === id)
+    if (target !== undefined) await removeEntryFiles(target)
+    const kept = previous.filter(entry => entry.id !== id)
+    await writeIndex(kept)
+    return kept.map(toWire)
+  })
+}
+
+/** Remove every entry (and all image files). */
+export async function clearGallery(): Promise<HistoryEntry[]> {
+  return mutateGallery(async () => {
+    const previous = await readIndex()
+    for (const entry of previous) await removeEntryFiles(entry)
+    await writeIndex([])
+    return []
+  })
+}
+
+/** Read one stored image file by its (validated) file name. */
+export async function readGalleryImage(file: string): Promise<{ data: Buffer; mime: string } | undefined> {
+  // Only accept <id>-<index>.<png|jpg|jpeg|webp|gif> — the exact names this
+  // 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))
+    return { data, mime: mimeOfFile(file) }
+  } catch {
+    return undefined
+  }
+}

package/src/index.ts

@@ -26,6 +26,7 @@ export const inject = ['webServer', 'systemPrompt']
 // contract only requires name / inject / Config / apply.
 export { makeRoutes } from './routes.ts'
 export { generateImage, ImageGenError } from './engine.ts'
+export { appendGallery, clearGallery, listGallery, readGalleryImage, removeGallery } from './gallery-store.ts'
 export { listTemplates, readTemplateImage, refreshTemplates, clearTemplateMemo } from './templates-store.ts'
 export { checkForUpdate, clearUpdateCache, compareVersions, CURRENT_VERSION, installUpdate, profileFromProcess } from './updater.ts'
 
@@ -59,7 +60,7 @@ const DEFAULT_ANNOUNCE = true
 const SECTION_ORDER = 150
 
 /** Model-facing announcement: plugin presence, capabilities, and limits. */
-export const IMAGEGEN_GUIDANCE = '本机已安装 dsh-imagegen 插件（DSH AI 生图）：侧边栏「AI 生图」入口。能力：对接 OpenAI 兼容图像生成 API（模型 gpt-image-2），支持文生图（/images/generations）与图生图（/images/edits，上传参考图）；API 地址与密钥在 GUI「设置 → 插件 → 可配置」中配置，密钥仅存于本机设置文档；生成请求由本地宿主代理转发，结果以 base64 返回面板，可预览与下载。内置「提示词模板库」（面板提示词框左下角「模板库」按钮）：打包 awesome-gpt-image-2 的数百条 gpt-image-2 提示词案例（含中文标题、分类、参考图，可搜索/按分类筛选），参考图经宿主代理按需缓存到本地；用户可一键把模板提示词填入提示词框再生成。限制：生成消耗上游 API 额度；图片内容由上游模型生成，可能不符合预期或包含不适宜内容；api_key 以明文存储在设置文档中；参考图会发送至所配置的 API 服务；模板库在线刷新与参考图首次加载需要访问 vibeui.top。用户提到「生图 / 绘画 / 生成图片 / gpt-image-2 / 文生图 / 图生图 / 提示词模板」时即指本插件，请据此协作。'
+export const IMAGEGEN_GUIDANCE = '本机已安装 dsh-imagegen 插件（DSH AI 生图）：侧边栏「AI 生图」入口。能力：对接 OpenAI 兼容图像生成 API（模型 gpt-image-2 / grok-imagine-image），支持文生图（/images/generations）与图生图（/images/edits，上传参考图，grok 模型按官方 JSON image_url 协议发送）；API 地址与密钥在 GUI「设置 → 插件 → 可配置」中配置，密钥仅存于本机设置文档；生成请求由本地宿主代理转发，结果以 base64 返回面板，可预览与下载；可一键把满意的图片加入「画廊」（工作台顶部 文生图 / 图生图 / 画廊 三个标签页，画廊在右侧展示，收藏持久化在本地 ~/.dsh/dsh-imagegen/gallery/）。内置「提示词模板库」（面板提示词框左下角「模板库」按钮）：打包 awesome-gpt-image-2 的数百条 gpt-image-2 提示词案例（含中文标题、分类、参考图，可搜索/按分类筛选），参考图经宿主代理按需缓存到本地；用户可一键把模板提示词填入提示词框再生成。限制：生成消耗上游 API 额度；图片内容由上游模型生成，可能不符合预期或包含不适宜内容；api_key 以明文存储在设置文档中；参考图会发送至所配置的 API 服务；模板库在线刷新与参考图首次加载需要访问 vibeui.top。用户提到「生图 / 绘画 / 生成图片 / gpt-image-2 / grok-imagine-image / 文生图 / 图生图 / 画廊 / 提示词模板」时即指本插件，请据此协作。'
 
 /** Effective config (schema defaults applied). */
 interface EffectiveConfig {

package/src/protocol.ts

@@ -1,14 +1,14 @@
 /**
  * Wire contract shared by the host and client halves of dsh-imagegen: the
  * settings namespace, the route paths, and the generate payload/result shapes.
- * Pure types + constants — safe for the client bundle to inline.
+ * Pure types + constants 鈥?safe for the client bundle to inline.
  */
 
 /** Settings namespace this plugin owns (host settings seam + bridge). */
 export const IMAGEGEN_SETTINGS_NAMESPACE = 'dsh-imagegen'
 
 /** Published package version shared by the host updater and the client UI. */
-export const PLUGIN_VERSION = '1.0.9'
+export const PLUGIN_VERSION = '1.0.19'
 
 /** Same-origin route family (loopback-only, mirroring the dsh-ssh fence). */
 export const SETTINGS_API = {
@@ -39,6 +39,19 @@ export const HISTORY_API = {
   image: '/api/dsh-imagegen/history/image',
 } as const
 
+/**
+ * Same-origin route family for the user-curated gallery (favorites). Entries
+ * reuse the history wire shape and persist under ~/.dsh/dsh-imagegen/gallery/;
+ * unlike history there is no size cap 鈥?the user adds images on purpose.
+ */
+export const GALLERY_API = {
+  list: '/api/dsh-imagegen/gallery/list',
+  append: '/api/dsh-imagegen/gallery/append',
+  remove: '/api/dsh-imagegen/gallery/remove',
+  clear: '/api/dsh-imagegen/gallery/clear',
+  image: '/api/dsh-imagegen/gallery/image',
+} as const
+
 /** Maximum number of history entries retained host-side (oldest evicted). */
 export const HISTORY_MAX = 50
 
@@ -103,7 +116,7 @@ export interface TemplateRefreshResult {
 /** Generation modes. */
 export type GenerateMode = 'text' | 'edit'
 
-/** A client → host generate request (what the panel collects). */
+/** A client 鈫?host generate request (what the panel collects). */
 export interface GenerateRequest {
   /** text-to-image (images/generations) or image-to-image (images/edits). */
   mode: GenerateMode
@@ -111,9 +124,12 @@ export interface GenerateRequest {
   model: string
   /** The prompt (up to 2000 chars in the UI). */
   prompt: string
-  /** Canvas size: 'auto' or a pixel size like '1024x1024'. */
+  /** Canvas size as an aspect ratio: 'auto' or e.g. '1:1' / '16:9' / '21:9'.
+   *  The host maps it onto each model's own vocabulary (aspect_ratio for Grok,
+   *  the closest pixel size for OpenAI-compatible endpoints). */
   size: string
-  /** Quality: 'auto' | 'low' | 'medium' | 'high'. */
+  /** Clarity tier: 'auto' | '1k' | '2k' | '4k'. The host maps it onto the
+   *  model's own vocabulary (resolution for Grok, quality for OpenAI). */
   quality: string
   /** Number of images, 1-4. */
   n: number

package/src/routes.ts

@@ -11,9 +11,10 @@ import type { WebRoute } from '@deepseek-ai/dsh-host-webserver'
 import { SettingsConflictError, settingsNamespace, type SettingsDescriptor } from '@deepseek-ai/dsh-settings'
 import { generateImage, type UpstreamConfig } from './engine.ts'
 import { appendHistory, clearHistory, listHistory, readHistoryImage, removeHistory } from './history-store.ts'
+import { appendGallery, clearGallery, listGallery, readGalleryImage, removeGallery } from './gallery-store.ts'
 import { listTemplates, readTemplateImage, refreshTemplates } from './templates-store.ts'
 import { checkForUpdate, CURRENT_VERSION, installUpdate } from './updater.ts'
-import { GENERATE_API, HISTORY_API, IMAGEGEN_SETTINGS_NAMESPACE, SETTINGS_API, TEMPLATES_API, UPDATE_API, type GeneratedImage, type GenerateRequest, type HistoryEntry, type HistoryEntryInput, type TemplateListResult, type TemplateRefreshResult } from './protocol.ts'
+import { GALLERY_API, GENERATE_API, HISTORY_API, IMAGEGEN_SETTINGS_NAMESPACE, SETTINGS_API, TEMPLATES_API, UPDATE_API, type GeneratedImage, type GenerateRequest, type HistoryEntry, type HistoryEntryInput, type TemplateListResult, type TemplateRefreshResult } from './protocol.ts'
 
 /** Cap on JSON request bodies (settings ops and generate payloads are small). */
 const MAX_JSON_BODY_BYTES = 24 * 1024 * 1024
@@ -42,6 +43,14 @@ export interface ImageGenRoutesDeps {
     clear: () => Promise<HistoryEntry[]>
     readImage: (file: string) => Promise<{ data: Buffer; mime: string } | undefined>
   }
+  /** Overrideable gallery backend, primarily for host integration tests. */
+  gallery?: {
+    list: () => Promise<HistoryEntry[]>
+    append: (entry: HistoryEntryInput) => Promise<{ entries: HistoryEntry[]; added: boolean }>
+    remove: (id: string) => Promise<HistoryEntry[]>
+    clear: () => Promise<HistoryEntry[]>
+    readImage: (file: string) => Promise<{ data: Buffer; mime: string } | undefined>
+  }
   /** Overrideable template-library backend, primarily for host integration tests. */
   templates?: {
     list: () => Promise<TemplateListResult>
@@ -190,6 +199,13 @@ export function makeRoutes(deps: ImageGenRoutesDeps): WebRoute[] {
     clear: clearHistory,
     readImage: readHistoryImage,
   }
+  const gallery = deps.gallery ?? {
+    list: listGallery,
+    append: appendGallery,
+    remove: removeGallery,
+    clear: clearGallery,
+    readImage: readGalleryImage,
+  }
   const templates = deps.templates ?? {
     list: listTemplates,
     refresh: refreshTemplates,
@@ -454,6 +470,108 @@ export function makeRoutes(deps: ImageGenRoutesDeps): WebRoute[] {
         res.end(found.data)
       },
     },
+    // ----------------------------------------------------- gallery list
+    {
+      kind: 'exact',
+      path: GALLERY_API.list,
+      handler: async (req, res) => {
+        if (!guard(req, res, 'POST')) return
+        try {
+          writeJson(res, 200, { ok: true, entries: await gallery.list() })
+        } catch (error) {
+          writeJson(res, 200, { ok: false, code: 'gallery-failed', message: messageOf(error) })
+        }
+      },
+    },
+    // --------------------------------------------------- gallery append
+    {
+      kind: 'exact',
+      path: GALLERY_API.append,
+      handler: async (req, res) => {
+        if (!guard(req, res, 'POST')) return
+        const body = await readJsonBody(req, MAX_HISTORY_BODY_BYTES)
+        if (body === undefined) {
+          writeJson(res, 200, { ok: false, code: 'bad-request', message: 'unreadable JSON body' })
+          return
+        }
+        const entry = parseHistoryEntryInput(body)
+        if (entry === undefined) {
+          writeJson(res, 200, { ok: false, code: 'bad-request', message: 'malformed gallery entry' })
+          return
+        }
+        try {
+          // The host owns gallery ids: a fresh id per append keeps retries and
+          // duplicate submissions from ever reusing a stale filename prefix.
+          const result = await gallery.append({ ...entry, id: randomUUID() })
+          writeJson(res, 200, { ok: true, entries: result.entries, added: result.added })
+        } catch (error) {
+          writeJson(res, 200, { ok: false, code: 'gallery-failed', message: messageOf(error) })
+        }
+      },
+    },
+    // --------------------------------------------------- gallery remove
+    {
+      kind: 'exact',
+      path: GALLERY_API.remove,
+      handler: async (req, res) => {
+        if (!guard(req, res, 'POST')) return
+        const body = await readJsonBody(req)
+        const id = body !== undefined && typeof body.id === 'string' ? body.id : ''
+        if (id === '') {
+          writeJson(res, 200, { ok: false, code: 'bad-request', message: 'gallery id is required' })
+          return
+        }
+        try {
+          writeJson(res, 200, { ok: true, entries: await gallery.remove(id) })
+        } catch (error) {
+          writeJson(res, 200, { ok: false, code: 'gallery-failed', message: messageOf(error) })
+        }
+      },
+    },
+    // ---------------------------------------------------- gallery clear
+    {
+      kind: 'exact',
+      path: GALLERY_API.clear,
+      handler: async (req, res) => {
+        if (!guard(req, res, 'POST')) return
+        try {
+          writeJson(res, 200, { ok: true, entries: await gallery.clear() })
+        } catch (error) {
+          writeJson(res, 200, { ok: false, code: 'gallery-failed', message: messageOf(error) })
+        }
+      },
+    },
+    // ------------------------------------------------ gallery image (prefix)
+    {
+      kind: 'prefix',
+      path: GALLERY_API.image,
+      handler: async (req, res) => {
+        if (!isLoopbackRequest(req)) {
+          writeJson(res, 403, { error: 'forbidden: loopback-only' })
+          return
+        }
+        if (req.method !== 'GET') {
+          writeJson(res, 405, { error: `method not allowed: ${req.method}` })
+          return
+        }
+        const file = imageFileFrom(req.url, GALLERY_API.image)
+        if (file === undefined) {
+          writeJson(res, 404, { error: 'not found' })
+          return
+        }
+        const found = await gallery.readImage(file)
+        if (found === undefined) {
+          writeJson(res, 404, { error: 'not found' })
+          return
+        }
+        res.writeHead(200, {
+          'content-type': found.mime,
+          'content-length': found.data.length,
+          'cache-control': 'private, max-age=3600',
+        })
+        res.end(found.data)
+      },
+    },
     // --------------------------------------------------- templates list
     {
       kind: 'exact',