@dsh-plus/image-studio 0.1.5 → 0.1.7

package/src/client/panel/picker.tsx

@@ -1,15 +1,20 @@
 /**
- * 画廊图片选择器（模态）：源图多选（≤16）与遮罩单选共用。
- * 扁平化全部画廊条目的图片，倒序排列；底部确认条显示已选数量。
+ * 源图选择器（模态）：源图多选（≤MAX_SOURCE_IMAGES）与遮罩单选共用。
+ * 两个来源分区——画廊（已生成图片）与本地上传（暂存区），可混合选择；
+ * 选中态以 SourceRef 记录（kind 区分 id 空间），底部确认条显示已选数量。
  * @module image-studio/client/panel/picker
  */
 import { Modal } from '@deepseek-ai/dsh-client-ui-primitives'
+import { IconPlusOutline16 } from '@dsh-plus/shared/client'
 import { type ReactElement, useState } from 'react'
+import type { SourceRef, UploadEntry } from '../../dto.ts'
 import type { GalleryItem } from '../../gallery/store.ts'
-import { imageUrl } from '../api.ts'
+import { MAX_SOURCE_IMAGES } from '../../limits.ts'
+import { imageUrl, uploadImageUrl } from '../api.ts'
 import type { Translate } from '../i18n.ts'
+import { UploadButton, type UploadsApi } from './uploads.tsx'
 
