@mokuyoaxis/dsh-iris 0.2.1 → 0.2.3

package/lib/provider-protocol.js

@@ -68,6 +68,18 @@ 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);
@@ -95,3 +107,64 @@ export function isConfiguredProvider(provider) {
     && providerMediaBaseUrl(provider)
     && (provider.auth === 'none' || (typeof provider.apiKey === 'string' && provider.apiKey.trim())));
 }
+
+/**
+ * 生图尺寸的协议差异集中在这里，调用点不再自带厂商假设。
+ *
+ * 分隔符（2026-10-11 实测线上端点）：
+ * - dashscope 用 `宽*高`；多模态端点严格校验格式，传 `100x100` 直接回
+ *   `Invalid size format`；旧异步端点提交期完全不校验（`100x100`/`100X100`/`auto` 均 200），
+ *   由具体模型在生成期报错。
+ * - OpenAI 兼容三家用 `宽x高`；尺寸集合由各家网关决定，只做格式归一，不设数值白名单。
+ *
+ * 数值边界只登记服务端确证会拒绝的那一条：
+ * - dashscope 多模态：`Image area must be between 262144 (512x512) and 4194304 (2048x2048)`。
+ * - 其余协议暂无证据，一律留空 —— 本地不拦，交给上游报错，避免比服务端更严。
+ */
+export const IMAGE_SIZE_RULES = Object.freeze({
+  dashscope: Object.freeze({ separator: '*' }),
+  'openai-images': Object.freeze({ separator: 'x' }),
+  'openai-chat-images': Object.freeze({ separator: 'x' }),
+  'openai-responses-images': Object.freeze({ separator: 'x' }),
+  'dashscope/multimodal-sync': Object.freeze({
+    separator: '*', minArea: 262144, maxArea: 4194304
+  })
+});
+
+/** 协议级规则优先于账号级；都没有则返回 null（= 本地不约束）。 */
+export function imageSizeRule(protocol, mode) {
+  const key = mode ? String(protocol) + '/' + String(mode) : String(protocol);
+  return IMAGE_SIZE_RULES[key] || IMAGE_SIZE_RULES[String(protocol)] || null;
+}
+
+/** 解析 `宽<分隔符>高`；无法识别返回 null（含 `auto` 这类自由取值）。 */
+export function parseImageSize(size) {
+  const m = /^(\d+)\s*([*x×X])\s*(\d+)$/.exec(String(size ?? '').trim());
+  if (!m) return null;
+  const width = Number(m[1]);
+  const height = Number(m[3]);
+  if (!Number.isFinite(width) || !Number.isFinite(height) || width <= 0 || height <= 0) return null;
+  return { width, height, separator: m[2] };
+}
+
+/** 把尺寸归一成该协议的规范分隔符；无法识别的原样返回。 */
+export function normalizeImageSize({ protocol, mode, size } = {}) {
+  const rule = imageSizeRule(protocol, mode);
+  if (!rule || !rule.separator) return size;
+  const parsed = parseImageSize(size);
+  if (!parsed) return size;
+  return parsed.width + rule.separator + parsed.height;
+}
+
+/** 返回违规说明；合规、无规则或无法识别时返回 null。纯函数：不抛错、不依赖具体错误类型。 */
+export function imageSizeViolation({ protocol, mode, size } = {}) {
+  const rule = imageSizeRule(protocol, mode);
+  if (!rule || rule.minArea === undefined) return null;
+  const parsed = parseImageSize(size);
+  if (!parsed) return null;
+  const { width, height } = parsed;
+  const area = width * height;
+  if (area >= rule.minArea && area <= rule.maxArea) return null;
+  const label = mode ? protocol + '/' + mode : protocol;
+  return `尺寸 ${width}*${height} 不被 ${label} 接受：总像素需在 ${rule.minArea}–${rule.maxArea} 之间`;
+}

package/lib/provider-task-runner.js

@@ -4,7 +4,7 @@ import crypto from 'node:crypto';
 import fs from 'node:fs';
 import path from 'node:path';
 import sharp from 'sharp';
