@mokuyoaxis/dsh-iris 0.2.5 → 0.2.6

package/docs/DSH_PROVIDER_CONNECTIONS.md

@@ -0,0 +1,34 @@
+# 复用 DSH 供应商连接
+
+版本要求：Iris 0.2.6；发布状态见 [README](../README.md)。0.2.5 不包含此入口。
+
+DSH 已有兼容媒体服务时，可以在 Iris 工作台引用它的连接，避免再次填写和保存 Base URL/API Key。Iris 保留自己的模型、媒体协议与功能池；宿主连接提供当前地址和凭据。已有手动供应商配置继续使用。
+
+## 工作台操作
+
+1. 打开“添加供应商”，在“连接来源”选择已配置的 DSH 连接。
+2. 明确选择该服务实际支持的媒体协议，保存。
+3. 发现或添加媒体模型，确认它用于哪些功能。首次配置可同时启用所选功能的自动池，保存即可使用，无需再次逐项分配。
+
+引用连接不会自动发现、实测或生成；只有用户确认的用途和功能策略决定调用范围。已有手工名单或停用状态不会自动改变。DSH 能进行文字对话不证明相同服务支持媒体接口；协议、账号权限和模型能力仍需核对。三种调用方式见 [功能模型池](FUNCTION_MODEL_POOLS.md)。
+
+## 地址、密钥与恢复
+
+Iris 配置只保存 `dshProvider: { provider, settingsNs }`，不保存该连接的普通 Base URL 或密钥。操作期间，DSH 适配层通过公开供应商目录、已脱敏设置描述和凭据接口构造内存副本；不同并发操作的副本隔离，不进入配置持久化。
+
+DSH 的地址或密钥变化影响下一次操作。Iris 供应商列表展示连接来源、地址和可用状态，密钥只显示“由 DSH 管理”。停止使用引用或删除 Iris 供应商不会修改 DSH 原连接。
+
+离线 Doctor 不解析宿主引用，会提示“需由运行中宿主解析”，不会要求再填写同一把密钥。请在 DSH 工作台查看连接状态和功能池候选；候选元数据不代替真实接口权限验证。
+
+原连接停用、移除或无法解析时，该项不可用；显式指定该模型不会换用其他账号。原任务的恢复继续校验提交端点和协议绑定，地址改变时拒绝向新端点观察原任务，不会重新生成。已缓存完整字节的本地补交付沿用现有规则。
+
+## 支持范围
+
+- 需要 DSH 的 `llm.listProviders/listConfigurableProviders`、`settings.describe` 和对应凭据服务。
+- 支持配置中的 `apiKeyEnv` 引用、默认 `llm-pi-ai` 实例的 API Key 记录，以及目录明确声明的环境凭据引用。
+- OAuth/登录授权、专有签名和自定义请求头不转换为媒体认证；界面显示原因，可继续手动添加适合的媒体供应商。
+- 尚不自动处理别名 `llm-pi-ai` 实例的私有记录归属；这类实例可以使用公开的 `apiKeyEnv` 引用。
+- 缺少接口的旧宿主保留手动配置。连接复用能力按实际服务检测，不扩大已有宿主版本声明。
+- Headless CLI 不读取 DSH 连接。CLI 媒体调用继续使用显式的独立 Provider 配置；含 DSH 引用的条目不能在无宿主进程中解析。
+
+此功能不迁移已有配置、导出宿主密钥或读取其他项目文件；功能策略由用户明确选择，受理后不自动重提和单写者约束继续保留。

package/docs/FUNCTION_MODEL_ASSIGNMENTS.md

@@ -2,6 +2,8 @@
 
 版本要求：Iris0.2.4。0.2.3只有Music采用严格名单；本页说明升级后的统一规则，发布状态见 [README](../README.md)。
 
+本页说明 0.2.4/0.2.5 的规则，以及 0.2.6 中“仅用所选模型”的行为。0.2.6 另提供 [自动池、手选与停用](FUNCTION_MODEL_POOLS.md)；旧名单及缺失/空分配继续保持本页行为，不会静默启用自动池。以下“只有名单内模型参与”仅适用于手选模式。
+
 在“功能分配（调用顺序）”中为图片、视频、语音、音乐、转写和视觉分别选择模型。模型池登记资源、能力、协议和健康；只有加入功能名单的模型参与该功能的新请求。普通模型使用 `providerId::modelId` 复合引用，同名模型的不同账号独立选择。
 
 每次请求按名单顺序选择。已停用、缺少配置、已知冷却或不支持本次模式的项可跳过；名单之外的模型不会补入。临时指定模型也必须属于名单，且本次只调用指定项；失败不会改用其他模型。没有分配或名单全部不可用时明确失败。

package/docs/FUNCTION_MODEL_POOLS.md

