@mokuyoaxis/dsh-iris 0.2.2 → 0.2.3

package/README.en.md

@@ -18,7 +18,9 @@
   <a href="LICENSE"><img alt="MIT License" src="https://img.shields.io/badge/license-MIT-1689FF.svg?style=flat-square"></a>
 </p>
 
-dsh-iris gives agents, the Iris workbench and a standalone CLI image, video, speech and visual understanding capabilities. Each image model can use DashScope, OpenAI Images, chat image generation or Responses. Shared Core Artifacts connect generation, vision, OCR and chat editing. The DSH workbench provides configuration and task management, while the 🫧 bubble offers draft optimization in the composer.
+dsh-iris gives agents, the Iris workbench and a standalone CLI image, video, music, speech and visual understanding capabilities. Each image model can use DashScope, OpenAI Images, chat image generation or Responses. Shared Core Artifacts connect generation, vision, OCR and chat editing. The DSH workbench provides configuration and task management, while the 🫧 bubble offers draft optimization in the composer.
+
+Music uses a Chat Completions interface with inline audio, explicit model assignment, configurable 502 retries, and playback/export. See [Music setup and usage](docs/MUSIC.md) (Chinese).
 
 ## A real generation example
 
@@ -44,23 +46,23 @@ These captures come from an Android browser connected to DSH under Termux/PRoot
 
 The project is at an early stage; interfaces and configuration formats may still change between releases.
 
-Iris 0.2.2 provides a DSH plugin and a headless CLI sharing tasks, artifacts and model routing, adding controlled prompt editing and reliable media execution while retaining the OpenAI-compatible image and vision workflow. Core internals have not been frozen as a public SDK.
+Iris 0.2.3 provides a DSH plugin and a headless CLI sharing tasks, artifacts and model routing, adding music generation, three agent skills, synchronous delivery recovery, and prompt editor improvements. Core internals have not been frozen as a public SDK.
 
 > Version support: Iris `0.2.x` requires Node.js `>=22.0.0` and its DSH plugin supports only the exact host version `0.2.0-rc.2`. Older DSH hosts should pin `@mokuyoaxis/dsh-iris@0.1.4` as described below instead of following npm latest. Iris and DSH have independent version numbers.
 
-## What's new in 0.2.2
+## What's new in 0.2.3
 
-**Controlled prompt editing and reliable media execution**, building on the existing OpenAI-compatible image and vision workflow.
+**Music creation, agent guidance, and media delivery recovery.**
 
-- **General prompt editor:** five collapsible targets and editable comparisons; faithful grouping by default, explicit rewriting and separately requested/adopted suggestions.
-- **Explicit function pools:** capabilities come from configuration or trusted metadata; bare accounts and model names do not grant capabilities. Ordered candidates and explicit labels remain.
-- **Core recovery and delivery:** retain writer intent and interrupted recovery evidence; use file adoption and chunked hashes for non-image media without automatic lease takeover or regeneration.
-- **Image diagnostics:** normalize size separators, accept valid long edges and identify local rejection before HTTP; distinguish network/body failures, cancellation/timeouts and complete HTTP errors.
-- **Portable regressions:** match interruption checkpoints using physical root paths and native filename handling.
+- **Music generation:** assign music models independently and generate MP3/WAV through the agent, workbench, or CLI, with playback, download, export, and bounded 502 retries.
+- **Three agent skills:** guidance for single media operations, creative workflows, and UI acceptance; music remains optional.
+- **Delivery recovery:** redeliver cached synchronous results through the original task without generating again.
+- **Prompt editing:** retain previews after errors or cancellation, skip model calls for single-part faithful grouping, and reset instructions separately from model settings.
+- **Routing and format feedback:** explain text model selection and check rewrite output while retaining custom v1 configuration.
 
-See the [0.2.2 release notes](docs/releases/0.2.2.md) and [CHANGELOG](CHANGELOG.md) for scope and validation boundaries.
+See the [0.2.3 release notes](docs/releases/0.2.3.md) and [CHANGELOG](CHANGELOG.md) for scope and validation boundaries.
 
