@mokuyoaxis/dsh-iris 0.2.0 → 0.2.2

package/docs/HEADLESS_CLI.md

@@ -1,8 +1,10 @@
-# Headless CLI（0.2.0）
+# Headless CLI
 
-Iris 0.2.0 提供无 DSH 的本地裁剪、图片 diff、视频抽帧，以及 Provider 媒体任务闭环。结果保存为 Core Artifact，并可在后续进程中检查或导出。Core 内部接口与 Artifact v0 尚未冻结为跨版本公共 SDK。
+本文面向 Iris 0.2.2，涵盖无 DSH 的本地处理、媒体生成、视觉分析、配置和任务管理。媒体结果保存为 Core Artifact，可在后续进程中检查、分析或导出；纯视觉不自动创建产物。Core 内部接口与 Artifact v0 尚未冻结为公共 SDK。
 
-需要 Node.js ≥ 22.0.0。在自己的项目安装 `npm install @mokuyoaxis/dsh-iris@0.2.0` 后，通过 `npx dsh-iris ...` 使用命令；也可临时运行 `npx --package @mokuyoaxis/dsh-iris@0.2.0 dsh-iris --help`。下文的 `dsh-iris` 指该版本提供的可执行入口，不需要安装 DSH。
+需要 Node.js ≥ 22.0.0。安装 `npm install @mokuyoaxis/dsh-iris@0.2.2` 后运行 `npx dsh-iris --help`。源码入口为 `node bin/dsh-iris.js ...`；安装本地 tarball 后也可运行 `dsh-iris ...`。
+
+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)。
 
 ## 配置查询与离线诊断
 
@@ -26,6 +28,10 @@ dsh-iris runtime recover --data-root /absolute/path/to/iris-data --confirm-stale
 
 此命令会再次核对租约证据和 PID，写入私有恢复审计记录后释放陈旧租约；活跃、无法确认、损坏或 PID 不匹配时拒绝。它不是 Doctor 的自动副作用，也不会修复 Task/Artifact。不要手动删除 `.iris-runtime-writer-v0` 或把“PID 不存在”单独当作安全证明。
 
+0.2.2保留创建/释放意图和恢复步骤证据。Doctor 可报告 `phase: pending` 或 `recovering`；恢复本身被强杀后重新运行 Doctor，回显最新 PID，不沿用旧确认。只有完整证据且所有相关 PID 已退出才可继续；无 owner 的旧空目录及仅剩旧 `.owner.stale-*` 的现场仍拒绝。恢复审计保留完整退役目录，普通启动不删除它们。需要支持 hard link 的私有文件系统；参数、Task/Artifact/配置版本不变。细节与验证边界见 [Core Runtime 契约](CORE_RUNTIME_CONTRACT.md)。
+
+媒体与视觉路由会持久记录短时 429 冷却或明确额度/预算耗尽，后续候选跳过受阻模型。冷却到期不发起请求；持续停用需 `models test` 成功恢复。状态及私有配置写入规则见 [Provider 健康](PROVIDER_HEALTH.md) 与 [CLI 管理命令](CLI_MANAGEMENT.md)。
+
 ## 裁剪并保存 Artifact
 
 ```bash
@@ -71,6 +77,8 @@ dsh-iris run image \
 
 旧裸 DashScope 账号的已知目录仅在 DSH 配置加载或保存时一次性写入 `models`，随后可见、可编辑；CLI 只读配置，不执行该迁移。独立 CLI 配置须自行声明模型。
 
+生图按每个模型的有效图片协议调用，保存真实 PNG/JPEG/WebP 字节。聊天改图使用 `source_artifact_id`，创建关联原图的新 Artifact；具体参数和协议限制见 [模型级图片协议](CLI_MANAGEMENT.md#模型级图片协议) 与 [Artifact 聊天改图](CLI_MANAGEMENT.md#artifact-聊天改图)。
+
 同步图片会在一次命令内完成 Task → Attempt → Provider Adapter → download → Artifact。异步图片模型先持久化受理事实与远端 Task ID；之后由用户显式执行单步观察，不建立后台 timer。
 
 视频（t2v/i2v）同样走 Core：
@@ -82,7 +90,7 @@ dsh-iris run video \
   --input '{"prompt":"海浪拍岸","size":"1280*720","duration":5}'
 ```
 