-/** 扁平化的可选图片（imageId + 归属条目提示词）。 */
+/** 扁平化的可选画廊图片（imageId + 归属条目提示词）。 */
 interface PickableImage {
   imageId: string
   prompt: string
@@ -20,11 +25,13 @@ interface ImagePickerProps {
   t: Translate
   title: string
   items: GalleryItem[]
+  /** 上传暂存区（列表 + 上传入口）。 */
+  uploads: UploadsApi
   /** 多选（源图）或单选（遮罩）。 */
   multiple: boolean
-  /** 初始已选（源图回填）。 */
-  initial: string[]
-  onConfirm(ids: string[]): void
+  /** 初始已选（源图/遮罩回填）。 */
+  initial: SourceRef[]
+  onConfirm(refs: SourceRef[]): void
   onClose(): void
 }
 
@@ -38,60 +45,137 @@ export function flattenImages(items: GalleryItem[]): PickableImage[] {
   return out
 }
 
+/** 引用键（选中判定与去重；两个 id 空间不重叠但不互相假设）。 */
+export function refKey(ref: SourceRef): string {
+  return `${ref.kind}:${ref.id}`
+}
+
+/** 缩略图地址（画廊 / 上传两套端点）。 */
+export function refUrl(ref: SourceRef): string {
+  return ref.kind === 'gallery' ? imageUrl(ref.id) : uploadImageUrl(ref.id)
+}
+
 export function ImagePicker(props: ImagePickerProps): ReactElement {
-  const { t, title, items, multiple, initial, onConfirm, onClose } = props
-  const [selected, setSelected] = useState<string[]>(initial)
+  const { t, title, items, uploads, multiple, initial, onConfirm, onClose } = props
+  const [selected, setSelected] = useState<SourceRef[]>(initial)
+  const [section, setSection] = useState<'gallery' | 'uploads'>(
+    uploads.items.length > 0 && items.length === 0 ? 'uploads' : 'gallery',
+  )
   const images = flattenImages(items)
+  const uploadItems = [...uploads.items].reverse()
+  const selectedKeys = selected.map(refKey)
 
-  const toggle = (imageId: string): void => {
+  const toggle = (ref: SourceRef): void => {
+    const key = refKey(ref)
     if (multiple) {
       setSelected((current) =>
-        current.includes(imageId)
-          ? current.filter((id) => id !== imageId)
-          : current.length >= 16
+        current.some((item) => refKey(item) === key)
+          ? current.filter((item) => refKey(item) !== key)
+          : current.length >= MAX_SOURCE_IMAGES
             ? current
-            : [...current, imageId],
+            : [...current, ref],
       )
       return
     }
-    setSelected((current) => (current.includes(imageId) ? [] : [imageId]))
+    setSelected((current) => (current.some((item) => refKey(item) === key) ? [] : [ref]))
   }
 
+  /** 新上传条目直接选中（少一次点击；超限按剩余额度截断）。 */
+  const selectUploaded = (entries: UploadEntry[]): void => {
+    const refs = entries.map((entry) => ({ kind: 'upload' as const, id: entry.id }))
+    setSelected((current) => (multiple ? [...current, ...refs].slice(0, MAX_SOURCE_IMAGES) : refs))
+    setSection('uploads')
+  }
+
+  const grid = (cells: Array<{ ref: SourceRef; title: string }>, empty: string): ReactElement =>
+    cells.length === 0 ? (
+      <p className="ims-empty">{empty}</p>
+    ) : (
+      <div className="ims-pickerGrid" role="listbox" aria-multiselectable={multiple}>
+        {cells.map((cell) => {
+          const index = selectedKeys.indexOf(refKey(cell.ref))
+          const on = index >= 0
+          return (
+            <button
+              key={refKey(cell.ref)}
+              type="button"
+              role="option"
+              aria-selected={on}
+              className={`ims-pickerCell${on ? ' ims-pickerCellOn' : ''}`}
+              title={cell.title}
+              onClick={() => toggle(cell.ref)}
+            >
+              <img src={refUrl(cell.ref)} alt={cell.title} loading="lazy" />
+              {on ? <span className="ims-pickerMark">{index + 1}</span> : null}
+            </button>
+          )
+        })}
+      </div>
+    )
+
   // 官方 Modal 承载（嵌套 portal：层级高于工作台，遮罩/Escape 由 Modal 处理）。
   return (
     <Modal open onClose={onClose} title={title} headless className="ims-pickerModal">
       <div className="ims-sub">
         <div className="ims-subHead">
           <h3 className="ims-subTitle">{title}</h3>
+          <UploadButton
+            t={t}
+            uploads={uploads}
+            multiple={multiple}
+            // 遮罩只接受 PNG（官方要求带透明通道）；源图不限格式。
+            accept={multiple ? undefined : 'image/png'}
+            onUploaded={selectUploaded}
+            className="ims-btn ims-btnPrimary ims-btnSmall"
+          >
+            <IconPlusOutline16 size={14} /> {t('upload.pick')}
+          </UploadButton>
           <button type="button" className="ims-btn ims-btnGhost" onClick={onClose}>
             {t('common.close')}
           </button>
         </div>
-        {images.length === 0 ? (
-          <p className="ims-empty">{t('picker.empty')}</p>
-        ) : (
-          <div className="ims-pickerGrid" role="listbox" aria-multiselectable={multiple}>
-            {images.map((image) => {
-              const on = selected.includes(image.imageId)
-              return (
-                <button
-                  key={image.imageId}
-                  type="button"
-                  role="option"
-                  aria-selected={on}
-                  className={`ims-pickerCell${on ? ' ims-pickerCellOn' : ''}`}
-                  title={image.prompt}
-                  onClick={() => toggle(image.imageId)}
-                >
-                  <img src={imageUrl(image.imageId)} alt={image.prompt} loading="lazy" />
-                  {on ? (
-                    <span className="ims-pickerMark">{selected.indexOf(image.imageId) + 1}</span>
-                  ) : null}
-                </button>
-              )
-            })}
-          </div>
-        )}
+        <div className="ims-seg">
+          <button
+            type="button"
+            className={`ims-segItem${section === 'gallery' ? ' ims-segItemOn' : ''}`}
+            aria-pressed={section === 'gallery'}
+            onClick={() => setSection('gallery')}
+          >
+            {t('picker.section.gallery')}
+          </button>
+          <button
+            type="button"
+            className={`ims-segItem${section === 'uploads' ? ' ims-segItemOn' : ''}`}
+            aria-pressed={section === 'uploads'}
+            onClick={() => {
+              uploads.reload()
+              setSection('uploads')
+            }}
+          >
+            {t('picker.section.uploads')}
+          </button>
+        </div>
+        {section === 'gallery'
+          ? grid(
+              images.map((image) => ({
+                ref: { kind: 'gallery', id: image.imageId },
+                title: image.prompt,
+              })),
+              t('picker.empty'),
+            )
+          : grid(
+              uploadItems.map((entry) => ({
+                ref: { kind: 'upload', id: entry.id },
+                title: entry.name,
+              })),
+              t('upload.empty'),
+            )}
+        {uploads.error !== null ? (
+          <p className="ims-status ims-statusError" role="alert">
+            {t('upload.failed')}
+            {uploads.error}
+          </p>
+        ) : null}
         <div className="ims-subFoot">
           <button
             type="button"

package/src/client/panel/uploads.tsx

@@ -0,0 +1,124 @@
+/**
+ * 本地文件上传的浏览器半：列表/上传/错误态封装为 hook，控件供生图表单与
+ * 图片选择器复用。上传为串行（逐个文件），首个失败即中断并展示原因；
+ * 成功后条目即时并入本地列表（选择器无需刷新即可见）。
+ * @module image-studio/client/panel/uploads
+ */
+import {
+  type ChangeEvent,
+  type ReactElement,
+  type ReactNode,
+  useCallback,
+  useRef,
+  useState,
+} from 'react'
+import type { UploadEntry } from '../../dto.ts'
+import { fetchUploads, uploadImage } from '../api.ts'
+import type { Translate } from '../i18n.ts'
+
+/** 可接受的上传类型（宿主端另有魔数嗅探兜底）。 */
+const ACCEPT = 'image/png,image/jpeg,image/webp,image/gif'
+
+export interface UploadsApi {
+  /** 暂存区条目（索引序，最新在后）。 */
+  items: UploadEntry[]
+  /** 列表加载/上传进行中。 */
+  busy: boolean
+  /** 最近一次失败原因（成功即清空）。 */
+  error: string | null
+  /** 上传一批文件，返回成功条目（失败中断并置 error）。 */
+  add(files: FileList | File[]): Promise<UploadEntry[]>
+  /** 重新拉取列表。 */
+  reload(): void
+}
+
+/** 上传暂存区读写 hook（每个消费组件一份，互不共享状态）。 */
+export function useUploads(): UploadsApi {
+  const [items, setItems] = useState<UploadEntry[]>([])
+  const [busy, setBusy] = useState(false)
+  const [error, setError] = useState<string | null>(null)
+
+  const reload = useCallback((): void => {
+    setBusy(true)
+    fetchUploads()
+      .then((res) => setItems(res.items))
+      .catch(() => setItems([]))
+      .finally(() => setBusy(false))
+  }, [])
+
+  const add = useCallback(async (files: FileList | File[]): Promise<UploadEntry[]> => {
+    const list = Array.from(files)
+    if (list.length === 0) return []
+    setBusy(true)
+    setError(null)
+    const saved: UploadEntry[] = []
+    try {
+      for (const file of list) {
+        const entry = await uploadImage(file)
+        saved.push(entry)
+      }
+      setItems((current) => [...current, ...saved])
+      return saved
+    } catch (err: unknown) {
+      setError(err instanceof Error ? err.message : String(err))
+      return saved
+    } finally {
+      setBusy(false)
+    }
+  }, [])
+
+  return { items, busy, error, add, reload }
+}
+
+interface UploadButtonProps {
+  t: Translate
+  uploads: UploadsApi
+  /** 上传成功回调（新条目已入列表；调用方按需自动选中）。 */
+  onUploaded(entries: UploadEntry[]): void
+  /** 允许多选（源图）或单选（遮罩）。 */
+  multiple: boolean
+  /** 允许的文件类型（缺省四类位图；遮罩场景传 image/png）。 */
+  accept?: string
+  disabled?: boolean
+  className?: string
+  children: ReactNode
+}
+
+/** 隐藏 file input + 触发按钮（移动端显式 accept 图像类型，避免退化为相册单选）。 */
+export function UploadButton(props: UploadButtonProps): ReactElement {
+  const { t, uploads, onUploaded, multiple, disabled, className, children } = props
+  const inputRef = useRef<HTMLInputElement>(null)
+
+  const onChange = (event: ChangeEvent<HTMLInputElement>): void => {
+    const files = event.target.files
+    if (files !== null && files.length > 0) {
+      void uploads.add(files).then((entries) => {
+        if (entries.length > 0) onUploaded(entries)
+      })
+    }
+    // 复位以便连续选择同一文件。
+    event.target.value = ''
+  }
+
+  return (
+    <>
+      <button
+        type="button"
+        className={className ?? 'ims-btn ims-btnGhost'}
+        disabled={disabled === true || uploads.busy}
+        onClick={() => inputRef.current?.click()}
+      >
+        {children}
+      </button>
+      <input
+        ref={inputRef}
+        type="file"
+        hidden
+        multiple={multiple}
+        accept={props.accept ?? ACCEPT}
+        aria-label={t('upload.pick')}
+        onChange={onChange}
+      />
+    </>
+  )
+}

package/src/client/styles.ts

@@ -235,6 +235,32 @@ export const imageStudioCss = `
   white-space: nowrap;
 }
 .ims-paramControl { width: 132px; flex: none; min-height: 30px; padding: 4px 8px; }
+.ims-inputInvalid {
+  border-color: var(--dsw-alias-state-error-primary);
+}
+.ims-paramValue { display: grid; gap: 4px; justify-items: end; }
+.ims-paramPresets { display: flex; flex-wrap: wrap; gap: 4px; justify-content: flex-end; }
+.ims-chip {
+  padding: 1px 6px;
+  border: 1px solid var(--dsw-alias-border-l2);
+  border-radius: 999px;
+  background: transparent;
+  color: var(--dsw-alias-label-secondary);
+  font-family: var(--ds-font-family-code);
+  font-size: 10px;
+  line-height: 16px;
+  cursor: pointer;
+}
+.ims-chip:hover { background: var(--dsw-alias-interactive-bg-hover); }
+.ims-chipOn {
+  border-color: var(--dsw-alias-brand-primary);
+  color: var(--dsw-alias-brand-primary);
+}
+.ims-paramWarn {
+  margin-top: 2px;
+  color: var(--dsw-alias-state-error-primary);
+  font-size: 11px;
+}
 .ims-adv { margin-top: 8px; }
 .ims-advSummary {
   cursor: pointer;
@@ -361,6 +387,30 @@ export const imageStudioCss = `
 }
 .ims-subFoot .ims-status { margin: 0 auto 0 0; }
 
+/* 选择器来源切换（画廊 / 本地上传） */
+.ims-seg {
+  display: flex;
+  flex: none;
+  gap: 4px;
+  padding: 8px 14px 0;
+}
+.ims-segItem {
+  padding: 4px 10px;
+  border: 1px solid transparent;
+  border-radius: 999px;
+  background: transparent;
+  color: var(--dsw-alias-label-secondary);
+  font-size: 12px;
+  cursor: pointer;
+}
+.ims-segItem:hover { background: var(--dsw-alias-interactive-bg-hover); }
+.ims-segItemOn {
+  border-color: var(--dsw-alias-border-l2);
+  background: var(--dsw-alias-bg-layer-1);
+  color: var(--dsw-alias-label-primary);
+  font-weight: 600;
+}
+
 /* 选择器网格 */
 .ims-pickerGrid {
   flex: 1;

package/src/config.ts

@@ -59,6 +59,12 @@ export const Config = z.object({
     .max(10_000)
     .description('画廊保留上限（条，0 = 不清理；超限按最旧删除）')
     .default(500),
+  uploadTtlHours: z
+    .number()
+    .min(1)
+    .max(720)
+    .description('上传原图保留时长（小时；未被画廊条目引用的超期即回收）')
+    .default(24),
 })
 
 export type ImageStudioConfig = Schemastery.TypeT<typeof Config>

package/src/dto.ts

@@ -8,6 +8,20 @@ import type { ParamPresetEntry, PromptPresetEntry, ProviderPresetEntry } from '.
 import type { GalleryItem } from './gallery/store.ts'
 import type { ImageEndpoint } from './provider/types.ts'
 import type { TaskState } from './task/runner.ts'
+import type { UploadEntry } from './uploads/store.ts'
+
+// GalleryItem 由 gallery/store 定义，但属 wire 视图的一部分（GalleryListWire 及
+// 客户端半 fetchGalleryItem 都用它）；在此转出，dto 保持「前后端共享类型单一门面」。
+export type { GalleryItem, UploadEntry }
+
+/**
+ * 源图引用：画廊已落盘图片（gallery）或本地文件上传的暂存图片（upload）。
+ * 两个 id 空间互不重叠，故引用必须显式带 kind（同一字符串在两边含义不同）。
+ */
+export interface SourceRef {
+  kind: 'gallery' | 'upload'
+  id: string
+}
 
 /** 任务提交请求体。 */
 export interface GenerateRequest {
@@ -25,9 +39,13 @@ export interface GenerateRequest {
   paramPresetId?: string
   /** 参数覆盖表（同 ParamSpecMap 形态）。 */
   paramSpecs?: Record<string, { enabled: boolean; value?: unknown }>
-  /** 图生图源图（本画廊 imageId；edit 必填 ≥1）。 */
+  /** 图生图源图（edit 必填 ≥1，≤16；画廊图片与本地文件上传混用）。 */
+  sources?: SourceRef[]
+  /** 可选遮罩（官方要求 PNG；与源图同一引用形态）。 */
+  mask?: SourceRef
+  /** @deprecated 旧客户端兼容：等价于 kind='gallery' 的 sources。 */
   sourceIds?: string[]
-  /** 可选 PNG mask（本画廊 imageId）。 */
+  /** @deprecated 旧客户端兼容：等价于 kind='gallery' 的 mask。 */
   maskId?: string
 }
 

package/src/errors.ts

@@ -13,6 +13,8 @@ export const ERROR_CODES = [
   'task-not-runnable',
   'credential-unavailable',
   'settings-unavailable',
+  'unsupported-media',
+  'upload-too-large',
   'provider-error',
 ] as const
 
@@ -41,6 +43,10 @@ export function statusOfCode(code: string): number {
     case 'credential-unavailable':
     case 'settings-unavailable':
       return 409
+    case 'unsupported-media':
+      return 415
+    case 'upload-too-large':
+      return 413
     default:
       return 500
   }

package/src/gallery/store.ts

@@ -11,6 +11,8 @@ import { appendFile, mkdir, readdir, readFile, rename, rm, writeFile } from 'nod
 import { join } from 'node:path'
 
 import { pluginDataPath } from '@dsh-plus/shared'
+import { isImageId } from '../images/id.ts'
+import { extOfMime } from '../images/mime.ts'
 import type { ImageEndpoint } from '../provider/types.ts'
 
 /** 画廊条目元数据（DTO 主体，端点原样投影）。 */
@@ -30,8 +32,10 @@ export interface GalleryItem {
   imageIds: string[]
   /** 每张图的 revised_prompt（与 imageIds 对齐，可为 null）。 */
   revisedPrompts: Array<string | null>
-  /** 图生图源图（本画廊内的 imageId）；文生图为空。 */
+  /** 图生图源图中的画廊图片（本画廊 imageId）；文生图为空。 */
   sourceIds: string[]
+  /** 图生图源图中的本地文件上传（uploads 暂存区 id）；上传被回收即失效。 */
+  sourceUploads: string[]
 }
 
 /**
@@ -49,23 +53,20 @@ 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 })
 }
 
+/** 旧条目补齐新增字段（sourceUploads 为后加字段，历史 JSONL 里不存在）。 */
+function normalizeItem(item: GalleryItem): GalleryItem {
+  return {
+    ...item,
+    sourceIds: item.sourceIds ?? [],
+    sourceUploads: item.sourceUploads ?? [],
+  }
+}
+
 /** 解析 JSONL 全量元数据（坏行跳过并告警；空文件返回空表）。 */
 export async function loadGallery(log: (message: string) => void): Promise<GalleryItem[]> {
   let text: string
@@ -78,7 +79,7 @@ export async function loadGallery(log: (message: string) => void): Promise<Galle
   for (const line of text.split('\n')) {
     if (line.trim().length === 0) continue
     try {
-      items.push(JSON.parse(line) as GalleryItem)
+      items.push(normalizeItem(JSON.parse(line) as GalleryItem))
     } catch {
       log(`画廊元数据坏行跳过：${line.slice(0, 80)}`)
     }
@@ -94,7 +95,7 @@ async function appendIndex(item: GalleryItem): Promise<void> {
 
 /** 图片文件绝对路径。 */
 function imagePathOf(imageId: string, ext: string): string {
-  if (!/^[a-f0-9-]{36}$/.test(imageId) || !/^[a-z0-9]{2,4}$/.test(ext)) {
+  if (!isImageId(imageId) || !/^[a-z0-9]{2,4}$/.test(ext)) {
     throw new Error(`非法画廊图片标识：${imageId}.${ext}`)
   }
   return join(imagesDir(), `${imageId}.${ext}`)

package/src/images/id.ts

@@ -0,0 +1,12 @@
+/**
+ * 图片标识形态（uuid）：画廊 imageId 与上传 uploadId 共用同一约束。
+ * 既是路由参数白名单，也是路径拼接的穿越防线（单一事实源）。
+ * @module image-studio/images/id
+ */
+
+const IMAGE_ID_RE = /^[a-f0-9-]{36}$/
+
+/** 是否为合法图片标识（未知类型一律 false）。 */
+export function isImageId(value: unknown): value is string {
+  return typeof value === 'string' && IMAGE_ID_RE.test(value)
+}

package/src/images/mime.ts

@@ -0,0 +1,64 @@
+/**
+ * 图片 MIME 单一事实源：扩展名互转 + 魔数嗅探。
+ * 上传边界只认官方 images 端点接受的位图格式（png/jpeg/webp/gif），
+ * 不信任客户端声明的 content-type（防伪装文件落盘）。
+ * 纯函数零依赖，宿主两半均可安全引入。
+ * @module image-studio/images/mime
+ */
+
+/** 魔数嗅探窗口（最长特征序列 + 偏移）。 */
+const SNIFF_BYTES = 16
+
+/** 落盘扩展名 ← MIME（白名单外一律按 png 处理）。 */
+export function extOfMime(mime: string): string {
+  switch (mime) {
+    case 'image/jpeg':
+      return 'jpg'
+    case 'image/webp':
+      return 'webp'
+    case 'image/gif':
+      return 'gif'
+    default:
+      return 'png'
+  }
+}
+
+/** MIME ← 落盘扩展名（读取回程；与 extOfMime 互逆）。 */
+export function mimeOfExt(ext: string): string {
+  switch (ext) {
+    case 'jpg':
+    case 'jpeg':
+      return 'image/jpeg'
+    case 'webp':
+      return 'image/webp'
+    case 'gif':
+      return 'image/gif'
+    default:
+      return 'image/png'
+  }
+}
+
+/** 前若干字节是否以 prefix 开头。 */
+function startsWith(bytes: Uint8Array, prefix: readonly number[], offset = 0): boolean {
+  if (bytes.length < offset + prefix.length) return false
+  return prefix.every((value, index) => bytes[offset + index] === value)
+}
+
+/** ASCII 特征序列 → 字节数组（'RIFF' / 'WEBP' 等容器标记）。 */
+function ascii(text: string): number[] {
+  return [...text].map((char) => char.charCodeAt(0))
+}
+
+/**
+ * 魔数嗅探图片类型；非白名单格式返回 null。
+ * @param bytes - 文件字节（只需前 16 字节即可判定）。
+ */
+export function detectImageMime(bytes: Uint8Array): string | null {
+  const head = bytes.subarray(0, SNIFF_BYTES)
+  if (startsWith(head, [0x89, 0x50, 0x4e, 0x47, 0x0d, 0x0a, 0x1a, 0x0a])) return 'image/png'
+  if (startsWith(head, [0xff, 0xd8, 0xff])) return 'image/jpeg'
+  if (startsWith(head, ascii('GIF87a')) || startsWith(head, ascii('GIF89a'))) return 'image/gif'
+  // WebP：RIFF 容器 + 第 8 字节起 'WEBP' 四字符码。
+  if (startsWith(head, ascii('RIFF')) && startsWith(head, ascii('WEBP'), 8)) return 'image/webp'
+  return null
+}

package/src/index.ts

@@ -1,9 +1,10 @@
 /**
  * dsh 插件：图像工作室。
- * OpenAI Images 协议文生图/图生图，官方全参数开关化（enabled=false 不进请求），
- * 双预设体系（提示词/参数/提供商），并发生图任务（FIFO + 可配置上限），
- * 画廊持久化（元数据 JSONL + 图片落盘）与二次编辑链（sourceIds）。
- * 服务经 ctx.imageStudio 暴露；前端接口见 docs/README.md「前端接入点」。
+ * OpenAI Images 协议文生图/图生图（源图可取画廊图片或本地上传），官方全参数
+ * 开关化（enabled=false 不进请求），双预设体系（提示词/参数/提供商），并发生图
+ * 任务（FIFO + 可配置上限），画廊持久化（元数据 JSONL + 图片落盘）与二次编辑链
+ * （sourceIds / sourceUploads）。服务经 ctx.imageStudio 暴露；
+ * 前端接口见 docs/README.md「前端接入点」。
  * @module @dsh-plus/image-studio
  */
 import type { Context } from '@deepseek-ai/cordis'
@@ -22,12 +23,18 @@ export type {
   GenerateRequest,
   PresetsWire,
   ProvidersWire,
+  SourceRef,
   TaskWire,
+  UploadEntry,
 } from './dto.ts'
-export { type ErrorCode, ImageStudioError } from './errors.ts'
+export { type ErrorCode, ImageStudioError, statusOfCode } from './errors.ts'
 export type { GalleryItem } from './gallery/store.ts'
+export { isImageId } from './images/id.ts'
+export { detectImageMime, extOfMime, mimeOfExt } from './images/mime.ts'
+export { MAX_SOURCE_IMAGES, UPLOAD_MAX_BYTES } from './limits.ts'
 export type { ParamEntry } from './params/catalog.ts'
 export { PARAM_CATALOG, paramEntryOf, paramKeysFor } from './params/catalog.ts'
+export { checkImageSize, IMAGE_SIZE_RULE, SIZE_PRESETS } from './params/size.ts'
 export type { ParamSpec, ParamSpecMap } from './params/spec.ts'
 export { normalizeParamSpecs, ParamValidationError, validateParamSpecs } from './params/spec.ts'
 export { ImageStudioService } from './service.ts'

package/src/limits.ts

@@ -0,0 +1,12 @@
+/**
+ * 跨半共享的数量/体积上限（单一事实源）。
+ * 宿主边界校验与浏览器半控件共用，避免两处各写一个数字而漂移。
+ * 纯常量零依赖，浏览器半可安全引入。
+ * @module image-studio/limits
+ */
+
+/** 单次 edits 请求的源图上限（官方 GPT Image 限制）。 */
+export const MAX_SOURCE_IMAGES = 16
+
+/** 单张上传原图体积上限（50MB，对齐官方 images 端点与仓库上传约定）。 */
+export const UPLOAD_MAX_BYTES = 50 * 1024 * 1024