@dsh-plus/image-studio 0.1.0

package/package.json

@@ -0,0 +1,60 @@
+{
+  "name": "@dsh-plus/image-studio",
+  "version": "0.1.0",
+  "description": "dsh-plus service+ui plugin: 图像工作室——OpenAI Images 协议文生图/图生图，全参数开关化，双预设体系，并发生图任务与可二次编辑画廊",
+  "type": "module",
+  "main": "lib/index.js",
+  "types": "lib/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./lib/index.d.ts",
+      "default": "./lib/index.js"
+    },
+    "./client": "./lib/client.js",
+    "./src/*": "./src/*",
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "lib",
+    "src"
+  ],
+  "dependencies": {
+    "https-proxy-agent": "^9.1.0",
+    "@dsh-plus/shared": "0.1.11"
+  },
+  "peerDependencies": {
+    "@deepseek-ai/cordis": "^4.0.2",
+    "@deepseek-ai/dsh-credentials": "*",
+    "@deepseek-ai/dsh-host-webserver": "*",
+    "@deepseek-ai/dsh-settings": "*",
+    "@deepseek-ai/schemastery": "^3.18.2"
+  },
+  "devDependencies": {
+    "@deepseek-ai/cordis": "4.0.2",
+    "@deepseek-ai/dsh-credentials": "0.1.5-alpha.1",
+    "@deepseek-ai/dsh-host-webserver": "0.1.5-alpha.1",
+    "@deepseek-ai/dsh-session": "0.1.5-alpha.1",
+    "@deepseek-ai/dsh-settings": "0.1.5-alpha.1",
+    "@deepseek-ai/schemastery": "3.18.2",
+    "@types/node": "26.4.0",
+    "@types/react": "~18.3.31",
+    "react": "^18.2.0"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "dsh": {
+    "client": {
+      "inject": [
+        "@deepseek-ai/dsh-client-ui-renderer",
+        "@deepseek-ai/dsh-client-locale",
+        "@deepseek-ai/dsh-api-remotes"
+      ],
+      "platform": "web"
+    }
+  },
+  "scripts": {
+    "build": "tsdown",
+    "watch": "tsdown --watch"
+  }
+}

package/src/api.ts