-import { createCoreArtifact } from './core-artifacts.js';
+import { adoptCoreArtifactFile, createCoreArtifact } from './core-artifacts.js';
 import {
   activateCoreWatch,
   beginCoreAttempt,
@@ -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' })
 });
@@ -155,13 +158,15 @@ async function deliverArtifacts(dataRoot, taskId, adapter, remoteArtifacts, sign
     }
     recordCoreDownloadCompleted(dataRoot, taskId);
     for (const staged of stagedFiles) {
-      const artifact = createCoreArtifact(dataRoot, {
+      const input = {
         kind: profile.kind,
         mediaType: staged.mediaType,
-        bytes: staged.bytes || fs.readFileSync(staged.target),
         metadata: { taskId, capability: task.capability },
         ...(task.sourceArtifactId ? { relations: [{ type: 'derived-from', artifactId: task.sourceArtifactId }] } : {})
-      });
+      };
+      const artifact = staged.bytes
+        ? createCoreArtifact(dataRoot, { ...input, bytes: staged.bytes })
+        : adoptCoreArtifactFile(dataRoot, { ...input, sourcePath: staged.target });
       artifactIds.push(artifact.id);
     }
     return completeCoreDelivery(dataRoot, taskId, artifactIds);
@@ -193,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 结果，使重启和故障边界可重复验证。
@@ -234,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,
@@ -246,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, {
@@ -264,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 });
@@ -273,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
         });
       }
@@ -306,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/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@mokuyoaxis/dsh-iris",
-  "version": "0.2.1",
-  "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.3",
+  "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,6 +28,7 @@
     "!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"
   ],
@@ -54,6 +55,7 @@
     "dsh-plugin",
     "image-generation",
     "video-generation",
+    "music-generation",
     "text-to-speech",
     "transcription",
     "vision",

package/user_guide.md

@@ -1,10 +1,12 @@
 # dsh-iris 用户指南
 
-本指南说明如何安装、配置和使用 Iris 0.2.1。升级范围见 [CHANGELOG](CHANGELOG.md) 和 [发布说明](docs/releases/0.2.1.md)。
+本指南说明如何安装、配置和使用 Iris 0.2.3。升级范围见 [CHANGELOG](CHANGELOG.md) 和 [发布说明](docs/releases/0.2.3.md)。
+
+0.2.2 的能力来自明确功能标签、旧能力字段绑定或供应商能力元数据，账号和名称不再自动赋能。已有明确配置保留；仅有裸账号的配置需要先给实际模型设置功能，再加入有序候选池。
 
 ## 安装
 
-先运行 `dsh --version`。Iris `0.2.1` 仅声明支持 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.1 要求 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.3` 仅声明支持 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.x 要求 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 范围内，从 npm 安装固定稳定版到 Web profile：
 
@@ -15,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.1。
+只下载旧稳定包可运行 `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.3。
 
 在 DSH `0.2.0-rc.2` 上，从 npm 安装：
 
 ```bash
-dsh plugin --profile web add @mokuyoaxis/dsh-iris@0.2.1
+dsh plugin --profile web add @mokuyoaxis/dsh-iris@0.2.3
 dsh web
 ```
 
@@ -28,7 +30,7 @@ dsh web
 
 ### 独立 CLI
 
-无需 DSH，在自己的项目安装 `npm install @mokuyoaxis/dsh-iris@0.2.1`，通过 `npx dsh-iris --help` 查看入口。详见 [Headless CLI](docs/HEADLESS_CLI.md) 和 [视觉 CLI](docs/VISION_CLI.md)。
+无需 DSH，在自己的项目安装 `npm install @mokuyoaxis/dsh-iris@0.2.3`，通过 `npx dsh-iris --help` 查看入口。详见 [Headless CLI](docs/HEADLESS_CLI.md) 和 [视觉 CLI](docs/VISION_CLI.md)。
 
 其他 DSH 版本，包括 `0.2.0` 正式版与其他 rc，须另行验收。让 Agent 协助安装时，可使用[简要 Prompt](docs/AGENT_QUICKSTART.md)。
 
