@dickpy/dsh-imagegen 1.0.0

package/src/history-store.ts

@@ -0,0 +1,217 @@
+/**
+ * Host-persisted generation history: images are stored as individual files
+ * under ~/.dsh/dsh-imagegen/images/ and an index.json keeps the metadata +
+ * file names. This makes the history survive across browsers/devices that
+ * connect to the same DSH host, and keeps list responses small (the browser
+ * loads image bytes lazily through the history image route).
+ *
+ * Framework-free (node:fs only) so the route layer can drive it directly.
+ */
+
+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'
+
+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')
+
+/** 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. */
+interface StoredEntry {
+  id: string
+  createdAt: number
+  mode: GenerateMode
+  model: string
+  prompt: string
+  size: string
+  quality: string
+  detail: string
+  n: number
+  images: StoredImage[]
+  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
+}
+
+/** 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/history/image/${image.file}`,
+      mime: image.mime,
+      ...image.revisedPrompt === undefined ? {} : { revisedPrompt: image.revisedPrompt },
+    })),
+    ...entry.refName === undefined ? {} : { refName: entry.refName },
+  }
+}
+
+/** List the persisted history, newest first, as wire entries. */
+export async function listHistory(): Promise<HistoryEntry[]> {
+  const entries = await readIndex()
+  return entries.map(toWire)
+}
+
+/** Append one generation, evicting the oldest beyond HISTORY_MAX. */
+export async function appendHistory(input: HistoryEntryInput): Promise<HistoryEntry[]> {
+  await ensureDirs()
+  const prefix = safeId(input.id)
+  const storedImages: StoredImage[] = []
+  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 },
+    })
+  }
+  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,
+    ...input.refName === undefined ? {} : { refName: input.refName },
+  }
+  const merged = [entry, ...await readIndex()]
+  const kept = merged.slice(0, HISTORY_MAX)
+  for (const dropped of merged.slice(HISTORY_MAX)) await removeEntryFiles(dropped)
+  await writeIndex(kept)
+  return kept.map(toWire)
+}
+
+/** Remove one entry (and its image files). */
+export async function removeHistory(id: string): Promise<HistoryEntry[]> {
+  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 clearHistory(): Promise<HistoryEntry[]> {
+  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 readHistoryImage(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

@@ -0,0 +1,139 @@
+/**
+ * dsh-imagegen — host half. Mounts the plugin's settings section (api_url /
+ * api_key on the host settings seam), the /api/dsh-imagegen route family
+ * (loopback-only settings bridge + image-generation proxy that keeps the API
+ * key host-side), and a system-prompt announcement. The browser half
+ * (./client) renders the sidebar entry and the split-pane generation studio.
+ */
+
+import type { Context } from '@deepseek-ai/cordis'
+import { installSettingsSection, settingsNamespace } from '@deepseek-ai/dsh-settings'
+import z from 'schemastery'
+// Type-only: pulls the webServer Context merge (route registration).
+import type {} from '@deepseek-ai/dsh-host-webserver'
+// Type-only: pulls the systemPrompt Context merge (announcement section).
+import type {} from '@deepseek-ai/dsh-system-prompt'
+import { IMAGEGEN_SETTINGS_NAMESPACE } from './protocol.ts'
+import { makeRoutes, type SettingsSeam } from './routes.ts'
+
+/** Stable cordis plugin name. */
+export const name = 'imagegen'
+
+/** Services required before the surfaces can mount. */
+export const inject = ['webServer', 'systemPrompt']
+
+// Internals re-exported for smoke tests and host-side debugging; the plugin
+// contract only requires name / inject / Config / apply.
+export { makeRoutes } from './routes.ts'
+export { generateImage, ImageGenError } from './engine.ts'
+
+/** The branded settings namespace of this plugin (the card edits it). */
+export const ImageGenSettingsNamespace = settingsNamespace(IMAGEGEN_SETTINGS_NAMESPACE)
+
+/** Plugin config, validated by the same-named schemastery schema. */
+export interface Config {
+  /** Master switch for the plugin (routes, prompt section). */
+  enabled?: boolean
+  /** Announce the plugin in every agent's system prompt. */
+  announceToAgent?: boolean
+  /** Base URL of the OpenAI-compatible endpoint, e.g. https://api.openai.com/v1 */
+  apiUrl?: string
+  /** Bearer API key (stored as a secret field on the settings seam). */
+  apiKey?: string
+}
+
+export const Config: z<Config> = z.object({
+  enabled: z.boolean().default(true),
+  announceToAgent: z.boolean().default(true),
+  apiUrl: z.string().default(''),
+  apiKey: z.string().role('secret').default(''),
+})
+
+/** Schema defaults, re-read for hand-built contexts (the loader applies them normally). */
+const DEFAULT_ENABLED = true
+const DEFAULT_ANNOUNCE = true
+
+/** Order of the announcement section within the tool-guidance band. */
+const SECTION_ORDER = 150
+
+/** Model-facing announcement: plugin presence, capabilities, and limits. */
+export const IMAGEGEN_GUIDANCE = '本机已安装 dsh-imagegen 插件（DSH AI 生图）：侧边栏「AI 生图」入口；本地插件（源码位于 E:\\dsh-plugin，独立于 dsh-web-ui 插件全家桶）。能力：对接 OpenAI 兼容图像生成 API（模型 gpt-image-2），支持文生图（/images/generations）与图生图（/images/edits，上传参考图）；API 地址与密钥在 GUI「设置 → 插件 → 可配置」中配置，密钥仅存于本机设置文档；生成请求由本地宿主代理转发，结果以 base64 返回面板，可预览与下载。限制：生成消耗上游 API 额度；图片内容由上游模型生成，可能不符合预期或包含不适宜内容；api_key 以明文存储在设置文档中；参考图会发送至所配置的 API 服务。用户提到「生图 / 绘画 / 生成图片 / gpt-image-2 / 文生图 / 图生图」时即指本插件，请据此协作。'
+
+/** Effective config (schema defaults applied). */
+interface EffectiveConfig {
+  enabled: boolean
+  announceToAgent: boolean
+  apiUrl: string
+  apiKey: string
+}
+
+/**
+ * Mount the settings section, routes, and announcement.
+ * @param ctx - host plugin context carrying webServer/systemPrompt.
+ * @param config - resolved plugin config (schema defaults applied by the loader).
+ */
+export function apply(ctx: Context, config?: Config): void {
+  // The live source the surfaces read: the settings section once the settings
+  // service is attached, the composition entry otherwise.
+  let current: () => Config = () => config ?? {}
+  const resolve = (): EffectiveConfig => {
+    const value = current()
+    return {
+      enabled: value.enabled ?? DEFAULT_ENABLED,
+      announceToAgent: value.announceToAgent ?? DEFAULT_ANNOUNCE,
+      apiUrl: value.apiUrl ?? '',
+      apiKey: value.apiKey ?? '',
+    }
+  }
+
+  // The route family mounts once, gated on the settings seam (the bridge
+  // serves it; without the seam there is nothing to expose). Route handlers
+  // read resolve() per request, so config edits apply live. The settings
+  // bridge deliberately keeps serving while the plugin is disabled — it is
+  // how the user re-enables the plugin from the settings card.
+  ctx.inject(['settings'], (sctx) => {
+    const seam = sctx.get('settings') as unknown as SettingsSeam
+    sctx.effect(
+      () => {
+        const routes = makeRoutes({
+          settings: seam,
+          resolve: () => {
+            const value = resolve()
+            return { apiUrl: value.apiUrl, apiKey: value.apiKey }
+          },
+        })
+        const disposers = routes.map(route => ctx.webServer.register(route))
+        return () => { for (const dispose of disposers) dispose() }
+      },
+      'dsh-imagegen: routes',
+    )
+  })
+
+  // System-prompt announcement (toggled by settings changes).
+  let disposeSection: (() => void) | undefined
+  const sync = (): void => {
+    if (disposeSection !== undefined) {
+      disposeSection()
+      disposeSection = undefined
+    }
+    const value = resolve()
+    if (!value.enabled || !value.announceToAgent) return
+    disposeSection = ctx.systemPrompt.section({
+      name: 'plugin:dsh-imagegen',
+      order: SECTION_ORDER,
+      text: IMAGEGEN_GUIDANCE,
+    })
+  }
+
+  installSettingsSection(ctx, ImageGenSettingsNamespace, Config, config ?? {}, {
+    setSource: (source) => {
+      current = source
+      sync()
+    },
+    onChange: sync,
+  })
+
+  // Initial registration from the composition entry (covers deployments with
+  // no settings service, whose installSettingsSection never fires its hooks).
+  sync()
+}

package/src/protocol.ts

@@ -0,0 +1,118 @@
+/**
+ * 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.
+ */
+
+/** Settings namespace this plugin owns (host settings seam + bridge). */
+export const IMAGEGEN_SETTINGS_NAMESPACE = 'dsh-imagegen'
+
+/** Same-origin route family (loopback-only, mirroring the dsh-ssh fence). */
+export const SETTINGS_API = {
+  describe: '/api/dsh-imagegen/settings/describe',
+  mutate: '/api/dsh-imagegen/settings/mutate',
+} as const
+
+/** The image-generation proxy route. */
+export const GENERATE_API = '/api/dsh-imagegen/generate'
+
+/**
+ * Same-origin route family for the host-persisted generation history. Images
+ * live as files under ~/.dsh/dsh-imagegen/images/ and are served back through
+ * the `image` prefix route, so list responses carry metadata only (never
+ * base64) and the browser loads thumbnails/previews lazily.
+ */
+export const HISTORY_API = {
+  list: '/api/dsh-imagegen/history/list',
+  append: '/api/dsh-imagegen/history/append',
+  remove: '/api/dsh-imagegen/history/remove',
+  clear: '/api/dsh-imagegen/history/clear',
+  image: '/api/dsh-imagegen/history/image',
+} as const
+
+/** Maximum number of history entries retained host-side (oldest evicted). */
+export const HISTORY_MAX = 50
+
+/** Generation modes. */
+export type GenerateMode = 'text' | 'edit'
+
+/** 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
+  /** Upstream model name, e.g. gpt-image-2. */
+  model: string
+  /** The prompt (up to 2000 chars in the UI). */
+  prompt: string
+  /** Canvas size: 'auto' or a pixel size like '1024x1024'. */
+  size: string
+  /** Quality: 'auto' | 'low' | 'medium' | 'high'. */
+  quality: string
+  /** Number of images, 1-4. */
+  n: number
+  /**
+   * Passthrough detail parameter: '' (omit), 'standard', or 'high'. Some
+   * gpt-image-2 gateways expose it; official OpenAI endpoints reject unknown
+   * parameters, so the UI defaults to '' (omit).
+   */
+  detail: string
+  /** Reference image as a data URL (edit mode only). */
+  image?: string
+}
+
+/** One generated image, normalized host-side to base64 so the browser never
+ *  has to fetch the upstream (no CORS, no key exposure). */
+export interface GeneratedImage {
+  /** Raw base64 payload (no data: prefix). */
+  b64: string
+  /** MIME type of the payload, e.g. image/png. */
+  mime: string
+  /** Upstream revised prompt, when provided. */
+  revisedPrompt?: string
+}
+
+/** Successful generate outcome. */
+export interface GenerateResult {
+  images: GeneratedImage[]
+}
+
+/** One history image reference as the browser consumes it (a served URL). */
+export interface HistoryImageRef {
+  /** Same-origin URL: `${HISTORY_API.image}/<file>`. */
+  url: string
+  /** MIME type, e.g. image/png. */
+  mime: string
+  /** Upstream revised prompt, when provided. */
+  revisedPrompt?: string
+}
+
+/** A saved generation as the browser consumes it (metadata + served images). */
+export interface HistoryEntry {
+  id: string
+  createdAt: number
+  mode: GenerateMode
+  model: string
+  prompt: string
+  size: string
+  quality: string
+  detail: string
+  n: number
+  images: HistoryImageRef[]
+  /** Reference-image filename (edit mode), kept for display only. */
+  refName?: string
+}
+
+/** A history entry the client submits for persistence (images still carry base64). */
+export interface HistoryEntryInput {
+  id: string
+  createdAt: number
+  mode: GenerateMode
+  model: string
+  prompt: string
+  size: string
+  quality: string
+  detail: string
+  n: number
+  images: GeneratedImage[]
+  refName?: string
+}