@mokuyoaxis/dsh-iris 0.2.0 → 0.2.1

package/.dsh/skills/iris-compose-media/SKILL.md

@@ -35,11 +35,13 @@ Do not add an analysis, transcription, or review step merely because a tool exis
 
 ## Resolve media inputs
 
-- Use `iris_look_at_image` for an absolute image path visible to the host.
+- For edits to an existing Core image, pass its ID as `source_artifact_id` to `iris_edit_image` with the requested change. This creates a new Task and Artifact while keeping the source intact; it requires a configured chat image model.
+- PNG, JPEG and WebP can be used directly; do not convert a generated PNG to JPEG merely to call vision or OCR. Core IDs and host paths remain separate inputs.
+- Use `iris_look_at_image` for a host-visible absolute `image_path` or an existing Core image `artifact_id` (choose one).
 - Use `iris_relook_attachment` for an image attachment already present in the session or produced by Iris.
-- Use `iris_long_ocr` when exact text from an image matters more than a visual description.
-- Video and audio tools require host-visible absolute `video_path` or `audio_path` values. A browser-local path, `content://` URI, or ordinary web URL is not a host path; request an upload or exported host path.
-- Keep every returned attachment ID, task ID, and output path that a later step needs. Do not invent or reconstruct identifiers.
+- Use `iris_long_ocr` when exact text from an image matters more than a visual description; choose exactly one of `image_path`, Core `artifact_id`, or session `attachment_id`. `iris_locate` accepts the same three sources for original-pixel bounding boxes.
+- Video and audio file inputs require host-visible absolute `video_path` or `audio_path` values. Video summaries can instead consume existing Core `frame_artifact_ids`. A browser-local path, `content://` URI, or ordinary web URL is not a host path; request an upload or exported host path.
+- Keep every returned Core Artifact ID, attachment ID, task ID, and output path that a later step needs. Core `artifact_id` and session `attachment_id` are distinct; do not use either as a file path or invent identifiers.
 
 An attachment returned by `iris_draw_image` can be passed as `first_frame_attachment_id` to `iris_generate_video`. An existing host image uses `first_frame_path`. The local path returned by `iris_speak_text` can be passed as `audio_path` for S2V.
 
@@ -48,6 +50,7 @@ An attachment returned by `iris_draw_image` can be passed as `first_frame_attach
 Choose the minimum chain, then read only the matching section of [references/workflows.md](references/workflows.md):
 
 - inspect an image, then draw: `iris_look_at_image` or `iris_relook_attachment` → `iris_draw_image`;
+- edit a Core image, then inspect: `iris_edit_image` → `iris_look_at_image` using the new Artifact ID;
 - generate/reuse a still, then animate: optional `iris_draw_image` → `iris_generate_video`;
 - summarize a video, then narrate: `iris_media_summarize` → `iris_speak_text`;
 - create an S2V talking video: resolve a first frame and audio → `iris_generate_video`;
@@ -55,6 +58,8 @@ Choose the minimum chain, then read only the matching section of [references/wor
 
 Use `iris_video_frames` only for explicit frame extraction or a custom frame-level workflow. Do not load every workflow section when one route is sufficient.
 
+If frames are already saved by `iris_video_frames`, pass its returned `frame_artifact_ids` to `iris_media_summarize` instead of extracting again. This reads the original timestamps and frame order without the video file or ffmpeg. Omit `video_path`, `max_frames`, `target_width`, and `transcribe:true`; supply existing speech as `transcribe_text` when available.
+
 ## Control cost and iteration
 
 - Create one new Iris generation **Task** per requested artifact by default. A Provider Attempt is an internal candidate submission inside that Task; do not count failover attempts as user-authorized new Tasks.
@@ -72,7 +77,7 @@ When a generation tool returns a Task, or the user asks to retry, recover, cance
 - Observation failure resumes observation; delivery failure resumes delivery. Neither authorizes regeneration. If that recovery action is available only in the Iris workbench, say so and preserve the Task ID.
 - If the user cancels, stop the chain and do not launch downstream generation. Cancellation requested or unknown is not proof that no provider work occurred.
 - Preserve partial outputs. Report which step succeeded, which failed or became uncertain, and whether accepted work may remain active.
-- If an attachment is missing, request a re-upload or host path. If `ffmpeg`/`ffprobe` is unavailable, explain that frame extraction and video summarization cannot run.
+- If an attachment is missing, request a re-upload or host path. If `ffmpeg`/`ffprobe` is unavailable, new video frame extraction cannot run; summaries can still use existing Core frame IDs.
 - If vision is unavailable but the creation prompt is complete, skip source analysis only when the requested result still remains valid.
 
 ## Report the result

package/.dsh/skills/iris-compose-media/references/workflows.md

@@ -9,6 +9,12 @@ Read only the section matching the chosen workflow. Keep paid steps bounded by t
 3. Call `iris_draw_image` once for each requested artifact.
 4. Inspect the result only when verification or iteration was requested. A mismatch is evidence to report, not automatic permission to regenerate.
 
+## Edit a Core image, then inspect
+
+1. Resolve the source Core Artifact ID; one static PNG, JPEG or WebP image up to 20 MiB is supported.
+2. Call `iris_edit_image` with `source_artifact_id` and a focused modification prompt, optionally an explicit model. The original stays intact and the edited Artifact records its source.
+3. Inspect the new Artifact ID only when review is requested. Preserve the Task ID if acceptance or delivery is uncertain; do not repeat the edit automatically.
+
 ## Generate or reuse a still, then animate
 
 1. Create a still with `iris_draw_image`, reuse an Iris-produced first-frame attachment, or obtain a host-visible path. Do not pass an ordinary session attachment as `first_frame_attachment_id`.
@@ -18,7 +24,7 @@ Read only the section matching the chosen workflow. Keep paid steps bounded by t
 
 ## Summarize a video, then narrate
 
-1. Call `iris_media_summarize` with `transcribe=true` unless the user wants visual-only analysis.
+1. Call `iris_media_summarize` with `video_path` and `transcribe=true` unless the user wants visual-only analysis. If Core frames already exist, use their `frame_artifact_ids` instead and optionally provide `transcribe_text`; omit `transcribe=true` and sampling options for existing frames.
 2. Do not also call `iris_video_frames` or `iris_transcribe_audio` by default; the summary action already samples frames and can transcribe audio.
 3. Write narration for the requested audience and length without presenting inference as visible fact.
 4. Call `iris_speak_text`; return the summary, contact-sheet attachment, and saved audio path.

package/.dsh/skills/iris-verify-ui/SKILL.md

@@ -22,6 +22,7 @@ Ask one concise question only when a missing reference, target state, theme, or
 ## Prepare the inputs
 
 1. Identify each image source:
+   - Existing Core image: pass `artifact_id` to look/locate/OCR. Crop and pixel diff still need a supported path or attachment; export the Artifact explicitly if those steps require it.
    - Host absolute path: pass `image_path`.
    - Current-session or Iris-produced attachment: pass `attachment_id`.
    - Browser-local path, `content://` URI, or ordinary web URL: do not assume the host can read it. Ask for an upload or a host-accessible file.
