@mokuyoaxis/dsh-iris 0.2.2 → 0.2.4

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,24 @@ 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.4 provides a DSH plugin and a headless CLI sharing tasks, artifacts and model routing, with persistent image import, native Qwen editing, and explicit function assignments. Music, three agent skills, and synchronous delivery recovery remain available. Core internals have not been frozen as a public SDK.
+
+> Version support: Iris 0.2.4 supports DSH `0.2.0-rc.2` or `0.2.1-alpha.4`; Iris 0.2.0–0.2.3 supports rc.2 only. Node.js must be at least 22.0.0 and meet any higher host requirement. Older DSH hosts should pin Iris 0.1.4. See the [compatibility matrix](docs/DSH_COMPATIBILITY.md).
 
-> 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.4
 
-## What's new in 0.2.2
+**Image reuse, explicit function assignments, and support for the newer host.**
 
-**Controlled prompt editing and reliable media execution**, building on the existing OpenAI-compatible image and vision workflow.
+- **Persistent image import:** save an existing image through the workbench, agent, or CLI for later vision, editing, and export. The source file stays intact and no model is called.
+- **Native Qwen editing:** use supported DashScope Qwen image editing models as well as chat image models; edited images retain a link to their source.
+- **Explicit assignments:** image, video, TTS, music, transcription, and vision use only their assigned ordered lists. Explicit overrides must also be assigned.
+- **Two host versions:** DSH rc.2 and alpha.4 use the same manifest, client peer, and Doctor compatibility boundary.
 
-- **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.
+**Check assignments before upgrading:** empty lists stop new calls instead of adding models from the pool. Existing tasks retain their original bindings. Add the DSH default model explicitly to vision when needed. See the [upgrade guide](docs/FUNCTION_MODEL_ASSIGNMENTS.md).
 
-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.4 release notes](docs/releases/0.2.4.md) and [CHANGELOG](CHANGELOG.md); music and Skills from the previous release are documented in [0.2.3](docs/releases/0.2.3.md).
 
-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
 
@@ -70,17 +73,17 @@ Future work includes additional protocol adapters and **music generation**; see
 | 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.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) |
+| Dependencies | DSH rc.2 or alpha.4, and Node.js ≥ 22 meeting host requirements | 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
 
@@ -88,7 +91,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` or `0.2.1-alpha.4` | `0.2.4` | 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,33 +112,33 @@ 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 rc.2 or alpha.4: install 0.2.4
 
 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.4
 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.4
 
 Install in your own project without DSH:
 
 ```bash
-npm install @mokuyoaxis/dsh-iris@0.2.2
+npm install @mokuyoaxis/dsh-iris@0.2.4
 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 its Iris version and your local `dsh --version` against the [compatibility matrix](docs/DSH_COMPATIBILITY.md); older hosts should pin `@0.1.4`. Catalog and npm data may be cached. The actual package's top-level `engines.dsh`, Node requirement, and client peers define its 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.
 
-After the first start, open "Settings → Iris workbench → + Add provider", enter your provider base URL and API key, then click "Discover models". A single provider can start with automatic capability assignment. Full steps, image protocol selection, and failover notes are in the [user guide](user_guide.md) (Chinese).
+After the first start, open "Settings → Iris workbench → + Add provider", enter your provider base URL and API key, discover models, label their capabilities, and assign them to each function. Version 0.2.4 uses explicit ordered lists for all functions; see [assignment rules and upgrade impact](docs/FUNCTION_MODEL_ASSIGNMENTS.md) (Chinese). Full steps and protocol selection are in the [user guide](user_guide.md) (Chinese).
 
 Once configured, minimal instructions can be as simple as:
 
@@ -154,7 +157,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 +168,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 +177,9 @@ 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.4 registers 17 agent tools, including import, editing, and music, and uses host routing, attachments, models, 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.
+
+Save an uploaded or local image as a persistent Artifact for viewing, editing and export; see [image import](docs/IMAGE_IMPORT.md) (Chinese).
 
 | Iris version | DSH range | Verification |
 |---|---|---|
