@mokuyoaxis/dsh-iris 0.2.1 → 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,25 +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.1 provides a DSH plugin and a headless CLI sharing tasks, artifacts and model routing, completing 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.1
+## What's new in 0.2.3
 
-**Complete the OpenAI-compatible image and vision workflow:** image generation → Core Artifact → vision/OCR by ID → chat editing → new Artifact, shared by the CLI and DSH workbench.
+**Music creation, agent guidance, and media delivery recovery.**
 
-- **Models and protocols:** discover models and classify capabilities, then choose image protocols per model; models within one account can use Images, chat or Responses interfaces.
-- **Image delivery:** preserve PNG/JPEG/WebP bytes and handle large base64 image responses.
-- **Artifact editing:** edit from a Core image card, `iris_edit_image`, or the CLI; save a linked new image while preserving the source.
-- **Standalone vision:** look, locate, OCR and video summaries with explicit model selection and direct image/frame Artifact inputs.
-- **Input budgets:** configure account/model sending limits, preserve originals, report OCR resizing and map locate coordinates to source pixels.
-- **Library and CLI management:** pagination, filters, selection across pages, ZIP downloads and recoverable Core deletion; S2V, HTML screenshots, configuration and bounded waiting.
-- **Model recovery:** amber for temporary 429 cooldown; red for confirmed quota or budget exhaustion until a manual test succeeds.
+- **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.1 release notes](docs/releases/0.2.1.md) and [CHANGELOG](CHANGELOG.md) for scope and pending checks.
+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
 
@@ -71,18 +71,18 @@ Future work includes additional protocol adapters and **music generation**; see
 | Who it's for | DeepSeek Harness users who want agent tools, the workbench, and in-chat prompt optimization | Users who want media generation, task tracking, and artifact export from the command line without DSH |
 | Entry point | Choose a pinned release under "Quickest start" below | `dsh-iris run ...` — see [Headless CLI](docs/HEADLESS_CLI.md) |
 | Data location | `$DSH_HOME/iris/v1/` (Core data root `core-v0`) | Any absolute path passed via `--data-root` |
-| Automatic observation | Yes (bounded DSH host ticks + restart takeover) | Explicit `task observe`; 0.2.1 also offers bounded `task wait` |
+| Automatic observation | Yes (bounded DSH host ticks + restart takeover) | Explicit `task observe`; 0.2.2 also offers bounded `task wait` |
 | Dependencies | DSH `0.2.0-rc.2` and Node.js ≥ 22 | Node.js ≥ 22 and `sharp` only (`ffmpeg` for video frames) |
 
 Both paths read and write the same Core Task/Artifact facts: point the CLI at the `core-v0` data root of a DSH profile to inspect/export DSH-generated artifacts, and vice versa. Only one writer is allowed per data root.
 
 > 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
 
@@ -90,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.1` | 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 |
 
@@ -111,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.1
+### 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.1
+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.1
+### Standalone CLI: install 0.2.3
 
 Install in your own project without DSH:
 
 ```bash
-npm install @mokuyoaxis/dsh-iris@0.2.1
+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.1 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.
 
