@dsh-plus/image-studio 0.1.0

package/src/dto.ts

@@ -0,0 +1,87 @@
+/**
+ * 传输对象（DTO）：HTTP 端点 wire 类型，前后端共享
+ * （浏览器半 import type 消费，构建期零运行时依赖）。
+ * @module image-studio/dto
+ */
+
+import type { ParamPresetEntry, PromptPresetEntry, ProviderPresetEntry } from './config.ts'
+import type { GalleryItem } from './gallery/store.ts'
+import type { ImageEndpoint } from './provider/types.ts'
+import type { TaskState } from './task/runner.ts'
+
+/** 任务提交请求体。 */
+export interface GenerateRequest {
+  /** 提供商预设 id 与 inline 二选一（都传时 inline 优先）。 */
+  providerPresetId?: string
+  /** inline 提供商（无预设直发；apiKey 走同 preset 凭据通道）。 */
+  inlineProvider?: {
+    protocol: string
+    baseUrl: string
+    model: string
+  }
+  endpoint: ImageEndpoint
+  prompt: string
+  /** 参数预设 id（先应用，再被 paramSpecs 覆盖）。 */
+  paramPresetId?: string
+  /** 参数覆盖表（同 ParamSpecMap 形态）。 */
+  paramSpecs?: Record<string, { enabled: boolean; value?: unknown }>
+  /** 图生图源图（本画廊 imageId；edit 必填 ≥1）。 */
+  sourceIds?: string[]
+  /** 可选 PNG mask（本画廊 imageId）。 */
+  maskId?: string
+}
+
+/** 任务记录 wire 视图。 */
+export interface TaskWire {
+  id: string
+  state: TaskState
+  endpoint: ImageEndpoint
+  model: string
+  promptPreview: string
+  createdAt: string
+  startedAt: string | null
+  finishedAt: string | null
+  error: string | null
+  /** 成功时指向画廊条目 id。 */
+  galleryItemId: string | null
+}
+
+/** 任务提交应答。 */
+export interface GenerateAccepted {
+  taskId: string
+}
+
+/** 画廊删除/查询应答。 */
+export interface GalleryListWire {
+  items: GalleryItem[]
+  total: number
+}
+
+/** 凭据状态（describe 投影，永不回传值）。 */
+export interface CredentialStatusWire {
+  credentialRef: string
+  configured: boolean
+}
+
+/** providers 端点应答：协议 registry + 参数目录（前端表单依据）。 */
+export interface ProvidersWire {
+  protocols: Array<{ id: string; label: string; endpoints: ImageEndpoint[] }>
+  params: Array<{
+    key: string
+    kind: string
+    values?: readonly string[]
+    min?: number
+    max?: number
+    applies: ImageEndpoint[]
+    generation: string
+    advanced: boolean
+    description: string
+  }>
+}
+
+/** 预设三组（settings 快照投影）。 */
+export interface PresetsWire {
+  promptPresets: PromptPresetEntry[]
+  paramPresets: ParamPresetEntry[]
+  providerPresets: ProviderPresetEntry[]
+}

package/src/errors.ts

@@ -0,0 +1,47 @@
+/**
+ * 插件内可识别错误：消息即结构化错误码，端点与任务层按码映射 HTTP 状态。
+ * @module image-studio/errors
+ */
+
+/** 全部错误码（封闭集合，新增协议/端点行为时按需扩充）。 */
+export const ERROR_CODES = [
+  'unknown-protocol',
+  'unknown-endpoint',
+  'invalid-request',
+  'unknown-source',
+  'unknown-task',
+  'task-not-runnable',
+  'credential-unavailable',
+  'settings-unavailable',
+  'provider-error',
+] as const
+
+export type ErrorCode = (typeof ERROR_CODES)[number]
+
+export class ImageStudioError extends Error {
+  readonly code: ErrorCode
+
+  constructor(code: ErrorCode, message?: string) {
+    super(message ?? code)
+    this.name = 'ImageStudioError'
+    this.code = code
+  }
+}
+
+/** 按错误码映射 HTTP 状态（端点边界统一使用）。 */
+export function statusOfCode(code: string): number {
+  switch (code) {
+    case 'unknown-protocol':
+    case 'unknown-endpoint':
+    case 'invalid-request':
+    case 'unknown-source':
+    case 'unknown-task':
+    case 'task-not-runnable':
+      return 400
+    case 'credential-unavailable':
+    case 'settings-unavailable':
+      return 409
+    default:
+      return 500
+  }
+}