@@ -182,8 +187,10 @@ 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 |
+| `0.2.4` | `0.2.0-rc.2` or `0.2.1-alpha.4` | 17 tools / 3 skills; actual SDK, loader, and client slot isolation checks; full browser and hot reload checks remain separate |
 
-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.
+See the [compatibility matrix](docs/DSH_COMPATIBILITY.md) for the current scope and [rc.2 adaptation notes](docs/DSH_RC2_ADAPTATION.md) for historical changes. npm 0.1.4 does not contain these later adaptations.
 
 Iris 0.2.x no longer claims older DSH support; historical validation does not automatically cover this version. DSH `0.2.0` stable and other rc versions are also outside its support range. Automated checks cover server loading, tool and Skill registration, routes, the client bundle, and UI slots separately so Doctor can identify which boundary failed.
 
@@ -196,8 +203,10 @@ Core and the DSH Adapter are being separated: DSH keeps loading the same npm pac
 | Tool | Purpose |
 |---|---|
 | `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_import_image` | Save a local or session image as a persistent Artifact for later operations |
+| `iris_edit_image` | Edit a source Artifact with a chat image model or supported native Qwen edit 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 |
@@ -227,7 +236,7 @@ Look, locate and OCR accept a local path, session attachment or Core image `arti
 
 Look, OCR chunks, locate and chat editing prepare sending copies using account/model budgets, with an 8 MiB default. Core originals, downloaded dimensions and hashes stay intact. OCR reports resizing and small-text risk; locate returns source-pixel coordinates. See [input budgets](docs/CLI_MANAGEMENT.md#看图输入预算).
 
-Chat editing uses a source Artifact ID and saves a linked new image; it requires a model configured for chat image generation. See [Artifact editing](docs/CLI_MANAGEMENT.md#artifact-聊天改图) and [workbench management](docs/WORKBENCH_ARTIFACTS.md) for filtering, selection, downloads and recovery.
+Image editing uses a source Artifact ID and saves a linked new image through a chat image model or, in 0.2.4, supported native DashScope Qwen models. See [Artifact editing](docs/CLI_MANAGEMENT.md#artifact-聊天改图) and [workbench management](docs/WORKBENCH_ARTIFACTS.md) for supported models, filtering, selection, downloads and recovery.
 
 Iris accepts three file sources, in the recommended order:
 
@@ -251,7 +260,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 +285,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 authenticated `/iris/api/doctor` JSON. It checks the host version, plugin, 17 tools and three skills, four route groups, host capabilities, client version, and four UI slots. 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 +338,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,24 @@ dsh-iris 为 Agent、Iris 工作台和独立 CLI 提供图像、视频、语音
 
 项目目前处于早期版本，接口和配置格式仍可能随版本迭代调整。
 
-Iris 0.2.2 同时提供 DSH 插件与无 DSH 的 CLI，共用任务、产物和模型路由，升级可控提示词编辑与媒体运行可靠性，保留 OpenAI 兼容图片与视觉工作流。Core 内部接口尚未冻结为公共 SDK。
+Iris 0.2.4 同时提供 DSH 插件与无 DSH 的 CLI，共用任务、产物和模型路由，支持图片导入、原生 Qwen 改图及统一功能分配。音乐、三项 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 的版本号独立。
+> 版本支持：Iris 0.2.4支持DSH `0.2.0-rc.2` 或 `0.2.1-alpha.4`，Iris 0.2.0–0.2.3仅支持rc.2。Node.js最低22.0.0；宿主若要求更高，以宿主为准。旧DSH固定使用Iris0.1.4，详见 [兼容矩阵](docs/DSH_COMPATIBILITY.md)。
 
-## 0.2.2 更新重点
+## 0.2.4 更新重点
 
-**可控提示词编辑与媒体运行可靠性**，在既有 OpenAI 兼容图片与视觉工作流上继续完善。
+**图片续作、明确的功能模型分配与新版宿主兼容**。
 
-- **提示词一般功能**：折叠五用途、原稿与改动预览；默认忠实整理，明确改写与独立建议需用户选择。
-- **明确功能模型池**：能力来自配置或可信元数据，裸账号与名称不自动赋能；保留功能入口、有序候选和既有明确标签。
-- **Core 恢复与交付**：保留 writer 创建/释放/恢复中断证据，非图片产物使用文件接收与分块哈希；不自动抢占租约或重新生成。
-- **生图诊断**：尺寸分隔符归一、合法长边和本地未受理校验；区分网络/正文故障、取消/超时与完整 HTTP 业务错误。
-- **跨平台回归**：修复中断夹具的根路径别名与分隔符假设，保留实际检查点验证。
+- **图片导入**：通过工作台、Agent或CLI把已有图片保存为持久作品，继续看图、改图和导出；保留源文件，不调用模型。
+- **原生 Qwen 改图**：除聊天生图外，支持DashScope Qwen带图编辑，修改版另存为关联原图的新作品。
+- **统一功能分配**：生图、视频、TTS、Music、转写和视觉只使用各自明确分配的有序名单；临时指定也须已分配。
+- **双版本宿主**：兼容DSH rc.2及alpha.4，manifest、客户端peer和Doctor使用相同范围。
 
-完整变化和待验边界见 [0.2.2 发布说明](docs/releases/0.2.2.md) 与 [CHANGELOG](CHANGELOG.md)。
+**升级前请检查功能分配**：空名单会停止新调用，不再自动补入模型池；已有任务仍可按原绑定查询和恢复。DSH默认视觉须明确加入视觉名单。详见 [升级说明](docs/FUNCTION_MODEL_ASSIGNMENTS.md)。
 
-后续计划继续适配其他协议，并增加 **Music 音乐生成**功能，详见 [路线图](docs/ROADMAP.md#后续功能方向)。
+完整变化见 [0.2.4 发布说明](docs/releases/0.2.4.md) 与 [CHANGELOG](CHANGELOG.md)；上一版音乐与Skills见 [0.2.3](docs/releases/0.2.3.md)。
+
+音乐的接口格式、模型分配与使用示例见 [Music](docs/MUSIC.md)。其他协议与后续能力见 [路线图](docs/ROADMAP.md#后续功能方向)。
 
 ## 两条使用路径
 
@@ -70,17 +71,17 @@ Iris 0.2.2 同时提供 DSH 插件与无 DSH 的 CLI，共用任务、产物和
 | 入口 | 按下文「最快开始」选择固定版本 | `dsh-iris run ...`，见 [Headless CLI](docs/HEADLESS_CLI.md) |
 | 数据位置 | `$DSH_HOME/iris/v1/`（Core 数据根 `core-v0`） | 显式 `--data-root` 指定的任意绝对路径 |
 | 自动观察 | 有（DSH Host 有界节拍 + 重启接管） | 显式 `task observe`；0.2.2 另提供有界 `task wait` |
-| 依赖 | DSH `0.2.0-rc.2`、Node.js ≥ 22 | 仅 Node.js ≥ 22 与 `sharp`（视频抽帧另需 `ffmpeg`） |
+| 依赖 | DSH rc.2或alpha.4、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#从旧工作台显式导入)。
 
 ## 最快开始
 
@@ -88,7 +89,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.1-alpha.4` | `0.2.4` | 固定 npm 版本 |
 | `>=0.1.2-rc.1 <0.1.3-0` 或 `0.1.5-rc.1` | 稳定版 `0.1.4` | 固定 npm 版本 |
 | 其他版本 | 暂无当前支持声明 | 先核对宿主适配，不能按相邻版本推定兼容 |
 