@@ -51,6 +53,7 @@ dsh --profile web --dump-config
 3. Base URL 填 `https://dashscope.aliyuncs.com/compatible-mode/v1`；如果账号使用百炼业务空间专属域名，再把“媒体 Base URL”填为同地域的 `https://{WorkspaceId}.cn-beijing.maas.aliyuncs.com/compatible-mode/v1`（地域按账号实际情况替换）。
 4. 填入与模型、Endpoint 同地域的 DashScope API Key，点击“保存”。
 5. 展开刚添加的供应商，点击“发现模型”。
+6. 若模型显示“未标注功能”，点击其“设置功能”，勾选已确认支持的功能并保存。
 
 如果只有一个供应商，可以先保留“能力分配”为自动。Iris 会从模型池中为画图、视频、语音、转写和视觉能力选择第一个匹配模型。需要固定模型或设置故障转移顺序时，再到“能力分配（failover 顺序）”中调整。
 
@@ -75,9 +78,9 @@ Iris 当前支持两类调用路径：
 
 ## 模型池
 
-“发现模型”对普通 OpenAI 兼容服务读取 `GET /models`；对阿里云官方端点读取并分页拉完 `GET /api/v1/models`。官方 `IG/VG/ASR/TTS/VU` 能力元数据优先，缺少元数据时才按模型名兜底。用户手工纠正的能力标签优先级最高，后续重新发现不会覆盖。发现失败时，原模型池不会被清空。
+“发现模型”对普通 OpenAI 兼容服务读取 `GET /models`；对阿里云官方端点读取并分页拉完 `GET /api/v1/models`。供应商返回的 `IG/VG/ASR/TTS/VU` 等明确能力元数据用于功能分类；只有名称或未知能力时，模型显示“未标注功能”，需手动设置。已有明确配置（包括空标签）优先，后续重新发现不会覆盖。分类声明仍需实测，不证明远端接口已经可用。发现失败时，原模型池不会被清空。
 
-模型发现采用合并更新：保留手工模型、手工能力标注及本次目录未返回的旧模型，只追加或更新发现项。删除模型仍需用户显式操作。运行时仅使用已配置模型；某项能力缺少模型时会提示配置，不再猜测厂商默认值。旧裸账号的兼容目录会在配置写入时转成可编辑的模型条目，显式空模型池不会触发该迁移。
+模型发现采用合并更新：保留手工模型、明确功能标签及本次目录未返回的旧模型，只追加或更新发现项。删除模型仍需用户显式操作。裸账号在保存或加载时都不再补厂商默认模型；已经保存的模型和标签保留，`imageModel` 等旧字段仍作为明确功能绑定兼容。空模型池、空能力标签保持权威。某项功能没有候选时会提示配置。
 
 模型池中的能力名称如下：
 
@@ -90,7 +93,11 @@ Iris 当前支持两类调用路径：
 | 音频转写 | `transcribe` | `iris_transcribe_audio` |
 | 视觉理解 | `vision` | `iris_look_at_image`、OCR、定位、视频摘要 |
 
-没有 `/models` 接口时，可以在供应商的模型池中手动添加模型名。Iris 能识别常见的 wan、qwen-vl、qwen-tts、qwen-audio ASR Filetrans、Fun-ASR、paraformer、gpt-image、dall-e 和 Gemini 命名；无法识别的模型需要在高级配置中显式填写 `capabilities`。
+没有 `/models` 接口时，可以手动添加模型名，再通过“设置功能”明确选择用途；也可在配置中填写模型的 `capabilities`。省略标签时保持未标注，即使名字像已知媒体模型也不会进入功能候选链。
+
+未提供标签的模型仍可在后续发现中接收供应商能力元数据；显式保存空标签表示当前不加入任何功能池，发现不会覆盖该选择。
+
+Iris 先按画图、视频、语音、转写和视觉功能组织候选池，再按该功能的能力分配顺序选模型；每次从首项开始，生成只有明确未受理才切换。标注功能不会发起实测、生成或改变分配顺序。
 
 点击模型旁单项能力标记会进行验证。视觉、图片和 TTS 会先显示确认框，再发起真实供应商请求，不是本地校验：
 
@@ -122,22 +129,30 @@ Iris 当前支持两类调用路径：
 
 每项能力都可以设置一个有序的“供应商 + 模型”列表。界面显示的是模型名和供应商，配置中保存为 `providerId::modelId` 复合引用，因此不同供应商的同名模型不会冲突。
 
