@mokuyoaxis/dsh-iris 0.2.0 → 0.2.2

package/docs/ROADMAP.md

@@ -1,34 +1,51 @@
 # 路线图
 
-Iris 正从 DSH 媒体插件演进为可独立运行、可接入不同 Agent 宿主的媒体生产核心。本文只列当前状态与后续方向；历史版本的具体改动见[变更记录](../CHANGELOG.md)，内部实现顺序不在公开路线图中展开。
+Iris 正从 DSH 媒体插件演进为可独立运行、可接入不同 Agent 宿主的媒体生产核心。本文列当前状态与后续方向；版本变化见 [变更记录](../CHANGELOG.md)。
 
 ## 当前状态
 
-当前版本为 `0.2.0`，保留包名 `@mokuyoaxis/dsh-iris`，同时提供 DeepSeek Harness 插件和 Headless CLI。它提供：
+当前版本为 **Iris 0.2.2**。包名保持 `@mokuyoaxis/dsh-iris`，同时提供 DSH 插件与无 DSH 的 Headless CLI。本版变化见 [0.2.2 发布说明](releases/0.2.2.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.2采用明确功能能力：移除裸 DashScope 和名称自动赋能，保留功能入口、按功能分配的有序模型池及安全 failover。工作台提供明确功能标签设置；已有配置不自动迁移。Music 接入与相关网关排查暂缓，恢复前需取得可验证的真实音频。
+
+0.2.2 的 Core 可靠性已补齐 writer 意图与显式恢复证据，非图片交付复用文件接收和分块哈希；普通 writer 不自动抢占，未知/损坏现场继续拒绝。实现及边界见 [Core Runtime](CORE_RUNTIME_CONTRACT.md) 与 [Provider Adapter](PROVIDER_ADAPTER_CONTRACT.md)。
+
+0.2.2 的提示词一般功能已提供折叠五用途、原文/顺序保持的忠实整理、明确改写与单独获取/采纳的建议，保留自定义 v1 配置和旧 API。特殊功能待定义，独立提示词 CLI 和英文默认指令候选未接入；详见 [提示词优化系统](PROMPT_OPTIMIZER.md)。
+
+0.2.2 的生图尺寸归一、本地未受理校验及网络/正文诊断已实现，受理未知仍停止自动重提；不以本地代码保证公网线路稳定。见 [错误与取消传播](PROVIDER_ADAPTER_CONTRACT.md#错误与取消传播)。
+
+0.2.1 的发布检查覆盖完整测试、lint、实际 tarball、敏感信息、仓库外安装与跨平台 CI。服务层与包安装验收之外，近期优先补齐真实浏览器/移动端及异步重启使用证据。
+
+工作台两轮功能已实现；第三轮仍需补浏览器/移动端的筛选、分页、跨页选择、识别、改图、下载及回收区使用验收，以及真实异步任务重启后的 CLI 接管。已有真实图片生成、按 ID 看图和聊天改图链路验证，完整会话与重启范围继续以 [验证说明](DSH_CORE_MIGRATION.md#验证证据与限制) 为准。上述变化纳入 0.2.2；完整工作台与重启范围的剩余验收仍保留。
+
+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 +59,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.2 安全边界。安全目标是避免凭据泄露、路径越权、跨站写入和因错误重试造成重复计费；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.2 的媒体、聊天改图和维护入口共享 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 消费与编辑关系；两种存储保持独立。
 - 不用更多自动重试换取表面成功率。

package/docs/VISION_CLI.md

@@ -0,0 +1,132 @@
+# 独立视觉 CLI
+
+状态：**Iris 0.2.2**。安装 `npm install @mokuyoaxis/dsh-iris@0.2.2` 后运行 `npx dsh-iris ...`，或从源码运行 `node bin/dsh-iris.js ...`。需要 Node.js ≥ 22、已有依赖 Sharp；从视频文件抽帧还需要 PATH 中的 ffmpeg、ffprobe，复用既有 Core 帧不需要。
+
+## 四个命令
+
+所有命令必须显式提供私有配置文件，媒体文件使用绝对路径；看图/定位/OCR 也可指定 Core 图片 ID，摘要可指定 Core 帧 ID，并提供数据根。下面假设配置位于 `/absolute/path/providers.json`，图片和视频路径也需替换：
+
+```bash
+dsh-iris vision look \
+  --provider-config /absolute/path/providers.json \
+  --input '{"image_path":"/absolute/path/image.png","question":"画面中有什么？"}'
+
+dsh-iris vision locate \
+  --provider-config /absolute/path/providers.json \
+  --model-ref 'aliyun::qwen3-vl-flash' \
+  --input '{"image_path":"/absolute/path/image.png","target":"红色方块"}'
+
+dsh-iris vision ocr \
+  --provider-config /absolute/path/providers.json \
+  --input '{"image_path":"/absolute/path/screenshot.png","chunk_height":1200,"overlap":120}' \
+  --format text --output ./recognized.txt
+
+dsh-iris vision summarize \
+  --provider-config /absolute/path/providers.json \
+  --input '{"video_path":"/absolute/path/clip.mp4","max_frames":8,"question":"总结视频内容"}' \
+  --output ./summary.json --sheet-output ./contact-sheet.png
+```
+
+`look` 的 `question` 可省略，默认用中文描述画面。`locate` 要求非空 `target`，返回原图像素 `bbox` 或 `{found:false}`，同时提供原图尺寸和 `input` 图片事实。模型被明确要求使用 0–1000 归一化坐标；返回结果已换算、处理 EXIF 方向并向外取整，可直接用于原图裁剪。定位结果取决于模型判断。
+
+`ocr` 默认块高 1200、重叠 120、最大宽度 2048，可用 `chunk_height`、`overlap`、`max_dimension`、`max_invocations` 调整；沿用 [OCR](OCR_MODEL.md) 的限制，最多 32 块和 64 次生成。各切片再应用实际模型的 `visionInput`。返回 `complete` / `partial` / `failed`、成功/失败/未处理块数、每块状态与 `fullText`，保留原段号；成功块的 `input.source/sent` 记录切片与实际发送图的宽高、字节数和 MIME。文本格式会提示缩小导致的细字风险；失败块正文不会混入识别全文。
+
+`summarize` 默认均匀取 8 帧，`max_frames` 最多 20；`target_width` 默认 640，按源图比例缩放。每次视觉候选调用只发送一张带时间戳的 PNG 拼图，`--sheet-output` 保存的就是该图片。JSON 仅包含拼图尺寸、MIME 和 SHA-256，不包含图片 base64 或本机路径。
+
+## 直接使用 Core 图片
+
+`look`、`locate`、`ocr` 均接受 `artifact_id`，与 `image_path` 二选一。ID 可来自生成图片、裁剪、HTML 截图、视频抽帧等 Core 产物；用 `artifact list --data-root ... --media-type image/png` 查找，或从已有命令结果取得真实 ID。
+
+```bash
+dsh-iris vision look \
+  --provider-config /absolute/path/providers.json \
+  --data-root /absolute/path/iris-core \
+  --input '{"artifact_id":"artifact_0123456789abcdef01234567","question":"画面中有什么？"}'
+
+dsh-iris vision locate \
+  --provider-config /absolute/path/providers.json \
+  --data-root /absolute/path/iris-core \
+  --input '{"artifact_id":"artifact_0123456789abcdef01234567","target":"发送按钮"}'
+
+dsh-iris vision ocr \
+  --provider-config /absolute/path/providers.json \
+  --data-root /absolute/path/iris-core \
+  --input '{"artifact_id":"artifact_0123456789abcdef01234567","chunk_height":1200,"overlap":120}' \
+  --format text --output ./recognized.txt
+```
+
+示例 ID 需替换成实际 ID。读取核验 Core 内容哈希，使用 Manifest 的 MIME 和图片原字节，支持最多 20 MiB 的 PNG/JPEG/WebP/GIF，不限制图片的 `kind`。看图、OCR 每块和定位按实际账号/模型准备发送副本，默认 8 MiB；超预算 PNG/JPEG/WebP 等比缩小并保留格式，原图及下载字节不变。可配置大小与最长边，见 [视觉输入预算](CLI_MANAGEMENT.md#看图输入预算)。定位返回原像素坐标；OCR 保留单帧、像素/分块上限与部分完成语义。JSON 结果（含 OCR 部分结果）附 `artifactId`。
+
+这三个命令只以 reader 打开显式数据根，不需要原图片文件、不导出临时图片、不创建 Task/Artifact，也不取得 writer 租约。缺失、损坏、非图片或超限 Artifact 在调用模型前拒绝；缺失的数据根不会被创建。文件输入用法不变。
+
+## 复用已保存的 Core 帧
+
+先用 `media frames --data-root ... --input ...` 抽帧，从结果的 `artifacts[].id` 取 ID；也可用 `artifact list --data-root ... --kind video-frame` 查找。将同一视频中要分析的帧直接传给摘要：
+
+```bash
+dsh-iris vision summarize \
+  --provider-config /absolute/path/providers.json \
+  --data-root /absolute/path/iris-core \
+  --input '{"frame_artifact_ids":["artifact_0123456789abcdef01234567","artifact_89abcdef0123456789abcdef"],"question":"总结这些片段"}' \
+  --output ./summary.json --sheet-output ./contact-sheet.png
+```
+
+示例 ID 需替换成实际 ID。`video_path` 与 `frame_artifact_ids` 必须二选一；帧 ID 数组为 1–20 个不同的 `video-frame` Artifact，读取时核对其内容哈希、帧序号、时间戳和尺寸，按 `atSec`、`frameIndex` 排序。可以只选择部分帧，结果 `frames[]` 保留实际使用的 `artifactId`、原 `frameIndex`、`atSec`、尺寸；`meta.source` 为 `core-artifacts`，`startSec` / `endSec` 是所选帧覆盖的时间范围，不代表完整视频时长。
+
+此模式只读 Core，不要求原视频或 ffmpeg，不导出临时副本、不新增 Task/Artifact；其他进程持有 writer 租约时仍可读取。`max_frames`、`target_width` 只用于视频文件模式，已有帧需直接选择 ID。已有帧不自动提取音轨，可用 `transcribe_text` 提供已有文字；`transcribe:true` 需要视频文件模式。
+
+## 配置和模型选择
+
+配置沿用 Iris Provider 文件，不执行配置迁移或模型发现。文件必须为普通文件，POSIX 权限限制为当前用户可读写（例如 `chmod 600 providers.json`）。可以直接只读使用已有 Iris 配置；不会推断 DSH_HOME、HOME 或当前目录。
+
+最小结构如下，`apiKey` 由你在私有文件中设置，不放在命令参数中：
+
+```json
+{
+  "providers": [{
+    "id": "aliyun",
+    "type": "openai",
+    "enabled": true,
+    "baseUrl": "https://dashscope.aliyuncs.com/compatible-mode/v1",
+    "apiKey": "你的密钥",
+    "models": [{"id": "qwen3-vl-flash", "capabilities": ["vision"]}]
+  }],
+  "assignments": {"vision": ["aliyun::qwen3-vl-flash"]}
+}
+```
+
+省略 `--model-ref` 时按 `assignments.vision` 排序，再以配置模型池补齐。只有本地不可用、明确拒绝或正常空正文才允许下一候选；截断、未知终态、收到正文后的失败、取消和超时停止调用。显式 `--model-ref providerId::modelId` 严格只绑定该账号与模型，失败不会替换；新视觉命令不接受裸模型名。模型需启用并声明 `vision` 能力，未配置时直接失败。当前自持视觉端口支持 OpenAI-compatible Chat Completions SSE，不追加 DSH 宿主候选。
+
+成功 JSON 携带实际 `modelRef`、`selectionReason`（`explicit` / `assignment` / `pool`）、模型身份、正常终态及可用的 usage。OCR 的实际选择保留在每个成功块上。配置凭据、端点和原始错误响应不会出现在诊断中；模型回答和 OCR 正文是用户内容。
+
+## 输出、预算与退出码
+
+默认 `--format json`，`--format text` 输出看图/摘要正文、定位 bbox JSON 或带完成状态的 OCR 文本。stdout 始终返回相同格式，`--output` 同时保存该结果。输出文件允许相对路径，父目录必须存在；已有文件不会覆盖。仅摘要支持 `--sheet-output`。两份文件逐个排他写入，不提供多文件事务；若第二份保存失败，第一份可能已经保存。
+
+默认一次操作共用 120 秒，`--timeout-ms 1..120000` 可缩短。预算覆盖文件读取、图像准备、抽帧、可选转写等待与全部视觉候选。Sharp 原生操作和同步 ffprobe 无法强制中断，取消后不会继续消费结果生成；可取消的网络请求与 ffmpeg 会收到信号。每次视觉正文上限 6000 字、输入图片最多 20 MiB，沿用共享端口的正常终态检查。
+
+退出码：成功为 `0`；模型、配置、输入错误或 OCR 部分完成/失败为 `1`；命令参数/输出路径错误为 `2`；SIGINT / SIGTERM 为 `130` / `143`。OCR 部分完成仍输出结构化结果，脚本应同时检查退出码与 `status`。
+
+## 摘要中的音轨
+
+默认只分析画面，不自动转写。已有转写可用 `transcribe_text` 显式提供，不产生任务：
+
+```bash
+dsh-iris vision summarize \
+  --provider-config /absolute/path/providers.json \
+  --input '{"video_path":"/absolute/path/clip.mp4","transcribe_text":"这里是已获得的转写文字"}'
+```
+
+主动上传并转写音轨需设置 `transcribe:true` 和显式数据根；视觉与转写模型分别选择：
+
+```bash
+dsh-iris vision summarize \
+  --provider-config /absolute/path/providers.json \
+  --data-root /absolute/path/iris-core \
+  --model-ref 'aliyun::qwen3-vl-flash' \
+  --input '{"video_path":"/absolute/path/clip.mp4","transcribe":true,"transcribe_model_ref":"aliyun::qwen-audio-3.0-asr-flash-filetrans"}'
+```
+
+配置需声明 `transcribe` 模型，并使用既有上传型转写协议（当前 DashScope）。省略 `transcribe_model_ref` 时沿用转写 assignment/模型池，显式指定时只使用该项；不能同时提供 `transcribe_text`。本次命令观察已受理的同一 Core Task，读取成功的文本 Artifact 后摘要；普通转写失败则返回画面摘要并将 `transcription.status` 标为 `failed`。无音轨标为 `no_audio`；取消/超时直接终止摘要，已经提交的转写任务保留事实，可按 [Headless CLI](HEADLESS_CLI.md) 的任务命令继续检查、观察或重新取回，不会自动重提。
+
+文件输入的纯视觉命令不要求数据根，不创建 Core Runtime、Task 或 Artifact；使用图片/帧 Artifact ID 时只使用显式数据根的 reader，主动音轨转写时才持有 writer 租约。独立提示词优化入口不属于本次交付。

package/docs/VISION_MODEL.md

@@ -0,0 +1,51 @@
+# 单图视觉调用
+
+状态：**Iris 0.2.2**。本文说明共享单图视觉调用。
+
+## 使用与变化
+
+Agent 的 `iris_look_at_image` / `iris_relook_attachment`、工作台的看图/重看，以及用户显式确认的视觉实测，改为消费共享 VisionModel Port。不自动生成媒体任务或保存 Core 产物。
+
+`iris_look_at_image` 与看图动作现可用 `artifact_id` 代替 `image_path`，直接读取当前 DSH profile 的 Core 图片，二者必须二选一。图片的 MIME、原字节和内容哈希由共享读取器核对，不要求原文件或临时导出、不写入 Core；生成图片、HTML 截图、裁剪、视频帧均可使用。自持模型成功时无需为 Core 输入另存 DSH 附件；DSH 候选仍通过既有附件桥接。工具文字保留 Core ID，动作 JSON 带 `artifactId`。工作台原表单继续输入文件路径，动作 API 可直接传 ID。独立 CLI 的同一用法见 [视觉 CLI](VISION_CLI.md)。
+
+Iris 按已配置的视觉模型顺序选择自持后端，最后考虑 DSH 默认视觉模型。DSH 必须明确提供 Provider、模型及图片输入能力；默认文本模型、未知元数据和身份漂移在生成前拒绝。自持成功时不查询 DSH 元数据或为回退额外保存附件。
+
+只有明确认证/权限拒绝、速率/额度拒绝、正常完成但正文为空，以及本地能力不可用，才允许进入下一个候选。已收到部分正文、截断、工具调用、内容阻断、网络/协议错误、取消或超时都会停止操作。正常空结果后的切换可能已经产生上一模型的费用。
+
+SSE `[DONE]`、EOF 或已经出现文字不代表完成。自持 Chat Completions 必须提供正常的 `finish_reason: stop`；DSH 必须提供可验证的正常 `finish`。正文超限和 token 截断明确失败，不再截取前若干字返回成功。DSH 的 `block-end` 替换同一块的 delta，思考正文不进入回答。
+
+## 预算与图片
+
+| 限制 | 默认值 |
+|---|---|
+| 整体时间 | 120 秒，覆盖文件/Artifact/附件读取、元数据、桥接及所有候选 |
+| 输入文字 | 32 KiB UTF-8 |
+| 原图片读取 | 20 MiB，PNG/JPEG/WebP/GIF 字节；本地看图工具沿用 PNG/JPEG/WebP 格式限制 |
+| 自持看图、定位与 OCR 每块发送副本 | 默认 8 MiB，可按账号/模型覆盖；最长边限制可选 |
+| 输出正文 | 6,000 个 UTF-16 code units，超限失败 |
+| 生成次数 | 最多为本次有限候选表的长度，每个候选只调用一次；不可用候选不计生成次数 |
+| 显式视觉实测 | 默认 15 秒，只调用指定的一个自持模型，不使用 DSH 回退 |
+
+视觉能力探针使用 128×128 纯红 PNG。旧的 1×1 图片会被部分模型的最小尺寸检查拒绝，不能据此判断模型不支持视觉。
+
+图片以字节与 MIME 进入共享层，Core 读取先核验原图哈希。看图、重看和生成后自述会在发送前按实际账号 × 模型准备副本：小图原字节透传，超预算 PNG/JPEG/WebP 从原图等比缩小，保留 MIME 并应用 EXIF 方向，不写入 Core、不替换原图。动画图片需要缩放时明确拒绝，避免静默只取第一帧。原图下载与工作台展示继续使用原 Artifact。
+
+Provider 和 `models[]` 均可选 `visionInput: {maxBytes, maxDimension}`；正整数分别表示编码图片字节上限和最长边像素。优先级为模型逐字段覆盖账号，再继承默认 8 MiB。`null` 恢复继承，不迁移旧配置，也不自动探测供应商上限。8 MiB 是客户端默认发送预算，不表示所有模型都接受该大小。CLI 和工作台设置见 [配置管理](CLI_MANAGEMENT.md#看图输入预算)。
+
+DSH rc.2 会压缩宿主附件。看图、OCR 和定位允许这种宿主规范化，并检查引用哈希、实际 MIME、字节数及原始/归一化尺寸；随后仍使用同次 `saveImage()` 返回的引用。损坏或不匹配的引用会在模型调用前拒绝。OCR 在切片后应用预算，记录真正输入的尺寸；定位明确约定模型坐标域，处理缩放和 EXIF 方向后返回原图像素。详见 [OCR](OCR_MODEL.md) 和 [定位](COMPOSITE_VISION.md)。默认宿主候选应用客户端 8 MiB 预算，宿主自身仍可能进一步缩小图片。
+
+大小拒绝使用 `IRIS_MODEL_IMAGE_TOO_LARGE`；已知上限时显示实际字节数及上限。上游明确的 400 图片大小消息仅提取数值，不展示原始供应商正文；其他 400 是输入拒绝，429 仍按限流/额度分类。一次调用不会因大小拒绝自动压缩重发或切换模型。
+
+预先取消时不读取图片、不做桥接、不调用模型。在途取消/超时会向模型、读取及元数据传递 abort，并结束底层迭代。DSH rc.2 的 `saveImage()` 没有取消参数：本地等待仍有界，迟到保存可能留下宿主附件，之后不会启动生成。Host 附件属于宿主数据，不是 Core Artifact；不自动删除它们。取消也不证明远端执行或计费已停止。
+
+## 开发与验证边界
+
+`vision-core.js` 只消费显式请求与 Model Ports；`vision-model-routing.js` 拥有配置选型、文件解析和结果/健康投影；HTTP 与 DSH 适配器拥有协议和图片桥接。安全错误只包含稳定代码、调用事实和受控状态，不能包含 Prompt、图片、Key、端点或原始异常。
+
+两类视觉协议复用 Model Port conformance；HTTP 额外检查 SSE 分帧、UTF-8、终态及正文上限，DSH 额外检查附件字节、元数据与迟到桥接。实际安装的 rc.2 Runtime/Attachments 另用离线模型源验收；包外验收使用无 DSH/Cordis 的安装副本。
+
+2026-10-02 使用现有 DashScope `qwen3-vl-flash` 做了隔离实测：HTTP Port、DSH 原生 PiAiAdapter 与实际 Runtime、Agent 看图/重看、工作台看图/重看、截断拒绝和收到正文后的取消均通过。DSH 的通用 OpenAI 兼容路由在本次测试中需显式设置 `compat.maxTokensField: max_tokens`，才能让 DashScope 执行输出 token 上限；这是测试路由的宿主配置，没有修改个人 profile。
+
+[长图 OCR](OCR_MODEL.md)、[定位、拼图摘要与自述](COMPOSITE_VISION.md) 均已消费共享端口与整次预算；各自另验分块、bbox 解析、一张拼图一次生成及可选 Core 转写。legacy `vision.js` / Host `visionModel.analyze()` 兼容实现仍保留，现有业务入口不再调用。Model Port 的迁移切片本身不新增公开 SDK export 或生产依赖；0.2.1 提供 [视觉 CLI](VISION_CLI.md) 和可选 `visionInput`。复杂图像质量与 Android 浏览器仍需独立验证。
+
+契约与迁移说明见 [Model Port](MODEL_PORT_CONTRACT.md) 和 [DSH → Core](DSH_CORE_MIGRATION.md)。

package/docs/WORKBENCH_ARTIFACTS.md

@@ -0,0 +1,67 @@
+# 工作台作品浏览、识别与管理
+
+状态：**Iris 0.2.2**。
+
+Iris 工作台的作品库统一展示 Core 和旧版作品，包括图片、视频、音频和文本。默认按时间倒序排列，每页 24 个；使用上一页、下一页浏览全部作品。媒体类型、作品来源和产物类型可组合筛选，匹配总数与 Core/旧版计数均按当前筛选计算。切换筛选回到第一页，刷新保留页码和筛选；尾页因作品数量减少而超界时，回到最后一页。
+
+Core 的原始输入 `host-input` 不出现在作品库。不可读取的 Core 条目局部跳过并提示；Core 整体暂时不可用时仍可浏览旧版作品，此时计数只含可读取来源。图片提供预览，视频、音频提供播放器，文本可以打开原文件。
+
+## 从图片卡看图与 OCR
+
+Core 图片卡的“看图”“OCR”按钮直接读取原 Artifact。点击即按默认配置运行，不需要复制路径、导出图片或转换格式。
+
+- 看图默认详细描述，可在“更多选项”填写问题并重新识别。
+- OCR 默认块高 1200、重叠 120 像素，可在“更多选项”修改；结果明确标记完成、部分完成或失败。
+- 结果面板保留图片预览，正文可复制或下载为浏览器本地 `.txt` 文件。
+- “取消识别”、关闭结果或切换分析会取消在途请求；迟到响应不会覆盖后续分析。
+- 关闭结果保留作品页码和筛选，不自动写回对话或启动生成任务。
+
+支持 Core PNG/JPEG/WebP/GIF。模型沿用当前 Iris 视觉能力分配及既有候选规则；主动点击识别会请求模型，浏览列表不会。旧版图片保留打开和既有工具的文件路径输入；旧版作品 ID 与 Core ID 不混用。
+
+看图、OCR 每块输入和定位按实际账号/模型准备发送副本，默认 8 MiB；大图保留 Core 原文件，只等比缩小发给模型的 PNG/JPEG/WebP。可在账号详情或模型行设置大小预算、最长边及恢复继承，见 [视觉输入预算](CLI_MANAGEMENT.md#看图输入预算)。展示、详情和下载仍读取原图；OCR 保留切片规则，结果标明缩小时的细字风险；定位返回已换算的原图像素。更新插件后需重新加载 DSH 后端并刷新客户端。
+
+## 从图片卡改图
+
+Core 静态 PNG/JPEG/WebP 图片卡增加“改图”。填写修改指令，可显式选择支持聊天生图的模型，或按现有候选顺序选择。面板只读取模型配置，不自动实测；只列出 `openai-chat-images` 生图模型，冷却/额度耗尽项不可选择。
+
+点击“生成修改版”才调用模型，原图保留，修改版作为关联原图的新 Core 作品显示。成功后提供新 Artifact 链接、刷新作品库，保留筛选和页码；新作品可继续看图/OCR、编辑、下载和管理。来源最多 20 MiB；大图只处理发送副本，预算设置也可在聊天生图模型行编辑。
+
+“停止等待”、关闭面板或切换分析会中止在途等待，迟到响应不覆盖新面板。远端可能已受理，须在任务区查看结果，不会自动再次生成。编辑任务的手动重试要求重新输入修改指令并确认原图 ID；只支持一次带图请求，不保存聊天历史或提供蒙版。详见 [CLI 改图](CLI_MANAGEMENT.md#artifact-聊天改图)。
+
+## 查询与完整性
+
+工作台使用同源 `GET /iris/api/works`，参数为 `offset`、`limit`（默认 24，最多 60）、`media_type`（all/image/video/audio/text）、`source`（all/core/legacy）和 `kind`（all 或具体产物类型）。服务端先过滤、按时间及来源/ID 稳定排序，再统一分页，返回 `items/total/offset/limit/kinds/counts`；客户端不再拼接两个已经分页的结果。
+
+目录查询复用已提交的 Manifest 与派生 Index，只读取元数据和文件大小，不反复读取视频等媒体的完整字节、不重建索引或取得 Core writer 租约。打开媒体、看图/OCR、CLI inspect/list/export 保留原有完整内容哈希核验；目录里显示的哈希不表示本次浏览已经重新核验了全部文件内容。
+
+OCR 动作 JSON 附 `status/totalChunks/successfulChunks/failedChunks/skippedChunks`，便于界面表达完整度。识别正文不自动保存为 Core Artifact。
+
+## 选择、详情与批量下载
+
+勾选作品卡或点击“选择本页”，显式选择最多 200 项。翻页和刷新保留选择，本页重复项不会重复加入；切换筛选清空选择。超过上限的整页选择会被拒绝，不截断或隐式选择所有匹配作品。
+
+“复制选中 ID”每行一个 ID；旧版 ID 仍不能作为 Core Artifact 输入。“下载选中作品”把 Core 与旧版作品合为一个 ZIP，单次原文件合计最多 128 MiB。包内按 `core/<artifact_id>.<扩展名>` 和 `legacy/<作品ID>.<扩展名>` 命名，`works.json` 记录原文件名、来源、ID、MIME、字节数及 SHA-256，不携带本机路径、授权链接或提示词。所有选中项先预检，文件缺失或 Core 哈希失败时不返回部分 ZIP；保留原字节，不重编码图片或压缩媒体。可取消准备中的下载，大文件可继续使用 [CLI 批量导出](CLI_MANAGEMENT.md)。
+
+每张卡的“详情”显示基本字段；Core 另展示完整 SHA-256、关联和尺寸/时间等安全元数据，并实际核验内容哈希。旧版只核验文件存在，不声称具有历史内容哈希。
+
+## Core 回收区
+
+Core 卡的“移入回收区”或“删除选中 Core 作品”先打开只读删除预览，再明确确认执行。批量删除只接受全部为 Core 的选中项；旧版保留原有单项永久删除与清空语义。
+
+预览列出文件数、大小和引用阻塞。作品被任务记录引用时，可逐项明确勾选同时移除相关的已结束任务记录，再重新预览；未结束或结果未知任务不能勾选。任务仍关联未选中的其他作品、后续重试或外部产物关系时继续阻止删除，不自动级联或扩大选中集。
+
+确认后复用 `core.delete` Command，将文件放入同一 Core 根的可恢复隔离目录。执行时重新核对事实和引用，成功返回事务 ID。“Core 回收区”列出删除与 CLI 清理事务；可明确确认恢复准备中、已隔离或中断的事务，恢复核对原哈希且不覆盖原位置冲突。已恢复/已回退事务保留记录但不能再次恢复。
+
+隔离保留字节，不立即释放磁盘空间，也没有永久清空回收区入口。相同事务可使用 [CLI 管理命令](CLI_MANAGEMENT.md) 检查和恢复。这里只管理当前 DSH profile 的 Core，浏览/下载不请求模型。
+
+新增内部同源入口：`GET /iris/api/works/{core|legacy}/:id`、`POST /iris/api/works/download`（`items:[{source,id}]`）、`POST /iris/api/works/delete`（`artifact_ids/task_ids/confirm_delete`）、`GET /iris/api/works/transactions`、`POST /iris/api/works/restore`（`transaction_id/confirm_restore:true`）。删除省略确认时只返回预览；执行与恢复必须显式确认，均沿用既有 Host/浏览器来源守卫。
+
+## 验收状态与后续
+
+0.2.1 已实现作品管理与图片卡改图。2026-10-09 的实现快照通过 163 个测试文件、263 文件 lint 与已安装 DSH rc.2 服务 31 项隔离检查；新增真实网关改图已分别通过 DSH 工具与工作台入口交付新 Artifact，来源哈希保持不变。正式版本包另执行仓库外安装与跨平台 CI，证据范围见 [迁移验证说明](DSH_CORE_MIGRATION.md#验证证据与限制)。
+
+作品管理第二轮的历史快照（2026-10-08）通过 145 个测试文件、240 文件 lint、rc.2 服务 30 项，以及包外 100 命令和 140 文件候选包安装验证。程序化证据覆盖分页/过滤、客户端组件交互、ZIP 原字节与 CRC、删除引用保护、隔离/冲突恢复及工作台事务由独立 CLI 恢复。历史快照不代表最终 0.2.1 包已验收，详见 [迁移验证说明](DSH_CORE_MIGRATION.md#验证证据与限制)。
+
+真实浏览器/移动端排版、播放器、剪贴板和下载体验仍待逐项验收；用户已有绘图/识图/TTS 的试用反馈不等于新作品卡和回收区已全部目视通过。后续拟以第三轮补这些检查、真实附件链路和异步重启/CLI 接管，当前尚未执行。收藏、标签和搜索列在 [后续路线图](ROADMAP.md#后续功能方向)。
+
+更新本地插件后需重新加载 DSH 后端并刷新客户端，确保新路由和工具参数实际生效。

package/docs/file-access-across-environments.md

@@ -1,16 +1,19 @@
 # 文件访问与跨环境
 
-Iris 可以从浏览器上传、会话附件或宿主文件路径读取媒体。三种方式适合的场景不同；如果不确定，优先使用上传。
+Iris 0.2.1 可以从 Core Artifact ID、浏览器上传、会话附件或宿主文件路径读取媒体。已有 Core 作品优先使用 ID；外部文件按实际环境选择上传、附件或路径。
 
 ## 推荐顺序
 
-1. **浏览器上传**
+1. **Core Artifact ID**
+   看图、OCR、定位和聊天改图可直接使用已有图片/帧的 `artifact_id`，无需复制路径或先导出文件。按 ID 看图/OCR 会核验原始字节、MIME 和 SHA-256；PNG、JPEG、WebP 均可直接输入。CLI 需显式 `--data-root`，见 [视觉 CLI](VISION_CLI.md)。摘要还可复用 `frame_artifact_ids`。
+
+2. **浏览器上传**
    适合图片、音频和中小型视频。文件内容会传到运行 DeepSeek Harness 的宿主，因此不要求浏览器和宿主共享文件系统。
 
-2. **会话附件**
+3. **会话附件**
    适合复用当前会话中已有的图片或 Iris 生成的产物。附件引用比手动复制路径更稳定。
 
-3. **宿主路径**
+4. **宿主路径**
    适合宿主本地的大文件，可以避免再次复制。路径必须从宿主进程的视角填写，浏览器能看到并不代表宿主也能读取。
 
 ## 环境差异
@@ -21,7 +24,7 @@ Iris 可以从浏览器上传、会话附件或宿主文件路径读取媒体。
 | 原生 Windows | 上传、附件或宿主路径 | 使用 Windows 绝对路径，例如 `C:\Media\video.mp4` |
 | WSL | 优先上传或附件 | Windows 文件在 WSL 中通常映射为 `/mnt/c/...`，不能直接使用 Windows 路径 |
 | 容器或远程宿主 | 上传或附件 | 浏览器本地路径通常对远端进程不可见 |
-| Android + PRoot | 优先上传 | 共享存储是否可读取决于挂载方式和 Android 权限 |
+| Android + PRoot | 优先上传 | 共享存储是否可读取取决于挂载方式和 Android 权限 |
 
 浏览器文件选择器交给 Iris 的是文件内容，而不是一个可供宿主读取的本地路径。因此，它也适用于 WSL、远程部署和 Android 文件选择器返回 `content://` URI 的情况。
 

package/docs/releases/0.2.1.md

@@ -0,0 +1,56 @@
+## Iris Media for DSH 0.2.1
+
+Iris 0.2.1 completes the OpenAI-compatible image and vision workflow: image generation → Core Artifact → vision/OCR by ID → chat editing → new Artifact. Model discovery and capability classification, per-model protocols and shared artifact management bring this workflow to both the CLI and DSH workbench. The package remains `@mokuyoaxis/dsh-iris`.
+
+### Highlights
+
+- Choose an image protocol per model: native DashScope, OpenAI Images, gateway chat image generation, or Responses image generation. Models within one account can use different interfaces while keeping routing, health evidence and task bindings separate.
+- Preserve generated PNG, JPEG and WebP bytes with matching MIME types, extensions and content hashes. Fix base64 validation that could overflow the stack on large 4K image responses.
+- Edit an existing Core image by Artifact ID through `iris_edit_image`, a workbench image card, or CLI `run image` with `source_artifact_id`. Chat image models create a new Artifact with a `derived-from` relationship; the source stays intact and remains protected by task references.
+- Run `vision look / locate / ocr / summarize` without DSH, with explicit model selection and JSON, text or file output. Look, OCR and locate accept image Artifact IDs; summaries reuse existing frame Artifacts without the original video or another ffmpeg pass.
+- Set account and model input budgets. Look, OCR chunks, locate and chat editing prepare sending copies when necessary, using an 8 MiB default budget while preserving Core originals. OCR reports resized inputs; locate maps normalized coordinates and EXIF orientation back to original pixels.
+- Browse Core and legacy media together with pagination, filters, details and explicit selection across pages. Copy IDs, download a mixed-source ZIP, or preview and confirm recoverable Core deletion. Restore checks hashes and refuses conflicting destinations.
+- Complete CLI support for S2V video, restricted HTML screenshots, provider/model/configuration management, bounded task waiting, filtered queries, bulk export and recoverable Core maintenance.
+- Distinguish temporary 429 cooldown from confirmed quota or budget exhaustion. Amber cooldown expires into candidate eligibility without an automatic probe. Red exhaustion blocks the model across restarts until a manual model test succeeds.
+- Use shared Text/Vision Model Ports for prompt previews and visual operations, with complete-result checks, shared deadlines and cancellation. Composer previews also gain per-operation rules, assembly without a model call and editable comparisons.
+
+### Compatibility and upgrade
+
+- Node.js: `>=22.0.0`.
+- DSH plugin: **exactly `0.2.0-rc.2`**. No compatibility claim is added for other rc versions or DSH 0.2.0 stable.
+- Older supported DSH hosts should keep `@mokuyoaxis/dsh-iris@0.1.4`.
+- Headless CLI requires no DSH installation. Video-file frame extraction requires ffmpeg/ffprobe; HTML screenshots require an explicitly configured Chromium executable.
+- Configuration remains v1 with optional per-model settings. No production dependency or public SDK export is added.
+
+Install the pinned package on DSH rc.2:
+
+```bash
+dsh plugin --profile web add @mokuyoaxis/dsh-iris@0.2.1
+```
+
+Or install the CLI in your project:
+
+```bash
+npm install @mokuyoaxis/dsh-iris@0.2.1
+npx dsh-iris --help
+```
+
+After updating a DSH plugin, reload the backend and refresh the web client. Older supported hosts should keep the pinned 0.1.4 release.
+
+### Verification and limits
+
+Verification covers 163 test files, lint over 263 source files, an actual tarball installed outside the repository without DSH, and 31 isolated checks against installed DSH rc.2 services. Live checks also exercised gateway image generation, Artifact-ID vision, and chat edits delivered through DSH and the workbench while preserving source hashes.
+
+Browser/mobile acceptance of the complete work-library flow and asynchronous restart with CLI takeover remain open. These checks are not inferred from automated tests or isolated host-service checks.
+
+Responses image generation currently supports synchronous single-image requests. Chat image generation/editing is a gateway extension to Chat Completions, not a claim that every OpenAI-compatible chat service supports images. Editing accepts one static PNG/JPEG/WebP Artifact; masks, multiple references and conversation edit history are not implemented. Image detail, edit fidelity and output resolution depend on the selected service.
+
+OpenAI-compatible image and vision support does not add generic video, TTS, transcription or music protocols. Core deletion is recoverable quarantine, with no permanent purge; legacy work deletion retains its existing permanent behavior. Accepted or uncertain generation never automatically resubmits. Core and Model Port internals remain outside a frozen public SDK.
+
+### Future plans
+
+Extend support to other protocols and add music generation, building on Core tasks, Artifacts and work-library management. These are planned follow-up features and are not included in 0.2.1; see the [roadmap](https://github.com/mokuyoaxis/dsh-iris/blob/v0.2.1/docs/ROADMAP.md#后续功能方向).
+
+Full scope: [CHANGELOG](https://github.com/mokuyoaxis/dsh-iris/blob/v0.2.1/CHANGELOG.md), [CLI management](https://github.com/mokuyoaxis/dsh-iris/blob/v0.2.1/docs/CLI_MANAGEMENT.md), [workbench artifacts](https://github.com/mokuyoaxis/dsh-iris/blob/v0.2.1/docs/WORKBENCH_ARTIFACTS.md), and [roadmap](https://github.com/mokuyoaxis/dsh-iris/blob/v0.2.1/docs/ROADMAP.md).
+
+Full changelog: [v0.2.0…v0.2.1](https://github.com/mokuyoaxis/dsh-iris/compare/v0.2.0...v0.2.1).

package/docs/releases/0.2.2.md

@@ -0,0 +1,31 @@
+# Iris 0.2.2：可控提示词编辑与媒体运行可靠性
+
+0.2.2 在既有图片与视觉工作流上，升级提示词优化的一般功能，并加固 Core 恢复、媒体交付和生图错误诊断。包名仍为 `@mokuyoaxis/dsh-iris`，Node.js 最低为 22.0.0，DSH 插件仅声明支持 `0.2.0-rc.2`；配置、Task/Artifact 版本和生产依赖保持。
+
+## 提示词优化
+
+- 一般功能可折叠，支持通用、画图、改图、视频与数字人五种用途，可查看草稿、改动及实际指令。
+- 默认“忠实整理”：模型只决定相邻片段的分段位置，程序从原文按原顺序拼回；遗漏、重复或调换片段会拒绝。它保证原文片段和句序，不声称自动证明所有排版变化的语义相同。
+- 明确选择“改写表达”才执行改写规则；改写结果仍需人工核对。
+- 可选建议独立获取，默认不加入正文；用户选择并采纳后才改变预览，支持撤回。获取建议会额外调用一次模型，采纳/撤回不调用模型、不直接写回或发送。
+- 保留旧自定义 v1 配置和旧文字 API，不自动改写个人配置；内置指令按 Skills 的目标、输入、约束和输出组织，S2V 明确为首帧加音频数字人。
+- 拒绝原稿和明确规则未授权的新链接/媒体输出，保护原稿和已有预览；不自动重试。合法引用与原样组装保持。
+
+## 功能模型池与媒体可靠性
+
+- 能力来自明确模型标签、旧能力字段绑定或供应商能力元数据；裸 DashScope 账号和模型名称不再自动赋予功能。发现保留未标注模型，供用户设置功能标签。已有明确配置（含空标签）优先，有序候选与复合模型身份保持。
+- Core writer 创建前原子发布完整 owner 意图，释放时整体退役目录；显式恢复保留连续步骤与审计。普通 writer 不自动抢占，活跃、未知、损坏或无 owner 的旧现场仍拒绝。需要支持 hard link 的私有文件系统，不承诺断电、共享存储或混用旧 writer 的新增保证。
+- 视频、音频与文本 staging 复用文件接收和分块哈希，减少整文件读取；本地交付失败保留远端成功，重新交付不重新生成。图片格式验证和 inline 解码仍可能使用完整 Buffer。
+- 生图尺寸按协议归一分隔符，DashScope 多模态只执行有证据的总像素规则，合法长边不再被误拒绝。本地尺寸错误在 HTTP 前明确为未受理。
+- 网络异常保留请求/正文阶段与可用错误码，原生取消/超时和完整 HTTP 业务错误保持各自分类；DSH 即时错误显示脱敏原因。受理未知仍禁止自动重提收费请求，HTTP 200 响应头不等于图片已交付。
+- 修复故障注入夹具的路径别名与分隔符假设，保持实际中断检查点验证，不通过跳过 Windows 测试绕过问题。
+
+## 升级与边界
+
+在 DSH `0.2.0-rc.2` 的 Web profile 使用 `dsh plugin --profile web add @mokuyoaxis/dsh-iris@0.2.2`；CLI 使用 `npm install @mokuyoaxis/dsh-iris@0.2.2`。升级后重启宿主并刷新客户端。旧宿主继续固定使用 Iris 0.1.4；其他 DSH 版本需独立验证。
+
+仅有裸账号而没有明确功能标签的配置，升级后需要给实际模型设置功能，再加入对应有序候选池；不会自动创建默认模型或迁移个人文件。原自定义 Prompt 不被覆盖，只有显式恢复默认才采用新内置模板。
+
+Music 继续暂缓，特殊功能待定义。英文默认 Prompt 和严格纯正文候选仍是实验，未在本版部署。原生 Gemini/Fal/Replicate、独立提示词 CLI/SDK、同步无远端 ID 的持久缓存恢复未接入；完整工作台第三轮与真实异步重启接管验收仍待补齐。网关 Gemini 兼容生图成功不等于原生 Gemini Adapter 或具体底层模型身份已验证；一次线路成功不保证持续稳定。
+
+详细用法见 [提示词优化](../PROMPT_OPTIMIZER.md)、[Core Runtime](../CORE_RUNTIME_CONTRACT.md)、[Provider Adapter](../PROVIDER_ADAPTER_CONTRACT.md) 和 [用户指南](../../user_guide.md)。