@dickpy/dsh-imagegen 1.5.1 → 1.5.3

package/src/engine.ts

@@ -84,6 +84,13 @@ function isZhipuImage(model: string): boolean {
   return modelFamily(model) === 'zhipu'
 }
 
+/** Whether the model is Alibaba Qwen-Image, which speaks the DashScope native
+ *  multimodal-generation contract (NOT OpenAI-compatible): a chat-style
+ *  messages body, `宽*高` pixel sizes, and image URLs in the reply content. */
+function isQwenImage(model: string): boolean {
+  return modelFamily(model) === 'qwen'
+}
+
 function isGlmImage(model: string): boolean {
   return /^glm-image(?:-|$)/i.test(model.trim())
 }
@@ -101,6 +108,42 @@ function seedreamSize(quality: string): string {
   return '2K'
 }
 
+/** The panel's aspect ratios mapped to Qwen-Image's `宽*高` pixel sizes.
+ *  The classic series (qwen-image / -plus / -max) documents this fixed list;
+ *  2.0 / 3.0-series models accept any size within their pixel budget and
+ *  recommend the larger set. */
+const QWEN_SIZE_CLASSIC: Readonly<Record<string, string>> = {
+  '16:9': '1664*928',
+  '21:9': '1664*928',
+  '4:3': '1472*1104',
+  '3:2': '1472*1104',
+  '1:1': '1328*1328',
+  '3:4': '1104*1472',
+  '2:3': '1104*1472',
+  '9:16': '928*1664',
+}
+
+const QWEN_SIZE_HD: Readonly<Record<string, string>> = {
+  '16:9': '2688*1536',
+  '21:9': '2688*1536',
+  '4:3': '2368*1728',
+  '3:2': '2368*1728',
+  '1:1': '2048*2048',
+  '3:4': '1728*2368',
+  '2:3': '1728*2368',
+  '9:16': '1536*2688',
+}
+
+/** Versioned ids (qwen-image-2.0 / -3.0-pro / …) take the large size set. */
+function isVersionedQwenImage(model: string): boolean {
+  return /^qwen-image-\d+\.\d/i.test(model.trim())
+}
+
+function qwenSize(model: string, ratio: string): string | undefined {
+  if (ratio === '' || ratio === 'auto') return undefined
+  return (isVersionedQwenImage(model) ? QWEN_SIZE_HD : QWEN_SIZE_CLASSIC)[ratio]
+}
+
 /** The panel's aspect ratios mapped to the closest OpenAI pixel size
  *  (gpt-image-2 / generic OpenAI-compatible endpoints). */
 const OPENAI_SIZE_BY_RATIO: Readonly<Record<string, string>> = {
@@ -472,6 +515,110 @@ async function requestOneImage(
   }))
 }
 