package/src/gallery/store.ts

@@ -0,0 +1,172 @@
+/**
+ * 画廊存储：元数据 JSONL（追加）+ 图片落盘（原子写）。
+ * 元数据记录完整请求参数与提示词（二次编辑回放依据）；
+ * sourceIds 记录图生图衍生链。落点遵循《插件存储规范》：
+ * $DSH_HOME/dsh-plus/image-studio/gallery/{index.jsonl, images/}
+ * @module image-studio/gallery/store
+ */
+
+import { randomUUID } from 'node:crypto'
+import { appendFile, mkdir, readdir, readFile, rename, rm, writeFile } from 'node:fs/promises'
+import { join } from 'node:path'
+
+import { pluginDataPath } from '@dsh-plus/shared'
+import type { ImageEndpoint } from '../provider/types.ts'
+
+/** 画廊条目元数据（DTO 主体，端点原样投影）。 */
+export interface GalleryItem {
+  id: string
+  createdAt: string
+  /** 提供商预设 id（inline 请求时为 null）。 */
+  providerPresetId: string | null
+  protocol: string
+  endpoint: ImageEndpoint
+  model: string
+  /** 用户输入提示词（原样，非 revised）。 */
+  prompt: string
+  /** 全部启用的请求参数（请求体快照，含 response_format 等）。 */
+  params: Record<string, unknown>
+  /** 结果图 id 列表（images/<imageId>.<ext>）。 */
+  imageIds: string[]
+  /** 每张图的 revised_prompt（与 imageIds 对齐，可为 null）。 */
+  revisedPrompts: Array<string | null>
+  /** 图生图源图（本画廊内的 imageId）；文生图为空。 */
+  sourceIds: string[]
+}
+
+/**
+ * 存储层根路径（惰性解析：DSH_HOME 可能在模块加载后才被测试/dev 环境设置）。
+ */
+function galleryRoot(): string {
+  return pluginDataPath('image-studio', 'gallery')
+}
+
+function indexFile(): string {
+  return join(galleryRoot(), 'index.jsonl')
+}
+
+function imagesDir(): string {
+  return join(galleryRoot(), 'images')
+}
+
+/** 图片扩展名由 MIME 推导（仅白名单格式）。 */
+export function extOfMime(mime: string): string {
+  switch (mime) {
+    case 'image/jpeg':
+      return 'jpg'
+    case 'image/webp':
+      return 'webp'
+    default:
+      return 'png'
+  }
+}
+
+/** 确保目录存在。 */
+async function ensureDirs(): Promise<void> {
+  await mkdir(imagesDir(), { recursive: true })
+}
+
+/** 解析 JSONL 全量元数据（坏行跳过并告警；空文件返回空表）。 */
+export async function loadGallery(log: (message: string) => void): Promise<GalleryItem[]> {
+  let text: string
+  try {
+    text = await readFile(indexFile(), 'utf8')
+  } catch {
+    return []
+  }
+  const items: GalleryItem[] = []
+  for (const line of text.split('\n')) {
+    if (line.trim().length === 0) continue
+    try {
+      items.push(JSON.parse(line) as GalleryItem)
+    } catch {
+      log(`画廊元数据坏行跳过：${line.slice(0, 80)}`)
+    }
+  }
+  return items
+}
+
+/** 追加一条元数据（JSONL 原子性：单行小写入）。 */
+async function appendIndex(item: GalleryItem): Promise<void> {
+  await ensureDirs()
+  await appendFile(indexFile(), `${JSON.stringify(item)}\n`, 'utf8')
+}
+
+/** 图片文件绝对路径。 */
+function imagePathOf(imageId: string, ext: string): string {
+  if (!/^[a-f0-9-]{36}$/.test(imageId) || !/^[a-z0-9]{2,4}$/.test(ext)) {
+    throw new Error(`非法画廊图片标识：${imageId}.${ext}`)
+  }
+  return join(imagesDir(), `${imageId}.${ext}`)
+}
+
+/** 读取图片字节（未知 id 抛错由调用方映射 404）。 */
+export async function readImageBytes(imageId: string): Promise<{ data: Uint8Array; ext: string }> {
+  const files = await readdir(imagesDir()).catch(() => [] as string[])
+  const hit = files.find((name) => name.startsWith(`${imageId}.`))
+  if (hit === undefined) throw new Error(`unknown-image: ${imageId}`)
+  const ext = hit.slice(imageId.length + 1)
+  const data = await readFile(imagePathOf(imageId, ext))
+  return { data: new Uint8Array(data), ext }
+}
+
+/** 画廊新条目：落图片字节 + 追加元数据（一个事务语义，图片先落）。 */
+export async function saveGalleryItem(input: {
+  item: Omit<GalleryItem, 'id' | 'createdAt' | 'imageIds' | 'revisedPrompts'>
+  images: Array<{ data: Uint8Array; mime: string; revisedPrompt: string | null }>
+}): Promise<GalleryItem> {
+  await ensureDirs()
+  const imageIds: string[] = []
+  for (const image of input.images) {
+    const imageId = randomUUID()
+    const ext = extOfMime(image.mime)
+    // 原子写：临时文件 + rename，中断不留半截图片。
+    const target = imagePathOf(imageId, ext)
+    const tmp = `${target}.tmp-${process.pid}-${Date.now()}`
+    await writeFile(tmp, image.data)
+    await rename(tmp, target)
+    imageIds.push(imageId)
+  }
+  const item: GalleryItem = {
+    ...input.item,
+    id: randomUUID(),
+    createdAt: new Date().toISOString(),
+    imageIds,
+    revisedPrompts: input.images.map((image) => image.revisedPrompt),
+  }
+  await appendIndex(item)
+  return item
+}
+
+/** 删除单条：图片文件与 JSONL 行（重写式删除）。 */
+export async function deleteGalleryItem(itemId: string): Promise<boolean> {
+  const items = await loadGallery(() => {})
+  const hit = items.find((item) => item.id === itemId)
+  if (hit === undefined) return false
+  for (const imageId of hit.imageIds) {
+    const files = await readdir(imagesDir()).catch(() => [] as string[])
+    for (const name of files) {
+      if (name.startsWith(`${imageId}.`)) {
+        await rm(join(imagesDir(), name), { force: true })
+      }
+    }
+  }
+  const kept = items.filter((item) => item.id !== itemId)
+  const tmp = `${indexFile()}.tmp-${process.pid}-${Date.now()}`
+  await writeFile(
+    tmp,
+    kept.map((item) => JSON.stringify(item)).join('\n') + (kept.length > 0 ? '\n' : ''),
+    'utf8',
+  )
+  await rename(tmp, indexFile())
+  return true
+}
+
+/** 按 imageId 反查所属条目（二次编辑定位元数据用）。 */
+export async function itemOfImage(
+  imageId: string,
+  log: (message: string) => void,
+): Promise<GalleryItem | null> {
+  const items = await loadGallery(log)
+  return items.find((item) => item.imageIds.includes(imageId)) ?? null
+}