-Future work includes additional protocol adapters and **music generation**; see the [roadmap](docs/ROADMAP.md#后续功能方向).
+Future work includes additional protocol adapters and creative workflows; see the [roadmap](docs/ROADMAP.md#后续功能方向).
 
 ## Two ways to use Iris
 
@@ -76,11 +78,11 @@ Both paths read and write the same Core Task/Artifact facts: point the CLI at th
 
 > Install size note: image processing depends on `sharp` and its prebuilt binaries (~27 MB). On uncommon platforms (e.g. some ARM proot environments) a failed sharp install is detected by `dsh-iris doctor`; image actions become unavailable while everything else keeps working.
 
-## Relationship with ai-paint
+## Optional legacy configuration import
 
-`ai-paint` is the maintainer's local, unpublished predecessor of Iris. It is not a public dependency, and users never need to download, install, or create it. Without that project, simply configure providers in the Iris workbench as described below.
+For a new installation, add providers in the Iris workbench. Iris uses its own configuration and does not scan other projects by default.
 
-Early versions read models and credentials from the maintainer's local ai-paint configuration — partly to migrate the predecessor project, and partly so the host process could reuse an existing API key locally instead of pasting keys into agent sessions, command-line arguments, or documents. Version 0.1.1 separates the two configurations completely: Iris uses only its own configuration. The old one can be imported exactly once, and only by explicitly setting `IRIS_IMPORT_WORKBENCH_CONFIG` to the absolute path of the local config file. Iris never scans for ai-paint by default and never syncs the two sides. The variable carries a file path, not an API key, and the source file is left untouched. See the [user guide](user_guide.md) for details.
+If you already have an ai-paint configuration, set `IRIS_IMPORT_WORKBENCH_CONFIG` to its absolute file path for a one-time provider import. Iris leaves the source untouched and does not keep configurations synchronized. The variable holds a file path, not an API key. See the [user guide](user_guide.md) for details.
 
 ## Quickest start
 
@@ -88,7 +90,7 @@ Check the host with `dsh --version` and ensure `pnpm` is on your PATH. Iris and
 
 | Your DSH | Iris choice | Source |
 |---|---|---|
-| `0.2.0-rc.2` | `0.2.2` | Pinned npm release |
+| `0.2.0-rc.2` | `0.2.3` | Pinned npm release |
 | `>=0.1.2-rc.1 <0.1.3-0` or `0.1.5-rc.1` | Stable `0.1.4` | Pinned npm release |
 | Other versions | No current support claim | Check host adaptation before installing |
 
@@ -109,29 +111,29 @@ npm pack @mokuyoaxis/dsh-iris@0.1.4
 
 This writes a `.tgz` to the current directory. Use `npm install @mokuyoaxis/dsh-iris@0.1.4` if you only want a regular npm dependency; that does not add a DSH profile layer. Pinning `@0.1.4` keeps selecting the old stable release after latest changes. See [npm pack](https://docs.npmjs.com/cli/v11/commands/npm-pack/). Version 0.1.4 does not contain the 0.2.0 Core media CLI or the later DSH rc.2 adaptation.
 
-### DSH 0.2.0-rc.2: install 0.2.2
+### DSH 0.2.0-rc.2: install 0.2.3
 
 Install the pinned release into your Web profile:
 
 ```bash
-dsh plugin --profile web add @mokuyoaxis/dsh-iris@0.2.2
+dsh plugin --profile web add @mokuyoaxis/dsh-iris@0.2.3
 dsh web
 ```
 
 The plugin loads on the next DSH start. The web UI defaults to `http://127.0.0.1:3080`; open the complete URL if startup output includes authentication parameters. Reload the backend and refresh the web client after updating.
 
-### Standalone CLI: install 0.2.2
+### Standalone CLI: install 0.2.3
 
 Install in your own project without DSH:
 
 ```bash
-npm install @mokuyoaxis/dsh-iris@0.2.2
+npm install @mokuyoaxis/dsh-iris@0.2.3
 npx dsh-iris --help
 ```
 
 ### Choosing a version in dsh-market
 
-The marketplace entry should resolve to the full package name `@mokuyoaxis/dsh-iris`. Check both its displayed Iris version and your local `dsh --version` before installing: 0.2.2 is for DSH rc.2; older hosts should use the pinned `@0.1.4` commands above. Catalog and npm information may be cached. The actual npm package's `dsh.engines.dsh` and Node engines determine its declared requirements; a visible listing does not imply support for every DSH release.
+The marketplace entry should resolve to the full package name `@mokuyoaxis/dsh-iris`. Check both its displayed Iris version and your local `dsh --version` before installing: Iris 0.2.x is for DSH rc.2; older hosts should use the pinned `@0.1.4` commands above. Catalog and npm information may be cached. The actual npm package's `dsh.engines.dsh` and Node engines determine its declared requirements; a visible listing does not imply support for every DSH release.
 
 > The unscoped `dsh-iris` on npm belongs to a different plugin. Always keep the fully scoped name `@mokuyoaxis/dsh-iris` when installing or updating Iris Media.
 
@@ -154,7 +156,7 @@ For a copyable installation and usage prompt, see [Agent quickstart prompt](docs
 ![Iris architecture overview](docs/assets/diagrams/iris-architecture.png)
 
 - Image generation, text-to-video, image-to-video, and S2V digital-human video
-- Text-to-speech and audio transcription
+- Music generation, text-to-speech, and audio transcription
 - Visual question answering, long-image OCR, target grounding, cropping, and pixel-diff analysis
 - Video frame extraction and multimodal video summarization
 - Asynchronous task tracking, restart recovery, and token-authorized media playback
@@ -165,7 +167,7 @@ For a copyable installation and usage prompt, see [Agent quickstart prompt](docs
 
 ## Prerequisites
 
-- A Node.js version that satisfies your DeepSeek Harness release's requirement; Iris 0.2.2 requires at least 22.0.0, while the published npm 0.1.4 historically requires 20.10.0
+- A Node.js version that satisfies your DeepSeek Harness release's requirement; Iris 0.2.x requires at least 22.0.0, while the published npm 0.1.4 historically requires 20.10.0
 - A working DeepSeek Harness environment with `pnpm` on the PATH
 - At least one supported media or vision provider
 - `ffmpeg` and `ffprobe` for extracting frames or summarizing a video file; summaries of existing Core frames need neither
@@ -174,7 +176,7 @@ After installing the plugin, add a provider in the Iris workbench and assign mod
 
 ## DeepSeek Harness adaptation
 
-dsh-iris remains a native DSH plugin. Iris 0.2.2 server registers 15 agent tools, including image editing, and uses host-provided routing, attachment, model, and lifecycle services. The web client contributes settings, composer, and global-overlay UI. Iris does not start another service or listen on an extra port.
+dsh-iris remains a native DSH plugin. Iris 0.2.3 server registers 16 agent tools, including image editing and music, and uses host-provided routing, attachment, model, and lifecycle services. The web client contributes settings, composer, and global-overlay UI. Iris does not start another service or listen on an extra port.
 
 | Iris version | DSH range | Verification |
 |---|---|---|
@@ -182,6 +184,7 @@ dsh-iris remains a native DSH plugin. Iris 0.2.2 server registers 15 agent tools
 | Published stable `0.1.4` | `0.1.5-rc.1` | Historical daily Android/Linux profile checks |
 | `0.2.0` | Only `0.2.0-rc.2` | Installed-service isolation checks, Core diff, and SlotRegistry; user demonstration reported successful, with detailed browser actions and asynchronous restart/rollback verification continuing |
 | `0.2.2` | Only `0.2.0-rc.2` | Installed-service checks cover 15 tools and 31 boundaries; complete browser/mobile and real asynchronous restart acceptance remain pending |
+| `0.2.3` | Only `0.2.0-rc.2` | Adds music and a third skill; check actual loading with Host Doctor after upgrading |
 
 See the [rc.2 adaptation notes](docs/DSH_RC2_ADAPTATION.md) for scope. The published npm 0.1.4 package does not contain these later changes.
 
@@ -198,6 +201,7 @@ Core and the DSH Adapter are being separated: DSH keeps loading the same npm pac
 | `iris_draw_image` | Generate images from a prompt |
 | `iris_edit_image` | Edit a source Artifact into a new image with a chat image model, preserving provenance |
 | `iris_generate_video` | Text-to-video, image-to-video, or S2V digital-human video |
+| `iris_generate_music` | Generate music from a description and save playable, downloadable audio |
 | `iris_speak_text` | Synthesize speech from text |
 | `iris_transcribe_audio` | Transcribe audio to text |
 | `iris_task_status` | Check the status and outputs of one task or the recent tasks |
@@ -251,7 +255,7 @@ Iris organizes ordered model candidates by function. Capability assignments iden
 
 Version 0.2.2 uses explicit function labels, legacy capability bindings, or provider capability metadata. Bare accounts and model names no longer grant capabilities. Discovery retains unlabelled models; assign their functions in the workbench or with CLI `models caps`. Existing explicit labels, assignment order and safe failover are preserved. Earlier 0.2.1 inference no longer grants capabilities to bare accounts or model names.
 
-Generation capabilities accept multiple candidate models. Every request starts at the head of the ordered list; this is safe failover, not round-robin. Iris tries the next candidate only when the provider explicitly proves that the request was not accepted. A 500 response, timeout, disconnect, missing response, polling failure, or local persistence failure never authorizes automatic resubmission. Once accepted, Iris may only resume observation or delivery.
+Generation capabilities accept multiple candidate models. Every request starts at the head of the ordered list; this is safe failover, not round-robin. Iris tries the next candidate only when the provider explicitly proves that the request was not accepted. A 500 response, timeout, disconnect, missing response, polling failure, or local persistence failure never authorizes automatic resubmission. Once accepted, Core may only resume observation or delivery. The music entry point separately supports configured, bounded HTTP 502 retries as linked new tasks; these may consume extra quota and can be disabled with `retry_502: 0`. See [Music](docs/MUSIC.md).
 
 The workbench lists paused observation, unknown acceptance/outcome, and successful generation with failed delivery under “Needs attention.” Re-observe never submits; re-deliver never regenerates; acknowledge/restore only changes the local reminder queue; only an explicitly confirmed informed retry creates a linked new task and may incur duplicate charges. Creating that task archives the original reminder while preserving its unknown facts and audit link. See [Task semantics](docs/TASK_SEMANTICS.md), [Architecture](docs/ARCHITECTURE.md), [Security](docs/SECURITY.md), and the [Fault-injection matrix](docs/FAULT_INJECTION.md).
 
@@ -276,11 +280,11 @@ npx @mokuyoaxis/dsh-iris doctor --json
 
 The installed binary is `dsh-iris`. Exit code `0` is healthy, `1` means warnings, and `2` means hard errors. Offline Doctor checks Node.js, sharp, ffmpeg/ffprobe, a real but cleaned-up storage write probe, configuration, models/assignments, task semantics, temporary files, and orphaned or missing artifacts.
 
-A running DSH instance also provides a “Host diagnostics” card in the Iris workbench and exposes the authenticated `/iris/api/doctor` JSON. It checks the DSH version, plugin, current tools, two Skills, four route groups, Browser/attachment/model capabilities, client version, and four UI Slots. It reads only safe snapshots and registration evidence; it never calls Browser, models, or providers. See [Host Doctor](docs/HOST_DOCTOR.md).
+A running DSH instance also provides a “Host diagnostics” card and the authenticated `/iris/api/doctor` JSON. It checks the DSH version, plugin, current tools and bundled skills, four route groups, host capabilities, client version, and four UI Slots. Version 0.2.3 checks 16 tools and three skills. It reads safe registration evidence without calling Browser, models, or providers. See [Host Doctor](docs/HOST_DOCTOR.md).
 
 ## Composed workflow example
 
-Iris ships two agent skills (`iris-verify-ui` and `iris-compose-media`) that chain multiple tools into bounded, reviewable media workflows. The example below is "look → redraw → self-check": understand the source image first, then generate, review against concrete mismatches, and only deliver once the review passes.
+Three bundled skills guide single media operations, creative workflows, and UI acceptance. The existing "look → redraw → self-check" example below is one optional route: review follows the requested goal, useful outputs remain available, and music is an optional asset step.
 
 ![Composed workflow example](docs/assets/diagrams/iris-workflow-compose.png)
 
@@ -329,24 +333,27 @@ Legacy media links carry random capability tokens. Core media uses random Artifa
 
 ## Agent Skills
 
-When the plugin is enabled, it automatically registers the two bundled skills through the DSH skill registry:
+The DSH skill registry receives three bundled skills:
 
 | Skill | When to use |
 |---|---|
-| [`iris-verify-ui`](.dsh/skills/iris-verify-ui/SKILL.md) | Combine screenshots, semantic inspection, element grounding, cropping, and pixel comparison into evidence-based UI acceptance |
-| [`iris-compose-media`](.dsh/skills/iris-compose-media/SKILL.md) | Chain two or more Iris tools into media workflows: inspect-then-draw, image-to-video, video summary with narration, S2V, and more |
+| [`iris-use`](.dsh/skills/iris-use/SKILL.md) | Single generation/editing, vision/OCR, speech, music, task queries, and artifact delivery |
+| [`iris-compose-media`](.dsh/skills/iris-compose-media/SKILL.md) | Image revisions, video assets, narration, S2V, and optional music |
+| [`iris-verify-ui`](.dsh/skills/iris-verify-ui/SKILL.md) | Interface reproduction and screenshot acceptance, including confirmed failure |
 
-From 0.1.2, as long as the host provides the DSH skill registry, regular npm installs can discover and load both skills from any project directory — no need to clone this repository or configure a skill search path. When the project directory contains same-name skills, DSH's native precedence keeps using the project versions; if the skill registry is unavailable, the Iris tools still load on their own.
+Skills work independently of the session working directory. Project skills retain precedence, and tools still load when the registry is unavailable. All three use the [shared capability and artifact contract](.dsh/skills/iris-use/references/media-contract.md).
 
-For deterministic selection, invoke either skill with DSH's `/name` form:
+To select a skill explicitly, use DSH's `/name` form:
 
 ```text
+/iris-use Generate a rock soundtrack and return its audio artifact and playback link
+
 /iris-compose-media Inspect my uploaded product photo, create a matching poster, then verify the requested constraints
 
 /iris-verify-ui Compare the current screenshot with the reference, locate regressions, and return an evidence-based verdict
 ```
 
-Natural-language discovery remains available. Do not force the composition skill for a single draw, OCR, or transcription action; ask directly or name the matching Iris tool. Skills plan tool use but never bypass Iris task, cost-confirmation, or safety boundaries.
+Natural-language requests and direct tool calls remain available. `iris-use` guides single operations; composition guides multi-step work, with music added only when requested. Skills do not replace tool loading or model assignment, or alter task and cost-confirmation boundaries.
 
 ## Development and verification
 

package/README.md

@@ -18,7 +18,7 @@
   <a href="LICENSE"><img alt="MIT License" src="https://img.shields.io/badge/license-MIT-1689FF.svg?style=flat-square"></a>
 </p>
 
-dsh-iris 为 Agent、Iris 工作台和独立 CLI 提供图像、视频、语音与视觉理解能力。图片模型可分别连接 DashScope、OpenAI Images、聊天生图或 Responses 接口；生成作品由共享 Core 管理，可按 Artifact ID 看图、OCR 和聊天改图。DSH 工作台集中配置与任务管理，🫧 泡泡提供对话草稿优化入口。
+dsh-iris 为 Agent、Iris 工作台和独立 CLI 提供图像、视频、音乐、语音与视觉理解能力。图片模型可分别连接 DashScope、OpenAI Images、聊天生图或 Responses 接口；音乐支持 Chat Completions 内嵌音频接口。生成作品由共享 Core 管理，可按 Artifact ID 看图、OCR、聊天改图或导出。DSH 工作台集中配置与任务管理，🫧 泡泡提供对话草稿优化入口。
 
 ## 实际生成示例
 
@@ -44,23 +44,23 @@ dsh-iris 为 Agent、Iris 工作台和独立 CLI 提供图像、视频、语音
 
 项目目前处于早期版本，接口和配置格式仍可能随版本迭代调整。
 
-Iris 0.2.2 同时提供 DSH 插件与无 DSH 的 CLI，共用任务、产物和模型路由，升级可控提示词编辑与媒体运行可靠性，保留 OpenAI 兼容图片与视觉工作流。Core 内部接口尚未冻结为公共 SDK。
+Iris 0.2.3 同时提供 DSH 插件与无 DSH 的 CLI，共用任务、产物和模型路由，加入音乐生成、三项 Agent Skills 和同步媒体交付恢复，并完善提示词编辑。Core 内部接口尚未冻结为公共 SDK。
 
 > 版本支持：Iris `0.2.x` 要求 Node.js `>=22.0.0`，DSH 插件仅支持准确版本 `0.2.0-rc.2`。旧 DSH 使用下文列出的 `@mokuyoaxis/dsh-iris@0.1.4`，不要直接跟随 npm latest 更新。Iris 与 DSH 的版本号独立。
 
-## 0.2.2 更新重点
+## 0.2.3 更新重点
 
-**可控提示词编辑与媒体运行可靠性**，在既有 OpenAI 兼容图片与视觉工作流上继续完善。
+**音乐创作、Agent 使用引导与媒体交付恢复**。
 
-- **提示词一般功能**：折叠五用途、原稿与改动预览；默认忠实整理，明确改写与独立建议需用户选择。
-- **明确功能模型池**：能力来自配置或可信元数据，裸账号与名称不自动赋能；保留功能入口、有序候选和既有明确标签。
-- **Core 恢复与交付**：保留 writer 创建/释放/恢复中断证据，非图片产物使用文件接收与分块哈希；不自动抢占租约或重新生成。
-- **生图诊断**：尺寸分隔符归一、合法长边和本地未受理校验；区分网络/正文故障、取消/超时与完整 HTTP 业务错误。
-- **跨平台回归**：修复中断夹具的根路径别名与分隔符假设，保留实际检查点验证。
+- **音乐生成**：独立分配音乐模型，通过 Agent、工作台或 CLI 生成 MP3/WAV，可试听、下载和导出；支持配置有限的 502 重试。
+- **三项 Agent Skills**：分别指导单步媒体操作、多步骤创作与界面验收；配乐按需加入。
+- **交付恢复**：完整同步结果已缓存时，可沿原任务重新交付，无需重新生成。
+- **提示词编辑**：失败和取消保留已有预览，单片段忠实整理无需模型调用，配置恢复可只重置默认指令。
+- **路由与格式说明**：显示文本模型选择原因，检查改写正文格式，保留自定义 v1 配置。
 
-完整变化和待验边界见 [0.2.2 发布说明](docs/releases/0.2.2.md) 与 [CHANGELOG](CHANGELOG.md)。
+完整变化和升级说明见 [0.2.3 发布说明](docs/releases/0.2.3.md) 与 [CHANGELOG](CHANGELOG.md)。
 
-后续计划继续适配其他协议，并增加 **Music 音乐生成**功能，详见 [路线图](docs/ROADMAP.md#后续功能方向)。
+音乐的接口格式、模型分配与使用示例见 [Music](docs/MUSIC.md)。其他协议与后续能力见 [路线图](docs/ROADMAP.md#后续功能方向)。
 
 ## 两条使用路径
 
@@ -76,11 +76,11 @@ Iris 0.2.2 同时提供 DSH 插件与无 DSH 的 CLI，共用任务、产物和
 
 > 安装体积提示：图像处理依赖 `sharp` 及其预编译二进制（约 27MB）。冷门平台（如部分 ARM proot 环境）安装失败时 `dsh-iris doctor` 可检出，图像类动作不可用，其余能力不受影响。
 
-## 与 ai-paint 的关系
+## 可选的旧配置导入
 
-`ai-paint` 是 Iris 维护者本机未公开的前身项目，不是 Iris 的公开依赖，也不是用户需要下载、安装或自行创建的目录。没有该项目的用户直接按下文在 Iris 工作台配置供应商即可。
+首次使用时，直接在 Iris 工作台添加供应商。Iris 使用自己的配置，不会默认扫描其他项目。
 
-早期版本从维护者本机的 ai-paint 配置读取模型与凭据，既用于迁移前身项目，也让宿主进程可以在本地复用已有 API Key，避免为迁移而把密钥粘贴到 Agent 会话、命令行参数或文档中。0.1.1 将两者的配置彻底分离：Iris 只使用自己的配置；旧配置仅可通过把 `IRIS_IMPORT_WORKBENCH_CONFIG` 显式设为本地配置文件的绝对路径进行一次性导入，不会默认扫描 ai-paint，也不会在两边同步。该变量保存的是文件路径而不是 API Key，来源文件不会被修改；具体操作见[用户指南](user_guide.md#从旧工作台显式导入)。
+已有旧 ai-paint 配置时，可通过 `IRIS_IMPORT_WORKBENCH_CONFIG` 显式指定来源文件的绝对路径，一次性导入供应商；不修改来源文件、不持续同步。该变量保存文件路径，不包含 API Key。具体操作见[用户指南](user_guide.md#从旧工作台显式导入)。
 
 ## 最快开始
 
@@ -88,7 +88,7 @@ Iris 0.2.2 同时提供 DSH 插件与无 DSH 的 CLI，共用任务、产物和
 
 | 你的 DSH | Iris 选择 | 安装来源 |
 |---|---|---|
-| `0.2.0-rc.2` | `0.2.2` | 固定 npm 版本 |
+| `0.2.0-rc.2` | `0.2.3` | 固定 npm 版本 |
 | `>=0.1.2-rc.1 <0.1.3-0` 或 `0.1.5-rc.1` | 稳定版 `0.1.4` | 固定 npm 版本 |
 | 其他版本 | 暂无当前支持声明 | 先核对宿主适配，不能按相邻版本推定兼容 |
 
@@ -109,29 +109,29 @@ npm pack @mokuyoaxis/dsh-iris@0.1.4
 
 命令会在当前目录生成 `.tgz`。只需安装为普通 npm 依赖时可使用 `npm install @mokuyoaxis/dsh-iris@0.1.4`；这不会自动把插件加入 DSH profile。固定 `@0.1.4` 可在 latest 更新后继续取得旧稳定版本，见 [npm pack 文档](https://docs.npmjs.com/cli/v11/commands/npm-pack/)。0.1.4 不包含 0.2.0 的 Core 媒体 CLI，也不包含 DSH rc.2 的后续适配。
 
-### DSH 0.2.0-rc.2：安装 0.2.2
+### DSH 0.2.0-rc.2：安装 0.2.3
 
 安装固定版本到 Web profile：
 
 ```bash
-dsh plugin --profile web add @mokuyoaxis/dsh-iris@0.2.2
+dsh plugin --profile web add @mokuyoaxis/dsh-iris@0.2.3
 dsh web
 ```
 
 插件在下一次 DSH 启动时装载。Web UI 默认位于 `http://127.0.0.1:3080`；启动输出带认证参数时请打开完整 URL。更新后需重新加载后端并刷新客户端。
 
-### 独立 CLI：安装 0.2.2
+### 独立 CLI：安装 0.2.3
 
 在自己的项目中安装，无需 DSH：
 
 ```bash
-npm install @mokuyoaxis/dsh-iris@0.2.2
+npm install @mokuyoaxis/dsh-iris@0.2.3
 npx dsh-iris --help
 ```
 
 ### dsh-market 安装时的版本选择
 
-市场条目应对应完整包名 `@mokuyoaxis/dsh-iris`。安装前同时核对市场显示的 Iris 版本与本机 `dsh --version`：0.2.2 仅用于 DSH rc.2；旧宿主使用上面的固定 `@0.1.4` 命令。市场目录与 npm 信息可能有缓存，以实际 npm 包的 `dsh.engines.dsh` 和 Node engines 为准；市场中可见不代表任意 DSH 版本兼容。
+市场条目应对应完整包名 `@mokuyoaxis/dsh-iris`。安装前同时核对市场显示的 Iris 版本与本机 `dsh --version`：Iris 0.2.x 仅用于 DSH rc.2；旧宿主使用上面的固定 `@0.1.4` 命令。市场目录与 npm 信息可能有缓存，以实际 npm 包的 `dsh.engines.dsh` 和 Node engines 为准；市场中可见不代表任意 DSH 版本兼容。
 
 > npm 上无 scope 的 `dsh-iris` 属于另一款插件。安装和更新 Iris Media 时必须保留完整包名 `@mokuyoaxis/dsh-iris`。
 
@@ -142,6 +142,7 @@ npx dsh-iris --help
 ```text
 使用 iris_draw_image：画一只坐在蓝色窗边的白猫。
 总结我刚上传的这张图片。
+用 Iris 生成一首复古摇滚配乐，保存为音频作品。
 用 Iris 总结 /absolute/path/demo.mp4，再把摘要合成为语音。
 ```
 
@@ -154,7 +155,7 @@ DSH 的 profile 与插件命令由[官方安装说明](https://github.com/deepse
 ![Iris 架构总览](docs/assets/diagrams/iris-architecture.png)
 
 - 图像生成、文生视频、图生视频和 S2V 数字人视频
-- 文本转语音与音频转写
+- 音乐生成、文本转语音与音频转写
 - 看图问答、长图 OCR、目标定位、裁剪和像素差异分析
 - 视频抽帧与多模态内容摘要
 - 异步任务跟踪、重启恢复和带授权令牌的媒体播放
@@ -165,7 +166,7 @@ DSH 的 profile 与插件命令由[官方安装说明](https://github.com/deepse
 
 ## 使用前准备
 
-- 满足所用 DeepSeek Harness 版本要求的 Node.js；Iris 0.2.2 最低为 22.0.0，旧 npm 0.1.4 的历史要求为 20.10.0
+- 满足所用 DeepSeek Harness 版本要求的 Node.js；Iris 0.2.x 最低为 22.0.0，旧 npm 0.1.4 的历史要求为 20.10.0
 - 一个可用的 DeepSeek Harness 环境，以及 PATH 中的 `pnpm`
 - 至少一个受支持的媒体或视觉服务供应商
 - 从视频文件抽帧或摘要时，需要系统提供 `ffmpeg` 与 `ffprobe`；复用 Core 帧摘要无需这两个工具
@@ -174,7 +175,7 @@ DSH 的 profile 与插件命令由[官方安装说明](https://github.com/deepse
 
 ## DeepSeek Harness 适配
 
-dsh-iris 仍按 DSH 原生插件装载。0.2.2 服务端注册 15 个 Agent 工具（含改图），并使用宿主提供的路由、附件、模型和生命周期能力；Web 客户端接入设置页、会话输入区与全局悬浮层。插件不会启动额外服务或监听端口。
+dsh-iris 仍按 DSH 原生插件装载。0.2.3 服务端注册 16 个 Agent 工具（含改图与音乐），并使用宿主提供的路由、附件、模型和生命周期能力；Web 客户端接入设置页、会话输入区与全局悬浮层。插件不会启动额外服务或监听端口。
 
 | Iris 范围 | DSH 范围 | 验证记录 |
 |---|---|---|
@@ -182,6 +183,7 @@ dsh-iris 仍按 DSH 原生插件装载。0.2.2 服务端注册 15 个 Agent 工
 | 已发布稳定版 `0.1.4` | `0.1.5-rc.1` | 历史 Android/Linux 日常 profile 验收 |
 | `0.2.0` | 仅 `0.2.0-rc.2` | 真实安装服务隔离验收、Core diff 与 SlotRegistry；已有用户实机演示反馈，逐项浏览器操作与异步重启/回退继续验收 |
 | `0.2.2` | 仅 `0.2.0-rc.2` | 真实安装服务隔离检查覆盖 15 个工具与 31 项边界；完整浏览器/移动端及真实异步重启验收仍待完成 |
+| `0.2.3` | 仅 `0.2.0-rc.2` | 增加音乐工具和第三项 Skill；升级后用宿主诊断检查实际装载 |
 
 rc.2 修正与验证范围见[适配说明](docs/DSH_RC2_ADAPTATION.md)；已发布 npm 0.1.4 包不包含这项后续适配。
 
@@ -198,6 +200,7 @@ Core 与 DSH Adapter 正在分离，DSH 继续加载同一个 npm 包，Adapter
 | `iris_draw_image` | 根据提示词生成图片 |
 | `iris_edit_image` | 按原图 Artifact ID 和修改指令创建关联来源的新图片（聊天生图模型） |
 | `iris_generate_video` | 生成文生视频、图生视频或 S2V 数字人视频 |
+| `iris_generate_music` | 根据描述生成音乐，保存为可试听、下载的音频作品 |
 | `iris_speak_text` | 将文本合成为语音 |
 | `iris_transcribe_audio` | 将音频转写为文本 |
 | `iris_task_status` | 查询单个任务或最近任务的状态和产物 |
@@ -251,7 +254,7 @@ Iris 按功能组织有序模型候选池，能力分配使用 `providerId::mode
 
 0.2.2 只采用明确功能标签、旧能力字段绑定或供应商能力元数据，裸账号和名称不再自动赋能。发现保留未标注模型，可在工作台“设置功能”或 CLI `models caps` 中明确用途；已有明确标签优先，分配顺序和安全切换保持。旧 0.2.1 的裸账号与模型名称推断不再用于功能赋能。
 
-生成类能力可以配置多个候选模型。每次请求都从有序列表首项开始，并非 round-robin；Iris 只有在供应商明确证明未受理时才会尝试下一个候选；500、超时、断网、响应缺失、轮询失败和本地落盘失败都不会授权自动重提。远端服务一旦受理任务，Iris 只会恢复观察或交付，以免产生重复任务或重复计费。
+生成类能力可以配置多个候选模型。每次请求都从有序列表首项开始，并非 round-robin；Iris 只有在供应商明确证明未受理时才会尝试下一个候选；500、超时、断网、响应缺失、轮询失败和本地落盘失败都不会授权自动重提。远端服务一旦受理任务，Iris 只会恢复观察或交付，以免产生重复任务或重复计费。音乐入口另外支持按本次参数执行有限的 502 重试，每次重发建立新任务，可能消耗额外额度；可设置 `retry_502: 0` 关闭，见 [Music](docs/MUSIC.md)。
 
 工作台把观察暂停、受理/结果未知和生成成功但交付失败单列为“需要处理”。“重新观察”不会提交；“重新交付”不会重新生成；“标为已读/恢复提醒”只改变本地提醒队列；只有“知情重试”会创建新任务，并要求用户逐次确认潜在重复费用。新任务创建后，原提醒自动归档但保留未知事实和新旧任务关联。任务语义、架构、安全边界与故障证据分别见 [`TASK_SEMANTICS.md`](docs/TASK_SEMANTICS.md)、[`ARCHITECTURE.md`](docs/ARCHITECTURE.md)、[`SECURITY.md`](docs/SECURITY.md) 和 [`FAULT_INJECTION.md`](docs/FAULT_INJECTION.md)。
 
@@ -276,11 +279,11 @@ npx @mokuyoaxis/dsh-iris doctor --json
 
 安装后的二进制名是 `dsh-iris`。退出码 `0` 表示正常、`1` 表示有警告、`2` 表示有硬错误。离线 Doctor 检查 Node、sharp、ffmpeg/ffprobe、数据目录真实写入、配置、模型/分配、任务语义、临时文件和孤儿/缺失产物。
 
-运行中的 DSH 另在 Iris 工作台提供“宿主诊断”卡片，并公开已认证的 `/iris/api/doctor` JSON：检查 DSH 版本、插件、当前工具、两项 Skill、四组路由、Browser/附件/模型能力、客户端版本和四个 UI Slot。它只读取安全快照与注册证据，不调用 Browser、模型或 Provider；详见 [Host Doctor](docs/HOST_DOCTOR.md)。
+运行中的 DSH 另在 Iris 工作台提供“宿主诊断”卡片，并公开已认证的 `/iris/api/doctor` JSON：检查 DSH 版本、插件、当前工具与随包 Skill、四组路由、Browser/附件/模型能力、客户端版本和四个 UI Slot。0.2.3 检查 16 个工具和三项 Skill。它只读取安全快照与注册证据，不调用 Browser、模型或 Provider；详见 [Host Doctor](docs/HOST_DOCTOR.md)。
 
 ## 组合工作流示例
 
-Iris 自带两个 Agent Skills（`iris-verify-ui` 与 `iris-compose-media`），把多个工具编排成有界、可复核的媒体工作流。下例是「看图 → 重绘 → 自检」：先理解原图，再生成，复核针对具体偏差，只有复核通过才交付。
+三项 Agent Skills 分别指导单步媒体操作、多步骤创作与界面验收。下图是既有「看图 → 重绘 → 自检」示例；检查按用户目标加入，已有作品和部分结果保留，音乐作为可选素材步骤。
 
 ![组合工作流示例](docs/assets/diagrams/iris-workflow-compose.png)
 
@@ -329,24 +332,27 @@ Iris 自带两个 Agent Skills（`iris-verify-ui` 与 `iris-compose-media`），
 
 ## Agent Skills
 
-插件启用时会通过 DSH Skill registry 自动注册两个随包 Skill：
+插件通过 DSH Skill registry 注册三项随包 Skill：
 
 | Skill | 适用场景 |
 |---|---|
-| [`iris-verify-ui`](.dsh/skills/iris-verify-ui/SKILL.md) | 组合截图、语义检查、元素定位、裁剪和像素比较，完成有证据的 UI 验收 |
-| [`iris-compose-media`](.dsh/skills/iris-compose-media/SKILL.md) | 组合两个以上 Iris 工具，完成看图后绘图、图片转视频、视频总结配旁白或 S2V 等媒体工作流 |
+| [`iris-use`](.dsh/skills/iris-use/SKILL.md) | 单步生成、改图、看图/OCR、语音、音乐、查询与作品交付 |
+| [`iris-compose-media`](.dsh/skills/iris-compose-media/SKILL.md) | 图片版本、视频素材、旁白、S2V和可选配乐等多步骤创作 |
+| [`iris-verify-ui`](.dsh/skills/iris-verify-ui/SKILL.md) | 界面还原与截图验收，区分通过、部分通过、失败和证据不足 |
 
-从 0.1.2 起，只要宿主提供 DSH Skill registry，普通 npm 安装用户在任意项目目录中都能发现并加载它们，不需要克隆本仓库或另外配置 Skill 搜索目录。项目目录中存在同名 Skill 时，仍按 DSH 原生优先级使用项目版本；Skill registry 不可用时，Iris 工具仍可独立装载。
+Skill 不依赖会话工作目录，项目中的同名 Skill 仍优先；宿主未提供 registry 时，工具仍可独立使用。三项共享[能力与产物说明](.dsh/skills/iris-use/references/media-contract.md)，区分Core ID、附件、播放链接和文件输入；TTS用于后续文件处理时先导出。
 
 用户想稳定指定方法时，可直接用 DSH 的 `/name` 形式：
 
 ```text
+/iris-use 生成一首摇滚配乐，返回音频作品和播放链接
+
 /iris-compose-media 分析我上传的产品照，生成同构图海报，再检查是否符合要求
 
 /iris-verify-ui 对比当前截图和参考图，定位偏差并给出有证据的结论
 ```
 
-也可以继续用自然语言让 Agent 自动发现。单步绘图、OCR、转写等无需强行唤起组合 Skill，直接说需求或指定对应 Iris 工具即可。Skill 只规划工具链，不会绕过 Iris 的任务、费用确认和安全边界。
+也可以自然语言请求或直接指定工具。单步操作由iris-use指导，多步骤由编排Skill指导；音乐仅在用户要求时加入。Skill不能替代工具装载或模型分配，也不改变任务、费用确认和安全边界。
 
 ## 开发与验证
 

package/bin/dsh-iris.js

@@ -5,11 +5,12 @@ import { createCommandService } from '../lib/command-service.js';
 import { createCoreRuntime } from '../lib/core-runtime.js';
 import { recoverCoreWriterLease } from '../lib/core-lease-recovery.js';
 import { doctor, formatDoctorReport } from '../lib/doctor.js';
-import { loadProviderCatalog, providerCatalogSnapshot, catalogCapabilitySnapshot, imageCandidatesFromCatalog, providerForTaskFromCatalog, providerTaskBinding, transcribeCandidatesFromCatalog, ttsCandidatesFromCatalog, videoCandidatesFromCatalog } from '../lib/provider-catalog.js';
+import { loadProviderCatalog, providerCatalogSnapshot, catalogCapabilitySnapshot, imageCandidatesFromCatalog, musicCandidatesFromCatalog, providerForTaskFromCatalog, providerTaskBinding, transcribeCandidatesFromCatalog, ttsCandidatesFromCatalog, videoCandidatesFromCatalog } from '../lib/provider-catalog.js';
 import { createConfiguredProviderAdapter } from '../lib/provider-adapters.js';
 import { providerForImageModel } from '../lib/provider-protocol.js';
 import { prepareProviderInput } from '../lib/provider-adapter.js';
 import { createProviderTaskRunner } from '../lib/provider-task-runner.js';
+import { generateMusicTask } from '../lib/music-generation.js';
 import { GenerationInputError, normalizeGenerationInput } from '../lib/generation-input.js';
 import { executeVisionCommand, normalizeVisionInput } from '../lib/headless-vision.js';
 import { videoTaskCandidates } from '../lib/video-input.js';
@@ -47,7 +48,7 @@ function usage() {
     '  dsh-iris providers <add|set> --provider-config <absolute-path> --input <provider-json>',
     '  dsh-iris providers remove <provider-id> --provider-config <absolute-path>',
     '  dsh-iris models list --provider-config <absolute-path>',
-    '  dsh-iris models <add|remove|caps|protocol|vision-input> <providerId::modelId> --provider-config <absolute-path> [--input <json>]',
+    '  dsh-iris models <add|remove|caps|protocol|music-protocol|vision-input> <providerId::modelId> --provider-config <absolute-path> [--input <json>]',
     '  dsh-iris models discover <provider-id> --provider-config <absolute-path> [--apply <true|false>]',
     '  dsh-iris models test <providerId::modelId> --capability <vision|tts|image-gen|video-gen|transcribe> --provider-config <absolute-path> [--data-root <absolute-path>]',
     '  dsh-iris assignments <list|set|clear> --provider-config <absolute-path> [--input <json>]',
@@ -60,6 +61,7 @@ function usage() {
     '  dsh-iris run image --data-root <absolute-path> --provider-config <absolute-path> --input <json>',
     '  dsh-iris run video --data-root <absolute-path> --provider-config <absolute-path> --input <json>',
     '  dsh-iris run tts --data-root <absolute-path> --provider-config <absolute-path> --input <json>',
+    '  dsh-iris run music --data-root <absolute-path> --provider-config <absolute-path> --input <json>',
     '  dsh-iris run transcribe --data-root <absolute-path> --provider-config <absolute-path> --input <json>',
     '  dsh-iris task inspect <id> --data-root <absolute-path>',
     '  dsh-iris task list --data-root <absolute-path>',
@@ -67,7 +69,7 @@ function usage() {
     '  dsh-iris <task|artifact> inspect-many --data-root <absolute-path> --input <json>',
     '  dsh-iris task observe <id> --data-root <absolute-path> --provider-config <absolute-path>',
     '  dsh-iris task wait <id> --data-root <absolute-path> [--provider-config <absolute-path>] [--timeout-ms <1..1200000>] [--poll-interval-ms <50..60000>]',
-    '  dsh-iris task redeliver <id> --data-root <absolute-path> --provider-config <absolute-path>',
+    '  dsh-iris task redeliver <id> --data-root <absolute-path> [--provider-config <absolute-path>]',
     '  dsh-iris task cancel <id> --data-root <absolute-path> --provider-config <absolute-path>',
     '  dsh-iris task retry <id> --data-root <absolute-path> --provider-config <absolute-path> --input <json> --confirm-billing [--model-ref <providerId::modelId>]',
     '  dsh-iris artifact inspect <id> --data-root <absolute-path>',
@@ -231,7 +233,7 @@ async function main(args) {
 
   if (['config', 'providers', 'models', 'assignments'].includes(args[0])) {
     const [group, verb] = args;
-    const verbs = { config: ['init', 'show', 'check'], providers: ['add', 'set', 'remove'], models: ['list', 'add', 'remove', 'caps', 'protocol', 'vision-input', 'discover', 'test'], assignments: ['list', 'set', 'clear'] };
+    const verbs = { config: ['init', 'show', 'check'], providers: ['add', 'set', 'remove'], models: ['list', 'add', 'remove', 'caps', 'protocol', 'music-protocol', 'vision-input', 'discover', 'test'], assignments: ['list', 'set', 'clear'] };
     if (!verbs[group].includes(verb)) throw new CliUsageError('未知配置命令');
     const positional = (group === 'providers' && verb === 'remove') || (group === 'models' && verb !== 'list');
     const id = positional ? required(args[2], group === 'providers' || verb === 'discover' ? 'provider-id' : 'model-ref') : undefined;
@@ -250,6 +252,7 @@ async function main(args) {
     const result = await executeConfigCommand(required(options['provider-config'], 'provider-config'), group === 'config' ? verb : group + '.' + verb, input, {
       signal: cliAbortController.signal,
       probe: async ({ provider, modelId, capability, signal }) => {
+        if (capability === 'music-gen') return { skipped: true, ok: false, reason: 'Music 不发起小样本探测；请使用 run music 提交创作要求' };
         if (capability === 'vision') return probeVisionModel(provider, modelId, { bytes: Buffer.from(RED_TEST_IMAGE.split(',')[1], 'base64'), mediaType: 'image/png' }, { signal });
         if (['video-gen', 'transcribe'].includes(capability) && !options.input) return {
           skipped: true, ok: false, reason: '请用 models test --input 提供与 run video/transcribe 相同的真实素材；未发起请求'
@@ -398,6 +401,22 @@ async function main(args) {
   }
 
   // 语音合成输入冻结（E2 Profile）：同步完成型，一次命令内完成 Task → Artifact。
+  if (args[0] === 'run' && args[1] === 'music') {
+    const options = flags(args.slice(2), ['data-root', 'provider-config', 'input']);
+    const normalized = generationInput('music', jsonInput(options.input));
+    const catalog = loadProviderCatalog(required(options['provider-config'], 'provider-config'));
+    const routes = musicCandidatesFromCatalog(catalog, normalized.modelRef);
+    let result;
+    await withRawRuntime('writer', options['data-root'], async runtime => {
+      result = await generateMusicTask({ runner: createProviderTaskRunner(runtime),
+        candidates: routes.map(route => ({ adapter: trackedProviderAdapter(route.provider, options), model: route.modelRef,
+          selectionReason: route.selectionReason, providerBinding: providerTaskBinding(route.provider) })),
+        providerInput: normalized.providerInput, options: normalized.musicOptions, signal: cliAbortController.signal });
+      console.log(JSON.stringify(result, null, 2));
+    });
+    return result.task.outcome === 'succeeded' && result.task.deliveryState === 'ready' ? 0 : 1;
+  }
+
   if (args[0] === 'run' && args[1] === 'tts') {
     const options = flags(args.slice(2), ['data-root', 'provider-config', 'input']);
     const { providerInput, modelRef } = generationInput('tts', jsonInput(options.input));
@@ -473,10 +492,10 @@ async function main(args) {
 
   if (args[0] === 'task' && args[1] === 'redeliver' && args[2]) {
     const options = flags(args.slice(3), ['data-root', 'provider-config']);
-    const catalog = loadProviderCatalog(required(options['provider-config'], 'provider-config'));
+    const catalog = options['provider-config'] ? loadProviderCatalog(options['provider-config']) : null;
     await withRuntime('reader', options['data-root'], (commands) => commands.execute('task.inspect', { task_id: args[2] }));
     const result = await withRuntime('writer', options['data-root'], (commands) => commands.execute('task.redeliver', { task_id: args[2] }), {
-      resolveTaskAdapter: (task) => trackedProviderAdapter(providerForTaskFromCatalog(catalog, task), options, task)
+      ...(catalog ? { resolveTaskAdapter: (task) => trackedProviderAdapter(providerForTaskFromCatalog(catalog, task), options, task) } : {})
     });
     console.log(JSON.stringify(result, null, 2));
     return 0;
@@ -512,6 +531,8 @@ async function main(args) {
         ? videoCandidatesFromCatalog(catalog, modelRef || undefined)
         : capability === 'tts'
           ? ttsCandidatesFromCatalog(catalog, modelRef || undefined)
+          : capability === 'music'
+            ? musicCandidatesFromCatalog(catalog, modelRef || undefined)
           : capability === 'transcribe'
             ? transcribeCandidatesFromCatalog(catalog, modelRef || undefined)
             : imageCandidatesFromCatalog(catalog, modelRef || undefined)

package/docs/AGENT_QUICKSTART.md

@@ -2,22 +2,22 @@
 
 把下面一段交给负责安装或使用 Iris 的 Agent。版本与发布状态以当前 [README](../README.md) 为准；Iris 和 DSH 的版本号独立。
 
-当前安装版本为 Iris 0.2.2。先核对宿主与实际安装版本，再使用新视觉命令或 Artifact 改图；旧宿主仍固定安装 0.1.4。
+本文对应 Iris 0.2.3。使用时先核对实际版本、可用工具和功能分配；旧宿主仍固定安装 0.1.4。
 
 ## 中文
 
 ```text
 请根据本仓库 README，帮我安装并使用 Iris（@mokuyoaxis/dsh-iris）。
 先确认运行环境、目标 DSH profile，并用 dsh --version 核对宿主；Iris 0.2.x 要求 Node.js >=22.0.0（旧 npm 0.1.4 的历史要求为 >=20.10.0）：
-- DSH 0.2.0-rc.2：固定安装 dsh plugin --profile web add @mokuyoaxis/dsh-iris@0.2.2。
+- DSH 0.2.0-rc.2：固定安装 dsh plugin --profile web add @mokuyoaxis/dsh-iris@0.2.3。
 - DSH >=0.1.2-rc.1 <0.1.3-0 或 0.1.5-rc.1：固定安装 dsh plugin --profile web add @mokuyoaxis/dsh-iris@0.1.4；只下载用 npm pack @mokuyoaxis/dsh-iris@0.1.4。
 - 其他 DSH 版本：先报告没有支持声明，不自行升级宿主或跳过版本检查。
-没有 DSH、希望用 CLI 时，按 docs/HEADLESS_CLI.md 使用 npm 0.2.2；npm 0.1.4 不含新的 Core 媒体 CLI。
-先用 --help 和 Doctor 核对实际版本与命令。Iris 0.2.2 支持 OpenAI 兼容图片与视觉工作流；其他协议与 music 是后续计划。
+没有 DSH、希望用 CLI 时，按 docs/HEADLESS_CLI.md 使用 npm 0.2.3；npm 0.1.4 不含新的 Core 媒体 CLI。
+先用 --help 和 Doctor 核对实际版本与命令。Iris 0.2.3 支持图片、视频、语音、视觉与音乐入口。音乐需明确分配模型并选择 Chat Completions（内嵌音频）协议，详见 docs/MUSIC.md；使用 iris_generate_music。
 从 dsh-market 安装也要核对实际包名、版本和兼容范围；市场缓存不代表支持旧宿主，不对旧 DSH 安装 latest。
 若使用其他 profile，把示例中的 web 换成已确认的目标。保留完整 scoped 包名，不把 dsh-iris 当作同一 npm 包。
 安装后检查 Doctor 和工具可达性，再执行我指定的媒体任务；不要输出 API Key，重启宿主前说明影响。
-查询、观察和重新取回不等于重新生成；任务已受理或受理未知时，不自动重新提交。
+查询、观察和重新取回不等于重新生成；任务已受理或受理未知时，不自行重新提交。音乐入口内部执行本次配置的有限502重试，不再由Agent包外层循环；配乐仅按用户要求加入流程。
 最后报告所用 Iris/DSH 版本、安装来源和实际验证结果。
 ```
 
@@ -26,14 +26,14 @@
 ```text
 Help me install and use Iris (@mokuyoaxis/dsh-iris) according to this repository's README.
 Check the environment, target DSH profile, and dsh --version first; Iris 0.2.x requires Node.js >=22.0.0 (the published npm 0.1.4 historically requires >=20.10.0):
-- DSH 0.2.0-rc.2: pin dsh plugin --profile web add @mokuyoaxis/dsh-iris@0.2.2.
+- DSH 0.2.0-rc.2: pin dsh plugin --profile web add @mokuyoaxis/dsh-iris@0.2.3.
 - DSH >=0.1.2-rc.1 <0.1.3-0 or 0.1.5-rc.1: pin dsh plugin --profile web add @mokuyoaxis/dsh-iris@0.1.4; download only with npm pack @mokuyoaxis/dsh-iris@0.1.4.
 - Other DSH versions: report the missing support claim; do not upgrade the host or bypass its version checks automatically.
-For CLI use without DSH, follow docs/HEADLESS_CLI.md using npm 0.2.2; npm 0.1.4 does not include the new Core media CLI.
-Check --help, Doctor and the actual installed version before using commands. Iris 0.2.2 supports the OpenAI-compatible image and vision workflow; additional protocols and music remain future work.
+For CLI use without DSH, follow docs/HEADLESS_CLI.md using npm 0.2.3; npm 0.1.4 does not include the new Core media CLI.
+Check --help, Doctor and the actual installed version before using commands. Iris 0.2.3 offers image, video, speech, vision, and music operations. Music requires explicit model assignment and the Chat Completions inline-audio protocol described in docs/MUSIC.md; use iris_generate_music for music generation.
 For dsh-market, check the actual package name, version, and compatibility range too. Cached listings do not establish older-host support; do not install latest on an old DSH host.
 Replace web with the confirmed profile when needed. Keep the scoped package name; unscoped dsh-iris is a different npm package.
 Check Doctor and tool availability after installation, then carry out my requested media task. Do not expose API keys; explain the impact before restarting the host.
-Inspect, observe, and redeliver do not create a new generation. Never resubmit automatically after accepted or unknown acceptance.
+Inspect, observe, and redeliver do not generate again. Do not add an agent retry loop after accepted or unknown acceptance; music handles its configured bounded 502 retries internally. Add music to workflows only when requested.
 Report the Iris/DSH versions, installation source, and actual validation results.
 ```

package/docs/ARCHITECTURE.md

@@ -64,7 +64,7 @@ DSH Host / Cordis                         Headless CLI
 ## Task、Attempt 与 Artifact
 
 - 一个用户意图对应一个 Core Task；每次候选供应商调用对应一个稳定 Attempt。Attempt 必须在可能发送计费请求前落盘。
-- 只有明确 `not_accepted` 才允许自动切换候选；`accepted` 或 `unknown` 后禁止自动重提。重试会创建新 Task，并要求用户再次提供未持久化的输入和明确确认潜在费用。
+- Core只有明确 `not_accepted` 才自动切换候选；`accepted` 或 `unknown` 后通用Runner停止重提。人工重试会创建新Task，要求重新提供输入并确认潜在费用。Music功能层另按本次配置对明确HTTP502进行有限重发，保留原Task的未知事实和新旧任务关系，详见 [音乐生成](MUSIC.md)。
 - 生成结果与本地交付是两类事实。远端成功后下载失败仍保持 `outcome=succeeded / deliveryState=failed`，可显式重新交付而不重新生成。
 - 新 Attempt 可选保存阶段时间戳与模型选择来源；旧记录缺少这些字段仍可读取。
 - Artifact Manifest v0 保存内容哈希、媒体类型、中性元数据和关系边；不保存 Prompt、API Key、签名 URL、Provider 端点或宿主绝对路径。