@@ -0,0 +1,213 @@
+/**
+ * image-studio HTTP 端点（同源 webServer，与 usage-panel 同一暴露面约定）：
+ * - POST generate / GET tasks|tasks/<id> / POST tasks/<id>/cancel
+ * - GET gallery|gallery/<id> / DELETE gallery/<id> / GET images/<id>
+ * - GET|POST|DELETE credentials（describe/set/unset，值永不回传）
+ * - GET providers（协议 registry + 参数目录，前端表单依据）
+ * @module image-studio/api
+ */
+import type { IncomingMessage, ServerResponse } from 'node:http'
+
+import type { Context } from '@deepseek-ai/cordis'
+import type {} from '@deepseek-ai/dsh-host-webserver'
+import type { GenerateRequest } from './dto.ts'
+import { ImageStudioError, statusOfCode } from './errors.ts'
+import { PARAM_CATALOG } from './params/catalog.ts'
+import { ParamValidationError } from './params/spec.ts'
+import { listProtocols } from './provider/registry.ts'
+import type { ImageStudioService } from './service.ts'
+
+const ROUTE_PREFIX = '/dsh-plus/image-studio'
+
+function sendJson(res: ServerResponse, status: number, body: unknown): void {
+  res.writeHead(status, { 'content-type': 'application/json; charset=utf-8' })
+  res.end(JSON.stringify(body))
+}
+
+function readBody(req: IncomingMessage): Promise<string> {
+  return new Promise((resolve, reject) => {
+    const chunks: Buffer[] = []
+    req.on('data', (chunk: Buffer) => chunks.push(chunk))
+    req.on('end', () => resolve(Buffer.concat(chunks).toString('utf8')))
+    req.on('error', reject)
+  })
+}
+
+/** 统一错误结算：ImageStudioError/ParamValidationError 按码映射，其余 500。 */
+function sendError(res: ServerResponse, error: unknown): void {
+  if (error instanceof ImageStudioError) {
+    sendJson(res, statusOfCode(error.code), { error: error.code, message: error.message })
+    return
+  }
+  if (error instanceof ParamValidationError) {
+    sendJson(res, 400, { error: 'invalid-request', message: error.message })
+    return
+  }
+  sendJson(res, 500, {
+    error: 'internal',
+    message: error instanceof Error ? error.message : String(error),
+  })
+}
+
+/** 端点处理函数表（path 段 → handler）。 */
+type Handler = (req: IncomingMessage, res: ServerResponse, rest: string) => Promise<void>
+
+function buildHandlers(service: ImageStudioService): Record<string, Handler> {
+  return {
+    async generate(_req, res, rest) {
+      if (rest !== '') throw new ImageStudioError('invalid-request', '未知路径')
+      if (method(_req) !== 'POST') {
+        sendJson(res, 405, { error: 'POST only' })
+        return
+      }
+      const body = JSON.parse(await readBody(_req)) as GenerateRequest
+      const taskId = await service.submitGenerate(body)
+      sendJson(res, 202, { taskId })
+    },
+    async tasks(_req, res, rest) {
+      // /tasks 与 /tasks/<id> 与 /tasks/<id>/cancel
+      if (rest === '') {
+        sendJson(res, 200, { tasks: service.taskWires() })
+        return
+      }
+      const [taskId, action] = rest.split('/')
+      if (taskId === undefined || taskId.length === 0) {
+        throw new ImageStudioError('invalid-request', '缺少任务 id')
+      }
+      if (action === 'cancel') {
+        if (method(_req) !== 'POST') {
+          sendJson(res, 405, { error: 'POST only' })
+          return
+        }
+        const ok = service.cancelTask(taskId)
+        sendJson(res, ok ? 200 : 409, ok ? { ok: true } : { error: 'task-not-runnable' })
+        return
+      }
+      if (action !== undefined) throw new ImageStudioError('invalid-request', `未知操作：${action}`)
+      const wire = service.taskWire(taskId)
+      if (wire === null) throw new ImageStudioError('unknown-task', `任务不存在：${taskId}`)
+      sendJson(res, 200, wire)
+    },
+    async gallery(_req, res, rest) {
+      const [itemId] = rest.split('/')
+      if (itemId === undefined || itemId === '') {
+        if (method(_req) !== 'GET') {
+          sendJson(res, 405, { error: 'GET only' })
+          return
+        }
+        const items = await service.gallery()
+        sendJson(res, 200, { items, total: items.length })
+        return
+      }
+      if (itemId === 'credentials' || itemId === 'providers') return
+      if (method(_req) === 'DELETE') {
+        const removed = await service.deleteGalleryItem(itemId)
+        sendJson(res, removed ? 200 : 404, removed ? { ok: true } : { error: 'not-found' })
+        return
+      }
+      if (method(_req) !== 'GET') {
+        sendJson(res, 405, { error: 'GET or DELETE only' })
+        return
+      }
+      const items = await service.gallery()
+      const item = items.find((entry) => entry.id === itemId)
+      if (item === undefined) {
+        sendJson(res, 404, { error: 'not-found' })
+        return
+      }
+      sendJson(res, 200, item)
+    },
+    async images(_req, res, rest) {
+      const imageId = rest.replace(/\/$/, '')
+      if (imageId.length === 0 || imageId.includes('/')) {
+        sendJson(res, 404, { error: 'not-found' })
+        return
+      }
+      const bytes = await service.imageBytes(imageId)
+      if (bytes === null) {
+        sendJson(res, 404, { error: 'not-found' })
+        return
+      }
+      const mime = bytes.ext === 'jpg' ? 'image/jpeg' : `image/${bytes.ext}`
+      res.writeHead(200, { 'content-type': mime, 'cache-control': 'private, max-age=3600' })
+      res.end(Buffer.from(bytes.data))
+    },
+    async credentials(_req, res, rest) {
+      const refName = rest.replace(/\/$/, '')
+      if (refName.length === 0) {
+        sendJson(res, 400, { error: 'invalid-request', message: '缺少凭据引用名' })
+        return
+      }
+      if (method(_req) === 'GET') {
+        sendJson(res, 200, await service.credentialStatus(refName))
+        return
+      }
+      if (method(_req) === 'POST') {
+        const body = JSON.parse(await readBody(_req)) as { value?: unknown }
+        if (typeof body.value !== 'string' || body.value.length === 0) {
+          sendJson(res, 400, { error: 'invalid-request', message: 'value 必须是非空字符串' })
+          return
+        }
+        await service.setCredential(refName, body.value)
+        sendJson(res, 200, { ok: true })
+        return
+      }
+      if (method(_req) === 'DELETE') {
+        await service.unsetCredential(refName)
+        sendJson(res, 200, { ok: true })
+        return
+      }
+      sendJson(res, 405, { error: 'GET/POST/DELETE only' })
+    },
+    async providers(_req, res, rest) {
+      if (rest !== '' || method(_req) !== 'GET') {
+        sendJson(res, rest !== '' ? 404 : 405, { error: 'GET /providers only' })
+        return
+      }
+      sendJson(res, 200, {
+        protocols: listProtocols(),
+        params: PARAM_CATALOG,
+      })
+    },
+    async presets(_req, res, rest) {
+      // 预设读写走官方 settings RPC；本端点仅提供只读快照（懒人通道）。
+      if (rest !== '' || method(_req) !== 'GET') {
+        sendJson(res, 405, { error: 'GET /presets only' })
+        return
+      }
+      sendJson(res, 200, service.presets())
+    },
+  }
+}
+
+/** 请求方法小写化。 */
+function method(req: IncomingMessage): string {
+  return (req.method ?? 'GET').toUpperCase()
+}
+
+/** 路由分发（prefix 单注册 + 内部分段）。 */
+export function registerImageStudioApi(ctx: Context, service: ImageStudioService): void {
+  const handlers = buildHandlers(service)
+  ctx.webServer.register({
+    kind: 'prefix',
+    path: ROUTE_PREFIX,
+    handler: (req, res) => {
+      const url = new URL(req.url ?? '/', 'http://localhost')
+      const segments = url.pathname.slice(ROUTE_PREFIX.length).replace(/^\//, '')
+      const [head, ...tail] = segments.split('/')
+      const rest = tail.join('/')
+      void (async () => {
+        if (head === undefined || head === '') {
+          sendJson(res, 404, { error: 'unknown endpoint' })
+          return
+        }
+        const handler = handlers[head]
+        if (handler === undefined) {
+          sendJson(res, 404, { error: `unknown endpoint: ${head}` })
+          return
+        }
+        await handler(req, res, rest)
+      })().catch((error: unknown) => sendError(res, error))
+    },
+  })
+}

package/src/client/api.ts

@@ -0,0 +1,89 @@
+/**
+ * 数据端点通道（前端预留）：同源 fetch 封装，类型与 dto.ts 对齐。
+ * 本次仅交付通道层，不交付调用它的界面。
+ * @module image-studio/client/api
+ */
+import { getJson, postJson } from '@dsh-plus/shared/client'
+import type {
+  CredentialStatusWire,
+  GalleryItem,
+  GalleryListWire,
+  GenerateAccepted,
+  GenerateRequest,
+  PresetsWire,
+  ProvidersWire,
+  TaskWire,
+} from '../dto.ts'
+
+const BASE = '/dsh-plus/image-studio'
+
+/** 提交生图任务。 */
+export function generate(request: GenerateRequest): Promise<GenerateAccepted> {
+  return postJson<GenerateAccepted>(`${BASE}/generate`, request)
+}
+
+/** 批量任务轮询。 */
+export function fetchTasks(): Promise<{ tasks: TaskWire[] }> {
+  return getJson(`${BASE}/tasks`)
+}
+
+/** 单任务查询。 */
+export function fetchTask(taskId: string): Promise<TaskWire> {
+  return getJson(`${BASE}/tasks/${taskId}`)
+}
+
+/** 取消任务。 */
+export function cancelTask(taskId: string): Promise<{ ok: boolean }> {
+  return postJson(`${BASE}/tasks/${taskId}/cancel`)
+}
+
+/** 画廊列表。 */
+export function fetchGallery(): Promise<GalleryListWire> {
+  return getJson(`${BASE}/gallery`)
+}
+
+/** 画廊条目详情（含参数回放）。 */
+export function fetchGalleryItem(itemId: string): Promise<GalleryItem> {
+  return getJson(`${BASE}/gallery/${itemId}`)
+}
+
+/** 删除画廊条目。 */
+export function deleteGalleryItem(itemId: string): Promise<{ ok: boolean }> {
+  return fetch(`${BASE}/gallery/${itemId}`, {
+    method: 'DELETE',
+    credentials: 'same-origin',
+  }).then((res) => res.json() as Promise<{ ok: boolean }>)
+}
+
+/** 图片 URL（<img src> 直连，非 fetch）。 */
+export function imageUrl(imageId: string): string {
+  return `${BASE}/images/${imageId}`
+}
+
+/** 凭据状态（describe，永不回传值）。 */
+export function fetchCredentialStatus(refName: string): Promise<CredentialStatusWire> {
+  return getJson(`${BASE}/credentials/${refName}`)
+}
+
+/** 设置凭据值。 */
+export function setCredential(refName: string, value: string): Promise<{ ok: boolean }> {
+  return postJson(`${BASE}/credentials/${refName}`, { value })
+}
+
+/** 删除凭据。 */
+export function unsetCredential(refName: string): Promise<{ ok: boolean }> {
+  return fetch(`${BASE}/credentials/${refName}`, {
+    method: 'DELETE',
+    credentials: 'same-origin',
+  }).then((res) => res.json() as Promise<{ ok: boolean }>)
+}
+
+/** 协议 registry + 参数目录。 */
+export function fetchProviders(): Promise<ProvidersWire> {
+  return getJson(`${BASE}/providers`)
+}
+
+/** 预设只读快照（读写走官方 settings RPC）。 */
+export function fetchPresets(): Promise<PresetsWire> {
+  return getJson(`${BASE}/presets`)
+}

package/src/client/card.tsx

@@ -0,0 +1,14 @@
+/**
+ * 配置卡片占位组件：本次交付为空壳（不做前端设计与编码）。
+ * 后续版本在此渲染三组预设编辑与凭据管理；keyed 槽位契约已声明。
+ * @module image-studio/client/card
+ */
+
+/** 占位组件。 */
+export function StudioConfigCard(props: { t?: (key: string) => string }): unknown {
+  const t = props.t ?? ((key: string) => key)
+  const el = document.createElement('div')
+  el.className = 'dsh-plus-image-studio-card-placeholder'
+  el.textContent = t('cardPlaceholder')
+  return { type: el, props: {} }
+}

package/src/client/client.ts

@@ -0,0 +1,75 @@
+/**
+ * 浏览器半入口（本次预留空壳，不做界面设计与编码）：
+ * - 注册独立设置页占位（settings.section），声明画廊/生图页后续挂载点；
+ * - 注册 settings.plugin.item 配置卡片占位（key = settings 命名空间）。
+ * 数据通道与插槽契约见 docs/README.md「前端接入点」。
+ * @module @dsh-plus/image-studio/client
+ */
+import type { Context } from '@deepseek-ai/cordis'
+import { StudioConfigCard } from './card.tsx'
+import { en, NS, zh } from './i18n.ts'
+import { StudioSection } from './section.tsx'
+import { injectCardStyles, injectSectionStyle } from './styles.ts'
+
+export const name = 'dsh-plus-image-studio'
+
+/** 浏览器半需要的 cordis 服务 key（loader 据此注入）。 */
+export const inject = ['slots', 'locale', 'remote', 'remote.settings'] as const
+
+interface SlotsLike {
+  inject(key: string, callback: () => unknown): unknown
+  register(options: Record<string, unknown>, component: unknown): () => void
+}
+
+interface LocaleLike {
+  register(ns: string, dict: { zh: Record<string, string>; en: Record<string, string> }): () => void
+  bind(ns: string): (key: string) => string
+}
+
+interface ClientContext {
+  slots: SlotsLike
+  locale: LocaleLike
+  effect(execute: () => () => void, label?: string): unknown
+}
+
+export function apply(ctx: Context): void {
+  const c = ctx as unknown as ClientContext
+  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,
+    ),
+  )
+
+  // 配置卡片占位（settings.plugin.item：keyed 槽位，key = settings 命名空间）。
+  c.slots.inject('settings.plugin.item', () =>
+    c.slots.register(
+      {
+        name: 'settings.plugin.item',
+        key: 'dsh-plus-image-studio',
+        locale: NS,
+        inject: () => ({ t }),
+      },
+      StudioConfigCard,
+    ),
+  )
+}