@@ -109,39 +110,40 @@ 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 rc.2或alpha.4：安装 0.2.4
 
 安装固定版本到 Web profile：
 
 ```bash
-dsh plugin --profile web add @mokuyoaxis/dsh-iris@0.2.2
+dsh plugin --profile web add @mokuyoaxis/dsh-iris@0.2.4
 dsh web
 ```
 
 插件在下一次 DSH 启动时装载。Web UI 默认位于 `http://127.0.0.1:3080`；启动输出带认证参数时请打开完整 URL。更新后需重新加载后端并刷新客户端。
 
-### 独立 CLI：安装 0.2.2
+### 独立 CLI：安装 0.2.4
 
 在自己的项目中安装，无需 DSH：
 
 ```bash
-npm install @mokuyoaxis/dsh-iris@0.2.2
+npm install @mokuyoaxis/dsh-iris@0.2.4
 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`，按 [兼容矩阵](docs/DSH_COMPATIBILITY.md) 选择；旧宿主使用固定 `@0.1.4`。市场目录与npm信息可能有缓存，以实际包的顶层 `engines.dsh`、Node要求及客户端peer为准；市场中可见不代表任意DSH版本兼容。
 
 > npm 上无 scope 的 `dsh-iris` 属于另一款插件。安装和更新 Iris Media 时必须保留完整包名 `@mokuyoaxis/dsh-iris`。
 