package/src/index.ts

@@ -0,0 +1,44 @@
+/**
+ * dsh 插件：图像工作室。
+ * OpenAI Images 协议文生图/图生图，官方全参数开关化（enabled=false 不进请求），
+ * 双预设体系（提示词/参数/提供商），并发生图任务（FIFO + 可配置上限），
+ * 画廊持久化（元数据 JSONL + 图片落盘）与二次编辑链（sourceIds）。
+ * 服务经 ctx.imageStudio 暴露；前端接口见 docs/README.md「前端接入点」。
+ * @module @dsh-plus/image-studio
+ */
+import type { Context } from '@deepseek-ai/cordis'
+
+import { Config, type ImageStudioConfig } from './config.ts'
+import { ImageStudioService } from './service.ts'
+
+export const name = 'dsh-plus-image-studio'
+
+export const inject = ['credentials'] as const
+
+export { credentialRefNameOf, isValidPresetId } from './credentials.ts'
+export type {
+  CredentialStatusWire,
+  GalleryListWire,
+  GenerateRequest,
+  PresetsWire,
+  ProvidersWire,
+  TaskWire,
+} from './dto.ts'
+export { type ErrorCode, ImageStudioError } from './errors.ts'
+export type { GalleryItem } from './gallery/store.ts'
+export type { ParamEntry } from './params/catalog.ts'
+export { PARAM_CATALOG, paramEntryOf, paramKeysFor } from './params/catalog.ts'
+export type { ParamSpec, ParamSpecMap } from './params/spec.ts'
+export { normalizeParamSpecs, ParamValidationError, validateParamSpecs } from './params/spec.ts'
+export { ImageStudioService } from './service.ts'
+export { Config }
+
+declare module '@deepseek-ai/cordis' {
+  interface Context {
+    imageStudio: ImageStudioService
+  }
+}
+
+export function apply(ctx: Context, config: ImageStudioConfig): void {
+  ctx.plugin(ImageStudioService, config)
+}