-输入冻结为 `{prompt, size?, duration?, img_data_url?, model_ref?}`：`img_data_url` 是首帧的 `data:image/` data URL（i2v）；s2v 数字人上传流程不在 headless 面开放。视频交付走独立 Profile：远端成功后下载为 `video/mp4`，Artifact kind 为 `generated-video`。受理后由显式 `task observe` 逐拍推进（DashScope 视频通常需要数拍）。
+普通视频输入为 `{prompt, size?, duration?, img_data_url?, first_frame_path?, model_ref?}`：首帧可用 data URL 或绝对本地路径，二者互斥。0.2.1 支持 S2V 的 `first_frame_path + audio_path + resolution?`，共用 Core Attempt 的按候选上传，见 [CLI 管理与补齐](CLI_MANAGEMENT.md)。视频产物为 `video/mp4` / `generated-video`。显式 `task observe` 每次推进一拍；0.2.1 `task wait` 提供有界等待，不重新提交。
 
 语音合成是同步完成型，一次命令内完成 Task → Attempt → 交付：
 
@@ -197,10 +205,10 @@ dsh-iris artifact rebuild --data-root /absolute/path/to/iris-data
 ## 当前边界
 
 - Core 的 `run`、`media`、`task`、`artifact` 和 `runtime recover` 操作必须显式提供绝对 `--data-root`，避免误写日常 profile；配置查询只要求 `--provider-config`，Doctor 省略数据根时按上述默认范围检查。
-- 该路径只使用 Node.js、`sharp` 和 Iris Core，不加载 DSH/Cordis，也不启动服务；只有显式 `run image`、`run video`、`run tts`、`run transcribe`、`task observe`、`task redeliver`、`task cancel` 和 `task retry` 会访问供应商。
+- 该路径只使用 Node.js、`sharp` 和 Iris Core，不加载 DSH/Cordis，也不启动服务；只有显式媒体生成、视觉分析、模型发现/实测及任务观察/等待/交付/取消/重试会访问供应商；Doctor 与本地列表查询不触发探针。
 - Artifact Manifest v0 已包含 SHA-256、关系边、可重建 Index 和进程崩溃窗口恢复；格式与限制见 [Artifact Manifest v0](ARTIFACT_MANIFEST.md)。
-- 当前开放 `crop`、同步/异步图片提交、视频 t2v/i2v 提交、语音同步合成（`run tts`）、音频转写（`run transcribe`）、图片/视频/转写单步观察（CLI `task observe` 与工作台「重新观察」共用）、失败产物重新取回（CLI `task redeliver` 与工作台「重新取回作品」共用）、人工取消（CLI `task cancel` 与工作台「取消任务」共用，只有供应商明确确认才记为已取消）、重试为新任务（CLI `task retry` 与工作台「重试为新任务」共用，必须显式确认计费且重新提供 prompt/文本/音频地址）、Task 只读查询与 Artifact 管理；自动观察、其他媒体能力和其余 Command 会按相同事实语义逐项迁入。
-- CLI 暂不提供 Core Task/Artifact 删除能力（`task`/`artifact` 的 `inspect/list` 均为纯 reader）；DSH 工作台的删除、清空与孤儿清理也只处理 legacy `outputs/`，Core 作品同样只读。不要手动删除 `core-v0` 中的记录、Manifest 或对象；Core 删除与清理能力计划在 0.2.x 开放。
+- 当前开放 `crop`、同步/异步图片提交、视频 t2v/i2v 提交、语音同步合成（`run tts`）、音频转写（`run transcribe`）、图片/视频/转写单步观察（CLI `task observe` 与工作台「重新观察」共用）、失败产物重新取回（CLI `task redeliver` 与工作台「重新取回作品」共用）、人工取消（CLI `task cancel` 与工作台「取消任务」共用，只有供应商明确确认才记为已取消）、重试为新任务（CLI `task retry` 与工作台「重试为新任务」共用，必须显式确认计费且重新提供 prompt/文本/音频地址）、Task 只读查询与 Artifact 管理；0.2.1 已补齐 S2V、HTML、视觉分析、模型与配置管理、任务等待、批量操作和 Core 隔离/恢复，见 [CLI 管理](CLI_MANAGEMENT.md)。后台自动观察由 DSH 生命周期负责，CLI 不启动常驻服务。
+- 0.2.1 Headless CLI 提供 `core delete/cleanup/transactions/restore`：默认只读预览，明确选择和确认后隔离文件，引用保护和恢复哈希检查均生效，详见 [CLI 管理与补齐](CLI_MANAGEMENT.md)。DSH 工作台已接上同一 Core 隔离/恢复命令，见 [工作台作品管理](WORKBENCH_ARTIFACTS.md)；既有永久删除、清空与孤儿清理仍只处理 legacy `outputs/`。Core 永久 purge 留待 0.2.x，不要手动删除 `core-v0` 中的记录、Manifest 或对象。
 
 ## 源码仓库的包外验收
 

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.2 已提供独立 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.2。** 0.2.0 已包含 M1 契约；0.2.2 接入 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,29 +244,31 @@ 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 中明确记录，不能把这条路径称为完全零副作用。
 
 提示词优化仍由 DSH 边界读取 v1 配置、解析固定/会话/默认模型，返回选择来源供 UI 展示。共享核心只接收选定端口与模板；保留原草稿、预览后写回和不携带会话历史的行为。Provider 健康反馈由入口消费安全结果/错误，模型端口不导入健康 Store。
 
