@mokuyoaxis/dsh-iris 0.2.1 → 0.2.3

package/docs/PROMPT_OPTIMIZER.md

@@ -1,10 +1,36 @@
 # 提示词优化与规则组装
 
-状态：**Iris 0.2.1**。本版提供按次规则、只组装和可编辑预览；后续独立提示词优化系统另行安排。
+本文面向 Iris 0.2.3，介绍对话草稿的忠实整理、明确改写、可选建议和零模型调用的规则组装。结果先进入预览，写回不会自动发送。
+
+## 用途选择
+
+面板将一般功能放在可折叠卡片中，按“通用、画图、改图、视频、数字人”选择用途。当前草稿、本次规则、操作、可编辑结果和对照属于同一功能区域；折叠不清空选择、规则或结果，也不触发模型请求。指令与模型设置独立折叠，可在调用前查看当前系统指令和目标模板。浏览器原生对话框在顶层显示，避免宿主悬浮按钮遮住结果。桌面和窄屏使用同一流程，支持点击背景或 Escape 关闭、焦点恢复与对话框内键盘焦点循环。
+
+| 目标 | 标识 | 内置优化重点 |
+|---|---|---|
+| 通用 | `general` | 目标、背景、约束、输出和验收 |
+| 画图 | `image` | 主体、场景、构图与已指定风格 |
+| 改图 | `image-edit` | 明确修改范围，保持原图其余特征 |
+| 视频 | `video` | 动作先后、镜头与连续性 |
+| 数字人 | `s2v` | 已有首帧与音频下的人物动作、表情和镜头 |
+
+默认指令参照项目 Skills 的职责、目标、输入、保持/改变和输出组织方式，并使用实际 Iris 工具语义。S2V 指已有首帧加音频的数字人视频。优化器仍只编辑草稿，不读取图片/音频、不生成媒体，也不冒充已经检查素材；具体方位、数量、颜色、数值、引用原文和否定条件必须保留。模型实际是否遵守仍需用户检查原文对照。
+
+v1 配置兼容：增加 `targets["image-edit"]`，旧配置缺少此项时只在内存补齐，不自动重写文件。既有 systemPrompt、目标模板与模型路由优先保留，包含用户自定义 s2v 文本；用户显式恢复默认后才替换为新的内置指令。没有新增规则持久格式、特殊功能或 CLI。
+
+### 编辑方式
+
+新界面默认选择 **忠实整理**：模型只选择相邻原文片段之间的分段位置，程序从原稿拼回正文。每个片段必须恰好出现一次、句序保持，遗漏、重复、调换或新增内容都会拒绝。条件、动作先后、引文、代码和复杂格式采用保守分段；已有完整文本允许保持原样。忠实整理保证原文片段和顺序，不是自动证明所有排版变化的语义完全相同。
+
+需要等义润色或明确改变某个项目时，选择 **改写表达** 并填写本次改写规则。例如“只把白色丝袜改为黑色，其余保持”授权改变指定颜色；其余事实和否定继续保留。忠实整理不会静默执行或丢弃改写规则。改写表达仍是模型生成文字，新增含义与遗漏需查看对照，不能以结果非空证明忠实。
+
+结果中的 **可选补充与待确认** 独立于正文。点击“获取补充建议”才新增一次模型调用，不自动生成第二轮；默认未勾选，勾选也不改正文，点击“采纳所选建议”后才加入可编辑预览。采纳与撤回不调用模型、不直接写回或发送。手动修改预览会清除旧建议绑定，避免撤回旧快照覆盖你的编辑；再次获取建议针对当前文字。失败、取消、会话切换或请求期间文字变化不会把迟到建议写入预览。
+
+只组装仍为零模型调用。旧后端未声明编辑能力时保留原“智能优化”流程，不发送其不支持的新策略。会话/fixed 模型选择保持，不因为选择“画图”用途就进入生图模型池，也不硬编码供应商默认模型或失败后自动切换。
 
 ## 使用
 
-在 DSH 输入框写入未发送的纯文本草稿，打开 🫧，选择通用、图片、视频或首尾帧视频目标。
+在 DSH 输入框写入未发送的纯文本草稿，打开 🫧 并选择用途。0.2.2 提供五用途和一般功能新布局；旧 0.2.1 的四目标调用仍兼容。
 
 “本次规则”可填写以下内容；留空表示不选择。规则只在当前组件中保留，刷新后重置，不改写已有 `prompt-optimizer.json`。
 