package/src/ns.ts

@@ -0,0 +1,7 @@
+/**
+ * settings 命名空间字面量（纯常量，零依赖，浏览器半可安全引入）。
+ * 服务端直接以字面量注册（settings 编译期校验命名空间语法，见 config.ts），
+ * 浏览器半将其作为 settings.plugin.item keyed 槽位的 key（配置卡片）。
+ * @module image-studio/ns
+ */
+export const SETTINGS_NS = 'dsh-plus-image-studio'

package/src/params/catalog.ts

@@ -0,0 +1,184 @@
+/**
+ * 官方 Images API 全参数目录（单一事实源）。
+ * 覆盖官方全集（generations + edits 通用、edit 专属、legacy 代际）；
+ * 各中转支持的子集不同（如 PackyAPI 不支持 stream），由用户按需启用，
+ * 目录不做子集裁剪。前端表单/校验据此目录动态生成。
+ * 纯数据 + 纯函数，零依赖，浏览器半可安全引入。
+ * @module image-studio/params/catalog
+ */
+import type { ImageEndpoint } from '../provider/types.ts'
+
+/** 参数值类型（校验与前端控件形态的依据）。 */
+export type ParamKind = 'string' | 'integer' | 'enum' | 'boolean'
+
+/** 单个参数的目录条目。 */
+export interface ParamEntry {
+  /** 请求体字段名（官方 API 参数名）。 */
+  key: string
+  /** 值类型。 */
+  kind: ParamKind
+  /** enum 类型时的合法取值。 */
+  values?: readonly string[]
+  /** integer 时的下界（含）。 */
+  min?: number
+  /** integer 时的上界（含）。 */
+  max?: number
+  /** 适用端点（new-array 是目录实现细节，不外泄）。 */
+  applies: readonly ImageEndpoint[]
+  /** 适用模型代际：current（GPT Image）| dall-e-3 | dall-e-2 | all。 */
+  generation: 'current' | 'dall-e-3' | 'dall-e-2' | 'all'
+  /** 默认关闭（中转不兼容或旧代际专用，显式启用才发送）。 */
+  advanced: boolean
+  /** 中文说明（面向用户的简述）。 */
+  description: string
+}
+
+/** 目录键序即文档序（prompt/model/n 常用在前）。 */
+const CATALOG_RAW: readonly ParamEntry[] = [
+  {
+    key: 'model',
+    kind: 'string',
+    applies: ['generation', 'edit'],
+    generation: 'all',
+    advanced: false,
+    description: '图像模型 id；请求基础来自提供商预设，此处仅作展示与 inline 覆盖',
+  },
+  {
+    key: 'n',
+    kind: 'integer',
+    min: 1,
+    max: 10,
+    applies: ['generation', 'edit'],
+    generation: 'current',
+    advanced: false,
+    description: '生成张数（1-10；部分中转仅支持 1）',
+  },
+  {
+    key: 'size',
+    kind: 'string',
+    applies: ['generation', 'edit'],
+    generation: 'current',
+    advanced: false,
+    description:
+      '尺寸，如 1024x1024 / 1536x1024 / 1024x1536 / auto；宽高需为 16 的倍数、最大边 ≤3840、比例 ≤3:1（依模型限制）',
+  },
+  {
+    key: 'quality',
+    kind: 'enum',
+    values: ['auto', 'low', 'medium', 'high'],
+    applies: ['generation', 'edit'],
+    generation: 'current',
+    advanced: false,
+    description: '质量档位',
+  },
+  {
+    key: 'background',
+    kind: 'enum',
+    values: ['auto', 'transparent', 'opaque'],
+    applies: ['generation', 'edit'],
+    generation: 'current',
+    advanced: false,
+    description: '输出背景透明行为（对提示词里的场景背景无影响）',
+  },
+  {
+    key: 'output_format',
+    kind: 'enum',
+    values: ['png', 'jpeg', 'webp'],
+    applies: ['generation', 'edit'],
+    generation: 'current',
+    advanced: false,
+    description: '输出格式（部分中转不支持 webp）',
+  },
+  {
+    key: 'output_compression',
+    kind: 'integer',
+    min: 0,
+    max: 100,
+    applies: ['generation', 'edit'],
+    generation: 'current',
+    advanced: true,
+    description: '压缩率 0-100，仅 jpeg/webp 有效',
+  },
+  {
+    key: 'moderation',
+    kind: 'enum',
+    values: ['auto', 'low'],
+    applies: ['generation', 'edit'],
+    generation: 'current',
+    advanced: true,
+    description: '内容审核严格度',
+  },
+  {
+    key: 'response_format',
+    kind: 'enum',
+    values: ['url', 'b64_json'],
+    applies: ['generation', 'edit'],
+    generation: 'all',
+    advanced: false,
+    description: '返回形式；插件两种都会落盘本地化，画廊不受外链过期影响',
+  },
+  {
+    key: 'stream',
+    kind: 'boolean',
+    applies: ['generation', 'edit'],
+    generation: 'current',
+    advanced: true,
+    description: '流式返回（多数中转不支持，默认关闭）',
+  },
+  {
+    key: 'partial_images',
+    kind: 'integer',
+    min: 0,
+    max: 3,
+    applies: ['generation', 'edit'],
+    generation: 'current',
+    advanced: true,
+    description: '流式中间图数量（依赖 stream，默认关闭）',
+  },
+  {
+    key: 'user',
+    kind: 'string',
+    applies: ['generation', 'edit'],
+    generation: 'all',
+    advanced: true,
+    description: '终端用户标识（业务归因用）',
+  },
+  {
+    key: 'input_fidelity',
+    kind: 'enum',
+    values: ['low', 'high'],
+    applies: ['edit'],
+    generation: 'current',
+    advanced: false,
+    description: '图生图输入保真度（high 更保留原图细节，token 消耗增大）',
+  },
+  {
+    key: 'style',
+    kind: 'enum',
+    values: ['vivid', 'natural'],
+    applies: ['generation'],
+    generation: 'dall-e-3',
+    advanced: true,
+    description: 'dall-e-3 代际风格参数（GPT Image 不需要）',
+  },
+] as const
+
+/** 只读目录（冻结防运行期篡改）。 */
+export const PARAM_CATALOG: readonly ParamEntry[] = Object.freeze(
+  CATALOG_RAW.map((entry) => Object.freeze(entry)),
+)
+
+/** 按字段名查目录条目。 */
+export function paramEntryOf(key: string): ParamEntry | null {
+  return PARAM_CATALOG.find((entry) => entry.key === key) ?? null
+}
+
+/** 某端点下可用的参数键集合（含 advanced）。 */
+export function paramKeysFor(endpoint: ImageEndpoint): readonly string[] {
+  return PARAM_CATALOG.filter((entry) => entry.applies.includes(endpoint)).map((entry) => entry.key)
+}
+
+/** 官方 API 对指定参数是否本就不发送（由请求基础或输入承载）。 */
+export function isHostParam(key: string): boolean {
+  return key === 'model'
+}