-- 未手工分配时，每个新请求都从模型池第一个匹配项开始；这不是 round-robin。
+- 图片、视频、语音、转写与视觉未手工分配时，从模型池第一个匹配项开始；音乐仅使用明确分配名单。
 - 手工列表中的模型优先，并按列表顺序尝试。
-- 模型池中其余具备该能力的模型仍会作为后续候选。
-- 点击“恢复自动”会清除手工顺序。
+- 除音乐外，模型池中其余具备该能力的模型仍会作为后续候选。
+- 点击“恢复自动”会清除手工顺序；音乐清空名单后需重新分配才能生成。
 
 生成类故障转移只覆盖上传、提交和同步生成阶段。远端一旦受理异步任务，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
@@ -236,11 +251,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 对比当前截图和参考图，定位偏差并给出有证据的结论
@@ -250,18 +269,20 @@ Iris 工作台中的文件字段提供三种方式：
 
 ## 对话框提示词优化
 
-0.2.1增加“智能优化 / 只组装”、本次规则、可编辑结果和改动对照，详见 [提示词优化与规则组装](docs/PROMPT_OPTIMIZER.md)。规则按次传入，不修改现有 v1 配置；后续独立提示词优化系统另行安排。
+0.2.2 在既有只组装、本次规则和可编辑对照上提供一般功能：默认忠实整理、可选改写表达、独立补充建议，以及折叠卡、改图用途与贴近 Skills 的指令；特殊功能后续安排。详见 [提示词优化与规则组装](docs/PROMPT_OPTIMIZER.md)。规则按次传入，原有自定义 v1 配置保留，读取旧配置不自动重写。
 
 安装并启用 Iris 后，DSH 对话输入区会出现一个没有边框、底色和文字的“🫧”入口。点击后打开半透明玻璃悬浮窗；桌面端靠近输入区，手机窄屏自动变为底部面板，并适配浏览器安全区、可用高度和内部滚动。它独立于 Iris 工作台，可用于普通问答、写作、编程以及图片/视频生成提示词。[查看 Android 16 真机完整流程](docs/screenshots.md)。
 
 使用流程：
 
 1. 在对话框写入草稿，点击“🫧”。
-2. 选择“通用对话、图片生成、视频生成、首尾帧视频”之一。
-3. 点击“生成预览”。此时会调用模型，可能产生费用。
-4. 检查结果后选择“写回输入框、复制、再优化”或“恢复原文”。Iris 不会自动发送消息。
+2. 在一般功能中选择“通用、画图、改图、视频、数字人”（旧 0.2.1 的四目标调用保持兼容）。
+3. 默认“忠实整理”，保持原文与句序，只调整分组/分段；单片段直接保留原文，不调用模型。需要润色或明确改变指定内容时选择“改写表达”，再展开本次规则；只组装仍原样拼接草稿与前后缀，不调用模型。旧后端保留“智能优化”。
+4. 编辑预览、检查原文与改动，然后选择“写回输入框、复制、重新生成预览”或“恢复原文”。需要额外创意时展开“可选补充与待确认”，点击获取才调用一次模型；勾选后还需点击采纳才加入预览，可以撤回上次采纳。手动编辑会清除旧建议绑定；建议与待确认问题不代表已验证事实或用户已有要求。折叠不清空选择和结果，Iris 不会自动发送消息。
+
+默认路由是当前会话模型；当前会话没有选择时使用 DSH 默认模型，固定配置优先于这两项。预览显示实际选择原因。“指令与模型设置”可查看指令、导出/导入 JSON，选择“仅恢复默认指令”或“恢复全部设置”；前者保留模型、生成参数和入口开关。配置单独保存在 `$DSH_HOME/iris/v1/prompt-optimizer.json`，不包含供应商 API Key，也不与 `providers.json` 混合。
 