@@ -45,7 +46,7 @@ When raw HTML needs capture, call `iris_html_screenshot` with the same HTML wrap
 
 ### 2. Inspect semantics
 
-Inspect the current and reference images separately. Call `iris_look_at_image` for a host path and `iris_relook_attachment` for an attachment.
+Inspect the current and reference images separately. Call `iris_look_at_image` for a Core Artifact ID or host path and `iris_relook_attachment` for an attachment.
 
 Each vision call sees only one image. Ask the same structured questions for both images:
 

package/CHANGELOG.md

@@ -4,7 +4,51 @@
 
 ## [Unreleased]
 
-暂无。
+后续未归入版本的变更在此记录。
+
+## [0.2.1] - 2026-10-09
+
+0.2.1 的更新重点是 **完成 OpenAI 兼容图片与视觉工作流**：生成图片 → Core Artifact → 按 ID 看图/OCR → 聊天改图 → 新 Artifact，CLI 与 DSH 工作台共用同一链路。模型发现与能力分类、模型级图片协议、视觉输入和作品管理共同支持这套流程。要求仍为 Node.js ≥ 22.0.0，DSH 插件仅支持 `0.2.0-rc.2`；包名、配置版本和生产依赖保持不变。完整范围见 [0.2.1 发布说明](docs/releases/0.2.1.md)。
+
+### Added
+
+- 生图模型可独立设置 `imageProtocol`，分别选择 DashScope、OpenAI Images、聊天生图或 Responses 生图；省略或 `auto` 时继承账号默认。同账号的模型可使用不同接口，生成、实测和恢复按实际协议绑定，不扫描接口或自动探测。
+- 聊天生图兼容非流式 Chat Completions 图片消息；Responses 支持同步单图、已完成的 `image_generation_call` 及网关图片消息。生成结果按真实字节保存为 PNG/JPEG/WebP Core Artifact，MIME、后缀和内容哈希一致。纯文字 200、缺图或未完成响应不会宣称成功或自动重提。
+- Artifact ID 聊天改图：DSH `iris_edit_image`、Core 图片卡“改图”与 CLI `run image` 的 `source_artifact_id` 共用 `openai-chat-images`。修改版另存为新 Artifact，记录 `derived-from` 及来源引用，原图保留；编辑池只选择聊天生图模型。详见 [Artifact 聊天改图](docs/CLI_MANAGEMENT.md#artifact-聊天改图)。
+- 独立视觉 CLI：`vision look / locate / ocr / summarize`，支持严格显式模型选择、JSON/文本、结果文件和摘要拼图输出；DSH 与 CLI 复用共享视觉业务。纯视觉不创建 Task/Artifact，主动音轨转写使用 Core。
+- 看图、定位和 OCR 支持 `artifact_id`；视频摘要支持 `frame_artifact_ids`。只读核验 Core 原字节、MIME 和哈希，不要求原文件或临时导出；已有视频帧无需再次抽帧或 ffmpeg。
+- 账号与模型可配置 `visionInput.maxBytes/maxDimension`，模型逐字段覆盖账号，默认发送预算 8 MiB。工作台和 CLI `models vision-input` 可设置或恢复继承；看图、OCR 分块、定位和聊天改图按实际候选准备发送副本，Core 原图、下载与哈希不变。
+- 工作台统一 Core/旧版图片、视频、音频和文本，每页 24 项，支持媒体、来源和产物类型过滤、真实匹配计数。Core 图片卡直接看图/OCR/改图，识别结果可取消、复制和下载，并明确 OCR 部分完成。
+- 作品详情、显式跨页选择、ID 复制与混合来源 ZIP 下载，单次最多 200 项、下载上限 128 MiB。Core 删除先预览，再确认移入可恢复回收区；恢复不覆盖冲突文件。详见 [工作台作品管理](docs/WORKBENCH_ARTIFACTS.md)。
+- CLI 补齐 S2V 数字人视频、HTML 截图、账号/模型/能力分配管理、模型发现与显式实测、有界 `task wait`、分页过滤、批量查询/导出，以及 JSON 文件和 stdin 输入。
+- CLI `core delete/cleanup/transactions/restore` 提供默认预览、引用和活跃任务保护、明确选择后的隔离、哈希核对恢复及失败补偿；不提供永久 purge。
+- 对话泡泡增加本次改写规则、原样前缀/后缀、“只组装”、可编辑结果和原文/改动对照。规则按次传入，v1 配置保持不变；未扩展后续独立提示词优化系统。
+
+### Changed
+
+- 提示词优化、单图看图/重看、OCR、定位、视频拼图摘要及生成后自述迁入共享 Text/Vision Model Ports。准备与候选共用整体预算，严格检查正常终态；取消、超时、截断或协议错误停止后续生成，超长正文明确失败。
+- OCR 整次操作最多 32 块、64 次生成、120 秒；先按转正后的长图切片，再按候选预算处理每块，记录实际发送尺寸与字节数，缩小时提示细字风险，区分完成、部分完成和失败。
+- 定位显式要求模型返回 0–1000 归一化坐标，依据实际发送尺寸和 EXIF 方向换算回原图像素，向外取整供裁剪；接受经核验的 DSH 附件规范化，不猜测返回坐标域。
+- 模型路由区分短时限流和明确耗尽。短时 429 按 `Retry-After`（默认 60 秒）冷却，以琥珀色显示；到期只恢复候选资格，不自动验证。明确免费额度或预算耗尽以红色持续停用至手动实测成功，重启后仍跳过。DSH、CLI、OCR 共用账号 × 模型规则。
+- S2V 首帧与音频迁入共享 Core Attempt 上传链，各候选使用自己的账号；HTML 截图经独立 Chromium Browser Port 或 DSH 宿主保存 Core PNG。配置写入使用私有备份、原子替换和竞争写保护。
+- 修改模型图片协议只使对应生图验证失效，不解除限流或耗尽停用；发现保留手工能力、协议覆盖和输入预算。原图引用参与 Core 删除与清理保护。
+
+### Fixed
+
+- 修复 4K 生图响应的 base64 校验触发调用栈溢出，保留原字节交付与字符、padding 校验。
+- 修复视觉探针图片过小造成的能力误判，改用 128×128 红色 PNG。
+- 修复 OCR 显式 `overlap: 0` 被入口默认值覆盖，以及失败块导致后续原段号丢失。
+- 修复视频摘要时间戳标签未绘制、十帧以上按文件名字典序排列造成的时序错乱；交付与模型输入使用同一张拼图。
+- 保护提示词写回时的新草稿、忙碌状态和结构化引用，旧请求迟到结果不覆盖新操作；不支持的显式 reasoning effort 在生成前拒绝。
+- 修正跨平台 CLI 测试的文件 URL、路径、权限与信号断言；缺少可选 ffmpeg/ffprobe 时只跳过相应视频段。
+
+### 已知限制
+- 浏览器/移动端完整作品管理，以及真实异步任务重启后的 CLI 接管尚未完成验收；已有本地测试和 rc.2 服务隔离检查不替代这些验证。
+- Responses 当前仅同步单图；聊天改图不支持 mask、多参考图或连续编辑历史。独立 Images 编辑与原生 Gemini/Fal 协议未在本版接入。
+
+### 后续方向
+
+- 继续适配其他协议，并规划 Music 音乐生成功能；均属于后续工作，不纳入 0.2.1。详见 [路线图](docs/ROADMAP.md#后续功能方向)。
 
 ## [0.2.0] - 2026-10-01
 
@@ -223,7 +267,8 @@ Iris 0.2.0 要求 Node.js ≥ 22.0.0，DSH 插件仅支持 `0.2.0-rc.2`；旧宿
 - 上传采用流式限额、临时 `.part` 文件和原子落盘，失败时会清理未完成文件。
 - 修改状态的路由拒绝明确的跨站请求，媒体文件继续使用随机能力令牌访问。
 
-[Unreleased]: https://github.com/mokuyoaxis/dsh-iris/compare/v0.2.0...HEAD
+[Unreleased]: https://github.com/mokuyoaxis/dsh-iris/compare/v0.2.1...HEAD
+[0.2.1]: https://github.com/mokuyoaxis/dsh-iris/compare/v0.2.0...v0.2.1
 [0.2.0]: https://github.com/mokuyoaxis/dsh-iris/compare/v0.1.4...v0.2.0
 [0.1.4]: https://github.com/mokuyoaxis/dsh-iris/compare/v0.1.3...v0.1.4
 [0.1.3]: https://github.com/mokuyoaxis/dsh-iris/compare/v0.1.2...v0.1.3

package/README.en.md

@@ -8,7 +8,7 @@
 
 <h1 align="center">Iris Media for DSH</h1>
 
-<p align="center"><strong>A multimodal media production runtime · currently shipped as a DeepSeek Harness plugin</strong></p>
+<p align="center"><strong>A multimodal media production runtime · DSH plugin and standalone CLI</strong></p>
 
 <p align="center">
   <a href="#deepseek-harness-adaptation"><img alt="DeepSeek Harness compatible" src="https://img.shields.io/badge/DeepSeek%20Harness-compatible-4D6BFE.svg?style=flat-square"></a>
@@ -18,7 +18,7 @@
   <a href="LICENSE"><img alt="MIT License" src="https://img.shields.io/badge/license-MIT-1689FF.svg?style=flat-square"></a>
 </p>
 
-dsh-iris gives agents and the Iris workbench image, video, speech, and visual understanding capabilities, and it can optimize any draft directly in the DSH composer. It connects to Alibaba Cloud DashScope (Bailian) and to OpenAI Images–compatible services. Configuration and task management live in the Iris workbench, and a floating Iris bubble in the bottom-right corner is the quick entry point.
+dsh-iris gives agents, the Iris workbench and a standalone CLI image, video, speech and visual understanding capabilities. Each image model can use DashScope, OpenAI Images, chat image generation or Responses. Shared Core Artifacts connect generation, vision, OCR and chat editing. The DSH workbench provides configuration and task management, while the 🫧 bubble offers draft optimization in the composer.
 
 ## A real generation example
 
@@ -44,18 +44,34 @@ These captures come from an Android browser connected to DSH under Termux/PRoot
 
 The project is at an early stage; interfaces and configuration formats may still change between releases.
 
-Iris is evolving toward a media production core that can run independently and plug into different agent hosts. Version 0.2.0 provides both a DSH plugin and a headless CLI media path (crop, image/video/TTS/transcription submission, task observation, artifact export). Core internals have not been frozen as a public SDK.
+Iris 0.2.1 provides a DSH plugin and a headless CLI sharing tasks, artifacts and model routing, completing the OpenAI-compatible image and vision workflow. Core internals have not been frozen as a public SDK.
 
-> Version support: Iris `0.2.0` requires Node.js `>=22.0.0` and its DSH plugin supports only the exact host version `0.2.0-rc.2`. Older DSH hosts should pin `@mokuyoaxis/dsh-iris@0.1.4` as described below instead of following npm latest. Iris and DSH have independent version numbers.
+> Version support: Iris `0.2.x` requires Node.js `>=22.0.0` and its DSH plugin supports only the exact host version `0.2.0-rc.2`. Older DSH hosts should pin `@mokuyoaxis/dsh-iris@0.1.4` as described below instead of following npm latest. Iris and DSH have independent version numbers.
+
+## What's new in 0.2.1
+
+**Complete the OpenAI-compatible image and vision workflow:** image generation → Core Artifact → vision/OCR by ID → chat editing → new Artifact, shared by the CLI and DSH workbench.
+
+- **Models and protocols:** discover models and classify capabilities, then choose image protocols per model; models within one account can use Images, chat or Responses interfaces.
+- **Image delivery:** preserve PNG/JPEG/WebP bytes and handle large base64 image responses.
+- **Artifact editing:** edit from a Core image card, `iris_edit_image`, or the CLI; save a linked new image while preserving the source.
+- **Standalone vision:** look, locate, OCR and video summaries with explicit model selection and direct image/frame Artifact inputs.
+- **Input budgets:** configure account/model sending limits, preserve originals, report OCR resizing and map locate coordinates to source pixels.
+- **Library and CLI management:** pagination, filters, selection across pages, ZIP downloads and recoverable Core deletion; S2V, HTML screenshots, configuration and bounded waiting.
+- **Model recovery:** amber for temporary 429 cooldown; red for confirmed quota or budget exhaustion until a manual test succeeds.
+
+See the [0.2.1 release notes](docs/releases/0.2.1.md) and [CHANGELOG](CHANGELOG.md) for scope and pending checks.
+
+Future work includes additional protocol adapters and **music generation**; see the [roadmap](docs/ROADMAP.md#后续功能方向).
 
 ## Two ways to use Iris
 
-| | Path A: DSH plugin (0.2.0) | Path B: Headless CLI (0.2.0) |
+| | Path A: DSH plugin | Path B: Headless CLI |
 |---|---|---|
 | Who it's for | DeepSeek Harness users who want agent tools, the workbench, and in-chat prompt optimization | Users who want media generation, task tracking, and artifact export from the command line without DSH |
 | Entry point | Choose a pinned release under "Quickest start" below | `dsh-iris run ...` — see [Headless CLI](docs/HEADLESS_CLI.md) |
 | Data location | `$DSH_HOME/iris/v1/` (Core data root `core-v0`) | Any absolute path passed via `--data-root` |
-| Automatic observation | Yes (bounded DSH host ticks + restart takeover) | No — explicit single-step `task observe` |
+| Automatic observation | Yes (bounded DSH host ticks + restart takeover) | Explicit `task observe`; 0.2.1 also offers bounded `task wait` |
 | Dependencies | DSH `0.2.0-rc.2` and Node.js ≥ 22 | Node.js ≥ 22 and `sharp` only (`ffmpeg` for video frames) |
 
 Both paths read and write the same Core Task/Artifact facts: point the CLI at the `core-v0` data root of a DSH profile to inspect/export DSH-generated artifacts, and vice versa. Only one writer is allowed per data root.
@@ -74,7 +90,7 @@ Check the host with `dsh --version` and ensure `pnpm` is on your PATH. Iris and
 
 | Your DSH | Iris choice | Source |
 |---|---|---|
-| `0.2.0-rc.2` | `0.2.0` | Pinned npm release |
+| `0.2.0-rc.2` | `0.2.1` | Pinned npm release |
 | `>=0.1.2-rc.1 <0.1.3-0` or `0.1.5-rc.1` | Stable `0.1.4` | Pinned npm release |
 | Other versions | No current support claim | Check host adaptation before installing |
 
@@ -95,24 +111,33 @@ npm pack @mokuyoaxis/dsh-iris@0.1.4
 
 This writes a `.tgz` to the current directory. Use `npm install @mokuyoaxis/dsh-iris@0.1.4` if you only want a regular npm dependency; that does not add a DSH profile layer. Pinning `@0.1.4` keeps selecting the old stable release after latest changes. See [npm pack](https://docs.npmjs.com/cli/v11/commands/npm-pack/). Version 0.1.4 does not contain the 0.2.0 Core media CLI or the later DSH rc.2 adaptation.
 
-### DSH 0.2.0-rc.2: install 0.2.0
+### DSH 0.2.0-rc.2: install 0.2.1
 
-Install the pinned npm release into the Web profile:
+Install the pinned release into your Web profile:
 
 ```bash
-dsh plugin --profile web add @mokuyoaxis/dsh-iris@0.2.0
+dsh plugin --profile web add @mokuyoaxis/dsh-iris@0.2.1
 dsh web
 ```
 
-The plugin loads the next time DSH starts; the web UI defaults to `http://127.0.0.1:3080`. Open the complete URL if startup output includes authentication parameters. Version 0.2.0's compatibility metadata admits only DSH rc.2.
+The plugin loads on the next DSH start. The web UI defaults to `http://127.0.0.1:3080`; open the complete URL if startup output includes authentication parameters. Reload the backend and refresh the web client after updating.
+
+### Standalone CLI: install 0.2.1
+
+Install in your own project without DSH:
+
+```bash
+npm install @mokuyoaxis/dsh-iris@0.2.1
+npx dsh-iris --help
+```
 
 ### Choosing a version in dsh-market
 
-The marketplace entry should resolve to the full package name `@mokuyoaxis/dsh-iris`. Check both its displayed Iris version and your local `dsh --version` before installing: 0.2.0 is for DSH rc.2; older hosts should use the pinned `@0.1.4` commands above. Catalog and npm information may be cached. The actual npm package's `dsh.engines.dsh` and Node engines determine its declared requirements; a visible listing does not imply support for every DSH release.
+The marketplace entry should resolve to the full package name `@mokuyoaxis/dsh-iris`. Check both its displayed Iris version and your local `dsh --version` before installing: 0.2.1 is for DSH rc.2; older hosts should use the pinned `@0.1.4` commands above. Catalog and npm information may be cached. The actual npm package's `dsh.engines.dsh` and Node engines determine its declared requirements; a visible listing does not imply support for every DSH release.
 
 > The unscoped `dsh-iris` on npm belongs to a different plugin. Always keep the fully scoped name `@mokuyoaxis/dsh-iris` when installing or updating Iris Media.
 
-After the first start, open "Settings → Iris workbench → + Add provider", enter your DashScope base URL and API key, then click "Discover models". A single provider can start with automatic capability assignment. Full steps, OpenAI Images–compatible configuration, and failover notes are in the [user guide](user_guide.md) (Chinese).
+After the first start, open "Settings → Iris workbench → + Add provider", enter your provider base URL and API key, then click "Discover models". A single provider can start with automatic capability assignment. Full steps, image protocol selection, and failover notes are in the [user guide](user_guide.md) (Chinese).
 
 Once configured, minimal instructions can be as simple as:
 
@@ -142,26 +167,27 @@ For a copyable installation and usage prompt, see [Agent quickstart prompt](docs
 
 ## Prerequisites
 
-- A Node.js version that satisfies your DeepSeek Harness release's requirement; Iris 0.2.0 requires at least 22.0.0, while the published npm 0.1.4 historically requires 20.10.0
+- A Node.js version that satisfies your DeepSeek Harness release's requirement; Iris 0.2.1 requires at least 22.0.0, while the published npm 0.1.4 historically requires 20.10.0
 - A working DeepSeek Harness environment with `pnpm` on the PATH
 - At least one supported media or vision provider
-- `ffmpeg` and `ffprobe` on the system, for video frame extraction and video summaries
+- `ffmpeg` and `ffprobe` for extracting frames or summarizing a video file; summaries of existing Core frames need neither
 
 After installing the plugin, add a provider in the Iris workbench and assign models to the capabilities you need. Provider keys are kept in Iris's host-side configuration; on POSIX systems, Iris's own directories and files are tightened to `0700` and `0600` respectively, and neither the UI nor the API ever returns full keys. On Windows, file modes are not equivalent to ACLs — keep relying on your user directory and system account permissions.
 
 ## DeepSeek Harness adaptation
 
-dsh-iris remains a native DSH plugin. Its server registers 14 agent tools and uses host-provided routing, attachment, model, and lifecycle services. The web client contributes settings, composer, and global-overlay UI. Iris does not start another service or listen on an extra port.
+dsh-iris remains a native DSH plugin. Iris 0.2.1 server registers 15 agent tools, including image editing, and uses host-provided routing, attachment, model, and lifecycle services. The web client contributes settings, composer, and global-overlay UI. Iris does not start another service or listen on an extra port.
 
 | Iris version | DSH range | Verification |
 |---|---|---|
 | Published stable `0.1.4` | `>=0.1.2-rc.1 <0.1.3-0` | Historical clean and daily Web profiles on Linux ARM64 |
 | Published stable `0.1.4` | `0.1.5-rc.1` | Historical daily Android/Linux profile checks |
 | `0.2.0` | Only `0.2.0-rc.2` | Installed-service isolation checks, Core diff, and SlotRegistry; user demonstration reported successful, with detailed browser actions and asynchronous restart/rollback verification continuing |
+| `0.2.1` | Only `0.2.0-rc.2` | Installed-service checks cover 15 tools and 31 boundaries; complete browser/mobile and real asynchronous restart acceptance remain pending |
 
 See the [rc.2 adaptation notes](docs/DSH_RC2_ADAPTATION.md) for scope. The published npm 0.1.4 package does not contain these later changes.
 
-Iris 0.2.0 no longer claims older DSH support; historical validation does not automatically cover this version. DSH `0.2.0` stable and other rc versions are also outside its support range. Automated checks cover server loading, tool and Skill registration, routes, the client bundle, and UI slots separately so Doctor can identify which boundary failed.
+Iris 0.2.x no longer claims older DSH support; historical validation does not automatically cover this version. DSH `0.2.0` stable and other rc versions are also outside its support range. Automated checks cover server loading, tool and Skill registration, routes, the client bundle, and UI slots separately so Doctor can identify which boundary failed.
 
 Core and the DSH Adapter are being separated: DSH keeps loading the same npm package, while the Adapter maps host capabilities into Core. A DSH API change should require an Adapter or client-bridge fix, not a rewrite of Task or Artifact semantics. Version 0.2.0 includes the headless CLI. The `dsh` prefix will be removed after a second real Host Adapter is implemented and accepted, with a new npm package at that point; see the [roadmap](docs/ROADMAP.md).
 
@@ -172,6 +198,7 @@ Core and the DSH Adapter are being separated: DSH keeps loading the same npm pac
 | Tool | Purpose |
 |---|---|
 | `iris_draw_image` | Generate images from a prompt |
+| `iris_edit_image` | Edit a source Artifact into a new image with a chat image model, preserving provenance |
 | `iris_generate_video` | Text-to-video, image-to-video, or S2V digital-human video |
 | `iris_speak_text` | Synthesize speech from text |
 | `iris_transcribe_audio` | Transcribe audio to text |
@@ -198,6 +225,12 @@ Core and the DSH Adapter are being separated: DSH keeps loading the same npm pac
 
 ## File inputs
 
+Look, locate and OCR accept a local path, session attachment or Core image `artifact_id`; summaries can reuse `frame_artifact_ids`. Artifact inputs are read-only and checked against their MIME type and content hash. PNG/JPEG/WebP inputs need no manual JPEG conversion. See [vision CLI](docs/VISION_CLI.md).
+
+Look, OCR chunks, locate and chat editing prepare sending copies using account/model budgets, with an 8 MiB default. Core originals, downloaded dimensions and hashes stay intact. OCR reports resizing and small-text risk; locate returns source-pixel coordinates. See [input budgets](docs/CLI_MANAGEMENT.md#看图输入预算).
+
+Chat editing uses a source Artifact ID and saves a linked new image; it requires a model configured for chat image generation. See [Artifact editing](docs/CLI_MANAGEMENT.md#artifact-聊天改图) and [workbench management](docs/WORKBENCH_ARTIFACTS.md) for filtering, selection, downloads and recovery.
+
 Iris accepts three file sources, in the recommended order:
 
 1. **Browser upload** — best for local files and cross-environment access; 64 MB per file.
@@ -208,6 +241,8 @@ Uploads are stored under `$DSH_HOME/iris/v1/uploads/` and kept for 7 days by def
 
 ## Conversation prompt optimization
 
+The 0.2.1 adds per-operation rules, assembly without a model call and editable comparisons. Rules are not persisted and no standalone prompt CLI is added. See the [prompt optimizer guide](docs/PROMPT_OPTIMIZER.md).
+
 Iris adds a borderless, text-free “🫧” control directly to the DSH composer, so the workbench does not need to be open. It opens a translucent glass panel with background blur and soft depth; on narrow screens and Android browsers it becomes a safe-area-aware, internally scrollable bottom sheet to prevent overlap and overflow. It reads only the current unsent plain-text draft and offers general, image, video, and start-to-end-frame video targets. The result is previewed first and is written back only after confirmation; Iris never sends it automatically. Drafts containing structured `@` or `/` references are left untouched for now so their identities are not lost.
 
 By default, the optimizer uses the model selected for the current session and falls back to DSH's default model when the session has none. The request carries no chat history, tools, attachments, or workspace content—only the current draft and target template. To prevent reasoning tokens from exhausting the generation budget before visible text is complete, `generation.reasoningEffort` defaults to `off-if-supported`: reasoning is disabled only when DSH model metadata explicitly advertises such an effort; otherwise the provider default is used, and the session High/Low setting is not inherited. JSON may select `provider-default`, `inherit`, or an exact effort ID advertised by the model. For predictable cost and latency, use a `fixed` route with a lightweight non-reasoning model. You can also export `prompt-optimizer.json`, change `route.mode` to `fixed`, name another `provider` and `model` already registered in DSH, and import it again. “Reset to defaults” restores Iris's built-in prompt, target templates, session-model routing, and generation settings. The composer control can be disabled independently and re-enabled from the Iris workbench; disabling it does not stop the workbench, agent tools, or task runtime. An optimization call may incur charges from the selected text model.
@@ -226,9 +261,9 @@ Transcription is a separate `transcribe` capability and does not consume the TTS
 
 ## Capability health and model verification
 
-The workbench and main bubble expose four persistent health states: gray means unconfigured; blue means configured but unverified, or that success evidence is older than seven days; green means the exact provider × model × capability recently passed an explicit probe or real task; muted red is reserved for explicit 401/403 or authentication/permission failures. Text and evidence time accompany color, and critical provider configuration changes invalidate old evidence.
+The workbench and main bubble show gray for unconfigured, blue for unverified, green for success within seven days, and muted red for authentication or permission failures. The 0.2.1 also shows amber for temporary 429 cooldown and bright red for confirmed free quota or budget exhaustion, with a reason and recovery condition.
 
-Iris performs no background probes. Rate limits, network errors, 5xx responses, content-safety failures, cancellation, and unknown acceptance never overwrite a recent green state with red, trigger a hidden retry, or create hidden cost. Vision, image, and TTS can be probed per model; video and transcription require real user tasks. Host Doctor checks only DSH/Iris loading and host ports—it does not validate providers or models. See [Provider and capability health](docs/PROVIDER_HEALTH.md) for the state and failover contract.
+Iris performs no background probes. Temporary 429 responses use `Retry-After`, or a 60-second default cooldown. Expiry restores candidate eligibility without a verification request. Confirmed free quota or budget exhaustion persists across restarts until an explicit model test succeeds; test buttons remain available. Vision, image, and TTS have built-in test samples; video and transcription tests require real input through the CLI. Network errors, 5xx responses, content-safety failures, cancellation, and unknown acceptance do not overwrite recent success evidence. Host Doctor only checks loading and host ports. See [Provider and capability health](docs/PROVIDER_HEALTH.md).
 
 ## Offline diagnostics
 
@@ -241,7 +276,7 @@ npx @mokuyoaxis/dsh-iris doctor --json
 
 The installed binary is `dsh-iris`. Exit code `0` is healthy, `1` means warnings, and `2` means hard errors. Offline Doctor checks Node.js, sharp, ffmpeg/ffprobe, a real but cleaned-up storage write probe, configuration, models/assignments, task semantics, temporary files, and orphaned or missing artifacts.
 
-A running DSH instance also provides a “Host diagnostics” card in the Iris workbench and exposes the authenticated `/iris/api/doctor` JSON. It checks the DSH version, plugin, 14 tools, two Skills, four route groups, Browser/attachment/model capabilities, client version, and four UI Slots. It reads only safe snapshots and registration evidence; it never calls Browser, models, or providers. See [Host Doctor](docs/HOST_DOCTOR.md).
+A running DSH instance also provides a “Host diagnostics” card in the Iris workbench and exposes the authenticated `/iris/api/doctor` JSON. It checks the DSH version, plugin, current tools, two Skills, four route groups, Browser/attachment/model capabilities, client version, and four UI Slots. It reads only safe snapshots and registration evidence; it never calls Browser, models, or providers. See [Host Doctor](docs/HOST_DOCTOR.md).
 
 ## Composed workflow example
 
@@ -259,18 +294,19 @@ Runtime data lives under `$DSH_HOME/iris/v1/` by default:
 |---|---|
 | `providers.json` | Providers, capability assignments, and redacted health evidence; file mode 0600 |
 | `prompt-optimizer.json` | Imported optimizer prompt, target templates, model route, and generation settings; file mode 0600 |
-| `tasks.json` | Task metadata and attachment indexes; up to 500 records |
-| `artifacts.json` | Minimal work-library index and random access tokens; no prompt, provider, or task relationship |
-| `outputs/` | Generated and processed media |
+| `core-v0/` | New tasks, attempts, Artifact objects, manifests and recoverable quarantine transactions |
+| `tasks.json` | Legacy task metadata and attachment indexes; up to 500 records |
+| `artifacts.json` | Legacy work-library index and random access tokens; no prompt, provider, or task relationship |
+| `outputs/` | Legacy generated and processed media |
 | `uploads/` | Temporary copies of browser uploads |
 
 On first load, 0.1.1 tightens POSIX permissions across an existing `$DSH_HOME/iris/v1/` tree without modifying file contents or following symlinks. Large media downloads stream to a private temporary file and are moved into place atomically, instead of loading a whole video into memory.
 
 Asynchronous tasks are polled in the background. After a plugin restart, Iris can re-adopt tasks that are still running remotely. Cancellation signals propagate through local waits and polling; whether the remote computation itself can be cancelled depends on the provider's API.
 
-The work library has its own lifecycle: clearing terminal task history does not delete works, and older media can be recovered by re-indexing `outputs/`. Deleting one work or clearing the library deletes the actual files behind a separate confirmation. See [Work library v0](docs/ARTIFACT_LIBRARY.md) (Chinese). Favorites, tags, and search remain future work after the full Artifact Manifest.
+The work library has its own lifecycle: clearing terminal task history does not delete works, and older media can be recovered by re-indexing `outputs/`. Legacy deletion removes actual files with separate confirmation; see [Work library v0](docs/ARTIFACT_LIBRARY.md). Core deletion uses preview and recoverable quarantine; see [workbench management](docs/WORKBENCH_ARTIFACTS.md). Favorites, tags and search remain future work.
 
-Audio and video are served through Iris media links that carry random capability tokens. Images are, wherever possible, also saved as DSH durable attachments so they stay usable in the conversation.
+Legacy media links carry random capability tokens. Core media uses random Artifact IDs and host/browser origin guards. Images are, wherever possible, also saved as DSH durable attachments so they stay usable in the conversation.
 
 ## Security notes
 
@@ -280,13 +316,13 @@ Audio and video are served through Iris media links that carry random capability
 - `IRIS_TRUSTED_HOSTS` is not an authentication mechanism. When exposing DSH to the public internet or an untrusted network, configure authentication and HTTPS at the reverse proxy or host layer.
 - Paid model probes run one capability at a time and always confirm before a real provider call; video and transcription never submit empty-sample paid probes automatically.
 - HTML screenshots render inside a sandboxed page without same-origin privileges; scripts and external network access are disabled by default.
-- Media links use random capability tokens, and file paths are resolved only from task records or the minimal work-library index.
+- Legacy media links use random capability tokens; Core media reads verify Artifact content hashes. A host allowlist does not replace user authentication.
 - Iris provides no account system of its own; multi-user isolation and access control are the responsibility of the DeepSeek Harness deployment.
 
 ## Known limitations
 
 - `sharp` bundles native components; glibc Linux, Windows, and macOS are the primary targets. Non-standard environments such as bare Termux may need extra work.
-- Video frame extraction and video summaries require system-installed `ffmpeg` and `ffprobe`.
+- Video-file frame extraction and summaries require system-installed `ffmpeg` and `ffprobe`; summaries of existing Core frames need neither.
 - HTML screenshots load no remote scripts, fonts, or images; inline the resources you need first.
 - Under WSL, containers, and remote deployments, browser paths usually cannot be handed to the host directly — prefer uploading files.
 - Provider model lists are candidate sets only; whether a model truly supports a capability is settled by real calls.
@@ -300,7 +336,7 @@ When the plugin is enabled, it automatically registers the two bundled skills th
 | [`iris-verify-ui`](.dsh/skills/iris-verify-ui/SKILL.md) | Combine screenshots, semantic inspection, element grounding, cropping, and pixel comparison into evidence-based UI acceptance |
 | [`iris-compose-media`](.dsh/skills/iris-compose-media/SKILL.md) | Chain two or more Iris tools into media workflows: inspect-then-draw, image-to-video, video summary with narration, S2V, and more |
 
-From 0.1.2, as long as the host provides the DSH skill registry, regular npm installs can discover and load both skills from any project directory — no need to clone this repository or configure a skill search path. When the project directory contains same-name skills, DSH's native precedence keeps using the project versions; if the skill registry is unavailable, the 14 Iris tools still load on their own.
+From 0.1.2, as long as the host provides the DSH skill registry, regular npm installs can discover and load both skills from any project directory — no need to clone this repository or configure a skill search path. When the project directory contains same-name skills, DSH's native precedence keeps using the project versions; if the skill registry is unavailable, the Iris tools still load on their own.
 
 For deterministic selection, invoke either skill with DSH's `/name` form:
 
@@ -322,7 +358,7 @@ Tests cover config merging, model identity, task lifecycle, generation actions,
 
 The test scheduler runs on Node.js, launching one process per file and stopping at the first failure — no Bash involved. Temporary directories use system APIs and are cleaned up on exit. GitHub Actions defines a Linux/Windows × Node.js 22.0.0/latest 22.x matrix, with repeated natural-exit checks on the minimum version, and a pre-release hook re-runs the full suite. DSH host smoke tests on native Windows/WSL are still pending real-machine verification.
 
-Releases are triggered by `v*` tags through `.github/workflows/release.yml`: the full test suite runs first, then the tarball is packaged, a GitHub Release is created with the workflow's built-in `GITHUB_TOKEN` (tarball attached; release notes taken from the matching CHANGELOG section), and npm publish happens when an `NPM_TOKEN` secret is configured. No local GitHub credentials are needed.
+Releases are triggered by `v*` tags through `.github/workflows/release.yml`: the full test suite runs first, then the tarball is packaged, a GitHub Release is created with the workflow's built-in `GITHUB_TOKEN` (tarball attached; release notes taken first from `docs/releases/<version>.md`, otherwise from the matching CHANGELOG section), and npm publish happens when an `NPM_TOKEN` secret is configured. No local GitHub credentials are needed.
 
 ## Documentation