@@ -14,10 +40,12 @@
 | 输出前缀 | 模型改写完成后，程序原样加入开头 | 原样加入原稿开头 |
 | 输出后缀 | 模型改写完成后，程序原样加入末尾 | 原样加入原稿末尾 |
 
-智能优化进行一次文本模型生成；只组装不读取模型路由或优化配置、不调用模型，在 Host 文本服务不可用时仍可使用。只组装不会套用目标模板或自动润色原稿。规则之间与正文之间用两个 LF 分隔；输出规则原文与只组装的草稿空白保持不变。
+需要模型的优化进行一次文本生成；单片段忠实整理直接保留原文，不调用模型。只组装不读取模型路由或优化配置、不调用模型，在 Host 文本服务不可用时仍可使用。只组装不会套用目标模板或自动润色原稿。规则之间与正文之间用两个 LF 分隔；输出规则原文与只组装的草稿空白保持不变。
 
 结果先进入可编辑预览。可以查看原文、本次参与规则、实际模型与思考策略，以及折叠相同首尾后的中间替换区。这是文本改动对照，不代表模型解释了每处改动的原因。手动编辑也会更新对照；复制和写回使用编辑后的文字。
 
+改写结果会在拼接前后缀之前检查未由原稿/明确改写规则提供的新链接、媒体标记和明显的执行完成/拒绝回复；已有合法链接、原文引用及只组装保留。忠实整理与建议模式另检查专用 JSON 形状、片段序列或建议字段，未授权正文不能混入。检查不构成任意自然语言的完整语义证明。拒绝后不自动重试、切换模型或写回；上游可能已经处理请求，不能据此推定没有计费或媒体副作用。
+
 写回不会自动发送。出现新草稿时先确认替换；出现结构化 `@`、`/` 引用或忙碌状态时拒绝写回。切换会话清除旧预览并取消在途操作，即便两边草稿文本相同。取消、关闭或卸载会传递 abort，迟到结果不能恢复旧预览或覆盖新操作。恢复原文只恢复本次操作前的文字，不自动恢复附件/结构化引用。
 
 ## 规则来源与限制
@@ -34,14 +62,54 @@
 
 取消表示本地停止等待并向底层传递信号，不保证第三方远端执行或计费已停止。失败、工具调用、未知终态和部分正文不会作为完整结果交付。
 
-## 开发边界
+## 预览、配置与恢复
+
+再次优化失败或取消时，已有预览和手工编辑会保留；等待期间继续编辑，新结果不会覆盖这些改动。单片段忠实整理会显示“无需分段，未调用模型”。需要模型时，预览显示实际路由及选择原因，并可展开发送给 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 只组装只提交输出规则。
 
-配置 API 在配置对象外返回 `capabilities: { rules: true, assemble: true }`。新客户端读到明确能力才启用规则和只组装按钮，防止旧后端忽略 mode 并意外调用模型。能力字段不进入配置导出文件。
+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,6 +1,8 @@
 # Provider Adapter v0 生命周期契约
 
-状态：**Iris 0.2.1；沿用 v0 生命周期内部契约。** 0.1.4 建立六操作契约，0.2.0 增加可选输入准备能力，0.2.1 增加聊天/Responses 生图及模型级协议覆盖。 这是 Iris Core 模块与供应商协议实现之间的内部边界，尚未冻结为第三方公开 SDK。DashScope 与 OpenAI Images 兼容实现通过同一套零网络 conformance runner；聊天/Responses 图片协议另有提交、交付与 CLI 回归。
+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 回归。
 
 ## 目标与依赖方向
 
@@ -74,6 +76,8 @@ Core Attempt 持久化 `providerId::modelId` 复合身份，具体 Provider Adap
 
 `download` 物化已经确认成功的产物：`remote-url` 执行下载，`inline-base64` 直接写入私有 staging。inline 正文只作为 non-enumerable 的短生命周期字段传给 Runner，不进入 JSON、Task 或 Manifest。生图产物按真实字节校验 PNG/JPEG/WebP，保留字节、MIME、后缀和哈希。物化失败只能改变交付状态，不能触发生成重提。OpenAI Images、聊天生图与当前 Responses 生图切片均同步返回图片，所以 `poll` 与 `cancel` 显式 unsupported；Responses 纯文字、缺图或未完成结果保留受理未知，不扫描其他接口。DashScope 当前没有经过验证的远端取消接口，因此 `cancel` 同样显式 unsupported，而不是伪装取消成功。
 