-默认路由是当前会话模型；当前会话没有选择时使用 DSH 默认模型。面板中的“JSON 配置”可以导出当前配置、导入修改后的 JSON，或恢复 Iris 内置默认值。配置单独保存在 `$DSH_HOME/iris/v1/prompt-optimizer.json`，不包含供应商 API Key，也不与 `providers.json` 混合。
+再次优化失败或取消会保留已有预览，等待期间继续编辑时，新结果不会覆盖手工改动。配置异常会说明默认值和原文件保留状态；导入前可先导出备份。
 
 导出文件格式：
 
@@ -273,8 +294,9 @@ Iris 工作台中的文件字段提供三种方式：
   "targets": {
     "general": "通用任务的补充要求",
     "image": "图片提示词的补充要求",
+    "image-edit": "明确修改范围并保持原图其余特征",
     "video": "视频提示词的补充要求",
-    "s2v": "首尾帧视频的补充要求"
+    "s2v": "首帧加音频数字人视频的补充要求"
   },
   "route": {
     "mode": "session"
@@ -317,6 +339,12 @@ Task v2 将“供应商是否受理、观察是否继续、远端结果和本地
 
 旧版任务会明确显示“旧任务 · 只读”。只有服务端明确返回 `schemaVersion=1` 才使用该标签；客户端与服务端热更新暂时不同步时，不会把字段缺失的新任务误判为旧任务。
 
+### 生图错误诊断（0.2.2）
+
+即时错误与任务详情显示同一脱敏原因。包装的网络异常保留请求或正文读取阶段及可用的底层错误码，可区分 DNS/TLS、连接建立超时、等待响应头超时和正文中断；原生取消/超时保持各自分类，鉴权、参数、限流及额度错误分别分类。`fetch failed` 本身不能证明图片太大或网关回收长连接，需结合阶段与错误码判断。
+
+尺寸按当前协议归一分隔符。DashScope 多模态只校验已确认的总像素范围，合法长边不受额外单边上限限制；本地面积不合法明确记为未受理。传输中断仍保留受理未知，不自动重提收费请求。HTTP 200 响应头不等于正文完整或图片已交付；生成成功后的本地交付失败仍与生成结果分开记录。详见 [Provider Adapter 契约](docs/PROVIDER_ADAPTER_CONTRACT.md#错误与取消传播)。
+
 ### 清除历史与作品库
 
 工作台中的作品库独立于任务历史。新落盘媒体会自动入库；首次升级会接回已有 `outputs/`，也可以随时点击“找回本地作品”重新扫描。清空已完成任务或清理旧任务只删除任务状态、Prompt、错误与重试记录，作品仍可在工作台和泡泡打开。
@@ -353,11 +381,11 @@ 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.1 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.3 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.3 包含 16 个工具（含音乐）和三项 Skill；升级后需重启服务端、刷新页面，并为要使用的功能分配模型。点击“刷新”查看结果，原始JSON可在已认证的同一浏览器访问 `/iris/api/doctor`。
 
 Host Doctor 不打开 Browser、不读取附件或会话、不调用模型，也不请求供应商。报告中的 `exitCode` 是诊断严重度，不是 HTTP 状态：`0` 全部健康，`1` 有可降级警告，`2` 有硬错误。未安装 HTML Browser 时出现一条 Browser 警告是预期降级；如果提示尚未收到客户端握手，刷新 DSH 页面后再点“刷新”。若显示 `not found`，通常是前端已更新而 DSH 后端仍运行旧插件代码，应重启 DSH 后再刷新页面。
 
@@ -394,7 +422,7 @@ dsh plugin --profile web remove @mokuyoaxis/dsh-iris
 - **对话框没有“🫧”入口**：确认 Iris 客户端已加载且当前存在会话；再到“设置 → Iris 工作台 → 对话框提示词优化”检查是否被单独关闭。
 - **提示词优化提示没有模型**：先在当前会话选择主模型，或在 JSON 中配置 `route.mode: "fixed"`。
 - **设置中没有 Iris 工作台**：确认插件已加入 Web profile，并在安装后重启 DSH；可用 `dsh plugin --profile web list` 和 `--dump-config` 检查。
-- **没有可用模型**：先确认供应商已启用且 Key 有效，再运行“发现模型”；不支持 `/models` 时手动添加。
+- **没有可用模型**：先确认供应商已启用且 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` 模型。