@mokuyoaxis/dsh-iris 0.2.0 → 0.2.1

package/docs/HOST_ADAPTER_CONTRACT.md

@@ -1,12 +1,12 @@
 # Host Adapter v0 契约
 
-状态：**v0.1.4 内部契约与渐进迁移已完成，并通过真实 DSH 隔离 canary。** 本文固定真实消费者所需的最小边界；不宣称已经提供独立 Core、公开 Host SDK 或完整 Local Host。
+状态：**v0.1.4 内部契约与渐进迁移已完成，并通过真实 DSH 隔离 canary。** 本文固定真实消费者所需的最小边界；0.2.1 已提供独立 Core/CLI，但未冻结公开 Host SDK，也未实现完整 Local Host。
 
 ## 目标
 
 Host Adapter 只负责把一个宿主的工具、路由、客户端、附件、会话、浏览器和模型能力映射为 Iris 端口。Command 接收 Iris 输入、`AbortSignal` 和所声明的 Host Port，**不得接收原始 `ctx`**。Task、Provider、文件持久化和成本语义不属于宿主。
 
-契约版本固定为 `0`。它在 0.1.x 内仍是内部接口；只有经过 DSH 与 Local Host 两个真实消费者验证后，才考虑成为公开 SDK。
+契约版本固定为 `0`。它仍是内部接口；只有经过 DSH 与 Local Host 两个真实消费者验证后，才考虑成为公开 SDK。
 
 ## 端口清单
 
@@ -29,7 +29,7 @@ Host Adapter 只负责把一个宿主的工具、路由、客户端、附件、
 | Command/入口 | 必需端口 | 可选端口 | 说明 |
 |---|---|---|---|
 | `image` | 无 | `visionModel` | 生成与 Task 不依赖宿主；成功后的简短视觉描述可以降级 |
-| `video`、`tts`、`transcribe` | 无 | 无 | Provider、Task 与产物落盘属于 Iris Core 候选 |
+| `video`、`tts`、`transcribe` | 无 | 无 | Provider、Task 与产物落盘属于 Iris Core |
 | `look`、`locate`、`ocr` | 无 | `visionModel` | 优先使用 Iris Provider；没有任何视觉后端才失败 |
 | `crop`、`diff`、`video_frames` | 无 | 无 | 确定性本地动作 |
 | `media_summarize` | 无 | `visionModel` | 帧提取是本地动作，理解阶段允许宿主视觉降级 |
@@ -45,9 +45,9 @@ Host Adapter 只负责把一个宿主的工具、路由、客户端、附件、
 
 ## 不可违反规则
 
-1. Core 候选、Command、Task 和 Provider 模块不得导入 DSH/Cordis 运行时，也不得通过任意字段重新取得原始 `ctx`。
+1. Core、Command、Task 和 Provider 模块不得导入 DSH/Cordis 运行时，也不得通过任意字段重新取得原始 `ctx`。
 2. Host Adapter 只能映射宿主能力；不得复制业务校验、Provider 路由、Task 状态机、failover 或产物持久化。
-3. 宿主会话 ID 只能作为来源上下文，不能成为 Iris Task、Attempt 或未来 Artifact 的主键。
+3. 宿主会话 ID 只能作为来源上下文，不能成为 Iris Task、Attempt 或 Artifact 的主键。
 4. Command 输入和结果只能包含 JSON、字节、稳定引用与受控错误；不得持久化 page、session、service 等 live Host 对象。
 5. 能力探测必须显式、可序列化且零计费。缺能力返回稳定分类和可执行说明，不得用异常吞噬后继续猜测私有 API。
 6. 调用方的 `AbortSignal` 必须传播到 Host 操作；断开、取消和超时不得被 Adapter 转换为自动重试。
@@ -87,16 +87,16 @@ Iris 继续作为普通 DSH/Cordis 插件装载：`cordis.patch.yml` 只把 npm
 - `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` 上有历史宿主验证记录，不继承为当前候选的支持声明。
-- Iris `0.2.0` 只声明 DSH `0.2.0-rc.2`，已通过真实安装服务隔离验收，保留附件完整引用、绑定明确图片模型路由并适配客户端主视图选择；边界与尚未完成的浏览器实机检查见 [rc.2 适配说明](DSH_RC2_ADAPTATION.md)。
+- 已发布 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)。
 
 Local Host 不模拟 Browser、会话或附件。测试需要这些能力时必须显式注入，缺失行为也属于契约。
 
-## Text/Vision 后续共享契约
+## Text/Vision 共享契约
 
-[Text/Vision Model Port v0](MODEL_PORT_CONTRACT.md) 已实现独立纯契约、调用控制与 test-only Fake Port，不替换本契约已有的 `textModel.stream()` / `visionModel.analyze()` 方法。后续由 DSH 模型适配器把 Host 方法映射为共享 `complete()`：解析原始流和正常终态、传递取消、桥接同一张图片，并隔离 Host 引用与会话上下文。
+[Text/Vision Model Port v0](MODEL_PORT_CONTRACT.md) 已实现独立纯契约、调用控制与 test-only Fake Port，不替换本契约已有的 `textModel.stream()` / `visionModel.analyze()` 方法。0.2.1 已由 DSH 模型适配器把 Host 能力映射为共享 `complete()`：解析原始流和正常终态、传递取消、桥接同一张图片，并隔离 Host 引用与会话上下文。
 
-普通能力快照仍为零模型调用。显式视觉实测属于可能计费的模型操作，不能用于 `describe()` 或自动 Doctor；缺图片桥接时必须在模型调用前失败。新共享版本不代表 Host Adapter v0 已升级、公开 SDK 已冻结或现有消费者已迁移。
+普通能力快照仍为零模型调用。显式视觉实测属于可能计费的模型操作，不能用于 `describe()` 或自动 Doctor；缺图片桥接时必须在模型调用前失败。共享端口已被视觉、OCR、定位、摘要与提示词预览消费；它不代表 Host Adapter v0 已升级或公开 SDK 已冻结。
 
 ## 范围
 

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、插件装载、14 个工具、2 项 Skill、4 组路由、Browser/附件/模型能力、客户端版本与 4 个 UI Slot |
+| `host` | 已认证 DSH 中的 `GET /iris/api/doctor` | DSH 版本和 Host Port、插件装载、当前工具（0.2.1为 15 个）、2 项 Skill、4 组路由、Browser/附件/模型能力、客户端版本与 4 个 UI Slot |
 
 两种模式都默认零网络、零计费。Host Doctor 不调用任何 Host Port，不打开 Browser，不读取附件或会话，不调用文本/视觉模型，也不向 Provider 发送请求。它只读取：
 
@@ -29,14 +29,14 @@ Host Doctor 是 Iris 在运行中的 DSH 实例内提供的兼容性诊断。它
 
 如果刚安装、热更新或强制刷新，先等 Web 页面完成装载，再刷新诊断。未收到客户端握手时，Host Doctor 只报告警告，不会把“服务端已装载”冒充成“UI 已装载”。
 
-Iris `0.2.0` 仅支持 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/离线诊断不受此宿主限制。
+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/离线诊断不受此宿主限制。
 
 ## 运行时证据
 
 服务端只登记成功完成的注册：
 
 - 插件身份与 npm 版本；
-- 14 个 Iris Agent 工具名；
+- Iris Agent 工具名（0.2.1包含 `iris_edit_image`，共 15 个）；
 - `iris-verify-ui`、`iris-compose-media`；
 - `/iris/media`、`/iris/api`、`/iris/api/actions`、`/iris/render` 四组逻辑路由。
 

package/docs/MODEL_PORT_CONTRACT.md

@@ -1,6 +1,8 @@
 # Text/Vision Model Port v0 契约设计
 