@@ -156,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
@@ -167,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.1 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
@@ -176,14 +176,15 @@ 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.1 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 |
 |---|---|---|
 | Published stable `0.1.4` | `>=0.1.2-rc.1 <0.1.3-0` | Historical clean and daily Web profiles on Linux ARM64 |
 | 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.1` | 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.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.
 
@@ -200,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 |
@@ -241,17 +243,19 @@ Uploads are stored under `$DSH_HOME/iris/v1/uploads/` and kept for 7 days by def
 
 ## Conversation prompt optimization
 
-The 0.2.1 adds per-operation rules, assembly without a model call and editable comparisons. Rules are not persisted and no standalone prompt CLI is added. See the [prompt optimizer guide](docs/PROMPT_OPTIMIZER.md).
+Version 0.2.2 extends per-operation rules, assembly without a model call and editable comparisons. It groups general, image creation, image editing, video and S2V targets in a collapsible section. The interface defaults to faithful grouping of original text in its original order; rewriting requires an explicit choice, and optional suggestions are fetched and adopted separately. Default instructions follow the project's Skills; custom v1 configuration and the existing text API remain compatible. Rules are not persisted and no standalone prompt CLI is added. See the [prompt optimizer guide](docs/PROMPT_OPTIMIZER.md).
 
-Iris adds a borderless, text-free “🫧” control directly to the DSH composer, so the workbench does not need to be open. It opens a translucent glass panel with background blur and soft depth; on narrow screens and Android browsers it becomes a safe-area-aware, internally scrollable bottom sheet to prevent overlap and overflow. It reads only the current unsent plain-text draft and offers general, image, video, and start-to-end-frame video targets. The result is previewed first and is written back only after confirmation; Iris never sends it automatically. Drafts containing structured `@` or `/` references are left untouched for now so their identities are not lost.
+Iris adds a borderless, text-free “🫧” control directly to the DSH composer, so the workbench does not need to be open. It opens a translucent glass panel with background blur and soft depth; on narrow screens and Android browsers it becomes a safe-area-aware, internally scrollable bottom sheet. It reads only the current unsent plain-text draft. The result is previewed first and is written back only after confirmation; Iris never sends it automatically. Drafts containing structured `@` or `/` references are left untouched for now so their identities are not lost.
 
 By default, the optimizer uses the model selected for the current session and falls back to DSH's default model when the session has none. The request carries no chat history, tools, attachments, or workspace content—only the current draft and target template. To prevent reasoning tokens from exhausting the generation budget before visible text is complete, `generation.reasoningEffort` defaults to `off-if-supported`: reasoning is disabled only when DSH model metadata explicitly advertises such an effort; otherwise the provider default is used, and the session High/Low setting is not inherited. JSON may select `provider-default`, `inherit`, or an exact effort ID advertised by the model. For predictable cost and latency, use a `fixed` route with a lightweight non-reasoning model. You can also export `prompt-optimizer.json`, change `route.mode` to `fixed`, name another `provider` and `model` already registered in DSH, and import it again. “Reset to defaults” restores Iris's built-in prompt, target templates, session-model routing, and generation settings. The composer control can be disabled independently and re-enabled from the Iris workbench; disabling it does not stop the workbench, agent tools, or task runtime. An optimization call may incur charges from the selected text model.
 
 ## Model assignment and failover
 
-Capability assignment uses `providerId::modelId` as the model identity. The same model name from a different provider or account counts as two independent options. Discovery prefers provider capability metadata, falls back to name rules, and preserves explicit user overrides. Alibaba Cloud media calls may use a separate Workspace `mediaBaseUrl`.
+Iris organizes ordered model candidates by function. Capability assignments identify each executor with `providerId::modelId`; the same model name from a different provider or account is a separate option. Alibaba Cloud media calls may use a separate Workspace `mediaBaseUrl`.
+
+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).
 
@@ -261,7 +265,7 @@ Transcription is a separate `transcribe` capability and does not consume the TTS
 
 ## Capability health and model verification
 
-The workbench and main bubble show gray for unconfigured, blue for unverified, green for success within seven days, and muted red for authentication or permission failures. The 0.2.1 also shows amber for temporary 429 cooldown and bright red for confirmed free quota or budget exhaustion, with a reason and recovery condition.
+The workbench and main bubble show gray for unconfigured, blue for unverified, green for success within seven days, and muted red for authentication or permission failures. The 0.2.2 also shows amber for temporary 429 cooldown and bright red for confirmed free quota or budget exhaustion, with a reason and recovery condition.
 
 Iris performs no background probes. Temporary 429 responses use `Retry-After`, or a 60-second default cooldown. Expiry restores candidate eligibility without a verification request. Confirmed free quota or budget exhaustion persists across restarts until an explicit model test succeeds; test buttons remain available. Vision, image, and TTS have built-in test samples; video and transcription tests require real input through the CLI. Network errors, 5xx responses, content-safety failures, cancellation, and unknown acceptance do not overwrite recent success evidence. Host Doctor only checks loading and host ports. See [Provider and capability health](docs/PROVIDER_HEALTH.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,25 +44,23 @@ dsh-iris 为 Agent、Iris 工作台和独立 CLI 提供图像、视频、语音
 
 项目目前处于早期版本，接口和配置格式仍可能随版本迭代调整。
 
-Iris 0.2.1 同时提供 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.1 更新重点
+## 0.2.3 更新重点
 
-**完成 OpenAI 兼容图片与视觉工作流**：生成图片 → Core Artifact → 按 ID 看图/OCR → 聊天改图 → 新 Artifact，CLI 与 DSH 工作台共用同一链路。
+**音乐创作、Agent 使用引导与媒体交付恢复**。
 
-- **模型与协议**：发现模型并分类能力，按模型选择图片协议；同账号的不同模型可使用 Images、聊天或 Responses 接口。
-- **图片交付**：PNG/JPEG/WebP 按真实字节交付，修复大图 base64 校验。
-- **Artifact 改图**：从 Core 图片卡、`iris_edit_image` 或 CLI 发起聊天编辑，新作品关联原图，原图保留。
-- **独立视觉 CLI**：看图、定位、OCR 和视频摘要支持显式模型选择；图片与帧可直接按 Artifact ID 读取。
-- **视觉输入预算**：账号/模型可设置发送大小与最长边，只处理发送副本；OCR 提示细字风险，定位坐标映射回原图。
-- **作品与 CLI 管理**：统一分页过滤、跨页选择、ZIP 下载、Core 回收与恢复；CLI 补齐 S2V、HTML 截图、配置和有界等待。
-- **模型恢复规则**：短时 429 显示琥珀冷却，明确额度或预算耗尽显示红色停用，需手动实测成功恢复。
+- **音乐生成**：独立分配音乐模型，通过 Agent、工作台或 CLI 生成 MP3/WAV，可试听、下载和导出；支持配置有限的 502 重试。
+- **三项 Agent Skills**：分别指导单步媒体操作、多步骤创作与界面验收；配乐按需加入。
+- **交付恢复**：完整同步结果已缓存时，可沿原任务重新交付，无需重新生成。
+- **提示词编辑**：失败和取消保留已有预览，单片段忠实整理无需模型调用，配置恢复可只重置默认指令。
+- **路由与格式说明**：显示文本模型选择原因，检查改写正文格式，保留自定义 v1 配置。
 
-完整变化和发布前待验项见 [0.2.1 发布说明](docs/releases/0.2.1.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#后续功能方向)。
 
 ## 两条使用路径
 
@@ -71,18 +69,18 @@ Iris 0.2.1 同时提供 DSH 插件与无 DSH 的 CLI，共用任务、产物和
 | 适合谁 | 已在使用 DeepSeek Harness，想要 Agent 工具、工作台和对话内提示词优化 | 想在无 DSH 环境用命令行完成媒体生成、任务跟踪和作品导出 |
 | 入口 | 按下文「最快开始」选择固定版本 | `dsh-iris run ...`，见 [Headless CLI](docs/HEADLESS_CLI.md) |
 | 数据位置 | `$DSH_HOME/iris/v1/`（Core 数据根 `core-v0`） | 显式 `--data-root` 指定的任意绝对路径 |
-| 自动观察 | 有（DSH Host 有界节拍 + 重启接管） | 显式 `task observe`；0.2.1 另提供有界 `task wait` |
+| 自动观察 | 有（DSH Host 有界节拍 + 重启接管） | 显式 `task observe`；0.2.2 另提供有界 `task wait` |
 | 依赖 | DSH `0.2.0-rc.2`、Node.js ≥ 22 | 仅 Node.js ≥ 22 与 `sharp`（视频抽帧另需 `ffmpeg`） |
 
 两条路径读写同一份 Core Task/Artifact 事实：CLI 指向 DSH profile 的 `core-v0` 数据根即可 inspect/export DSH 生成的作品，反之亦然。同一数据根只允许一个写者。
 
 > 安装体积提示：图像处理依赖 `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#从旧工作台显式导入)。
 
 ## 最快开始
 
