@mokuyoaxis/dsh-iris 0.2.2 → 0.2.4

package/docs/HOST_DOCTOR.md

@@ -5,7 +5,9 @@ Host Doctor 是 Iris 在运行中的 DSH 实例内提供的兼容性诊断。它
 | 模式 | 入口 | 观察范围 |
 |---|---|---|
 | `offline` | `dsh-iris doctor [--json]` | Node、依赖、私有存储、配置、Task 与产物；不要求 DSH |
-| `host` | 已认证 DSH 中的 `GET /iris/api/doctor` | DSH 版本和 Host Port、插件装载、当前工具（0.2.1为 15 个）、2 项 Skill、4 组路由、Browser/附件/模型能力、客户端版本与 4 个 UI Slot |
+| `host` | 已认证 DSH 中的 `GET /iris/api/doctor` | DSH与Host Port、插件、当前工具/Skill、4组路由、Browser/附件/模型、客户端版本和4个UI Slot；Iris 0.2.4检查17工具/3项Skill |
+
+0.2.4新增 `iris_import_image`，图片导入自身不调用模型。0.2.3检查16工具/3项Skill，发布状态见 [README](../README.md)。
 
 两种模式都默认零网络、零计费。Host Doctor 不调用任何 Host Port，不打开 Browser，不读取附件或会话，不调用文本/视觉模型，也不向 Provider 发送请求。它只读取：
 
@@ -29,15 +31,15 @@ Host Doctor 是 Iris 在运行中的 DSH 实例内提供的兼容性诊断。它
 
 如果刚安装、热更新或强制刷新，先等 Web 页面完成装载，再刷新诊断。未收到客户端握手时，Host Doctor 只报告警告，不会把“服务端已装载”冒充成“UI 已装载”。
 
-Iris `0.2.x` 仅支持 DSH `0.2.0-rc.2`，版本检查与 package 的 DSH engines 一致。旧 DSH `0.1.2` 线或 `0.1.5-rc.1` 返回版本错误，并提示使用历史稳定包 `@mokuyoaxis/dsh-iris@0.1.4`；旧版 Doctor 的支持范围不继承到当前版本。无 DSH 的 CLI/离线诊断不受此宿主限制。
+Iris0.2.4支持DSH `0.2.0-rc.2` 或 `0.2.1-alpha.4`，Doctor与package顶层/嵌套DSH engines及客户端peer保持同一范围。0.2.0–0.2.3仅支持rc.2。旧DSH0.1.2线或0.1.5-rc.1返回版本错误，并提示固定Iris0.1.4；无DSH的CLI/离线诊断不受宿主版本限制。见 [兼容矩阵](DSH_COMPATIBILITY.md)。
 
 ## 运行时证据
 
 服务端只登记成功完成的注册：
 
 - 插件身份与 npm 版本；
-- Iris Agent 工具名（0.2.1包含 `iris_edit_image`，共 15 个）；
-- `iris-verify-ui`、`iris-compose-media`；
+- Iris Agent工具名（0.2.4为17个，0.2.3为16个）；
+- 随包的 `iris-use`、`iris-compose-media`、`iris-verify-ui`，缺失iris-use明确报告；
 - `/iris/media`、`/iris/api`、`/iris/api/actions`、`/iris/render` 四组逻辑路由。
 
 客户端通过 `POST /iris/api/host-client` 回报插件 ID、静态客户端版本、协议版本和已执行的 Slot 名单。接口拒绝额外字段、未知 Slot、错误插件身份、空版本和无效协议号；同一前端版本的并发报告只做 Slot 单调并集，避免乱序请求把完整证据覆盖成部分证据。报告只保存在内存，不参与认证、任务执行或能力授权，也不接收 API Key、草稿、会话、附件或 Provider 数据。

package/docs/IMAGE_IMPORT.md