+/**
+ * Qwen-Image (DashScope native multimodal-generation): one chat-style request
+ * carries the prompt (plus the reference image for edit mode) and answers
+ * synchronously with image URLs in the reply content. The versioned series
+ * batches natively (n ≤ 6; the panel caps at 4), the classic series is
+ * single-image per call.
+ */
+async function generateQwenImage(
+  baseUrl: string,
+  upstream: UpstreamConfig,
+  request: GenerateRequest,
+  options: { signal?: AbortSignal },
+): Promise<GenerateResult> {
+  const model = wireModel(request)
+  const content: Array<Record<string, unknown>> = []
+  if (request.mode === 'edit') {
+    if (typeof request.image !== 'string' || request.image === '') {
+      throw new ImageGenError('图生图需要上传参考图片', 'edit-image-missing')
+    }
+    // DashScope multimodal messages take the reference image as a content
+    // item; a base64 data URI rides in the same field as a remote URL.
+    const parsed = parseDataUrl(request.image)
+    if (parsed === undefined) throw new ImageGenError('参考图片格式无效', 'edit-image-invalid')
+    const bytes = Buffer.from(parsed.base64, 'base64')
+    if (bytes.byteLength > MAX_EDIT_IMAGE_BYTES) {
+      throw new ImageGenError('参考图片超过 10MB 上限', 'edit-image-too-large')
+    }
+    content.push({ image: request.image })
+  }
+  content.push({ text: request.prompt })
+
+  const batchable = isVersionedQwenImage(model)
+  const count = batchable ? clampCount(request.n) : 1
+  const size = qwenSize(model, request.size)
+  const body = {
+    model,
+    input: { messages: [{ role: 'user', content }] },
+    parameters: {
+      ...size !== undefined ? { size } : {},
+      ...count > 1 ? { n: count } : {},
+    },
+  }
+
+  const budget = requestSignal(options.signal, UPSTREAM_TIMEOUT_MS)
+  let response: Response
+  try {
+    response = await fetch(`${baseUrl}/services/aigc/multimodal-generation/generation`, {
+      method: 'POST',
+      headers: {
+        authorization: `Bearer ${upstream.apiKey.trim()}`,
+        'content-type': 'application/json',
+      },
+      body: JSON.stringify(body),
+      signal: budget.signal,
+    })
+  } catch (error) {
+    const message = error instanceof Error ? error.message : String(error)
+    if (/aborter/i.test(message) || /timeout/i.test(message)) {
+      throw new ImageGenError('上游接口响应超时（240 秒）', 'upstream-timeout')
+    }
+    throw new ImageGenError(`无法连接上游接口：${message}`, 'upstream-unreachable')
+  } finally {
+    budget.dispose()
+  }
+
+  let payload: unknown
+  try {
+    payload = await response.json()
+  } catch {
+    throw new ImageGenError(`上游接口返回了非 JSON 响应（HTTP ${response.status}）`, 'upstream-invalid')
+  }
+  if (!response.ok || payload === null || typeof payload !== 'object') {
+    throw new ImageGenError(upstreamMessage(payload, response.status), 'upstream-rejected')
+  }
+
+  // output.choices[].message.content[] mixes text and { image: url } items.
+  const record = payload as Record<string, unknown>
+  const output = record.output as Record<string, unknown> | undefined
+  const choices = output !== undefined && Array.isArray(output.choices) ? output.choices : []
+  const urls: string[] = []
+  for (const choice of choices) {
+    const message = choice !== null && typeof choice === 'object'
+      ? (choice as Record<string, unknown>).message
+      : undefined
+    const items = message !== null && typeof message === 'object' && Array.isArray((message as Record<string, unknown>).content)
+      ? (message as Record<string, unknown>).content as unknown[]
+      : []
+    for (const item of items) {
+      if (item !== null && typeof item === 'object') {
+        const image = (item as Record<string, unknown>).image
+        if (typeof image === 'string' && image !== '') urls.push(image)
+      }
+    }
+  }
+  if (urls.length === 0) {
+    throw new ImageGenError('上游响应缺少图片内容', 'upstream-empty')
+  }
+  const images = await Promise.all(urls.map(async url => {
+    const normalized = await normalizeItem({ url }, upstream)
+    return { b64: normalized.b64, mime: normalized.mime }
+  }))
+  return { images }
+}
+
 /**
  * Forward one generate request to the configured endpoint. The requested image
  * count is satisfied with N parallel single-image requests (the `n` batch
@@ -482,6 +629,7 @@ export async function generateImage(upstream: UpstreamConfig, request: GenerateR
   const baseUrl = upstream.apiUrl.trim().replace(/\/+$/, '')
   if (baseUrl === '') throw new ImageGenError('api_url 未配置：请先在「设置 → 插件 → 可配置」中填写', 'config-missing')
   if (upstream.apiKey.trim() === '') throw new ImageGenError('api_key 未配置：请先在「设置 → 插件 → 可配置」中填写', 'config-missing')
+  if (isQwenImage(wireModel(request))) return generateQwenImage(baseUrl, upstream, request, options)
   if (request.mode === 'edit' && isZhipuImage(wireModel(request))) {
     throw new ImageGenError('智谱 GLM-Image 当前仅支持文生图，请切换到文生图模式或选择支持图生图的模型', 'edit-unsupported')
   }

package/src/index.ts

@@ -20,6 +20,7 @@ import type {} from '@deepseek-ai/dsh-tools'
 import type { ImageAttachmentRef } from '@deepseek-ai/dsh-attachment'
 import { IMAGEGEN_SETTINGS_NAMESPACE, type ChannelConfig, type ModelMapping } from './protocol.ts'
 import { makeRoutes, type SettingsSeam } from './routes.ts'
+import { syncAllTemplates } from './templates-store.ts'
 import { ImageGenerationRuntime, type ChannelsView, type RuntimeChannel } from './generation-runtime.ts'
 import { registerAgentImageTools } from './agent-image-tools.ts'
 import { registerEditImageCommand } from './edit-image-command.ts'
@@ -39,7 +40,8 @@ export { ImageGenerationRuntime } from './generation-runtime.ts'
 export { registerAgentImageTools } from './agent-image-tools.ts'
 export { latestSessionImage, registerEditImageCommand } from './edit-image-command.ts'
 export { appendGallery, clearGallery, listGallery, readGalleryImage, removeGallery, updateGalleryTags } from './gallery-store.ts'
-export { listTemplates, readTemplateImage, refreshTemplates, clearTemplateMemo } from './templates-store.ts'
+export { listTemplates, readTemplateImage, refreshTemplates, sampleTemplates, syncAllTemplates, clearTemplateMemo } from './templates-store.ts'
+export { addTemplateFavorite, clearTemplateFavoritesMemo, listTemplateFavorites, removeTemplateFavorite } from './template-favorites.ts'
 export { checkForUpdate, clearUpdateCache, compareVersions, CURRENT_VERSION, installUpdate, profileFromProcess } from './updater.ts'
 
 /** The branded settings namespace of this plugin (the card edits it). */
