@dsh-plus/image-studio 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 agguy
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/lib/client.js

@@ -0,0 +1,129 @@
+window.__ModuleLoader__.load({
+	id: "@dsh-plus/image-studio",
+	factory: (require) => {
+		var module = { exports: {} };
+		var exports = module.exports;
+		Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
+		//#region src/client/card.tsx
+		/**
+		* 配置卡片占位组件：本次交付为空壳（不做前端设计与编码）。
+		* 后续版本在此渲染三组预设编辑与凭据管理；keyed 槽位契约已声明。
+		* @module image-studio/client/card
+		*/
+		/** 占位组件。 */
+		function StudioConfigCard(props) {
+			const t = props.t ?? ((key) => key);
+			const el = document.createElement("div");
+			el.className = "dsh-plus-image-studio-card-placeholder";
+			el.textContent = t("cardPlaceholder");
+			return {
+				type: el,
+				props: {}
+			};
+		}
+		//#endregion
+		//#region src/client/i18n.ts
+		/**
+		* i18n 字典（zh 为主，en 兜底）；NS 与 settings 命名空间分离，
+		* 仅承载前端文案 key。本次只含占位文案。
+		* @module image-studio/client/i18n
+		*/
+		/** locale 命名空间。 */
+		const NS = "dsh-plus-image-studio";
+		const zh = {
+			nav: "图像工作室",
+			placeholder: "生图工作台与画廊将在后续版本提供",
+			cardPlaceholder: "图像工作室配置（预设/凭据管理将在后续版本提供）"
+		};
+		const en = {
+			nav: "Image Studio",
+			placeholder: "Image workspace and gallery arrive in a later release",
+			cardPlaceholder: "Image Studio settings (preset/credential management arrives later)"
+		};
+		//#endregion
+		//#region src/client/section.tsx
+		/**
+		* 独立设置页占位组件：本次交付为空壳（不做前端设计与编码）。
+		* 后续版本在此渲染生图工作台与画廊；插槽契约已按官方 settings.section 形态声明。
+		* @module image-studio/client/section
+		*/
+		/** 占位组件（props 形态对齐 settings.section 四 share 注入）。 */
+		function StudioSection(props) {
+			const t = props.t ?? ((key) => key);
+			const el = document.createElement("div");
+			el.className = "dsh-plus-image-studio-section-placeholder";
+			el.textContent = t("placeholder");
+			return {
+				type: el,
+				props: {}
+			};
+		}
+		//#endregion
+		//#region src/client/styles.ts
+		/**
+		* 画廊/生图占位样式：本次交付仅注入极简占位类名（无视觉设计）。
+		* 沿用官方约定 <style data-plugin data-plugin-css>，HMR 按此卸载。
+		* @module image-studio/client/styles
+		*/
+		const PKG = "@dsh-plus/image-studio";
+		/** 注入设置页占位样式。 */
+		function injectSectionStyle() {
+			return inject$1("dsh-plus-image-studio-section", ".dsh-plus-image-studio-section-placeholder{padding:16px;opacity:.6}");
+		}
+		/** 注入配置卡片占位样式。 */
+		function injectCardStyles() {
+			return inject$1("dsh-plus-image-studio-card", ".dsh-plus-image-studio-card-placeholder{padding:8px;opacity:.6}");
+		}
+		function inject$1(id, css) {
+			if (typeof document === "undefined") return null;
+			const tag = document.createElement("style");
+			tag.dataset.plugin = PKG;
+			tag.dataset.pluginCss = `${PKG}/${id}`;
+			tag.textContent = css;
+			document.head.appendChild(tag);
+			return tag;
+		}
+		//#endregion
+		//#region src/client/client.ts
+		const name = "dsh-plus-image-studio";
+		/** 浏览器半需要的 cordis 服务 key（loader 据此注入）。 */
+		const inject = [
+			"slots",
+			"locale",
+			"remote",
+			"remote.settings"
+		];
+		function apply(ctx) {
+			const c = ctx;
+			const sectionTag = injectSectionStyle();
+			const cardTag = injectCardStyles();
+			c.effect(() => () => {
+				sectionTag?.remove();
+				cardTag?.remove();
+			}, "image-studio: style");
+			c.effect(() => c.locale.register(NS, {
+				zh,
+				en
+			}), "image-studio: locale");
+			const t = c.locale.bind(NS);
+			c.slots.inject("settings.section", () => c.slots.register({
+				name: "settings.section",
+				id: "dsh-plus-image-studio",
+				order: 16,
+				label: () => t("nav"),
+				inject: () => ({ t })
+			}, StudioSection));
+			c.slots.inject("settings.plugin.item", () => c.slots.register({
+				name: "settings.plugin.item",
+				key: "dsh-plus-image-studio",
+				locale: NS,
+				inject: () => ({ t })
+			}, StudioConfigCard));
+		}
+		//#endregion
+		exports.apply = apply;
+		exports.inject = inject;
+		exports.name = name;
+		return module.exports;
+	}
+});