@@ -90,7 +88,7 @@ Iris 0.2.1 同时提供 DSH 插件与无 DSH 的 CLI，共用任务、产物和
 
 | 你的 DSH | Iris 选择 | 安装来源 |
 |---|---|---|
-| `0.2.0-rc.2` | `0.2.1` | 固定 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 版本 |
 | 其他版本 | 暂无当前支持声明 | 先核对宿主适配，不能按相邻版本推定兼容 |
 
@@ -111,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.1
+### DSH 0.2.0-rc.2：安装 0.2.3
 
 安装固定版本到 Web profile：
 
 ```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
 ```
 
 插件在下一次 DSH 启动时装载。Web UI 默认位于 `http://127.0.0.1:3080`；启动输出带认证参数时请打开完整 URL。更新后需重新加载后端并刷新客户端。
 
-### 独立 CLI：安装 0.2.1
+### 独立 CLI：安装 0.2.3
 
 在自己的项目中安装，无需 DSH：
 
 ```bash
-npm install @mokuyoaxis/dsh-iris@0.2.1
+npm install @mokuyoaxis/dsh-iris@0.2.3
 npx dsh-iris --help
 ```
 
 ### dsh-market 安装时的版本选择
 
-市场条目应对应完整包名 `@mokuyoaxis/dsh-iris`。安装前同时核对市场显示的 Iris 版本与本机 `dsh --version`：0.2.1 仅用于 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`。
 
@@ -144,6 +142,7 @@ npx dsh-iris --help
 ```text
 使用 iris_draw_image：画一只坐在蓝色窗边的白猫。
 总结我刚上传的这张图片。