@@ -115,7 +117,7 @@ const DEFAULT_ALLOW_AGENT_IMAGE_GENERATION = true
 const SECTION_ORDER = 150
 
 /** Model-facing announcement: plugin presence, capabilities, and limits. */
-export const IMAGEGEN_GUIDANCE = '本机已安装 dsh-imagegen 插件（DSH AI 生图）：侧边栏「AI 生图」入口。能力：通过「渠道」对接 OpenAI 兼容图像生成 API（每个渠道 = 一个 API 端点 + 各自的模型目录），支持文生图（/images/generations）与图生图（/images/edits，上传参考图，grok-imagine 模型按官方 JSON image_url 协议发送，nanobanana 系列按 aspect_ratio / image_size 参数协议发送；seedream 系列统一走 /images/generations，参考图以 JSON image 数组发送；智谱 `glm-image` 使用官方 `/api/paas/v4/images/generations`，当前仅支持文生图）。API 地址与密钥在 GUI 设置中按渠道配置，密钥仅存于本机设置文档；生成请求由本地宿主代理转发，结果以 base64 返回面板，可预览与下载。模型只能使用用户在各渠道配置目录中的模型；检测模型时会过滤聊天、Embedding 等非图片模型，但模型出现在 /models 中仍不等于其网关原生支持生图协议，遇到 Qwen、Gemini 等非 OpenAI 生图协议时应如实说明上游兼容性。可一键把满意的图片加入「画廊」。内置「提示词模板库」（面板提示词框左下角「模板库」按钮）：打包 awesome-gpt-image-2 的数百条提示词案例，可搜索、筛选与复用。Agent 可直接调用 `generate_image` 提交文生图，也可用 `edit_image` 图生图；默认保持工具调用等待直到任务完成，完成图片显示在工具调用对应的左侧结果区域，模型收到状态和附件引用，不会额外伪造用户消息。用户也可以使用 `/edit_image <修改描述>`，命令会直接读取当前对话最近图片并调用插件图片模型，不经过对话模型的图片能力检查。若明确需要后台执行，可传 `wait_for_completion: false`，之后再用 `get_image_generation_task` 查询；不要反复轮询。限制：生成消耗上游 API 额度；图片内容由上游模型生成，可能不符合预期或包含不适宜内容；api_key 以明文存储在设置文档中；参考图会发送至所配置的 API 服务；模板库在线刷新与参考图首次加载需要访问 vibeui.top。用户提到「生图 / 绘画 / 生成图片 / 文生图 / 图生图 / 画廊 / 提示词模板」时即指本插件，请据此协作。'
+export const IMAGEGEN_GUIDANCE = '本机已安装 dsh-imagegen 插件（DSH AI 生图）：侧边栏「AI 生图」入口。能力：通过「渠道」对接 OpenAI 兼容图像生成 API（每个渠道 = 一个 API 端点 + 各自的模型目录），支持文生图（/images/generations）与图生图（/images/edits，上传参考图，grok-imagine 模型按官方 JSON image_url 协议发送，nanobanana 系列按 aspect_ratio / image_size 参数协议发送；seedream 系列统一走 /images/generations，参考图以 JSON image 数组发送；智谱 `glm-image` 使用官方 `/api/paas/v4/images/generations`，当前仅支持文生图；qwen-image 系列使用阿里云 DashScope 原生接口（api_url 填 https://dashscope.aliyuncs.com/api/v1，不支持 OpenAI 兼容模式，该渠道不可复用于提示词增强，尺寸自动映射为宽*高）。API 地址与密钥在 GUI 设置中按渠道配置，密钥仅存于本机设置文档；生成请求由本地宿主代理转发，结果以 base64 返回面板，可预览与下载。模型只能使用用户在各渠道配置目录中的模型；检测模型时会过滤聊天、Embedding 等非图片模型，但模型出现在 /models 中仍不等于其网关原生支持生图协议，遇到 Qwen、Gemini 等非 OpenAI 生图协议时应如实说明上游兼容性。可一键把满意的图片加入「画廊」。内置「提示词模板库」（面板提示词框左下角「模板库」按钮）：多来源标签页（精选案例库 / 沧河案例库，后续可扩展），打包 awesome-gpt-image-2 的数百条提示词案例，可搜索、筛选、收藏（星标，宿主持久化）与复用；各来源列表独立刷新，宿主每 12 小时后台自动同步一次。Agent 可直接调用 `generate_image` 提交文生图，也可用 `edit_image` 图生图；默认保持工具调用等待直到任务完成，完成图片显示在工具调用对应的左侧结果区域，模型收到状态和附件引用，不会额外伪造用户消息。用户也可以使用 `/edit_image <修改描述>`，命令会直接读取当前对话最近图片并调用插件图片模型，不经过对话模型的图片能力检查。若明确需要后台执行，可传 `wait_for_completion: false`，之后再用 `get_image_generation_task` 查询；不要反复轮询。限制：生成消耗上游 API 额度；图片内容由上游模型生成，可能不符合预期或包含不适宜内容；api_key 以明文存储在设置文档中；参考图会发送至所配置的 API 服务；模板库在线刷新与参考图首次加载需要访问对应来源站点（vibeui.top / gpt-image2.canghe.ai）。用户提到「生图 / 绘画 / 生成图片 / 文生图 / 图生图 / 画廊 / 提示词模板」时即指本插件，请据此协作。'
 
 /** Append the live channel × model table so an Agent can honor user choices. */
 function guidanceFor(channels: RuntimeChannel[], defaultChannelId: string): string {
@@ -276,7 +278,25 @@ export function apply(ctx: Context, config?: Config): void {
           runtime,
         })
         const disposers = routes.map(route => ctx.webServer.register(route))