@@ -0,0 +1,84 @@
+# 功能模型池与调用方式
+
+版本要求：Iris 0.2.6；发布状态见 [README](../README.md)。0.2.4/0.2.5 使用 [严格功能名单](FUNCTION_MODEL_ASSIGNMENTS.md)；升级不会自动启用自动池。
+
+## 配好一次即可使用
+
+在工作台添加媒体供应商，或 [引用 DSH 已有连接](DSH_PROVIDER_CONNECTIONS.md)，选择实际支持的媒体协议。在供应商详情填写模型名，勾选它可用于哪些功能，点击“保存模型用途”。
+
+首次配置会推荐勾选“同时启用所选功能的自动池”。保存后，已确认的模型直接进入这些功能的候选，不需要再逐项添加到功能名单。已有配置不会自动改为此模式；启用框会明确说明它会替换所选功能的调用方式。仅保存用途不发起实测或生成，也不代表上游已验证可用。
+
+供应商详情的“模型目录”默认折叠，点击“同步目录”读取最新列表；发现的新条目显示“待确认用途”，确认后才会加入自动池。名称和 DSH 文字连接不证明媒体能力。Music 还需明确绑定 `musicProtocol: gemini-web-music`。
+
+## 目录更新与候选可用性
+
+新自动请求开始前按需检查供应商目录，成功结果缓存 10 分钟，同连接并发读取合并；也可在工作台主动同步。同步只读取目录，不发起模型实测或生成。配置检查、手选请求、停用功能与旧任务查询不会暗中刷新目录。同步失败保留上次完整目录及错误原因，短暂退避 30 秒；坏响应或不完整分页不会覆盖快照。
+
+目录展示同步时间、新条目与“目录未列出”的已配置模型。未列出本身不能证明下线：手工模型、用途和顺序继续保留，新模型仍需确认。混合视频/音频输出不自动获得 TTS 用途，音频理解也不自动获得文件转写用途；可信的明确能力代码优先。
+
+当当前连接在新提交或实测中明确返回模型不存在（模型专属错误码，或精确的 `404 Model not exist.`）时，仅隔离该连接的模型及能力，后续请求跳过它。通用路径 404、参数 400、认证错误、限流与网络错误不按模型消失处理。历史成功保留，可用性单独显示；目录重新列出不自动解除隔离。改变连接或有效图片协议后重新判断，也可在核对目录后单独确认费用进行实测，成功恢复。旧任务的查询、观察与交付仍沿用原绑定，不解除或新增此类阻断。
+
+DSH、Agent 和独立 CLI 共用规则。媒体的候选切换仍遵守受理边界；视觉保留已有操作停止规则，本次已发出的明确模型 404 会隔离后续请求，不因此扩张同一操作的切换条件。当前没有后台定时器、自动付费探针、按目录自动删除模型或自动授权新模型。
+
+## 每个功能有三种调用方式
+
+| 方式 | 候选范围 | 没有合格候选时 |
+|---|---|---|
+| 自动池 | 已确认用途、连接启用且协议支持的同功能模型，按供应商和模型登记顺序选择 | 显示候选为零及配置缺口，不发起请求 |
+| 仅用所选模型 | 只使用手选的有序名单，不补入其他模型 | 提示添加所选模型或切换模式 |
+| 停用 | 停止此功能的新调用 | 显式传入模型也不能绕过 |
+
+工作台“功能池与调用方式”展示各功能的候选数，以及未连接、待确认用途、协议不支持或限流等原因。切换自动池先展示影响并确认；切回手选会保留原名单。自动池不是网络连通或上游能力实测的保证。
+
+自动池采用页面内确认，确认前显示“尚未保存”；提交后在该功能旁依次显示“正在保存”“正在更新候选”和“已保存”。保存期间暂时禁用重复切换。若未收到确认，点击“刷新状态”只读取保存结果，不会再次提交；已保存但候选更新失败会分别说明。
+
+更新后，需让 DSH 服务端加载新代码，再刷新页面。仅刷新页面可能形成新界面配旧服务端；此时页面会提示重启 DSH，并暂停策略切换，避免把旧接口的成功响应误认为自动池已启用。
+
+生图和改图共享图片池，视频和 S2V 共享视频池，再按具体输入和协议过滤。看图、OCR、定位和视觉摘要共享视觉池。TTS、Music、转写分别使用自己的池；裁剪、导入、抽帧等本地操作不要求模型。
+
+自动视觉默认不包含宿主资源；需要时明确勾选“使用 DSH 当前视觉模型”。它仍须由宿主声明支持图片输入，独立 CLI 不能执行该资源。
+
+## 顺序选择与安全切换
+
+每个新请求从首个合格候选开始。A 明确未受理时可以继续 B；已知冷却项会跳过。此阶段没有跨请求 A→B→C 的轮转游标。
+
+临时指定模型须在当前允许范围内，本次只调用它，失败不替换。工作台默认保留自动选择，不会把首个候选填成显式参数；Agent 也只应在用户明确指定时传模型参数。
+
+媒体受理未知、已经受理或交付失败时，仍绑定原任务处理，不因池内还有模型就重新生成。池和策略变化只影响新请求，旧任务沿原模型、协议和端点绑定观察或补交付。Music 原有显式 502 重发规则独立保留，每次建立关联新任务，可能增加费用。
+
+## 旧配置与 CLI
+
+旧字符串、数组及对象形式的分配继续按原手选名单解释，缺失或空分配保持零调用；读取不会自动启用或迁移。用户主动切换策略时，旧引用归一化保存，原手工名单保留。无宿主 CLI 仍使用显式私有配置，不解析 DSH 连接引用。
+
+新策略在现有 `assignments` 中按功能保存，例如：
+
+```json
+{
+  "assignments": {
+    "image-gen": {"mode": "auto", "models": ["account::preferred-image"]},
+    "music-gen": {"mode": "manual", "models": ["account::music"]},
+    "vision": {"mode": "auto", "models": [], "hostVision": false},
+    "video-gen": {"mode": "disabled", "models": []}
+  }
+}
+```
+
+`models` 是保留的手工名单，自动模式不以它限制候选。新增模型必须有明确功能标签，发现条目须经用户确认；模型的限流、协议及实际输入约束继续生效。
+
+通过现有 CLI JSON 输入管理，无需增加命令或直接编辑配置：
+
+```bash
+dsh-iris models add 'account::image-a' --provider-config /absolute/path/providers.json \
+  --input '{"capabilities":["image-gen"],"enableAutomatic":true}'
+dsh-iris models caps 'account::image-b' --provider-config /absolute/path/providers.json \
+  --input '{"capabilities":["image-gen"]}'
+dsh-iris assignments set --provider-config /absolute/path/providers.json \
+  --input '{"capability":"image-gen","mode":"auto"}'
+dsh-iris assignments set --provider-config /absolute/path/providers.json \
+  --input '{"capability":"image-gen","mode":"manual","model_refs":["account::image-b"]}'
+dsh-iris assignments set --provider-config /absolute/path/providers.json \
+  --input '{"capability":"image-gen","mode":"disabled"}'
+dsh-iris capabilities list --provider-config /absolute/path/providers.json
+```
+
+`enableAutomatic:true` 是明确修改所选功能策略的动作；省略时只确认用途，已有自动功能会纳入该模型，已有手工/停用功能不变。`assignments clear` 继续清除该功能分配并停止新调用，不表示恢复自动。配置写入沿用唯一私有备份与并发修改检查，见 [CLI 管理](CLI_MANAGEMENT.md)。

