@mokuyoaxis/dsh-iris 0.2.0 → 0.2.1

package/docs/VISION_CLI.md

@@ -0,0 +1,132 @@
+# 独立视觉 CLI
+
+状态：**Iris 0.2.1**。安装 `npm install @mokuyoaxis/dsh-iris@0.2.1` 后运行 `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.1**。本文说明共享单图视觉调用。
+
+## 使用与变化
+
+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.1**。
+
+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).