@@ -0,0 +1,49 @@
+# 图片导入
+
+版本要求：Iris0.2.4；npm0.2.3没有本页的导入命令和工具。发布状态见 [README](../README.md)。
+
+把上传图片、会话图片或宿主本地图片保存为Iris作品，获得后续看图、改图、裁剪和导出可复用的作品ID。导入只在本地保存副本，不调用模型、不创建生成任务，原文件保持。
+
+支持单张静态PNG、JPEG、WebP，最多20 MiB。格式和尺寸按真实内容识别，保留原始字节；不会按文件名转码，不支持动画、网络URL或`content://`路径。相册中的图片请通过浏览器上传。
+
+## 工作台
+
+1. 打开作品区，展开“导入图片”。
+2. 用“上传文件”选择图片，也可选当前会话附件；宿主本地文件可通过“高级 · 宿主路径”输入。
+3. 点击“保存到作品”。完成后显示图片，作品区刷新；导入作品标为“导入图片”。
+
+单纯上传仍是临时输入副本，既有上传保留期为七天；“保存到作品”成功后，作品与上传副本独立保存，不随该保留期过期。上传或输入格式错误时，按错误提示修正后重新导入。
+
+## Agent
+
+使用实际已装载的 `iris_import_image`，二选一：
+
+```json
+{"image_path":"/absolute/path/source.png"}
+```
+
+```json
+{"attachment_id":"current-session-image-id"}
+```
+
+附件只能来自当前会话或Iris已有的受支持图片引用，不能猜测其他会话附件ID。结果给出作品ID与图片链接。需要修改时，把返回ID交给 `iris_edit_image` 的 `source_artifact_id`；已经是Core图片的作品可直接使用，不必重复导入。
+
+## CLI
+
+无需DSH或供应商配置，使用明确的数据根和宿主可读绝对路径：
+
+```bash
+dsh-iris artifact import --data-root /absolute/path/iris-core \
+  --input '{"image_path":"/absolute/path/source.png"}'
+```
+
+返回JSON中的 `artifact.id` 是稳定作品ID，`artifact.kind` 为 `imported-image`，并包含媒体类型、尺寸与内容哈希。原路径和文件名不写入作品记录。该命令使用既有Core单写者约束；同一数据根已有其他写者时按现有规则拒绝。
+
+```bash
+dsh-iris artifact export artifact_ID --data-root /absolute/path/iris-core \
+  --output /absolute/path/export.png
+```
+
+导出保留原字节，输出路径不能覆盖已有文件。看图与改图另按对应功能分配调用模型，见 [视觉CLI](VISION_CLI.md)、[聊天改图](CLI_MANAGEMENT.md#artifact-聊天改图) 和 [功能模型分配](FUNCTION_MODEL_ASSIGNMENTS.md)。
+
+本步只提供持久导入与已有操作衔接；原图/新版并排对比、版本选择和配乐关联仍是后续工作。

package/docs/MODEL_PORT_CONTRACT.md

@@ -1,6 +1,10 @@
 # Text/Vision Model Port v0 契约设计
 
-状态：**Iris 0.2.2。** 0.2.0 已包含 M1 契约；0.2.2 接入 DSH 文本适配器与共享优化消费者、HTTP/DSH Vision Port，以及 look/relook、OCR、定位、拼图摘要和图片自述。端口仍为内部契约，不增加公开 export 或生产依赖，不改变 [Host Adapter v0](HOST_ADAPTER_CONTRACT.md) 的现有方法。新增按次规则与 UI 见 [提示词优化系统](PROMPT_OPTIMIZER.md)，单图预算与宿主附件副作用见 [单图视觉调用](VISION_MODEL.md)，复合操作见 [长图 OCR](OCR_MODEL.md) 和 [定位与摘要](COMPOSITE_VISION.md)。
+状态：**Iris 0.2.3。** 0.2.0 已包含 M1 契约；0.2.2 接入 DSH 文本适配器与共享优化消费者、HTTP/DSH Vision Port，以及 look/relook、OCR、定位、拼图摘要和图片自述。端口仍为内部契约，不增加公开 export 或生产依赖，不改变 [Host Adapter v0](HOST_ADAPTER_CONTRACT.md) 的现有方法。新增按次规则与 UI 见 [提示词优化系统](PROMPT_OPTIMIZER.md)，单图预算与宿主附件副作用见 [单图视觉调用](VISION_MODEL.md)，复合操作见 [长图 OCR](OCR_MODEL.md) 和 [定位与摘要](COMPOSITE_VISION.md)。
+
+DSH Text 绑定按精确元数据检查文本输入声明；明确不接受 text、身份漂移或非法模态字段在生成前拒绝。没有声明时保持 unknown，已有元数据查询失败则返回准备阶段 unavailable，不再吞掉错误继续生成。查询与生成共用取消/预算，Vision 仍由独立桥接检查 image 输入，不借用 Text 的 text 检查。改写格式与路由原因见 [提示词优化系统](PROMPT_OPTIMIZER.md)。
+
+提示词核心为单片段 faithful 提供程序返回路径，在模型绑定/元数据/生成前短路；输入、规则、输出限额和取消仍检查。已调用的提示词结果提供 `processing.request` 完整指令快照，未调用不伪造请求；这是业务响应扩展，不改变 Model Port v0 请求/完成协议或公共 exports。
 
 0.2.1 还提供 [视觉 CLI](VISION_CLI.md)、可选账号/模型 `visionInput` 和设置命令，见 [看图输入预算](CLI_MANAGEMENT.md#看图输入预算)；不改变请求/完成 DTO、契约版本或公开 exports。该设置用于看图、OCR 分块、定位和聊天改图的发送副本，不是供应商能力上限声明；聊天改图的媒体任务语义仍由 Core Runner 管理。
 
@@ -28,7 +32,7 @@ flowchart TD
   VISION --> FA
 ```
 
-图中是目标结构。独立文本 Provider 与新 Headless 命令不在本轮范围；当前自持 Provider 目录尚无 `text` 能力。
+图中是目标结构。独立文本 Provider 与提示词 Headless 命令尚未提供；当前自持 Provider 目录尚无 `text` 能力。
 
 ## 职责归属
 

package/docs/MUSIC.md

@@ -0,0 +1,77 @@
+# 音乐生成
+
+Iris 0.2.3 提供独立音乐生成能力。配置音乐模型后，可以通过 DSH 对话、工作台或 CLI 生成 MP3/WAV，试听、下载并导出同一作品。音乐与文本转语音分别配置，组合创作时按需加入配乐。
+
+## 支持的接口
+
+选择 **Chat Completions（内嵌音频）**：服务接收 OpenAI 风格的 `/chat/completions` 请求，并在 `choices[].message.content` 文本中返回 MP3/WAV 的 `data:audio/...;base64,...` 链接。
+
+接口支持取决于请求和返回格式，不取决于供应商名称或模型 ID。仅声明“OpenAI 兼容”的服务不一定支持这种音频输出；纯文字、远程音频 URL 或其他音频字段不能通过当前接口交付。Google 原生音乐 API 需要独立适配，目前不在支持范围内。
+
+## 工作台配置
+
+1. 添加音乐服务的供应商，填写实际 Base URL 和 API Key；Base URL 应包含服务要求的 API 前缀，例如 `/v1`。
+2. 发现或手动添加实际模型，为它设置“音乐”功能标签。
+3. 在模型的“音乐协议”中选择“Chat Completions（内嵌音频）”。
+4. 在“能力分配”中将该模型加入音乐名单。
+
+音乐仅使用明确分配的名单；未分配时会提示配置缺失。发现模型、添加标签或修改协议不会提交生成请求。音乐协议独立于账号和模型的图片协议。
+
+配置文件中的 `musicProtocol` 使用现有标识 `gemini-web-music`，以兼容已有配置；这个标识不要求供应商或模型必须命名为 Gemini。
+
+## 通过 DSH 或工作台生成
+
+在 DSH 中可以直接描述需求：
+
+```text
+用 Iris 生成一首复古摇滚配乐，电吉他和鼓为主，期望约30秒，无人声。
+```
+
+也可以明确选择 `/iris-use` 或工具 `iris_generate_music`。工作台的音乐卡片提供描述输入、模型选择、生成、试听与下载。结果保存为 Core 音频作品，可继续查询或导出。
+
+曲长、人声、歌词、语言和节拍通过描述表达，由实际模型决定；当前没有保证精确控制这些属性的独立参数。输入或响应格式不符时会明确失败。
+
+## CLI 配置与生成
+
+下面的 `music-provider::music-model` 是示例，请替换为实际供应商 ID 和模型 ID。配置路径与数据根均使用绝对路径。
+
+```bash
+dsh-iris models add music-provider::music-model \
+  --provider-config /absolute/path/providers.json \
+  --input '{"capabilities":["music-gen"],"musicProtocol":"gemini-web-music"}'
+
+dsh-iris assignments set \
+  --provider-config /absolute/path/providers.json \
+  --input '{"capability":"music-gen","model_refs":["music-provider::music-model"]}'
+
+dsh-iris run music \
+  --data-root /absolute/path/iris-data \
+  --provider-config /absolute/path/providers.json \
+  --input '{"prompt":"轻快钢琴配乐，期望约30秒，无人声","retry_502":2,"retry_delay_ms":5000,"timeout_ms":300000}'
+```
+
+已有模型可用 `models caps` 设置功能标签，并用 `models music-protocol` 设置 `musicProtocol`。这些命令只修改指定配置并保留私有备份，不请求生成。
+
+生成输入为 `prompt`，可选 `model_ref` 指定名单中的模型。成功退出码为 0，最终失败为 1；JSON 输出包含最终 Task、Artifact ID、本次 Task ID 列表与重试次数。后续进程可用 `artifact inspect` 和 `artifact export` 导出同一作品，见 [Headless CLI](HEADLESS_CLI.md)。
+
+## 超时、重试与失败恢复
+
+| 参数 | 默认值 | 含义 |
+|---|---:|---|
+| `timeout_ms` | 300000 | 单次请求上限，范围 1–3600000 毫秒；不是音乐时长 |
+| `retry_502` | 2 | HTTP 502 后额外生成次数，范围 0–5；0 关闭，默认最多提交3次 |
+| `retry_delay_ms` | 5000 | 502 后等待时间，范围 0–60000 毫秒 |
+
+仅收到 HTTP 502 时按本次参数重试，同一失败模型重新生成，不自动切换来源。每次重发创建关联的新 Task；上游可能已经生成音乐，因此重试可能消耗额外额度。超时、其他 HTTP 状态、文字响应和交付失败不触发这项重试。供应商配额以其实际政策为准。
+
+完整音频已缓存但本地交付失败时，使用工作台“重新取回作品”或 `task redeliver` 恢复，不重新生成。手动 `task retry` 是一次新的知情生成，需要重新提供描述；不要在 Agent 外层再增加重试循环。
+
+取消会停止本地等待和后续重试，无法据此确认上游生成已经撤销。逐模型 `models test --capability music-gen` 会跳过音乐测试；需要验证服务时，明确提交所需作品。
+
+## 接口与产物
+
+- 模型能力标签为 `music-gen`，Core Task 能力为 `music`，产物类型为 `generated-audio`。
+- DSH 工具和工作台使用 `POST /iris/api/actions/music`；工具/Action 的模型字段是 `model`，CLI 使用 `model_ref`。
+- 当前只交付 MP3/WAV，按响应媒体类型保存，不转换格式。音频作品可复用作品库筛选、播放和导出。
+
+交付失败的详细恢复步骤见 [同步交付恢复](SYNC_DELIVERY_RECOVERY.md)。

package/docs/PROMPT_OPTIMIZER.md

@@ -1,8 +1,8 @@
 # 提示词优化与规则组装
 
-状态：**Iris 0.2.2**。在既有按次规则、只组装和可编辑预览上增加一般功能，特殊功能待后续安排。
+本文面向 Iris 0.2.3，介绍对话草稿的忠实整理、明确改写、可选建议和零模型调用的规则组装。结果先进入预览，写回不会自动发送。
 
-## 一般功能（0.2.2）
+## 用途选择
 
 面板将一般功能放在可折叠卡片中，按“通用、画图、改图、视频、数字人”选择用途。当前草稿、本次规则、操作、可编辑结果和对照属于同一功能区域；折叠不清空选择、规则或结果，也不触发模型请求。指令与模型设置独立折叠，可在调用前查看当前系统指令和目标模板。浏览器原生对话框在顶层显示，避免宿主悬浮按钮遮住结果。桌面和窄屏使用同一流程，支持点击背景或 Escape 关闭、焦点恢复与对话框内键盘焦点循环。
 
@@ -14,13 +14,13 @@
 | 视频 | `video` | 动作先后、镜头与连续性 |
 | 数字人 | `s2v` | 已有首帧与音频下的人物动作、表情和镜头 |
 
-默认指令参照项目 Skills 的职责、目标、输入、保持/改变和输出组织方式，并使用实际 Iris 工具语义。S2V 的旧内置“首尾帧”标签有误，本轮修正为首帧+音频数字人。优化器仍只编辑草稿，不读取图片/音频、不生成媒体，也不冒充已经检查素材；具体方位、数量、颜色、数值、引用原文和否定条件必须保留。模型实际是否遵守仍需用户检查原文对照。
+默认指令参照项目 Skills 的职责、目标、输入、保持/改变和输出组织方式，并使用实际 Iris 工具语义。S2V 指已有首帧加音频的数字人视频。优化器仍只编辑草稿，不读取图片/音频、不生成媒体，也不冒充已经检查素材；具体方位、数量、颜色、数值、引用原文和否定条件必须保留。模型实际是否遵守仍需用户检查原文对照。
 
 v1 配置兼容：增加 `targets["image-edit"]`，旧配置缺少此项时只在内存补齐，不自动重写文件。既有 systemPrompt、目标模板与模型路由优先保留，包含用户自定义 s2v 文本；用户显式恢复默认后才替换为新的内置指令。没有新增规则持久格式、特殊功能或 CLI。
 
-### 编辑方式（0.2.2）
+### 编辑方式
 
-新界面默认选择 **忠实整理**：模型只选择相邻原文片段之间的分段位置，程序从原稿拼回正文。每个片段必须恰好出现一次、句序保持，遗漏、重复、调换或新增内容都会拒绝。条件、动作先后、引文、代码和复杂格式采用保守分段；已有完整文本允许保持原样。本次保证的是原文片段和顺序，不是自动证明所有排版变化的语义完全相同。
+新界面默认选择 **忠实整理**：模型只选择相邻原文片段之间的分段位置，程序从原稿拼回正文。每个片段必须恰好出现一次、句序保持，遗漏、重复、调换或新增内容都会拒绝。条件、动作先后、引文、代码和复杂格式采用保守分段；已有完整文本允许保持原样。忠实整理保证原文片段和顺序，不是自动证明所有排版变化的语义完全相同。
 
 需要等义润色或明确改变某个项目时，选择 **改写表达** 并填写本次改写规则。例如“只把白色丝袜改为黑色，其余保持”授权改变指定颜色；其余事实和否定继续保留。忠实整理不会静默执行或丢弃改写规则。改写表达仍是模型生成文字，新增含义与遗漏需查看对照，不能以结果非空证明忠实。
 
@@ -40,11 +40,11 @@ v1 配置兼容：增加 `targets["image-edit"]`，旧配置缺少此项时只
 | 输出前缀 | 模型改写完成后，程序原样加入开头 | 原样加入原稿开头 |
 | 输出后缀 | 模型改写完成后，程序原样加入末尾 | 原样加入原稿末尾 |
 
-智能优化进行一次文本模型生成；只组装不读取模型路由或优化配置、不调用模型，在 Host 文本服务不可用时仍可使用。只组装不会套用目标模板或自动润色原稿。规则之间与正文之间用两个 LF 分隔；输出规则原文与只组装的草稿空白保持不变。
+需要模型的优化进行一次文本生成；单片段忠实整理直接保留原文，不调用模型。只组装不读取模型路由或优化配置、不调用模型，在 Host 文本服务不可用时仍可使用。只组装不会套用目标模板或自动润色原稿。规则之间与正文之间用两个 LF 分隔；输出规则原文与只组装的草稿空白保持不变。
 
 结果先进入可编辑预览。可以查看原文、本次参与规则、实际模型与思考策略，以及折叠相同首尾后的中间替换区。这是文本改动对照，不代表模型解释了每处改动的原因。手动编辑也会更新对照；复制和写回使用编辑后的文字。
 
-实现前的真实模型补测发现，文本模型别名也可能返回图片链接，甚至返回扩写正文加图片链接。改写结果会在拼接前后缀之前检查未由原稿/明确改写规则提供的新链接、媒体标记和明显的执行完成/拒绝回复；已有合法链接、原文引用及只组装保留。忠实整理与建议模式另检查专用 JSON 形状、片段序列或建议字段，未授权正文不能混入。检查不构成任意自然语言的完整语义证明。拒绝后不自动重试、切换模型或写回；上游可能已经处理请求，不能据此推定没有计费或媒体副作用。
+改写结果会在拼接前后缀之前检查未由原稿/明确改写规则提供的新链接、媒体标记和明显的执行完成/拒绝回复；已有合法链接、原文引用及只组装保留。忠实整理与建议模式另检查专用 JSON 形状、片段序列或建议字段，未授权正文不能混入。检查不构成任意自然语言的完整语义证明。拒绝后不自动重试、切换模型或写回；上游可能已经处理请求，不能据此推定没有计费或媒体副作用。
 
 写回不会自动发送。出现新草稿时先确认替换；出现结构化 `@`、`/` 引用或忙碌状态时拒绝写回。切换会话清除旧预览并取消在途操作，即便两边草稿文本相同。取消、关闭或卸载会传递 abort，迟到结果不能恢复旧预览或覆盖新操作。恢复原文只恢复本次操作前的文字，不自动恢复附件/结构化引用。
 
@@ -62,16 +62,54 @@ v1 配置兼容：增加 `targets["image-edit"]`，旧配置缺少此项时只
 
 取消表示本地停止等待并向底层传递信号，不保证第三方远端执行或计费已停止。失败、工具调用、未知终态和部分正文不会作为完整结果交付。
 
-## 开发边界
+## 预览、配置与恢复
+
+再次优化失败或取消时，已有预览和手工编辑会保留；等待期间继续编辑，新结果不会覆盖这些改动。单片段忠实整理会显示“无需分段，未调用模型”。需要模型时，预览显示实际路由及选择原因，并可展开发送给 Model Port 的指令。
+
+配置异常时，界面说明是否使用默认值及原文件是否保留。“仅恢复默认指令”保留模型、生成参数和入口开关；“恢复全部设置”重置完整配置。导入会替换当前配置，操作前可先导出备份。
+
+## 开发者参考
 
 `prompt-optimizer-core.js` 只接收显式文字、模板快照及 TextModel Port；DSH 入口负责 v1 配置、模型绑定、预览与写回。DSH 适配器聚合 `text-delta` / `block-end`、忽略思考正文、检查终态和清理源迭代器。rc.2 的缓存与未缓存输入计数相加后成为共享输入 token 数，未知 usage 字段省略。
 
-优化和组装不创建 Core Task/Attempt/Artifact，不取得 writer 租约。纯核心可在无 DSH 的安装树中执行，但本轮未增加 CLI 命令、自持文本目录、公共 SDK export 或规则持久化格式。
+优化和组装不创建 Core Task/Attempt/Artifact，不取得 writer 租约。纯核心可在无 DSH 的安装树中执行，当前没有独立提示词 CLI、公共 SDK export 或规则持久化格式。
 
 现有 `POST /iris/api/prompt-optimizer/optimize` 增加可选 `mode`（`optimize` / `assemble`）与 `rules`；省略时沿用原优化行为。规则形状为 `{ id, label, kind, text, position? }`：kind 是 `optimization` 或 `output`，只有 output 设置 `prefix` / `suffix`。调用者不能伪造 source；响应由程序标记为 `user-selected`。直接 API 在 assemble 模式携带 optimization 规则会拒绝；UI 只组装只提交输出规则。
 
-0.2.2增加可选 `editing: "faithful" | "rewrite" | "suggestions"`，仅用于 optimize。省略时保持旧文字改写协议与 `optimized` 文本响应，不破坏旧调用；新界面显式传 faithful。faithful 允许输出前后缀但不接受 optimization 规则，响应另含 `editing: { strategy, coverage: "exact", order: "preserved", groups }`。suggestions 不接受任何规则，`optimized` 逐字等于原稿，另含 `suggestions: [{ id, label, text }]`、`questions: string[]`，ID 由程序生成；本轮指令要求至多三条有用建议/问题，协议上限分别为六条，label 最多 80、text/问题最多 600 字符。它们未经事实验证或采纳，不能当成用户已有要求。
+0.2.2增加可选 `editing: "faithful" | "rewrite" | "suggestions"`，仅用于 optimize。省略时保持旧文字改写协议与 `optimized` 文本响应，不破坏旧调用；新界面显式传 faithful。faithful 允许输出前后缀但不接受 optimization 规则，响应另含 `editing: { strategy, coverage: "exact", order: "preserved", groups }`。suggestions 不接受任何规则，`optimized` 逐字等于原稿，另含 `suggestions: [{ id, label, text }]`、`questions: string[]`，ID 由程序生成；内置指令要求至多三条有用建议/问题，协议上限分别为六条，label 最多 80、text/问题最多 600 字符。它们未经事实验证或采纳，不能当成用户已有要求。
 
 配置 API 在配置对象外返回 `capabilities: { rules: true, assemble: true }`；0.2.2另声明 `targets: ["general", "image", "image-edit", "video", "s2v"]` 与 `editing: ["faithful", "rewrite", "suggestions"]`。客户端读到明确能力才启用规则、只组装、新改图目标与新编辑策略。没有 targets 声明时只启用旧四目标，没有 editing 声明时保持旧智能优化；能力字段不进入配置导出文件。
 
 参见 [Model Port 契约](MODEL_PORT_CONTRACT.md) 与 [架构边界](ARCHITECTURE.md)。浏览器/Android 交互和真实模型质量需各自验收。
+
+### 改写格式与路由选择
+
+改写表达增加专用正文交付协议：返回输入 JSON 中 prompt 的实际字符串值，不复制 target/prompt 容器或序列化转义，保留原稿实际的 JSON、代码、引号、换行和反斜杠。协议追加到本次请求，不覆盖自定义 v1 配置。程序拒绝可识别的新增双字段 target/prompt 外壳、完整外层代码围栏，以及带转义的整体 JSON 字符串包装；原稿本身采用该 JSON 形状、改写规则提供对应字段样例，或素材已有围栏/JSON 字符串时允许保留。原稿内部引用 JSON 不授权给整份正文新加容器。输出前后缀仍由程序原样拼接，改写不再自动剥掉 text/markdown 围栏。忠实整理和建议继续使用各自的 JSON 协议，省略 editing 的旧入口也使用新改写交付约定。
+
+这些是有限结构检查：原稿已有对应格式时不能自动辨别所有额外包装，也不能可靠判断普通正文中每个新增转义、标题、解释或含义变化。不会自动解包 JSON、删反斜杠或重试。结果仍需查看对照；rewrite 的输入和结果沿用首尾 trim，不承诺逐字保留首尾缩进。
+
+需要模型的操作，选择优先级保持 **fixed 配置 → 当前会话明确选择 → 宿主默认**。null/未提供会话路由才使用默认；提供但缺字段、包含无效 ID 或无效 reasoningEffort 时明确拒绝。fixed 优先，不读取被其覆盖的会话或默认选择，也不在固定模型失败后改用另一来源。只组装和本地单片段忠实结果不使用模型路由。
+
+调用前使用宿主精确模型元数据检查身份与文本输入能力。inputModalities 明确不包含 text 则拒绝；缺失字段或没有查询端口属于未知，不从模型名、用途或媒体池推断。查询端口存在但查询失败则返回准备阶段错误，停止生成，不能把失败当成未知继续请求。元数据查询和生成仍共用一次操作预算，只查询所选路线，没有额外生成探测。已声明接受文本输入不保证远端只输出文字，正文检查继续生效。
+
+响应 route 另含 `reason`（选择原因）与 `textInput: "supported" | "unknown"`（宿主文本输入声明）；预览显示这两项，旧响应缺少字段时保持原显示。没有新增路由池、成本/时延排名、配置格式迁移或失败切换。
+
+### 预览保护、忠实零调用与本次指令
+
+再次优化保留当前预览、手工编辑及建议撤回记录；新结果成功且预览未在等待期间改变时才替换。失败、取消、关闭后的迟到结果或等待期间的继续编辑不清空或覆盖已有内容；切换会话仍清除旧预览并中止请求。重新生成依照输入框当前草稿，继续保持明确写回、不自动发送。
+
+忠实整理若只有一个受保护的原文片段，程序原样返回并拼接输出前后缀，跳过优化配置加载、模型路由、元数据查询和生成。响应保持 `mode: "optimize"`、完整来源/顺序及单组 ID，另含 `execution: { modelInvocations: 0, reason: "single-part-faithful" }`、`route: null`、`configSource: "not-loaded"`；界面显示“忠实整理：无需分段，未调用模型”，不标为只组装。正常输入/规则/输出限额及预取消继续检查；多片段仍由模型决定连续分组。英文句号、条件、复杂引用/代码等经保守分段可能成为单片段，这表示原样保留，不表示已经改善排版。
+
+配置 API 在配置对象外另声明 `capabilities.localFaithful: true`；界面只有收到这一明确能力才说明单片段零调用。仅有旧 faithful 能力时继续说明可能产生模型费用，避免单独更新客户端后误宣称旧服务端已经省掉调用。能力不进入 v1 配置导出。
+
+调用模型的响应 `processing.request: { system, prompt }` 保存本次完整编译指令，包括模式协议、改写规则及素材 JSON 包装。预览的折叠区分别展示正文处理和可选建议的快照；它们表示 Iris 发送给 Model Port 的内容，不保证等于宿主/SDK/供应商最终 payload。没有模型请求时不伪造快照。旧响应缺少字段时保留原显示，不迁移配置或持久保存这些快照。
+
+### 配置反馈与恢复范围
+
+配置读取、导入、恢复和开关接口在配置之外返回 `feedback.warnings`；已调用的优化结果另含本次 `configFeedback`，没有加载配置的本地路径不伪造读取状态。正常默认与正常加载没有警告；读取失败、JSON 无效或校验失败会说明正在使用内置默认，并记录原文件是否隔离保留。反馈和受控日志不返回原始错误、文件内容、被忽略的字段值或私有路径。成功隔离的原文件继续保留，不自动清理。
+
+v1 仍忽略未知字段并按内置默认补齐缺项，但现在反馈未知或当前路由未使用的字段名。例如 `modeTemplates`、`rules`、`generation.maxTokens` 并未接入，实际 token 字段是 `generation.maxOutputTokens`；session 路由中的 provider/model 不生效。反馈最多列出 32 个字段名、每名最多 256 字符，同时报告总数。导入仍替换当前完整配置，不把缺项自动合并为当前个人设置；反馈不写入导出文件或持久 v1 配置。
+
+“仅恢复默认指令”只更新 systemPrompt 和全部 targets，保留当前可读设置中的 route、generation、enabled；“恢复全部设置”同时重置上述全部字段、生成预算和入口开关。只恢复指令需要 `capabilities.resetInstructions: true`，旧后端按钮不可用，防止旧服务端把新请求当成全部恢复。恢复操作需要界面确认；读取回退时，不能声称保留未读出的原设置，因此仅指令恢复拒绝，需先导入有效配置或明确全部恢复。
+
+API `POST .../reset` 接受 `scope: "instructions" | "all"`，省略 scope 继续旧的全部恢复；其他 scope 返回 400 且零写入。读取失败不移动原文件；内容无效隔离失败时也不会因切换入口开关覆盖原文件。成功隔离后的入口切换继续保留本进程的回退提示，显式有效导入或全部恢复才清除；进程重载后以实际当前文件为准。

package/docs/PROVIDER_ADAPTER_CONTRACT.md

@@ -1,5 +1,7 @@
 # Provider Adapter v0 生命周期契约
 
+Iris 0.2.3 提供 `music` Task能力与 Chat Completions 内嵌音频 Adapter（现有标识 `gemini-web-music`），复用v0同步completed和音频交付契约。音乐模型通过独立 `musicProtocol` 绑定，见 [音乐生成](MUSIC.md)。502重新生成策略在Music功能层执行，Adapter仍只提交一次。
+
 状态：**Iris 0.2.2；沿用 v0 生命周期内部契约。** 0.1.4 建立六操作契约，0.2.0 增加可选输入准备能力，0.2.2 增加聊天/Responses 生图及模型级协议覆盖。 这是 Iris Core 模块与供应商协议实现之间的内部边界，尚未冻结为第三方公开 SDK。DashScope 与 OpenAI Images 兼容实现通过同一套零网络 conformance runner；聊天/Responses 图片协议另有提交、交付与 CLI 回归。
 
 ## 目标与依赖方向

package/docs/ROADMAP.md

@@ -1,46 +1,37 @@
 # 路线图
 
-Iris 正从 DSH 媒体插件演进为可独立运行、可接入不同 Agent 宿主的媒体生产核心。本文列当前状态与后续方向；版本变化见 [变更记录](../CHANGELOG.md)。
+Iris 的方向是本地优先、Agent 可调用的多模态创作工作台。用户可从描述或已有素材出发，生成、修改、选择和交付作品。本文介绍当前能力与后续方向；版本变化见 [变更记录](../CHANGELOG.md)。
 
 ## 当前状态
 
-当前版本为 **Iris 0.2.2**。包名保持 `@mokuyoaxis/dsh-iris`，同时提供 DSH 插件与无 DSH 的 Headless CLI。本版变化见 [0.2.2 发布说明](releases/0.2.2.md)。
+本文对应 **Iris0.2.4**，发布状态见 [README](../README.md)。包名为 `@mokuyoaxis/dsh-iris`，同时提供DSH插件与独立CLI，详见 [0.2.4发布说明](releases/0.2.4.md)。
 
-0.2.1 的更新重点是 **完成 OpenAI 兼容图片与视觉工作流**：生成图片 → Core Artifact → 按 ID 看图/OCR → 聊天改图 → 新 Artifact，CLI 与 DSH 工作台共用同一链路。本版已实现以下能力：
+- 图片生成、Artifact ID 看图/OCR/定位和聊天改图，支持按模型配置图片协议。
+- 持久图片导入与原生Qwen改图，六类功能统一严格分配及显式宿主视觉；支持DSH rc.2和alpha.4。见 [0.2.4发布说明](releases/0.2.4.md)。
+- 视频、S2V、TTS、转写与音乐生成，共用任务、音频/视频作品和导出入口；音乐使用明确分配名单。
+- 三项 Agent Skills 分别指导单步操作、多步骤创作和界面验收；配乐与检查按用户目标加入。
+- 提示词的忠实整理、明确改写、可选建议与预览；完整同步媒体结果缓存后的交付恢复。
+- 工作台全媒体筛选、分页、跨页选择和下载，CLI 的配置、查询与可恢复维护。
 
-- 图片生成按模型选择 DashScope、OpenAI Images、聊天生图或 Responses 协议，PNG/JPEG/WebP 按真实字节交付；
-- Artifact ID 看图、OCR、定位，以及“来源 Artifact → 聊天改图 → 新 Artifact”的关系与引用保护；
-- 共享视觉预算、长图分块、取消与完整终态检查；账号/模型输入预算只处理发送副本，定位坐标映射回原图；
-- 图片、视频、S2V、语音、转写与本地处理的 Core 任务链，独立视觉 CLI、HTML 截图及完整配置/查询/维护命令；
-- 工作台统一 Core/旧版全媒体分页过滤，跨页选择、ZIP 下载、详情及 Core 可恢复隔离/恢复；
-- 短时 429 琥珀冷却、明确额度或预算耗尽红色停用，以及既有提示词泡泡的按次规则和可编辑预览。
-
-CLI 与 DSH 共用 Task、Attempt、Artifact 和 Command Service；Host 负责会话、附件、浏览器与 UI。纯视觉和提示词预览消费共享 Model Ports，不自动创建媒体 Task/Artifact。受理未知不会自动重提，同一数据根只允许一个 writer。Core 与 Model Port 内部接口尚未冻结为公共 SDK，详见 [Core 迁移](DSH_CORE_MIGRATION.md)、[CLI](HEADLESS_CLI.md) 和 [Artifact Manifest](ARTIFACT_MANIFEST.md)。
-
-Node.js 最低版本保持 22.0.0，DSH 插件只声明支持准确的 `0.2.0-rc.2`。旧 DSH `>=0.1.2-rc.1 <0.1.3-0` 或 `0.1.5-rc.1` 继续固定安装 Iris `0.1.4`；其他宿主版本需独立验收。第二个真实 Host Adapter 完成并验收后再安排仓库与 npm 包更名，CLI、测试 fixture 与媒体 Provider 不算第二个 Host Adapter。
+DSH与CLI共用Task和Artifact，同一数据根只允许一个写者。纯视觉和提示词预览不自动创建媒体任务；Core与Model Port仍是内部契约。Node.js最低22.0.0，Iris0.2.4支持DSH rc.2或alpha.4，旧宿主固定Iris0.1.4，见 [兼容矩阵](DSH_COMPATIBILITY.md)。
 
 ## 近期优先：真实使用验收
 
-0.2.2采用明确功能能力：移除裸 DashScope 和名称自动赋能，保留功能入口、按功能分配的有序模型池及安全 failover。工作台提供明确功能标签设置；已有配置不自动迁移。Music 接入与相关网关排查暂缓，恢复前需取得可验证的真实音频。
-
-0.2.2 的 Core 可靠性已补齐 writer 意图与显式恢复证据，非图片交付复用文件接收和分块哈希；普通 writer 不自动抢占，未知/损坏现场继续拒绝。实现及边界见 [Core Runtime](CORE_RUNTIME_CONTRACT.md) 与 [Provider Adapter](PROVIDER_ADAPTER_CONTRACT.md)。
-
-0.2.2 的提示词一般功能已提供折叠五用途、原文/顺序保持的忠实整理、明确改写与单独获取/采纳的建议，保留自定义 v1 配置和旧 API。特殊功能待定义，独立提示词 CLI 和英文默认指令候选未接入；详见 [提示词优化系统](PROMPT_OPTIMIZER.md)。
-
-0.2.2 的生图尺寸归一、本地未受理校验及网络/正文诊断已实现，受理未知仍停止自动重提；不以本地代码保证公网线路稳定。见 [错误与取消传播](PROVIDER_ADAPTER_CONTRACT.md#错误与取消传播)。
+优先完善图片创作与配乐、短片素材准备等完整流程：复用已有作品、按需生成、试听或查看结果，再导出可继续处理的素材。分别交付音视频素材不等于自动混音成片。
 
-0.2.1 的发布检查覆盖完整测试、lint、实际 tarball、敏感信息、仓库外安装与跨平台 CI。服务层与包安装验收之外，近期优先补齐真实浏览器/移动端及异步重启使用证据。
+持续改进浏览器/移动端体验、模型配置说明和异步任务重启后的接管。音乐当前支持Chat Completions内嵌音频接口；新增音乐来源按具体协议与实际需求适配，不要求用户使用特定个人网关。
 
-工作台两轮功能已实现；第三轮仍需补浏览器/移动端的筛选、分页、跨页选择、识别、改图、下载及回收区使用验收，以及真实异步任务重启后的 CLI 接管。已有真实图片生成、按 ID 看图和聊天改图链路验证，完整会话与重启范围继续以 [验证说明](DSH_CORE_MIGRATION.md#验证证据与限制) 为准。上述变化纳入 0.2.2；完整工作台与重启范围的剩余验收仍保留。
+已有完整同步结果时，交付失败可以恢复缓存；缺少缓存的旧任务和过期URL不能保证恢复，详见 [同步交付恢复](SYNC_DELIVERY_RECOVERY.md)。作品管理和可恢复隔离见 [工作台作品管理](WORKBENCH_ARTIFACTS.md)。
 
-DSH 工作台与 Headless CLI 均复用 Core 的引用保护、可恢复隔离和恢复命令；legacy `outputs/` 的永久删除仍由旧工作台处理。两种删除语义与已实现的作品管理见 [工作台作品管理](WORKBENCH_ARTIFACTS.md)。
+DSH 工作台与 Headless CLI 共用 Core 的可恢复隔离和恢复入口，操作见 [CLI 管理](CLI_MANAGEMENT.md)。legacy `outputs/` 的删除仍永久生效；Core 回收区的删除可恢复，尚未提供永久 purge。两种行为在工作台分别显示，操作前应确认作品来源。
 
 ## 后续功能方向
 
 ### 后续 0.2.x
 
+- 图片创作的原图/新版并排对比与版本选择；0.2.4已提供持久图片导入和原生Qwen改图。
 - 适配其他协议，包括原生 Gemini、Fal 和后续 Replicate；网关兼容接口与原生协议接入分别验证；
-- Music 音乐生成：接入音乐生成模型，复用 Core 任务、Artifact 和作品管理；具体协议、模型与入口后续确定，不纳入 0.2.1；
+- 按实际需求增加音乐来源、可控参数和音视频衔接；已有音乐生成入口见 [音乐生成](MUSIC.md)；
 - 收藏、标签与工作台搜索（CLI 及工作台过滤、分页、显式选择/批量下载已完成）；
 - Artifact 关系边冻结 `retried-from` 类型，补全重试谱系（0.2.0 仅有 Task 级 `retriedFrom`）；
 - Core 隔离内容的永久 purge（0.2.1 已开放可恢复隔离/恢复，legacy 永久删除保持原行为）；
@@ -69,7 +60,7 @@ DSH 工作台与 Headless CLI 均复用 Core 的引用保护、可恢复隔离
 
 ## 质量要求
 
-- 已受理或受理未知的远端任务不得自动重提。
+- Core仅在明确未受理时切换候选；Music的有限502重发遵从本次配置并保留独立Task事实。
 - 同一数据根不得出现两个写者；reader 不产生隐式写入。
 - Core/CLI 在 DSH/Cordis 不可解析时仍能装载和运行本地动作。
 - Task、Attempt 和 Artifact 不保存凭据、私有 URL 或不必要的宿主绝对路径。

package/docs/SECURITY.md

@@ -23,8 +23,8 @@ API、SSE 和 Doctor 只返回凭据存在性或掩码提示。Provider 错误
 
 - 所有生成 Attempt 在网络副作用前落盘。
 - 只有供应商明确证明未受理时才允许自动 failover。
-- 500、超时、连接重置、响应丢失、轮询失败、事件失败和本地落盘失败都不能授权自动重提。
-- “重新观察”只查询已有远端任务；“重新交付”只查询并下载已成功产物。
+- 通用候选切换不因500、超时、连接重置、响应丢失、轮询失败、事件失败或本地落盘失败自动重提。Music入口按本次配置对明确HTTP502执行有限的新任务重发，保留原受理未知事实并可能消耗额外额度；设置 `retry_502: 0` 可关闭，见 [音乐生成](MUSIC.md)。
+- “重新观察”只查询已有远端任务；“重新交付”只消费已有成功结果。0.2.3 支持同步完整缓存的本地交付或原 URL 下载，异步保持 re-poll；均不重新生成。缓存缺失或损坏不授权自动重提，详见 [同步交付恢复](SYNC_DELIVERY_RECOVERY.md)。
 - “知情重试”必须单独确认可能重复任务或重复计费，并创建带 `retryOf/manualRetries` 关系的新 Task。创建后只归档原提醒，不改写原任务的未知事实；当前只对能从安全记录无损重建的文生图和文生视频开放，文件型输入和截断文本要求用户从原始输入重新发起。
 - “标为已读/恢复提醒”只操作有界的本地 `attentionEvents` 审计元数据，不发送网络请求，也不把用户处置等同于供应商已经受理。
 - Iris 当前没有凭空假设 DashScope 的远端取消协议。停止本地观察后若远端结果无法确认，状态保持 unknown。
@@ -37,6 +37,7 @@ API、SSE 和 Doctor 只返回凭据存在性或掩码提示。Provider 错误
 - legacy 任务与独立作品的媒体链接使用随机 128-bit 能力令牌。令牌应视为临时访问凭据，不应发布到公网。
 - Core 媒体路由 `/iris/api/core/artifact/<artifact_id>/media` **没有独立 token**。它使用随机 96-bit Artifact ID 作为不可猜测的持有者标识，并叠加默认回环/显式 trusted Host、浏览器 `Origin`/`Sec-Fetch-Site` 拒绝跨站、`Cross-Origin-Resource-Policy: same-origin`、`Referrer-Policy: no-referrer` 与每次 SHA-256 校验。任何能访问受信 Host 且持有 Artifact ID 的客户端都能读取对应媒体；`IRIS_TRUSTED_HOSTS` 不是身份认证。不要把 Core Artifact ID 或媒体 URL 发布到不受信任位置。
 - 清理任务元数据默认不删除作品；legacy 独立作品索引不保存 Prompt、Provider、Model 或任务关系；Core Manifest 保存中性元数据、SHA-256 和来源/派生关系，不保存凭据或私有下载 URL。
+- `delivery-cache/v0/` 是私有同步结果证据，不属于公共 Task/Artifact DTO：可能包含签名下载 URL 和媒体正文，不上传到 Issue，也不由媒体路由暴露。缓存随显式 Task 隔离/恢复，不自动删除；需要为额外磁盘占用留出空间。
 - legacy 删除单件作品、清空作品库或删除真正的孤儿文件都需要独立确认，会保留任务历史，但旧媒体链接将失效。0.2.1 Core 删除使用可恢复隔离，任务/产物引用会阻止删除；同时移除关联的已结束任务记录需要明确选择和确认，恢复不会覆盖冲突文件。见 [工作台作品管理](WORKBENCH_ARTIFACTS.md)。
 - 符号链接不会被私有树权限收紧逻辑跟随。Doctor 会把 Iris 数据根为符号链接视为硬错误。
 

package/docs/SYNC_DELIVERY_RECOVERY.md

@@ -0,0 +1,39 @@
+# 同步媒体结果的交付恢复
+
+Iris 0.2.3 支持从缓存恢复完整同步媒体结果。本地交付失败后，可沿原任务重新交付；Task/Artifact 格式和公开 HTTP 路径保持，不需要迁移旧数据。
+
+## 使用行为
+
+同步 Images、聊天生图、Responses、TTS 或音乐 返回完整结果后，本地写入失败仍记录 `accepted / succeeded / deliveryState=failed`。工作台“重新取回作品”和 CLI `task redeliver` 共用原 Task/Attempt 的恢复路径，不调用 submit、不创建新 Attempt。
+
+- 完整字节已缓存：仅做本地验证和交付，不访问 Provider，也不要求原供应商配置仍存在。
+- 完整响应只有 URL，或某些下载未完成：保留原来源，只下载缺少的产物；仍需原供应商/binding。它不 poll 或重新生成。
+- 异步任务：保持原来的远端 ID、一次 re-poll 与下载路径。
+- 缓存丢失、损坏、身份不匹配或字节校验失败：明确失败，不自动回退到下载或生成。成功后再次重新交付仍拒绝。
+
+全部字节已缓存时可以运行：
+
+```bash
+dsh-iris task redeliver task_0123456789abcdef01234567 \
+  --data-root /absolute/path/to/iris-data
+```
+
+需要访问原供应商取回 URL 时，另提供 `--provider-config /absolute/path/to/providers.json`。本地缓存恢复不增加第二次生成费用；网络下载仍受原服务权限、流量政策和 URL 有效期影响。
+
+## 持久化与中断边界
+
+`delivery-cache/v0/<task_id>/result.json` 是完整同步结果的提交证据，绑定原 Task、Attempt、Provider、模型及可选 binding，预留每件作品的稳定 Artifact ID。内联 base64 先解码为普通私有文件，结果文件最后原子发布；URL 仅保存于私有缓存。Task 只增加可选的 `deliveryCache: true`，不保存 URL 或媒体正文。
+
+URL 下载只有正常完成、实际文件大小与 Adapter 返回值一致并通过媒体类型检查后，才提交包含 size/SHA-256 的 payload 引用。未提交文件不冒充完整缓存；已提交字节在每次恢复时重新校验。缓存已提交但 Task 完成事实尚未落盘时，显式 Task 恢复可从同一 Attempt 的缓存补回成功事实，然后将中断交付置为 failed，等待用户显式重新交付。
+
+Artifact 写入采用缓存预留的 ID。已有完整对象、Manifest 或提交 Record 必须与恢复的内容和中性元数据一致；异常证据保留并拒绝覆盖。第一件作品成功而第二件失败、或作品全部提交而 Task ready 落盘失败时，恢复复用已提交作品，不创建重复 ID。reader、Doctor、查看任务和刷新作品均不触发恢复。
+
+该机制不保证在收到响应与成功保存缓存之间断电/进程退出时仍能找回结果；磁盘写入失败也可能使完整结果无法缓存。缓存发布失败仍保持已生成的 succeeded/failed 事实，不据此自动重提。旧同步失败任务没有保留下来的结果时，不能追溯恢复。签名 URL 过期后也不能保证下载可继续。
+
+## 隐私与生命周期
+
+缓存目录/文件在 POSIX 上分别为 0700/0600。签名 URL、完整媒体和结果来源只在私有缓存中，HTTP DTO、Task JSON、Artifact Manifest、诊断及普通日志不包含这些值。缓存校验不跟随目录或文件符号链接。
+
+完整与未提交缓存不因失败、取消、重启或交付成功而自动删除，因此会占用额外磁盘。缓存随显式 Task 隔离一起移入原可恢复事务，恢复时一并恢复；删除 Task 不连带删除作品。未完成交付的预留 Artifact ID 参与引用保护，既有清理不会接回或清掉它们。不引入后台 TTL、自动清理或新的永久删除入口。
+
+相关契约：[Core Runtime](CORE_RUNTIME_CONTRACT.md)、[Headless CLI](HEADLESS_CLI.md)、[安全边界](SECURITY.md)。

package/docs/TASK_SEMANTICS.md

@@ -116,14 +116,14 @@ Task v2 至少包含以下事实轴；字段值采用可序列化的 snake_case
 
 结构化错误至少应区分 stage、category、HTTP 状态、供应商错误码、受理状态和可安全展示的信息。任务、Attempt、事件与日志不得保存 API Key、Authorization 头、完整请求体、私有绝对路径或带临时签名的结果 URL。
 
-错误是否“可重试”与是否“允许自动重新提交”是两个不同问题。前者描述技术性质，后者只能由 `acceptance=not_accepted` 授权。
+错误是否“可重试”与Core是否“允许自动切换候选”是两个不同问题。前者描述技术性质，后者只能由 `acceptance=not_accepted` 授权。Music入口另外按本次配置对明确HTTP502执行有限的新Task重发，保留原任务的 `unknown` 事实；这不改变Core候选切换规则，详见 [音乐生成](MUSIC.md)。
 
 ## 10. 事件与 UI
 
 - 每次 Task v2 持久化变更得到单调递增的 Task `revision`。完整状态快照另带进程 `stateEpoch/stateRevision`；客户端拒绝同一 epoch 内迟到的旧快照，SSE 重连后以持久化全量快照收敛。
 - SSE 慢消费者进入背压时只保留最新待发快照，避免旧状态排队造成内存增长或视觉倒退。
 - UI 应把事实映射成“排队中、运行中、观察暂停、需要确认、结果待取回、已完成、明确失败、已取消”等人类状态，不应在手机界面直接堆叠所有内部字段。
-- `acceptance=unknown`、`cancelState=unknown` 和 `deliveryState=failed` 必须提供明确的人工接管入口；任何可能再次计费的操作都需要单独确认。
+- `acceptance=unknown`、`cancelState=unknown` 和 `deliveryState=failed` 必须提供明确的人工接管入口；手动重新生成需要逐次确认潜在费用。Music入口内部的有限502重发按本次配置执行。
 - 提醒处置与任务事实正交：标为已读只把任务移出主动提醒队列，恢复提醒只重新开放该队列；两者都不得修改受理、观察、结果、交付或取消事实。
 - 知情重试创建并关联新 Task 后，原提醒自动记录为“已通过重试处理”。原任务保留原始未知事实和审计记录，但不继续产生重复角标；用户可从历史详情恢复提醒。
 
@@ -138,11 +138,11 @@ Task v2 至少包含以下事实轴；字段值采用可序列化的 snake_case
 
 故障注入至少覆盖：请求发送前失败、提交响应丢失、获得远端 ID 后本地落盘失败、轮询 429/500/超时、远端成功后下载失败、取消响应丢失，以及 `submitting/accepted/running` 阶段的进程退出与恢复。
 
-每个场景必须同时断言最终事实字段和供应商提交调用次数。对于 `accepted` 或 `unknown`，自动重复提交次数必须为 **0**。
+每个场景必须同时断言最终事实字段和供应商提交调用次数。Core候选切换遇到 `accepted` 或 `unknown` 时，自动重复提交次数必须为 **0**；Music功能层的有限502重发单独验证新Task关系与次数。
 
 ## 13. 本版非目标
 
 - 不在语义冻结阶段重写全部任务存储或 UI。
 - 不新增 Gemini、Fal、Replicate 等供应商分支。
 - v0.1.3 包含零网络、可独立运行的离线 Doctor v0 与最薄 CLI；v0.1.4 已接入 Host/Provider Adapter、Host Doctor 和不含谱系的作品库 v0。0.2.0 已实现 [Core Artifact Manifest](ARTIFACT_MANIFEST.md)，0.2.1 补齐共享 CLI/DSH 消费与编辑关系；两种存储保持独立。
-- 不用更多自动重试换取表面成功率。
+- 通用恢复流程不增加无界自动重试。

package/docs/VISION_CLI.md

@@ -95,9 +95,9 @@ dsh-iris vision summarize \
 }
 ```
 
-省略 `--model-ref` 时按 `assignments.vision` 排序，再以配置模型池补齐。只有本地不可用、明确拒绝或正常空正文才允许下一候选；截断、未知终态、收到正文后的失败、取消和超时停止调用。显式 `--model-ref providerId::modelId` 严格只绑定该账号与模型，失败不会替换；新视觉命令不接受裸模型名。模型需启用并声明 `vision` 能力，未配置时直接失败。当前自持视觉端口支持 OpenAI-compatible Chat Completions SSE，不追加 DSH 宿主候选。
+0.2.4省略 `--model-ref` 时仅按 `assignments.vision` 名单排序，不补入模型池。只有本地不可用、明确拒绝或正常空正文才允许下一候选；截断、未知终态、收到正文后的失败、取消和超时停止调用。显式 `--model-ref providerId::modelId` 须已分配且只绑定该账号与模型，失败不会替换；新视觉命令不接受裸模型名。模型需启用并声明vision能力，未配置时直接失败。自持视觉支持OpenAI-compatible Chat Completions SSE；CLI不能执行DSH宿主视觉资源。见 [功能模型分配](FUNCTION_MODEL_ASSIGNMENTS.md)。
 
-成功 JSON 携带实际 `modelRef`、`selectionReason`（`explicit` / `assignment` / `pool`）、模型身份、正常终态及可用的 usage。OCR 的实际选择保留在每个成功块上。配置凭据、端点和原始错误响应不会出现在诊断中；模型回答和 OCR 正文是用户内容。
+成功JSON携带实际`modelRef`、`selectionReason`（`explicit` / `assignment`）、模型身份、正常终态及可用usage；旧记录的`pool`来源仍可读取。OCR实际选择保留在每个成功块上。配置凭据、端点和原始错误响应不会出现在诊断中；模型回答和OCR正文是用户内容。
 
 ## 输出、预算与退出码
 
@@ -127,6 +127,6 @@ dsh-iris vision summarize \
   --input '{"video_path":"/absolute/path/clip.mp4","transcribe":true,"transcribe_model_ref":"aliyun::qwen-audio-3.0-asr-flash-filetrans"}'
 ```
 
-配置需声明 `transcribe` 模型，并使用既有上传型转写协议（当前 DashScope）。省略 `transcribe_model_ref` 时沿用转写 assignment/模型池，显式指定时只使用该项；不能同时提供 `transcribe_text`。本次命令观察已受理的同一 Core Task，读取成功的文本 Artifact 后摘要；普通转写失败则返回画面摘要并将 `transcription.status` 标为 `failed`。无音轨标为 `no_audio`；取消/超时直接终止摘要，已经提交的转写任务保留事实，可按 [Headless CLI](HEADLESS_CLI.md) 的任务命令继续检查、观察或重新取回，不会自动重提。
+配置需声明并分配`transcribe`模型，使用既有上传型转写协议（当前DashScope）。省略`transcribe_model_ref`时只使用转写名单，显式指定须属于名单且只使用该项；不能同时提供`transcribe_text`。本次命令观察已受理的同一Core Task，读取成功的文本Artifact后摘要；普通转写失败则返回画面摘要并将`transcription.status`标为`failed`。无音轨标为`no_audio`；取消/超时直接终止摘要，已提交任务保留事实，可按 [Headless CLI](HEADLESS_CLI.md) 继续检查、观察或补交付，不会自动重提。
 
 文件输入的纯视觉命令不要求数据根，不创建 Core Runtime、Task 或 Artifact；使用图片/帧 Artifact ID 时只使用显式数据根的 reader，主动音轨转写时才持有 writer 租约。独立提示词优化入口不属于本次交付。

package/docs/VISION_MODEL.md

@@ -8,7 +8,7 @@ Agent 的 `iris_look_at_image` / `iris_relook_attachment`、工作台的看图/
 
 `iris_look_at_image` 与看图动作现可用 `artifact_id` 代替 `image_path`，直接读取当前 DSH profile 的 Core 图片，二者必须二选一。图片的 MIME、原字节和内容哈希由共享读取器核对，不要求原文件或临时导出、不写入 Core；生成图片、HTML 截图、裁剪、视频帧均可使用。自持模型成功时无需为 Core 输入另存 DSH 附件；DSH 候选仍通过既有附件桥接。工具文字保留 Core ID，动作 JSON 带 `artifactId`。工作台原表单继续输入文件路径，动作 API 可直接传 ID。独立 CLI 的同一用法见 [视觉 CLI](VISION_CLI.md)。
 
-Iris 按已配置的视觉模型顺序选择自持后端，最后考虑 DSH 默认视觉模型。DSH 必须明确提供 Provider、模型及图片输入能力；默认文本模型、未知元数据和身份漂移在生成前拒绝。自持成功时不查询 DSH 元数据或为回退额外保存附件。
+0.2.4按视觉分配名单选择后端，不补入模型池。DSH当前默认模型须作为 `host:current-vision` 明确加入并排序，不再自动追加；临时指定只调用该项。DSH必须明确提供Provider、模型及图片输入能力；默认文本模型、未知元数据和身份漂移在生成前拒绝。自持成功时不查询DSH元数据或额外保存附件。升级变化见 [功能模型分配](FUNCTION_MODEL_ASSIGNMENTS.md)。
 
 只有明确认证/权限拒绝、速率/额度拒绝、正常完成但正文为空，以及本地能力不可用，才允许进入下一个候选。已收到部分正文、截断、工具调用、内容阻断、网络/协议错误、取消或超时都会停止操作。正常空结果后的切换可能已经产生上一模型的费用。
 

package/docs/WORKBENCH_ARTIFACTS.md

@@ -2,6 +2,8 @@
 
 状态：**Iris 0.2.2**。
 
+0.2.4新增 [图片导入](IMAGE_IMPORT.md)：作品区展开“导入图片”，选择文件后点击“保存到作品”。导入图片保留原字节，标为“导入图片”，可直接看图、改图或下载；单纯上传的临时副本与保存后的作品分开。
+
 Iris 工作台的作品库统一展示 Core 和旧版作品，包括图片、视频、音频和文本。默认按时间倒序排列，每页 24 个；使用上一页、下一页浏览全部作品。媒体类型、作品来源和产物类型可组合筛选，匹配总数与 Core/旧版计数均按当前筛选计算。切换筛选回到第一页，刷新保留页码和筛选；尾页因作品数量减少而超界时，回到最后一页。
 
 Core 的原始输入 `host-input` 不出现在作品库。不可读取的 Core 条目局部跳过并提示；Core 整体暂时不可用时仍可浏览旧版作品，此时计数只含可读取来源。图片提供预览，视频、音频提供播放器，文本可以打开原文件。
@@ -22,9 +24,9 @@ Core 图片卡的“看图”“OCR”按钮直接读取原 Artifact。点击即
 
 ## 从图片卡改图
 
-Core 静态 PNG/JPEG/WebP 图片卡增加“改图”。填写修改指令，可显式选择支持聊天生图的模型，或按现有候选顺序选择。面板只读取模型配置，不自动实测；只列出 `openai-chat-images` 生图模型，冷却/额度耗尽项不可选择。
+Core静态PNG/JPEG/WebP图片卡提供“改图”。填写修改指令，可选择已分配的带图编辑模型，或按当前生图名单顺序选择。面板只读取配置，不自动实测；列出openai-chat-images及0.2.4接入的DashScope Qwen原生改图模型，冷却/额度耗尽项不可选择。具体型号见 [CLI改图](CLI_MANAGEMENT.md#artifact-聊天改图)。
 
-点击“生成修改版”才调用模型，原图保留，修改版作为关联原图的新 Core 作品显示。成功后提供新 Artifact 链接、刷新作品库，保留筛选和页码；新作品可继续看图/OCR、编辑、下载和管理。来源最多 20 MiB；大图只处理发送副本，预算设置也可在聊天生图模型行编辑。
+点击“生成修改版”才调用模型，原图保留，修改版作为关联原图的新 Core 作品显示。成功后提供新 Artifact 链接、刷新作品库，保留筛选和页码；新作品可继续看图/OCR、编辑、下载和管理。来源最多 20 MiB；大图只处理发送副本，预算设置也可在支持改图的模型行编辑。
 
 “停止等待”、关闭面板或切换分析会中止在途等待，迟到响应不覆盖新面板。远端可能已受理，须在任务区查看结果，不会自动再次生成。编辑任务的手动重试要求重新输入修改指令并确认原图 ID；只支持一次带图请求，不保存聊天历史或提供蒙版。详见 [CLI 改图](CLI_MANAGEMENT.md#artifact-聊天改图)。
 

package/docs/releases/0.2.3.md

@@ -0,0 +1,54 @@
+# Iris 0.2.3：音乐创作、Agent Skills 与交付恢复
+
+0.2.3 加入独立音乐生成、三项随包 Agent Skills 和同步媒体结果恢复，并完善提示词预览、改写输出与配置反馈。
+
+## 音乐生成
+
+为音乐功能明确分配模型后，可通过 DSH 对话、工作台或 `dsh-iris run music` 生成 MP3/WAV，保存为音频作品并试听、下载或导出。音乐与 TTS 分别配置，多步骤创作按需加入配乐。
+
+当前支持 **Chat Completions（内嵌音频）**：服务在聊天响应正文中返回音频 data URL。不限定供应商名称或模型 ID，也不等同于支持所有 OpenAI 兼容音频接口或 Google 原生音乐 API。
+
+音乐入口默认对明确 HTTP 502 额外重试两次，可设置 `retry_502: 0` 关闭。每次重发创建关联的新任务，可能消耗额外额度；其他错误不触发这项重试。曲长、歌词、人声等通过描述表达，精确控制取决于实际模型。详见 [音乐生成](../MUSIC.md)。
+
+## Agent Skills
+
+- `iris-use`：单步生成、改图、视觉、语音、音乐、任务查询和作品交付。
+- `iris-compose-media`：图片版本、视频素材、旁白、S2V 和可选配乐等多步骤创作。
+- `iris-verify-ui`：按用户目标检查界面，报告通过、部分通过、失败或证据不足。
+
+三项 Skill 共用能力与产物说明，指导 Agent 复用已有作品、区分任务查询与恢复，并在需要文件输入时先导出 Core 音频。宿主诊断检查 16 个工具与三项 Skill。
+
+## 同步交付恢复
+
+供应商已返回完整结果但本地交付失败时，工作台“重新取回作品”和 CLI `task redeliver` 可沿原任务使用私有缓存恢复，无需重新生成。完整字节缓存可离线交付；只有 URL 时仍需原供应商权限与有效链接。
+
+没有保留完整结果的旧任务无法追溯恢复。缓存会占用额外磁盘，并随显式任务隔离和恢复管理。详见 [同步交付恢复](../SYNC_DELIVERY_RECOVERY.md)。
+
+## 提示词编辑
+
+- 再次优化失败或取消时保留已有预览和手工编辑，迟到结果不覆盖等待期间的新编辑。
+- 单片段忠实整理直接保留原文，无需调用模型；可查看实际调用的指令和模型选择原因。
+- 改写返回正文，拒绝可识别的新增 JSON 外壳、外层围栏或整体字符串包装；原稿已有的合法格式保留，结果仍需查看对照。
+- 配置异常说明默认值和原文件保留状态；“仅恢复默认指令”保留模型、生成参数和入口开关，“恢复全部设置”重置完整配置。
+
+自定义 v1 配置继续使用，升级不会自动替换其指令。详见 [提示词优化](../PROMPT_OPTIMIZER.md)。
+
+## 升级
+
+DSH `0.2.0-rc.2` 的 Web profile：
+
+```bash
+dsh plugin --profile web add @mokuyoaxis/dsh-iris@0.2.3
+dsh web
+```
+
+独立 CLI：
+
+```bash
+npm install @mokuyoaxis/dsh-iris@0.2.3
+npx dsh-iris --help
+```
+
+升级后重启 DSH 后端并刷新页面，确认宿主诊断中的客户端与服务端版本一致，再为音乐分配模型。最低 Node.js 为 22.0.0；DSH 插件仅支持准确的 `0.2.0-rc.2`，旧宿主继续固定使用 Iris 0.1.4。配置、Task/Artifact 版本与生产依赖保持。
+
+本版未提供自动混音成片、批量音乐调度或 Google 原生音乐 Adapter。完整步骤见 [用户指南](../../user_guide.md)。