package/lib/index.d.ts

@@ -0,0 +1,321 @@
+import z from "@deepseek-ai/schemastery";
+import { Context, Service } from "@deepseek-ai/cordis";
+//#region src/config.d.ts
+declare const Config: z<Schemastery.ObjectS<{
+  promptPresets: z<unknown[], any[]>;
+  paramPresets: z<unknown[], any[]>;
+  providerPresets: z<unknown[], any[]>;
+  maxConcurrent: z<number, number>;
+  requestTimeoutMs: z<number, number>;
+  proxy: z<string, string>;
+  galleryMaxItems: z<number, number>;
+}>, Schemastery.ObjectT<{
+  promptPresets: z<unknown[], any[]>;
+  paramPresets: z<unknown[], any[]>;
+  providerPresets: z<unknown[], any[]>;
+  maxConcurrent: z<number, number>;
+  requestTimeoutMs: z<number, number>;
+  proxy: z<string, string>;
+  galleryMaxItems: z<number, number>;
+}>>;
+type ImageStudioConfig = Schemastery.TypeT<typeof Config>;
+/** 提示词预设（解析后视图）。 */
+interface PromptPresetEntry {
+  id: string;
+  name: string;
+  text: string;
+}
+/** 参数预设（解析后视图）。 */
+interface ParamPresetEntry {
+  id: string;
+  name: string;
+  endpoint: 'generation' | 'edit';
+  paramSpecs: unknown;
+}
+/** 提供商预设（解析后视图）。 */
+interface ProviderPresetEntry {
+  id: string;
+  name: string;
+  protocol: string;
+  baseUrl: string;
+  model: string;
+  credentialRef: string;
+  extraHeaders: Record<string, string>;
+}
+//#endregion
+//#region src/provider/types.d.ts
+/**
+ * 图像生成 provider 抽象：协议无关的请求/结果模型 + 适配器契约。
+ * 首批实现 openai-images；后续协议经 ImageProviderRegistry 挂载，不改核心。
+ * @module image-studio/provider/types
+ */
+/** 生图端点（官方 Images API 两类；新增协议可扩展联合）。 */
+type ImageEndpoint = 'generation' | 'edit';
+//#endregion
+//#region src/gallery/store.d.ts
+/** 画廊条目元数据（DTO 主体，端点原样投影）。 */
+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[];
+}
+//#endregion
+//#region src/task/runner.d.ts
+/**
+ * 生图任务并发执行器：FIFO 队列 + 可配置并发上限（0 = 不限）。
+ * 与业务解耦：任务体是注入的异步函数，本模块只管调度与状态；
+ * 纯调度逻辑可单测（不触网）。
+ * @module image-studio/task/runner
+ */
+/** 任务状态。 */
+type TaskState = 'queued' | 'running' | 'succeeded' | 'failed' | 'cancelled';
+//#endregion
+//#region src/dto.d.ts
+/** 任务提交请求体。 */
+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 视图。 */
+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;
+}
+/** 画廊删除/查询应答。 */
+interface GalleryListWire {
+  items: GalleryItem[];
+  total: number;
+}
+/** 凭据状态（describe 投影，永不回传值）。 */
+interface CredentialStatusWire {
+  credentialRef: string;
+  configured: boolean;
+}
+/** providers 端点应答：协议 registry + 参数目录（前端表单依据）。 */
+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 快照投影）。 */
+interface PresetsWire {
+  promptPresets: PromptPresetEntry[];
+  paramPresets: ParamPresetEntry[];
+  providerPresets: ProviderPresetEntry[];
+}
+//#endregion
+//#region src/service.d.ts
+declare class ImageStudioService extends Service {
+  private current;
+  private readonly runner;
+  private readonly log;
+  constructor(ctx: Context, config: ImageStudioConfig);
+  /** 配置热更：并发上限即时生效（进行中任务不受影响）。 */
+  private applyConfig;
+  private promptPresets;
+  private paramPresets;
+  private providerPresets;
+  /** 预设快照（端点投影）。 */
+  presets(): {
+    promptPresets: PromptPresetEntry[];
+    paramPresets: ParamPresetEntry[];
+    providerPresets: ProviderPresetEntry[];
+  };
+  /** describe 单个提供商预设凭据（不回传值）。 */
+  credentialStatus(presetId: string): Promise<{
+    credentialRef: string;
+    configured: boolean;
+  }>;
+  /** set/unset 凭据（端点写通道）。 */
+  setCredential(presetId: string, value: string): Promise<void>;
+  unsetCredential(presetId: string): Promise<void>;
+  /** credentials seam 可选探测（缺席返回 null）。 */
+  private credentialsSeam;
+  private requireCredentials;
+  /** 提交生图任务：校验 → 入队 → 返回 taskId。 */
+  submitGenerate(request: GenerateRequest): Promise<string>;
+  /** 单任务查询（wire 投影）。 */
+  taskWire(id: string): TaskWire | null;
+  /** 任务列表（最新在前）。 */
+  taskWires(): TaskWire[];
+  /** 取消任务。 */
+  cancelTask(id: string): boolean;
+  private toTaskWire;
+  /**
+   * 任务准备（边界校验集中地）：提供商预设/inline → target；
+   * 参数预设 + 覆盖 → 归一化参数表；sourceIds → 输入图字节。
+   */
+  private prepareTask;
+  /** 提供商预设 / inline → ProviderTarget（凭据即时 resolve）。 */
+  private resolveTarget;
+  /** 凭据解析（每次操作即时 resolve，不缓存）。 */
+  private resolveApiKey;
+  /** 参数预设 + 覆盖合并 → 端点归一化（model 由 target 承载）。 */
+  private resolveParams;
+  /** 模型优先级：inline > 提供商预设（参数表中的 model 仅为展示，不参与）。 */
+  private modelOf;
+  private providerModelOf;
+  /** 源图字节加载（edit ≥1 张；单图上限 50MB 对齐官方）。 */
+  private loadSourceImages;
+  private loadMask;
+  private loadOneImage;
+  /** 任务体：调协议适配器 → 成功入画廊。失败向上抛给 TaskRunner 记录。 */
+  private executeTask;
+  /** 提交时上下文里的预设 id（executeTask 无原请求，经 target 旁路携带）。 */
+  private presetIdOf;
+  /** 画廊列表（全量；分页/过滤由端点层做）。 */
+  gallery(): Promise<GalleryItem[]>;
+  /** 删除画廊条目（图片 + 元数据）。 */
+  deleteGalleryItem(itemId: string): Promise<boolean>;
+  /** 读取图片字节（端点直投流）。 */
+  imageBytes(imageId: string): Promise<{
+    data: Uint8Array;
+    ext: string;
+  } | null>;
+  dispose(): void;
+}
+//#endregion
+//#region src/credentials.d.ts
+/**
+ * 凭据引用名派生与校验：提供商预设 id → IMAGE_STUDIO_PRESET_<ID>。
+ * 规则对齐《插件存储规范》：大写下划线、全大写、前缀属主。
+ * 纯函数，零依赖。
+ * @module image-studio/credentials
+ */
+/** 预设 id 是否合法（kebab-case，用于引用名派生）。 */
+declare function isValidPresetId(id: string): boolean;
+/** 预设 id → 凭据引用名（kebab → SNAKE 大写）。 */
+declare function credentialRefNameOf(presetId: string): string;
+//#endregion
+//#region src/errors.d.ts
+/**
+ * 插件内可识别错误：消息即结构化错误码，端点与任务层按码映射 HTTP 状态。
+ * @module image-studio/errors
+ */
+/** 全部错误码（封闭集合，新增协议/端点行为时按需扩充）。 */
+declare const ERROR_CODES: readonly ["unknown-protocol", "unknown-endpoint", "invalid-request", "unknown-source", "unknown-task", "task-not-runnable", "credential-unavailable", "settings-unavailable", "provider-error"];
+type ErrorCode = (typeof ERROR_CODES)[number];
+declare class ImageStudioError extends Error {
+  readonly code: ErrorCode;
+  constructor(code: ErrorCode, message?: string);
+}
+//#endregion
+//#region src/params/catalog.d.ts
+/** 参数值类型（校验与前端控件形态的依据）。 */
+type ParamKind = 'string' | 'integer' | 'enum' | 'boolean';
+/** 单个参数的目录条目。 */
+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;
+}
+/** 只读目录（冻结防运行期篡改）。 */
+declare const PARAM_CATALOG: readonly ParamEntry[];
+/** 按字段名查目录条目。 */
+declare function paramEntryOf(key: string): ParamEntry | null;
+/** 某端点下可用的参数键集合（含 advanced）。 */
+declare function paramKeysFor(endpoint: ImageEndpoint): readonly string[];
+//#endregion
+//#region src/params/spec.d.ts
+/** 单参数的开关 + 自定义值。 */
+interface ParamSpec {
+  enabled: boolean;
+  value?: unknown;
+}
+/** 端点 → 该端点参数表。 */
+type ParamSpecMap = Record<string, ParamSpec>;
+/** 归一化失败原因（边界校验用，端点转 invalid-request）。 */
+declare class ParamValidationError extends Error {
+  readonly key: string;
+  constructor(key: string, message: string);
+}
+/**
+ * 校验并归一化一份参数表：仅保留启用且适用于该端点的参数；
+ * model 是请求基础（提供商预设承载），不计入协议参数表。
+ * 任何禁用/未知/越界项直接抛 ParamValidationError（边界 fail-loud）。
+ */
+declare function normalizeParamSpecs(specs: ParamSpecMap, endpoint: ImageEndpoint): Record<string, unknown>;
+/** 校验预设里的参数表（结构合法但可跨端点；应用时再按端点归一化）。 */
+declare function validateParamSpecs(specs: unknown): ParamSpecMap;
+//#endregion
+//#region src/index.d.ts
+declare const name = "dsh-plus-image-studio";
+declare const inject: readonly ["credentials"];
+declare module '@deepseek-ai/cordis' {
+  interface Context {
+    imageStudio: ImageStudioService;
+  }
+}
+declare function apply(ctx: Context, config: ImageStudioConfig): void;
+//#endregion
+export { Config, type CredentialStatusWire, type ErrorCode, type GalleryItem, type GalleryListWire, type GenerateRequest, ImageStudioError, ImageStudioService, PARAM_CATALOG, type ParamEntry, type ParamSpec, type ParamSpecMap, ParamValidationError, type PresetsWire, type ProvidersWire, type TaskWire, apply, credentialRefNameOf, inject, isValidPresetId, name, normalizeParamSpecs, paramEntryOf, paramKeysFor, validateParamSpecs };