package/docs/HEADLESS_CLI.md

@@ -1,10 +1,10 @@
 # Headless CLI
 
-`run music` 支持音乐生成与模型级协议配置，见 [音乐生成](MUSIC.md)。0.2.4的六类功能均采用明确分配名单，升级差异见 [功能模型分配](FUNCTION_MODEL_ASSIGNMENTS.md)。
+`run music` 支持音乐生成与模型级协议配置，见 [音乐生成](MUSIC.md)。0.2.6 可选择自动池、仅用所选模型或停用，旧名单和空配置不自动改变，见 [功能模型池](FUNCTION_MODEL_POOLS.md)。
 
-本文面向Iris0.2.5，涵盖无DSH的本地处理、媒体生成、视觉分析、配置和任务管理。媒体结果保存为Core Artifact，可在后续进程中检查、分析或导出；纯视觉不自动创建产物。Core内部接口与Artifact v0尚未冻结为公共SDK。
+本文面向 Iris 0.2.6，涵盖无 DSH 的本地处理、媒体生成、视觉分析、配置和任务管理。媒体结果保存为 Core Artifact，可在后续进程中检查、分析或导出；纯视觉不自动创建产物。Core 内部接口与 Artifact v0 尚未冻结为公共 SDK。
 
-需要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也可用于安装。
+需要Node.js ≥ 22.0.0。按 [README](../README.md) 核对发布状态，安装 `npm install @mokuyoaxis/dsh-iris@0.2.6` 后运行 `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)。
 
@@ -18,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或端点。0.2.4的 `capabilities list` 按六种配置能力列出明确分配且当前CLI可用的 `providerId::modelId` 候选链；空链标为 `gap: no_configured_model`。这些只是配置事实，不证明远端模型或协议可调用。
+前两项只读取显式提供的私有配置文件，不创建 Core Runtime 或数据根，也不请求 Provider。`providers list` 输出供应商身份、启用/配置状态、认证方式、媒体协议及其推断标记、配置能力、模型数和已有目录摘要；不输出 API Key 或端点。`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。
 