package/src/params/spec.ts

@@ -0,0 +1,109 @@
+/**
+ * 参数开关/自定义模型（ParamSpec）与归一化裁剪纯函数。
+ * 每参数：enabled=false 不进请求（用上游默认值）；value 覆盖目录默认。
+ * 校验只在系统边界（api.ts）执行；内部基于契约信任。
+ * @module image-studio/params/spec
+ */
+import type { ImageEndpoint } from '../provider/types.ts'
+import { paramEntryOf } from './catalog.ts'
+
+/** 单参数的开关 + 自定义值。 */
+export interface ParamSpec {
+  enabled: boolean
+  value?: unknown
+}
+
+/** 端点 → 该端点参数表。 */
+export type ParamSpecMap = Record<string, ParamSpec>
+
+/** 归一化失败原因（边界校验用，端点转 invalid-request）。 */
+export class ParamValidationError extends Error {
+  readonly key: string
+
+  constructor(key: string, message: string) {
+    super(`参数 ${key} ${message}`)
+    this.name = 'ParamValidationError'
+    this.key = key
+  }
+}
+
+/** 校验单个值符合目录条目约束；返回规范值。 */
+export function validateParamValue(key: string, value: unknown): unknown {
+  const entry = paramEntryOf(key)
+  if (entry === null) throw new ParamValidationError(key, '不在参数目录中')
+  switch (entry.kind) {
+    case 'string':
+      if (typeof value !== 'string' || value.length === 0) {
+        throw new ParamValidationError(key, '必须是非空字符串')
+      }
+      return value
+    case 'enum':
+      if (typeof value !== 'string' || !entry.values?.includes(value)) {
+        throw new ParamValidationError(key, `必须是 ${entry.values?.join(' | ') ?? '枚举值'} 之一`)
+      }
+      return value
+    case 'integer': {
+      if (typeof value !== 'number' || !Number.isInteger(value)) {
+        throw new ParamValidationError(key, '必须是整数')
+      }
+      if (entry.min !== undefined && value < entry.min) {
+        throw new ParamValidationError(key, `不能小于 ${entry.min}`)
+      }
+      if (entry.max !== undefined && value > entry.max) {
+        throw new ParamValidationError(key, `不能大于 ${entry.max}`)
+      }
+      return value
+    }
+    case 'boolean':
+      if (typeof value !== 'boolean') throw new ParamValidationError(key, '必须是布尔值')
+      return value
+  }
+}
+
+/**
+ * 校验并归一化一份参数表：仅保留启用且适用于该端点的参数；
+ * model 是请求基础（提供商预设承载），不计入协议参数表。
+ * 任何禁用/未知/越界项直接抛 ParamValidationError（边界 fail-loud）。
+ */
+export function normalizeParamSpecs(
+  specs: ParamSpecMap,
+  endpoint: ImageEndpoint,
+): Record<string, unknown> {
+  const out: Record<string, unknown> = {}
+  for (const [key, spec] of Object.entries(specs)) {
+    if (!spec?.enabled) continue
+    if (key === 'model') continue
+    const entry = paramEntryOf(key)
+    if (entry === null) throw new ParamValidationError(key, '不在参数目录中')
+    if (!entry.applies.includes(endpoint)) {
+      throw new ParamValidationError(key, `不适用于 ${endpoint} 端点`)
+    }
+    out[key] = validateParamValue(key, spec.value)
+  }
+  return out
+}
+
+/** 校验预设里的参数表（结构合法但可跨端点；应用时再按端点归一化）。 */
+export function validateParamSpecs(specs: unknown): ParamSpecMap {
+  if (specs === null || typeof specs !== 'object' || Array.isArray(specs)) {
+    throw new ParamValidationError('(整体)', '必须是对象')
+  }
+  const out: ParamSpecMap = {}
+  for (const [key, raw] of Object.entries(specs as Record<string, unknown>)) {
+    if (raw === null || typeof raw !== 'object') {
+      throw new ParamValidationError(key, '条目必须是 { enabled, value? }')
+    }
+    const spec = raw as { enabled?: unknown; value?: unknown }
+    if (typeof spec.enabled !== 'boolean') {
+      throw new ParamValidationError(key, 'enabled 必须是布尔值')
+    }
+    const entry = paramEntryOf(key)
+    if (entry === null) throw new ParamValidationError(key, '不在参数目录中')
+    const item: ParamSpec = { enabled: spec.enabled }
+    if (spec.value !== undefined) {
+      item.value = validateParamValue(key, spec.value)
+    }
+    out[key] = item
+  }
+  return out
+}