-首次启动后，打开“设置 → Iris 工作台 → + 添加供应商”，填入供应商 Base URL 和 API Key，再点“发现模型”。单供应商可以先使用自动能力分配。完整步骤、图片协议选择和故障转移说明见[用户指南](user_guide.md)。
+首次启动后，打开“设置 → Iris 工作台 → + 添加供应商”，填入供应商Base URL和API Key，再点“发现模型”，标注能力并为所需功能分配模型。0.2.4统一严格名单，升级差异见 [功能模型分配](docs/FUNCTION_MODEL_ASSIGNMENTS.md)；完整步骤和协议选择见 [用户指南](user_guide.md)。
 
 配置完成后，最小指令可以是：
 
 ```text
 使用 iris_draw_image：画一只坐在蓝色窗边的白猫。
 总结我刚上传的这张图片。
+用 Iris 生成一首复古摇滚配乐，保存为音频作品。
 用 Iris 总结 /absolute/path/demo.mp4，再把摘要合成为语音。
 ```
 
@@ -154,7 +156,7 @@ DSH 的 profile 与插件命令由[官方安装说明](https://github.com/deepse
 ![Iris 架构总览](docs/assets/diagrams/iris-architecture.png)
 
 - 图像生成、文生视频、图生视频和 S2V 数字人视频
-- 文本转语音与音频转写
+- 音乐生成、文本转语音与音频转写
 - 看图问答、长图 OCR、目标定位、裁剪和像素差异分析
 - 视频抽帧与多模态内容摘要
 - 异步任务跟踪、重启恢复和带授权令牌的媒体播放
@@ -165,7 +167,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 +176,9 @@ DSH 的 profile 与插件命令由[官方安装说明](https://github.com/deepse
 
 ## DeepSeek Harness 适配
 
-dsh-iris 仍按 DSH 原生插件装载。0.2.2 服务端注册 15 个 Agent 工具（含改图），并使用宿主提供的路由、附件、模型和生命周期能力；Web 客户端接入设置页、会话输入区与全局悬浮层。插件不会启动额外服务或监听端口。
+dsh-iris仍按DSH原生插件装载。0.2.4服务端注册17个Agent工具，包含图片导入、改图与音乐；使用宿主提供的路由、附件、模型和生命周期能力。Web客户端接入设置页、会话输入区与全局悬浮层，不启动额外服务或监听端口。
+
+上传图片或本地图片可保存为持久作品，继续看图、改图及导出，见 [图片导入](docs/IMAGE_IMPORT.md)。
 
 | Iris 范围 | DSH 范围 | 验证记录 |
 |---|---|---|
@@ -182,8 +186,10 @@ 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；升级后用宿主诊断检查实际装载 |
+| `0.2.4` | `0.2.0-rc.2` 或 `0.2.1-alpha.4` | 17工具/3项Skill；两版实际SDK、加载器与界面插槽隔离验收，完整浏览器/热更新另验 |
 
-rc.2 修正与验证范围见[适配说明](docs/DSH_RC2_ADAPTATION.md)；已发布 npm 0.1.4 包不包含这项后续适配。
+当前声明与验收范围见 [版本兼容](docs/DSH_COMPATIBILITY.md)，早期rc.2修正见 [历史适配记录](docs/DSH_RC2_ADAPTATION.md)；npm0.1.4不包含这些后续适配。
 
 Iris 0.2.x 不再声明支持旧 DSH；旧版的历史验收不自动覆盖当前版本。DSH `0.2.0` 正式版及其他 rc 同样未列入支持范围。自动化测试分别检查服务端装载、工具与 Skill 注册、路由、客户端 bundle 和 Slot；其中一层失效时，Doctor 应指出具体边界。
 
@@ -196,8 +202,10 @@ Core 与 DSH Adapter 正在分离，DSH 继续加载同一个 npm 包，Adapter
 | 工具 | 用途 |
 |---|---|
 | `iris_draw_image` | 根据提示词生成图片 |
-| `iris_edit_image` | 按原图 Artifact ID 和修改指令创建关联来源的新图片（聊天生图模型） |
+| `iris_import_image` | 将本地图片或会话图片保存为持久作品，返回后续操作使用的作品ID |
+| `iris_edit_image` | 按原图 Artifact ID 和修改指令创建关联来源的新图片（聊天生图或已接入的原生 Qwen 改图模型） |
 | `iris_generate_video` | 生成文生视频、图生视频或 S2V 数字人视频 |
+| `iris_generate_music` | 根据描述生成音乐，保存为可试听、下载的音频作品 |
 | `iris_speak_text` | 将文本合成为语音 |
 | `iris_transcribe_audio` | 将音频转写为文本 |
 | `iris_task_status` | 查询单个任务或最近任务的状态和产物 |
@@ -227,7 +235,7 @@ Core 与 DSH Adapter 正在分离，DSH 继续加载同一个 npm 包，Adapter
 
 看图、OCR 每块、定位和聊天改图按账号/模型预算准备发送副本，默认 8 MiB，可调整大小与最长边；Core 原图、下载尺寸和哈希保持不变。OCR 标明缩小后的实际尺寸与细字风险，定位返回原图像素坐标。详见 [视觉输入预算](docs/CLI_MANAGEMENT.md#看图输入预算)。
 
-Core 图片改图直接使用来源 ID，修改版另存为新作品；[聊天改图](docs/CLI_MANAGEMENT.md#artifact-聊天改图)仅支持配置了聊天生图协议的模型。作品分页、过滤、跨页选择、下载与回收操作见 [工作台作品管理](docs/WORKBENCH_ARTIFACTS.md)。
+Core图片改图直接使用来源ID，修改版另存为新作品；[改图](docs/CLI_MANAGEMENT.md#artifact-聊天改图)支持聊天生图协议及0.2.4的DashScope原生Qwen改图。作品分页、过滤、跨页选择、下载与回收操作见 [工作台作品管理](docs/WORKBENCH_ARTIFACTS.md)。
 
 Iris 支持三种文件来源，推荐顺序如下：
 
@@ -251,7 +259,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 +284,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，检查宿主版本、插件、17工具/3项Skill、四组路由、宿主能力、客户端版本和四个UI Slot。它只读取安全快照与注册证据，不调用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 +337,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不能替代工具装载或模型分配，也不改变任务、费用确认和安全边界。
 
 ## 开发与验证