@@ -75,11 +75,11 @@ dsh-iris run image \
   --input '{"prompt":"一朵雨后的鸢尾花","model_ref":"provider-id::model-id","size":"1024*1024","n":1}'
 ```
 
-`model_ref` 可省略；省略时只使用assignment名单，按配置顺序选择。指定时须属于名单且本次只调用该项。每个请求从首项开始，只有明确 `not_accepted` 才进入下一项。配置文件须为普通文件，POSIX权限不得开放给group/other；API Key、端点、Prompt和下载URL都不会写入Task输出。
+`model_ref` 可省略；省略时按当前功能策略选择候选，自动池按登记顺序，手选模式按名单顺序，停用不调用。指定时须属于当前允许范围且本次只调用该项。每个请求从首项开始，只有明确 `not_accepted` 才进入下一项。配置文件须为普通文件，POSIX 权限不得开放给 group/other；API Key、端点、Prompt 和下载 URL 都不会写入 Task 输出。
 
 模型必须存在于配置的 `models` 或旧模型字段中，且具备所请求的能力；缺失时返回配置错误，不注入厂商默认模型。显式 `models:[]` 表示没有可用模型。`model_ref` 也接受裸模型名，同名跨供应商时从当前功能名单中取首个匹配项；需要精确绑定账号时使用 `providerId::modelId`。显式指定只选择该模型，不扩展 failover 候选。
 
-裸 DashScope 账号不再自动写入厂商目录或授予功能能力。已有明确保存的模型和旧能力字段绑定继续保留；独立 CLI 配置同样需要声明模型并分配给功能。
+裸 DashScope 账号不自动写入厂商目录或授予功能能力。已有明确保存的模型和旧能力字段绑定继续保留；独立 CLI 配置同样需要声明模型用途，并明确启用自动池或配置手选名单。
 
 生图按每个模型的有效图片协议调用，保存真实 PNG/JPEG/WebP 字节。聊天改图使用 `source_artifact_id`，创建关联原图的新 Artifact；具体参数和协议限制见 [模型级图片协议](CLI_MANAGEMENT.md#模型级图片协议) 与 [Artifact 聊天改图](CLI_MANAGEMENT.md#artifact-聊天改图)。
 
@@ -138,7 +138,7 @@ dsh-iris task inspect task_0123456789abcdef01234567 \
 
 新建 Attempt 可选保存 `stageTimestamps`：排队、开始提交、提交响应、远端终态、开始下载、下载校验完成和本地 Artifact 处理完成七个边界。字段按发生顺序单调不减；旧记录缺失该字段仍可读取。重新交付会从新的下载开始边界重新计时，不伪造尚未跨过的阶段。
 
-新建Attempt还可选保存 `selectionReason`：`explicit` 表示调用方明确指定名单内模型，`assignment` 表示按提交当时的功能名单选择。`pool` 保留为旧记录的历史来源，0.2.4不再产生池补齐候选。该事实随Attempt在Provider submit前落盘；`task inspect` 只展示持久记录，不按当前assignment事后猜测。旧记录缺少字段时保持缺失；第几次failover仍看 `ordinal`。
+新建 Attempt 还可选保存 `selectionReason`：`explicit` 表示调用方明确指定允许范围内的模型，`assignment` 表示按提交时的手选名单选择，`pool` 表示自动池选择。0.2.4/0.2.5 不产生新的池补齐候选，0.2.6 在主动启用自动池后使用 `pool`。该事实随 Attempt 在 Provider submit 前落盘；`task inspect` 只展示持久记录，不按当前策略事后猜测。旧记录缺少字段时保持缺失；第几次 failover 仍看 `ordinal`。
 
 已受理的异步图片 Task 可以显式推进一次：
 

package/docs/HOST_ADAPTER_CONTRACT.md

@@ -2,6 +2,8 @@
 
 状态：**v0.1.4 内部契约与渐进迁移已完成，并通过真实 DSH 隔离 canary。** 本文固定真实消费者所需的最小边界；0.2.2 已提供独立 Core/CLI，但未冻结公开 Host SDK，也未实现完整 Local Host。
 
+Iris 0.2.6 增加 [三种功能池策略](FUNCTION_MODEL_POOLS.md)；下文“功能名单”在 0.2.6 中指当前功能允许范围，自动池也遵守相同的 Host 边界。0.2.4/0.2.5 采用严格名单。
+
 ## 目标
 
 Host Adapter 只负责把一个宿主的工具、路由、客户端、附件、会话、浏览器和模型能力映射为 Iris 端口。Command 接收 Iris 输入、`AbortSignal` 和所声明的 Host Port，**不得接收原始 `ctx`**。Task、Provider、文件持久化和成本语义不属于宿主。
@@ -20,10 +22,13 @@ Host Adapter 只负责把一个宿主的工具、路由、客户端、附件、
 | `sessions` | `ctx.get('sessionQuery')` / Client sessions | 列出当前会话的受支持附件和最小模型选择信息 | 只使用 Iris 自有产物或显式上传 |
 | `browser` | `ctx.get('browser')` | 将受限 HTML 渲染为图片；不向 Command 暴露 DSH page/session 对象 | HTML 截图不可用 |
 | `textModel` | DSH LLM/default-model 服务 | 文本生成及精确模型元数据；当前宿主视觉也由此绑定默认选择 | 宿主文本/视觉不可用，自持 Provider 按各功能名单执行 |
+| `providerConnections`（0.2.6） | DSH LLM 目录、settings 与 credentials 服务 | 列出无密钥的连接元数据；仅在服务端操作期间解析所引用连接 | 连接引用不可用，手动供应商不受影响 |
 | `visionModel` | DSH 旧视觉桥接 | 保留 `analyze()` 兼容入口；当前视觉共享端口经 `textModel` 与附件桥接执行 | 旧桥接不可用，不自动授予视觉功能调用资格 |
 
 `ports` 只包含真实可调用的方法对象。缺失或版本不兼容的能力进入 `unavailable`，并提供 `kind` 与人类可读 `reason`；Doctor 与运行错误必须消费同一份事实。
 
+0.2.6 在 DSH 适配边界使用 `providerConnections.list()` 和 `resolve(reference, { signal })`。前者不读取密钥值，后者只返回操作期间的服务端连接信息；Core 接收已经解析的普通 Provider 参数，不接收该端口、DSH 对象或凭据引用。使用 DSH 连接的生成、发现、视觉及任务恢复条件依赖此端口，普通手动配置不依赖。详见 [连接复用](DSH_PROVIDER_CONNECTIONS.md)。
+
 ## Command × Host Port 矩阵
 
 | Command/入口 | 必需端口 | 可选端口 | 说明 |
@@ -43,7 +48,7 @@ Host Adapter 只负责把一个宿主的工具、路由、客户端、附件、
 | Workbench/API/媒体路由 | `routes` | `clientSlots` | HTTP/UI 只是投影，不是真相来源 |
 | 随包 Skill | `skills` | 无 | Skill 不得绕过 Command、Task 或费用边界 |
 
-开发树中的宿主视觉必须以 `host:current-vision` 加入视觉名单并排序；读取的是DSH当前默认选择，不是当前对话选择。不自动追加宿主候选，临时指定失败也不回退。升级规则见 [功能模型分配](FUNCTION_MODEL_ASSIGNMENTS.md)。
+宿主视觉必须以 `host:current-vision` 加入视觉名单，或在自动池中明确启用宿主视觉；读取的是 DSH 当前默认选择，不是当前对话选择。不自动追加宿主候选，临时指定失败也不回退。升级规则见 [功能模型池](FUNCTION_MODEL_POOLS.md)。
 
 ## 不可违反规则
 
@@ -86,7 +91,7 @@ Iris 继续作为普通 DSH/Cordis 插件装载：`cordis.patch.yml` 只把 npm
 ## 当前覆盖
 
 - `lib/index.js` 负责 DSH 插件入口、生命周期和工具注册；
-- `lib/dsh-host-adapter.js` 映射九类命名端口；
+- `lib/dsh-host-adapter.js` 映射上述命名端口；
 - Local Host fixture 覆盖 crop/diff、Task 查询与提醒操作，并验证缺失能力的错误；
 - Host Doctor 对服务端注册账本、客户端版本和 Slot 握手分别给出结果；
 - 已发布 Iris `0.1.4` 在 DSH `0.1.2-rc.1` 与 `0.1.5-rc.1` 上有历史宿主验证记录，不继承为当前版本的支持声明。

package/docs/HOST_DOCTOR.md

@@ -5,7 +5,7 @@ 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.4检查17工具/3项Skill |
+| `host` | 运行中 DSH 的 `GET /iris/api/doctor` | DSH与Host Port、插件、当前工具/Skill、4组路由、Browser/附件/模型、客户端版本和4个UI Slot；Iris 0.2.6保留17工具/3项Skill |
 
 0.2.4新增 `iris_import_image`，图片导入自身不调用模型。0.2.3检查16工具/3项Skill，发布状态见 [README](../README.md)。
 
@@ -23,7 +23,7 @@ Host Doctor 是 Iris 在运行中的 DSH 实例内提供的兼容性诊断。它
 /iris/api/doctor
 ```
 