+用 Iris 生成一首复古摇滚配乐，保存为音频作品。
 用 Iris 总结 /absolute/path/demo.mp4，再把摘要合成为语音。
 ```
 
@@ -156,7 +155,7 @@ DSH 的 profile 与插件命令由[官方安装说明](https://github.com/deepse
 ![Iris 架构总览](docs/assets/diagrams/iris-architecture.png)
 
 - 图像生成、文生视频、图生视频和 S2V 数字人视频
-- 文本转语音与音频转写
+- 音乐生成、文本转语音与音频转写
 - 看图问答、长图 OCR、目标定位、裁剪和像素差异分析
 - 视频抽帧与多模态内容摘要
 - 异步任务跟踪、重启恢复和带授权令牌的媒体播放
@@ -167,7 +166,7 @@ DSH 的 profile 与插件命令由[官方安装说明](https://github.com/deepse
 
 ## 使用前准备
 
-- 满足所用 DeepSeek Harness 版本要求的 Node.js；Iris 0.2.1 最低为 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 帧摘要无需这两个工具
@@ -176,14 +175,15 @@ DSH 的 profile 与插件命令由[官方安装说明](https://github.com/deepse
 
 ## DeepSeek Harness 适配
 
-dsh-iris 仍按 DSH 原生插件装载。0.2.1 服务端注册 15 个 Agent 工具（含改图），并使用宿主提供的路由、附件、模型和生命周期能力；Web 客户端接入设置页、会话输入区与全局悬浮层。插件不会启动额外服务或监听端口。
+dsh-iris 仍按 DSH 原生插件装载。0.2.3 服务端注册 16 个 Agent 工具（含改图与音乐），并使用宿主提供的路由、附件、模型和生命周期能力；Web 客户端接入设置页、会话输入区与全局悬浮层。插件不会启动额外服务或监听端口。
 
 | Iris 范围 | DSH 范围 | 验证记录 |
 |---|---|---|
 | 已发布稳定版 `0.1.4` | `>=0.1.2-rc.1 <0.1.3-0` | 历史 Linux ARM64 干净与日常 Web profile 验收 |
 | 已发布稳定版 `0.1.4` | `0.1.5-rc.1` | 历史 Android/Linux 日常 profile 验收 |
 | `0.2.0` | 仅 `0.2.0-rc.2` | 真实安装服务隔离验收、Core diff 与 SlotRegistry；已有用户实机演示反馈，逐项浏览器操作与异步重启/回退继续验收 |
-| `0.2.1` | 仅 `0.2.0-rc.2` | 真实安装服务隔离检查覆盖 15 个工具与 31 项边界；完整浏览器/移动端及真实异步重启验收仍待完成 |
+| `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 包不包含这项后续适配。
 