+0.2.2对视频、音频及文本 staging 复用 Artifact Store 的文件复制接收路径，哈希仍按 1 MiB 分块计算，不再为落库整文件 `readFileSync`。Profile、大小核对、元数据、关系边和交付失败事实保持。图片仍读取字节验证真实格式；inline 响应的解码以及工作台预览/ZIP 等读取路径仍可能使用完整 Buffer，本改动不声称端到端流式传输。
+
 聊天改图仍使用 `capability:image`：Runner 从当前 Core 校验并读取来源 Artifact，短生命周期 `input.image:{bytes,mediaType}` 与 `prompt` 交给聊天适配器。适配器按实际模型 `visionInput` 准备副本，HTTP 用户消息使用 `text` 与 `image_url` data URL。普通 Images/Responses 不接受此输入，编辑候选链预先过滤协议。Task 仅保存可选 `sourceArtifactId`，用于未知/失败任务的来源保护和交付时写入新 Artifact 的 `derived-from`；旧记录无需迁移，重试仍重新提供输入。来源或编辑输入预算失败发生在 HTTP 之前。
 
 ## 可选输入准备与上传边界
@@ -92,14 +96,20 @@ Host 和 CLI 通过 `prepareProviderInput(adapter, { model, filePath, signal?, t
 
 `submit` 抛错由统一调用器转换成保守四态；`cancel` 抛错转换为 `unknown`；`discover/poll/download` 抛出脱敏的 `ProviderContractError`，由各自调用方应用重试和事实规则。
 
+0.2.2的生图传输同时覆盖请求与响应正文读取。包装的网络异常在尚未取得响应头时标记 `stage=submit`，取得响应头后正文读取失败时标记 `stage=response`；已知网络超时码归类 timeout，两者都保留 `acceptance=unknown`，不凭 HTTP 200 响应头断言完整生成成功。可用的底层网络错误码放入既有 `providerCode` 字段，提示区分 DNS、TLS、连接建立、等待响应头及正文读取；没有明确错误码时只描述实际阶段。原生 AbortError、TimeoutError 或 ABORT_ERR 保留原异常及取消/超时分类，未附加正文读取阶段证据时沿用提交调用的阶段。完整 HTTP 业务响应仍按鉴权、限流/额度、参数或供应商错误分类，明确分类不被错误文字中的 timeout 覆盖。
+
+本地尺寸校验使用 `validate / invalid_request / not_accepted`，在 HTTP 前失败。分隔符按协议归一，DashScope 多模态只执行已有证据的总像素范围，不推断单边上限；OpenAI 兼容网关的数值集合留给上游。`retryable` 表示错误类别可重试，不授权重提受理未知的收费请求；Core 的受理门继续先于候选切换。DSH 动作错误附带同一脱敏 `safeMessage`，不输出原始 cause、正文或凭据。
+
 ## 当前内置实现
 
 | 协议 | discover | submit | poll | cancel | download | mapError |
 |---|---:|---:|---:|---:|---:|---:|
 | DashScope | 支持（`/api/v1/models` 分页与能力元数据） | 图片/视频/TTS/转写 | 图片/视频/转写 | 显式不支持 | 支持 | 支持 |
 | OpenAI Images 兼容 | 支持 | 同步图片 | 显式不支持 | 显式不支持 | 支持 | 支持 |
+| OpenAI 聊天生图兼容 | 支持 | 同步图片/单来源改图 | 显式不支持 | 显式不支持 | 支持 | 支持 |
+| OpenAI Responses 生图兼容 | 支持 | 同步单图 | 显式不支持 | 显式不支持 | 支持 | 支持 |
 
-本表只描述协议生命周期，不扩大 0.1.4 的供应商范围。Gemini、Fal 与 Replicate 仍在 0.2.x 路线中。
+本表描述已实现的协议生命周期；网关 Gemini 模型可以使用兼容协议，不代表原生 Gemini Adapter 已接入。原生 Gemini、Fal 与 Replicate 仍在后续路线中。
 
 ## conformance runner
 

package/docs/PROVIDER_HEALTH.md

@@ -1,6 +1,6 @@
 # Provider 与能力健康状态
 
-状态：**Iris 0.2.1**。新增短时限流冷却与明确额度/预算耗尽停用，沿用既有持久健康证据。
+状态：**Iris 0.2.2**。新增短时限流冷却与明确额度/预算耗尽停用，沿用既有持久健康证据。
 
 Iris 用持久化证据描述“当前配置是否存在、最近是否实际成功、是否出现明确凭据失败”。它不是后台监控，也不等同于 Host Doctor。
 

package/docs/ROADMAP.md

@@ -1,38 +1,35 @@
 # 路线图
 
-Iris 正从 DSH 媒体插件演进为可独立运行、可接入不同 Agent 宿主的媒体生产核心。本文列当前状态与后续方向；版本变化见 [变更记录](../CHANGELOG.md)。
+Iris 的方向是本地优先、Agent 可调用的多模态创作工作台。用户可从描述或已有素材出发，生成、修改、选择和交付作品。本文介绍当前能力与后续方向；版本变化见 [变更记录](../CHANGELOG.md)。
 
 ## 当前状态
 
-当前版本为 **Iris 0.2.1**。包名保持 `@mokuyoaxis/dsh-iris`，同时提供 DSH 插件与无 DSH 的 Headless CLI。功能范围见 [0.2.1 发布说明](releases/0.2.1.md)。
+当前版本为 **Iris 0.2.3**。包名为 `@mokuyoaxis/dsh-iris`，同时提供 DSH 插件与独立 CLI，详见 [0.2.3 发布说明](releases/0.2.3.md)。
 
-0.2.1 的更新重点是 **完成 OpenAI 兼容图片与视觉工作流**：生成图片 → Core Artifact → 按 ID 看图/OCR → 聊天改图 → 新 Artifact，CLI 与 DSH 工作台共用同一链路。本版已实现以下能力：
+- 图片生成、Artifact ID 看图/OCR/定位和聊天改图，支持按模型配置图片协议。
+- 视频、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，DSH插件支持准确的 `0.2.0-rc.2`，旧宿主使用固定的Iris `0.1.4`。
 
 ## 近期优先：真实使用验收
 
-0.2.1 的发布检查覆盖完整测试、lint、实际 tarball、敏感信息、仓库外安装与跨平台 CI。服务层与包安装验收之外，近期优先补齐真实浏览器/移动端及异步重启使用证据。
+优先完善图片创作与配乐、短片素材准备等完整流程：复用已有作品、按需生成、试听或查看结果，再导出可继续处理的素材。分别交付音视频素材不等于自动混音成片。
+
+持续改进浏览器/移动端体验、模型配置说明和异步任务重启后的接管。音乐当前支持Chat Completions内嵌音频接口；新增音乐来源按具体协议与实际需求适配，不要求用户使用特定个人网关。
 
-工作台两轮功能已实现；第三轮仍需补浏览器/移动端的筛选、分页、跨页选择、识别、改图、下载及回收区使用验收，以及真实异步任务重启后的 CLI 接管。已有真实图片生成、按 ID 看图和聊天改图链路验证，完整会话与重启范围继续以 [验证说明](DSH_CORE_MIGRATION.md#验证证据与限制) 为准。提示词优化系统的后续设计单独安排，不扩入本次发布。
+已有完整同步结果时，交付失败可以恢复缓存；缺少缓存的旧任务和过期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
 
 - 适配其他协议，包括原生 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 永久删除保持原行为）；
@@ -61,7 +58,7 @@ DSH 工作台与 Headless CLI 均复用 Core 的引用保护、可恢复隔离
 
 ## 质量要求
 
-- 已受理或受理未知的远端任务不得自动重提。
+- Core仅在明确未受理时切换候选；Music的有限502重发遵从本次配置并保留独立Task事实。
 - 同一数据根不得出现两个写者；reader 不产生隐式写入。
 - Core/CLI 在 DSH/Cordis 不可解析时仍能装载和运行本地动作。
 - Task、Attempt 和 Artifact 不保存凭据、私有 URL 或不必要的宿主绝对路径。

package/docs/SECURITY.md

@@ -1,6 +1,6 @@
 # Iris 安全边界
 
-状态：Iris 0.2.1 安全边界。安全目标是避免凭据泄露、路径越权、跨站写入和因错误重试造成重复计费；Iris 与 DSH 仍是本机同一信任域内的预览软件，不构成多租户安全边界。
+状态：Iris 0.2.2 安全边界。安全目标是避免凭据泄露、路径越权、跨站写入和因错误重试造成重复计费；Iris 与 DSH 仍是本机同一信任域内的预览软件，不构成多租户安全边界。
 
 ## 信任模型
 
@@ -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

@@ -1,6 +1,6 @@
 # Iris Task/Attempt v2 语义契约
 
-状态：**v0.1.3 已实现；v0.1.4 Host/Provider Adapter、Host Doctor 与作品库 v0 已接入。** Task v2 已覆盖图片、视频、转写与 TTS，包括同步/异步、上传/提交、混合协议候选、工作台稳定用户态、状态流防倒退、重新观察、重新交付、提醒已读/恢复和知情人工重试。本文的 Task v2 字段描述 legacy 任务，不等同于 Core DTO。作品库 v0 分离旧本地作品生命周期；0.2.0 已实现 Core Task/Attempt 与 Artifact Manifest，0.2.1 的媒体、聊天改图和维护入口共享 Core 事实，见 [Core Runtime](CORE_RUNTIME_CONTRACT.md)。
+状态：**v0.1.3 已实现；v0.1.4 Host/Provider Adapter、Host Doctor 与作品库 v0 已接入。** Task v2 已覆盖图片、视频、转写与 TTS，包括同步/异步、上传/提交、混合协议候选、工作台稳定用户态、状态流防倒退、重新观察、重新交付、提醒已读/恢复和知情人工重试。本文的 Task v2 字段描述 legacy 任务，不等同于 Core DTO。作品库 v0 分离旧本地作品生命周期；0.2.0 已实现 Core Task/Attempt 与 Artifact Manifest，0.2.2 的媒体、聊天改图和维护入口共享 Core 事实，见 [Core Runtime](CORE_RUNTIME_CONTRACT.md)。
 
 ## 1. 为什么需要 v2
 
@@ -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

@@ -1,6 +1,6 @@
 # 独立视觉 CLI
 
-状态：**Iris 0.2.1**。安装 `npm install @mokuyoaxis/dsh-iris@0.2.1` 后运行 `npx dsh-iris ...`，或从源码运行 `node bin/dsh-iris.js ...`。需要 Node.js ≥ 22、已有依赖 Sharp；从视频文件抽帧还需要 PATH 中的 ffmpeg、ffprobe，复用既有 Core 帧不需要。
+状态：**Iris 0.2.2**。安装 `npm install @mokuyoaxis/dsh-iris@0.2.2` 后运行 `npx dsh-iris ...`，或从源码运行 `node bin/dsh-iris.js ...`。需要 Node.js ≥ 22、已有依赖 Sharp；从视频文件抽帧还需要 PATH 中的 ffmpeg、ffprobe，复用既有 Core 帧不需要。
 
 ## 四个命令
 

package/docs/VISION_MODEL.md

@@ -1,6 +1,6 @@
 # 单图视觉调用
 
-状态：**Iris 0.2.1**。本文说明共享单图视觉调用。
+状态：**Iris 0.2.2**。本文说明共享单图视觉调用。
 
 ## 使用与变化
 

package/docs/WORKBENCH_ARTIFACTS.md

@@ -1,6 +1,6 @@
 # 工作台作品浏览、识别与管理
 
-状态：**Iris 0.2.1**。
+状态：**Iris 0.2.2**。
 
 Iris 工作台的作品库统一展示 Core 和旧版作品，包括图片、视频、音频和文本。默认按时间倒序排列，每页 24 个；使用上一页、下一页浏览全部作品。媒体类型、作品来源和产物类型可组合筛选，匹配总数与 Core/旧版计数均按当前筛选计算。切换筛选回到第一页，刷新保留页码和筛选；尾页因作品数量减少而超界时，回到最后一页。
 

package/docs/releases/0.2.2.md

@@ -0,0 +1,31 @@
+# Iris 0.2.2：可控提示词编辑与媒体运行可靠性
+
+0.2.2 在既有图片与视觉工作流上，升级提示词优化的一般功能，并加固 Core 恢复、媒体交付和生图错误诊断。包名仍为 `@mokuyoaxis/dsh-iris`，Node.js 最低为 22.0.0，DSH 插件仅声明支持 `0.2.0-rc.2`；配置、Task/Artifact 版本和生产依赖保持。
+
+## 提示词优化
+
+- 一般功能可折叠，支持通用、画图、改图、视频与数字人五种用途，可查看草稿、改动及实际指令。
+- 默认“忠实整理”：模型只决定相邻片段的分段位置，程序从原文按原顺序拼回；遗漏、重复或调换片段会拒绝。它保证原文片段和句序，不声称自动证明所有排版变化的语义相同。
+- 明确选择“改写表达”才执行改写规则；改写结果仍需人工核对。
+- 可选建议独立获取，默认不加入正文；用户选择并采纳后才改变预览，支持撤回。获取建议会额外调用一次模型，采纳/撤回不调用模型、不直接写回或发送。
+- 保留旧自定义 v1 配置和旧文字 API，不自动改写个人配置；内置指令按 Skills 的目标、输入、约束和输出组织，S2V 明确为首帧加音频数字人。
+- 拒绝原稿和明确规则未授权的新链接/媒体输出，保护原稿和已有预览；不自动重试。合法引用与原样组装保持。
+
+## 功能模型池与媒体可靠性
+
+- 能力来自明确模型标签、旧能力字段绑定或供应商能力元数据；裸 DashScope 账号和模型名称不再自动赋予功能。发现保留未标注模型，供用户设置功能标签。已有明确配置（含空标签）优先，有序候选与复合模型身份保持。
+- Core writer 创建前原子发布完整 owner 意图，释放时整体退役目录；显式恢复保留连续步骤与审计。普通 writer 不自动抢占，活跃、未知、损坏或无 owner 的旧现场仍拒绝。需要支持 hard link 的私有文件系统，不承诺断电、共享存储或混用旧 writer 的新增保证。
+- 视频、音频与文本 staging 复用文件接收和分块哈希，减少整文件读取；本地交付失败保留远端成功，重新交付不重新生成。图片格式验证和 inline 解码仍可能使用完整 Buffer。
+- 生图尺寸按协议归一分隔符，DashScope 多模态只执行有证据的总像素规则，合法长边不再被误拒绝。本地尺寸错误在 HTTP 前明确为未受理。
+- 网络异常保留请求/正文阶段与可用错误码，原生取消/超时和完整 HTTP 业务错误保持各自分类；DSH 即时错误显示脱敏原因。受理未知仍禁止自动重提收费请求，HTTP 200 响应头不等于图片已交付。
+- 修复故障注入夹具的路径别名与分隔符假设，保持实际中断检查点验证，不通过跳过 Windows 测试绕过问题。
+
+## 升级与边界
+
+在 DSH `0.2.0-rc.2` 的 Web profile 使用 `dsh plugin --profile web add @mokuyoaxis/dsh-iris@0.2.2`；CLI 使用 `npm install @mokuyoaxis/dsh-iris@0.2.2`。升级后重启宿主并刷新客户端。旧宿主继续固定使用 Iris 0.1.4；其他 DSH 版本需独立验证。
+
+仅有裸账号而没有明确功能标签的配置，升级后需要给实际模型设置功能，再加入对应有序候选池；不会自动创建默认模型或迁移个人文件。原自定义 Prompt 不被覆盖，只有显式恢复默认才采用新内置模板。
+
+Music 继续暂缓，特殊功能待定义。英文默认 Prompt 和严格纯正文候选仍是实验，未在本版部署。原生 Gemini/Fal/Replicate、独立提示词 CLI/SDK、同步无远端 ID 的持久缓存恢复未接入；完整工作台第三轮与真实异步重启接管验收仍待补齐。网关 Gemini 兼容生图成功不等于原生 Gemini Adapter 或具体底层模型身份已验证；一次线路成功不保证持续稳定。
+
+详细用法见 [提示词优化](../PROMPT_OPTIMIZER.md)、[Core Runtime](../CORE_RUNTIME_CONTRACT.md)、[Provider Adapter](../PROVIDER_ADAPTER_CONTRACT.md) 和 [用户指南](../../user_guide.md)。

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)。