@dsh-plus/image-studio 0.1.0

package/src/service.ts

@@ -0,0 +1,458 @@
+/**
+ * image-studio 服务主体：
+ * - settings installSection（三组预设 + 并发/超时/代理/画廊上限）；
+ * - TaskRunner 并发生图：提交即排队，成功自动入画廊（元数据 + 图片落盘）；
+ * - 提供商预设按 id 即时 resolve credentials（不缓存）；
+ * - 端点：generate/tasks/gallery/images/credentials/providers（api.ts 注册）。
+ * 红线：开发测试仅指向本地 mock，严禁真实调用产生费用。
+ * @module image-studio/service
+ */
+import { type Context, Service } from '@deepseek-ai/cordis'
+import { credentialRef } from '@deepseek-ai/dsh-credentials'
+import type {} from '@deepseek-ai/dsh-settings'
+import { registerImageStudioApi } from './api.ts'
+import {
+  type ImageStudioConfig,
+  type ParamPresetEntry,
+  type PromptPresetEntry,
+  type ProviderPresetEntry,
+  SETTINGS_NS,
+} from './config.ts'
+import { credentialRefNameOf, isValidPresetId } from './credentials.ts'
+import type { GenerateRequest, TaskWire } from './dto.ts'
+import { ImageStudioError } from './errors.ts'
+import type { GalleryItem } from './gallery/store.ts'
+import {
+  loadGallery,
+  readImageBytes,
+  deleteGalleryItem as removeGalleryItem,
+  saveGalleryItem,
+} from './gallery/store.ts'
+import type { ParamSpecMap } from './params/spec.ts'
+import { normalizeParamSpecs, validateParamSpecs } from './params/spec.ts'
+import { createProvider } from './provider/registry.ts'
+import type { ImageEndpoint, InputImage, ProviderTarget } from './provider/types.ts'
+import type { TaskRecord } from './task/runner.ts'
+import { TaskRunner } from './task/runner.ts'
+
+interface SettingsLike {
+  installSection(
+    ownerCtx: Context,
+    ns: string,
+    schema: unknown,
+    base: unknown,
+    hooks: { setSource(source: () => unknown): void; onChange(): void },
+  ): void
+}
+
+/** credentials seam 最小面（真实服务经 inject 探测获取）。 */
+interface CredentialsFace {
+  resolve(ref: unknown): Promise<{ value: string; source: string } | undefined>
+  describe(ref: unknown): Promise<{ configured: boolean }>
+  set(ref: unknown, value: string): Promise<void>
+  unset(ref: unknown): Promise<void>
+}
+
+/** 提交时的请求摘要（任务快照）。 */
+interface TaskSnapshot {
+  endpoint: ImageEndpoint
+  model: string
+  prompt: string
+}
+
+/** 单任务成功产物（TaskRunner result 槽）。 */
+interface TaskOutcome {
+  galleryItemId: string
+}
+
+export class ImageStudioService extends Service {
+  private current: () => ImageStudioConfig
+  private readonly runner: TaskRunner<TaskSnapshot>
+  private readonly log: (message: string) => void
+
+  constructor(ctx: Context, config: ImageStudioConfig) {
+    super(ctx, 'imageStudio')
+    this.current = () => config
+    this.log = (message) => ctx.logger('image-studio').warn(message)
+    this.runner = new TaskRunner<TaskSnapshot>({ maxConcurrent: config.maxConcurrent })
+    ctx.inject(['settings'], (settingsCtx) => {
+      this.settingsRef = settingsCtx.settings as unknown as SettingsLike
+      settingsCtx.settings.installSection(ctx, SETTINGS_NS, configSchemaRef, config, {
+        setSource: (source) => {
+          this.current = source as () => ImageStudioConfig
+          this.applyConfig()
+        },
+        onChange: () => {},
+      })
+    })
+    ctx.inject(['webServer'], (webCtx) => {
+      registerImageStudioApi(webCtx as Context, this)
+    })
+  }
+
+  /** 配置热更：并发上限即时生效（进行中任务不受影响）。 */
+  private applyConfig(): void {
+    this.runner.reconfigure(this.current().maxConcurrent)
+  }
+
+  // ---------- 预设读取 ----------
+
+  private promptPresets(): PromptPresetEntry[] {
+    return this.current().promptPresets
+  }
+
+  private paramPresets(): ParamPresetEntry[] {
+    return this.current().paramPresets as ParamPresetEntry[]
+  }
+
+  private providerPresets(): ProviderPresetEntry[] {
+    return this.current().providerPresets as ProviderPresetEntry[]
+  }
+
+  /** 预设快照（端点投影）。 */
+  presets(): {
+    promptPresets: PromptPresetEntry[]
+    paramPresets: ParamPresetEntry[]
+    providerPresets: ProviderPresetEntry[]
+  } {
+    return {
+      promptPresets: this.promptPresets(),
+      paramPresets: this.paramPresets(),
+      providerPresets: this.providerPresets(),
+    }
+  }
+
+  // ---------- 凭据 ----------
+
+  /** describe 单个提供商预设凭据（不回传值）。 */
+  async credentialStatus(
+    presetId: string,
+  ): Promise<{ credentialRef: string; configured: boolean }> {
+    const refName = credentialRefNameOf(presetId)
+    const credentials = await this.credentialsSeam()
+    if (credentials === null) return { credentialRef: refName, configured: false }
+    const info = await credentials.describe(credentialRef(refName))
+    return { credentialRef: refName, configured: info.configured }
+  }
+
+  /** set/unset 凭据（端点写通道）。 */
+  async setCredential(presetId: string, value: string): Promise<void> {
+    const credentials = await this.requireCredentials()
+    await credentials.set(credentialRef(credentialRefNameOf(presetId)), value)
+  }
+
+  async unsetCredential(presetId: string): Promise<void> {
+    const credentials = await this.requireCredentials()
+    await credentials.unset(credentialRef(credentialRefNameOf(presetId)))
+  }
+
+  /** credentials seam 可选探测（缺席返回 null）。 */
+  private async credentialsSeam(): Promise<CredentialsFace | null> {
+    const found = (this.ctx as unknown as { get?(key: 'credentials'): unknown }).get?.(
+      'credentials',
+    )
+    return found === undefined || found === null ? null : (found as CredentialsFace)
+  }
+
+  private async requireCredentials(): Promise<CredentialsFace> {
+    const seam = await this.credentialsSeam()
+    if (seam === null) throw new ImageStudioError('credential-unavailable')
+    return seam
+  }
+
+  // ---------- 生图任务 ----------
+
+  /** 提交生图任务：校验 → 入队 → 返回 taskId。 */
+  async submitGenerate(request: GenerateRequest): Promise<string> {
+    const snapshot = await this.prepareTask(request)
+    const summary: TaskSnapshot = {
+      endpoint: snapshot.endpoint,
+      model: snapshot.target.model,
+      prompt: snapshot.prompt,
+    }
+    const record = this.runner.submit(summary, (signal) => this.executeTask(snapshot, signal))
+    return record.id
+  }
+
+  /** 单任务查询（wire 投影）。 */
+  taskWire(id: string): TaskWire | null {
+    const record = this.runner.get(id)
+    return record === null ? null : this.toTaskWire(record)
+  }
+
+  /** 任务列表（最新在前）。 */
+  taskWires(): TaskWire[] {
+    return this.runner
+      .list()
+      .reverse()
+      .map((record) => this.toTaskWire(record))
+  }
+
+  /** 取消任务。 */
+  cancelTask(id: string): boolean {
+    return this.runner.cancel(id)
+  }
+
+  private toTaskWire(record: TaskRecord<TaskSnapshot>): TaskWire {
+    const outcome = record.result as TaskOutcome | null
+    return {
+      id: record.id,
+      state: record.state,
+      endpoint: record.snapshot.endpoint,
+      model: record.snapshot.model,
+      promptPreview: record.snapshot.prompt.slice(0, 120),
+      createdAt: record.createdAt,
+      startedAt: record.startedAt,
+      finishedAt: record.finishedAt,
+      error: record.error,
+      galleryItemId:
+        record.state === 'succeeded' && outcome !== null ? outcome.galleryItemId : null,
+    }
+  }
+
+  /**
+   * 任务准备（边界校验集中地）：提供商预设/inline → target；
+   * 参数预设 + 覆盖 → 归一化参数表；sourceIds → 输入图字节。
+   */
+  private async prepareTask(request: GenerateRequest): Promise<{
+    target: ProviderTarget
+    endpoint: ImageEndpoint
+    prompt: string
+    n: number
+    images: InputImage[]
+    mask: InputImage | null
+    params: Record<string, unknown>
+    sourceIds: string[]
+  }> {
+    const target = await this.resolveTarget(request)
+    const endpoint = request.endpoint
+    if (endpoint !== 'generation' && endpoint !== 'edit') {
+      throw new ImageStudioError('invalid-request', `未知端点：${String(endpoint)}`)
+    }
+    if (typeof request.prompt !== 'string' || request.prompt.trim().length === 0) {
+      throw new ImageStudioError('invalid-request', 'prompt 不能为空')
+    }
+    const params = await this.resolveParams(request, endpoint)
+    const nValue = params.n
+    const n = typeof nValue === 'number' ? nValue : 1
+    const sourceIds = request.sourceIds ?? []
+    const images = await this.loadSourceImages(sourceIds, endpoint)
+    const mask = request.maskId !== undefined ? await this.loadMask(request.maskId) : null
+    return {
+      target,
+      endpoint,
+      prompt: request.prompt,
+      n,
+      images,
+      mask,
+      params: stripHostParams(params),
+      sourceIds,
+    }
+  }
+
+  /** 提供商预设 / inline → ProviderTarget（凭据即时 resolve）。 */
+  private async resolveTarget(request: GenerateRequest): Promise<ProviderTarget> {
+    const config = this.current()
+    const inline = request.inlineProvider
+    let protocol: string
+    let baseUrl: string
+    let model: string
+    let extraHeaders: Record<string, string> = {}
+    let refName: string
+    if (inline !== undefined) {
+      protocol = inline.protocol
+      baseUrl = inline.baseUrl
+      model = inline.model
+      // inline 无独立凭据：复用 providerPresetId 引用或拒绝。
+      if (request.providerPresetId === undefined) {
+        throw new ImageStudioError(
+          'invalid-request',
+          'inline 提供商必须同时给出 providerPresetId 以定位凭据',
+        )
+      }
+      refName = credentialRefNameOf(request.providerPresetId)
+    } else if (request.providerPresetId !== undefined) {
+      const preset = this.providerPresets().find((item) => item.id === request.providerPresetId)
+      if (preset === undefined) {
+        throw new ImageStudioError('invalid-request', `未知提供商预设：${request.providerPresetId}`)
+      }
+      protocol = preset.protocol
+      baseUrl = preset.baseUrl
+      model = preset.model
+      extraHeaders = preset.extraHeaders ?? {}
+      refName = isValidPresetId(preset.id)
+        ? credentialRefNameOf(preset.id)
+        : credentialRefNameOf(preset.credentialRef)
+    } else {
+      throw new ImageStudioError('invalid-request', '必须提供 providerPresetId 或 inlineProvider')
+    }
+    const apiKey = await this.resolveApiKey(refName)
+    const target: ProviderTarget & { presetId?: string } = {
+      protocol,
+      baseUrl,
+      model,
+      apiKey,
+      extraHeaders,
+      proxy: config.proxy,
+      timeoutMs: config.requestTimeoutMs,
+    }
+    // 预设 id 旁路携带（executeTask 落画廊时补记 providerPresetId）。
+    target.presetId =
+      inline !== undefined ? (request.providerPresetId ?? null) : (request.providerPresetId ?? null)
+    return target
+  }
+
+  /** 凭据解析（每次操作即时 resolve，不缓存）。 */
+  private async resolveApiKey(refName: string): Promise<string> {
+    const credentials = await this.requireCredentials()
+    const resolved = await credentials.resolve(credentialRef(refName))
+    if (resolved === undefined) {
+      throw new ImageStudioError('credential-unavailable', `凭据未配置：${refName}`)
+    }
+    return resolved.value
+  }
+
+  /** 参数预设 + 覆盖合并 → 端点归一化（model 由 target 承载）。 */
+  private async resolveParams(
+    request: GenerateRequest,
+    endpoint: ImageEndpoint,
+  ): Promise<Record<string, unknown>> {
+    let specs: ParamSpecMap = {}
+    if (request.paramPresetId !== undefined) {
+      const preset = this.paramPresets().find((item) => item.id === request.paramPresetId)
+      if (preset === undefined) {
+        throw new ImageStudioError('invalid-request', `未知参数预设：${request.paramPresetId}`)
+      }
+      specs = validateParamSpecs(preset.paramSpecs)
+    }
+    if (request.paramSpecs !== undefined) {
+      specs = { ...specs, ...validateParamSpecs(request.paramSpecs) }
+    }
+    const normalized = normalizeParamSpecs(specs, endpoint)
+    return { model: this.modelOf(request), ...normalized }
+  }
+
+  /** 模型优先级：inline > 提供商预设（参数表中的 model 仅为展示，不参与）。 */
+  private modelOf(request: GenerateRequest): string {
+    return request.inlineProvider?.model ?? this.providerModelOf(request.providerPresetId)
+  }
+
+  private providerModelOf(presetId: string | undefined): string {
+    if (presetId === undefined) return ''
+    return this.providerPresets().find((item) => item.id === presetId)?.model ?? ''
+  }
+
+  /** 源图字节加载（edit ≥1 张；单图上限 50MB 对齐官方）。 */
+  private async loadSourceImages(
+    sourceIds: string[],
+    endpoint: ImageEndpoint,
+  ): Promise<InputImage[]> {
+    if (endpoint === 'generation') return []
+    if (sourceIds.length === 0) {
+      throw new ImageStudioError('invalid-request', 'edit 端点必须提供至少一张源图（sourceIds）')
+    }
+    if (sourceIds.length > 16) {
+      throw new ImageStudioError('invalid-request', '源图最多 16 张（官方 GPT Image 限制）')
+    }
+    const images: InputImage[] = []
+    for (const imageId of sourceIds) {
+      images.push(await this.loadOneImage(imageId))
+    }
+    return images
+  }
+
+  private async loadMask(maskId: string): Promise<InputImage> {
+    return this.loadOneImage(maskId)
+  }
+
+  private async loadOneImage(imageId: string): Promise<InputImage> {
+    try {
+      const { data, ext } = await readImageBytes(imageId)
+      return { data, mime: ext === 'jpg' ? 'image/jpeg' : `image/${ext}` }
+    } catch {
+      throw new ImageStudioError('unknown-source', `源图不存在：${imageId}`)
+    }
+  }
+
+  /** 任务体：调协议适配器 → 成功入画廊。失败向上抛给 TaskRunner 记录。 */
+  private async executeTask(
+    snapshot: Awaited<ReturnType<ImageStudioService['prepareTask']>>,
+    signal: AbortSignal,
+  ): Promise<TaskOutcome> {
+    const provider = createProvider(snapshot.target.protocol)
+    if (!provider.endpoints.includes(snapshot.endpoint)) {
+      throw new ImageStudioError(
+        'unknown-endpoint',
+        `协议 ${provider.id} 不支持端点 ${snapshot.endpoint}`,
+      )
+    }
+    const result = await provider.generate(
+      {
+        target: snapshot.target,
+        endpoint: snapshot.endpoint,
+        prompt: snapshot.prompt,
+        n: snapshot.n,
+        images: snapshot.images,
+        mask: snapshot.mask,
+        params: snapshot.params,
+      },
+      signal,
+    )
+    const item = await saveGalleryItem({
+      item: {
+        providerPresetId: this.presetIdOf(snapshot),
+        protocol: snapshot.target.protocol,
+        endpoint: snapshot.endpoint,
+        model: snapshot.target.model,
+        prompt: snapshot.prompt,
+        params: snapshot.params,
+        sourceIds: snapshot.sourceIds,
+      },
+      images: result.images.map((image) => ({
+        data: image.data,
+        mime: image.mime,
+        revisedPrompt: image.revisedPrompt,
+      })),
+    })
+    return { galleryItemId: item.id }
+  }
+
+  /** 提交时上下文里的预设 id（executeTask 无原请求，经 target 旁路携带）。 */
+  private presetIdOf(snapshot: { target: ProviderTarget }): string | null {
+    return (snapshot.target as ProviderTarget & { presetId?: string }).presetId ?? null
+  }
+
+  // ---------- 画廊 ----------
+
+  /** 画廊列表（全量；分页/过滤由端点层做）。 */
+  async gallery(): Promise<GalleryItem[]> {
+    return loadGallery(this.log)
+  }
+
+  /** 删除画廊条目（图片 + 元数据）。 */
+  async deleteGalleryItem(itemId: string): Promise<boolean> {
+    return removeGalleryItem(itemId)
+  }
+
+  /** 读取图片字节（端点直投流）。 */
+  async imageBytes(imageId: string): Promise<{ data: Uint8Array; ext: string } | null> {
+    try {
+      return await readImageBytes(imageId)
+    } catch {
+      return null
+    }
+  }
+
+  dispose(): void {
+    // 进行中任务随进程终止（AbortController 无需逐一 abort——进程退出即断）。
+  }
+}
+
+/** 静态 schema 引用（installSection 用；避免循环 import config → service）。 */
+import { Config as configSchemaRef } from './config.ts'
+
+/** 剔除 host 承载参数（model 不进协议参数表——openai-images 请求体单独拼）。 */
+function stripHostParams(params: Record<string, unknown>): Record<string, unknown> {
+  const { model: _model, ...rest } = params
+  return rest
+}

