@mokuyoaxis/dsh-iris 0.2.3 → 0.2.5

package/docs/DSH_COMPATIBILITY.md

@@ -0,0 +1,69 @@
+# DSH 版本兼容
+
+Iris与DSH的版本号独立。安装前运行 `dsh --version`，并核对要安装的Iris版本；发布状态见 [README](../README.md)。
+
+## Iris 0.2.5
+
+0.2.5恢复旧宿主支持，并覆盖以下12个准确版本。旧宿主使用同一套 Iris Core、Music、图片导入和原生 Qwen 改图功能，无需维护旧版功能分支。
+
+| DSH 版本线 | 已验证的准确版本 |
+|---|---|
+| 0.1.2 | `0.1.2-rc.1` |
+| 0.1.5 | `0.1.5-rc.1`、`0.1.5-rc.2`、`0.1.5-rc.3` |
+| 0.1.7 | `0.1.7-rc.1`、`0.1.7-rc.2` |
+| 0.2.0 | `0.2.0-rc.1`、`0.2.0-rc.2` |
+| 0.2.1 | `0.2.1-alpha.1`、`0.2.1-alpha.2`、`0.2.1-alpha.3`、`0.2.1-alpha.4` |
+
+0.1.0/0.1.1及未列出的alpha、rc和正式版本未纳入本轮声明。
+
+## 历史版本
+
+| Iris版本 | 支持的DSH版本 |
+|---|---|
+| 0.2.4 | `0.2.0-rc.2` 或 `0.2.1-alpha.4` |
+| 0.2.0–0.2.3 | `0.2.0-rc.2` |
+| 0.1.4 | `>=0.1.2-rc.1 <0.1.3-0` 或 `0.1.5-rc.1` |
+
+0.2.4的历史范围保持两项准确版本。0.2.5按实际接口能力选择桥接，不再按“0.2”版本号启用默认视觉路由；已验证的旧宿主也能精确绑定默认模型、确认图片输入能力并正确处理失败终态。
+
+扩大插件支持不要求现有用户升级DSH。当前Iris Core、CLI和插件要求Node.js ≥ 22.0.0；DSH若要求更高，以宿主为准。保留旧DSH时也需要满足这个Node要求。
+
+## 安装与升级
+
+在上述12个准确版本的宿主中固定安装0.2.5：
+
+```bash
+dsh plugin --profile web add @mokuyoaxis/dsh-iris@0.2.5
+```
+
+使用其他profile时替换 `web`。更新后检查服务端装载、刷新Web客户端，并查看Iris工作台的 [宿主诊断](HOST_DOCTOR.md)。alpha.3及之后的DSH改善了插件更新与热加载，但仍以实际装载结果为准。
+
+0.2.4起统一六类功能的明确模型名单。已有分配保持；以前依赖自动模型池的功能需要在升级后明确分配，见 [升级说明](FUNCTION_MODEL_ASSIGNMENTS.md)。本次宿主适配不迁移旧作品、任务或个人配置；从Iris0.1.4整体升级的旧数据流程仍需单独验收。
+
+## 兼容声明如何生效
+
+0.2.5的 `package.json` 顶层 `engines.dsh`、嵌套 `dsh.engines.dsh` 与五项可选客户端peer列出12个准确版本；Doctor按同一集合诊断。各版本的客户端SDK分别验收；也覆盖现有根包0.1.5-rc.1/关键组件0.1.5-rc.2的混合安装。宿主版本与SDK版本需要分别核对，不能只根据根包字符串推定。Iris不把DSH客户端包安装为生产依赖。
+
+rc.2的加载器检查DSH相关peer；alpha.4优先读取顶层 `engines.dsh`，未声明时再检查peer。只改嵌套字段不能扩大新加载器的支持范围。另外，npm默认的预览版匹配与DSH的匹配选项有差别，`^0.2.0-rc.2` 不能代替按已验收准确版本逐项并列的范围。
+
+## 验证范围
+
+宿主验收使用各版官方发布的Cordis、LLM、ToolRuntime、附件、Skill、WebServer和SlotRegistry，覆盖模型路由、错误终态、视觉/OCR/定位/摘要、工具交付、作品管理及四个Iris界面插槽。Music和原生Qwen改图通过实际工具调度，使用离线响应核对持久产物、图片附件及原图关系。模型事件由本地fixture提供，禁止外部模型请求；音频夹具只验证字节交付，不代表试听质量。
+
+旧Loader没有现代兼容检查helper时，脚本改用其原生Profile/Boot装载；较新Loader检查最终manifest。临时SDK安装只用于验收配套服务，不等于启动了完整DSH应用。
+
+维护者可在本机已有目标SDK时运行：
+
+```bash
+node scripts/verify-dsh-host.mjs --dsh-root /absolute/path/to/@deepseek-ai/dsh
+```
+
+脚本在独立临时目录使用隔离DSH_HOME，不操作日常profile。Node客户端夹具另需与目标renderer同版本的官方 `@deepseek-ai/dsh-client-ui-slots` SDK；实际Web前端已内嵌此模块。若宿主安装树未提供独立包，可在仓库外准备官方SDK后显式指定：
+
+```bash
+node scripts/verify-dsh-host.mjs --dsh-root /absolute/path/to/@deepseek-ai/dsh --client-sdk-root /absolute/path/to/sdk-fixture
+```
+
+脚本不会自动下载依赖或升级宿主。仅准备SDK且未安装DSH的原生模块时，旧Loader的Node接口检查可使用 `node --expose-internals`；常规DSH安装使用宿主自带的模块。
+
+React/DOM和会话数据部分使用fixture，因此这项验收不代替完整浏览器操作、草稿写回、真机触摸或插件热更新验收。TLS和带前缀反代也不由loopback HTTP检查推定通过。早期rc.2适配的历史原因见 [rc.2适配记录](DSH_RC2_ADAPTATION.md)。

