@mokuyoaxis/dsh-iris 0.2.5 → 0.2.7

package/docs/LOCAL_API_CONTRACT.md

@@ -0,0 +1,115 @@
+# 独立本地 API 契约（0.3 / I4）
+
+0.2.7 已实现 **I4A 默认只读**与 **I4B 显式本地创建**：显式本机监听、Bearer/Host/Origin、受控流程/媒体，以及主动启用的上传/创建与持久身份接回，见 [只读 API](LOCAL_API.md)和 [本地创建](LOCAL_CREATION.md)。**继续/选择、Operation 与执行取消仍是设计稿**；本契约尚未冻结为公开 SDK，上述 I4A/I4B 入口随 npm 0.2.7 分发。
+
+当前固定流程的真实执行入口仍是 [CLI](IMAGE_FLOW.md)；[独立 Web Demo](WEB_PROTOTYPE.md)只消费内存演示，保留到 0.3.0 阶段统一润色。它尚未接入只读 API，也不作为完整服务或写操作已经实现的依据。
+
+## 1. 实例与启动
+
+一个服务实例显式绑定一个已初始化的专用 Flow 根和一个 Application Runtime。Provider 配置来源可显式提供，省略时仍可查看已有流程/图片，启用本地写入后也可上传；模型列表返回未配置，不能创建新 Run。由用户主动启动，固定仅监听 `127.0.0.1`；首次不支持远程监听、代理转发或自动扫描 DSH 配置。CLI 的 `flow init` 仍负责初始化新根，浏览器不能指定根路径、初始化旧根或变更 Provider 配置。
+
+API 使用 `/api/v0` 前缀，后续静态页面须与 API 同源。只有 HTTP 适配器负责验证外部输入、生成受控 DTO 和管理请求；不得把 `application.execute(name, input)`、现有 DSH `serveApi` 或 CLI 参数作为通用 HTTP 转发口。模型来自显式配置中允许改图的候选，Flow 继续绑定单一明确模型与 `n=1`。
+
+I4B 的上传与 Run 创建均不生成，完成本地提交后返回 201，同 Key 接回返回 200。`api init` 先在空的已初始化 Flow 根建立请求区，`api serve --allow-local-writes` 才开放这两个 POST，不自动转换已有创作根。默认启动仍只读。
+
+## 2. 身份与浏览器边界
+
+- 每次启动产生 32 字节随机会话 Token，CLI 通过必填 `--token-file` 写入新的根外私有文件（POSIX 0600），不打印 Token。服务鉴权使用 Token 摘要和等时比较；调用进程读取私有文件，以 `Authorization: Bearer …` 发送，不进入 URL、命令行参数、Run、日志或错误文本。未来浏览器只在标签页内存保留 Token；页面重新连接不开始生成。首版文件交付替代最初的终端显示提案，支持自动化且避免管道日志收集 Token。
+- **所有 API，包括模型列表、状态与媒体，都验证身份**；Token 比较使用等时比较。首版不使用 Cookie，也不建立“同源就已认证”的假设。退出页面丢弃客户端 Token；停机使该进程 Token 失效。
+- `Host` 必须精确匹配实际监听 authority。带 `Origin` 的请求仅允许该页面精确 origin；`Origin: null`、外站 origin 和不匹配 Host 拒绝，不采信 `Forwarded` 或 `X-Forwarded-*`。无 Origin 的本机 CLI 请求仍须通过 Host 与 Token 检查。不同 origin 的 OPTIONS 不开放 CORS。
+- 当前 API 响应使用限制性 CSP。未来页面的脚本/样式只从本站加载，无内联脚本、第三方资源、对象、框架嵌入或表单提交；用户内容用文本节点展示，媒体通过带认证的 fetch 获取 Blob 后展示/下载，不将 Token 放入 `<img>` URL。
+- JSON、状态、媒体和错误响应使用 `Cache-Control: no-store`、`X-Content-Type-Options: nosniff`；API 不重定向到 Provider URL。首切片仅为意外服务错误记录净化调用帧与关联 ID。若增加访问日志，只记录方法、固定路由类型、状态、随机关联 ID 与耗时，不记录 Authorization、正文、查询参数或绝对路径。
+
+Bearer、Host/Origin 与 CSP 是不同边界，不能相互替代。静态预览器没有凭据或 Core 权限，它的验证不等于这里的认证验收。
+
+## 3. 有限路由
+
+下列除 Operation 外的 GET 路由已实现，并支持同样鉴权的 HEAD；I4B 只实现 images/runs 两个 POST，其他 POST 与 Operation 查询仍是提案。JSON 响应含 `contractVersion: 0`；列表最多 30 项，摘要不含 Prompt；创建 JSON 上限 64 KiB，Prompt 使用现行生成输入约束。未知/重复查询参数和带正文的只读请求拒绝。
+
+| 方法与路径 | 输入 | 语义 |
+|---|---|---|
+| `GET /session` | 无 | 返回实例标识、契约版本、允许的操作与输入上限；不返回根路径、Key 或端点 |
+| `GET /models` | 无 | 返回当前可选的 `modelRef`、显示名和是否支持改图；不会探测 Provider、同步目录或修改用途 |
+| `POST /images`（I4B） | 原始 PNG/JPEG/WebP 字节、匹配的 Content-Type、Idempotency-Key | 本地提交后返回 201 和 Artifact 引用，同 Key 接回返回 200；不接受文件路径、URL、目录或 SVG |
+| `GET /runs` | `cursor`、`limit`，limit 1–30 | 已有流程摘要，不含 Prompt；只读，不观察远端 |
+| `POST /runs`（I4B） | `{sourceArtifactId, modelRef, prompt, size?}`、Idempotency-Key | 固定 `image-edit/v0` / `n=1`，只保存输入与身份，零生成请求；本地提交后 201，同 Key 接回 200 |
+| `GET /runs/:id` | 无 | 返回下述 FlowView；只读，不创建 Task、补交付或继续步骤 |
+| `POST /runs/:id/continue` | 空 JSON、Idempotency-Key | 显式首次提交、单次观察原任务、补交付或本地比较；不重提已有 Attempt |
+| `POST /runs/:id/selection` | `{artifactId}`、Idempotency-Key | 只接受该 Run 的原图/新版；不触发生成或下载 |
+| `GET /artifacts/:id/content` | 无 | 按已验证 Artifact ID 和清单读取该根内媒体字节，不接受 path/URL 参数；不写文件 |
+| `GET /runs/:id/download` | 无 | 返回已选择图片的原字节及受控附件名；未选择则冲突，不接受服务器输出路径 |
+| `GET /operations/:id`（待实现） | 无 | 查询本实例操作状态，不能借此继续操作 |
+| `POST /operations/:id/cancel` | 空 JSON | 停止本次排队/等待，幂等；不代表远端生成已撤销或已退款 |
+
+上传累积读取限制使用现有 `MAX_IMPORT_IMAGE_BYTES = 20 MiB`，不能只相信 Content-Length；最终交给 `readImportImage({imageBytes}, signal)` 检查实际格式和静态图片要求。连接关闭、超量与解析失败不留下临时可服务文件，不把 filename 当服务器路径。并发上传上限 1，超过返回忙；用户显式重试复用原 Key。
+
+上传复用现有图片验证与 Artifact 预留 ID 提交；请求与作品在同一次 writer 内保存。当前图片读取/下载仍限 64 MiB，类型 PNG/JPEG/WebP，先检查清单大小再校验内容哈希，最多两个活动读取。大型媒体磁盘流式、Range 和音视频仍待后续。下载不调用服务器本地 `flow.export(output_path)`；浏览器是否保存成功不属于持久 Run 事实。
+
+## 4. FlowView 与操作反馈
+
+浏览器只消费白名单投影，不直接接收磁盘 Run、完整 Task、Attempt、Provider 错误对象或配置。完整详情是用户创作数据，需要认证；摘要不包含 Prompt。
+
+```text
+FlowView {
+  contractVersion: 0,
+  id, recipe: "image-edit/v0", revision, createdAt, updatedAt,
+  status: not_started | running | needs_attention | delivery_failed |
+          needs_comparison | awaiting_selection | selected,
+  input: { prompt, modelRef, size? },
+  source: { artifactId },
+  output: { artifactId } | null,
+  comparison: { artifactId } | null,
+  selection: { artifactId } | null,
+  task: { id, acceptance, outcome, deliveryState, attemptCount } | null,
+  metrics: { ratio, diffPixels, totalPixels, width, height } | null
+}
+```
+
+ID 继续使用当前 `run_` / `task_` / `artifact_` 加 24 位小写十六进制。DTO 不带绝对路径、端点、绑定摘要、远端任务 ID 或任意媒体 URL。媒体信息如格式/尺寸应由独立受控投影提供，不信任用户文件名。`metrics` 仅来自实际已提交比较作品；像素差异不是质量评分。
+
+| `status` | 首要操作与文案边界 |
+|---|---|
+| `not_started` | “开始生成”；可能产生费用，输入已经固定 |
+| `running` | “查看原任务”；每次显式操作至多观察一次，页面不自行调用 continue |
+| `needs_attention` | 显示受理未知/失败/取消等事实；无自动重提。需要新生成时明确新建 Run |
+| `delivery_failed` | “恢复结果”；生成已经成功，恢复原缓存/远端结果，不新生成 |
+| `needs_comparison` | “完成比较”；执行本地步骤，不新生成 |
+| `awaiting_selection` | 选择原图或新版；下载仍禁用 |
+| `selected` | 可下载；不能据此声称文件已经保存到用户设备 |
+
+I4B 的上传与创建同步完成本地提交，以 201/200 返回 Artifact/FlowView 和 `idempotentReplay`，不返回持久排队的 202，也不开放 Operation 查询或取消。相同 Key 保证原业务身份与效果；已有 Run 的返回状态可以随真实进度变化，不承诺重放完全相同的响应字节。
+
+后续异步执行拟在持久接收后返回 `202 {contractVersion:0, operationId, runId?}`，状态为 `queued | running | succeeded | failed | interrupted`。GET 轮询只能读取，不能驱动 Provider；原任务的远端观察必须显式点击。实例内拟最多一个活动 writer、8 个等待写操作；同一 Run 已有活动 continue 时，新 Key 返回冲突，同 Key 接回原 Operation。取消直接中止对应控制器，不能排在被取消 writer 后面；停止等待不伪造远端 Task canceled。这些执行/Operation 语义须另行实现和验收，不随 I4B 自动开放。
+
+## 5. 上传与持久创建幂等（I4B）
+
+I2 保证相同 Run 使用原 Task；I4B 另保证同 Key 创建请求接回原 Artifact/Run。前端禁用按钮、内存 Map 和“成功后才写 Key → Run 映射”不能代替持久意图。
+
+新空专用根使用 `creation-requests/v0/root.json` 和 `requests/req_<64 hex>.json`，没有数据库或已有创作根迁移；现有 Task/Artifact/Run 格式保持。具体约定为：
+
+1. 客户端每次明确动作使用一个不带引号的小写 UUIDv4 `Idempotency-Key`。请求区保存稳定 rootId；命名空间按 rootId、操作种类和 Key 计算 SHA256，**不使用随重启变化的服务 instanceId、Token、端口或本机路径**。原始 Key 不持久保存或记录。
+2. 输入摘要来自规范化内容：图片的真实字节摘要、大小与 Content-Type；Run 的来源 ID、模型引用、规范化 Prompt/size、固定 recipe/n。对象键序不影响摘要，不额外改写正文。同 Key 不同内容 409；已发布意图不因模型池或端点变化另选身份。
+3. 同一个 operation-owned Core writer 内，先校验新输入并**排他发布 prepared 意图与全部预留身份**，再提交 Artifact/Run，最后原子更新 succeeded。不能通过两个独立 writer 或“先创建后补 Key 映射”实现。创建 Run 需内部受控的预留 Run/Task/比较作品 ID，浏览器不能指定它们。
+4. 已存在的 Run 按原始输入、来源/binding、创建时间和预留身份核对；允许后续 revision、输出或选择已经推进，返回当前事实，绝不覆盖回初始状态。图片复用现有 Artifact 重入提交及内容校验；未完成上传不另存原件，需客户端同 Key 重新提供相同字节。
+5. 意图发布前的验证失败、busy 或排队取消不消费 Key；发布后的断线不撤销已经接受的本地提交。启动、GET 和刷新不自动修复/重放；显式同 Key POST 才核对或补完。存储损坏或身份冲突保留现场，不能回退成随机新建；不永久缓存通用 500 并把原对象藏起来。
+6. prepared 引用保护包括预留上传对象、Flow 来源/Task/比较身份；succeeded 保留请求身份和原结果 ID，但不额外禁止显式删除未使用的上传，真实 Run/Task 引用仍保护。成功目标不可用时，同 Key 返回 `409 IRIS_API_RESULT_UNAVAILABLE`，不复活作品或重建 Run。损坏/未知请求阻止误清理，不能当作空引用；首版没有请求删除、TTL 或自动 GC，权限沿用私有约定。
+7. 新版 writer 和维护入口必须识别请求格式，未知/半初始化请求区拒绝写入。已发布旧程序没有这些新检查，不能靠一个标记保证其拒绝该根；此专用根只支持已验收的 request-aware writer，回退使用完整副本，不删除请求区伪装降级。已提交 Flow/图片仍可只读查看。
+8. 复用现有原子发布和重入能力，验证范围限进程异常退出/SIGKILL；不据此承诺断电、操作系统崩溃或共享存储下的跨文件事务。请求区本身不触发 Provider 目录刷新、探测、生成或任务观察。
+
+后续 continue/Operation 仍需独立的持久接收与中断协议；重启只展示未完成事实，**不能自动重放 continue**。I4B 的本地创建与中断证据不能代替可能计费的执行验收；开始按钮接入实际生成前，仍须补执行接收、未知受理、取消和停机测试。
+
+## 6. 错误与验收
+
+统一错误外形为 `{contractVersion:0, error:{code, message, requestId}}`，不附堆栈、配置或 Provider 原始响应。网络错误只返回已脱敏的有限分类；取消/断线不把未知改写为失败未计费。
+
+| HTTP | 类别 |
+|---|---|
+| 400 / 413 / 415 | 输入无效、正文过大、图片格式不支持 |
+| 401 / 403 | 身份无效、Host/Origin 不可信 |
+| 404 | 合法 ID 在该实例不存在 |
+| 409 | Key 输入冲突、原任务状态冲突、根被占用、同一 Run 操作活跃、尚未选择 |
+| 429 | 有界队列/上传已满，显式重试可复用原 Key |
+| 503 | 正在关闭；不再接收新写操作 |
+| 500 | 无法分类的内部错误，保留服务端关联证据并停止相应操作，不静默回退 |
+
+I4 必须实际验证：错误 Token/Host/Origin、媒体绕过、超量流式上传/损坏图片/路径参数、双击/不同 Key 并发、同 Key 响应丢失/重启、未知受理不重提、只读重连、取消时序、停机与租约释放。之后才让 [Web 原型](WEB_PROTOTYPE.md)换成真实传输并验收无 DSH 的端到端路径。本稿和静态预览不等于第二个生产 Host 已完成。

