@mokuyoaxis/dsh-iris 0.2.2 → 0.2.4

package/lib/dsh-text-model-adapter.js

@@ -65,7 +65,11 @@ export async function prepareDshTextModelPort(textModel, binding, { signal } = {
       if (signal?.aborted) throw abortError(signal, 'prepare', 'not_invoked');
       return textModel.resolveModelInfo(route.provider, route.model, signal);
     }), signal, 'prepare', 'not_invoked'); }
-    catch (_) { if (signal?.aborted) throw abortError(signal, 'prepare', 'not_invoked'); }
+    catch (_) {
+      if (signal?.aborted) throw abortError(signal, 'prepare', 'not_invoked');
+      // 查询失败不同于成功查询但能力缺失；不要吞掉错误后进入付费生成。
+      throw new ModelPortError('IRIS_MODEL_UNAVAILABLE', { stage: 'prepare', invocation: 'not_invoked' });
+    }
   }
   if (signal?.aborted) throw abortError(signal, 'prepare', 'not_invoked');
   return createDshTextModelPort(textModel, { ...route, sessionId }, { metadata });
@@ -73,7 +77,16 @@ export async function prepareDshTextModelPort(textModel, binding, { signal } = {
 
 /** 已绑定事实的纯构造；用于缓存元数据/协议 fixture，不执行元数据查询。 */
 export function createDshTextModelPort(textModel, binding, { metadata } = {}) {
-  return createDshBoundModelPort(textModel, binding, { metadata });
+  const bound = createDshBoundModelPort(textModel, binding, { metadata });
+  const modalities = metadata?.inputModalities;
+  if (modalities !== undefined) {
+    if (!Array.isArray(modalities) || modalities.some(value => typeof value !== 'string' || !value.trim())) {
+      throw new ModelPortError('IRIS_MODEL_PROTOCOL_INVALID', { stage: 'prepare', invocation: 'not_invoked' });
+    }
+    if (!modalities.includes('text')) throw new ModelPortError('IRIS_MODEL_UNSUPPORTED', { stage: 'prepare', invocation: 'not_invoked' });
+  }
+  // 缺失能力只表示未知；宿主接受文本输入也不证明远端必定只返回文字。
+  return Object.freeze({ ...bound, textInput: modalities === undefined ? 'unknown' : 'supported' });
 }
 
 /** 文本与视觉共用经过验证的 DSH 事件读取器；图片桥接仅由视觉适配器注入。 */

package/lib/generation-input.js

@@ -2,11 +2,13 @@
 
 import path from 'node:path';
 import fs from 'node:fs';
+import { normalizeMusicOptions } from './music-options.js';
 
 const FIELDS = Object.freeze({
   image: ['prompt', 'size', 'n', 'source_artifact_id'],
   video: ['prompt', 'size', 'duration', 'img_data_url', 'first_frame_path', 'audio_path', 'resolution'],
   tts: ['text', 'voice'],
+  music: ['prompt', 'timeout_ms', 'retry_502', 'retry_delay_ms'],
   transcribe: ['audio_url', 'audio_path']
 });
 
@@ -47,6 +49,7 @@ export function normalizeGenerationInput(capability, input, { allowAudioPath = f
   const providerInput = {};
   let audioPath;
   let sourceArtifactId;
+  let musicOptions;
   let firstFramePath, videoMode;
   if (capability === 'video') {
     audioPath = String(input.audio_path || '').trim();
@@ -101,6 +104,12 @@ export function normalizeGenerationInput(capability, input, { allowAudioPath = f
     const voice = text(input.voice, 'voice', 64);
     if (voice !== undefined) providerInput.voice = voice;
   }
+  if (capability === 'music') {
+    providerInput.prompt = text(input.prompt, 'prompt', 20000, true);
+    try { musicOptions = normalizeMusicOptions(input); }
+    catch (error) { fail(error.message); }
+    providerInput.timeoutMs = musicOptions.timeoutMs;
+  }
   if (capability === 'transcribe') {
     const audioUrl = String(input.audio_url || '').trim();
     audioPath = String(input.audio_path || '').trim();
@@ -119,6 +128,7 @@ export function normalizeGenerationInput(capability, input, { allowAudioPath = f
   return Object.freeze({
     modelRef,
     providerInput: Object.freeze(providerInput),
+    ...(musicOptions ? { musicOptions } : {}),
     ...(sourceArtifactId ? { sourceArtifactId } : {}),
     ...(audioPath ? { audioPath } : {}),
     ...(capability === 'video' ? { firstFramePath, videoMode } : {})

package/lib/host-runtime.js

@@ -10,9 +10,11 @@ export const IRIS_PLUGIN_ID = '@mokuyoaxis/dsh-iris';
 export const HOST_CLIENT_PROTOCOL_VERSION = 0;
 
 export const EXPECTED_IRIS_TOOLS = Object.freeze([
+  'iris_import_image',
   'iris_draw_image',
   'iris_edit_image',
   'iris_generate_video',
+  'iris_generate_music',
   'iris_speak_text',
   'iris_transcribe_audio',
   'iris_task_status',
@@ -28,8 +30,9 @@ export const EXPECTED_IRIS_TOOLS = Object.freeze([
 ]);
 
 export const EXPECTED_IRIS_SKILLS = Object.freeze([
-  'iris-verify-ui',
-  'iris-compose-media'
+  'iris-use',
+  'iris-compose-media',
+  'iris-verify-ui'
 ]);
 
 export const EXPECTED_IRIS_ROUTES = Object.freeze([

package/lib/image-edit-input.js

@@ -1,20 +1,22 @@
 'use strict';
-/** 聊天改图只接受当前 Core 中的静态图片；输入原字节不进入 Task 记录。 */
+/** 改图只接受当前 Core 中的静态图片；输入原字节不进入 Task 记录。 */
 import sharp from 'sharp';
 import { inspectCoreArtifact, readCoreArtifactBytes } from './core-artifacts.js';
 import { waitForModelWork } from './model-call-runtime.js';
+import { supportsImageEdit } from './provider-protocol.js';
 
 function invalid(message) {
   return Object.assign(new Error(message), { code: 'IRIS_IMAGE_EDIT_INPUT_INVALID' });
 }
 
 export function imageEditCandidates(candidates) {
+  const supported = candidate => supportsImageEdit(candidate.adapter.protocol, candidate.providerModel);
   if (candidates.some(candidate => candidate.selectionReason === 'explicit'
-      && candidate.adapter.protocol !== 'openai-chat-images')) {
-    throw invalid('指定模型的图片协议不支持聊天改图，请选择 openai-chat-images 模型');
+      && !supported(candidate))) {
+    throw invalid('指定模型的图片协议不支持此类改图，请选择聊天生图模型或 DashScope Qwen 原生改图模型');
   }
-  const selected = candidates.filter(candidate => candidate.adapter.protocol === 'openai-chat-images');
-  if (!selected.length) throw invalid('未配置可用的 openai-chat-images 生图模型，无法编辑原图');
+  const selected = candidates.filter(supported);
+  if (!selected.length) throw invalid('当前生图名单没有可用的聊天生图或 DashScope Qwen 改图模型');
   return selected;
 }
 

package/lib/image-import.js

@@ -0,0 +1,61 @@
+'use strict';
+
+import { open } from 'node:fs/promises';
+import sharp from 'sharp';
+
+export const MAX_IMPORT_IMAGE_BYTES = 20 * 1024 * 1024;
+const TYPES = Object.freeze({ png: 'image/png', jpeg: 'image/jpeg', webp: 'image/webp' });
+
+function invalid(message) {
+  return Object.assign(new Error(message), { code: 'IRIS_IMAGE_IMPORT_INVALID' });
+}
+
+function checkSize(size) {
+  if (!size || size > MAX_IMPORT_IMAGE_BYTES) throw invalid('导入图片必须非空，且不超过20 MiB');
+}
+
+/** 只读一次有界快照；后续校验和保存使用同一份字节，不再复制变化中的源路径。 */
+export async function readImportImage({ filePath, imageBytes }, signal) {
+  signal.throwIfAborted();
+  let bytes;
+  if (filePath) {
+    let file;
+    try {
+      file = await open(filePath, 'r');
+      const stat = await file.stat();
+      if (!stat.isFile()) throw invalid('导入来源必须是普通图片文件');
+      checkSize(stat.size);
+      bytes = Buffer.alloc(stat.size);
+      let offset = 0;
+      while (offset < bytes.length) {
+        signal.throwIfAborted();
+        const { bytesRead } = await file.read(bytes, offset, Math.min(65536, bytes.length - offset), offset);
+        if (!bytesRead) throw invalid('读取期间图片发生变化，请重新导入');
+        offset += bytesRead;
+      }
+      const extra = await file.read(Buffer.alloc(1), 0, 1, offset);
+      if (extra.bytesRead) throw invalid('读取期间图片发生变化，请重新导入');
+    } catch (error) {
+      signal.throwIfAborted();
+      if (error.code === 'IRIS_IMAGE_IMPORT_INVALID') throw error;
+      throw invalid('图片无法读取，请选择可读的普通文件');
+    } finally { await file?.close(); }
+  } else {
+    if (!(imageBytes instanceof Uint8Array)) throw invalid('导入图片内容必须是字节数据');
+    checkSize(imageBytes.byteLength);
+    bytes = Buffer.from(imageBytes);
+  }
+  signal.throwIfAborted();
+  let metadata;
+  try { metadata = await sharp(bytes).metadata(); }
+  catch (_) {
+    signal.throwIfAborted();
+    throw invalid('无法读取图片，请使用有效的静态PNG、JPEG或WebP');
+  }
+  signal.throwIfAborted();
+  const mediaType = TYPES[metadata.format];
+  if (!mediaType || metadata.pages > 1 || !metadata.width || !metadata.height) {
+    throw invalid('仅支持静态PNG、JPEG或WebP，不支持动画');
+  }
+  return { bytes, mediaType, metadata: { width: metadata.width, height: metadata.height } };
+}

package/lib/index.js

@@ -263,7 +263,7 @@ export async function apply(ctx) {
   // 若 webServer 已在运行，inject 回调也会触发；这里兜底立即挂载一次
   guard('媒体路由兜底挂载', () => mountIrisRoutes(ctx));
 
-  // DSH 的 Skill registry 是可选宿主能力。存在时把 npm 包内两项 Skill 注册到
+  // DSH 的 Skill registry 是可选宿主能力。存在时把 npm 包内三项 Skill 注册到
   // 全局层；项目目录中的同名 Skill 仍由 DSH 原生优先级覆盖。
   ctx.inject(['skills'], (skillCtx) => {
     guard('随包 Skill 注册', () => {
@@ -309,6 +309,30 @@ export async function apply(ctx) {
     return { blocks };
   }
 
+  safeRegister(host, {
+    name: 'iris_import_image',
+    description: 'Save a local image or a current-session image attachment as a persistent Iris image Artifact for later viewing, editing and export. Provide exactly one of image_path or attachment_id. Supports static PNG/JPEG/WebP up to 20 MiB, preserves the source, and never calls a model.',
+    parameters: {
+      type: 'object',
+      properties: {
+        image_path: { type: 'string', description: 'Absolute path to an image readable by the DSH host' },
+        attachment_id: { type: 'string', description: 'Image attachment from the current session, alternative to image_path' }
+      },
+      required: []
+    },
+    output: { schema: { type: 'object' }, render: (_args, value) => value.blocks },
+    isConcurrencySafe: () => true,
+    async execute(args, exec = {}) {
+      const imagePath = String(args.image_path || '').trim();
+      const attachmentId = String(args.attachment_id || '').trim();
+      if (Boolean(imagePath) === Boolean(attachmentId)) throw new Error('图片导入须选择image_path或attachment_id之一');
+      const input = imagePath ? { image_path: imagePath } : {
+        image_bytes: (await resolveVisionImageInput(dshHost(ctx), exec, { attachment_id: attachmentId }, exec.signal)).bytes
+      };
+      return runAction(dshHost(ctx), 'image_import', input, { signal: exec.signal });
+    }
+  });
+
   /* ---------- 🖼️ 画图 ---------- */
   safeRegister(host, {
     name: 'iris_draw_image',
@@ -321,7 +345,7 @@ export async function apply(ctx) {
         prompt: { type: 'string', description: 'Detailed visual description of the image to create' },
         size: { type: 'string', description: "Output size; DashScope uses 'W*H' (e.g. '1024*1024'), OpenAI uses 'WxH'. Default provider default." },
         n: { type: 'string', description: "Number of images, default '1'" },
-        model: { type: 'string', description: 'Override with a providerId::modelId reference (legacy bare model id also accepted)' }
+        model: { type: 'string', description: 'Optional assigned providerId::modelId; selects only this item (legacy bare model id also accepted)' }
       },
       required: ['prompt']
     },
@@ -383,12 +407,12 @@ export async function apply(ctx) {
 
   safeRegister(host, {
     name: 'iris_edit_image',
-    description: 'Edit an existing Core image by Artifact ID and an instruction using a configured openai-chat-images model. Returns new Core Artifacts and DSH image attachments; preserves the source image and records its provenance.',
+    description: 'Edit an existing Core image by Artifact ID and an instruction using an assigned chat-image model or native DashScope Qwen edit model. Returns new Core Artifacts and DSH image attachments; preserves the source image and records its provenance.',
     parameters: {
       type: 'object', properties: {
         source_artifact_id: { type: 'string', description: 'Core Artifact ID of the source PNG, JPEG or WebP image (up to 20 MiB)' },
         prompt: { type: 'string', description: 'Describe the changes and what should be preserved in the source image' },
-        model: { type: 'string', description: 'Optional providerId::modelId; image protocol must be openai-chat-images' },
+        model: { type: 'string', description: 'Optional assigned providerId::modelId; selects only this item; supports openai-chat-images or DashScope Qwen edit/max/plus and 2.0/pro models' },
         n: { type: 'string', description: "Number of images, default '1'" }
       }, required: ['source_artifact_id', 'prompt']
     },
@@ -419,7 +443,7 @@ export async function apply(ctx) {
         resolution: { type: 'string', description: "s2v only: output tier '480P' (default) or '720P'" },
         size: { type: 'string', description: "t2v/i2v only: output size 'W*H', e.g. '1280*720' (default)" },
         duration: { type: 'number', description: 't2v/i2v only: duration in seconds, if the model supports it' },
-        model: { type: 'string', description: 'Override with a providerId::modelId reference (legacy bare model id accepted)' }
+        model: { type: 'string', description: 'Optional assigned providerId::modelId; selects only this item (legacy bare model id accepted)' }
       },
       required: []
     },
@@ -463,16 +487,35 @@ export async function apply(ctx) {
     }
   });
 
+  safeRegister(host, {
+    name: 'iris_generate_music',
+    description: 'Generate music using a model explicitly assigned to Music. Returns audio artifact IDs and playback links. Lyrics, vocals and duration are prompt intentions. Configured 502 retries may generate again.',
+    parameters: { type: 'object', properties: {
+      prompt: { type: 'string', description: 'Describe the music, including any lyrics, vocals, mood or intended duration' },
+      model: { type: 'string', description: 'Optional assigned providerId::modelId; selects only this item' },
+      timeout_ms: { type: 'integer', description: 'Per-attempt timeout; default 300000 ms' },
+      retry_502: { type: 'integer', description: '502 regeneration retries, 0–5; default 2; each retry consumes another request' },
+      retry_delay_ms: { type: 'integer', description: 'Delay between 502 retries; default 5000 ms' }
+    }, required: ['prompt'] },
+    output: { schema: { type: 'string' }, render: (_args, value) => [{ type: 'text', text: value }] },
+    isConcurrencySafe: () => true,
+    async execute(args, exec) {
+      const submitted = await runAction(dshHost(ctx), 'music', args, { signal: exec.signal });
+      return submitted.text + '\nartifact: ' + submitted.artifactIds.join(', ') + '\n' +
+        submitted.artifactIds.map(id => '[♪ 音乐播放](/iris/api/core/artifact/' + encodeURIComponent(id) + '/media)').join('\n');
+    }
+  });
+
   /* ---------- 🔊 语音合成 ---------- */
   safeRegister(host, {
     name: 'iris_speak_text',
-    description: 'Synthesize speech audio from text using the configured TTS model (qwen-tts / compatible). Returns the saved audio file path.',
+    description: 'Synthesize spoken audio from text using the configured TTS model. Returns Core audio Artifact IDs and playback links; export an Artifact to a host file before passing it as audio_path to another tool. Use iris_generate_music for songs or background music.',
     parameters: {
       type: 'object',
       properties: {
         text: { type: 'string', description: 'Text to speak' },
         voice: { type: 'string', description: "Voice name, e.g. 'Cherry' (DashScope qwen-tts voices)" },
-        model: { type: 'string', description: 'Override with a providerId::modelId reference (legacy bare model id accepted)' }
+        model: { type: 'string', description: 'Optional assigned providerId::modelId; selects only this item (legacy bare model id accepted)' }
       },
       required: ['text']
     },
@@ -509,7 +552,7 @@ export async function apply(ctx) {
       type: 'object',
       properties: {
         audio_path: { type: 'string', description: 'Absolute path to the audio file (wav/mp3)' },
-        model: { type: 'string', description: 'Override with a providerId::modelId transcription reference (legacy bare model id accepted)' }
+        model: { type: 'string', description: 'Optional assigned transcription providerId::modelId; selects only this item (legacy bare model id accepted)' }
       },
       required: ['audio_path']
     },
@@ -621,7 +664,7 @@ export async function apply(ctx) {
         target_width: { type: 'integer', description: 'Frame width for sampling (default 640)' },
         transcribe: { type: 'boolean', description: 'Auto-transcribe the audio track for video_path (default true unless transcribe_text is provided). Existing frames only consume explicit text.' },
         transcribe_text: { type: 'string', description: 'Optional existing transcript text; does not create a transcription task' },
-        model: { type: 'string', description: 'Override the configured vision model id' }
+        model: { type: 'string', description: 'Optional item from the vision assignment list (providerId::modelId or host:current-vision); selects only this item' }
       },
       required: []
     },
@@ -683,7 +726,7 @@ export async function apply(ctx) {
         name: `iris-sheet-${Date.now()}.png`
       });
       if (exec.signal?.aborted) throw exec.signal.reason;
-      const viaLabel = via === 'selfstack' ? 'iris 自持栈' : 'DSH 全局视觉模型';
+      const viaLabel = via === 'selfstack' ? 'iris 自持栈' : 'DSH 当前默认模型';
       return {
         frames: summaryFrameRecords(frames),
         blocks: [
@@ -712,7 +755,7 @@ export async function apply(ctx) {
         image_path: { type: 'string', description: 'Absolute path to the image file (png/jpg/jpeg/webp)' },
         artifact_id: { type: 'string', description: 'Existing Core image Artifact ID in the current profile (alternative to image_path)' },
         question: { type: 'string', description: 'Question or extraction request about the image; defaults to a detailed description' },
-        model: { type: 'string', description: 'Override the configured vision model id (default qwen-vl-plus)' }
+        model: { type: 'string', description: 'Optional item from the vision assignment list (providerId::modelId or host:current-vision); selects only this item' }
       },
       required: []
     },
@@ -750,7 +793,7 @@ export async function apply(ctx) {
       properties: {
         attachment_id: { type: 'string', description: 'The attachment_id of an image that appeared in this session or was generated by iris' },
         question: { type: 'string', description: 'New question about the image pixels' },
-        model: { type: 'string', description: 'Override the configured vision model id' }
+        model: { type: 'string', description: 'Optional item from the vision assignment list (providerId::modelId or host:current-vision); selects only this item' }
       },
       required: ['attachment_id', 'question']
     },
@@ -780,7 +823,7 @@ export async function apply(ctx) {
   safeRegister(host, {
     name: 'iris_task_status',
     description:
-      'Query iris generation tasks (image/video/tts). Pass a task_id for one task, or omit it to list the latest tasks with status, progress, errors and output file paths.',
+      'Query Iris tasks (image/video/tts/music/transcription). Pass a task_id for one task, or omit it to list recent tasks. Core results provide Artifact IDs and playback links; legacy tasks may provide file paths. Querying does not re-observe or redeliver a task.',
     parameters: {
       type: 'object',
       properties: {
@@ -915,7 +958,7 @@ export async function apply(ctx) {
         artifact_id: { type: 'string', description: 'Existing Core image Artifact ID in the current profile (alternative to image_path or attachment_id)' },
         attachment_id: { type: 'string', description: 'Session attachment id of an image (alternative to image_path)' },
         target: { type: 'string', description: 'The object or UI element to locate, e.g. "send button"' },
-        model: { type: 'string', description: 'Override the vision model for this locate call (e.g. qwen3-vl-235b-a22b-thinking for higher grounding precision; default is the provider visionModel, typically qwen-vl-plus)' }
+        model: { type: 'string', description: 'Optional item from the vision assignment list (providerId::modelId or host:current-vision); selects only this item' }
       },
       required: ['target']
     },
@@ -1022,7 +1065,7 @@ export async function apply(ctx) {
     }
   });
 
-  console.log('[iris] tools registered: iris_draw_image, iris_edit_image, iris_generate_video, iris_speak_text, iris_transcribe_audio, iris_task_status, iris_look_at_image, iris_relook_attachment, iris_crop, iris_pixel_diff, iris_locate, iris_html_screenshot, iris_long_ocr, iris_video_frames, iris_media_summarize');
+  console.log('[iris] tools registered: iris_import_image, iris_draw_image, iris_edit_image, iris_generate_video, iris_generate_music, iris_speak_text, iris_transcribe_audio, iris_task_status, iris_look_at_image, iris_relook_attachment, iris_crop, iris_pixel_diff, iris_locate, iris_html_screenshot, iris_long_ocr, iris_video_frames, iris_media_summarize');
 };
 
 /* ---------------- 视觉路由（M3 补全）：look/relook 共用执行器 + 降级链 ---------------- */
@@ -1132,7 +1175,7 @@ export async function sessionAttachmentRef(host, exec, attachmentId) {
 /**
  * 看图问答（阶段 1：VisionBackend 降级链）。
  * 只取声明/推断出 vision 能力的自持栈 provider（严格选择），按序组装后端链，
- * 全局视觉模型兜底；每个后端的失败现场保留在 errors 里。
+ * 仅使用视觉功能的明确分配；宿主默认模型也需显式加入，每个后端失败保留在errors里。
  * @returns {{answer:string,via:'selfstack'|'global',model?:string,backendId:string}}
  */
 export async function askVision(host, { question, dataUrl, image, prepareImage, signal, model, budget }) {
@@ -1155,6 +1198,6 @@ export async function runVisionTool(host, exec, { origin, model, question, dataU
     model
   });
   const label = origin === 'relook' ? '重看回答' : '看图回答';
-  const viaLabel = via === 'selfstack' ? 'iris 自持栈' : 'DSH 全局视觉模型';
+  const viaLabel = via === 'selfstack' ? 'iris 自持栈' : 'DSH 当前默认模型';
   return `[iris] ${label}（${usedModel || '默认'} · ${viaLabel}）：\n${answer}` + (artifactId ? `\nCore Artifact: ${artifactId}` : '');
 }

package/lib/models.js

@@ -19,12 +19,18 @@ export const CAP_FIELD = {
   [CAPABILITIES.IMAGE]: 'imageModel',
   [CAPABILITIES.VIDEO]: 'videoModel',
   [CAPABILITIES.TTS]: 'ttsModel',
+  [CAPABILITIES.MUSIC]: 'musicModel',
   [CAPABILITIES.TRANSCRIBE]: 'transcribeModel',
   [CAPABILITIES.VISION]: 'visionModel'
 };
 
 const MODEL_REF_SEP = '::';
 
+/** Explicit host resource; never a Provider account or an implicit fallback. */
+export const HOST_VISION_REF = 'host:current-vision';
+export const HOST_VISION_MODEL = Object.freeze({ ref: HOST_VISION_REF, id: 'current-vision',
+  providerId: HOST_VISION_REF, capabilities: Object.freeze([CAPABILITIES.VISION]), source: 'host' });
+
 /** 稳定的模型复合引用；provider/model 分别编码，避免同名模型跨账号碰撞。 */
 export function modelRef(providerId, modelId) {
   return encodeURIComponent(String(providerId || '')) + MODEL_REF_SEP + encodeURIComponent(String(modelId || ''));
@@ -77,6 +83,7 @@ const DISCOVERY_CAPABILITIES = Object.freeze({
   IG: CAPABILITIES.IMAGE, IMAGE: CAPABILITIES.IMAGE, 'IMAGE-GEN': CAPABILITIES.IMAGE,
   VG: CAPABILITIES.VIDEO, VIDEO: CAPABILITIES.VIDEO, 'VIDEO-GEN': CAPABILITIES.VIDEO,
   TTS: CAPABILITIES.TTS, ASR: CAPABILITIES.TRANSCRIBE,
+  MUSIC: CAPABILITIES.MUSIC, 'MUSIC-GEN': CAPABILITIES.MUSIC,
   TRANSCRIBE: CAPABILITIES.TRANSCRIBE, VU: CAPABILITIES.VISION, VISION: CAPABILITIES.VISION
 });
 
@@ -115,6 +122,7 @@ export function providerModels(p) {
       const caps = configuredModelCapabilities(p, m);
       const extra = typeof m === 'object' && m ? { verified: m.verified, source: m.source,
         ...(m.imageProtocol !== undefined ? { imageProtocol: m.imageProtocol } : {}),
+        ...(m.musicProtocol !== undefined ? { musicProtocol: m.musicProtocol } : {}),
         ...(m.visionInput !== undefined ? { visionInput: m.visionInput } : {}) } : {};
       push(id, caps, extra);
     }
@@ -139,6 +147,7 @@ export function resolveModelRef(provider, capability, requested = '') {
 
 /** 共享旧分配对象、裸名称和复合引用的解析，池顺序决定同名匹配。 */
 export function resolvePoolModel(pool, raw, capability) {
+  if (raw === HOST_VISION_REF) return pool.find(m => m.ref === raw && m.capabilities.includes(capability)) || null;
   let providerId = '';
   let modelId = '';
   if (raw && typeof raw === 'object') {
@@ -153,7 +162,7 @@ export function resolvePoolModel(pool, raw, capability) {
     && m.capabilities.includes(capability)) || null;
 }
 
-/** DSH 与 CLI 共用的候选顺序：分配优先、按池顺序补齐并去重。 */
+/** DSH 与 CLI 共用的执行名单：只按明确分配排序并去重。 */
 export function orderedModels(pool, capability, assignments, { includeRateLimited = false } = {}) {
   const ordered = [];
   const seen = new Set();
@@ -167,7 +176,6 @@ export function orderedModels(pool, capability, assignments, { includeRateLimite
   for (const raw of (Array.isArray(assignments) ? assignments : (assignments ? [assignments] : []))) {
     add(resolvePoolModel(pool, raw, capability));
   }
-  for (const model of pool) add(model);
   return ordered;
 }
 
@@ -189,9 +197,10 @@ export function selectionReasonForModel(pool, capability, assignments, modelOrRe
 }
 
 /** 全局模型池：合并所有 provider 的模型 */
-export function modelPool(providers) {
+export function modelPool(providers, { includeHostVision = false } = {}) {
   const pool = [];
   for (const p of providers || []) pool.push(...providerModels(p));
+  if (includeHostVision) pool.push(HOST_VISION_MODEL);
   return pool;
 }
 

package/lib/music-generation.js

@@ -0,0 +1,21 @@
+import { setTimeout as delay } from 'node:timers/promises';
+
+/** Explicit Music 502 regeneration policy; each resubmission is a new Core Task. */
+export async function generateMusicTask({ runner, candidates, providerInput, options, signal }) {
+  const taskIds = [];
+  let result, retriedFrom;
+  for (let index = 0; index <= options.retry502; index++) {
+    signal?.throwIfAborted();
+    result = await runner.submit({ capability: 'music', candidates, providerInput, ...(retriedFrom ? { retriedFrom } : {}) });
+    taskIds.push(result.task.id);
+    const task = result.task;
+    if (result.localError || task.phase !== 'terminal' || task.lastError?.httpStatus !== 502
+        || task.outcome === 'succeeded' || index === options.retry502) break;
+    // Retry the actual model, without switching to another (potentially paid) source.
+    candidates = candidates.filter(candidate => candidate.model === task.modelRef && candidate.adapter.id === task.providerId);
+    if (!candidates.length) throw new Error('Music 重试无法找到原模型绑定');
+    retriedFrom = task.id;
+    await delay(options.retryDelayMs, undefined, { signal });
+  }
+  return Object.freeze({ ...result, taskIds: Object.freeze(taskIds), retries: taskIds.length - 1 });
+}

package/lib/music-options.js

@@ -0,0 +1,18 @@
+/** Music caller controls; generation parameters remain in the prompt. */
+export function normalizeMusicOptions(input = {}) {
+  const integer = (field, fallback, min, max) => {
+    if (input[field] !== undefined && !['number', 'string'].includes(typeof input[field])) {
+      throw new TypeError(`${field} 必须是整数`);
+    }
+    const value = input[field] === undefined ? fallback : Number(input[field]);
+    if (!Number.isSafeInteger(value) || value < min || value > max) {
+      throw new TypeError(`${field} 必须是 ${min}–${max} 的整数`);
+    }
+    return value;
+  };
+  return Object.freeze({
+    timeoutMs: integer('timeout_ms', 300000, 1, 3600000),
+    retry502: integer('retry_502', 2, 0, 5),
+    retryDelayMs: integer('retry_delay_ms', 5000, 0, 60000)
+  });
+}

package/lib/music-transport.js

@@ -0,0 +1,46 @@
+import { ProviderContractError } from './provider-contract.js';
+
+function responseError(message) {
+  return new ProviderContractError(message, { stage: 'response', category: 'protocol', acceptance: 'unknown' });
+}
+
+/** Gemini web gateway's documented non-streaming Markdown audio response. */
+export function musicArtifactsFromResponse(body) {
+  if (!Array.isArray(body?.choices)) throw responseError('Music 响应缺少 choices');
+  const artifacts = [], seen = new Set();
+  for (const choice of body.choices) {
+    const content = choice?.message?.content;
+    if (typeof content !== 'string') continue;
+    for (const match of content.matchAll(/data:(audio\/(?:mpeg|wav|x-wav));base64,([A-Za-z0-9+/=]+)/gi)) {
+      const data = match[2];
+      const bytes = Buffer.from(data, 'base64');
+      if (!bytes.length || bytes.toString('base64') !== data) throw responseError('Music 音频 base64 无效');
+      if (seen.has(data)) continue;
+      seen.add(data);
+      artifacts.push({ kind: 'inline-base64', data, mediaType: match[1].toLowerCase() === 'audio/mpeg' ? 'audio/mpeg' : 'audio/wav' });
+    }
+  }
+  if (!artifacts.length) throw responseError('Music 响应没有可交付的 MP3/WAV 音频');
+  return artifacts;
+}
+
+export async function generateMusic({ key, baseUrl, model, prompt, timeoutMs = 300000, signal }) {
+  const timeout = AbortSignal.timeout(timeoutMs);
+  const response = await fetch(String(baseUrl).replace(/\/+$/, '') + '/chat/completions', {
+    method: 'POST',
+    headers: { 'Content-Type': 'application/json', ...(key ? { Authorization: `Bearer ${key}` } : {}) },
+    signal: signal ? AbortSignal.any([signal, timeout]) : timeout,
+    body: JSON.stringify({ model, stream: false, messages: [{ role: 'user', content: prompt }] })
+  });
+  const text = await response.text();
+  let body;
+  try { body = JSON.parse(text); }
+  catch (error) { if (response.ok) throw responseError('Music 响应不是有效 JSON'); }
+  if (!response.ok) {
+    const message = String(body?.error?.message || body?.message || `Music HTTP ${response.status}`);
+    throw new ProviderContractError(key ? message.replaceAll(key, '[REDACTED]') : message, {
+      stage: 'submit', httpStatus: response.status, category: 'provider', acceptance: 'unknown', retryable: response.status === 502
+    });
+  }
+  return musicArtifactsFromResponse(body);
+}

package/lib/ocr-model-routing.js

@@ -12,6 +12,7 @@ export async function runOcrRequest(host, { providers = [], model, image, prepar
   const settings = normalizeOcrSettings({ chunkHeight, overlap, maxDimension, maxInvocations });
   const operation = createModelOperation({ signal, budget: { timeoutMs: budget.timeoutMs, maxInvocations: settings.maxInvocations } });
   try {
+    if (operation.signal.aborted) throw new ModelPortError('IRIS_MODEL_ABORTED');
     const inputs = new Map();
     const candidates = buildVisionModelCandidates(host, { providers, model, onRateLimit, prepareImages: true,
       prepareImageRequest: createVisionInputObserver(inputs) });