-状态：**2026-09-30，M1 纯契约、调用控制与 Fake Text/Vision Port 已实现；真实适配器及消费者尚未迁移。** 本文约定共享层与模型适配器的边界；现有 `textModel.stream()`、`visionModel.analyze()`、视觉后端与提示词优化器仍使用原实现。M1 不增加公开 export、CLI 命令、配置字段或生产依赖，也不改变 [Host Adapter v0](HOST_ADAPTER_CONTRACT.md) 的现有方法。
+状态：**Iris 0.2.1。** 0.2.0 已包含 M1 契约；0.2.1 接入 DSH 文本适配器与共享优化消费者、HTTP/DSH Vision Port，以及 look/relook、OCR、定位、拼图摘要和图片自述。端口仍为内部契约，不增加公开 export 或生产依赖，不改变 [Host Adapter v0](HOST_ADAPTER_CONTRACT.md) 的现有方法。新增按次规则与 UI 见 [提示词优化系统](PROMPT_OPTIMIZER.md)，单图预算与宿主附件副作用见 [单图视觉调用](VISION_MODEL.md)，复合操作见 [长图 OCR](OCR_MODEL.md) 和 [定位与摘要](COMPOSITE_VISION.md)。
+
+0.2.1 还提供 [视觉 CLI](VISION_CLI.md)、可选账号/模型 `visionInput` 和设置命令，见 [看图输入预算](CLI_MANAGEMENT.md#看图输入预算)；不改变请求/完成 DTO、契约版本或公开 exports。该设置用于看图、OCR 分块、定位和聊天改图的发送副本，不是供应商能力上限声明；聊天改图的媒体任务语义仍由 Core Runner 管理。
 
 ## 目标与范围
 
@@ -155,7 +157,7 @@ interface VisionModelPort {
 
 迁移保留已有业务预算：提示词草稿 32 KiB、输出 16,000 code units、默认 45 秒与 1,200 输出 token，原配置范围不变。草稿上限仍在业务层校验；端口的总文本上限需按草稿上限、JSON 转义的最坏增长与已验证模板上限计算，不能把带模板的整个请求限制为 32 KiB，导致原本合法的草稿被拒绝。
 
-视觉单次调用沿用 120 秒默认档，Host 原 6,000 字限制改为超限失败。其他入口需明确其文字/图片上限，不能直接套用生成任务的图片参数校验。v0 不为这些预算增加持久配置格式。显式 effort 在元数据未知时从直接透传变为调用前拒绝，是待实施的契约收紧；M2 必须覆盖配置与 inherit 路径，不能声称行为完全未变。
+视觉 M3 沿用 120 秒默认档，原 6,000 字限制改为超限失败；输入文字 32 KiB UTF-8，图片 20 MiB。其他入口需明确其文字/图片上限，不直接套用生成任务参数校验。v0 不为预算增加持久配置格式。0.2.1 的 M2 已将元数据未知时的显式 effort 从直接透传收紧为生成前拒绝，覆盖配置与 inherit；默认 off-if-supported 保留供应商默认回退，不能声称所有行为完全未变。
 
 ## 完整结果与底层流
 
@@ -209,12 +211,15 @@ type ModelPortErrorRecord = {
   invocation: 'not_invoked' | 'rejected' | 'responded' | 'unknown';
   backendId?: string;
   status?: number;  // 已验证的 HTTP 状态码；未知时省略
+  imageBytes?: number;  // 看图大小拒绝：实际发送图片字节数
+  imageMaxBytes?: number;  // 已验证的上限；未知时省略
 };
 ```
 
 | code | 含义 |
 |---|---|
 | `IRIS_MODEL_INPUT_INVALID` | 字段、类型、预算或输入大小非法 |
+| `IRIS_MODEL_IMAGE_TOO_LARGE` | 看图副本无法满足预算，或上游明确拒绝图片大小；安全数值生成说明，不返回原文 |
 | `IRIS_MODEL_UNAVAILABLE` | 未配置或缺失依赖/Host 图片桥接能力 |
 | `IRIS_MODEL_INCOMPATIBLE` | 端口版本或底层协议形状不兼容 |
 | `IRIS_MODEL_UNSUPPORTED` | 当前模型/协议不支持显式输入或生成参数 |
@@ -239,10 +244,10 @@ type ModelPortErrorRecord = {
 
 ## DSH 图片与结果桥接
 
-当前 Host 视觉实现只消费 attachment 引用，忽略 `imageDataUrl`。新适配器必须保证模型实际收到共享请求里的同一张图：
+DSH 视觉适配器通过 Attachments Port 桥接共享请求中的图片，模型必须收到同一张图或经核验的宿主规范化副本：
 
 1. 已验证 DSH 支持内联图片时，在适配边界转换字节；
-2. 否则使用 Attachments Port 保存相同字节，取得 Host 引用，再调用 Host 模型；该步骤受同一信号、deadline 与图片预算约束；
+2. 否则使用 Attachments Port 保存输入字节，取得 Host 引用，再调用 Host 模型；若宿主规范化图片，须核验实际 MIME、尺寸、字节数和来源引用，该步骤受同一信号、deadline 与图片预算约束；
 3. 若两者都不可用，调用模型前返回 `IRIS_MODEL_UNAVAILABLE`，禁止退化成只有问题的纯文本请求。
 
 Host 引用、session ID 与 source metadata 可存在于 DSH 适配器闭包，但不能进入共享请求、结果或诊断快照。桥接不得创建 Core Artifact；宿主是否持久保存附件需在实现与 canary 中明确记录，不能把这条路径称为完全零副作用。
@@ -251,17 +256,17 @@ Host 引用、session ID 与 source metadata 可存在于 DSH 适配器闭包，
 
 ## 实现切片与退出条件
 
-M1 已完成。以下其余切片仍为实施建议，不要求一次跨模块改造；提示词优化的功能定位与输入隔离继续讨论，M2 未获本轮实施授权。
+0.2.0 包含 M1；0.2.1 包含 M2/M3/M4 和 M5 独立视觉 CLI，详见 [视觉 CLI](VISION_CLI.md)；提示词优化后续由用户另行安排。
 
 | 切片 | 范围 | 退出条件 |
 |---|---|---|
 | M1：纯契约与调用控制（已实现） | `model-port-contract.js`、`model-invoker.js`、test-only Fake Text/Vision Port | 无 Host/配置/Store 依赖；请求、错误、预算与取消 conformance 通过 |
-| M2：首个文本消费者 | DSH 模型适配器与纯 `prompt-optimizer-core.js`；原优化入口保留配置/选择/投影 | 真实 DSH 流 fixture 与 Fake Port 结果一致；reasoning、预览/写回、取消、零 Task 写入回归通过 |
-| M3：视觉单次调用 | 自持协议适配器、DSH 图片桥接、look/relook | 真正检查终态；同图字节进入两后端；取消后零下一候选；Host 可选降级如实诊断 |
-| M4：复合视觉业务 | locate、OCR、contact-sheet summarize | bbox 与分块语义保持；整体预算有效；取消停止后续块；摘要仍默认一张拼图一次调用 |
-| M5：独立入口 | 再决定文本目录、显式 Headless 选择和产物交付 | 先审查配置/公开面；无 DSH tarball 消费者与真实 Provider 单独举证 |
+| M2：首个文本消费者（0.2.1 已实现） | `dsh-text-model-adapter.js` 与纯 `prompt-optimizer-core.js`；原入口保留配置/选择/投影，泡泡加入按次规则/组装/预览 | DSH/Fake 共用 conformance、reasoning、点击/写回、取消和零 Task 写入回归，以及已安装 rc.2 Runtime 隔离验收通过；真实模型/浏览器另验 |
+| M3：视觉单次调用（0.2.1 已实现） | `http-vision-model-adapter.js`、`dsh-vision-model-adapter.js`、`vision-core.js`，Agent/工作台 look/relook 与显式视觉实测 | HTTP/DSH 共用 conformance；同图字节、准备/整体预算、严格终态、取消后零下一候选；真实 rc.2 与阿里云隔离验收已通过；浏览器另验 |
+| M4：复合视觉业务（0.2.1 已实现） | OCR、locate、contact-sheet summarize 和生成后自述接入共享端口 | 有限分块与明确 partial；总预算/次数；取消停止后续块/候选；bbox 解析；同一张拼图一次候选生成；Core 转写正文；真实 DSH CLI 与独立安装逐项验收 |
+| M5：独立视觉入口（0.2.1 已实现） | CLI look/locate/ocr/summarize、严格显式选型和文件输出；主动转写才使用 Core | 实际 CLI 子进程、无 DSH tarball 安装副本与真实廉价 Provider 分别验收；文本目录与独立优化另行安排 |
 
-`model-http-adapter.js` 和 `dsh-model-adapter.js` 可作为协议映射的实现位置，最终命名由实施切片决定。现有 `vision.js` 的有序候选可以渐进接入共享调用策略；共享代码不反向导入旧 Host 实现。媒体摘要的 Core 抽帧接线与 S2V/Browser 迁移另行处理。
+实际协议实现为 `http-vision-model-adapter.js`、`dsh-vision-model-adapter.js` 和 `dsh-text-model-adapter.js`。视觉候选通过共享调用策略执行，业务入口不再调用 legacy `vision.js` 的模型链；共享代码不反向导入旧 Host 实现。0.2.1 的 S2V/Browser 已迁移至共享 Core，见 [CLI 管理与补齐](CLI_MANAGEMENT.md)；媒体摘要已支持复用 Core 抽帧 Artifact，无需原视频或 ffmpeg。
 
 ## M1 内部调用方式
 
@@ -274,13 +279,13 @@ M1 已完成。以下其余切片仍为实施建议，不要求一次跨模块
 
 `tests/fixtures/fake-model-port.mjs` 可复现正常正文、规范化流、准备失败、在途错误、等待取消与迟到结果；`model-conformance.mjs` 的同一组 17 项检查分别消费 Text/Vision。fixture 和输入记录只在测试进程存在，不进入 npm 包。
 
-所有共享调用通过调用控制执行；协议适配器负责将 abort 传递到真实源及清理资源。当前 M1 的完整性与取消证据来自 Fake Port，不代表现有 HTTP/DSH 协议已经符合新契约。
+所有共享调用通过调用控制执行；协议适配器负责向真实源传递 abort 和清理资源。M2 的 DSH 文本与 M3 的 HTTP/DSH 视觉 fixture 复用同组 conformance，已安装 Runtime 使用离线源适配器单独举证。M4 另验 OCR 多块、定位 bbox、摘要一张拼图、可选 Core 转写、自述及这些操作的取消，不能仅凭协议测试推断业务正确。
 
 现有配置版本、公开接口和全部消费者不应在一个提交中同时切换。M1 不提供对提示词内容的语义过滤或注入防护证明；优化系统的主动模板/约束加入和不可信输入隔离，需在后续业务设计中分别验证。
 
 ## 必须补齐的 conformance
 
-M1 已执行纯契约、调用控制与 Fake Port 路径。后续协议/业务测试仍需要执行真实适配/消费路径，不能仅比较 DTO 或检查源码字符串。
+M1 已执行纯契约、调用控制与 Fake Port；0.2.1 的 M2 执行 DSH 文本协议、业务/HTTP、实际组件点击及已安装 Runtime 隔离验收；0.2.1 的 M3 执行 HTTP/DSH Vision Port、单图入口与图片桥接。M4 在同一端口上逐项验证多块 OCR、定位、摘要与自述的整体 operation，并有实际 DSH CLI 和无 DSH 安装副本证据。
 
 | 场景 | 必须证明的结果 |
 |---|---|
@@ -292,9 +297,9 @@ M1 已执行纯契约、调用控制与 Fake Port 路径。后续协议/业务
 | EOF、`[DONE]` 但无终态、坏 JSON、未知终态 | 稳定失败，部分正文不返回为成功 |
 | 空结果、token 截断、输出超限、工具调用、内容阻断 | 独立错误；切换行为符合显式策略与总次数 |
 | OCR 与候选组合 | 有限总调用数与整体 deadline；普通块失败可形成明确 partial 业务结果，取消/超时终止操作 |
-| DSH 图片桥接 | 保存/内联的字节与输入相同；缺桥接时零模型调用，无引用泄漏 |
+| DSH 图片桥接 | 保存/内联输入图片，允许经核验的宿主规范化；损坏或不匹配引用在生成前拒绝；缺桥接时零模型调用，无引用泄漏 |
 | 模型身份与 usage | DSH 与 Iris 命名空间不混用；未知默认身份和 usage 字段省略 |
 | 错误、快照与自动记录 | 不包含输入、Key、端点、路径或 Host 对象；正文只作为显式结果返回，无隐式 Task/Artifact 写入 |
 | 两类适配器与业务入口 | Fake Port、HTTP 协议 fixture、DSH 流 fixture 消费同一组结果/错误规则 |
 
-当前 `tests/vision-backend.mjs` 明确允许预先取消后继续 Host fallback，当前 OCR 捕获取消后继续分块，视觉实测超时也只是 race。它们是待修行为，未来切换时应更新测试并留下先失败后修复的证据。M1/Fake Port 通过不等于这些消费者门禁已通过。
+legacy `tests/vision-backend.mjs` 仍验证旧兼容实现允许预先取消后继续 Host fallback。M3/M4 的现有业务入口已切换到新模块；旧 fixture 不代表新契约。OCR 额外证明取消/超时终止所有后续块、总次数有界和部分结果语义；定位、拼图摘要与自述另有完整终态、业务解析和取消验收。

package/docs/OCR_MODEL.md

@@ -0,0 +1,39 @@
+# 长图 OCR
+
+状态：**Iris 0.2.1**。定位、拼图摘要及自述见 [复合视觉调用](COMPOSITE_VISION.md)。
+
+Agent 的 `iris_long_ocr` 与工作台 OCR 使用相同分块业务和共享 Vision Ports。工具接受 `image_path`、`artifact_id` 或 `attachment_id` 三选一；工作台动作接受 `image_path` 或 `artifact_id` 二选一，现有表单继续输入文件路径。Core ID 读取当前 profile 的既有图片，核验内容哈希和 MIME，不依赖原文件、不导出临时图片、不写入 Core。工具文字保留 Core ID，动作 JSON 带 `artifactId`；CLI `vision ocr` 同样支持，详见 [视觉 CLI](VISION_CLI.md)。复用可选的账号/模型输入预算，不新增公开 SDK export 或生产依赖。
+
+## 分块与结果
+
+默认块高 1200 像素、重叠 120 像素，纵向步长为块高减重叠。显式 `overlap: 0` 会关闭重叠。保留原有块高至少 100、重叠钳制到 `[0, 块高−1]` 的规则；非有限数值在读取图片前拒绝。
+
+图片先按 EXIF 转正；宽图再按比例缩到默认最多 2048 像素宽，从上到下分块。输出中的宽高与 `y` 都是处理后图片的坐标，`sourceWidth/sourceHeight` 为转正后的源尺寸。每块提供相同源 PNG 切片，各候选在提交前按自己的账号/模型 `visionInput` 准备发送副本，不把整张长图先缩到模型最长边。重叠区域的重复文字仍保留，不做可能误删内容的自动去重。
+
+CLI/共享结果的成功块附 `input.source/sent`：切片与实际发送图的宽高、字节数、MIME，以及是否缩小。候选切换使用成功模型的记录；DSH 记录宿主保存后实际附件，而不是保存前估计。文本结果在整体宽度或某块缩小时明确提示细字可能丢失，并列出缩小块的发送尺寸。可以提高 CLI `max_dimension`（最高 4096）或模型预算以保留更多细节；缩放不会保证识别质量。
+
+| 结果 | 含义 |
+|---|---|
+| 完成 | 全部分块得到有正常终态的非空正文 |
+| 部分完成 | 至少一块成功，其他块失败或因次数上限未处理 |
+| 失败 | 没有任何完整成功块；工作台 `ok` 为 false |
+
+普通块失败允许继续处理后续块，失败块不会把半截正文拼入结果。成功段保留原始段号，例如第二块失败后第三块仍标记为 `[第3段 y=…]`。未处理块与失败块分别计数；部分结果不称为完整全文。块级诊断只有稳定模型错误，不能含原始异常、Key 或图片路径。
+
+取消或超时会立即终止整次操作并返回错误，**不以部分结果隐藏取消/超时**，也不会生成下一块或继续切换候选。
+
+## 整体预算
+
+| 限制 | 默认值 |
+|---|---|
+| 整体时间 | 120 秒，覆盖文件/Artifact/附件读取、图片处理、模型元数据、所有块与候选 |
+| 最大分块数 | 32，超出时生成前拒绝 |
+| 总生成次数 | 64，候选切换也占用次数；本地确认未调用不占次数 |
+| 源图片 | 20 MiB 编码字节，最多 4000 万像素；单帧 PNG/JPEG/WebP/GIF，工具/工作台本地路径接受 PNG/JPEG/WebP |
+| 每块正文 | 6000 个 UTF-16 code units，超限或 token 截断不返回成功 |
+
+次数用尽后不再准备/生成后续块，已完成块形成明确部分结果；一块也未完成则失败。整体 deadline 不会因下一块或下一候选重置。输入损坏、MIME 不符或多帧图片在生成前拒绝。
+
+DSH 默认视觉路由在本轮首次使用时绑定，操作期间的默认模型变更在下次 OCR 才生效。每块通过宿主保存并读回，允许核验过的合法规范化，检查内容哈希、字节数、MIME 和尺寸；不可取消保存与远端预处理的边界沿用 [单图视觉调用](VISION_MODEL.md)。Sharp 的原生图片处理不能被 AbortSignal 强制中止，本地等待有界退出后晚到结果会被忽略，不会启动模型或保存 Core 产物。
+
+OCR 不创建 Core/legacy Task、Attempt 或 Artifact，也不自动保存识别正文。验证使用共享 Fake/HTTP/DSH 端口、真实安装的 DSH 服务和无 DSH 的包外安装副本；真实模型验收单独记录，不把协议 fixture 当成识别质量证明。

package/docs/PROMPT_OPTIMIZER.md

@@ -0,0 +1,47 @@
+# 提示词优化与规则组装
+
+状态：**Iris 0.2.1**。本版提供按次规则、只组装和可编辑预览；后续独立提示词优化系统另行安排。
+
+## 使用
+
+在 DSH 输入框写入未发送的纯文本草稿，打开 🫧，选择通用、图片、视频或首尾帧视频目标。
+
+“本次规则”可填写以下内容；留空表示不选择。规则只在当前组件中保留，刷新后重置，不改写已有 `prompt-optimizer.json`。
+
+| 内容 | 智能优化 | 只组装 |
+|---|---|---|
+| 改写规则 | 指导模型如何编辑草稿，不要求将规则原文抄入结果 | 不使用 |
+| 输出前缀 | 模型改写完成后，程序原样加入开头 | 原样加入原稿开头 |
+| 输出后缀 | 模型改写完成后，程序原样加入末尾 | 原样加入原稿末尾 |
+
+智能优化进行一次文本模型生成；只组装不读取模型路由或优化配置、不调用模型，在 Host 文本服务不可用时仍可使用。只组装不会套用目标模板或自动润色原稿。规则之间与正文之间用两个 LF 分隔；输出规则原文与只组装的草稿空白保持不变。
+
+结果先进入可编辑预览。可以查看原文、本次参与规则、实际模型与思考策略，以及折叠相同首尾后的中间替换区。这是文本改动对照，不代表模型解释了每处改动的原因。手动编辑也会更新对照；复制和写回使用编辑后的文字。
+
+写回不会自动发送。出现新草稿时先确认替换；出现结构化 `@`、`/` 引用或忙碌状态时拒绝写回。切换会话清除旧预览并取消在途操作，即便两边草稿文本相同。取消、关闭或卸载会传递 abort，迟到结果不能恢复旧预览或覆盖新操作。恢复原文只恢复本次操作前的文字，不自动恢复附件/结构化引用。
+
+## 规则来源与限制
+
+优化处理规则、用户选择的改写规则、待处理草稿和程序拼接的输出规则分别处理。Iris 不从草稿解析额外规则，不读取会话历史、附件、工具或工作区。JSON 包装及 system 字段用于区分指令和素材，不能证明模型永远抵御提示词注入；事实保留、规则冲突和优化质量仍需真实模型评估与预览。
+
+输出前后缀不交给模型改写，也不自动转换为生成 API 参数。例如文字中的画幅要求不等同于图片工具的实际尺寸参数。Iris 不对任意自然语言规则做完整冲突检测。
+
+- 草稿：沿用修剪后 32 KiB UTF-8 上限；返回原文保留空白。
+- 规则：单条最多 4,000 个 UTF-16 code units；最多 12 条，正文总计 16 KiB UTF-8。
+- 最终结果：最多 16,000 个 UTF-16 code units；智能优化先为输出规则与分隔符预留空间，超限或截断失败。
+- 默认预算：45 秒、1,200 输出 token；元数据查询和生成共用 deadline，不自动重试或切换模型。
+- 配置仍为 v1，模型路由、JSON 导入/导出、恢复默认和开关保持原有方式。`off-if-supported` 在关闭能力未知时使用供应商默认；显式 effort 和 `inherit` 的具体档位必须有元数据声明，否则在生成前拒绝。该拒绝是与 npm 0.2.0 的行为差异。
+
+取消表示本地停止等待并向底层传递信号，不保证第三方远端执行或计费已停止。失败、工具调用、未知终态和部分正文不会作为完整结果交付。
+
+## 开发边界
+
+`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 或规则持久化格式。
+
+现有 `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 并意外调用模型。能力字段不进入配置导出文件。
+
+参见 [Model Port 契约](MODEL_PORT_CONTRACT.md) 与 [架构边界](ARCHITECTURE.md)。浏览器/Android 交互和真实模型质量需各自验收。

package/docs/PROVIDER_ADAPTER_CONTRACT.md

@@ -1,6 +1,6 @@
 # Provider Adapter v0 生命周期契约
 
-状态：**v0.1.4 的六操作内部契约已实现；0.2.0 增加可选输入准备能力。** 这是 Iris Core 模块与供应商协议实现之间的内部边界，尚未冻结为第三方公开 SDK。当前 DashScope 与 OpenAI Images 兼容实现已经通过同一套零网络 conformance runner。
+状态：**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 回归。
 
 ## 目标与依赖方向
 
@@ -23,7 +23,7 @@ Action / Task watcher / recovery / model discovery
 
 ## 描述结构
 
-0.2.0 的协议工厂由内部注册表选择，当前仍只有 `dashscope` 和 `openai-images` 两项，不提供公开注册 API。未知的显式 `mediaProtocol` 保留原值，调用时以 `IRIS_PROVIDER_PROTOCOL_UNSUPPORTED` 在联网前拒绝；错误只包含合法协议标识，不回显端点或凭据。
+协议工厂由内部注册表选择；0.2.0 基线提供 `dashscope` 和 `openai-images`，0.2.1 另有 `openai-chat-images` 与 `openai-responses-images`，不提供公开注册 API。生图模型可通过可选 `imageProtocol` 覆盖账号默认；选择、实测与 Task binding 共用有效协议，详见 [模型级图片协议](CLI_MANAGEMENT.md#模型级图片协议)。未知的显式 `mediaProtocol` 保留原值，调用时以 `IRIS_PROVIDER_PROTOCOL_UNSUPPORTED` 在联网前拒绝；错误只包含合法协议标识，不回显端点或凭据。
 
 未配置协议或选择 `auto` 时，官方端点可识别为对应协议；其他端点继续使用 OpenAI Images 兼容路径，并标记 `protocolInferred:true`。该标记表示尚待用户确认兼容性，不代表已经验证成功。显式选择协议会清除标记；旧记录中已保存的明确协议不追溯猜测其来源。CLI 与 DSH 共用选择逻辑，Task binding 绑定最终实际协议与端点。
 
@@ -72,13 +72,15 @@ Core Attempt 持久化 `providerId::modelId` 复合身份，具体 Provider Adap
 - `unknown` 只停止当前盯守并保留 `acceptance=accepted`，不得伪造失败或重提；
 - `succeeded` 和图片 `completed` 使用同一可物化描述：`remote-url` 或 `inline-base64`；文本任务仍可使用 text value。生成成功先于本地物化事实落盘。
 
-`download` 物化已经确认成功的产物：`remote-url` 执行下载，OpenAI Images 的 `inline-base64` 直接写入私有 staging。inline 正文只作为 non-enumerable 的短生命周期字段传给 Runner，不进入 JSON、Task 或 Manifest。物化失败只能改变交付状态，不能触发生成重提。OpenAI Images 当前同步返回图片，所以 `poll` 与 `cancel` 显式 unsupported；DashScope 当前没有经过验证的远端取消接口，因此 `cancel` 同样显式 unsupported，而不是伪装取消成功。
+`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，而不是伪装取消成功。
+
+聊天改图仍使用 `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 之前。
 
 ## 可选输入准备与上传边界
 
 Host 和 CLI 通过 `prepareProviderInput(adapter, { model, filePath, signal?, timeoutMs? })` 调用可选准备能力，不能自行绕过 Adapter 上传。DashScope 的 Adapter 闭包持有实际凭据与媒体端点并实现临时上传；OpenAI Images 明确不支持。未实现时在网络调用前抛 `IRIS_PROVIDER_INPUT_PREPARATION_UNSUPPORTED`。返回的 `{url}` 只供紧随其后的提交读取，属性不参与 JSON 序列化，不能进入 Task、日志或能力快照。
 
-上传错误经 Adapter 映射与脱敏，固定为 `stage=upload / acceptance=not_accepted`；这组字段属于返回调用方的安全错误分类，**不等于已持久化的 Core Attempt stage**。上传属于 Host/CLI 输入准备，只有随后真正调用 `submit` 才跨越可能计费的受理边界。当前 s2v 仍走 legacy 链，其 Attempt 可保存上传错误；Core 转写的 `audio_path` 在创建 Task 前上传，失败会直接返回且不创建 Core Task，也不会调用 submit。这是 D-12 当前采用的路径 B；若未来要求把准备失败纳入 Core 事实，须另行评审路径 A，不能由错误字段反推已经落盘。
+上传错误经 Adapter 映射与脱敏，固定为 `stage=upload / acceptance=not_accepted`；这组字段属于返回调用方的安全错误分类，**不等于已持久化的 Core Attempt stage**。上传属于 Host/CLI 输入准备，只有随后真正调用 `submit` 才跨越可能计费的受理边界。S2V 已迁入 Core：先持久化 Attempt，再按实际候选账号上传首帧和音频，上传失败可写入该 Attempt，且不调用生成 submit；Core 转写的 `audio_path` 在创建 Task 前上传，失败会直接返回且不创建 Core Task，也不会调用 submit。这是 D-12 当前采用的路径 B；若未来要求把准备失败纳入 Core 事实，须另行评审路径 A，不能由错误字段反推已经落盘。
 
 ## 错误与取消传播
 

package/docs/PROVIDER_HEALTH.md

@@ -1,6 +1,6 @@
 # Provider 与能力健康状态
 
-状态：v0.1.4 候选契约。
+状态：**Iris 0.2.1**。新增短时限流冷却与明确额度/预算耗尽停用，沿用既有持久健康证据。
 
 Iris 用持久化证据描述“当前配置是否存在、最近是否实际成功、是否出现明确凭据失败”。它不是后台监控，也不等同于 Host Doctor。
 
@@ -11,15 +11,32 @@ Iris 用持久化证据描述“当前配置是否存在、最近是否实际成
 | `unconfigured` | 灰色 | 当前能力没有启用且带凭据的候选模型 |
 | `configured` | 蓝色 | 已配置，但没有 7 天内的成功证据；旧证据过期后也回到此状态 |
 | `verified` | 绿色 | 该 Provider × Model × Capability 在 7 天内通过显式实测或真实任务成功 |
-| `failed` | 暗红色 | 最近的决定性证据是 401、403 或明确的认证/权限失败 |
+| `failed` | 暗红色或红色 | 明确认证/权限失败，或已确认额度/预算耗尽；短时限流另以琥珀色显示 |
 
 状态按 `Provider × Model × Capability` 记录，不因同名模型而合并。模型、Key、Base URL、协议或能力模型等关键配置变化会清空相关旧证据；移除模型或能力标签也会移除不再成立的记录。
 
+模型可单独设置 `imageProtocol`，未设置或 `auto` 时继承账号默认。改变有效图片协议只使该模型的生图验证失效；同模型的视觉验证、其他模型及冷却/额度停用均保留。再次选择同一有效协议不清空验证。设置入口见 [CLI 管理命令](CLI_MANAGEMENT.md)，DSH 模型池的生图模型行也可修改。
+
 ## 什么会改变状态
 
 显式“模型实测”和正常用户任务都会产生证据。视觉、图片和 TTS 可从模型池逐项实测；视频与转写不会发送空样本探针，应使用真实的视频生成或音频转写任务验证。成功受理、同步完成或视觉成功会刷新绿色及其成功时间。
 
-Iris 不做定时后台探测，也不会为了让图标变绿而产生隐形请求或费用。429/额度限制、网络错误、5xx、内容安全、用户取消和受理未知属于临时或不确定事实：它们可以记录为最近观察，但不会把 7 天内的绿色覆盖成红色。只有明确认证或权限失败才会变暗红；移除 API Key 后回到灰色。
+Iris 不做定时后台探测，也不会为了让图标变绿而产生隐形请求或费用。网络错误、5xx、内容安全、用户取消和受理未知不会覆盖近期成功证据。移除 API Key 后回到灰色。
+
+## 限流与耗尽的区别
+
+HTTP 状态、供应商错误码和明确错误说明一起决定路由规则，不凭 `quota` 或 `limit` 字样推断额度耗尽。百炼的 `Throttling.AllocationQuota` 也可能表示 TPS/TPM 限制。分类依据见[阿里云错误码说明](https://www.alibabacloud.com/help/zh/model-studio/error-code)。
+
+| 响应 | 路由与显示 |
+|---|---|
+| 短时或无法进一步确定的 429，包括频率、并发、服务忙 | 琥珀色“429 冷却中”，暂时跳过；优先遵从 `Retry-After` 秒数或 HTTP 日期，缺失或无效时默认 60 秒 |
+| 403 `AllocationQuota.FreeTierOnly`，或 403/429 明确表示免费额度耗尽 | 红色“额度耗尽已停用”，手动实测成功后才恢复 |
+| 429 `BudgetLimitExceeded` | 红色“预算耗尽已停用”，手动实测成功后才恢复 |
+| 普通 401/403 认证或权限失败 | 保留认证失败语义，不套用额度耗尽停用 |
+
+冷却与停用按 Provider × Model 记录，对同账号该模型的所有能力生效；其他账号的同名模型不受影响。状态持久保存，重启后继续遵守。正常路由、显式生成和 OCR 后续切片都会跳过受阻模型；已受理 Task 仍可观察原远端任务，绝不因此自动重提。
+
+模型池显示原因及冷却恢复时间，实测按钮保持可用。冷却到期只恢复候选资格，不触发验证请求；颜色按原有证据返回蓝色或绿色。发现、修改分配、改 Key/端点、移除再添加同名模型，以及旧任务成功，都不能解除明确耗尽的停用。显式实测只调用指定模型，失败不恢复，成功解除该账号该模型的冷却或停用。视频/转写实测须用 CLI `models test --input` 明确提供真实素材，未提供时跳过，见 [CLI 管理命令](CLI_MANAGEMENT.md)。
 
 ## failover 与泡泡汇总
 
@@ -27,7 +44,7 @@ Iris 不做定时后台探测，也不会为了让图标变绿而产生隐形请
 
 1. 任一路候选为绿色，能力为绿色；
 2. 否则任一路为蓝色，能力为蓝色；
-3. 只有所有已配置候选都为暗红时，能力才为暗红；
+3. 所有已配置候选均受阻时显示调用受阻；若全部只是冷却，显示琥珀色及最早恢复时间；
 4. 没有候选时为灰色。
 
 主泡泡再按五项能力使用同一保守规则汇总。汇总证据时间只从决定汇总颜色的候选中选择，例如绿色不会显示另一条较新蓝色临时观察的时间。界面同时显示文字和证据时间，不要求用户只凭颜色判断。
@@ -36,4 +53,4 @@ Iris 不做定时后台探测，也不会为了让图标变绿而产生隐形请
 
 Host Doctor 只检查 DSH、Iris 注册、Host Port、客户端版本和 UI Slot 是否装载；它零网络、零计费，不能证明 API Key 或具体模型可用。Provider 健康来自模型实测和真实业务请求，才回答供应商侧是否近期成功。离线 `dsh-iris doctor` 则检查本地运行时、配置、存储与任务一致性，三者不能互相替代。
 
-健康事实保存在 `$DSH_HOME/iris/v1/providers.json`，状态 API 仅返回脱敏标量。错误说明会移除 Authorization、Key、签名参数、私有路径和已配置的完整 API Key。
+健康事实保存在 `$DSH_HOME/iris/v1/providers.json`；可选 `health.rateLimits` 保存模型、时间、来源、HTTP 状态、冷却截止时间或耗尽原因，沿用 v1 配置，不要求迁移。状态 API 仅返回脱敏标量。错误说明会移除 Authorization、Key、签名参数、私有路径和已配置的完整 API Key。

package/docs/PROVIDER_RUNTIME_HARNESS.md

@@ -22,7 +22,7 @@ Task → 写前 Attempt → submit → accepted → poll
 
 ## 当前限制
 
-每次 `observe` 只轮询一次，不拥有后台 timer；同一 Runtime 内同一 Task 的并发操作以 `IRIS_PROVIDER_TASK_BUSY` 拒绝。交付只验收一个 `image/png` 产物；重新交付需有持久化的远端任务 ID。Task v0 尚未迁移 0.1.4 的任务文件，也未形成公开 package export。多产物、内容哈希、关系边、索引重建和孤儿回收由 Artifact Manifest 阶段完成。
+每次 `observe` 只轮询一次，不拥有后台 timer；同一 Runtime 内同一 Task 的并发操作以 `IRIS_PROVIDER_TASK_BUSY` 拒绝。该基础 harness 的交付 fixture 只使用一个 `image/png` 产物，不代表产品格式上限；0.2.1 的图片交付支持 PNG/JPEG/WebP，视频、音频和转写使用各自的 Profile 回归。重新交付需有持久化的远端任务 ID。Task v0 尚未迁移 0.1.4 的任务文件，也未形成公开 package export。[Artifact Manifest v0](ARTIFACT_MANIFEST.md) 已实现内容哈希、关系边、索引重建及多产物；Doctor 报告孤立对象，显式清理走可恢复隔离，永久 purge 留待后续。
 
 运行单项验收：
 

package/docs/PROVIDER_SUBMISSION_CONTRACT.md

@@ -53,8 +53,8 @@ Provider `submit()` 必须返回以下四种结构之一：
 
 ## 当前接入边界
 
-`lib/provider-contract.js`、Task v2 复制落盘原语和零网络 Fake Provider 已冻结本契约。完整图片能力现在都会在请求前写入 Attempt：DashScope 旧异步返回远端 ID 后进入观察；DashScope 新同步与 OpenAI Images 的成功响应记为 `completed/accepted`，随后独立推进本地产物交付。异步与同步候选可以在同一个 Task 中安全切换。
+`lib/provider-contract.js`、Task v2 复制落盘原语和零网络 Fake Provider 已冻结本契约。完整图片能力现在都会在请求前写入 Attempt：DashScope 旧异步返回远端 ID 后进入观察；DashScope 新同步、OpenAI Images、聊天生图与 Responses 生图的有效成功响应记为 `completed/accepted`，随后独立推进本地产物交付。异步与同步候选可以在同一个 Task 中安全切换。
 
 429 等可证明未创建任务的明确 4xx 拒绝可进入下一候选；408、409、425、499、5xx、网络异常、超时和成功响应缺少必要结果一律停止并记录 `acceptance=unknown`。同步生成已经成功后，下载或落盘失败记录为 `outcome=succeeded / deliveryState=failed`，不会重新生成。
 
-视频、转写与 TTS 使用同一受理边界，但提交前输入准备不自动成为 Core 事实。当前 s2v 仍走 legacy 链并可在 legacy Attempt 记录上传错误；Core 转写的 `audio_path` 在 Host/CLI 边界先上传，失败以脱敏的 `stage=upload / acceptance=not_accepted` 返回调用方，零 submit、零 Core Task。准备成功后才创建 Core Task/Attempt 并进入写前 submit；TTS 同步成功则先记 `completed/accepted` 再交付音频。工作台消费稳定的人类状态，并提供重新观察、重新交付、提醒已读/恢复和需确认费用的知情重试。v0.1.4 已将 discovery、submit、poll、cancel、download 与 error mapping 收口到统一 Adapter，并由零网络 conformance runner 覆盖现有 DashScope/OpenAI Images 路径。
+视频、转写与 TTS 使用同一受理边界，但提交前输入准备不自动成为 Core 事实。0.2.1 的 S2V 先持久化 Core Attempt，再按实际候选账号上传首帧和音频；上传失败保存安全错误，零生成 submit。Core 转写的 `audio_path` 在 Host/CLI 边界先上传，失败以脱敏的 `stage=upload / acceptance=not_accepted` 返回调用方，零 submit、零 Core Task。准备成功后才创建 Core Task/Attempt 并进入写前 submit；TTS 同步成功则先记 `completed/accepted` 再交付音频。工作台消费稳定的人类状态，并提供重新观察、重新交付、提醒已读/恢复和需确认费用的知情重试。v0.1.4 已将 discovery、submit、poll、cancel、download 与 error mapping 收口到统一 Adapter，并由零网络 conformance runner 覆盖现有 DashScope/OpenAI Images 路径。

package/docs/ROADMAP.md

@@ -1,34 +1,43 @@
 # 路线图
 
-Iris 正从 DSH 媒体插件演进为可独立运行、可接入不同 Agent 宿主的媒体生产核心。本文只列当前状态与后续方向；历史版本的具体改动见[变更记录](../CHANGELOG.md)，内部实现顺序不在公开路线图中展开。
+Iris 正从 DSH 媒体插件演进为可独立运行、可接入不同 Agent 宿主的媒体生产核心。本文列当前状态与后续方向；版本变化见 [变更记录](../CHANGELOG.md)。
 
 ## 当前状态
 
-当前版本为 `0.2.0`，保留包名 `@mokuyoaxis/dsh-iris`，同时提供 DeepSeek Harness 插件和 Headless CLI。它提供：
+当前版本为 **Iris 0.2.1**。包名保持 `@mokuyoaxis/dsh-iris`，同时提供 DSH 插件与无 DSH 的 Headless CLI。功能范围见 [0.2.1 发布说明](releases/0.2.1.md)。
 
-- 图片、视频和语音生成，音频转写；
-- 看图问答、OCR、目标定位、裁剪、像素比较、视频抽帧和摘要；
-- 多供应商模型池与能力分配；
-- 可恢复的异步任务、受理边界和人工接管；
-- 独立作品库、Iris 工作台、🫧 提示词优化入口；
-- 两项随包 Agent Skill；
-- Host/Provider Adapter、离线 Doctor 和零网络一致性测试。
+0.2.1 的更新重点是 **完成 OpenAI 兼容图片与视觉工作流**：生成图片 → Core Artifact → 按 ID 看图/OCR → 聊天改图 → 新 Artifact，CLI 与 DSH 工作台共用同一链路。本版已实现以下能力：
 
-0.2.0 建立实例化 Core Runtime，打通无 DSH 的 crop、四种媒体生成提交、Task 观察与 Artifact 管理，并提供带内容哈希、关系边、可重建 Index 和孤儿恢复的 Artifact Manifest v0。crop 与图片、视频、语音、转写的新任务全部落到共享 Core Task/Attempt/Artifact：Host 负责有界观察、启动接管和 attachment/UI 投影；统一作品区与五类用户状态投影覆盖四种媒体工作，CLI、DSH API 和 UI 共用同一 Command Service 的人工控制面（重新观察、重新取回、取消、重试为新任务）。迁移过程中积累了真实 Provider canary 记录，详细范围与后续待验项以验收文档为准。s2v 数字人视频、视觉理解与提示词优化仍走原有链路；Core 公开 API 未冻结，详见 [Headless CLI](HEADLESS_CLI.md)、[FakeProvider 生命周期验收器](PROVIDER_RUNTIME_HARNESS.md)、[Artifact Manifest](ARTIFACT_MANIFEST.md)和 [DSH → Core 渐进迁移](DSH_CORE_MIGRATION.md)。
+- 图片生成按模型选择 DashScope、OpenAI Images、聊天生图或 Responses 协议，PNG/JPEG/WebP 按真实字节交付；
+- Artifact ID 看图、OCR、定位，以及“来源 Artifact → 聊天改图 → 新 Artifact”的关系与引用保护；
+- 共享视觉预算、长图分块、取消与完整终态检查；账号/模型输入预算只处理发送副本，定位坐标映射回原图；
+- 图片、视频、S2V、语音、转写与本地处理的 Core 任务链，独立视觉 CLI、HTML 截图及完整配置/查询/维护命令；
+- 工作台统一 Core/旧版全媒体分页过滤，跨页选择、ZIP 下载、详情及 Core 可恢复隔离/恢复；
+- 短时 429 琥珀冷却、明确额度或预算耗尽红色停用，以及既有提示词泡泡的按次规则和可编辑预览。
 
-第二个真实 Host Adapter 实现并验收后，计划将现有 GitHub 仓库更名为 Iris，并新建 `@mokuyoaxis/iris` npm 包，复用发布工作流。当前 0.2.0 保留名称；旧包后续单独维护另行决定。CLI、测试 fixture 与媒体 Provider 不算第二个 Host Adapter。
+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)。
 
-已发布 Iris `0.1.4` 的历史 DSH 范围为 `>=0.1.2-rc.1 <0.1.3-0` 和 `0.1.5-rc.1`，旧宿主应固定安装 `@mokuyoaxis/dsh-iris@0.1.4`。Iris `0.2.0` 只声明支持准确的 DSH `0.2.0-rc.2`，已通过真实安装服务隔离验收；历史旧版验收不继承到当前版本。修正与实机待验项见 [rc.2 适配说明](DSH_RC2_ADAPTATION.md)。其他版本需先通过独立 Host canary 才会加入支持范围，具体安装与市场版本选择见 [README](../README.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。
 
-## 下一步
+## 近期优先：真实使用验收
+
+0.2.1 的发布检查覆盖完整测试、lint、实际 tarball、敏感信息、仓库外安装与跨平台 CI。服务层与包安装验收之外，近期优先补齐真实浏览器/移动端及异步重启使用证据。
+
+工作台两轮功能已实现；第三轮仍需补浏览器/移动端的筛选、分页、跨页选择、识别、改图、下载及回收区使用验收，以及真实异步任务重启后的 CLI 接管。已有真实图片生成、按 ID 看图和聊天改图链路验证，完整会话与重启范围继续以 [验证说明](DSH_CORE_MIGRATION.md#验证证据与限制) 为准。提示词优化系统的后续设计单独安排，不扩入本次发布。
+
+DSH 工作台与 Headless CLI 均复用 Core 的引用保护、可恢复隔离和恢复命令；legacy `outputs/` 的永久删除仍由旧工作台处理。两种删除语义与已实现的作品管理见 [工作台作品管理](WORKBENCH_ARTIFACTS.md)。
+
+## 后续功能方向
 
 ### 后续 0.2.x
 
-- 收藏、标签、搜索、筛选和批量导出；
+- 适配其他协议，包括原生 Gemini、Fal 和后续 Replicate；网关兼容接口与原生协议接入分别验证；
+- Music 音乐生成：接入音乐生成模型，复用 Core 任务、Artifact 和作品管理；具体协议、模型与入口后续确定，不纳入 0.2.1；
+- 收藏、标签与工作台搜索（CLI 及工作台过滤、分页、显式选择/批量下载已完成）；
 - Artifact 关系边冻结 `retried-from` 类型，补全重试谱系（0.2.0 仅有 Task 级 `retriedFrom`）；
-- Core Task/Artifact 删除、清理与孤儿 purge（0.2.0 的 Headless CLI 和 DSH 工作台都保持 Core 只读；工作台现有删除、清空与孤儿清理只作用于 legacy `outputs/`）；
+- Core 隔离内容的永久 purge（0.2.1 已开放可恢复隔离/恢复，legacy 永久删除保持原行为）；
 - 鸢尾花与泡泡视觉身份；
-- Gemini、Fal 和后续 Replicate Provider；
+- 有可用接口与实际需求后，补 Images 编辑、mask、多参考图或连续编辑；
 - 将提示词优化收口为 Core Prompt Engine 与共享 `prompt.optimize` Command，由 CLI 和 DSH 入口共同消费；DSH 只负责草稿读取、预览和写回；
 - 冻结中立 TextModel Port，把 Ollama、兼容文本端点及其他文本模型后端与媒体 Provider Catalog 分离，避免通用文本模型淹没 Iris 媒体模型界面；
 - 接入 ComfyUI、本地 TTS 等本地媒体 Provider，并补齐 `auth: none`、`billing: none`、同步完成语义和本地/远程 UI 区分；
@@ -42,12 +51,13 @@ Iris 正从 DSH 媒体插件演进为可独立运行、可接入不同 Agent 宿
 
 ## 兼容性与限制
 
-- Iris 0.2.0 的 Node.js 最低版本为 22.0.0；DSH 要求更高版本时以 DSH 为准。
-- 图片处理依赖 `sharp`；视频抽帧和摘要依赖 `ffmpeg`、`ffprobe`。
+- Iris 0.2.x 的 Node.js 最低版本为 22.0.0；DSH 要求更高版本时以 DSH 为准。
+- 图片处理依赖 `sharp`；视频文件抽帧依赖 `ffmpeg`、`ffprobe`，摘要复用既有 Core 帧时无需这两个工具。独立 HTML 截图需要显式提供 Chromium。
 - DSH 仍处于快速演进期。单个 Host Port 可以降级，但 DSH 若改变插件加载协议，仍需更新 DSH Adapter。
 - 模型发现只列出候选项；真实能力必须由用户显式验证。
 - 原生 Windows/WSL 的完整 DSH 宿主冒烟仍待补充。
-- Headless CLI 当前开放 crop、图片/视频/语音/转写提交、Task 查询/单步观察与 Artifact 检查/导出；必须显式指定绝对数据根，且不会自动循环观察。0.2.0 的 Headless CLI 与 DSH 工作台都不提供 Core Task/Artifact 删除或清理能力；工作台现有破坏性动作只处理 legacy `outputs/`。Core 删除能力计划在 0.2.x 开放。
+- Headless CLI 的媒体、视觉、S2V、HTML、配置、查询、批量、有界等待与 Core 隔离/恢复见 [CLI 管理](CLI_MANAGEMENT.md)。需要存储时显式指定绝对数据根，观察和等待不重新提交；Core 永久 purge 尚未开放。
+- Responses 只支持同步单图；聊天改图只支持一张静态来源图片，输出尺寸与编辑精度由模型决定。
 
 ## 质量要求
 

package/docs/SECURITY.md

@@ -1,6 +1,6 @@
 # Iris 安全边界
 
-状态：v0.1.4 候选实现。安全目标是避免凭据泄露、路径越权、跨站写入和因错误重试造成重复计费；Iris 与 DSH 仍是本机同一信任域内的预览软件，不构成多租户安全边界。
+状态：Iris 0.2.1 安全边界。安全目标是避免凭据泄露、路径越权、跨站写入和因错误重试造成重复计费；Iris 与 DSH 仍是本机同一信任域内的预览软件，不构成多租户安全边界。
 
 ## 信任模型
 
@@ -28,7 +28,7 @@ API、SSE 和 Doctor 只返回凭据存在性或掩码提示。Provider 错误
 - “知情重试”必须单独确认可能重复任务或重复计费，并创建带 `retryOf/manualRetries` 关系的新 Task。创建后只归档原提醒，不改写原任务的未知事实；当前只对能从安全记录无损重建的文生图和文生视频开放，文件型输入和截断文本要求用户从原始输入重新发起。
 - “标为已读/恢复提醒”只操作有界的本地 `attentionEvents` 审计元数据，不发送网络请求，也不把用户处置等同于供应商已经受理。
 - Iris 当前没有凭空假设 DashScope 的远端取消协议。停止本地观察后若远端结果无法确认，状态保持 unknown。
-- Provider 健康不做后台探测。只有 401、403 或明确认证/权限分类可变为暗红；429、网络、5xx、内容安全、取消与未知受理不得覆盖近期成功或授权自动重提。
+- Provider 健康不做后台探测。普通认证/权限失败为暗红；短时 429 以琥珀色冷却，优先遵从 `Retry-After`，默认 60 秒，到期只恢复候选资格。明确免费额度或预算耗尽以红色持续停用至手动实测成功，记录按账号和模型隔离。网络、5xx、内容安全、取消与未知受理不覆盖近期成功；任何健康变化均不授权自动重提已受理任务。
 
 ## 文件、上传与媒体访问
 
@@ -36,8 +36,8 @@ API、SSE 和 Doctor 只返回凭据存在性或掩码提示。Provider 错误
 - 输出文件名由 Iris 生成或通过 `basename` 收口，API 不返回宿主绝对路径。
 - 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 发布到不受信任位置。
-- 清理任务元数据默认不删除作品；独立作品索引不保存 Prompt、Provider、Model 或任务关系。
-- 删除单件作品、清空作品库或删除真正的孤儿文件都需要独立确认。作品删除会保留任务历史，但旧媒体链接将失效。
+- 清理任务元数据默认不删除作品；legacy 独立作品索引不保存 Prompt、Provider、Model 或任务关系；Core Manifest 保存中性元数据、SHA-256 和来源/派生关系，不保存凭据或私有下载 URL。
+- legacy 删除单件作品、清空作品库或删除真正的孤儿文件都需要独立确认，会保留任务历史，但旧媒体链接将失效。0.2.1 Core 删除使用可恢复隔离，任务/产物引用会阻止删除；同时移除关联的已结束任务记录需要明确选择和确认，恢复不会覆盖冲突文件。见 [工作台作品管理](WORKBENCH_ARTIFACTS.md)。
 - 符号链接不会被私有树权限收紧逻辑跟随。Doctor 会把 Iris 数据根为符号链接视为硬错误。
 
 ## Web 与渲染
@@ -49,7 +49,7 @@ API、SSE 和 Doctor 只返回凭据存在性或掩码提示。Provider 错误
 
 ## 离线 Doctor
 
-`dsh-iris doctor` 不启动 DSH，不发送供应商或计费请求，也不打印 API Key。默认 DSH 模式会在 Iris 数据目录或最近可写父目录创建一个随机小文件并立即删除，用于验证真实写权限；开发中的显式 `--data-root <abs>` Core 模式只读检查指定根的结构、索引、任务和租约，不做写探针，也不自动释放租约。`--json` 与文本输出使用同一结果模型，退出码为：`0` 正常、`1` 有警告、`2` 有硬错误。
+`dsh-iris doctor` 不启动 DSH，不发送供应商或计费请求，也不打印 API Key。默认 DSH 模式会在 Iris 数据目录或最近可写父目录创建一个随机小文件并立即删除，用于验证真实写权限；显式 `--data-root <abs>` Core 模式只读检查指定根的结构、索引、任务和租约，不做写探针，也不自动释放租约。`--json` 与文本输出使用同一结果模型，退出码为：`0` 正常、`1` 有警告、`2` 有硬错误。
 
 Doctor 不能证明 DSH 工具注册、浏览器、附件服务、客户端资源或真实 Provider 在线；这些仍需各自验证。
 

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，包括同步/异步、上传/提交、混合协议候选、工作台稳定用户态、状态流防倒退、重新观察、重新交付、提醒已读/恢复和知情人工重试。作品库 v0 只分离本地作品生命周期；正式 Artifact Manifest 仍属于后续工作。
+状态：**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)。
 
 ## 1. 为什么需要 v2
 
@@ -144,5 +144,5 @@ Task v2 至少包含以下事实轴；字段值采用可序列化的 snake_case
 
 - 不在语义冻结阶段重写全部任务存储或 UI。
 - 不新增 Gemini、Fal、Replicate 等供应商分支。
-- v0.1.3 包含零网络、可独立运行的离线 Doctor v0 与最薄 CLI；v0.1.4 已接入 Host/Provider Adapter、Host Doctor 和不含谱系的作品库 v0。完整 Artifact Manifest 仍属于后续版本。
+- 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 消费与编辑关系；两种存储保持独立。
 - 不用更多自动重试换取表面成功率。