-这是工作台路由下的 JSON 端点，继承 Iris 路由的 Host/认证边界。HTTP 200 表示诊断成功生成，不代表所有检查健康；应读取响应中的 `exitCode`：
+这是工作台路由下的 JSON 端点，使用 Iris 的回环/显式 trusted Host 和浏览器来源守卫；这些检查不提供身份认证，也不能假定该路径继承 DSH `/api` 的认证。对外暴露时须由部署者提供认证和访问控制，见 [安全边界](SECURITY.md)。HTTP 200 表示诊断成功生成，不代表所有检查健康；应读取响应中的 `exitCode`：
 
 - `0`：当前可观察项全部健康；
 - `1`：存在可降级警告，例如页面尚未打开、可选 Browser 缺失；

package/docs/MUSIC.md

@@ -13,9 +13,9 @@ Iris 0.2.3 提供独立音乐生成能力。配置音乐模型后，可以通过
 1. 添加音乐服务的供应商，填写实际 Base URL 和 API Key；Base URL 应包含服务要求的 API 前缀，例如 `/v1`。
 2. 发现或手动添加实际模型，为它设置“音乐”功能标签。
 3. 在模型的“音乐协议”中选择“Chat Completions（内嵌音频）”。
-4. 在“能力分配”中将该模型加入音乐名单。
+4. 在“功能池与调用方式”启用音乐自动池，或选择“仅用所选模型”并将它加入名单。0.2.3–0.2.5 只能使用手选名单。
 
-音乐仅使用明确分配的名单；未分配时会提示配置缺失。发现模型、添加标签或修改协议不会提交生成请求。音乐协议独立于账号和模型的图片协议。
+音乐遵守当前功能允许范围；没有合格候选时提示配置缺失。0.2.6 自动池仍要求确认用途并明确音乐协议，停用不能由临时指定绕过。发现模型、添加标签或修改协议不会提交生成请求。音乐协议独立于账号和模型的图片协议，详见 [功能模型池](FUNCTION_MODEL_POOLS.md)。
 
 配置文件中的 `musicProtocol` 使用现有标识 `gemini-web-music`，以兼容已有配置；这个标识不要求供应商或模型必须命名为 Gemini。
 

package/docs/PROVIDER_HEALTH.md

@@ -1,6 +1,28 @@
 # Provider 与能力健康状态
 