-        return () => { for (const dispose of disposers) dispose() }
+        // Background template sync: the upstream sources update on their own
+        // schedule, so pull every one of them shortly after start and then
+        // twice a day while the plugin stays enabled. Best-effort: failures
+        // keep the last good snapshot (bundled or previously refreshed).
+        const TEMPLATE_SYNC_INITIAL_DELAY_MS = 30_000
+        const TEMPLATE_SYNC_INTERVAL_MS = 12 * 60 * 60 * 1000
+        let syncTimer: NodeJS.Timeout | undefined
+        const runSync = (): void => {
+          if (!resolve().enabled) return
+          void syncAllTemplates().catch(() => { /* keep the last good snapshot */ })
+        }
+        const startTimer = setTimeout(runSync, TEMPLATE_SYNC_INITIAL_DELAY_MS)
+        syncTimer = setInterval(runSync, TEMPLATE_SYNC_INTERVAL_MS)
+        syncTimer.unref?.()
+        return () => {
+          clearTimeout(startTimer)
+          clearInterval(syncTimer)
+          for (const dispose of disposers) dispose()
+        }
       },
       'dsh-imagegen: routes',
     )

package/src/model-catalog.ts

@@ -8,7 +8,7 @@
  * Framework-free (pure data + regex), safe for the client bundle to inline.
  */
 
-export type ModelFamily = 'gpt-image' | 'dall-e' | 'grok' | 'nanobanana' | 'seedream' | 'zhipu' | 'unknown'
+export type ModelFamily = 'gpt-image' | 'dall-e' | 'grok' | 'nanobanana' | 'seedream' | 'zhipu' | 'qwen' | 'unknown'
 
 /** Capability/identity annotation for one model id. */
 export interface ModelCatalogEntry {
@@ -77,6 +77,14 @@ const ENTRIES: Record<Exclude<ModelFamily, 'unknown'>, Omit<ModelCatalogEntry, '
     supportsAspectRatio: false,
     qualityTiers: ['HD'],
   },
+  qwen: {
+    label: 'qwen-image',
+    labelZh: '千问图像',
+    known: true,
+    supportsEdit: true,
+    supportsAspectRatio: true,
+    qualityTiers: ['auto'],
+  },
 }
 
 /** Official Gemini image ids served by Nano Banana gateways. */
