@mokuyoaxis/dsh-iris 0.2.2 → 0.2.4

package/lib/provider-protocol.js

@@ -63,11 +63,29 @@ export function selectImageProtocol(provider, modelId) {
   return protocol === 'auto' ? selectMediaProtocol(provider) : { mediaProtocol: protocol, protocolInferred: false };
 }
 
+/** 已接入的带图编辑协议；这里只判断传输，不授予模型 image-gen 能力。 */
+export function supportsImageEdit(protocol, modelId) {
+  return protocol === 'openai-chat-images' || (protocol === 'dashscope'
+    && /^qwen-image-(?:edit(?:-(?:max|plus))?|2\.0(?:-pro)?)(?:-\d{4}-\d{2}-\d{2})?$/.test(String(modelId || '')));
+}
+
 /** 给已绑定图片模型的 Adapter/binding 投影协议，不改写账号默认值。 */
 export function providerForImageModel(provider, modelId) {
   return { ...provider, ...selectImageProtocol(provider, modelId) };
 }
 
+export function normalizeMusicProtocol(value) {
+  if (value !== 'gemini-web-music') throw Object.assign(new TypeError('musicProtocol 必须是 gemini-web-music'), {
+    code: 'IRIS_PROVIDER_MUSIC_PROTOCOL_INVALID'
+  });
+  return value;
+}
+
+export function providerForMusicModel(provider, modelId) {
+  const entry = provider.models?.find(model => model?.id?.trim() === modelId);
+  return { ...provider, mediaProtocol: normalizeMusicProtocol(entry?.musicProtocol), protocolInferred: false };
+}
+
 export function unsupportedProtocolError(protocol, kind = 'media') {
   const safeName = /^[a-z][a-z0-9-]{0,63}$/.test(String(protocol)) ? protocol : '(invalid)';
   const error = new TypeError('iris: 不支持的 ' + (kind === 'vision' ? 'Vision' : 'Provider') + ' 协议：' + safeName);

package/lib/provider-task-runner.js

@@ -31,6 +31,8 @@ import {
 } from './provider-adapter.js';
 import { ProviderContractError, providerErrorRecord, submitWithAcceptanceBoundary } from './provider-contract.js';
 import { imageEditCandidates, readImageEditArtifact } from './image-edit-input.js';
+import { createDeliveryCache, newDeliveryPayloadPath, readDeliveryCache,
+  readDeliveryPayload, recordDeliveryPayload } from './core-delivery-cache.js';
 
 export const PROVIDER_TASK_RUNNER_VERSION = 0;
 
@@ -44,6 +46,7 @@ export const DELIVERY_PROFILES = Object.freeze({
   video: Object.freeze({ kind: 'generated-video', mediaTypes: Object.freeze(['video/mp4']), defaultMediaType: 'video/mp4' }),
   // TTS 同步完成型：submit 内 completed → 同一次调用直接交付（无 remote 长轮询）。
   tts: Object.freeze({ kind: 'generated-audio', mediaTypes: Object.freeze(['audio/mpeg', 'audio/wav']), defaultMediaType: 'audio/mpeg' }),
+  music: Object.freeze({ kind: 'generated-audio', mediaTypes: Object.freeze(['audio/mpeg', 'audio/wav']), defaultMediaType: 'audio/mpeg' }),
   // 转写上传型异步：受理 + remoteTaskId → 长轮询 → 文本物化为 UTF-8 Artifact。
   transcribe: Object.freeze({ kind: 'transcript', mediaTypes: Object.freeze(['text/plain']), defaultMediaType: 'text/plain' })
 });
@@ -195,6 +198,62 @@ async function observeWithinRoot(dataRoot, taskId, adapter, signal) {
   return deliverArtifacts(dataRoot, taskId, adapter, result.artifacts, signal);
 }
 
+/** 同步结果按已提交缓存补交付；已下载项不再访问 Provider，稳定 Artifact ID 防重复。 */
+async function deliverCachedArtifacts(dataRoot, taskId, adapter, signal) {
+  beginCoreDelivery(dataRoot, taskId);
+  try {
+    const task = inspectCoreTask(dataRoot, taskId);
+    const profile = DELIVERY_PROFILES[task.capability];
+    if (!profile) throw new Error('Task 没有可用的交付 Profile');
+    const cache = readDeliveryCache(dataRoot, task);
+    for (let index = 0; index < cache.items.length; index++) {
+      if (signal.aborted) throw new Error('本地交付已取消');
+      const item = cache.items[index];
+      if (!item.payload) {
+        const declaredMediaType = item.source.mediaType || profile.defaultMediaType;
+        if (task.capability !== 'image' && !profile.mediaTypes.includes(declaredMediaType)) {
+          throw new Error('交付媒体类型不在 Profile 白名单');
+        }
+        checkAdapterForTask(task, adapter);
+        const target = newDeliveryPayloadPath(dataRoot, cache);
+        const downloaded = await invokeProviderOperation(adapter, 'download', {
+          capability: task.capability, artifact: item.source, targetPath: target, signal
+        }, { signal, taskId });
+        const stat = fs.lstatSync(target);
+        if (!stat.isFile() || stat.isSymbolicLink() || !stat.size || stat.size !== downloaded.bytes) {
+          throw new Error('Provider 物化结果与文件证据不一致');
+        }
+        const mediaType = task.capability === 'image'
+          ? await generatedImageMediaType(fs.readFileSync(target))
+          : declaredMediaType;
+        if (!profile.mediaTypes.includes(mediaType)) throw new Error('交付媒体类型不在 Profile 白名单');
+        recordDeliveryPayload(dataRoot, cache, index, target, mediaType);
+      }
+    }
+    recordCoreDownloadCompleted(dataRoot, taskId);
+    const artifactIds = [];
+    for (let index = 0; index < cache.items.length; index++) {
+      if (signal.aborted) throw new Error('本地交付已取消');
+      const item = cache.items[index];
+      const sourcePath = readDeliveryPayload(dataRoot, cache, index);
+      const mediaType = task.capability === 'image'
+        ? await generatedImageMediaType(fs.readFileSync(sourcePath))
+        : (item.payload.mediaType || profile.defaultMediaType);
+      if (!profile.mediaTypes.includes(mediaType)) throw new Error('交付媒体类型不在 Profile 白名单');
+      const artifact = adoptCoreArtifactFile(dataRoot, {
+        artifactId: item.artifactId, sourcePath, createdAt: cache.createdAt,
+        kind: profile.kind, mediaType, metadata: { taskId, capability: task.capability },
+        ...(task.sourceArtifactId ? { relations: [{ type: 'derived-from', artifactId: task.sourceArtifactId }] } : {})
+      });
+      artifactIds.push(artifact.id);
+    }
+    return completeCoreDelivery(dataRoot, taskId, artifactIds);
+  } catch (error) {
+    return failCoreDelivery(dataRoot, taskId, error);
+  }
+  // 完整结果与未提交文件留在私有缓存，失败、取消和重启都不自动清掉恢复证据。
+}
+
 /**
  * FakeProvider 与未来真实 Host 共用的生命周期调度候选。它不拥有 timer，也不会
  * 自动循环轮询；每次 observe 只消费一个 poll 结果，使重启和故障边界可重复验证。
@@ -236,6 +295,7 @@ export function createProviderTaskRunner(runtime) {
         providerInput = { ...providerInput, image };
       }
       const task = createCoreTask(dataRoot, { capability, retriedFrom: input.retriedFrom, sourceArtifactId: input.sourceArtifactId });
+      const completedResults = new Map();
       const wrapped = candidates.map(({ adapter, model, providerModel, prepareInput }) => ({
         id: adapter.id,
         model,
@@ -248,12 +308,14 @@ export function createProviderTaskRunner(runtime) {
             }); }
           }
           if (signal.aborted) throw new ProviderContractError('提交已取消', { stage: 'prepare', category: 'aborted', acceptance: 'not_accepted' });
-          return invokeProviderOperation(
+          const result = await invokeProviderOperation(
             adapter,
             'submit',
             { capability, model: providerModel, input: providerInput, signal },
             { ...context, signal, taskId: task.id }
           );
+          if (result.kind === 'completed') completedResults.set(context.attempt.id, result.artifacts);
+          return result;
         }
       }));
       const submitted = await submitWithAcceptanceBoundary(wrapped, providerInput, {
@@ -266,7 +328,20 @@ export function createProviderTaskRunner(runtime) {
             ...(candidate.selectionReason !== undefined ? { selectionReason: candidate.selectionReason } : {})
           });
         },
-        afterResult: async (attempt) => recordCoreAttemptResult(dataRoot, task.id, attempt)
+        afterResult: async (attempt) => {
+          let cacheError;
+          if (attempt.resultKind === 'completed') {
+            try {
+              createDeliveryCache(dataRoot, inspectCoreTask(dataRoot, task.id), completedResults.get(attempt.id));
+              attempt.deliveryCache = true;
+            } catch (error) { cacheError = error; }
+          }
+          recordCoreAttemptResult(dataRoot, task.id, attempt);
+          if (cacheError) {
+            failCoreDelivery(dataRoot, task.id, cacheError);
+            throw cacheError;
+          }
+        }
       });
       if (submitted.localError) {
         return Object.freeze({ taskId: task.id, task: inspectCoreTask(dataRoot, task.id), localError: submitted.localError });
@@ -275,10 +350,9 @@ export function createProviderTaskRunner(runtime) {
       if (submitted.result.kind === 'not_accepted') {
         finalizeCoreNoAcceptance(dataRoot, task.id, submitted.result.error);
       } else if (submitted.result.kind === 'completed') {
-        const artifacts = submitted.result.artifacts;
         return Object.freeze({
           taskId: task.id,
-          task: await deliverArtifacts(dataRoot, task.id, submitted.candidate.adapter, artifacts, signal),
+          task: await deliverCachedArtifacts(dataRoot, task.id, submitted.candidate.adapter, signal),
           attempts: submitted.attempts
         });
       }
@@ -308,8 +382,9 @@ export function createProviderTaskRunner(runtime) {
   function redeliver(taskId, adapter) {
     return runExclusive(taskId, 'execute', async ({ dataRoot, signal }) => {
       const task = inspectCoreTask(dataRoot, taskId);
-      checkAdapterForTask(task, adapter);
+      if (adapter || !task.deliveryCache) checkAdapterForTask(task, adapter);
       prepareCoreRedelivery(dataRoot, taskId);
+      if (task.deliveryCache) return deliverCachedArtifacts(dataRoot, taskId, adapter, signal);
       let result;
       try {
         result = await invokeProviderOperation(adapter, 'poll', {

package/lib/vision-model-routing.js

@@ -1,6 +1,6 @@
 'use strict';
 /** Host 边界：显式配置选型、字节解析和结果投影。 */
-import { resolveModelRef, parseModelRef } from './models.js';
+import { resolveModelRef, parseModelRef, HOST_VISION_REF } from './models.js';
 import { providerApiKey } from './provider-protocol.js';
 import { createHttpVisionModelPort } from './http-vision-model-adapter.js';
 import { prepareDshVisionModelPort } from './dsh-vision-model-adapter.js';
@@ -79,18 +79,31 @@ export function createConfiguredVisionModelPort(provider, model, { allowRateLimi
 export function buildVisionModelCandidates(host, { providers = [], model, allowRateLimited = false, onRateLimit, prepareImages = false,
   orientImages = false, prepareImageRequest } = {}) {
   const candidates = [], seen = new Set();
-  for (const provider of providers.filter(Boolean)) {
-    const ref = resolveModelRef(provider, 'vision', model);
+  let selected = providers.filter(Boolean);
+  const requested = String(model || '').trim();
+  if (requested) {
+    const parsed = parseModelRef(requested);
+    const provider = selected.find(p => p.id === HOST_VISION_REF ? requested === HOST_VISION_REF
+      : parsed ? parsed.providerId === p.id && parsed.modelId === p.visionModel : requested === p.visionModel);
+    if (!provider) throw new ModelPortError('IRIS_MODEL_UNAVAILABLE', { stage: 'prepare', invocation: 'not_invoked' });
+    selected = [provider];
+  }
+  if (!selected.length) throw new ModelPortError('IRIS_MODEL_UNAVAILABLE', { stage: 'prepare', invocation: 'not_invoked' });
+  for (const provider of selected) {
+    if (provider.id === HOST_VISION_REF) {
+      const hostCandidate = deferredDshPort(host, { prepareImages, orientImages, prepareImageRequest });
+      candidates.push({ ...hostCandidate, id: 'dsh-vision:default', via: 'global', backendId: 'dsh-global', model: 'DSH 当前默认模型' });
+      continue;
+    }
+    const ref = resolveModelRef(provider, 'vision', provider.visionModel);
     const parsed = parseModelRef(ref);
     // 显式模型会把同账号的多份池记录解析为同一复合引用，只保留首次候选。
     if (parsed && seen.has(ref)) continue;
     if (parsed) seen.add(ref);
-    const port = createConfiguredVisionModelPort(provider, model, { allowRateLimited, onRateLimit, prepareImages, orientImages, prepareImageRequest });
+    const port = createConfiguredVisionModelPort(provider, provider.visionModel, { allowRateLimited, onRateLimit, prepareImages, orientImages, prepareImageRequest });
     const id = port.describe().identity.backendId;
     candidates.push({ port, id, via: 'selfstack', backendId: provider.id, model: parsed?.modelId || '' });
   }
-  const hostCandidate = deferredDshPort(host, { prepareImages, orientImages, prepareImageRequest });
-  candidates.push({ ...hostCandidate, id: 'dsh-vision:default', via: 'global', backendId: 'dsh-global', model: '宿主视觉模型' });
   return candidates;
 }
 
@@ -137,6 +150,7 @@ function projectError(record, candidates) {
 /** prepareImage 的信号覆盖文件/会话读取；函数开始时即建立整体预算。 */
 export async function runVisionOperation(host, { providers, model, signal, budget = VISION_BUDGET, onRateLimit, prepareImages = false,
   orientImages = false, prepareImageRequest }, consume) {
+  if (signal?.aborted) throw new ModelPortError('IRIS_MODEL_ABORTED');
   const candidates = buildVisionModelCandidates(host, { providers, model, onRateLimit, prepareImages, orientImages, prepareImageRequest });
   const operation = createModelOperation({ signal, budget: { timeoutMs: budget.timeoutMs, maxInvocations: candidates.length } });
   try {
@@ -167,8 +181,8 @@ export async function runVisionRequest(host, { providers, model, question, image
 /** 付费确认在动作入口；红图实测只有一个供应商，不退到 Host 冒充其能力。 */
 export async function probeVisionModel(provider, model, image, { signal, timeoutMs = 15000 } = {}) {
   try {
-    const [candidate] = buildVisionModelCandidates(null, { providers: [provider], model, allowRateLimited: true });
-    const result = await completeVision([candidate.port], { prompt: '这张图片是什么颜色？请只回答颜色名称（中文）。', image },
+    const port = createConfiguredVisionModelPort(provider, model, { allowRateLimited: true });
+    const result = await completeVision([port], { prompt: '这张图片是什么颜色？请只回答颜色名称（中文）。', image },
       { signal, budget: { ...VISION_BUDGET, timeoutMs } });
     return { ok: /红|red/i.test(result.text), answer: result.text };
   } catch (error) {

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@mokuyoaxis/dsh-iris",
-  "version": "0.2.2",
-  "description": "Multi-provider image, video, and speech generation, transcription, visual understanding, and prompt optimization with an integrated Iris workbench for DeepSeek Harness.",
+  "version": "0.2.4",
+  "description": "Multi-provider image, video, music, and speech generation, transcription, visual understanding, and prompt optimization with an integrated Iris workbench for DeepSeek Harness.",
   "type": "module",
   "main": "lib/index.js",
   "exports": {
@@ -28,12 +28,13 @@
     "!docs/releases/0.1.1.md",
     "!docs/releases/0.1.2.md",
     "!docs/releases/0.1.3.md",
+    ".dsh/skills/iris-use",
     ".dsh/skills/iris-verify-ui",
     ".dsh/skills/iris-compose-media"
   ],
   "dsh": {
     "engines": {
-      "dsh": "0.2.0-rc.2"
+      "dsh": "0.2.0-rc.2 || 0.2.1-alpha.4"
     },
     "bundle": {
       "patch": "./cordis.patch.yml"
@@ -54,6 +55,7 @@
     "dsh-plugin",
     "image-generation",
     "video-generation",
+    "music-generation",
     "text-to-speech",
     "transcription",
     "vision",
@@ -63,7 +65,8 @@
   ],
   "license": "MIT",
   "engines": {
-    "node": ">=22.0.0"
+    "node": ">=22.0.0",
+    "dsh": "0.2.0-rc.2 || 0.2.1-alpha.4"
   },
   "scripts": {
     "test": "node scripts/test.mjs",
@@ -71,11 +74,11 @@
     "prepublishOnly": "npm test"
   },
   "peerDependencies": {
-    "@deepseek-ai/dsh-client-locale": "0.2.0-rc.2",
-    "@deepseek-ai/dsh-client-ui-conversation": "0.2.0-rc.2",
-    "@deepseek-ai/dsh-client-ui-renderer": "0.2.0-rc.2",
-    "@deepseek-ai/dsh-client-ui-session": "0.2.0-rc.2",
-    "@deepseek-ai/dsh-client-ui-settings": "0.2.0-rc.2"
+    "@deepseek-ai/dsh-client-locale": "0.2.0-rc.2 || 0.2.1-alpha.4",
+    "@deepseek-ai/dsh-client-ui-conversation": "0.2.0-rc.2 || 0.2.1-alpha.4",
+    "@deepseek-ai/dsh-client-ui-renderer": "0.2.0-rc.2 || 0.2.1-alpha.4",
+    "@deepseek-ai/dsh-client-ui-session": "0.2.0-rc.2 || 0.2.1-alpha.4",
+    "@deepseek-ai/dsh-client-ui-settings": "0.2.0-rc.2 || 0.2.1-alpha.4"
   },
   "peerDependenciesMeta": {
     "@deepseek-ai/dsh-client-locale": {

package/user_guide.md

@@ -1,12 +1,12 @@
 # dsh-iris 用户指南
 
-本指南说明如何安装、配置和使用 Iris 0.2.2。升级范围见 [CHANGELOG](CHANGELOG.md) 和 [发布说明](docs/releases/0.2.2.md)。
+本指南对应Iris 0.2.4。发布状态见 [README](README.md)，升级范围见 [CHANGELOG](CHANGELOG.md) 和 [发布说明](docs/releases/0.2.4.md)。
 
-0.2.2 的能力来自明确功能标签、旧能力字段绑定或供应商能力元数据，账号和名称不再自动赋能。已有明确配置保留；仅有裸账号的配置需要先给实际模型设置功能，再加入有序候选池。
+功能来自明确标签、旧能力字段绑定或供应商能力元数据，账号和名称不会自动赋能。0.2.4还要求把模型明确加入对应功能名单；空名单停止新调用。已有配置保留，详见 [升级说明](docs/FUNCTION_MODEL_ASSIGNMENTS.md)。
 
 ## 安装
 
-先运行 `dsh --version`。Iris `0.2.2` 仅声明支持 DSH `0.2.0-rc.2`；旧 DSH `>=0.1.2-rc.1 <0.1.3-0` 或 `0.1.5-rc.1` 使用固定版本 Iris `0.1.4`。验证边界见[适配说明](docs/DSH_RC2_ADAPTATION.md)。还需要 PATH 中的 `pnpm`，以及至少一个媒体或视觉服务供应商。Iris 0.2.2 要求 Node.js 22.0.0 或更高版本，旧 npm 0.1.4 的历史要求为 20.10.0；如果所用 DSH 版本要求更高，以 DSH 为准。Iris 0.1.1 及后续 0.1.x 不兼容 DSH 0.1.0/0.1.1 的旧客户端 Runtime。
+先运行 `dsh --version`。Iris 0.2.4支持DSH `0.2.0-rc.2` 或 `0.2.1-alpha.4`；Iris0.2.0–0.2.3仅支持rc.2。旧DSH `>=0.1.2-rc.1 <0.1.3-0` 或 `0.1.5-rc.1` 固定使用Iris0.1.4，见 [兼容矩阵](docs/DSH_COMPATIBILITY.md)。还需要PATH中的pnpm及至少一个所需功能的供应商。Iris最低Node.js为22.0.0，宿主要求更高时以宿主为准；旧npm0.1.4的历史要求为20.10.0。
 
 在上述旧 DSH 范围内，从 npm 安装固定稳定版到 Web profile：
 
@@ -17,12 +17,12 @@ dsh web
 
 npm 上无 scope 的 `dsh-iris` 是另一款插件；安装或更新 Iris Media 时必须使用完整 scoped 包名。
 
-只下载旧稳定包可运行 `npm pack @mokuyoaxis/dsh-iris@0.1.4`，安装为普通 npm 依赖可运行 `npm install @mokuyoaxis/dsh-iris@0.1.4`；后者不会自动加入 DSH profile。固定版本仍可在 latest 更新后安装，0.1.4 不包含新的 Core 媒体 CLI。DSH rc.2 使用 0.2.2。
+只下载旧稳定包可运行 `npm pack @mokuyoaxis/dsh-iris@0.1.4`，安装为普通npm依赖可运行 `npm install @mokuyoaxis/dsh-iris@0.1.4`；后者不会自动加入DSH profile。0.1.4不包含新的Core媒体CLI。
 
-在 DSH `0.2.0-rc.2` 上，从 npm 安装：
+在DSH rc.2或alpha.4上，固定安装0.2.4：
 
 ```bash
-dsh plugin --profile web add @mokuyoaxis/dsh-iris@0.2.2
+dsh plugin --profile web add @mokuyoaxis/dsh-iris@0.2.4
 dsh web
 ```
 
@@ -30,7 +30,7 @@ dsh web
 
 ### 独立 CLI
 
-无需 DSH，在自己的项目安装 `npm install @mokuyoaxis/dsh-iris@0.2.2`，通过 `npx dsh-iris --help` 查看入口。详见 [Headless CLI](docs/HEADLESS_CLI.md) 和 [视觉 CLI](docs/VISION_CLI.md)。
+无需DSH，在自己的项目安装 `npm install @mokuyoaxis/dsh-iris@0.2.4`，通过 `npx dsh-iris --help` 查看入口。发布状态见README，完整说明见 [Headless CLI](docs/HEADLESS_CLI.md) 和 [视觉CLI](docs/VISION_CLI.md)。
 
 其他 DSH 版本，包括 `0.2.0` 正式版与其他 rc，须另行验收。让 Agent 协助安装时，可使用[简要 Prompt](docs/AGENT_QUICKSTART.md)。
 
@@ -44,6 +44,12 @@ dsh --profile web --dump-config
 
 输出中应出现 `@mokuyoaxis/dsh-iris` 配置层和唯一行 ID `mokuyoaxis-dsh-iris`。DSH 的插件命令和 profile 机制见[官方说明](https://github.com/deepseek-ai/deepseek-harness/blob/master/docs/user/develop/basic/publish.md)。
 
+## 导入已有图片（0.2.4）
+
+在作品区展开“导入图片”，选择上传文件、会话附件或宿主路径，点击“保存到作品”。支持最多20 MiB的静态PNG/JPEG/WebP，保存原字节副本、保留原文件，不需要供应商或模型分配。成功后可使用图片卡的看图、OCR、改图及下载。
+
+导入要求Iris0.2.4，0.2.3没有此工具。Agent入口为 `iris_import_image`，CLI入口为 `artifact import`；上传临时副本与持久作品的区别及示例见 [图片导入](docs/IMAGE_IMPORT.md)。
+
 ## 最快配置：DashScope
 
 打开“设置 → Iris 工作台”，然后：
@@ -55,7 +61,7 @@ dsh --profile web --dump-config
 5. 展开刚添加的供应商，点击“发现模型”。
 6. 若模型显示“未标注功能”，点击其“设置功能”，勾选已确认支持的功能并保存。
 
-如果只有一个供应商，可以先保留“能力分配”为自动。Iris 会从模型池中为画图、视频、语音、转写和视觉能力选择第一个匹配模型。需要固定模型或设置故障转移顺序时，再到“能力分配（failover 顺序）”中调整。
+0.2.4中，单个供应商也需要在“功能分配（调用顺序）”为所需功能选择模型；未分配时不调用模型池。0.2.3仅Music采用严格名单，升级影响见 [功能模型分配](docs/FUNCTION_MODEL_ASSIGNMENTS.md)。
 
 保存供应商和修改能力分配都会立即生效，不需要重启 DSH。
 
@@ -129,22 +135,30 @@ Iris 先按画图、视频、语音、转写和视觉功能组织候选池，再
 
 每项能力都可以设置一个有序的“供应商 + 模型”列表。界面显示的是模型名和供应商，配置中保存为 `providerId::modelId` 复合引用，因此不同供应商的同名模型不会冲突。
 
-- 未手工分配时，每个新请求都从模型池第一个匹配项开始；这不是 round-robin。
-- 手工列表中的模型优先，并按列表顺序尝试。
-- 模型池中其余具备该能力的模型仍会作为后续候选。
-- 点击“恢复自动”会清除手工顺序。
+- 六类功能仅使用各自分配名单，每次按名单顺序选择，不补入其他模型。
+- 临时指定模型须已分配，本次只调用该项。
+- “清空分配”停止新调用，模型、任务与作品保留；已有任务按原绑定观察和补交付。
+- 视觉可明确加入“DSH 当前默认模型”并排序；未加入时不使用宿主视觉。
 
 生成类故障转移只覆盖上传、提交和同步生成阶段。远端一旦受理异步任务，Iris 就会继续跟踪这个任务，不会因轮询或下载失败自动重提，以免重复生成和计费。
 
+## 音乐生成
+
+为音乐服务添加实际模型，设置“音乐”标签，选择 **Chat Completions（内嵌音频）** 协议，再将模型加入音乐能力分配名单。音乐必须明确分配，不从其他模型池自动补齐；这个接口要求服务在聊天响应正文中返回MP3/WAV音频data URL。
+
+配置后可在DSH中说“用Iris生成一首复古摇滚配乐”，或使用工作台音乐卡片。生成结果可试听、下载与导出；音乐和TTS分别配置，配乐按需加入多步骤流程。
+
+音乐入口默认在明确HTTP502后额外重试两次，可能消耗额外额度；可用 `retry_502: 0` 关闭。时长、歌词和人声通过描述表达，精确控制取决于模型。完整配置与CLI示例见 [音乐生成](docs/MUSIC.md)。
+
 ## 从旧工作台显式导入
 
-`ai-paint` 是 Iris 维护者本机未公开的前身项目，不是公开依赖。普通用户不需要、也不应该为了使用 Iris 去下载、安装或自行创建 ai-paint 目录；直接在 Iris 工作台添加供应商即可。
+首次使用请直接在 Iris 工作台添加供应商。已有旧 ai-paint 配置时，可使用下面的一次性导入入口；无需安装旧项目。
 
-旧版读取路径同时承担了本机迁移和密钥保护作用：由运行 DSH 的宿主进程直接读取维护者已有的本地配置，可以避免为了迁移把 API Key 重新粘贴到 Agent 会话、命令行参数或文档中。它不是一个配置服务，也不意味着 Iris 运行时应该长期依赖另一个项目。
+导入由宿主进程读取本地配置，API Key 不需要经过 Agent 会话或命令行参数。
 
 从 0.1.1 起，Iris 独立保存供应商、密钥、模型池和能力分配，位置为 `$DSH_HOME/iris/v1/providers.json`（未设置 `DSH_HOME` 时使用用户目录下的 `.dsh`）。修改 Iris 配置不会影响 ai-paint，反之亦然。
 
-默认启动不会扫描 ai-paint 或其他项目。推荐通过工作台手动添加供应商；需要迁移旧 ai-paint 配置时，先停止目标 DSH 实例并备份其 Iris 配置，再显式指定来源文件的绝对路径。Bash 示例：
+默认启动不会扫描其他项目。推荐通过工作台手动添加供应商；需要迁移旧 ai-paint 配置时，先停止目标 DSH 实例并备份其 Iris 配置，再显式指定来源文件的绝对路径。Bash 示例：
 
 ```bash
 IRIS_IMPORT_WORKBENCH_CONFIG="/absolute/path/ai-paint/data/config.json" dsh web
@@ -164,9 +178,9 @@ Core 图片卡可直接点击“看图”或“OCR”；结果可以复制、下
 
 ### 按 Artifact ID 改图
 
-Core 静态 PNG/JPEG/WebP 图片卡可点击“改图”，填写修改指令，再选择聊天生图模型。点击“生成修改版”才调用模型，修改版保存为关联原图的新作品，原图保留；可继续看图、OCR、下载或编辑。
+Core 静态 PNG/JPEG/WebP 图片卡可点击“改图”，填写修改指令，再选择已分配的带图编辑模型。点击“生成修改版”才调用模型，修改版保存为关联原图的新作品，原图保留；可继续看图、OCR、下载或编辑。
 
-Agent 可调用 `iris_edit_image`，提供 `source_artifact_id`、`prompt` 与可选 `model_ref`。CLI 使用 `run image` 的同名字段，详见 [Artifact 聊天改图](docs/CLI_MANAGEMENT.md#artifact-聊天改图)。仅支持 `openai-chat-images` 的带图生成，不提供 mask、多参考图或连续编辑历史。
+Agent可调用 `iris_edit_image`，提供 `source_artifact_id`、`prompt` 与可选 `model`；CLI使用 `run image`，模型字段为 `model_ref`，见 [Artifact改图](docs/CLI_MANAGEMENT.md#artifact-聊天改图)。支持openai-chat-images带图生成，0.2.4另支持DashScope原生Qwen edit/max/plus、2.0/pro及日期快照。不提供mask、多参考图或连续编辑历史。
 
 ## 高级配置文件
 
@@ -243,11 +257,15 @@ Iris 工作台中的文件字段提供三种方式：
 
 直接写工具名最明确；自然语言也可以，由 Agent 判断需要调用哪个 Iris 工具。视频、图片和语音生成可能产生供应商费用。
 
-从 0.1.2 起，插件会在 DSH Skill registry 可用时自动注册 `iris-verify-ui` 和 `iris-compose-media`，不要求会话工作区位于本仓库，也不需要用户复制 `.dsh/skills/`。项目目录中存在同名 Skill 时，DSH 仍优先使用项目版本；宿主未提供 Skill registry 时不影响 Iris 工具（0.2.1共 15 个）。
+插件自动注册三项随包 Skill：单步操作用 `iris-use`，多步骤创作用 `iris-compose-media`，界面验收用 `iris-verify-ui`。无需复制 Skill 或切换到仓库目录；项目中的同名 Skill 优先，宿主未提供 registry 时工具仍可使用。
+
+三项共用[能力与产物说明](.dsh/skills/iris-use/references/media-contract.md)。Core音频返回Artifact ID与播放链接；需要audio_path时先导出成宿主文件。音乐独立于TTS，组合流程仅在用户要求时加入；分别交付音视频素材不代表已经混音成片。
 
 用户想稳定指定方法时，可直接用 DSH 的 `/name` 形式：
 
 ```text
+/iris-use 用已经分配的音乐模型生成一首摇滚配乐
+
 /iris-compose-media 分析我上传的产品照，生成同构图海报，再检查是否符合要求
 
 /iris-verify-ui 对比当前截图和参考图，定位偏差并给出有证据的结论
@@ -265,10 +283,12 @@ Iris 工作台中的文件字段提供三种方式：
 
 1. 在对话框写入草稿，点击“🫧”。
 2. 在一般功能中选择“通用、画图、改图、视频、数字人”（旧 0.2.1 的四目标调用保持兼容）。
-3. 0.2.2 默认“忠实整理”，保持原文与句序，只调整分组/分段。需要润色或明确改变指定内容时选择“改写表达”，再展开本次规则；只组装仍原样拼接草稿与前后缀，不调用模型。旧后端保留“智能优化”。
+3. 默认“忠实整理”，保持原文与句序，只调整分组/分段；单片段直接保留原文，不调用模型。需要润色或明确改变指定内容时选择“改写表达”，再展开本次规则；只组装仍原样拼接草稿与前后缀，不调用模型。旧后端保留“智能优化”。
 4. 编辑预览、检查原文与改动，然后选择“写回输入框、复制、重新生成预览”或“恢复原文”。需要额外创意时展开“可选补充与待确认”，点击获取才调用一次模型；勾选后还需点击采纳才加入预览，可以撤回上次采纳。手动编辑会清除旧建议绑定；建议与待确认问题不代表已验证事实或用户已有要求。折叠不清空选择和结果，Iris 不会自动发送消息。
 
-默认路由是当前会话模型；当前会话没有选择时使用 DSH 默认模型。0.2.2 的“指令与模型设置”可查看当前默认或自定义指令，导出/导入 JSON，或恢复内置默认值。配置单独保存在 `$DSH_HOME/iris/v1/prompt-optimizer.json`，不包含供应商 API Key，也不与 `providers.json` 混合。
+默认路由是当前会话模型；当前会话没有选择时使用 DSH 默认模型，固定配置优先于这两项。预览显示实际选择原因。“指令与模型设置”可查看指令、导出/导入 JSON，选择“仅恢复默认指令”或“恢复全部设置”；前者保留模型、生成参数和入口开关。配置单独保存在 `$DSH_HOME/iris/v1/prompt-optimizer.json`，不包含供应商 API Key，也不与 `providers.json` 混合。
+
+再次优化失败或取消会保留已有预览，等待期间继续编辑时，新结果不会覆盖手工改动。配置异常会说明默认值和原文件保留状态；导入前可先导出备份。
 
 导出文件格式：
 
@@ -367,11 +387,13 @@ npx @mokuyoaxis/dsh-iris doctor --json
 
 已安装包也可以直接运行 `dsh-iris doctor`。退出码为 `0`（正常）、`1`（警告）和 `2`（硬错误）。Doctor 会执行一个随后立即删除的本地写入探针，并检查配置、任务、能力分配、临时文件和产物引用；输出不含完整 API Key。离线模式无法检查 DSH 工具/客户端是否已经装载，也不会用付费请求验证 Provider。
 
-**0.2.0** 另提供 `doctor --data-root <绝对路径> --json`：只读盘点指定 Core 数据根的 Task、Artifact、Index 和租约，不执行上述写入探针，也不自动修复。`providers list` 与 `capabilities list` 可用 `--provider-config <私有配置绝对路径>` 只读查看脱敏供应商摘要和按配置排序的候选链；它们不代表远端能力已实测。异常退出留下租约时，先用显式 Doctor 查看 owner，再按 [Headless CLI 的恢复步骤](docs/HEADLESS_CLI.md#异常退出后的写者租约)人工确认并运行 `runtime recover`，不要手动删除租约。安装 npm 0.2.1 后使用 `dsh-iris` 命令；临时运行可用 `npx --package @mokuyoaxis/dsh-iris@0.2.2 dsh-iris ...`。旧版 0.1.4 不包含这些 Core 命令。
+**0.2.0** 另提供 `doctor --data-root <绝对路径> --json`：只读盘点指定 Core 数据根的 Task、Artifact、Index 和租约，不执行上述写入探针，也不自动修复。`providers list` 与 `capabilities list` 可用 `--provider-config <私有配置绝对路径>` 只读查看脱敏供应商摘要和按配置排序的候选链；它们不代表远端能力已实测。异常退出留下租约时，先用显式 Doctor 查看 owner，再按 [Headless CLI 的恢复步骤](docs/HEADLESS_CLI.md#异常退出后的写者租约)人工确认并运行 `runtime recover`，不要手动删除租约。安装 Iris 后使用 `dsh-iris` 命令；临时运行可用 `npx --package @mokuyoaxis/dsh-iris@0.2.4 dsh-iris ...`。旧版 0.1.4 不包含这些 Core 命令。
 
 ## Host Doctor
 
-DSH 运行后，打开“设置 → Iris 工作台 → 宿主诊断”。卡片会自动检查当前 DSH 版本、Iris 服务端和客户端版本、工具注册（0.2.1为 15 个）、两项随包 Skill、四组 Web 路由、四个 UI Slot，以及 Browser、附件、会话和宿主模型端口；点击“刷新”可重新读取，展开项可查看全部结果。需要原始 JSON 时，可在已经完成 DSH Web 认证的同一浏览器访问 `/iris/api/doctor`。
+DSH运行后打开“设置 → Iris工作台 → 宿主诊断”。卡片检查宿主/服务端/客户端版本、当前工具和随包Skill、四组路由与四个UI Slot。0.2.4包含17个工具和三项Skill；升级后检查服务端实际装载、刷新页面，并为所需功能分配模型。点击“刷新”查看结果，原始JSON可在已认证的同一浏览器访问 `/iris/api/doctor`。
+
+0.2.4新增图片导入后检查17个工具，三项Skill保持；0.2.3为16个工具。
 
 Host Doctor 不打开 Browser、不读取附件或会话、不调用模型，也不请求供应商。报告中的 `exitCode` 是诊断严重度，不是 HTTP 状态：`0` 全部健康，`1` 有可降级警告，`2` 有硬错误。未安装 HTML Browser 时出现一条 Browser 警告是预期降级；如果提示尚未收到客户端握手，刷新 DSH 页面后再点“刷新”。若显示 `not found`，通常是前端已更新而 DSH 后端仍运行旧插件代码，应重启 DSH 后再刷新页面。
 
@@ -411,7 +433,7 @@ dsh plugin --profile web remove @mokuyoaxis/dsh-iris
 - **没有可用模型**：先确认供应商已启用且 Key 有效，再运行“发现模型”；未标注模型需通过“设置功能”选择用途，不支持 `/models` 时手动添加并标注。
 - **OpenAI 兼容图片请求走错协议**：核对模型的有效图片协议；`/images/generations` 使用 `openai-images`，网关聊天图片扩展使用 `openai-chat-images`，同步 `/responses` 生图使用 `openai-responses-images`。可在生图模型行或 CLI `models protocol` 设置模型级覆盖，不需要改变同账号其他模型的接口。
 - **反向代理访问返回 `untrusted host`**：把浏览器实际使用的域名或 `host:port` 加入 `IRIS_TRUSTED_HOSTS`，保留 Host，并确认代理层已经启用认证。
-- **看图可用但 Iris 模型池显示为空**：Agent 视觉工具可以回退到 DSH 全局视觉模型；需要在工作台操作时仍建议配置 Iris 的 `vision` 模型。
+- **模型池为空时使用宿主看图**：0.2.4需在视觉分配中明确加入“DSH 当前默认模型”；宿主默认模型须声明图片输入。也可配置并分配自持 `vision` 模型。
 - **视频摘要提示 ffmpeg 不可用**：安装系统级 `ffmpeg` 和 `ffprobe`，并确保 DSH 进程的 PATH 能找到它们。
 - **本地文件不存在**：这里的“本地”指 DSH 宿主，不一定是浏览器所在设备；优先用“上传文件”。
 - **视频任务长时间运行**：不要重复提交。用 `iris_task_status` 或工作台任务详情查询原任务。