-状态：**Iris 0.2.2**。新增短时限流冷却与明确额度/预算耗尽停用，沿用既有持久健康证据。
+版本要求：**Iris 0.2.6**。包含能力检测、目录与模型可用性；沿用短时限流冷却、明确额度/预算耗尽停用及持久健康证据。发布状态见 [README](../README.md)。
+
+工作台的“能力状态与检测”与 [功能模型池](FUNCTION_MODEL_POOLS.md) 配套；以下健康证据规则继续适用。
+
+## 工作台检测入口
+
+能力检测默认折叠，只展示六项能力的近期成功与调用受阻摘要；点击“展开检测”后查看图片、视频、语音、音乐、转写、视觉六张能力卡及候选覆盖，例如“2个可用 · 1/2近期成功”。点卡片展开候选模型、最近验证时间和检测操作；供应商中的中文能力标签会直接展开检测区并打开对应详情。桌面随面板宽度排列，手机单列，适配宿主深浅主题。
+
+工作台统一分区、标题、按钮和表单样式。功能池、创作工具、快捷偏好、诊断和历史按需展开，运行中及需要处理的任务直接展示；检测跳转会展开对应的功能设置或创作工具分区。折叠不取消正在执行的实测，也不清空已经返回的结果；未提交的实测确认在折叠时关闭，重新展开后需再次确认。
+
+“检查配置”只读取当前分配、供应商元数据及历史健康状态，不调用模型，不把连接存在或模型名称当作实测成功。旧服务端缺少新策略字段时暂停实测，提示重新加载 DSH。真实实测先展示测试内容、具体模型及可能费用，确认后只调用这一项；提交前重新检查当前范围，停用、移出池、用途待确认或连接未就绪均不会提交。
+
+图片使用红色圆形测试图，语音合成“你好”，视觉识别内置红图。视频、转写、音乐及宿主视觉提供“前往功能验证”，打开实际任务表单，用户填写素材并选择模型后提交；打开表单本身不发起生成。实测结果依据现有接口返回，不额外证明媒体已经下载或可播放。
+
+逐项显示验证中、通过、未通过或结果未确认；确认期间防止重复提交。网络中断、超时或响应无法确认时保留未知结果，不自动重试；再次检查配置只读状态，不能证明上一请求未计费。冷却或额度耗尽的模型可显式实测恢复，仍须满足当前功能范围及连接要求。
+
+### TTS 的接口与音色限制
+
+当前接入 Qwen-TTS 普通 HTTP 合成，例如 `qwen3-tts-flash`；模型在具体账号、地域是否可用仍须实测。Qwen 的 `realtime` 语音模型使用 WebSocket；Qwen-Audio-TTS、CosyVoice、Sambert、MiniMax 语音系列需要各自的接口或参数适配，不能共用现有请求。已知接口缺口会显示具体原因、排除自动池并在手选提交时本地拒绝；从旧模型入口触发检测也只会跳过，不发送请求、不写成供应商实测失败。发现或确认 TTS 用途本身不证明接口已经接入。见[官方模型与协议对照](https://help.aliyun.com/zh/model-studio/tts-model/)及[Qwen-Audio-TTS HTTP 接口](https://help.aliyun.com/zh/model-studio/qwen-audio-tts-http-api)。
+
+复刻（`vc`）和声音设计（`vd`）模型需要与模型匹配的自建音色。固定“你好”探针没有音色素材，因而跳过；实际使用时先创建音色，再到语音功能填写对应音色 ID，不能自动沿用普通模型的 `Cherry`。
+
+遇到 `Model not exist`，先核对错误中的模型 ID、请求域名所属地域及该模型的接口。不要把整个供应商判为不可用，也不要批量重测其他模型。可先确认一个与现有 HTTP 接口匹配的模型用途，再单独确认费用进行实测；发现的新模型仍需确认，旧模型不会被自动删除或替换。修正后的提示保留上游错误与 HTTP 状态，不自动换地域、模型或重试。普通版请求格式见[官方 Qwen-TTS HTTP 文档](https://help.aliyun.com/zh/model-studio/qwen-tts-api)。
 
 Iris 用持久化证据描述“当前配置是否存在、最近是否实际成功、是否出现明确凭据失败”。它不是后台监控，也不等同于 Host Doctor。
 
@@ -15,6 +37,8 @@ Iris 用持久化证据描述“当前配置是否存在、最近是否实际成
 
 状态按 `Provider × Model × Capability` 记录，不因同名模型而合并。模型、Key、Base URL、协议或能力模型等关键配置变化会清空相关旧证据；移除模型或能力标签也会移除不再成立的记录。
 
+0.2.6 单独保存“当前连接明确返回模型不存在”的可用性证据：健康详情显示隔离原因，自动请求跳过该模型，历史成功仍保留。核对目录后可单独实测恢复；目录中列出仅证明发现信息，不能覆盖失败或算作成功验证。目录快照按需缓存，工作台默认折叠；只读配置检查不会同步或实测。完整边界见 [目录更新与候选可用性](FUNCTION_MODEL_POOLS.md#目录更新与候选可用性)。
+
 模型可单独设置 `imageProtocol`，未设置或 `auto` 时继承账号默认。改变有效图片协议只使该模型的生图验证失效；同模型的视觉验证、其他模型及冷却/额度停用均保留。再次选择同一有效协议不清空验证。设置入口见 [CLI 管理命令](CLI_MANAGEMENT.md)，DSH 模型池的生图模型行也可修改。
 
 ## 什么会改变状态
@@ -47,7 +71,7 @@ HTTP 状态、供应商错误码和明确错误说明一起决定路由规则，
 3. 所有已配置候选均受阻时显示调用受阻；若全部只是冷却，显示琥珀色及最早恢复时间；
 4. 没有候选时为灰色。
 
-主泡泡再按五项能力使用同一保守规则汇总。汇总证据时间只从决定汇总颜色的候选中选择，例如绿色不会显示另一条较新蓝色临时观察的时间。界面同时显示文字和证据时间，不要求用户只凭颜色判断。
+主泡泡再按六项能力使用同一保守规则汇总。汇总证据时间只从决定汇总颜色的候选中选择，例如绿色不会显示另一条较新蓝色临时观察的时间。界面同时显示文字和证据时间，不要求用户只凭颜色判断。
 
 ## 与诊断的区别
 

package/docs/ROADMAP.md

@@ -4,11 +4,12 @@ Iris 的方向是本地优先、Agent 可调用的多模态创作工作台。用
 
 ## 当前状态
 
-本文对应 **Iris0.2.5**，发布状态见 [README](../README.md)。包名为 `@mokuyoaxis/dsh-iris`，同时提供DSH插件与独立CLI；本版恢复旧宿主支持，详见 [0.2.5发布说明](releases/0.2.5.md)。
+本文对应 **Iris 0.2.6**，发布状态见 [README](../README.md)。包名为 `@mokuyoaxis/dsh-iris`，同时提供 DSH 插件与独立 CLI；本版增加连接复用、可选自动池和目录同步，详见 [0.2.6 发布说明](releases/0.2.6.md)。
 
 - 图片生成、Artifact ID 看图/OCR/定位和聊天改图，支持按模型配置图片协议。
-- 持久图片导入与原生Qwen改图，六类功能统一严格分配及显式宿主视觉，见 [0.2.4发布说明](releases/0.2.4.md)。0.2.5将DSH范围扩为12个准确版本。
-- 视频、S2V、TTS、转写与音乐生成，共用任务、音频/视频作品和导出入口；音乐使用明确分配名单。
+- 持久图片导入与原生 Qwen 改图；六类功能可选自动池、手选或停用，宿主视觉需明确启用。0.2.5 建立的 12 个准确 DSH 版本范围保持。
+- 视频、S2V、TTS、转写与音乐生成，共用任务、音频/视频作品和导出入口；音乐遵守当前允许范围并明确音乐协议。
+- DSH 连接引用、模型用途确认、按需目录快照与精确模型不存在隔离；能力检测和高级分区默认折叠，实测单独确认费用。
 - 三项 Agent Skills 分别指导单步操作、多步骤创作和界面验收；配乐与检查按用户目标加入。
 - 提示词的忠实整理、明确改写、可选建议与预览；完整同步媒体结果缓存后的交付恢复。
 - 工作台全媒体筛选、分页、跨页选择和下载，CLI 的配置、查询与可恢复维护。
@@ -43,6 +44,7 @@ DSH 工作台与 Headless CLI 共用 Core 的可恢复隔离和恢复入口，
 - 冻结中立 TextModel Port，把 Ollama、兼容文本端点及其他文本模型后端与媒体 Provider Catalog 分离，避免通用文本模型淹没 Iris 媒体模型界面；
 - 接入 ComfyUI、本地 TTS 等本地媒体 Provider，并补齐 `auth: none`、`billing: none`、同步完成语义和本地/远程 UI 区分；
 - 有可信价格来源后的成本与策略展示。
+- 显式授权后的目录新模型跟随、新语音协议及磁盘占用管理；当前自动池不自动授权目录新增模型，也没有跨请求轮转。
 
 ### 0.3 及以后
 

package/docs/SECURITY.md

@@ -1,6 +1,6 @@
 # Iris 安全边界
 
-状态：Iris 0.2.2 安全边界。安全目标是避免凭据泄露、路径越权、跨站写入和因错误重试造成重复计费；Iris 与 DSH 仍是本机同一信任域内的预览软件，不构成多租户安全边界。
+版本：Iris 0.2.6，发布状态见 [README](../README.md)。安全目标是避免凭据泄露、路径越权、跨站写入和因错误重试造成重复计费；Iris 与 DSH 仍是本机同一信任域内的预览软件，不构成多租户安全边界。
 
 ## 信任模型
 
@@ -13,10 +13,14 @@
 
 供应商凭据保存在 `$DSH_HOME/iris/v1/providers.json`。POSIX 上 Iris 创建的目录和文件分别使用 `0700` 与 `0600`，启动时会在不跟随符号链接的前提下收紧既有 Iris 树。Windows mode 不等同于 ACL，仍依赖当前用户目录和系统账户权限。
 
-API、SSE 和 Doctor 只返回凭据存在性或掩码提示。Provider 错误会移除 Bearer token、常见 Key、签名查询参数、堆栈和私有绝对路径。不要把 `providers.json`、环境变量或含签名的临时 URL 上传到 Issue。
+[DSH 连接复用](DSH_PROVIDER_CONNECTIONS.md)对引用条目只保存宿主连接标识，不保存密钥或普通 Base URL。连接列表使用脱敏设置与凭据存在性，不读取值；执行操作时才通过公开凭据接口取得内存副本。副本按异步操作隔离，不回写配置、Task、Artifact、HTTP 状态或日志。OAuth 和自定义请求头不会被猜测转换为 Bearer 认证。
+
+API、SSE 和 Doctor 只返回凭据存在性或掩码提示。Provider 错误会移除 Bearer token、常见 Key、签名查询参数、堆栈和私有绝对路径。0.2.6 的媒体 Provider Adapter 还会在截断之前移除本次已知 API Key，覆盖无固定前缀的密钥及错误码中的回显。不要把 `providers.json`、环境变量或含签名的临时 URL 上传到 Issue。
 
 健康证据与供应商配置同存于 `providers.json`，只保存模型、能力、时间、来源、错误分类、可选 HTTP 状态和脱敏短说明；状态 API 不返回完整 Key。关键凭据、端点或协议变化会清空旧证据，避免把另一组配置的成功错误沿用为当前事实。
 
+模型目录与可用性证据也保存在该私有配置中，只写入固定形状的模型/能力数据、时间与连接摘要，不保存解析后的凭据。摘要用于判断连接变化，不是身份认证。新自动请求可能按需读取目录；只读配置查询、手选请求及旧任务恢复不隐式同步或付费实测。目录出现新模型不授权使用，未列出也不自动删除或阻断；具体规则见 [功能模型池](FUNCTION_MODEL_POOLS.md)。
+
 `ai-paint` 是维护者未公开的本地前身，不是用户依赖。Iris 只有在用户显式设置 `IRIS_IMPORT_WORKBENCH_CONFIG` 为绝对路径且自身配置为空时才做一次性导入，不扫描其他项目，也不回写来源文件。
 
 ## 受理与费用安全
@@ -48,6 +52,12 @@ API、SSE 和 Doctor 只返回凭据存在性或掩码提示。Provider 错误
 - SSE 使用同源连接、节流和背压合并；慢消费者只保留最新快照，避免积压历史状态。
 - 如果把 DSH 通过 LAN、反向代理或隧道暴露，必须由部署者另加真正的认证、TLS、访问控制和来源限制。
 
+## 图像处理依赖
+
+0.2.6 将 `sharp` 最低版本提高到 `0.35.5`，锁文件同步其修复后的预编译依赖，以处理 [librsvg 高危公告 GHSA-wq5f-xc86-pv6w](https://github.com/lovell/sharp/security/advisories/GHSA-wq5f-xc86-pv6w)。公告涉及特定 glibc Linux 运行条件下的 SVG 内存安全问题；这不是本项目已发生利用的证据。只检查文件扩展名不能代替更新解码器。
+
+若部署时自行替换为系统 libvips/librsvg，应单独核对系统库修复版本；npm 锁文件和审计不覆盖自行安装的系统库。公开图片导入仍限制静态 PNG/JPEG/WebP，内部摘要使用程序构造的 SVG 标签。
+
 ## 离线 Doctor
 
 `dsh-iris doctor` 不启动 DSH，不发送供应商或计费请求，也不打印 API Key。默认 DSH 模式会在 Iris 数据目录或最近可写父目录创建一个随机小文件并立即删除，用于验证真实写权限；显式 `--data-root <abs>` Core 模式只读检查指定根的结构、索引、任务和租约，不做写探针，也不自动释放租约。`--json` 与文本输出使用同一结果模型，退出码为：`0` 正常、`1` 有警告、`2` 有硬错误。

package/docs/VISION_CLI.md

@@ -1,6 +1,6 @@
 # 独立视觉 CLI
 
-状态：**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 帧不需要。
+版本要求：**Iris 0.2.6**。发布状态见 [README](../README.md)；安装 `npm install @mokuyoaxis/dsh-iris@0.2.6` 后运行 `npx dsh-iris ...`，或从源码运行 `node bin/dsh-iris.js ...`。需要 Node.js ≥ 22、依赖 Sharp；从视频文件抽帧还需要 PATH 中的 ffmpeg、ffprobe，复用既有 Core 帧不需要。
 
 ## 四个命令
 
@@ -95,7 +95,7 @@ dsh-iris vision summarize \
 }
 ```
 
-0.2.4省略 `--model-ref` 时仅按 `assignments.vision` 名单排序，不补入模型池。只有本地不可用、明确拒绝或正常空正文才允许下一候选；截断、未知终态、收到正文后的失败、取消和超时停止调用。显式 `--model-ref providerId::modelId` 须已分配且只绑定该账号与模型，失败不会替换；新视觉命令不接受裸模型名。模型需启用并声明vision能力，未配置时直接失败。自持视觉支持OpenAI-compatible Chat Completions SSE；CLI不能执行DSH宿主视觉资源。见 [功能模型分配](FUNCTION_MODEL_ASSIGNMENTS.md)。
+省略 `--model-ref` 时按视觉功能策略排序：自动池使用已确认用途的合格模型，手选模式只用 `assignments.vision` 名单，停用不调用。只有本地不可用、明确拒绝或正常空正文才允许下一候选；截断、未知终态、收到正文后的失败、取消和超时停止调用。显式 `--model-ref providerId::modelId` 须在允许范围内且只绑定该账号与模型，失败不会替换；视觉命令不接受裸模型名。模型需启用并声明 vision 能力，未配置时直接失败。自持视觉支持 OpenAI-compatible Chat Completions SSE；CLI 不能执行 DSH 宿主视觉资源。见 [功能模型池](FUNCTION_MODEL_POOLS.md)。
 
 成功JSON携带实际`modelRef`、`selectionReason`（`explicit` / `assignment`）、模型身份、正常终态及可用usage；旧记录的`pool`来源仍可读取。OCR实际选择保留在每个成功块上。配置凭据、端点和原始错误响应不会出现在诊断中；模型回答和OCR正文是用户内容。
 

package/docs/releases/0.2.6.md

@@ -0,0 +1,50 @@
+# Iris 0.2.6：连接复用、功能模型池与目录同步
+
+0.2.6 减少首次配置的重复操作，并根据当前连接的目录和明确失败更新候选状态。安装要求见 [README](https://github.com/mokuyoaxis/dsh-iris/blob/v0.2.6/README.md)，本版升级方式与验证范围如下。
+
+## 配置与模型选择
+
+- 工作台可引用 DSH 已有的 API Key 连接，只保存连接标识，操作时取得地址与凭据；也可继续手动配置。缺少宿主接口、OAuth 或自定义认证时明确说明限制。独立 CLI 仍使用显式私有配置。
+- 六类功能可选自动池、仅用所选模型或停用。首次确认模型用途时可同时启用所选功能的自动池，免去再次分配。自动池按登记顺序选择，只有明确未受理才安全切换，没有跨请求轮转。
+- 旧手工名单、缺失/空分配及停用状态不会自动启用或扩池。新发现模型须确认用途；临时指定须在当前功能允许范围内且只调用该项。
+
+详见 [连接复用](https://github.com/mokuyoaxis/dsh-iris/blob/v0.2.6/docs/DSH_PROVIDER_CONNECTIONS.md) 和 [功能模型池](https://github.com/mokuyoaxis/dsh-iris/blob/v0.2.6/docs/FUNCTION_MODEL_POOLS.md)。
+
+## 目录与能力检测
+
+自动请求前按需同步完整目录，成功缓存 10 分钟，同连接并发合并；失败保留旧快照并短暂退避。目录未列出不证明模型下线，不删除手工配置。当前连接在新提交或实测中明确返回模型不存在时，仅隔离该模型及能力，保留历史成功；核对后可单项实测恢复，旧任务查询不改变此阻断。
+
+能力状态卡提供检测直达、配置检查与单模型实测。实测先确认费用，忙碌时防止重复提交；未知结果提示核对已有记录。视频、音乐、转写引导至真实任务，不提交空样本探针。
+
+TTS 会预先说明尚未支持的实时 WebSocket/其他语音接口，以及复刻/设计模型的专用音色要求。模型不存在错误提供模型 ID、请求域名及地域/协议排查方向。这些修正不承诺任意账号的模型当前可用，见 [能力健康](https://github.com/mokuyoaxis/dsh-iris/blob/v0.2.6/docs/PROVIDER_HEALTH.md)。
+
+## 工作台与安全修正
+
+工作台统一卡片与控件样式并收紧留白。能力检测、功能池与高级分区默认折叠，保留摘要、草稿及正在执行的请求。关闭时只显示“展开”，打开时只显示“收起”；客户端会原位更新旧样式，避免旧 CSS 残留导致双文案。
+
+媒体适配层在截断错误前移除本次已知密钥，覆盖无固定前缀 API Key 的上游回显。`sharp` 最低版本提高至 `0.35.5` 并更新锁文件，处理 librsvg 高危公告；见 [安全边界](https://github.com/mokuyoaxis/dsh-iris/blob/v0.2.6/docs/SECURITY.md#图像处理依赖)。
+
+## 安装与升级
+
+```bash
+dsh plugin --profile web add @mokuyoaxis/dsh-iris@0.2.6
+```
+
+独立 CLI：
+
+```bash
+npm install @mokuyoaxis/dsh-iris@0.2.6
+npx dsh-iris --help
+```
+
+将 `web` 替换为实际 profile。先备份 Iris 私有数据，升级后让 DSH 服务端加载新代码，再刷新页面；宿主诊断应显示一致的 0.2.6。只刷新网页而服务端仍旧时，策略切换会被暂停并提示重启。
+
+Node.js 最低仍为 22.0.0，DSH 声明沿用 0.2.5 的 12 个准确版本，见 [兼容矩阵](https://github.com/mokuyoaxis/dsh-iris/blob/v0.2.6/docs/DSH_COMPATIBILITY.md)。连接复用按实际公开服务检测，缺少服务的宿主保留手动配置。
+
+读取旧配置不自动迁移。用户主动启用新策略或目录同步后会保存相应可选字段；回退旧版前应使用升级前备份，不能假定旧版识别新的策略对象。已有任务继续按原模型、协议与端点绑定观察或补交付；池中有其他模型也不会使已受理任务重新生成。
+
+## 验证范围与保留限制
+
+本版验证覆盖离线协议/任务回归、凭据隔离和错误脱敏、DSH 公开服务隔离以及实际 Chromium 中的工作台流程。模型响应使用本地夹具，不能据此宣称真实 TTS 已恢复或保证上游可用率。
+
+完整 Android 真机触摸、实际热更新、长任务进程重启接管，以及从 Iris 0.1.4 个人数据整体升级仍需单独验收。作品、回收区和同步缓存仍需用户管理磁盘占用；Music 已有显式 502 重发规则可能增加费用，见 [音乐生成](https://github.com/mokuyoaxis/dsh-iris/blob/v0.2.6/docs/MUSIC.md)。