@@ -98,6 +106,7 @@ export function describeModel(model: string): ModelCatalogEntry {
   if (/^nanobanana/i.test(id) || NANOBANANA_GEMINI_IDS.has(id)) return { family: 'nanobanana', ...ENTRIES.nanobanana }
   if (/^(?:doubao-)?seedream/i.test(id)) return { family: 'seedream', ...ENTRIES.seedream }
   if (/^(?:glm-image|cogview(?:-|$))/i.test(id)) return { family: 'zhipu', ...ENTRIES.zhipu }
+  if (/^qwen-image(?:[-_.]|$)/i.test(id)) return { family: 'qwen', ...ENTRIES.qwen }
   return { family: 'unknown', label: 'unknown', labelZh: '未知协议', known: false, supportsEdit: true, supportsAspectRatio: false, qualityTiers: [] }
 }
 

package/src/presets.ts

@@ -54,6 +54,21 @@ export const IMAGE_PRESETS: PresetProvider[] = [
       { alias: 'glm-image', id: 'glm-image' },
     ],
   },
+  {
+    id: 'aliyun-dashscope-qwen',
+    name: '阿里云百炼（Qwen-Image）',
+    apiUrl: 'https://dashscope.aliyuncs.com/api/v1',
+    hint: '阿里云百炼 DashScope 原生接口：通义千问 Qwen-Image 系列（该渠道不可复用于提示词增强）',
+    models: [
+      { alias: 'qwen-image-3.0-pro', id: 'qwen-image-3.0-pro' },
+      { alias: 'qwen-image-3.0', id: 'qwen-image-3.0' },
+      { alias: 'qwen-image-2.0-pro', id: 'qwen-image-2.0-pro' },
+      { alias: 'qwen-image-2.0', id: 'qwen-image-2.0' },
+      { alias: 'qwen-image-max', id: 'qwen-image-max' },
+      { alias: 'qwen-image-plus', id: 'qwen-image-plus' },
+      { alias: 'qwen-image', id: 'qwen-image' },
+    ],
+  },
   {
     id: 'xai-grok',
     name: 'xAI（Grok）',

package/src/protocol.ts

@@ -8,7 +8,7 @@
 export const IMAGEGEN_SETTINGS_NAMESPACE = 'dsh-imagegen'
 
 /** Published package version shared by the host updater and the client UI. */
-export const PLUGIN_VERSION = '1.5.1'
+export const PLUGIN_VERSION = '1.5.3'
 
 /** Same-origin route family (loopback-only, mirroring the dsh-ssh fence). */
 export const SETTINGS_API = {
@@ -92,17 +92,68 @@ export const GALLERY_API = {
 export const HISTORY_MAX = 50
 
 /**
- * Same-origin route family for the bundled prompt-template library
- * (awesome-gpt-image-2 mirror). The case list ships inside the package and is
- * served by the host; reference images are proxied through the `image` prefix
- * route and cached on disk so repeated views never hit the network again.
+ * Same-origin route family for the prompt-template libraries. The library is
+ * multi-source: every request names a source id from {@link TEMPLATE_SOURCES},
+ * each source keeps an independent snapshot/image cache host-side, and
+ * reference images are proxied through the source-scoped `image` prefix route
+ * (`…/image/<sourceId>/<file>`) and cached on disk so repeated views never hit
+ * the network again.
  */
 export const TEMPLATES_API = {
   list: '/api/dsh-imagegen/templates/list',
   refresh: '/api/dsh-imagegen/templates/refresh',
+  sample: '/api/dsh-imagegen/templates/sample',
   image: '/api/dsh-imagegen/templates/image',
 } as const
 
+/** Same-origin route family for the user's saved (favorited) templates. */
+export const TEMPLATE_FAVORITES_API = {
+  list: '/api/dsh-imagegen/templates/favorites/list',
+  add: '/api/dsh-imagegen/templates/favorites/add',
+  remove: '/api/dsh-imagegen/templates/favorites/remove',
+} as const
+
+/** One prompt-template library source (a tab in the library overlay). */
+export interface TemplateSourceMeta {
+  /** Stable source id: snapshot dir name, image-cache dir, and request key. */
+  id: string
+  /** Tab label shown in the library overlay. */
+  label: string
+  /** Source homepage linked in the overlay footer. */
+  homepage: string
+  /** One-line description of the source (tab tooltip). */
+  description: string
+}
+
+/**
+ * The template-library source registry. Each entry is fully independent (own
+ * upstream JSON, own image pool, own refresh state) and renders as its own
+ * tab; adding a source later means appending an entry here plus a host-side
+ * fetch definition in templates-store.ts and an optional bundled snapshot.
+ */
+export const TEMPLATE_SOURCES: TemplateSourceMeta[] = [
+  {
+    id: 'vibeui',
+    label: '精选案例库',
+    homepage: 'https://vibeui.top/',
+    description: 'awesome-gpt-image-2 精选提示词案例（vibeui.top 镜像）',
+  },
+  {
+    id: 'canghe',
+    label: '沧河案例库',
+    homepage: 'https://gpt-image2.canghe.ai/',
+    description: 'GPT-Image2 Prompt Gallery（gpt-image2.canghe.ai，定期更新）',
+  },
+]
+
+/** Default source id when a request does not name one (legacy clients). */
+export const DEFAULT_TEMPLATE_SOURCE_ID = TEMPLATE_SOURCES[0]!.id
+
+/** True when the id names a registered template source. */
+export function isTemplateSourceId(id: string): boolean {
+  return TEMPLATE_SOURCES.some(source => source.id === id)
+}
+
 /** One prompt-library case as the browser consumes it. */
 export interface TemplateCase {
   /** Upstream case number (stable across refreshes). */
@@ -131,8 +182,10 @@ export interface TemplateCase {
   featured: boolean
 }
 
-/** Template-library list payload. */
+/** Template-library list payload (one source). */
 export interface TemplateListResult {
+  /** The source this list belongs to. */
+  sourceId: string
   cases: TemplateCase[]
   total: number
   /** Where the served list came from. */
@@ -143,12 +196,33 @@ export interface TemplateListResult {
   fetchedAt: string
 }
 
-/** Template-library refresh outcome. */
+/** Template-library refresh outcome (one source). */
 export interface TemplateRefreshResult {
+  sourceId: string
   total: number
   fetchedAt: string
 }
 
+/** One random inspiration pick served to the studio's empty state. */
+export interface TemplateSample {
+  /** Source the case came from (drives the image proxy URL). */
+  sourceId: string
+  /** The sampled case (full prompt is handed to the form on use). */
+  case: TemplateCase
+}
+
+/** One favorited template as persisted host-side and served to the browser. */
+export interface TemplateFavorite {
+  /** Stable key: `${sourceId}:${caseId}`. */
+  key: string
+  /** Source the case came from. */
+  sourceId: string
+  /** ISO time the favorite was saved. */
+  savedAt: string
+  /** Full case snapshot, so favorites survive upstream list churn. */
+  case: TemplateCase
+}
+
 /** Generation modes. */
 export type GenerateMode = 'text' | 'edit'
 

package/src/routes.ts

@@ -16,10 +16,11 @@ import { normalizeImageModels } from './image-models.ts'
 import { ImageGenerationRuntime, type ChannelsView } from './generation-runtime.ts'
 import { appendHistory, clearHistory, listHistory, readHistoryImage, removeHistory } from './history-store.ts'
 import { appendGallery, clearGallery, listGallery, readGalleryImage, removeGallery, updateGalleryTags } from './gallery-store.ts'
-import { listTemplates, readTemplateImage, refreshTemplates } from './templates-store.ts'
+import { listTemplates, readTemplateImage, refreshTemplates, sampleTemplates } from './templates-store.ts'
+import { addTemplateFavorite, listTemplateFavorites, removeTemplateFavorite } from './template-favorites.ts'
 import { checkForUpdate, CURRENT_VERSION, installUpdate } from './updater.ts'
 import { IMAGE_PRESETS } from './presets.ts'
-import { AGENT_IMAGE_API, CONVERSATION_IMAGE_API, GALLERY_API, GENERATE_API, HISTORY_API, IMAGEGEN_SETTINGS_NAMESPACE, IMAGE_MODEL_API, PRESETS_API, PROMPT_ENHANCE_API, SETTINGS_API, TASK_API, TEMPLATES_API, UPDATE_API, USAGE_API, type GeneratedImage, type GenerateRequest, type HistoryEntry, type HistoryEntryInput, type ModelMapping, type PresetProviderView, type TemplateListResult, type TemplateRefreshResult } from './protocol.ts'
+import { AGENT_IMAGE_API, CONVERSATION_IMAGE_API, DEFAULT_TEMPLATE_SOURCE_ID, GALLERY_API, GENERATE_API, HISTORY_API, IMAGEGEN_SETTINGS_NAMESPACE, IMAGE_MODEL_API, PRESETS_API, PROMPT_ENHANCE_API, SETTINGS_API, TASK_API, TEMPLATE_FAVORITES_API, TEMPLATES_API, UPDATE_API, USAGE_API, isTemplateSourceId, type GeneratedImage, type GenerateRequest, type HistoryEntry, type HistoryEntryInput, type ModelMapping, type PresetProviderView, type TemplateFavorite, type TemplateListResult, type TemplateRefreshResult, type TemplateSample } from './protocol.ts'
 
 /** Cap on JSON request bodies (settings ops and generate payloads are small). */
 const MAX_JSON_BODY_BYTES = 24 * 1024 * 1024
@@ -74,9 +75,16 @@ export interface ImageGenRoutesDeps {
   }
   /** Overrideable template-library backend, primarily for host integration tests. */
   templates?: {
-    list: () => Promise<TemplateListResult>
-    refresh: () => Promise<TemplateRefreshResult>
-    readImage: (file: string) => Promise<{ data: Buffer; mime: string } | undefined>
+    list: (sourceId: string) => Promise<TemplateListResult>
+    refresh: (sourceId: string) => Promise<TemplateRefreshResult>
+    sample: (count: number) => Promise<TemplateSample[]>
+    readImage: (sourceId: string, file: string) => Promise<{ data: Buffer; mime: string } | undefined>
+  }
+  /** Overrideable template-favorites backend, primarily for host integration tests. */
+  favorites?: {
+    list: () => Promise<TemplateFavorite[]>
+    add: (sourceId: string, item: TemplateFavorite['case']) => Promise<TemplateFavorite[]>
+    remove: (key: string) => Promise<TemplateFavorite[]>
   }
   /** Shared host queue, used by Agent tools and browser task endpoints. */
   runtime?: ImageGenerationRuntime
@@ -135,6 +143,13 @@ function messageOf(error: unknown): string {
   return error instanceof Error ? error.message : String(error)
 }
 
+/** Validate the { source } body of a template-library request. */
+function templateSourceOf(body: Record<string, unknown> | undefined): string | undefined {
+  const raw = body?.source
+  if (raw === undefined || raw === '') return DEFAULT_TEMPLATE_SOURCE_ID
+  return typeof raw === 'string' && isTemplateSourceId(raw) ? raw : undefined
+}
+
 function parseGenerateRequest(body: Record<string, unknown>): GenerateRequest | undefined {
   const prompt = typeof body.prompt === 'string' ? body.prompt.trim() : ''
   if (prompt === '') return undefined
@@ -311,8 +326,14 @@ export function makeRoutes(deps: ImageGenRoutesDeps): WebRoute[] {
   const templates = deps.templates ?? {
     list: listTemplates,
     refresh: refreshTemplates,
+    sample: sampleTemplates,
     readImage: readTemplateImage,
   }
+  const favorites = deps.favorites ?? {
+    list: listTemplateFavorites,
+    add: addTemplateFavorite,
+    remove: removeTemplateFavorite,
+  }
   const resolvePrompt = deps.resolvePrompt ?? (() => ({ apiUrl: '', apiKey: '', model: '' }))
   const resolveImageModels = deps.resolveImageModels ?? (() => normalizeImageModels(undefined))
 
@@ -908,8 +929,14 @@ export function makeRoutes(deps: ImageGenRoutesDeps): WebRoute[] {
       path: TEMPLATES_API.list,
       handler: async (req, res) => {
         if (!guard(req, res, 'POST')) return
+        const body = await readJsonBody(req)
+        const sourceId = templateSourceOf(body)
+        if (sourceId === undefined) {
+          writeJson(res, 200, { ok: false, code: 'templates-source-unknown', message: `未知的模板库来源：${String(body?.source ?? '')}` })
+          return
+        }
         try {
-          const result = await templates.list()
+          const result = await templates.list(sourceId)
           writeJson(res, 200, { ok: true, ...result })
         } catch (error) {
           writeJson(res, 200, { ok: false, code: 'templates-failed', message: messageOf(error) })
@@ -922,14 +949,36 @@ export function makeRoutes(deps: ImageGenRoutesDeps): WebRoute[] {
       path: TEMPLATES_API.refresh,
       handler: async (req, res) => {
         if (!guard(req, res, 'POST')) return
+        const body = await readJsonBody(req)
+        const sourceId = templateSourceOf(body)
+        if (sourceId === undefined) {
+          writeJson(res, 200, { ok: false, code: 'templates-source-unknown', message: `未知的模板库来源：${String(body?.source ?? '')}` })
+          return
+        }
         try {
-          const result = await templates.refresh()
+          const result = await templates.refresh(sourceId)
           writeJson(res, 200, { ok: true, ...result })
         } catch (error) {
           writeJson(res, 200, { ok: false, code: 'templates-refresh-failed', message: messageOf(error) })
         }
       },
     },
+    // --------------------------------------------- templates random sample
+    {
+      kind: 'exact',
+      path: TEMPLATES_API.sample,
+      handler: async (req, res) => {
+        if (!guard(req, res, 'POST')) return
+        const body = await readJsonBody(req)
+        const requested = Number(body?.count)
+        const count = Number.isFinite(requested) ? requested : 9
+        try {
+          writeJson(res, 200, { ok: true, samples: await templates.sample(count) })
+        } catch (error) {
+          writeJson(res, 200, { ok: false, code: 'templates-sample-failed', message: messageOf(error) })
+        }
+      },
+    },
     // -------------------------------------- templates image (prefix, proxied)
     {
       kind: 'prefix',
@@ -943,12 +992,17 @@ export function makeRoutes(deps: ImageGenRoutesDeps): WebRoute[] {
           writeJson(res, 405, { error: `method not allowed: ${req.method}` })
           return
         }
-        const file = imageFileFrom(req.url, TEMPLATES_API.image)
-        if (file === undefined) {
+        // Source-scoped: /image/<sourceId>/<file> (file names collide across
+        // sources, so the pool on disk is per source).
+        const raw = imageFileFrom(req.url, TEMPLATES_API.image)
+        const slash = raw?.indexOf('/') ?? -1
+        const sourceId = slash > 0 ? raw!.slice(0, slash) : ''
+        const file = slash > 0 ? raw!.slice(slash + 1) : ''
+        if (sourceId === '' || !isTemplateSourceId(sourceId) || file === '') {
           writeJson(res, 404, { error: 'not found' })
           return
         }
-        const found = await templates.readImage(file)
+        const found = await templates.readImage(sourceId, file)
         if (found === undefined) {
           writeJson(res, 404, { error: 'not found' })
           return
@@ -962,5 +1016,65 @@ export function makeRoutes(deps: ImageGenRoutesDeps): WebRoute[] {
         res.end(found.data)
       },
     },
+    // ------------------------------------------ template favorites: list
+    {
+      kind: 'exact',
+      path: TEMPLATE_FAVORITES_API.list,
+      handler: async (req, res) => {
+        if (!guard(req, res, 'POST')) return
+        try {
+          writeJson(res, 200, { ok: true, favorites: await favorites.list() })
+        } catch (error) {
+          writeJson(res, 200, { ok: false, code: 'template-favorites-failed', message: messageOf(error) })
+        }
+      },
+    },
+    // ------------------------------------------- template favorites: add
+    {
+      kind: 'exact',
+      path: TEMPLATE_FAVORITES_API.add,
+      handler: async (req, res) => {
+        if (!guard(req, res, 'POST')) return
+        const body = await readJsonBody(req)
+        const sourceId = templateSourceOf(body)
+        const rawCase = body?.case
+        if (sourceId === undefined || rawCase === null || typeof rawCase !== 'object') {
+          writeJson(res, 200, { ok: false, code: 'template-favorite-invalid', message: '收藏请求缺少有效的来源或模板数据' })
+          return
+        }
+        const record = rawCase as Record<string, unknown>
+        const id = Number(record.id)
+        const title = typeof record.title === 'string' ? record.title.trim() : ''
+        const prompt = typeof record.prompt === 'string' ? record.prompt.trim() : ''
+        if (!Number.isInteger(id) || title === '' || prompt === '') {
+          writeJson(res, 200, { ok: false, code: 'template-favorite-invalid', message: '收藏请求缺少有效的模板数据' })
+          return
+        }
+        try {
+          writeJson(res, 200, { ok: true, favorites: await favorites.add(sourceId, rawCase as TemplateFavorite['case']) })
+        } catch (error) {
+          writeJson(res, 200, { ok: false, code: 'template-favorites-failed', message: messageOf(error) })
+        }
+      },
+    },
+    // ---------------------------------------- template favorites: remove
+    {
+      kind: 'exact',
+      path: TEMPLATE_FAVORITES_API.remove,
+      handler: async (req, res) => {
+        if (!guard(req, res, 'POST')) return
+        const body = await readJsonBody(req)
+        const key = typeof body?.key === 'string' ? body.key : ''
+        if (key === '') {
+          writeJson(res, 200, { ok: false, code: 'template-favorite-invalid', message: '取消收藏请求缺少模板标识' })
+          return
+        }
+        try {
+          writeJson(res, 200, { ok: true, favorites: await favorites.remove(key) })
+        } catch (error) {
+          writeJson(res, 200, { ok: false, code: 'template-favorites-failed', message: messageOf(error) })
+        }
+      },
+    },
   ]
 }