@@ -200,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` | 查询单个任务或最近任务的状态和产物 |
@@ -241,17 +242,19 @@ Iris 支持三种文件来源，推荐顺序如下：
 
 ## 对话框提示词优化
 
-0.2.1 增加本次规则、只组装和可编辑对照预览；规则不持久化，也未新增独立提示词 CLI。功能及边界见 [提示词优化系统](docs/PROMPT_OPTIMIZER.md)。
+0.2.2 在既有按次规则、只组装和可编辑对照预览上增加一般功能。一般功能可折叠，提供通用、画图、改图、视频与数字人用途，默认忠实整理保留原文和句序；改写表达需明确选择，补充建议单独获取和采纳。默认指令贴近项目 Skills，既有自定义 v1 配置与旧 API 文字协议保留。规则不持久化，未新增独立提示词 CLI。功能及边界见 [提示词优化系统](docs/PROMPT_OPTIMIZER.md)。
 
-Iris 会在 DSH 对话输入区提供一个无边框、无文字的“🫧”入口，不需要打开 Iris 工作台。点击后打开带背景模糊、半透明层次和柔和光影的玻璃悬浮窗；桌面端靠近输入区显示，窄屏与 Android 浏览器自动切换为带安全区和内部滚动的底部面板，避免遮挡、溢出或控件挤叠。它只读取当前未发送的纯文本草稿，并提供通用、图片、视频和首尾帧视频四种目标模板；结果先预览，用户确认后才写回输入框，不会自动发送。含 `@` 或 `/` 结构化引用的草稿暂不改写，以免引用身份丢失。
+Iris 会在 DSH 对话输入区提供一个无边框、无文字的“🫧”入口，不需要打开 Iris 工作台。点击后打开带背景模糊、半透明层次和柔和光影的玻璃悬浮窗；桌面端靠近输入区显示，窄屏与 Android 浏览器自动切换为带安全区和内部滚动的底部面板。它只读取当前未发送的纯文本草稿；结果先预览，用户确认后才写回输入框，不会自动发送。含 `@` 或 `/` 结构化引用的草稿暂不改写，以免引用身份丢失。
 
 默认使用当前会话选中的主模型；会话尚未选定模型时回退到 DSH 默认模型。优化请求不携带聊天历史、工具、附件或工作区，只发送当前草稿与目标模板。为避免推理模型在正文前耗尽生成预算，默认 `generation.reasoningEffort` 为 `off-if-supported`：仅在 DSH 模型元数据明确支持关闭 thinking 时禁用推理，否则使用供应商默认值，并且不再继承主会话的 High/Low 档位。可在 JSON 中改为 `provider-default`、`inherit` 或模型声明的具体 effort ID；成本与稳定性优先时，建议使用 `fixed` 路由指定轻量非思考模型。用户也可以导出 `prompt-optimizer.json`，将 `route.mode` 改为 `fixed` 并指定其他已在 DSH 注册的 `provider` 与 `model`，然后从面板重新导入。面板提供“恢复默认”，可还原 Iris 内置 Prompt、目标模板、会话模型路由和生成参数。该对话入口可以单独关闭，并从 Iris 工作台重新启用；关闭不会停用工作台、Agent 工具或任务后台。优化调用可能产生对应文本模型的费用。
 
 ## 模型分配与故障转移
 
-能力分配使用 `providerId::modelId` 作为模型身份。同名模型如果来自不同供应商或不同账号，会被视为两个独立选项。模型发现优先采用供应商返回的能力元数据，名称规则只作兜底，用户手工标注最终生效；阿里云百炼可为媒体请求单独配置 Workspace `mediaBaseUrl`。
+Iris 按功能组织有序模型候选池，能力分配使用 `providerId::modelId` 区分执行器。同名模型来自不同供应商或账号时是独立选项；阿里云百炼可为媒体请求单独配置 Workspace `mediaBaseUrl`。
 
-生成类能力可以配置多个候选模型。每次请求都从有序列表首项开始，并非 round-robin；Iris 只有在供应商明确证明未受理时才会尝试下一个候选；500、超时、断网、响应缺失、轮询失败和本地落盘失败都不会授权自动重提。远端服务一旦受理任务，Iris 只会恢复观察或交付，以免产生重复任务或重复计费。
+0.2.2 只采用明确功能标签、旧能力字段绑定或供应商能力元数据，裸账号和名称不再自动赋能。发现保留未标注模型，可在工作台“设置功能”或 CLI `models caps` 中明确用途；已有明确标签优先，分配顺序和安全切换保持。旧 0.2.1 的裸账号与模型名称推断不再用于功能赋能。
+
+生成类能力可以配置多个候选模型。每次请求都从有序列表首项开始，并非 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)。
 
@@ -261,7 +264,7 @@ Iris 会在 DSH 对话输入区提供一个无边框、无文字的“🫧”入
 
 ## 能力健康与模型验证
 
-工作台与主泡泡用颜色和文字显示健康状态：灰色未配置，蓝色待验证，绿色表示对应“供应商 × 模型 × 能力”7 天内成功，暗红色表示明确认证/权限失败。0.2.1 另以琥珀色显示短时 429 冷却，红色显示已确认额度或预算耗尽，并给出原因和恢复条件。
+工作台与主泡泡用颜色和文字显示健康状态：灰色未配置，蓝色待验证，绿色表示对应“供应商 × 模型 × 能力”7 天内成功，暗红色表示明确认证/权限失败。0.2.2 另以琥珀色显示短时 429 冷却，红色显示已确认额度或预算耗尽，并给出原因和恢复条件。
 
 Iris 不做后台探测。短时 429 遵从 `Retry-After`，缺失时冷却 60 秒；到期恢复候选资格，不自动调用验证。明确免费额度或预算耗尽则停用至手动实测成功，重启后仍跳过；实测按钮保持可用。模型池可逐项实测视觉、图片和 TTS，视频与转写可用 CLI 实测命令提供真实素材。网络、5xx、内容安全、取消和受理未知不覆盖近期成功。Host Doctor 只核验装载与 Host Port。完整规则见 [Provider 与能力健康状态](docs/PROVIDER_HEALTH.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不能替代工具装载或模型分配，也不改变任务、费用确认和安全边界。
 
 ## 开发与验证