package/src/client/i18n.ts

@@ -0,0 +1,20 @@
+/**
+ * i18n 字典（zh 为主，en 兜底）；NS 与 settings 命名空间分离，
+ * 仅承载前端文案 key。本次只含占位文案。
+ * @module image-studio/client/i18n
+ */
+
+/** locale 命名空间。 */
+export const NS = 'dsh-plus-image-studio'
+
+export const zh = {
+  nav: '图像工作室',
+  placeholder: '生图工作台与画廊将在后续版本提供',
+  cardPlaceholder: '图像工作室配置（预设/凭据管理将在后续版本提供）',
+}
+
+export const en = {
+  nav: 'Image Studio',
+  placeholder: 'Image workspace and gallery arrive in a later release',
+  cardPlaceholder: 'Image Studio settings (preset/credential management arrives later)',
+}

package/src/client/section.tsx

@@ -0,0 +1,14 @@
+/**
+ * 独立设置页占位组件：本次交付为空壳（不做前端设计与编码）。
+ * 后续版本在此渲染生图工作台与画廊；插槽契约已按官方 settings.section 形态声明。
+ * @module image-studio/client/section
+ */
+
+/** 占位组件（props 形态对齐 settings.section 四 share 注入）。 */
+export function StudioSection(props: { t?: (key: string) => string }): unknown {
+  const t = props.t ?? ((key: string) => key)
+  const el = document.createElement('div')
+  el.className = 'dsh-plus-image-studio-section-placeholder'
+  el.textContent = t('placeholder')
+  return { type: el, props: {} }
+}