package/docs/LOCAL_CREATION.md

@@ -0,0 +1,50 @@
+# 本地上传与流程创建（0.2.7 / I4B）
+
+0.2.7 在 [只读本地 API](LOCAL_API.md)之上，增加显式启用的图片上传和固定 Run 创建。两者都只提交本地数据，不生成、不观察任务、不调用 Provider。实际生成仍使用 [Flow CLI](IMAGE_FLOW.md)；执行/取消 API 与真实 Web 接入留到后续。本功能从 npm 0.2.7 起随包分发。
+
+## 初始化与启用
+
+为这一功能选择新的专用根，先初始化 Flow，再初始化请求区：
+
+```bash
+dsh-iris flow init --data-root /absolute/path/new-flow-core
+dsh-iris api init --data-root /absolute/path/new-flow-core
+dsh-iris api serve --data-root /absolute/path/new-flow-core --token-file /absolute/private/session-001.token --provider-config /absolute/private/providers.json --allow-local-writes
+```
+
+`api init` 只接受空的已初始化 Flow 根，不转换已有创作数据。重复初始化返回原 rootId；半初始化、未知版本或损坏请求区报错并保留现场。省略 `--allow-local-writes` 时仍只读；没有 Provider 配置也可上传或读取已有结果，创建新 Run 需要显式的可改图模型配置。
+
+服务仍固定监听 `127.0.0.1`，默认随机端口；Token 文件与身份、Host/Origin、停止方法沿用 [只读入口](LOCAL_API.md)。Token 和请求 Key 是两件事：每次启动换 Token，同一次创建在网络不确定时保留原 Key。不要通过 URL、命令行参数或共享日志传 Token。
+
+## 两个本地写接口
+
+每次明确的新动作产生一个不带引号的小写 UUIDv4 `Idempotency-Key`，发送单个请求头。该 Key 不代替 Bearer 鉴权。
+
+| 路径 | 输入 | 返回 |
+|---|---|---|
+| `POST /api/v0/images` | 原始静态 PNG/JPEG/WebP 字节，匹配的 Content-Type，最多 20 MiB | `{contractVersion:0,idempotentReplay,artifact:{artifactId,mediaType,size,width,height}}` |
+| `POST /api/v0/runs` | UTF-8 JSON `{sourceArtifactId,modelRef,prompt,size?}`，最多 64 KiB | `{contractVersion:0,idempotentReplay,flow:<FlowView>}` |
+
+首次创建在本地提交完成后返回 201；同 Key、同规范化输入接回原身份，返回 200 和 `idempotentReplay: true`。同 Key 不同输入返回 409；新的 Key 表示另一明确创建，不做全局按内容去重。Run 固定 `image-edit/v0`、单一明确模型和 `n=1`，创建不建立实际 Task。模型配置只读解析，不刷新目录或实测能力。
+
+上传不接受路径、URL、文件名、SVG、动画或压缩正文；真实格式必须匹配 Content-Type。累计读取限额不只依赖 Content-Length，同时最多一个上传、最多九个本地创建请求；繁忙返回 429，同物理根有其他 writer 时返回 409，显式重试保留原 Key。
+
+超限返回 `413 IRIS_API_INPUT_TOO_LARGE`，不创建作品或消费 Key。对尚未结束的上传，先发送完整错误响应，再丢弃剩余正文并关闭连接；不继续缓存正文，连接仍受现有请求/空闲超时和服务停止约束。客户端收到拒绝后应停止上传。
+
+当前没有 `POST /runs/:id/continue`、selection、Operation 查询或取消接口。GET、HEAD、页面刷新和启动不自动执行或补完创建；现有 Demo 仍使用演示传输，尚未连接这个 API。
+
+## 重试、删除与中断
+
+请求意图、预留身份、业务提交和完成状态共用同一次 Core writer。跨进程重启、端口变化或 Token 轮换后，同 Key 仍绑定原数据根和原输入；已有 Run 后续执行或选择过，重放返回其当前 FlowView，不回退进度。已有意图不因当前 Provider 配置变化另选模型/端点，未来执行仍遵守原 Flow binding。
+
+意图发布前的输入错误、busy、排队取消或断线不消费 Key；发布后断线不撤销本地提交。未完成上传需要重新提供相同字节；显式同 Key POST 才核对或补完，没有自动后台重放。关闭服务会停止接收和等待，并保留未完成证据。
+
+未完成请求引用的来源与预留对象受删除/清理保护。成功上传如果没有其他 Run/Task 引用，仍可通过现有明确动作隔离或删除；之后同 Key 返回 `409 IRIS_API_RESULT_UNAVAILABLE`，不复活作品或新建替代身份。请求记录首版不自动过期、删除或 GC。
+
+## 数据与版本边界
+
+新私有请求区为 `creation-requests/v0`；现有 Run、Task、Artifact 格式保持，未迁移 DSH 日常数据。未知/损坏请求区使新版 writer 和维护操作报错，reader 仍可只读查看已有有效 Flow/图片。
+
+此专用根只支持认识请求格式且通过验收的 writer。旧 binary 没有新检查，不能靠一个新目录保证它拒写；不要用旧版本对该根执行写入。需要回退时使用改动前完整副本，不删除请求区伪装降级。半初始化现场不自动修复，优先另建新空根。
+
+验证范围为进程异常退出与 SIGKILL 下的身份接回；现有文件原语没有显式 fsync，不承诺断电、操作系统崩溃或 Android 共享存储上的跨文件事务。Windows/macOS 与真机使用范围须独立验证。

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.7**，本页检测入口从 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.7**，发布状态见 [README](../README.md)。包名为 `@mokuyoaxis/dsh-iris`，同时提供 DSH 插件与独立 CLI；本版增加截图修复、实例运行时、持久图片流程、本地 API 和 Core Skill 安装，详见 [0.2.7 发布说明](releases/0.2.7.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 的配置、查询与可恢复维护。
@@ -17,6 +18,18 @@ DSH与CLI共用Task和Artifact，同一数据根只允许一个写者。纯视
 
 宿主兼容继续集中在Adapter与客户端桥接。后续DSH更新优先检查实际API、工具/附件交付和输入区契约，复用同一验收入口扩充版本矩阵，避免让旧用户长期停留在缺少新功能的Iris分支。
 
+## 0.2.7 基础设施与 0.3.0 方向
+
+宿主 HTML 截图已适配浏览器返回的 PNG 数据，并增加实际监听地址解析和用户主动触发的截图自检，见 [0.2.7 发布说明](releases/0.2.7.md)与 [宿主诊断](HOST_DOCTOR.md#截图地址与主动自检027)。
+
+0.3 基础设施已接入首批 [内部应用运行时](CORE_RUNTIME_CONTRACT.md#应用运行时装配)与 [固定改图流程](IMAGE_FLOW.md)：实例写队列、稳定 Run/步骤与 Task 绑定、原任务/比较图恢复、引用保护和明确选择/导出。
+
+[DSH Core 装配](DSH_RUNTIME.md)也已迁入实例：写入共用应用队列，连接解析引用、观察器和启动接管由插件持有，卸载等待在途操作。原根与业务保持；legacy 配置等存储仍未实例化，Flow 尚未接入 DSH 工作台。
+
+0.2.7 已有 [I4A 默认只读 API](LOCAL_API.md)与 [I4B 本地创建](LOCAL_CREATION.md)：显式回环监听、Bearer/Host/Origin、受控图片，以及新空根主动启用的上传/Run 创建和持久 Key 身份接回。GET 不执行步骤，本地创建也不生成；有限执行/取消与 Operation 仍按 [API 契约](LOCAL_API_CONTRACT.md)继续。
+
+源码树保留 [面向 0.3.0 的独立 Web Demo](WEB_PROTOTYPE.md)，用于说明输入、状态、比较与选择的操作方向。当前只消费演示数据，不连接模型、不计费，也未接入 API；界面与交互细节留到 **0.3.0 阶段统一润色**。后续补执行接收、取消和恢复验收，再接入实际工作台。通用 Recipe 与实际独立工作台尚未完成，没有已承诺的发布日期。
+
 ## 近期优先：真实使用验收
 
 优先完善图片创作与配乐、短片素材准备等完整流程：复用已有作品、按需生成、试听或查看结果，再导出可继续处理的素材。分别交付音视频素材不等于自动混音成片。
@@ -39,10 +52,11 @@ DSH 工作台与 Headless CLI 共用 Core 的可恢复隔离和恢复入口，
 - Core 隔离内容的永久 purge（0.2.1 已开放可恢复隔离/恢复，legacy 永久删除保持原行为）；
 - 鸢尾花与泡泡视觉身份；
 - 有可用接口与实际需求后，补 Images 编辑、mask、多参考图或连续编辑；
-- 将提示词优化收口为 Core Prompt Engine 与共享 `prompt.optimize` Command，由 CLI 和 DSH 入口共同消费；DSH 只负责草稿读取、预览和写回；
+- 在已有纯核心提示词实现上补共享 `prompt.optimize` Command 与 CLI 消费；DSH 负责草稿读取、预览和写回；
 - 冻结中立 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.7，发布状态见 [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,20 @@ API、SSE 和 Doctor 只返回凭据存在性或掩码提示。Provider 错误
 - SSE 使用同源连接、节流和背压合并；慢消费者只保留最新快照，避免积压历史状态。
 - 如果把 DSH 通过 LAN、反向代理或隧道暴露，必须由部署者另加真正的认证、TLS、访问控制和来源限制。
 
+## 显式本地 API 与 Skill 安装
+
+0.2.7 的 [本地 API](LOCAL_API.md)由用户显式启动，只监听 `127.0.0.1`，与 DSH 路由的身份边界分别管理。每次启动产生独立会话 Token，写入新的根外私有文件；全部 API 与媒体都要求 Bearer、准确 Host 和受控 Origin，不将 Token 放入 URL 或 stdout。服务关闭后旧 Token 失效，原私有文件保留。
+
+默认 GET/HEAD 不写 Core 或调用 Provider。新空 Flow 根须显式 `api init`，并通过 `--allow-local-writes` 开启 [上传/创建](LOCAL_CREATION.md)；这两个 POST 不执行生成。请求意图与业务效果在同一 writer 内提交，同 Key 接回原身份，损坏请求保留并拒写，成功结果删除后不自动复活。固定流程的 Prompt 保存为专用根中的私有 Run 输入，不进入公共 Task/Artifact DTO；备份该根时应按私人创作数据保护。旧 writer 不得写入新流程根，回退应使用完整备份。
+
+[Core Skill 安装器](CORE_SKILLS.md)只有显式 `skills install/uninstall` 才修改目标，`status` 与 dry-run 只读。安装记录用于内容与归属检查，不能作为对恶意本机用户的认证。无归属目录、用户修改及软链不被接管；升级/卸载保留扫描根外备份，不自动清理。安装不改变模型、MCP 或宿主权限；文件完整不等于宿主已发现 Skill，也不等于 Agent 已完成业务验收。
+
+## 图像处理依赖
+
+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/SYNC_DELIVERY_RECOVERY.md

@@ -2,6 +2,8 @@
 
 Iris 0.2.3 支持从缓存恢复完整同步媒体结果。本地交付失败后，可沿原任务重新交付；Task/Artifact 格式和公开 HTTP 路径保持，不需要迁移旧数据。
 
+未发布的 [固定图片流程](IMAGE_FLOW.md)也将其绑定任务的成功 poll 结果先写入原交付缓存，再按预留 Artifact ID 交付；相应中断只接回原结果，不重新 submit。未绑定 Flow 的异步 Task 沿用原路径，本节其余内容描述 0.2.3 起的同步恢复边界。
+
 ## 使用行为
 
 同步 Images、聊天生图、Responses、TTS 或音乐 返回完整结果后，本地写入失败仍记录 `accepted / succeeded / deliveryState=failed`。工作台“重新取回作品”和 CLI `task redeliver` 共用原 Task/Attempt 的恢复路径，不调用 submit、不创建新 Attempt。

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.7**。发布状态见 [README](../README.md)；安装 `npm install @mokuyoaxis/dsh-iris@0.2.7` 后运行 `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/WEB_PROTOTYPE.md

@@ -0,0 +1,47 @@
+# 独立工作台 Demo（面向 0.3.0，未发布）
+
+这是面向 **0.3.0** 的交互预览，用来展示“选图与填写要求 → 查看状态 → 比较 → 选择与下载”的操作方向。**当前 Demo 保留作为参考，界面、文案和交互细节将在 0.3.0 阶段统一润色，尚未定稿。**
+
+Demo 可在源码树中独立预览，无需 DSH；使用内存演示与内置样图，不连接模型、不计费，也不写入 Core 数据。真实生成目前使用现有 DSH 工作台或 CLI；npm 0.2.7 不携带源码树的 prototypes/ 和预览脚本。
+
+## 启动预览
+
+在 Git 源码树中，使用现有 Node.js ≥22，无须安装新依赖：
+
+```bash
+node scripts/preview-workbench.mjs
+```
+
+终端打印 `http://127.0.0.1:<随机端口>/`，在本机浏览器中打开。可显式指定 `--port 4173`，端口占用会报错，不自动替换。Ctrl+C 关闭。预览器只监听 loopback 并提供固定静态资源，不能读取任意仓库文件、Core 数据、Provider 配置或 `.internal/`，不会启动 DSH。
+
+不要用仓库根上的通用文件服务器代替这个入口，避免把内部资料一并提供给浏览器。页面使用 JavaScript 模块，直接双击 HTML 并不等价于上述预览。
+
+## 可体验的流程
+
+1. 使用内置鸢尾花样图，或选择/拖放本地 PNG、JPEG、WebP；本地文件只生成标签页内的 Blob 预览，不上传。
+2. 选择演示模型、填写修改要求，点击“开始演示”。本次输入随后固定；修改输入需明确新建流程。
+3. 查看原图与示例结果，切换并排/叠图，明确选择原图或结果，再下载。
+4. 展开“运行详情与演示场景”，体验原任务进行中、受理未知、生成成功但交付中断、等待本地比较等状态。场景对新流程生效。
+
+**示例结果始终是内置样图，不是对上传图片或提示词的真实修改**。原图和示例结果可能相同；原型不伪造像素差异、模型质量分数、计费价格或进度百分比。下载原图取本地原字节，下载结果取内置样图；“已选择”和“下载请求已交给浏览器”分别显示，不声称文件已保存。
+
+状态名称和白名单 DTO 依据真实 [固定流程](IMAGE_FLOW.md)；投影有实际 Core/受控 Provider 测试。演示传输不读写磁盘 Run，不保证服务重启恢复。新建后可从详情中的流程列表只读切回本标签页旧记录；整页刷新清空演示状态，并且不会自动开始。未将文件、提示词或主题写入 localStorage。
+
+“停止本次等待”只中止当前演示操作，原任务事实保留；真实 API 的远端取消须有独立能力与确认，不能把停止等待写成取消成功。展开详情、重新读取状态、切换历史与比较方式均不驱动生成。
+
+## 实现和下一步
+
+原型位于 `prototypes/workbench/`，使用原生 HTML/CSS/JavaScript，复用现有图标和示例图片，没有新框架或生产依赖。运行详情默认折叠，关闭显示“展开”、打开显示“收起”；提供浅/深色、键盘焦点与 320/390px 布局。
+
+0.2.7 已有 [默认只读 API](LOCAL_API.md)及显式开启的 [本地上传/Run 创建](LOCAL_CREATION.md)，带持久请求意图和身份接回；当前 Demo 保持原样，尚未连接它们。后续补执行/取消、Operation 与恢复边界，再在 0.3.0 阶段结合实际接口统一完善页面。Demo 的当前布局、提示词和样例效果仅用于说明方向，不代表最终界面或模型能力。
+
+[本地 API 契约](LOCAL_API_CONTRACT.md)区分已实现的只读/本地创建切片与待实现的执行、选择和取消。相同 Run 的 Task 复用与 HTTP 创建幂等分别验证；执行接口安全和中断测试通过后，再替换演示传输并完成无 DSH 的实际端到端验收。
+
+源码树可运行下面的检查；浏览器检查需显式提供已经安装的 Chromium，不下载或安装浏览器。无沙箱仅在受控测试环境确有需要时显式追加 `--no-sandbox`，不改变生产浏览器策略。
+
+```bash
+node tests/web-prototype.mjs
+node scripts/verify-workbench-prototype.mjs --browser-executable /absolute/path/to/chromium --output /absolute/path/to/new-evidence-directory
+```
+
+浏览器检查保存交互结果与桌面/手机截图；这是隔离 Chromium 验收，不是 Android 真机触控或日常 DSH 装载证明。

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

package/docs/releases/0.2.7.md

@@ -0,0 +1,62 @@
+# Iris 0.2.7: screenshot compatibility, persistent image workflows, and portable Skills
+
+Iris 0.2.7 fixes DSH browser screenshots and adds explicit standalone entry points for persistent image editing, local API access, and Core Skill installation. The npm package remains `@mokuyoaxis/dsh-iris`; Node.js 22.0.0 or later is required. The twelve exact DSH versions supported by 0.2.6 are unchanged.
+
+## DSH screenshots and runtime ownership
+
+- HTML screenshots consume PNG data returned by the browser and save it through Core. The browser no longer needs permission to write into the Iris data root; its download-directory restriction can remain in place.
+- Screenshot navigation uses an explicit `DSH_WEB_BASE`, otherwise the host's public listening address, and finally the historical 3080 fallback when reliable host metadata is unavailable. Public media links retain their existing base-URL contract.
+- Host Doctor distinguishes an available Browser interface from a successful screenshot. An explicit screenshot check creates a local test artifact without calling a model; ordinary diagnosis remains read-only. Cancellation closes sessions opened during the operation.
+- DSH Core operations use an instance-owned application queue, connection references, and task observers. Unload cancels and awaits active work and lease release. Existing data roots, provider protocols, and billing rules remain intact; legacy configuration storage is outside this migration.
+
+## Standalone image workflows and local API
+
+- The fixed `image-edit/v0` CLI workflow persists a Run, private inputs, step-to-Task bindings, comparison results, and the user's selection; the selected image can then be exported. Recovery reuses existing tasks and reserved artifact identities instead of submitting uncertain work again.
+- `api serve` explicitly starts a loopback-only API that is read-only by default. It exposes selected model/workflow information and controlled image access, with a private session-token file and Bearer, Host, and Origin checks.
+- A new, empty workflow root can opt into local uploads and Run creation through `api init` and `api serve --allow-local-writes`. Durable request keys reconnect repeated requests to the original result. These endpoints do not generate media; execution and cancellation APIs remain future work.
+- Rejected uploads receive the complete error before the server closes the connection, avoiding premature resets on Windows. Remaining body bytes are discarded without buffering under the existing request and idle timeouts; shutdown also closes incomplete uploads. Size, authentication and concurrency limits remain in force.
+
+See [image workflows](https://github.com/mokuyoaxis/dsh-iris/blob/v0.2.7/docs/IMAGE_FLOW.md), [local API](https://github.com/mokuyoaxis/dsh-iris/blob/v0.2.7/docs/LOCAL_API.md), and [local creation](https://github.com/mokuyoaxis/dsh-iris/blob/v0.2.7/docs/LOCAL_CREATION.md) for commands and limits. These guides are currently in Chinese.
+
+## Portable Core Skill
+
+The package includes `iris-core`, with English instructions and bilingual titles for image import, generation, editing, task inspection, and artifact export through the standalone CLI.
+
+```bash
+dsh-iris skills install --target kimi --dry-run
+dsh-iris skills install --target kimi
+dsh-iris skills status --target kimi
+```
+
+Other harnesses can use an explicit absolute scan directory with `--directory`. Installation copies the complete Skill, records its version and content hashes, and preserves local changes. Managed upgrades and `skills uninstall` archive the previous copy outside the scan root. There is no npm postinstall hook or automatic model/MCP configuration.
+
+The original three DSH Skills remain registered as before. Successful file installation is separate from harness discovery and actual agent behavior; the status command reports `discovery: not_checked`. See [Core Skill installation](https://github.com/mokuyoaxis/dsh-iris/blob/v0.2.7/docs/CORE_SKILLS.md).
+
+## Install and upgrade
+
+For a supported DSH host:
+
+```bash
+dsh plugin --profile web add @mokuyoaxis/dsh-iris@0.2.7
+```
+
+For the standalone CLI:
+
+```bash
+npm install @mokuyoaxis/dsh-iris@0.2.7
+npx dsh-iris --help
+```
+
+Back up private Iris data before upgrading. Reload the DSH server code and refresh the client; use your actual profile name instead of `web`. This release does not automatically reload services, migrate existing roots, enable empty model assignments, or change dependency requirements. See the [compatibility matrix](https://github.com/mokuyoaxis/dsh-iris/blob/v0.2.7/docs/DSH_COMPATIBILITY.md).
+
+Use a new, dedicated root for workflow features and local creation. Older writers must not write that root; retain a pre-upgrade backup for rollback. One physical data root still permits one writer, and uncertain acceptance never permits automatic resubmission.
+
+## Scope and verification limits
+
+The source-only standalone Web demo remains an interaction reference for 0.3.0. It uses in-memory samples, does not call models, and is not connected to the local API. It is excluded from the npm package. A production standalone workbench, general Recipe engine, public Core SDK, and formal MCP server are not included.
+
+Validation covers isolated task/artifact behavior, host service integration, package execution, Skill conflict/backup handling, concurrent installers, and actual Kimi Code 2.3.0 Skill discovery/removal. Skill discovery checks submit no prompt and make no model calls; they do not establish a production Kimi adapter. Complete Android interaction, daily hot upgrades, real-provider availability, and whole-data upgrades from Iris 0.1.4 require separate validation. Historical local test-process timeouts remain under investigation.
+
+## 中文摘要
+
+0.2.7 修复浏览器截图保存目录限制、实际导航地址与取消处理，增加主动截图自检；Core/DSH 的写队列和观察器归实例持有。独立 CLI 新增持久图片流程，显式本地 API 默认只读，新空根可主动开启上传与流程创建；这些 HTTP 入口不执行生成。随包 `iris-core` Skill 可显式安装到 Kimi 或指定目录，保护用户修改并保留升级/卸载备份。DSH 原三项 Skill、12 个准确宿主版本与生产依赖保持。独立 Web 仍是面向 0.3.0 的源码演示，正式 MCP 和真实执行工作台继续后续开发。