package/src/task/runner.ts

@@ -0,0 +1,200 @@
+/**
+ * 生图任务并发执行器：FIFO 队列 + 可配置并发上限（0 = 不限）。
+ * 与业务解耦：任务体是注入的异步函数，本模块只管调度与状态；
+ * 纯调度逻辑可单测（不触网）。
+ * @module image-studio/task/runner
+ */
+
+/** 任务状态。 */
+export type TaskState = 'queued' | 'running' | 'succeeded' | 'failed' | 'cancelled'
+
+/** 任务记录（调度器视图）。 */
+export interface TaskRecord<S> {
+  id: string
+  state: TaskState
+  /** 排队/运行中的业务快照（提交时的请求摘要）。 */
+  snapshot: S
+  /** 成功结果（succeeded 时存在）。 */
+  result: unknown | null
+  /** 失败信息（failed/cancelled 时存在）。 */
+  error: string | null
+  createdAt: string
+  startedAt: string | null
+  finishedAt: string | null
+}
+
+interface TaskEntry<S> {
+  record: TaskRecord<S>
+  run: (signal: AbortSignal) => Promise<unknown>
+  controller: AbortController
+}
+
+export interface RunnerOptions {
+  /** 并发上限（0 = 不限）。 */
+  maxConcurrent: number
+  /** 任务 id 生成器（缺省自增）。 */
+  nextId?: () => string
+}
+
+/**
+ * 并发任务执行器。
+ * - submit 入队即返回记录引用（状态经 record 可变字段即时可见）；
+ * - 每次完成自动拉起下一段（pump 链式，无定时器）；
+ * - cancel 对 queued 置 cancelled、对 running 发 abort（任务体自行响应）。
+ */
+export class TaskRunner<S> {
+  private readonly entries = new Map<string, TaskEntry<S>>()
+  private readonly order: string[] = []
+  private maxConcurrent: number
+  private readonly nextId: () => string
+  /** 完结任务保留条数（防 Map 膨胀；由调用方配置）。 */
+  private readonly keepFinished: number
+
+  constructor(options: RunnerOptions, keepFinished = 200) {
+    this.maxConcurrent = Math.max(0, Math.floor(options.maxConcurrent))
+    this.nextId = options.nextId ?? defaultIdCounter()
+    this.keepFinished = keepFinished
+  }
+
+  /** 并发上限热更（配置热生效入口；进行中任务不受影响）。 */
+  reconfigure(maxConcurrent: number): void {
+    this.maxConcurrent = Math.max(0, Math.floor(maxConcurrent))
+  }
+
+  /** 提交任务：返回记录（后续状态经同一引用轮询）。 */
+  submit(snapshot: S, run: (signal: AbortSignal) => Promise<unknown>): TaskRecord<S> {
+    const controller = new AbortController()
+    const record: TaskRecord<S> = {
+      id: this.nextId(),
+      state: 'queued',
+      snapshot,
+      result: null,
+      error: null,
+      createdAt: new Date().toISOString(),
+      startedAt: null,
+      finishedAt: null,
+    }
+    this.entries.set(record.id, { record, run, controller })
+    this.order.push(record.id)
+    void this.pump()
+    return record
+  }
+
+  /** 单任务记录查询。 */
+  get(id: string): TaskRecord<S> | null {
+    return this.entries.get(id)?.record ?? null
+  }
+
+  /** 全部记录（完结在前端按需过滤）。 */
+  list(): TaskRecord<S>[] {
+    return this.order
+      .map((id) => this.entries.get(id)?.record)
+      .filter((record): record is TaskRecord<S> => record !== undefined)
+  }
+
+  /** 取消：queued 直接置 cancelled；running 发 abort（异步生效）。 */
+  cancel(id: string): boolean {
+    const entry = this.entries.get(id)
+    if (entry === undefined) return false
+    if (entry.record.state === 'queued') {
+      entry.record.state = 'cancelled'
+      entry.record.finishedAt = new Date().toISOString()
+      this.prune()
+      return true
+    }
+    if (entry.record.state === 'running') {
+      entry.controller.abort()
+      return true
+    }
+    return false
+  }
+
+  /** 活跃数（queued + running）。 */
+  get activeCount(): number {
+    let count = 0
+    for (const entry of this.entries.values()) {
+      if (entry.record.state === 'queued' || entry.record.state === 'running') count += 1
+    }
+    return count
+  }
+
+  /** 拉起可运行任务至并发上限。 */
+  private async pump(): Promise<void> {
+    for (;;) {
+      const capacity =
+        this.maxConcurrent === 0
+          ? Number.POSITIVE_INFINITY
+          : this.maxConcurrent - this.runningCount()
+      if (capacity <= 0) return
+      const next = this.order
+        .map((id) => this.entries.get(id))
+        .find((entry) => entry !== undefined && entry.record.state === 'queued')
+      if (next === undefined) return
+      this.start(next)
+      if (this.maxConcurrent !== 0) return
+    }
+  }
+
+  private start(entry: TaskEntry<S>): void {
+    entry.record.state = 'running'
+    entry.record.startedAt = new Date().toISOString()
+    const signal = entry.controller.signal
+    void entry
+      .run(signal)
+      .then((result) => {
+        // abort 后 gate 仍可能正常 resolve：以 signal.aborted 为准判失败。
+        if (signal.aborted) {
+          entry.record.state = 'failed'
+          entry.record.error = '任务已取消'
+          entry.record.finishedAt = new Date().toISOString()
+          return
+        }
+        if (entry.record.state !== 'running') return
+        entry.record.state = 'succeeded'
+        entry.record.result = result
+        entry.record.finishedAt = new Date().toISOString()
+      })
+      .catch((error: unknown) => {
+        if (entry.record.state === 'cancelled') return
+        entry.record.state = 'failed'
+        entry.record.error = error instanceof Error ? error.message : String(error)
+        entry.record.finishedAt = new Date().toISOString()
+      })
+      .finally(() => {
+        this.prune()
+        void this.pump()
+      })
+  }
+
+  private runningCount(): number {
+    let count = 0
+    for (const entry of this.entries.values()) {
+      if (entry.record.state === 'running') count += 1
+    }
+    return count
+  }
+
+  /** 清理最旧完结条目（保持 Map 上限）。 */
+  private prune(): void {
+    const finished = this.order.filter((id) => {
+      const state = this.entries.get(id)?.record.state
+      return state === 'succeeded' || state === 'failed' || state === 'cancelled'
+    })
+    const overflow = finished.length - this.keepFinished
+    if (overflow <= 0) return
+    for (const id of finished.slice(0, overflow)) {
+      this.entries.delete(id)
+      const index = this.order.indexOf(id)
+      if (index >= 0) this.order.splice(index, 1)
+    }
+  }
+}
+
+/** 缺省 id 计数器。 */
+function defaultIdCounter(): () => string {
+  let counter = 0
+  return () => {
+    counter += 1
+    return `task-${counter}`
+  }
+}