package/docs/DSH_RC2_ADAPTATION.md

@@ -1,5 +1,7 @@
 # DSH 0.2.0-rc.2 适配
 
+本文保留Iris0.2.0/0.2.1适配rc.2时的背景与验证记录。0.2.4兼容rc.2及alpha.4，0.2.5恢复了部分旧宿主支持。声明规则、使用步骤和验证边界见 [DSH版本兼容](DSH_COMPATIBILITY.md)。以下准确rc.2限制属于当时发行范围。
+
 本适配随 Iris `0.2.0` 发布；npm 0.1.4 包不包含这些后续修正。Iris 0.2.0 要求 Node.js `>=22.0.0`，DSH engines、五项客户端 peers 与 Host Doctor 仅放行准确版本 `0.2.0-rc.2`，不再沿用旧版支持窗口，也不推定其他 0.2 预览版或正式版兼容。
 
 旧 DSH `>=0.1.2-rc.1 <0.1.3-0` 或 `0.1.5-rc.1` 按历史验证范围使用稳定包 `@mokuyoaxis/dsh-iris@0.1.4`。安装与 npm tarball 下载方式见 [README](../README.md#最快开始)。保留的旧桥接与 fixture 测试不构成 Iris 0.2.0 的旧宿主支持承诺。
@@ -10,7 +12,7 @@ Iris 0.2.1 沿用相同 Node/DSH 要求，新增 Artifact 改图工具后共注
 
 | 边界 | 问题与修正 |
 |---|---|
-| 加载器与诊断 | rc.2 加载器检查 `peerDependencies`，原旧版客户端范围会被拒绝。当前客户端 peers、DSH engines、锁文件和 Host Doctor 均收敛到准确 rc.2，无需版本豁免。 |
+| 加载器与诊断 | rc.2加载器检查peerDependencies，原旧版客户端范围会被拒绝。当时客户端peers、DSH engines、锁文件和Doctor收敛到准确rc.2，无需版本豁免；0.2.4按两版范围同步。 |
 | 会话附件 | 扫描引用时曾丢弃 `bytes/width/height`，真实 `readImage()` 因完整性不匹配拒绝读取。适配器保留这些已知事实及 `originalDimensions` 的独立副本，不猜测缺失值，不复制额外 Host 字段。 |
 | 宿主视觉 | rc.2 的 `llm.stream()` 需要明确 Provider/模型路由。默认选择仅在精确模型元数据确认接受 `image` 时成为视觉候选；文本模型、未知能力和身份漂移在生成前拒绝，错误事件以及 `finish.reason.kind` 的 `error/aborted` 不再被当作空回答或部分成功。 |
 | 客户端会话 | rc.2 列表没有旧 `current` 字段。适配器使用唯一的 `retainedBy.mainView` 持有者，通知时回读 `getSnapshot()`，卸载时释放订阅；保留旧接口，有歧义或无选择时不取任意列表项。 |
@@ -29,7 +31,7 @@ node scripts/verify-dsh-host.mjs --dsh-root /absolute/path/to/@deepseek-ai/dsh
 
 脚本在仓库外创建新临时数据根，载入实际安装的 Cordis、加载器兼容检查、附件、工具、Skill、LLM、默认模型、WebServer 与客户端 SlotRegistry。模型使用本地 Fake Adapter，正常流遵循安装包的 `index` 和对象终态格式，并验证真实 Runtime 将异常转换为失败终态；禁止外部请求。会话日志和列表是显式 fixture，宿主进程入口是已核实 DSH bin 的模拟。实际 WebServer 只绑定临时 loopback 端口，退出时卸载所有 Fiber。临时目录与 `report.json` 保留供复核。
 
-当前脚本检查 15 个工具、2 项 Skill、Doctor 路由、DSH → Core diff → DSH 附件，以及四个客户端座位的注册和卸载。SlotRegistry 使用安装包中的真实代码，React/DOM 为 stub，因此不证明完整 Web profile 装载、实际组件渲染、点击和草稿写回。另用 `scripts/verify-headless-package.mjs --offline` 验证当前 tarball 在无 DSH/Cordis 安装树中执行 CLI 和 Artifact 导出。
+当时脚本检查15工具、2项Skill、Doctor路由、Core diff与附件，以及四个客户端座位。0.2.4检查17工具/3项Skill及两版宿主。SlotRegistry使用实际安装包代码，React/DOM为stub，不证明完整Web profile、实际渲染、点击和草稿写回。另用 `scripts/verify-headless-package.mjs --offline` 验证无DSH/Cordis安装树中的CLI和作品导出。
 
 ## 当前限制
 

package/docs/FUNCTION_MODEL_ASSIGNMENTS.md

@@ -0,0 +1,63 @@
+# 功能模型分配
+
+版本要求：Iris0.2.4。0.2.3只有Music采用严格名单；本页说明升级后的统一规则，发布状态见 [README](../README.md)。
+
+在“功能分配（调用顺序）”中为图片、视频、语音、音乐、转写和视觉分别选择模型。模型池登记资源、能力、协议和健康；只有加入功能名单的模型参与该功能的新请求。普通模型使用 `providerId::modelId` 复合引用，同名模型的不同账号独立选择。
+
+每次请求按名单顺序选择。已停用、缺少配置、已知冷却或不支持本次模式的项可跳过；名单之外的模型不会补入。临时指定模型也必须属于名单，且本次只调用指定项；失败不会改用其他模型。没有分配或名单全部不可用时明确失败。
+
+“清空分配”停止该功能的新调用，保留供应商、模型池、任务和作品。修改名单影响后续请求；原任务的观察和补交付仍绑定原模型和协议，不按新名单重新生成。原供应商停用、移除或绑定漂移时，仍可能无法恢复。
+
+## 功能范围
+
+- 图片生成与改图共用图片名单；改图只保留支持编辑协议的候选。
+- 视频与S2V共用视频名单，按实际首帧/音频输入筛选。
+- 看图、OCR、定位和视觉摘要共用视觉名单。
+- TTS、Music和转写各自分配；本地裁剪、抽帧等不需要模型。
+- 提示词优化继续使用独立文本路由，不随媒体分配改变。
+
+媒体生成仍只在明确未受理时切换候选。已受理或未知状态停止自动换模型；Vision沿用已有有限候选策略。Music的显式有限502重试维持原规则，可能消耗额外额度，每次创建关联新任务。
+
+## DSH宿主视觉
+
+视觉名单可加入并排序“DSH 当前默认模型”，引用为 `host:current-vision`。它通过宿主默认选择及精确元数据绑定，只有声明支持图片输入才调用；不宣称使用当前对话所选模型。一轮OCR或其他复合操作复用已绑定的实际模型，默认设置变化影响下一次操作。
+
+宿主视觉只有明确加入名单才参与，不自动放在自持模型之后。临时指定该项时也只使用该项。独立CLI没有DSH宿主，不能执行此资源；需分配可由CLI直接调用的Provider模型。
+
+## 从旧行为升级
+
+原来依赖“自动按模型池顺序选择”的功能需要明确分配。已有明确名单及顺序继续保留，升级不自动复制整个模型池、不修改个人配置。未填写和空名单均表示未分配；模型停用后仍可在分配页看到原选项及不可用状态。
+
+已有手动模型实测独立于生产名单，按既有确认与支持范围执行；实测成功更新健康状态，不自动分配。发现模型、查看状态和编辑标签不会发起生成。
+
+Headless配置示例：
+
+```json
+{
+  "providers": [
+    {
+      "id": "provider-a",
+      "auth": "none",
+      "baseUrl": "http://127.0.0.1:8080/v1",
+      "mediaProtocol": "openai-images",
+      "models": [
+        {"id": "image-a", "capabilities": ["image-gen"]},
+        {"id": "vision-a", "capabilities": ["vision"]}
+      ]
+    },
+    {
+      "id": "provider-b",
+      "auth": "none",
+      "baseUrl": "http://127.0.0.1:8081/v1",
+      "mediaProtocol": "openai-images",
+      "models": [{"id": "image-b", "capabilities": ["image-gen"]}]
+    }
+  ],
+  "assignments": {
+    "image-gen": ["provider-a::image-a", "provider-b::image-b"],
+    "vision": ["provider-a::vision-a"]
+  }
+}
+```
+
+示例引用的账号和模型必须实际存在、启用并声明对应能力。配置操作与参数见 [CLI管理](CLI_MANAGEMENT.md)。

package/docs/HEADLESS_CLI.md

@@ -1,13 +1,15 @@
 # Headless CLI
 
-`run music` 支持音乐生成与模型级协议配置，见 [音乐生成](MUSIC.md)。音乐使用明确分配名单；其余生成能力保留分配优先加池序补齐。
+`run music` 支持音乐生成与模型级协议配置，见 [音乐生成](MUSIC.md)。0.2.4的六类功能均采用明确分配名单，升级差异见 [功能模型分配](FUNCTION_MODEL_ASSIGNMENTS.md)。
 
-本文面向 Iris 0.2.3，涵盖无 DSH 的本地处理、媒体生成、视觉分析、配置和任务管理。媒体结果保存为 Core Artifact，可在后续进程中检查、分析或导出；纯视觉不自动创建产物。Core 内部接口与 Artifact v0 尚未冻结为公共 SDK。
+本文面向Iris0.2.5，涵盖无DSH的本地处理、媒体生成、视觉分析、配置和任务管理。媒体结果保存为Core Artifact，可在后续进程中检查、分析或导出；纯视觉不自动创建产物。Core内部接口与Artifact v0尚未冻结为公共SDK。
 
-需要 Node.js ≥ 22.0.0。安装 `npm install @mokuyoaxis/dsh-iris@0.2.3` 后运行 `npx dsh-iris --help`。源码入口为 `node bin/dsh-iris.js ...`；安装本地 tarball 后也可运行 `dsh-iris ...`。
+需要Node.js ≥ 22.0.0。按 [README](../README.md) 核对发布状态，安装 `npm install @mokuyoaxis/dsh-iris@0.2.5` 后运行 `npx dsh-iris --help`。源码入口为 `node bin/dsh-iris.js ...`；本地tarball也可用于安装。
 
 0.2.1 提供 `vision look / locate / ocr / summarize`。文件输入的纯视觉不需要数据根，支持显式模型覆盖、JSON/文本、结果和拼图文件；图片/帧 Artifact ID 输入需显式数据根，以 reader 读取既有 Core 产物，只有主动音轨转写才创建 Core Task/Artifact。完整命令与输出规则见 [独立视觉 CLI](VISION_CLI.md)；S2V、HTML、配置、等待及批量管理见 [CLI 管理](CLI_MANAGEMENT.md)。
 
+0.2.4新增 `artifact import --data-root /absolute/path/core --input '{"image_path":"/absolute/path/source.png"}'`，将本地图片保存为持久作品，不调用模型；详见 [图片导入](IMAGE_IMPORT.md)。npm0.2.3不包含此命令。
+
 ## 配置查询与离线诊断
 
 ```bash
@@ -16,7 +18,7 @@ dsh-iris capabilities list --provider-config /absolute/path/to/providers.json
 dsh-iris doctor --data-root /absolute/path/to/iris-data --json
 ```
 
-前两项只读取显式提供的私有配置文件，不创建 Core Runtime 或数据根，也不请求 Provider。`providers list` 输出供应商身份、启用/配置状态、认证方式、媒体协议及其推断标记、配置能力与模型数；不输出 API Key 或端点。`capabilities list` 按六种配置能力列出 `providerId::modelId` 候选链，音乐只使用明确分配名单，其余能力采用“手工分配优先、模型池顺序补齐”规则；空链标为 `gap: no_configured_model`。这些只是配置事实，不证明远端模型或协议可调用。
+前两项只读取显式提供的私有配置文件，不创建Core Runtime或数据根，也不请求Provider。`providers list`输出供应商身份、启用/配置状态、认证方式、媒体协议及其推断标记、配置能力与模型数；不输出API Key或端点。0.2.4的 `capabilities list` 按六种配置能力列出明确分配且当前CLI可用的 `providerId::modelId` 候选链；空链标为 `gap: no_configured_model`。这些只是配置事实，不证明远端模型或协议可调用。
 
 显式 `doctor --data-root` 是只读 Core 盘点：检查 Task/Artifact 结构、Index 一致性、孤立/未解析条目和写者租约；不创建缺失的根、不执行写入探针、不重建索引，也不释放租约。活跃写者可能使盘点在读取期间变化。省略 `--data-root` 时仍检查 DSH profile，保留原有写入探针，并纳入该 profile 的 `core-v0`。两种模式都返回 legacy/Core 计数对照，显式模式只统计指定根同层的 legacy 文件。退出码为 `0` 正常、`1` 警告、`2` 硬错误；诊断不会调用 Provider。
 
@@ -73,11 +75,11 @@ dsh-iris run image \
   --input '{"prompt":"一朵雨后的鸢尾花","model_ref":"provider-id::model-id","size":"1024*1024","n":1}'
 ```
 
-`model_ref` 可省略；省略时采用“手工 assignment 顺序优先、模型池顺序补齐”的安全 failover。每个请求从首项开始，只有明确 `not_accepted` 才进入下一项。配置文件须为普通文件，POSIX 权限不得开放给 group/other；API Key、端点、Prompt 和下载 URL都不会写入 Task 输出。
+`model_ref` 可省略；省略时只使用assignment名单，按配置顺序选择。指定时须属于名单且本次只调用该项。每个请求从首项开始，只有明确 `not_accepted` 才进入下一项。配置文件须为普通文件，POSIX权限不得开放给group/other；API Key、端点、Prompt和下载URL都不会写入Task输出。
 
-模型必须存在于配置的 `models` 或旧模型字段中，且具备所请求的能力；缺失时返回配置错误，不注入厂商默认模型。显式 `models:[]` 表示没有可用模型。`model_ref` 也接受裸模型名，同名跨供应商时按配置中的供应商顺序取首项；需要精确绑定账号时使用 `providerId::modelId`。显式指定只选择该模型，不扩展 failover 候选。
+模型必须存在于配置的 `models` 或旧模型字段中，且具备所请求的能力；缺失时返回配置错误，不注入厂商默认模型。显式 `models:[]` 表示没有可用模型。`model_ref` 也接受裸模型名，同名跨供应商时从当前功能名单中取首个匹配项；需要精确绑定账号时使用 `providerId::modelId`。显式指定只选择该模型，不扩展 failover 候选。
 
-旧裸 DashScope 账号的已知目录仅在 DSH 配置加载或保存时一次性写入 `models`，随后可见、可编辑；CLI 只读配置，不执行该迁移。独立 CLI 配置须自行声明模型。
+裸 DashScope 账号不再自动写入厂商目录或授予功能能力。已有明确保存的模型和旧能力字段绑定继续保留；独立 CLI 配置同样需要声明模型并分配给功能。
 
 生图按每个模型的有效图片协议调用，保存真实 PNG/JPEG/WebP 字节。聊天改图使用 `source_artifact_id`，创建关联原图的新 Artifact；具体参数和协议限制见 [模型级图片协议](CLI_MANAGEMENT.md#模型级图片协议) 与 [Artifact 聊天改图](CLI_MANAGEMENT.md#artifact-聊天改图)。
 
@@ -136,7 +138,7 @@ dsh-iris task inspect task_0123456789abcdef01234567 \
 
 新建 Attempt 可选保存 `stageTimestamps`：排队、开始提交、提交响应、远端终态、开始下载、下载校验完成和本地 Artifact 处理完成七个边界。字段按发生顺序单调不减；旧记录缺失该字段仍可读取。重新交付会从新的下载开始边界重新计时，不伪造尚未跨过的阶段。
 
-新建 Attempt 还可选保存 `selectionReason`：`explicit` 表示调用方显式提供 `model_ref`，`assignment` 表示候选来自提交当时的能力分配，`pool` 表示由配置模型池按顺序补齐。它与 Attempt 一起在 Provider submit 前落盘；`task inspect` 只展示持久事实，不会用当前可能已变化的 assignment 事后猜测。旧记录没有该字段时保持缺失，不伪造默认值；第几次 failover 仍看 `ordinal`。
+新建Attempt还可选保存 `selectionReason`：`explicit` 表示调用方明确指定名单内模型，`assignment` 表示按提交当时的功能名单选择。`pool` 保留为旧记录的历史来源，0.2.4不再产生池补齐候选。该事实随Attempt在Provider submit前落盘；`task inspect` 只展示持久记录，不按当前assignment事后猜测。旧记录缺少字段时保持缺失；第几次failover仍看 `ordinal`。
 
 已受理的异步图片 Task 可以显式推进一次：
 

package/docs/HOST_ADAPTER_CONTRACT.md

@@ -19,8 +19,8 @@ Host Adapter 只负责把一个宿主的工具、路由、客户端、附件、
 | `attachments` | `ctx.get('attachments')` | 保存/读取图片字节，返回 Iris 自有引用 DTO | DSH 图片投影或会话图片读取不可用 |
 | `sessions` | `ctx.get('sessionQuery')` / Client sessions | 列出当前会话的受支持附件和最小模型选择信息 | 只使用 Iris 自有产物或显式上传 |
 | `browser` | `ctx.get('browser')` | 将受限 HTML 渲染为图片；不向 Command 暴露 DSH page/session 对象 | HTML 截图不可用 |
-| `textModel` | DSH LLM/default-model 服务 | 执行无工具的文本生成并解析当前/默认模型 | 对话框提示词优化不可用 |
-| `visionModel` | DSH 全局视觉模型 | 作为 Iris 自持视觉 Provider 之外的可选后端 | 有自持视觉配置时降级；否则视觉动作失败 |
+| `textModel` | DSH LLM/default-model 服务 | 文本生成及精确模型元数据；当前宿主视觉也由此绑定默认选择 | 宿主文本/视觉不可用，自持 Provider 按各功能名单执行 |
+| `visionModel` | DSH 旧视觉桥接 | 保留 `analyze()` 兼容入口；当前视觉共享端口经 `textModel` 与附件桥接执行 | 旧桥接不可用，不自动授予视觉功能调用资格 |
 
 `ports` 只包含真实可调用的方法对象。缺失或版本不兼容的能力进入 `unavailable`，并提供 `kind` 与人类可读 `reason`；Doctor 与运行错误必须消费同一份事实。
 
@@ -28,21 +28,23 @@ Host Adapter 只负责把一个宿主的工具、路由、客户端、附件、
 
 | Command/入口 | 必需端口 | 可选端口 | 说明 |
 |---|---|---|---|
-| `image` | 无 | `visionModel` | 生成与 Task 不依赖宿主；成功后的简短视觉描述可以降级 |
-| `video`、`tts`、`transcribe` | 无 | 无 | Provider、Task 与产物落盘属于 Iris Core |
-| `look`、`locate`、`ocr` | 无 | `visionModel` | 优先使用 Iris Provider；没有任何视觉后端才失败 |
+| `image` | 无 | `textModel` + `attachments` | 生图按图片名单执行；成功后可选描述按视觉名单执行，不影响生成事实 |
+| `video`、`tts`、`music`、`transcribe` | 无 | 无 | Provider、Task 与产物落盘属于 Iris Core，分别使用功能名单 |
+| `look`、`locate`、`ocr` | 无 | `textModel` + `attachments` | 只按视觉名单尝试自持或显式宿主资源，无可用项时失败 |
 | `crop`、`diff`、`video_frames` | 无 | 无 | 确定性本地动作 |
-| `media_summarize` | 无 | `visionModel` | 帧提取是本地动作，理解阶段允许宿主视觉降级 |
+| `media_summarize` | 无 | `textModel` + `attachments` | 帧提取是本地动作，理解阶段只使用视觉名单 |
 | `html` | `browser` | 无 | Command 只调用语义级 `renderHtml` |
 | `relook` | 条件必需 `attachments` + `sessions` | 无 | Iris 自有附件可直接解析；会话附件必须走宿主端口 |
 | `attachments_list`、`attachment_export` | 条件必需 `attachments` + `sessions` | 无 | Iris 自有产物不依赖宿主；会话来源不得读取宿主私有文件 |
 | Task 查询、观察、交付、提醒和知情重试 | 无 | 无 | 事实、费用确认和新旧 Task 关系归 Iris 所有 |
-| Provider/模型/能力配置 | 无 | `visionModel` | 普通发现与配置不依赖宿主；视觉实测可选宿主后端且必须显式触发 |
+| Provider/模型/能力配置 | 无 | 无 | 普通发现与配置不依赖宿主；手动实测只调用指定Provider，不按生产名单或回退宿主 |
 | Prompt Optimize | `textModel` | `sessions` | 客户端可显式传模型；否则从宿主获取当前/默认选择 |
 | DSH 工具结果投影 | `tools` | `attachments` | 注册与结果转为 DSH attachment 属于 DSH Adapter，不进入 Command |
 | Workbench/API/媒体路由 | `routes` | `clientSlots` | HTTP/UI 只是投影，不是真相来源 |
 | 随包 Skill | `skills` | 无 | Skill 不得绕过 Command、Task 或费用边界 |
 
+开发树中的宿主视觉必须以 `host:current-vision` 加入视觉名单并排序；读取的是DSH当前默认选择，不是当前对话选择。不自动追加宿主候选，临时指定失败也不回退。升级规则见 [功能模型分配](FUNCTION_MODEL_ASSIGNMENTS.md)。
+
 ## 不可违反规则
 
 1. Core、Command、Task 和 Provider 模块不得导入 DSH/Cordis 运行时，也不得通过任意字段重新取得原始 `ctx`。
@@ -89,6 +91,8 @@ Iris 继续作为普通 DSH/Cordis 插件装载：`cordis.patch.yml` 只把 npm
 - Host Doctor 对服务端注册账本、客户端版本和 Slot 握手分别给出结果；
 - 已发布 Iris `0.1.4` 在 DSH `0.1.2-rc.1` 与 `0.1.5-rc.1` 上有历史宿主验证记录，不继承为当前版本的支持声明。
 - Iris `0.2.1` 只声明 DSH `0.2.0-rc.2`，已通过真实安装服务隔离验收，保留附件完整引用、绑定明确图片模型路由并适配客户端主视图选择；边界与尚未完成的浏览器实机检查见 [rc.2 适配说明](DSH_RC2_ADAPTATION.md)。
+- Iris0.2.4扩大为rc.2与alpha.4两项准确版本，顶层engines.dsh、嵌套字段、五项可选peer及Doctor同步；Core/Provider契约保持。当前范围和服务/浏览器验证区别见 [DSH版本兼容](DSH_COMPATIBILITY.md)。
+- Iris0.2.5在单一Adapter中按默认选择与模型元数据接口启用精确视觉路由，恢复旧宿主的当前功能；12个准确版本经官方SDK隔离验收后进入声明。Core/Provider和数据格式保持，具体范围仍以兼容矩阵为准。
 
 Local Host 不模拟 Browser、会话或附件。测试需要这些能力时必须显式注入，缺失行为也属于契约。
 

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、插件、当前工具/Skill、4组路由、Browser/附件/模型、客户端版本和4个UI Slot；Iris 0.2.3 检查16工具/3项Skill |
+| `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,14 +31,14 @@ 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.5的Doctor与package顶层/嵌套DSH engines及客户端peer统一覆盖12个已验证准确版本，包含0.1.2-rc.1和0.1.5系列；旧宿主不再被统一引导至Iris0.1.4。Iris0.2.4的历史范围仍为 `0.2.0-rc.2` 或 `0.2.1-alpha.4`。具体范围及SDK验收限制见 [兼容矩阵](DSH_COMPATIBILITY.md)。无DSH的CLI/离线诊断不受宿主版本限制。
 
 ## 运行时证据
 
 服务端只登记成功完成的注册：
 
 - 插件身份与 npm 版本；
-- Iris Agent工具名（含改图与音乐，共16个）；
+- 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` 四组逻辑路由。
 

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/ROADMAP.md

@@ -4,15 +4,18 @@ Iris 的方向是本地优先、Agent 可调用的多模态创作工作台。用
 
 ## 当前状态
 
-当前版本为 **Iris 0.2.3**。包名为 `@mokuyoaxis/dsh-iris`，同时提供 DSH 插件与独立 CLI，详见 [0.2.3 发布说明](releases/0.2.3.md)。
+本文对应 **Iris0.2.5**，发布状态见 [README](../README.md)。包名为 `@mokuyoaxis/dsh-iris`，同时提供DSH插件与独立CLI；本版恢复旧宿主支持，详见 [0.2.5发布说明](releases/0.2.5.md)。
 
 - 图片生成、Artifact ID 看图/OCR/定位和聊天改图，支持按模型配置图片协议。
+- 持久图片导入与原生Qwen改图，六类功能统一严格分配及显式宿主视觉，见 [0.2.4发布说明](releases/0.2.4.md)。0.2.5将DSH范围扩为12个准确版本。
 - 视频、S2V、TTS、转写与音乐生成，共用任务、音频/视频作品和导出入口；音乐使用明确分配名单。
 - 三项 Agent Skills 分别指导单步操作、多步骤创作和界面验收；配乐与检查按用户目标加入。
 - 提示词的忠实整理、明确改写、可选建议与预览；完整同步媒体结果缓存后的交付恢复。
 - 工作台全媒体筛选、分页、跨页选择和下载，CLI 的配置、查询与可恢复维护。
 
-DSH与CLI共用Task和Artifact，同一数据根只允许一个写者。纯视觉和提示词预览不自动创建媒体任务；Core与Model Port仍是内部契约。Node.js最低22.0.0，DSH插件支持准确的 `0.2.0-rc.2`，旧宿主使用固定的Iris `0.1.4`。
+DSH与CLI共用Task和Artifact，同一数据根只允许一个写者。纯视觉和提示词预览不自动创建媒体任务；Core与Model Port仍是内部契约。Node.js最低22.0.0。0.2.5恢复旧宿主的当前功能，并覆盖12个准确DSH版本；具体版本和历史范围见 [兼容矩阵](DSH_COMPATIBILITY.md)。
+
+宿主兼容继续集中在Adapter与客户端桥接。后续DSH更新优先检查实际API、工具/附件交付和输入区契约，复用同一验收入口扩充版本矩阵，避免让旧用户长期停留在缺少新功能的Iris分支。
 
 ## 近期优先：真实使用验收
 
@@ -28,6 +31,7 @@ DSH 工作台与 Headless CLI 共用 Core 的可恢复隔离和恢复入口，
 
 ### 后续 0.2.x
 
+- 图片创作的原图/新版并排对比与版本选择；0.2.4已提供持久图片导入和原生Qwen改图。
 - 适配其他协议，包括原生 Gemini、Fal 和后续 Replicate；网关兼容接口与原生协议接入分别验证；
 - 按实际需求增加音乐来源、可控参数和音视频衔接；已有音乐生成入口见 [音乐生成](MUSIC.md)；
 - 收藏、标签与工作台搜索（CLI 及工作台过滤、分页、显式选择/批量下载已完成）；

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.4.md

@@ -0,0 +1,27 @@
+# Iris 0.2.4：图片续作、统一分配与新版宿主兼容
+
+0.2.4让已有图片可以直接进入作品库并继续编辑，统一六类功能的模型选择规则，同时支持DSH rc.2与alpha.4。
+
+## 升级前检查功能分配
+
+图片、视频、TTS、Music、转写和视觉只使用各自明确分配的有序名单。名单为空时停止新调用，临时指定的模型也必须已分配，且只调用该项。以前依赖自动补入模型池的功能，需要在升级后明确分配模型。
+
+供应商、模型池和已有名单保留，不自动迁移个人配置。旧任务仍绑定原模型查询和补交付；手动模型实测独立于生产名单。DSH默认视觉改为需要明确加入名单的“DSH 当前默认模型”，独立CLI不能调用该宿主资源。见 [完整升级说明](../FUNCTION_MODEL_ASSIGNMENTS.md)。
+
+## 图片导入与原生Qwen改图
+
+工作台“导入图片”、`iris_import_image` 和CLI `artifact import` 保存静态PNG/JPEG/WebP图片，最多20 MiB，返回持久作品ID。保留原字节和源文件，不调用模型；已有Core作品无需重复导入。见 [图片导入](../IMAGE_IMPORT.md)。
+
+`iris_edit_image`、CLI和工作台改图支持DashScope原生Qwen edit/max/plus、2.0/pro系列及日期快照，继续支持聊天生图协议。模型还须具备image-gen能力并加入生图名单，具体账号与地域是否可用由服务端决定。`qwen-image-2.0-pro` 已通过真实CLI带图生成、取回与保存来源关系的实测。
+
+原图只读，发送副本按账号/模型预算处理；修改版保存为独立作品并关联来源。原生Qwen输入副本另受10 MiB上限约束。编辑精度、输出尺寸由模型决定，不提供蒙版、多参考图或像素级保真保证。见 [Artifact改图](../CLI_MANAGEMENT.md#artifact-聊天改图)。
+
+## DSH双版本兼容
+
+支持准确版本 `0.2.0-rc.2` 和 `0.2.1-alpha.4`，manifest、可选客户端peer及Doctor同步。不要求已有rc.2用户升级宿主，也不据此支持整个0.2.x。Iris最低Node.js为22.0.0；DSH若要求更高，以宿主为准。见 [兼容矩阵与验证范围](../DSH_COMPATIBILITY.md)。
+
+## 使用与验证范围
+
+Agent工具增至17项，三项Skills的共享说明包含图片导入、严格分配和Qwen改图。Music仍是可选功能，本版未更换音乐来源或增加新的音乐协议。
+
+宿主隔离验收覆盖实际官方SDK服务、工具/附件交付、HTTP与界面插槽；React/DOM和部分会话数据使用fixture，完整浏览器/移动端交互与热更新仍需实际使用验证。未增加Core数据格式迁移或生产依赖。

package/docs/releases/0.2.5.md

@@ -0,0 +1,33 @@
+# Iris 0.2.5：旧宿主继续使用当前功能
+
+0.2.5恢复当前Iris在旧DSH上的支持，将准确版本范围从2个扩展至12个。已验证的旧宿主可使用同一套Music、图片导入、原生Qwen改图和其他现有功能，无需停留在Iris0.1.4。
+
+## DSH版本范围
+
+- `0.1.2-rc.1`
+- `0.1.5-rc.1`、`0.1.5-rc.2`、`0.1.5-rc.3`
+- `0.1.7-rc.1`、`0.1.7-rc.2`
+- `0.2.0-rc.1`、`0.2.0-rc.2`
+- `0.2.1-alpha.1`、`0.2.1-alpha.2`、`0.2.1-alpha.3`、`0.2.1-alpha.4`
+
+engines、可选客户端peer和Doctor同步使用上述范围。保留旧DSH时仍需Node.js ≥22.0.0；宿主自身要求更高时以宿主为准。未列出的版本需单独验收。见 [兼容矩阵](https://github.com/mokuyoaxis/dsh-iris/blob/v0.2.5/docs/DSH_COMPATIBILITY.md)。
+
+## 视觉桥接修正
+
+默认视觉按宿主实际接口能力启用精确模型路由，修复旧SDK已有相同接口却进入历史路径、可能返回空结果或忽略失败终态的问题。旧版同样确认图片输入能力并处理取消；Core、Provider和数据格式保持，未增加生产依赖。
+
+## 安装与升级
+
+```bash
+dsh plugin --profile web add @mokuyoaxis/dsh-iris@0.2.5
+```
+
+将`web`替换为实际profile，更新后重载后端并刷新页面，用Iris宿主诊断确认17工具、3项Skill和客户端版本。独立CLI可使用`npm install @mokuyoaxis/dsh-iris@0.2.5`。
+
+从较早版本升级时，六类模型功能都需明确分配；DSH默认视觉也需加入视觉名单。见 [功能分配与升级说明](https://github.com/mokuyoaxis/dsh-iris/blob/v0.2.5/docs/FUNCTION_MODEL_ASSIGNMENTS.md)。本版不迁移旧任务、作品或个人配置。
+
+## 验证范围
+
+12个准确版本及现有根0.1.5-rc.1/组件rc.2混合安装，共13组官方SDK组合通过工具、附件、模型路由、HTTP和界面插槽隔离检查；旧Profile/Boot另通过实际tarball安装和装载。
+
+模型响应使用离线夹具，Music/Qwen检查验证协议与作品交付。React/DOM和部分会话数据使用fixture；完整浏览器/移动端交互、草稿写回、热更新和从Iris0.1.4个人数据整体升级仍需实际使用验证。见 [用户指南](https://github.com/mokuyoaxis/dsh-iris/blob/v0.2.5/user_guide.md)。