package/src/client/styles.ts

@@ -0,0 +1,33 @@
+/**
+ * 画廊/生图占位样式：本次交付仅注入极简占位类名（无视觉设计）。
+ * 沿用官方约定 <style data-plugin data-plugin-css>，HMR 按此卸载。
+ * @module image-studio/client/styles
+ */
+
+const PKG = '@dsh-plus/image-studio'
+
+/** 注入设置页占位样式。 */
+export function injectSectionStyle(): HTMLStyleElement | null {
+  return inject(
+    'dsh-plus-image-studio-section',
+    '.dsh-plus-image-studio-section-placeholder{padding:16px;opacity:.6}',
+  )
+}
+
+/** 注入配置卡片占位样式。 */
+export function injectCardStyles(): HTMLStyleElement | null {
+  return inject(
+    'dsh-plus-image-studio-card',
+    '.dsh-plus-image-studio-card-placeholder{padding:8px;opacity:.6}',
+  )
+}
+
+function inject(id: string, css: string): HTMLStyleElement | null {
+  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
+}

package/src/config.ts

@@ -0,0 +1,90 @@
+/**
+ * 配置单一事实源：cordis 行级 Config（组合默认）与 settings namespace
+ * （用户层，$DSH_HOME/settings.yaml 热生效）共用同一 schemastery schema。
+ * 三组纯用户配置：提示词预设 / 参数预设 / 提供商预设（API key 不在此，
+ * 走 credentials，引用名由 preset id 派生）。
+ * @module image-studio/config
+ */
+import z from '@deepseek-ai/schemastery'
+
+import { SETTINGS_NS as NS_LITERAL } from './ns.ts'
+
+/** settings 命名空间（字面量即合法命名空间，编译期校验）。 */
+export const SETTINGS_NS = NS_LITERAL
+
+// dts 可移植性：嵌套 schema 精确类型经 TypeT 消费，显式断掉推断链
+// （同 usage-panel/config 的既有约定）。
+/* biome-ignore lint/suspicious/noExplicitAny: 嵌套 schema 的 dts 可移植性 */
+const PromptPreset: any = z.object({
+  id: z.string().required().description('预设 id（稳定标识，删除级联引用）'),
+  name: z.string().required().description('预设名称'),
+  text: z.string().required().description('提示词模板'),
+})
+
+/* biome-ignore lint/suspicious/noExplicitAny: 嵌套 schema 的 dts 可移植性 */
+const ParamPreset: any = z.object({
+  id: z.string().required().description('预设 id'),
+  name: z.string().required().description('预设名称'),
+  endpoint: z.string().required().description('适用端点：generation | edit'),
+  /** 参数表结构由 params/spec 校验，settings 层存原始 JSON。 */
+  paramSpecs: z.any().required().description('参数开关表（ParamSpecMap JSON）'),
+})
+
+/* biome-ignore lint/suspicious/noExplicitAny: 嵌套 schema 的 dts 可移植性 */
+const ProviderPreset: any = z.object({
+  id: z.string().required().description('预设 id'),
+  name: z.string().required().description('预设名称'),
+  protocol: z.string().required().description('协议 id（如 openai-images）'),
+  baseUrl: z.string().required().description('API 基础地址（含 /v1）'),
+  model: z.string().required().description('模型 id'),
+  credentialRef: z.string().required().description('凭据引用名（IMAGE_STUDIO_PRESET_*）'),
+  extraHeaders: z.dict(z.string()).description('附加请求头（部分中转需要）').default({}),
+})
+
+export const Config = z.object({
+  promptPresets: z.array(PromptPreset).description('提示词预设').default([]),
+  paramPresets: z.array(ParamPreset).description('参数预设').default([]),
+  providerPresets: z.array(ProviderPreset).description('提供商预设').default([]),
+  maxConcurrent: z.number().min(0).max(16).description('生图任务并发上限（0 = 不限）').default(3),
+  requestTimeoutMs: z
+    .number()
+    .min(10_000)
+    .max(600_000)
+    .description('单请求超时（毫秒；生图长耗时，默认 5 分钟）')
+    .default(300_000),
+  proxy: z.string().description('上游请求代理（空 = 直连）').default(''),
+  galleryMaxItems: z
+    .number()
+    .min(0)
+    .max(10_000)
+    .description('画廊保留上限（条，0 = 不清理；超限按最旧删除）')
+    .default(500),
+})
+
+export type ImageStudioConfig = Schemastery.TypeT<typeof Config>
+
+/** 提示词预设（解析后视图）。 */
+export interface PromptPresetEntry {
+  id: string
+  name: string
+  text: string
+}
+
+/** 参数预设（解析后视图）。 */
+export interface ParamPresetEntry {
+  id: string
+  name: string
+  endpoint: 'generation' | 'edit'
+  paramSpecs: unknown
+}
+
+/** 提供商预设（解析后视图）。 */
+export interface ProviderPresetEntry {
+  id: string
+  name: string
+  protocol: string
+  baseUrl: string
+  model: string
+  credentialRef: string
+  extraHeaders: Record<string, string>
+}

package/src/credentials.ts

@@ -0,0 +1,22 @@
+/**
+ * 凭据引用名派生与校验：提供商预设 id → IMAGE_STUDIO_PRESET_<ID>。
+ * 规则对齐《插件存储规范》：大写下划线、全大写、前缀属主。
+ * 纯函数，零依赖。
+ * @module image-studio/credentials
+ */
+
+/** 引用名前缀（属主段）。 */
+const REF_PREFIX = 'IMAGE_STUDIO_PRESET_'
+
+/** 预设 id 是否合法（kebab-case，用于引用名派生）。 */
+export function isValidPresetId(id: string): boolean {
+  return /^[a-z][a-z0-9-]*$/.test(id) && id.length <= 64
+}
+
+/** 预设 id → 凭据引用名（kebab → SNAKE 大写）。 */
+export function credentialRefNameOf(presetId: string): string {
+  if (!isValidPresetId(presetId)) {
+    throw new Error(`非法提供商预设 id：${JSON.stringify(presetId)}`)
+  }
+  return `${REF_PREFIX}${presetId.replaceAll('-', '_').toUpperCase()}`
+}