@dickpy/dsh-imagegen 1.5.0 → 1.5.2

package/src/protocol.ts

@@ -8,7 +8,7 @@
 export const IMAGEGEN_SETTINGS_NAMESPACE = 'dsh-imagegen'
 
 /** Published package version shared by the host updater and the client UI. */
-export const PLUGIN_VERSION = '1.5.0'
+export const PLUGIN_VERSION = '1.5.2'
 
 /** Same-origin route family (loopback-only, mirroring the dsh-ssh fence). */
 export const SETTINGS_API = {
@@ -92,17 +92,68 @@ export const GALLERY_API = {
 export const HISTORY_MAX = 50
 
 /**
- * Same-origin route family for the bundled prompt-template library
- * (awesome-gpt-image-2 mirror). The case list ships inside the package and is
- * served by the host; reference images are proxied through the `image` prefix
- * route and cached on disk so repeated views never hit the network again.
+ * Same-origin route family for the prompt-template libraries. The library is
+ * multi-source: every request names a source id from {@link TEMPLATE_SOURCES},
+ * each source keeps an independent snapshot/image cache host-side, and
+ * reference images are proxied through the source-scoped `image` prefix route
+ * (`…/image/<sourceId>/<file>`) and cached on disk so repeated views never hit
+ * the network again.
  */
 export const TEMPLATES_API = {
   list: '/api/dsh-imagegen/templates/list',
   refresh: '/api/dsh-imagegen/templates/refresh',
+  sample: '/api/dsh-imagegen/templates/sample',
   image: '/api/dsh-imagegen/templates/image',
 } as const
 
+/** Same-origin route family for the user's saved (favorited) templates. */
+export const TEMPLATE_FAVORITES_API = {
+  list: '/api/dsh-imagegen/templates/favorites/list',
+  add: '/api/dsh-imagegen/templates/favorites/add',
+  remove: '/api/dsh-imagegen/templates/favorites/remove',
+} as const
+
+/** One prompt-template library source (a tab in the library overlay). */
+export interface TemplateSourceMeta {
+  /** Stable source id: snapshot dir name, image-cache dir, and request key. */
+  id: string
+  /** Tab label shown in the library overlay. */
+  label: string
+  /** Source homepage linked in the overlay footer. */
+  homepage: string
+  /** One-line description of the source (tab tooltip). */
+  description: string
+}
+
+/**
+ * The template-library source registry. Each entry is fully independent (own
+ * upstream JSON, own image pool, own refresh state) and renders as its own
+ * tab; adding a source later means appending an entry here plus a host-side
+ * fetch definition in templates-store.ts and an optional bundled snapshot.
+ */
+export const TEMPLATE_SOURCES: TemplateSourceMeta[] = [
+  {
+    id: 'vibeui',
+    label: '精选案例库',
+    homepage: 'https://vibeui.top/',
+    description: 'awesome-gpt-image-2 精选提示词案例（vibeui.top 镜像）',
+  },
+  {
+    id: 'canghe',
+    label: '沧河案例库',
+    homepage: 'https://gpt-image2.canghe.ai/',
+    description: 'GPT-Image2 Prompt Gallery（gpt-image2.canghe.ai，定期更新）',
+  },
+]
+
+/** Default source id when a request does not name one (legacy clients). */
+export const DEFAULT_TEMPLATE_SOURCE_ID = TEMPLATE_SOURCES[0]!.id
+
+/** True when the id names a registered template source. */
+export function isTemplateSourceId(id: string): boolean {
+  return TEMPLATE_SOURCES.some(source => source.id === id)
+}
+
 /** One prompt-library case as the browser consumes it. */
 export interface TemplateCase {
   /** Upstream case number (stable across refreshes). */
@@ -131,8 +182,10 @@ export interface TemplateCase {
   featured: boolean
 }
 
-/** Template-library list payload. */
+/** Template-library list payload (one source). */
 export interface TemplateListResult {
+  /** The source this list belongs to. */
+  sourceId: string
   cases: TemplateCase[]
   total: number
   /** Where the served list came from. */
@@ -143,12 +196,33 @@ export interface TemplateListResult {
   fetchedAt: string
 }
 
-/** Template-library refresh outcome. */
+/** Template-library refresh outcome (one source). */
 export interface TemplateRefreshResult {
+  sourceId: string
   total: number
   fetchedAt: string
 }
 
+/** One random inspiration pick served to the studio's empty state. */
+export interface TemplateSample {
+  /** Source the case came from (drives the image proxy URL). */
+  sourceId: string
+  /** The sampled case (full prompt is handed to the form on use). */
+  case: TemplateCase
+}
+
+/** One favorited template as persisted host-side and served to the browser. */
+export interface TemplateFavorite {
+  /** Stable key: `${sourceId}:${caseId}`. */
+  key: string
+  /** Source the case came from. */
+  sourceId: string
+  /** ISO time the favorite was saved. */
+  savedAt: string
+  /** Full case snapshot, so favorites survive upstream list churn. */
+  case: TemplateCase
+}
+
 /** Generation modes. */
 export type GenerateMode = 'text' | 'edit'
 

package/src/routes.ts

@@ -9,17 +9,18 @@ import type { IncomingMessage, ServerResponse } from 'node:http'
 import { randomUUID } from 'node:crypto'
 import type { WebRoute } from '@deepseek-ai/dsh-host-webserver'
 import type { ImageAttachmentRef, ImageMediaType, SaveImageAttachment } from '@deepseek-ai/dsh-attachment'
-import { SettingsConflictError, settingsNamespace, type SettingsDescriptor } from '@deepseek-ai/dsh-settings'
+import { SettingsConflictError, type SettingsDescriptor } from '@deepseek-ai/dsh-settings'
 import type { UpstreamConfig } from './engine.ts'
 import { enhancePrompt, listImageModels, listPromptModels, type PromptModelConfig } from './prompt-enhancer.ts'
 import { normalizeImageModels } from './image-models.ts'
 import { ImageGenerationRuntime, type ChannelsView } from './generation-runtime.ts'
 import { appendHistory, clearHistory, listHistory, readHistoryImage, removeHistory } from './history-store.ts'
 import { appendGallery, clearGallery, listGallery, readGalleryImage, removeGallery, updateGalleryTags } from './gallery-store.ts'
-import { listTemplates, readTemplateImage, refreshTemplates } from './templates-store.ts'
+import { listTemplates, readTemplateImage, refreshTemplates, sampleTemplates } from './templates-store.ts'
+import { addTemplateFavorite, listTemplateFavorites, removeTemplateFavorite } from './template-favorites.ts'
 import { checkForUpdate, CURRENT_VERSION, installUpdate } from './updater.ts'
 import { IMAGE_PRESETS } from './presets.ts'
-import { AGENT_IMAGE_API, CONVERSATION_IMAGE_API, GALLERY_API, GENERATE_API, HISTORY_API, IMAGEGEN_SETTINGS_NAMESPACE, IMAGE_MODEL_API, PRESETS_API, PROMPT_ENHANCE_API, SETTINGS_API, TASK_API, TEMPLATES_API, UPDATE_API, USAGE_API, type GeneratedImage, type GenerateRequest, type HistoryEntry, type HistoryEntryInput, type ModelMapping, type PresetProviderView, type TemplateListResult, type TemplateRefreshResult } from './protocol.ts'
+import { AGENT_IMAGE_API, CONVERSATION_IMAGE_API, DEFAULT_TEMPLATE_SOURCE_ID, GALLERY_API, GENERATE_API, HISTORY_API, IMAGEGEN_SETTINGS_NAMESPACE, IMAGE_MODEL_API, PRESETS_API, PROMPT_ENHANCE_API, SETTINGS_API, TASK_API, TEMPLATE_FAVORITES_API, TEMPLATES_API, UPDATE_API, USAGE_API, isTemplateSourceId, type GeneratedImage, type GenerateRequest, type HistoryEntry, type HistoryEntryInput, type ModelMapping, type PresetProviderView, type TemplateFavorite, type TemplateListResult, type TemplateRefreshResult, type TemplateSample } from './protocol.ts'
 
 /** Cap on JSON request bodies (settings ops and generate payloads are small). */
 const MAX_JSON_BODY_BYTES = 24 * 1024 * 1024
@@ -74,9 +75,16 @@ export interface ImageGenRoutesDeps {
   }
   /** Overrideable template-library backend, primarily for host integration tests. */
   templates?: {
-    list: () => Promise<TemplateListResult>
-    refresh: () => Promise<TemplateRefreshResult>
-    readImage: (file: string) => Promise<{ data: Buffer; mime: string } | undefined>
+    list: (sourceId: string) => Promise<TemplateListResult>
+    refresh: (sourceId: string) => Promise<TemplateRefreshResult>
+    sample: (count: number) => Promise<TemplateSample[]>
+    readImage: (sourceId: string, file: string) => Promise<{ data: Buffer; mime: string } | undefined>
+  }
+  /** Overrideable template-favorites backend, primarily for host integration tests. */
+  favorites?: {
+    list: () => Promise<TemplateFavorite[]>
+    add: (sourceId: string, item: TemplateFavorite['case']) => Promise<TemplateFavorite[]>
+    remove: (key: string) => Promise<TemplateFavorite[]>
   }
   /** Shared host queue, used by Agent tools and browser task endpoints. */
   runtime?: ImageGenerationRuntime
@@ -135,6 +143,13 @@ function messageOf(error: unknown): string {
   return error instanceof Error ? error.message : String(error)
 }
 
+/** Validate the { source } body of a template-library request. */
+function templateSourceOf(body: Record<string, unknown> | undefined): string | undefined {
+  const raw = body?.source
+  if (raw === undefined || raw === '') return DEFAULT_TEMPLATE_SOURCE_ID
+  return typeof raw === 'string' && isTemplateSourceId(raw) ? raw : undefined
+}
+
 function parseGenerateRequest(body: Record<string, unknown>): GenerateRequest | undefined {
   const prompt = typeof body.prompt === 'string' ? body.prompt.trim() : ''
   if (prompt === '') return undefined
@@ -311,8 +326,14 @@ export function makeRoutes(deps: ImageGenRoutesDeps): WebRoute[] {
   const templates = deps.templates ?? {
     list: listTemplates,
     refresh: refreshTemplates,
+    sample: sampleTemplates,
     readImage: readTemplateImage,
   }
+  const favorites = deps.favorites ?? {
+    list: listTemplateFavorites,
+    add: addTemplateFavorite,
+    remove: removeTemplateFavorite,
+  }
   const resolvePrompt = deps.resolvePrompt ?? (() => ({ apiUrl: '', apiKey: '', model: '' }))
   const resolveImageModels = deps.resolveImageModels ?? (() => normalizeImageModels(undefined))
 
@@ -563,7 +584,9 @@ export function makeRoutes(deps: ImageGenRoutesDeps): WebRoute[] {
         }
         const expectedRevision = typeof body.expectedRevision === 'number' ? body.expectedRevision : undefined
         try {
-          await deps.settings.mutate(settingsNamespace(ns), body.ops, expectedRevision)
+          // The alpha.2 settings package no longer exports settingsNamespace;
+          // the bridge already checked this value against our fixed namespace.
+          await deps.settings.mutate(ns, body.ops, expectedRevision)
         } catch (error) {
           writeJson(res, 200, failureOf(error))
           return
@@ -906,8 +929,14 @@ export function makeRoutes(deps: ImageGenRoutesDeps): WebRoute[] {
       path: TEMPLATES_API.list,
       handler: async (req, res) => {
         if (!guard(req, res, 'POST')) return
+        const body = await readJsonBody(req)
+        const sourceId = templateSourceOf(body)
+        if (sourceId === undefined) {
+          writeJson(res, 200, { ok: false, code: 'templates-source-unknown', message: `未知的模板库来源：${String(body?.source ?? '')}` })
+          return
+        }
         try {
-          const result = await templates.list()
+          const result = await templates.list(sourceId)
           writeJson(res, 200, { ok: true, ...result })
         } catch (error) {
           writeJson(res, 200, { ok: false, code: 'templates-failed', message: messageOf(error) })
@@ -920,14 +949,36 @@ export function makeRoutes(deps: ImageGenRoutesDeps): WebRoute[] {
       path: TEMPLATES_API.refresh,
       handler: async (req, res) => {
         if (!guard(req, res, 'POST')) return
+        const body = await readJsonBody(req)
+        const sourceId = templateSourceOf(body)
+        if (sourceId === undefined) {
+          writeJson(res, 200, { ok: false, code: 'templates-source-unknown', message: `未知的模板库来源：${String(body?.source ?? '')}` })
+          return
+        }
         try {
-          const result = await templates.refresh()
+          const result = await templates.refresh(sourceId)
           writeJson(res, 200, { ok: true, ...result })
         } catch (error) {
           writeJson(res, 200, { ok: false, code: 'templates-refresh-failed', message: messageOf(error) })
         }
       },
     },
+    // --------------------------------------------- templates random sample
+    {
+      kind: 'exact',
+      path: TEMPLATES_API.sample,
+      handler: async (req, res) => {
+        if (!guard(req, res, 'POST')) return
+        const body = await readJsonBody(req)
+        const requested = Number(body?.count)
+        const count = Number.isFinite(requested) ? requested : 9
+        try {
+          writeJson(res, 200, { ok: true, samples: await templates.sample(count) })
+        } catch (error) {
+          writeJson(res, 200, { ok: false, code: 'templates-sample-failed', message: messageOf(error) })
+        }
+      },
+    },
     // -------------------------------------- templates image (prefix, proxied)
     {
       kind: 'prefix',
@@ -941,12 +992,17 @@ export function makeRoutes(deps: ImageGenRoutesDeps): WebRoute[] {
           writeJson(res, 405, { error: `method not allowed: ${req.method}` })
           return
         }
-        const file = imageFileFrom(req.url, TEMPLATES_API.image)
-        if (file === undefined) {
+        // Source-scoped: /image/<sourceId>/<file> (file names collide across
+        // sources, so the pool on disk is per source).
+        const raw = imageFileFrom(req.url, TEMPLATES_API.image)
+        const slash = raw?.indexOf('/') ?? -1
+        const sourceId = slash > 0 ? raw!.slice(0, slash) : ''
+        const file = slash > 0 ? raw!.slice(slash + 1) : ''
+        if (sourceId === '' || !isTemplateSourceId(sourceId) || file === '') {
           writeJson(res, 404, { error: 'not found' })
           return
         }
-        const found = await templates.readImage(file)
+        const found = await templates.readImage(sourceId, file)
         if (found === undefined) {
           writeJson(res, 404, { error: 'not found' })
           return
@@ -960,5 +1016,65 @@ export function makeRoutes(deps: ImageGenRoutesDeps): WebRoute[] {
         res.end(found.data)
       },
     },
+    // ------------------------------------------ template favorites: list
+    {
+      kind: 'exact',
+      path: TEMPLATE_FAVORITES_API.list,
+      handler: async (req, res) => {
+        if (!guard(req, res, 'POST')) return
+        try {
+          writeJson(res, 200, { ok: true, favorites: await favorites.list() })
+        } catch (error) {
+          writeJson(res, 200, { ok: false, code: 'template-favorites-failed', message: messageOf(error) })
+        }
+      },
+    },
+    // ------------------------------------------- template favorites: add
+    {
+      kind: 'exact',
+      path: TEMPLATE_FAVORITES_API.add,
+      handler: async (req, res) => {
+        if (!guard(req, res, 'POST')) return
+        const body = await readJsonBody(req)
+        const sourceId = templateSourceOf(body)
+        const rawCase = body?.case
+        if (sourceId === undefined || rawCase === null || typeof rawCase !== 'object') {
+          writeJson(res, 200, { ok: false, code: 'template-favorite-invalid', message: '收藏请求缺少有效的来源或模板数据' })
+          return
+        }
+        const record = rawCase as Record<string, unknown>
+        const id = Number(record.id)
+        const title = typeof record.title === 'string' ? record.title.trim() : ''
+        const prompt = typeof record.prompt === 'string' ? record.prompt.trim() : ''
+        if (!Number.isInteger(id) || title === '' || prompt === '') {
+          writeJson(res, 200, { ok: false, code: 'template-favorite-invalid', message: '收藏请求缺少有效的模板数据' })
+          return
+        }
+        try {
+          writeJson(res, 200, { ok: true, favorites: await favorites.add(sourceId, rawCase as TemplateFavorite['case']) })
+        } catch (error) {
+          writeJson(res, 200, { ok: false, code: 'template-favorites-failed', message: messageOf(error) })
+        }
+      },
+    },
+    // ---------------------------------------- template favorites: remove
+    {
+      kind: 'exact',
+      path: TEMPLATE_FAVORITES_API.remove,
+      handler: async (req, res) => {
+        if (!guard(req, res, 'POST')) return
+        const body = await readJsonBody(req)
+        const key = typeof body?.key === 'string' ? body.key : ''
+        if (key === '') {
+          writeJson(res, 200, { ok: false, code: 'template-favorite-invalid', message: '取消收藏请求缺少模板标识' })
+          return
+        }
+        try {
+          writeJson(res, 200, { ok: true, favorites: await favorites.remove(key) })
+        } catch (error) {
+          writeJson(res, 200, { ok: false, code: 'template-favorites-failed', message: messageOf(error) })
+        }
+      },
+    },
   ]
 }

package/src/settings-compat.ts

@@ -0,0 +1,60 @@
+/** Compatibility helpers for the dsh-settings API transition. */
+
+import type { Context } from '@deepseek-ai/cordis'
+import * as settingsModule from '@deepseek-ai/dsh-settings'
+import type { SettingsNamespace, SettingsSectionHooks } from '@deepseek-ai/dsh-settings'
+import type z from 'schemastery'
+
+type SettingsModuleCompat = {
+  settingsNamespace?: (value: string) => SettingsNamespace
+  installSettingsSection?: <T>(
+    ctx: Context,
+    ns: SettingsNamespace,
+    schema: z<T>,
+    entry: T,
+    hooks: SettingsSectionHooks<T>,
+  ) => void
+}
+
+interface SettingsProviderCompat {
+  installSection?: <T>(
+    owner: Context,
+    ns: SettingsNamespace,
+    schema: z<T>,
+    entry: T,
+    hooks: SettingsSectionHooks<T>,
+  ) => void
+}
+
+const compatModule = settingsModule as unknown as SettingsModuleCompat
+
+/** Brand namespaces where the installed settings package still exposes it. */
+export function settingsNamespaceCompat(value: string): SettingsNamespace {
+  return compatModule.settingsNamespace?.(value) ?? value as SettingsNamespace
+}
+
+/**
+ * Register an optional settings section across the rc.7 and alpha.2 APIs.
+ * rc.7 exposes a module helper; alpha.2 moves the helper onto the provider.
+ */
+export function installSettingsSectionCompat<T>(
+  ctx: Context,
+  ns: SettingsNamespace,
+  schema: z<T>,
+  entry: T,
+  hooks: SettingsSectionHooks<T>,
+): void {
+  const legacyInstaller = compatModule.installSettingsSection
+  if (legacyInstaller !== undefined) {
+    legacyInstaller(ctx, ns, schema, entry, hooks)
+    return
+  }
+
+  ctx.inject(['settings'], (sctx) => {
+    const provider = sctx.get('settings') as unknown as SettingsProviderCompat
+    if (provider.installSection === undefined) {
+      throw new TypeError('dsh-settings does not expose installSection')
+    }
+    provider.installSection(ctx, ns, schema, entry, hooks)
+  })
+}

package/src/template-favorites.ts

@@ -0,0 +1,108 @@
+/**
+ * Favorites store for the prompt-template library.
+ *
+ * The user's starred templates persist host-side as full case snapshots under
+ * ~/.dsh/dsh-imagegen/templates/favorites.json, keyed by
+ * `${sourceId}:${caseId}` — the snapshot means a favorite stays usable even
+ * after the upstream list drops or renumbers the case. Framework-free
+ * (node:fs only) so the route layer and tests can drive it directly.
+ */
+
+import { promises as fs } from 'node:fs'
+import { homedir } from 'node:os'
+import path from 'node:path'
+import { isTemplateSourceId, type TemplateCase, type TemplateFavorite } from './protocol.ts'
+
+const DATA_DIR = path.join(homedir(), '.dsh', 'dsh-imagegen')
+const FAVORITES_PATH = path.join(DATA_DIR, 'templates', 'favorites.json')
+
+/** Refuse to grow the file without bound; the user curates this list. */
+const MAX_FAVORITES = 1000
+
+/** In-memory memo of the persisted list. */
+let memo: TemplateFavorite[] | undefined
+
+/** Build the stable key of one case within a source. */
+export function templateFavoriteKey(sourceId: string, caseId: number): string {
+  return `${sourceId}:${caseId}`
+}
+
+/** Validate + normalize one raw stored favorite; undefined when unusable. */
+function normalizeFavorite(raw: unknown): TemplateFavorite | undefined {
+  if (raw === null || typeof raw !== 'object') return undefined
+  const record = raw as Record<string, unknown>
+  if (typeof record.key !== 'string' || typeof record.savedAt !== 'string') return undefined
+  const sourceId = typeof record.sourceId === 'string' ? record.sourceId : ''
+  if (!isTemplateSourceId(sourceId)) return undefined
+  if (record.key !== templateFavoriteKey(sourceId, Number(record.case && (record.case as TemplateCase).id))) return undefined
+  const rawCase = record.case
+  if (rawCase === null || typeof rawCase !== 'object') return undefined
+  const item = rawCase as Record<string, unknown>
+  const id = Number(item.id)
+  const title = typeof item.title === 'string' ? item.title : ''
+  const prompt = typeof item.prompt === 'string' ? item.prompt : ''
+  if (!Number.isInteger(id) || title === '' || prompt === '') return undefined
+  // Keep only the wire fields so hand-edited files cannot smuggle extras.
+  const snapshot: TemplateCase = {
+    id,
+    title,
+    prompt,
+    category: typeof item.category === 'string' ? item.category : '',
+    categoryZh: typeof item.categoryZh === 'string' ? item.categoryZh : '',
+    styles: Array.isArray(item.styles) ? item.styles.map(String) : [],
+    scenes: Array.isArray(item.scenes) ? item.scenes.map(String) : [],
+    sourceLabel: typeof item.sourceLabel === 'string' ? item.sourceLabel : '',
+    sourceUrl: typeof item.sourceUrl === 'string' ? item.sourceUrl : '',
+    githubUrl: typeof item.githubUrl === 'string' ? item.githubUrl : '',
+    image: typeof item.image === 'string' ? item.image : '',
+    featured: item.featured === true,
+  }
+  return { key: record.key, sourceId, savedAt: record.savedAt, case: snapshot }
+}
+
+/** Read + parse the favorites file (memoized). */
+export async function listTemplateFavorites(): Promise<TemplateFavorite[]> {
+  if (memo !== undefined) return memo
+  try {
+    const parsed: unknown = JSON.parse(await fs.readFile(FAVORITES_PATH, 'utf8'))
+    memo = Array.isArray(parsed)
+      ? parsed.map(normalizeFavorite).filter((entry): entry is TemplateFavorite => entry !== undefined)
+      : []
+  } catch {
+    memo = []
+  }
+  return memo
+}
+
+/** Persist the list atomically and update the memo. */
+async function writeFavorites(entries: TemplateFavorite[]): Promise<void> {
+  memo = entries
+  await fs.mkdir(path.dirname(FAVORITES_PATH), { recursive: true })
+  const tmp = `${FAVORITES_PATH}.tmp-${process.pid}`
+  await fs.writeFile(tmp, JSON.stringify(entries, null, 2), 'utf8')
+  await fs.rename(tmp, FAVORITES_PATH)
+}
+
+/** Star one template. Re-starring refreshes the snapshot and is idempotent. */
+export async function addTemplateFavorite(sourceId: string, item: TemplateCase): Promise<TemplateFavorite[]> {
+  if (!isTemplateSourceId(sourceId)) throw new Error(`未知的模板库来源：${sourceId}`)
+  const key = templateFavoriteKey(sourceId, item.id)
+  const rest = (await listTemplateFavorites()).filter(entry => entry.key !== key)
+  const entry: TemplateFavorite = { key, sourceId, savedAt: new Date().toISOString(), case: item }
+  const next = [entry, ...rest].slice(0, MAX_FAVORITES)
+  await writeFavorites(next)
+  return next
+}
+
+/** Unstar one template by key; unknown keys are a no-op. */
+export async function removeTemplateFavorite(key: string): Promise<TemplateFavorite[]> {
+  const next = (await listTemplateFavorites()).filter(entry => entry.key !== key)
+  if (next.length === memo?.length) return next
+  await writeFavorites(next)
+  return next
+}
+
+/** Drop the in-memory memo (tests). */
+export function clearTemplateFavoritesMemo(): void {
+  memo = undefined
+}