+0.2.2 的一般功能在既有消费者上增加 faithful / rewrite / suggestions 策略；忠实整理校验原文片段覆盖和顺序，独立建议不自动加入正文。新策略与五用途不改变 Model Port 的单次调用契约，不新增自持文本能力、独立提示词 CLI 或公开 SDK；具体输出协议和旧调用兼容见 [提示词优化系统](PROMPT_OPTIMIZER.md)。
+
 ## 实现切片与退出条件
 
-M1 已完成。以下其余切片仍为实施建议，不要求一次跨模块改造；提示词优化的功能定位与输入隔离继续讨论，M2 未获本轮实施授权。
+0.2.0 包含 M1；0.2.1 包含 M2/M3/M4 和 M5 独立视觉 CLI，详见 [视觉 CLI](VISION_CLI.md)。一般提示词功能的新增编辑策略属于 0.2.2，特殊功能及独立提示词入口后续安排。
 
 | 切片 | 范围 | 退出条件 |
 |---|---|---|
 | 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 +281,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 +299,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.2**。定位、拼图摘要及自述见 [复合视觉调用](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,77 @@
+# 提示词优化与规则组装
+
+状态：**Iris 0.2.2**。在既有按次规则、只组装和可编辑预览上增加一般功能，特殊功能待后续安排。
+
+## 一般功能（0.2.2）
+
+面板将一般功能放在可折叠卡片中，按“通用、画图、改图、视频、数字人”选择用途。当前草稿、本次规则、操作、可编辑结果和对照属于同一功能区域；折叠不清空选择、规则或结果，也不触发模型请求。指令与模型设置独立折叠，可在调用前查看当前系统指令和目标模板。浏览器原生对话框在顶层显示，避免宿主悬浮按钮遮住结果。桌面和窄屏使用同一流程，支持点击背景或 Escape 关闭、焦点恢复与对话框内键盘焦点循环。
+
+| 目标 | 标识 | 内置优化重点 |
+|---|---|---|
+| 通用 | `general` | 目标、背景、约束、输出和验收 |
+| 画图 | `image` | 主体、场景、构图与已指定风格 |
+| 改图 | `image-edit` | 明确修改范围，保持原图其余特征 |
+| 视频 | `video` | 动作先后、镜头与连续性 |
+| 数字人 | `s2v` | 已有首帧与音频下的人物动作、表情和镜头 |
+
+默认指令参照项目 Skills 的职责、目标、输入、保持/改变和输出组织方式，并使用实际 Iris 工具语义。S2V 的旧内置“首尾帧”标签有误，本轮修正为首帧+音频数字人。优化器仍只编辑草稿，不读取图片/音频、不生成媒体，也不冒充已经检查素材；具体方位、数量、颜色、数值、引用原文和否定条件必须保留。模型实际是否遵守仍需用户检查原文对照。
+
+v1 配置兼容：增加 `targets["image-edit"]`，旧配置缺少此项时只在内存补齐，不自动重写文件。既有 systemPrompt、目标模板与模型路由优先保留，包含用户自定义 s2v 文本；用户显式恢复默认后才替换为新的内置指令。没有新增规则持久格式、特殊功能或 CLI。
+
+### 编辑方式（0.2.2）
+
+新界面默认选择 **忠实整理**：模型只选择相邻原文片段之间的分段位置，程序从原稿拼回正文。每个片段必须恰好出现一次、句序保持，遗漏、重复、调换或新增内容都会拒绝。条件、动作先后、引文、代码和复杂格式采用保守分段；已有完整文本允许保持原样。本次保证的是原文片段和顺序，不是自动证明所有排版变化的语义完全相同。
+
+需要等义润色或明确改变某个项目时，选择 **改写表达** 并填写本次改写规则。例如“只把白色丝袜改为黑色，其余保持”授权改变指定颜色；其余事实和否定继续保留。忠实整理不会静默执行或丢弃改写规则。改写表达仍是模型生成文字，新增含义与遗漏需查看对照，不能以结果非空证明忠实。
+
+结果中的 **可选补充与待确认** 独立于正文。点击“获取补充建议”才新增一次模型调用，不自动生成第二轮；默认未勾选，勾选也不改正文，点击“采纳所选建议”后才加入可编辑预览。采纳与撤回不调用模型、不直接写回或发送。手动修改预览会清除旧建议绑定，避免撤回旧快照覆盖你的编辑；再次获取建议针对当前文字。失败、取消、会话切换或请求期间文字变化不会把迟到建议写入预览。
+
+只组装仍为零模型调用。旧后端未声明编辑能力时保留原“智能优化”流程，不发送其不支持的新策略。会话/fixed 模型选择保持，不因为选择“画图”用途就进入生图模型池，也不硬编码供应商默认模型或失败后自动切换。
+
+## 使用
+
+在 DSH 输入框写入未发送的纯文本草稿，打开 🫧 并选择用途。0.2.2 提供五用途和一般功能新布局；旧 0.2.1 的四目标调用仍兼容。
+
+“本次规则”可填写以下内容；留空表示不选择。规则只在当前组件中保留，刷新后重置，不改写已有 `prompt-optimizer.json`。
+
+| 内容 | 智能优化 | 只组装 |
+|---|---|---|
+| 改写规则 | 指导模型如何编辑草稿，不要求将规则原文抄入结果 | 不使用 |
+| 输出前缀 | 模型改写完成后，程序原样加入开头 | 原样加入原稿开头 |
+| 输出后缀 | 模型改写完成后，程序原样加入末尾 | 原样加入原稿末尾 |
+
+智能优化进行一次文本模型生成；只组装不读取模型路由或优化配置、不调用模型，在 Host 文本服务不可用时仍可使用。只组装不会套用目标模板或自动润色原稿。规则之间与正文之间用两个 LF 分隔；输出规则原文与只组装的草稿空白保持不变。
+
+结果先进入可编辑预览。可以查看原文、本次参与规则、实际模型与思考策略，以及折叠相同首尾后的中间替换区。这是文本改动对照，不代表模型解释了每处改动的原因。手动编辑也会更新对照；复制和写回使用编辑后的文字。
+
+实现前的真实模型补测发现，文本模型别名也可能返回图片链接，甚至返回扩写正文加图片链接。改写结果会在拼接前后缀之前检查未由原稿/明确改写规则提供的新链接、媒体标记和明显的执行完成/拒绝回复；已有合法链接、原文引用及只组装保留。忠实整理与建议模式另检查专用 JSON 形状、片段序列或建议字段，未授权正文不能混入。检查不构成任意自然语言的完整语义证明。拒绝后不自动重试、切换模型或写回；上游可能已经处理请求，不能据此推定没有计费或媒体副作用。
+
+写回不会自动发送。出现新草稿时先确认替换；出现结构化 `@`、`/` 引用或忙碌状态时拒绝写回。切换会话清除旧预览并取消在途操作，即便两边草稿文本相同。取消、关闭或卸载会传递 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 只组装只提交输出规则。
+
+0.2.2增加可选 `editing: "faithful" | "rewrite" | "suggestions"`，仅用于 optimize。省略时保持旧文字改写协议与 `optimized` 文本响应，不破坏旧调用；新界面显式传 faithful。faithful 允许输出前后缀但不接受 optimization 规则，响应另含 `editing: { strategy, coverage: "exact", order: "preserved", groups }`。suggestions 不接受任何规则，`optimized` 逐字等于原稿，另含 `suggestions: [{ id, label, text }]`、`questions: string[]`，ID 由程序生成；本轮指令要求至多三条有用建议/问题，协议上限分别为六条，label 最多 80、text/问题最多 600 字符。它们未经事实验证或采纳，不能当成用户已有要求。
+
+配置 API 在配置对象外返回 `capabilities: { rules: true, assemble: true }`；0.2.2另声明 `targets: ["general", "image", "image-edit", "video", "s2v"]` 与 `editing: ["faithful", "rewrite", "suggestions"]`。客户端读到明确能力才启用规则、只组装、新改图目标与新编辑策略。没有 targets 声明时只启用旧四目标，没有 editing 声明时保持旧智能优化；能力字段不进入配置导出文件。
+
+参见 [Model Port 契约](MODEL_PORT_CONTRACT.md) 与 [架构边界](ARCHITECTURE.md)。浏览器/Android 交互和真实模型质量需各自验收。

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.2；沿用 v0 生命周期内部契约。** 0.1.4 建立六操作契约，0.2.0 增加可选输入准备能力，0.2.2 增加聊天/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,17 @@ 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，而不是伪装取消成功。
+
+0.2.2对视频、音频及文本 staging 复用 Artifact Store 的文件复制接收路径，哈希仍按 1 MiB 分块计算，不再为落库整文件 `readFileSync`。Profile、大小核对、元数据、关系边和交付失败事实保持。图片仍读取字节验证真实格式；inline 响应的解码以及工作台预览/ZIP 等读取路径仍可能使用完整 Buffer，本改动不声称端到端流式传输。
+
+聊天改图仍使用 `capability:image`：Runner 从当前 Core 校验并读取来源 Artifact，短生命周期 `input.image:{bytes,mediaType}` 与 `prompt` 交给聊天适配器。适配器按实际模型 `visionInput` 准备副本，HTTP 用户消息使用 `text` 与 `image_url` data URL。普通 Images/Responses 不接受此输入，编辑候选链预先过滤协议。Task 仅保存可选 `sourceArtifactId`，用于未知/失败任务的来源保护和交付时写入新 Artifact 的 `derived-from`；旧记录无需迁移，重试仍重新提供输入。来源或编辑输入预算失败发生在 HTTP 之前。
 
 ## 可选输入准备与上传边界
 
 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，不能由错误字段反推已经落盘。
 
 ## 错误与取消传播
 
@@ -90,14 +94,20 @@ Host 和 CLI 通过 `prepareProviderInput(adapter, { model, filePath, signal?, t
 
 `submit` 抛错由统一调用器转换成保守四态；`cancel` 抛错转换为 `unknown`；`discover/poll/download` 抛出脱敏的 `ProviderContractError`，由各自调用方应用重试和事实规则。
 
+0.2.2的生图传输同时覆盖请求与响应正文读取。包装的网络异常在尚未取得响应头时标记 `stage=submit`，取得响应头后正文读取失败时标记 `stage=response`；已知网络超时码归类 timeout，两者都保留 `acceptance=unknown`，不凭 HTTP 200 响应头断言完整生成成功。可用的底层网络错误码放入既有 `providerCode` 字段，提示区分 DNS、TLS、连接建立、等待响应头及正文读取；没有明确错误码时只描述实际阶段。原生 AbortError、TimeoutError 或 ABORT_ERR 保留原异常及取消/超时分类，未附加正文读取阶段证据时沿用提交调用的阶段。完整 HTTP 业务响应仍按鉴权、限流/额度、参数或供应商错误分类，明确分类不被错误文字中的 timeout 覆盖。
+
+本地尺寸校验使用 `validate / invalid_request / not_accepted`，在 HTTP 前失败。分隔符按协议归一，DashScope 多模态只执行已有证据的总像素范围，不推断单边上限；OpenAI 兼容网关的数值集合留给上游。`retryable` 表示错误类别可重试，不授权重提受理未知的收费请求；Core 的受理门继续先于候选切换。DSH 动作错误附带同一脱敏 `safeMessage`，不输出原始 cause、正文或凭据。
+
 ## 当前内置实现
 
 | 协议 | discover | submit | poll | cancel | download | mapError |
 |---|---:|---:|---:|---:|---:|---:|
 | DashScope | 支持（`/api/v1/models` 分页与能力元数据） | 图片/视频/TTS/转写 | 图片/视频/转写 | 显式不支持 | 支持 | 支持 |
 | OpenAI Images 兼容 | 支持 | 同步图片 | 显式不支持 | 显式不支持 | 支持 | 支持 |
+| OpenAI 聊天生图兼容 | 支持 | 同步图片/单来源改图 | 显式不支持 | 显式不支持 | 支持 | 支持 |
+| OpenAI Responses 生图兼容 | 支持 | 同步单图 | 显式不支持 | 显式不支持 | 支持 | 支持 |
 
-本表只描述协议生命周期，不扩大 0.1.4 的供应商范围。Gemini、Fal 与 Replicate 仍在 0.2.x 路线中。
+本表描述已实现的协议生命周期；网关 Gemini 模型可以使用兼容协议，不代表原生 Gemini Adapter 已接入。原生 Gemini、Fal 与 Replicate 仍在后续路线中。
 
 ## conformance runner
 

package/docs/PROVIDER_HEALTH.md

@@ -1,6 +1,6 @@
 # Provider 与能力健康状态
 
-状态：v0.1.4 候选契约。
+状态：**Iris 0.2.2**。新增短时限流冷却与明确额度/预算耗尽停用，沿用既有持久健康证据。
 
 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 路径。