@mokuyoaxis/dsh-iris 0.2.0 → 0.2.2

package/docs/ARTIFACT_LIBRARY.md

@@ -1,12 +1,12 @@
-# Iris 作品库 v0
+# Iris legacy 作品库 v0
 
-状态：v0.1.4 候选实现。
+状态：自 v0.1.4 实现，Iris 0.2.2 保留兼容。本文只描述旧 `outputs/` 与最小索引；当前工作台同时展示 Core Artifact，分页、过滤、批量下载与可恢复隔离见 [工作台作品管理](WORKBENCH_ARTIFACTS.md)。
 
 作品库解决“清除任务历史后仍能看到本地作品”的问题。任务记录描述执行过程；作品记录只负责本地媒体的发现、展示和访问。两者生命周期彼此独立。
 
 ## 用户语义
 
-- 新生成并成功落盘的图片、视频和音频会自动进入作品库。
+- 旧链路生成并成功落盘的图片、视频和音频会进入此索引；0.2.1 的 Core 媒体链路使用独立 Manifest，并由统一作品库展示。
 - 首次升级到带作品库的版本时，Iris 会扫描现有 `outputs/` 并建立最小索引。
 - “清空已完成”或“清理 7 天前”只删除终态任务记录，作品仍可从工作台和泡泡打开。
 - “找回本地作品”会重新扫描 `outputs/`，补录受支持的普通媒体文件，并移除文件已经不存在的失效索引。
@@ -19,6 +19,6 @@
 
 作品链接继续复用 `/iris/media`，使用 128-bit 随机能力令牌并只从索引解析文件。错误 ID、令牌、文件名或路径穿越输入统一返回 404。作品库不是备份：删除作品文件、删除整个 Iris 数据目录或存储损坏仍可能造成数据丢失，重要作品应另行备份。
 
-## 与未来 Artifact Manifest 的边界
+## 与 Core Artifact Manifest 的边界
 
-v0 不是完整 Artifact Manifest：没有内容哈希、去重、旁车数据、来源/派生关系、引用图或跨宿主导出契约。完整 Manifest 完成崩溃一致性和安全评审后，再承载收藏、标签、搜索、筛选和批量导出等能力。
+legacy v0 没有内容哈希、去重、旁车数据、来源/派生关系、引用图或跨宿主导出契约。[Artifact Manifest v0](ARTIFACT_MANIFEST.md) 已在 0.2.0 实现，Core 保存 SHA-256、关系边和可重建索引，不原地改写旧作品。0.2.1 的统一工作台已提供分页、过滤、显式选择与批量 ZIP 下载；收藏、标签和搜索仍属后续计划。旧文件的永久删除与 Core 的可恢复隔离具有不同语义。

package/docs/ARTIFACT_MANIFEST.md

@@ -1,6 +1,6 @@
 # Artifact Manifest v0
 
-Artifact Manifest v0 是 Iris 0.2.0 使用的内部格式，尚未作为公开 package API 冻结。它不替换 0.1.4 的 `outputs/` 与 `artifacts.json`；后续 Host 迁移只能显式、逐件复制旧作品，失败时保留原文件。
+Artifact Manifest v0 自 Iris 0.2.0 引入，0.2.1 沿用同一内部格式，尚未作为公开 package API 冻结。它不替换 0.1.4 的 `outputs/` 与 `artifacts.json`；后续 Host 迁移只能显式、逐件复制旧作品，失败时保留原文件。
 
 ## 存储与提交顺序
 

package/docs/CLI_MANAGEMENT.md

@@ -0,0 +1,183 @@
+# CLI 配置与任务管理
+
+本文面向 Iris 0.2.2，沿用 `dsh-iris` 入口，无需启动 DSH，未新增生产依赖。安装 `npm install @mokuyoaxis/dsh-iris@0.2.2` 后运行 `npx dsh-iris ...`；也可从源码或本地 tarball 使用同一入口。视觉命令见 [视觉 CLI](VISION_CLI.md)，基础媒体链路见 [Headless CLI](HEADLESS_CLI.md)。
+
+所有需要 JSON 的命令均支持 `--input '<json>'`、`--input-file /path/input.json` 或 `--input -`（stdin），只能选择一种，输入最多 2 MiB。私有配置必须是普通文件、绝对路径，POSIX 权限为 `0600`。真实请求只由显式执行生成、发现、实测或观察命令触发。
+
+能力配置规则已同步Iris 0.2.2：能力来自明确配置或供应商元数据，裸账号和模型名称不自动赋能。现有功能入口、按功能分配的有序候选池和安全切换规则保持。
+
+## S2V 数字人视频
+
+```bash
+dsh-iris run video --data-root /path/core --provider-config /path/providers.json \
+  --input '{"model_ref":"aliyun::wan2.2-s2v","first_frame_path":"/path/portrait.jpg","audio_path":"/path/speech.wav","resolution":"480P"}'
+```
+
+`first_frame_path` 与 `audio_path` 为绝对普通文件路径。提供音频时只选择 S2V 模型；显式选择普通视频模型会被拒绝，不能静默丢弃音频。S2V 的 prompt 可省略，resolution 支持 `480P`/`720P`，不接受 size/duration。普通图生视频也支持 `first_frame_path`，不能与 `img_data_url` 同时提供。
+
+DSH/CLI 共用 Core Runner：每个候选先写 Attempt，再以该候选的账号上传首帧和音频；只有明确未受理才可切换，受理未知停止。取消上传不提交生成、不转下一候选。图片/音频路径、上传地址和凭据不会写入 Task。后续 `task observe/wait` 使用原 Task/Provider/binding，不再上传或提交；最终得到 `generated-video` Artifact。DSH 的本会话附件首帧仍支持，宿主把附件字节转换为可读文件。
+
+## HTML 截图
+
+```bash
+dsh-iris media html --data-root /path/core --input-file /path/html-input.json \
+  --browser-executable /path/chromium --output /path/screenshot.png
+```
+
+输入为 `{"html":"<h1>Hello</h1>","width":1280,"height":720,"full_page":true}`。视口宽高为 1–4096 的整数，默认 1280×720；默认整页截图，最多 4000 万像素、单边 16384。也可以用 `IRIS_BROWSER_EXECUTABLE` 提供可执行文件绝对路径，不自动寻找 DSH 的浏览器或配置。
+
+独立 Chromium 通过 CDP pipe 通信、使用临时 profile 与临时回环 HTML 服务；操作结束或取消时关闭进程与临时目录。只接收 HTML 字符串，CSP 与原 DSH 渲染边界一致：允许内联样式、data/blob 图片、data 字体，禁止脚本、网络资源、表单和子页面。无任意 URL 截图入口。默认保留 Chromium 沙箱；确需在 root/PRoot 环境运行时，可显式传 `--browser-no-sandbox true`。默认整体超时 30 秒。
+
+截图先保存为 `html-screenshot` Core Artifact，`--output` 可同时导出 PNG，不覆盖已有文件。DSH 的工具与工作台 action 复用同一 Command 保存 Artifact，浏览器仍由 Host Port 提供。
+
+## 账号、模型与配置
+
+| 命令 | 行为 |
+| --- | --- |
+| `config init/show/check` | 创建空私有配置（不覆盖）、脱敏查看、检查重复账号和失效分配 |
+| `providers list` | 原有脱敏账号列表 |
+| `providers add/set --input-file ...` | 添加/局部更新账号；JSON 是 provider 对象，必须包含 id |
+| `providers remove <id>` | 移除指定账号，剪去失效分配 |
+| `models list` | 模型复合引用、能力和实测事实 |
+| `models add <ref> [--input ...]` | 添加模型；可给 capabilities，省略或空数组则保持未标注 |
+| `models caps <ref> --input ...` | 手动能力标签（允许空数组） |
+| `models protocol <ref> --input ...` | 单模型图片协议；`auto` 恢复账号默认 |
+| `models vision-input <ref> --input ...` | 模型视觉输入预算；`null` 恢复账号继承 |
+| `models remove <ref>` | 移除模型，剪去失效分配 |
+| `models discover <provider-id>` | 请求发现，仅预览，不修改配置 |
+| `models discover <provider-id> --apply true` | 合并明确能力元数据，保留未标注条目、已有明确标签和实测记录 |
+| `models test <ref> --capability vision` | 一次红图视觉实测，严格绑定该模型，记录 verified |
+| `models test <ref> --capability image-gen/tts --data-root ...` | 实际生成测试，结果保存为 Core Task/Artifact，图片最多等待 60 秒 |
+| `models test <ref> --capability video-gen/transcribe --data-root ... --input ...` | 使用真实素材单独实测，输入格式同 `run video/transcribe`，最多等待 60 秒；成功才恢复停用模型 |
+| `assignments list/set/clear` | 查询路由候选、保存有序复合引用或清除指定能力分配 |
+
+上述命令均需 `--provider-config /path/providers.json`。`<ref>` 必须是 `providerId::modelId`；媒体 run 的既有输入规则不变。`models test` 本身是显式真实请求，可能消耗额度，只调用指定模型，成功后解除该模型的冷却或耗尽停用。视频/转写未提供 `--input` 时返回 `skipped:true`，不请求供应商、不记录成功。`models list` 对受阻模型显示 `rateLimited`，短时限流另有 `retryAt`，明确耗尽另有 `reason`。
+
+```bash
+dsh-iris providers add --provider-config /path/providers.json --input-file /path/private-provider.json
+dsh-iris models caps 'aliyun::qwen3-vl-flash' --provider-config /path/providers.json \
+  --input '{"capabilities":["vision"]}'
+dsh-iris assignments set --provider-config /path/providers.json \
+  --input '{"capability":"vision","model_refs":["aliyun::qwen3-vl-flash"]}'
+```
+
+配置在明确写命令或真实请求首次确认冷却/耗尽时更新；只读查询和冷却到期不写配置、不请求模型。未知字段保留，每次写入先创建唯一的 `0600` 私有备份，再原子替换。备份包含原始凭据，按私有配置保管。并发修改检测失败则拒绝覆盖；不会自动迁移 DSH 配置或轮换备份。发现不会自动实测。脱敏输出不展示 API key、端点或原始错误正文。
+
+### 看图输入预算
+
+账号 `visionInput` 和 `models[].visionInput` 配置视觉发送副本的大小与最长边，用于看图、OCR 每块输入、定位及聊天改图。`maxBytes` 是图片编码字节上限，`maxDimension` 是最长边像素，均为正整数；模型逐字段覆盖账号，未设置时默认 8 MiB、不限制最长边。该默认值是客户端预算，不是上游能力声明。无需修改配置版本或迁移旧数据。
+
+```bash
+dsh-iris providers set --provider-config /path/providers.json \
+  --input '{"id":"gateway","visionInput":{"maxBytes":12582912}}'
+dsh-iris models vision-input 'gateway::vision-model' --provider-config /path/providers.json \
+  --input '{"visionInput":{"maxDimension":2048}}'
+dsh-iris models vision-input 'gateway::vision-model' --provider-config /path/providers.json \
+  --input '{"visionInput":null}'
+```
+
+示例中的 12 MiB 仅演示已知上游限制，其他账号应按实际服务设置。`models list/config show` 返回模型的 `visionInputEffective`；模型发现保留已有覆盖。工作台账号详情、视觉模型行与聊天生图模型行提供 MiB、最长边和恢复继承。保存配置不调用模型、不改验证成功状态、不解除额度停用。
+
+小图透传，超限 PNG/JPEG/WebP 等比缩小，保持真实格式和方向；Core 原图、尺寸和哈希不变，不创建预览 Artifact。读取原图片的本地上限仍为 20 MiB。OCR 先切片，再按实际候选预算处理每块，结果记录实际输入并提示缩小时的细字风险；定位显式转正图片，约定模型使用 0–1000 坐标，返回原图像素 bbox。DSH 使用核验后的实际附件尺寸。摘要拼图仍按原业务处理，动画需要缩放时拒绝。大小拒绝显示实际字节数与已知上限，400 不记为 429 冷却，不自动重发。
+
+### 模型级图片协议
+
+模型对象可选 `imageProtocol` 字段。支持 `dashscope`、`openai-images`、`openai-chat-images` 和 `openai-responses-images`；省略或使用 `auto` 时继承账号的 `mediaProtocol`。这个覆盖仅用于生图，不改变同模型的视觉能力或账号的视频、语音、转写路由。媒体端点仍使用账号的 `mediaBaseUrl`，留空沿用 `baseUrl`；DashScope 仍只允许阿里云官方 HTTPS 地址。
+
+```bash
+dsh-iris models protocol 'account::image-model' --provider-config /path/providers.json \
+  --input '{"imageProtocol":"openai-images"}'
+dsh-iris models protocol 'account::image-model' --provider-config /path/providers.json \
+  --input '{"imageProtocol":"auto"}'
+```
+
+`models add` 的输入也可同时提供 `capabilities` 和 `imageProtocol`。`models list/config show` 展示模型覆盖值及有效 `imageRouting`；DSH 设置中的生图模型行可直接选择图片协议。发现和能力编辑保留协议覆盖，不扫描生图端点、不自动实测。改变有效协议使该模型的生图验证失效，保留其他能力、其他模型与已有额度停用；异步观察/取回仍核对原模型的提交协议，协议改变时在请求前停止。
+
+`openai-chat-images` 是兼容网关的非流式 `POST /chat/completions` 生图扩展，读取消息正文中的图片 Markdown/data URL、`image_url` 内容块或 `message.images`；它不是 OpenAI 官方通用生图响应。普通文字或链接不会作为图片成功，纯文字 200 保留结果未知，停止自动切换接口或模型。只调用显式配置的接口，不扫描后缀。
+
+例如已在目录中的 `gemini-image` 可显式设置生图能力及聊天协议，随后直接生成并按返回的 Artifact ID 看图：
+
+```bash
+dsh-iris models caps 'gateway::gemini-image' --provider-config /path/providers.json \
+  --input '{"capabilities":["image-gen"]}'
+dsh-iris models protocol 'gateway::gemini-image' --provider-config /path/providers.json \
+  --input '{"imageProtocol":"openai-chat-images"}'
+dsh-iris run image --data-root /path/core --provider-config /path/providers.json \
+  --input '{"prompt":"画一只蓝色机器人","model_ref":"gateway::gemini-image"}'
+dsh-iris vision look --data-root /path/core --provider-config /path/providers.json \
+  --model-ref 'gateway::gemini-3.8-flash' --input '{"artifact_id":"artifact_ID"}'
+```
+
+聊天生图不发送 Images 的 `size` 参数；显式传入会在请求前报错，尺寸可在提示词中描述。`n>1` 使用聊天协议的候选数量参数，是否支持及实际图片数量由网关决定；默认单次请求一张。手动实测使用无尺寸参数的同一适配器。
+
+`openai-responses-images` 调用非流式 `POST /responses`，提交 `image_generation` 工具并指定 `action:generate` 和工具选择；`store:false`、`background:false`。模型引用指定 Responses 主模型，图片工具模型使用服务端默认，需选择支持图片工具的主模型。官方完成态 `image_generation_call.result` 为图片 base64；网关完成态消息中的 `output_text` 图片 Markdown/data URL 也可读取，这种消息不能证明执行了官方工具。参考 [官方图片工具说明](https://developers.openai.com/api/docs/guides/tools-image-generation)。
+
+```bash
+dsh-iris models protocol 'gateway::gemini-image' --provider-config /path/providers.json \
+  --input '{"imageProtocol":"openai-responses-images"}'
+dsh-iris run image --data-root /path/core --provider-config /path/providers.json \
+  --input '{"prompt":"画一只蓝色机器人","model_ref":"gateway::gemini-image"}'
+```
+
+此切片只支持同步生图、`n=1`，多图数量在请求前拒绝；可选 `size` 传给图片工具（例如 `1024x1024`，尺寸支持由服务端决定），默认与手动实测不指定尺寸。纯文字、无图、非法 base64 或未完成结果均停止并保留未知，不自动改接口或重提。目前不接后台轮询、多轮编辑、源图上传或 `/images/edits`。
+
+四种生图适配器共用 Core 交付，按实际图片字节识别 PNG/JPEG/WebP；MIME、`.png`/`.jpg`/`.webp` 后缀与 SHA-256 匹配，保留原字节，不因 data URL 标注、HTTP 头或 URL 后缀而转码。图片格式不受支持或取回失败只标记交付失败，保留远端成功事实，不自动重新生成。
+
+## Artifact 聊天改图
+
+为 `run image` 提供 `source_artifact_id`，将当前 Core 中的原图与修改指令一起发送给支持带图编辑的 `openai-chat-images` 模型：
+
+```bash
+dsh-iris run image --data-root /path/core --provider-config /path/providers.json \
+  --input '{"source_artifact_id":"artifact_ID","prompt":"把蓝色发饰改成白色，保留人物、服装和构图","model_ref":"gateway::gemini-image"}'
+```
+
+来源必须是同一数据根中的有效 Artifact ID（`artifact_` 后 24 位十六进制），最多 20 MiB 的静态 PNG/JPEG/WebP；创建 Task 前核验哈希、MIME 和真实格式。不需要导出原图，不支持 GIF/动画或蒙版。省略 `model_ref` 时沿用生图候选顺序，只保留聊天生图协议；显式指定其他协议会在 HTTP 前拒绝，不误发普通文生图。模型是否实际支持编辑由上游决定。
+
+原图只读，发送副本复用默认 8 MiB 与账号/模型 `visionInput`，按每个实际候选分别处理。新 Task 保存 `sourceArtifactId`，新 Artifact 保存 `derived-from` 来源关系；输出原字节及 MIME 保留。返回的新 Artifact ID 可继续 `vision look/ocr`、导出或编辑。
+
+未知受理、纯文字响应和交付失败不会自动重提或切换端点。知情 `task retry --confirm-billing true` 必须在新的 `--input` 中重新提供 `prompt` 和 `source_artifact_id`，模型覆盖使用外层 `--model-ref`。Core 删除预览会识别原图被编辑任务与新作品引用的情况。DSH 对应工具为 `iris_edit_image`，动作是 `image_edit`，工作台图片卡提供“改图”。
+
+## 等待与查询
+
+```bash
+dsh-iris task wait task_ID --data-root /path/core --provider-config /path/providers.json \
+  --timeout-ms 120000 --poll-interval-ms 2500
+dsh-iris task list --data-root /path/core --capability video --status succeeded --limit 20 --offset 0
+dsh-iris artifact list --data-root /path/core --kind generated-video --media-type video/mp4 --limit 20
+```
+
+`task wait` 只观察原 Task，不重新提交或自动 redeliver/retry。默认 120 秒、2.5 秒间隔，超时上限 20 分钟；超时中断在途 poll/下载，保留远端受理事实，可再次 wait。已结束的任务仅只读检查，不需要 Provider 配置或网络。退出码：ready 为 0，未成功交付为 1，超时为 3，SIGINT/SIGTERM 为 130/143。
+
+分页默认 limit=50，上限 200，offset 非负。Task 支持 status/capability/provider-id/model-ref/outcome/delivery-state；Artifact 支持 kind/media-type/task-id。先过滤再分页，total 是过滤后的匹配总数。列表只读，不触发观察或重建。
+
+```bash
+dsh-iris task inspect-many --data-root /path/core --input '{"task_ids":["task_ID"]}'
+dsh-iris artifact inspect-many --data-root /path/core --input-file /path/artifact-selection.json
+dsh-iris artifact export-many --data-root /path/core --input-file /path/artifact-selection.json --output /path/export-directory
+```
+
+Artifact 批量输入为 `{"artifact_ids":["artifact_ID", "artifact_OTHER"]}`，最多 200 个唯一 ID。批量查询逐项报告事实或错误；批量导出要求已有绝对输出目录，文件名由 ID 和媒体扩展名生成。所有 ID、媒体哈希及目标存在性先预检，失败则零导出；后续 I/O 错误逐项报告已导出与失败结果，退出码 1。不会覆盖已有文件，不隐式选择全部作品。
+
+## Core 删除、清理与恢复
+
+```bash
+# 默认只读预览；引用未同时选入时返回阻挡原因。
+dsh-iris core delete --data-root /path/core --input-file /path/deletion-selection.json
+# 输入为 {"task_ids":[...],"artifact_ids":[...]}，执行需明确标志。
+dsh-iris core delete --data-root /path/core --input-file /path/deletion-selection.json --confirm-delete
+dsh-iris core transactions --data-root /path/core
+dsh-iris core restore delete_ID --data-root /path/core
+
+dsh-iris core cleanup --data-root /path/core
+# 使用预览中的相对 paths 明确选取，不支持 glob。
+dsh-iris core cleanup --data-root /path/core --input-file /path/cleanup-selection.json --confirm-delete
+```
+
+仅允许确定终态 Task；活跃任务和受理/结果未知任务保留。Task 的 Artifact 引用、Artifact 关系、Artifact 的 taskId、后继任务 retriedFrom 都会阻止单独删除，需同时选入相应记录。不自动级联删除。
+
+删除先写事务清单，再把指定 Core 文件移到同一数据根的 `maintenance/v0/quarantine/delete_ID/`，更新已提交 Artifact 的派生索引，不接回孤儿、不升级早期记录。中途失败尽力补偿，保留事务 ID；崩溃后 `core transactions/restore` 可按写前清单恢复。恢复核对哈希、大小和原位置，不覆盖冲突文件。
+
+清理预览只列出默认一小时以上、原进程已退出的已知下载 `.part`，及没有 record/Manifest/Task/关系引用的已知孤立对象；`older_than_ms` 最小一分钟。执行必须提供当前仍符合条件的具体 paths。符号链接、未知文件、未提交 Manifest、legacy `outputs/` 和外部路径不会清理。Doctor 仍只读报告，无自动删除或修复。
+
+**隔离保留字节，暂不提供永久 purge，因此不会立即释放这部分磁盘空间。** DSH 工作台也已接上同一删除预览、隔离与事务恢复，见 [工作台作品管理](WORKBENCH_ARTIFACTS.md)；旧版永久删除/清空语义保持原样。收藏/标签、搜索及永久 purge 另行安排。

package/docs/COMPOSITE_VISION.md

@@ -0,0 +1,35 @@
+# 定位、视频摘要与图片自述
+
+状态：**Iris 0.2.2**。长图分块另见 [OCR](OCR_MODEL.md)。
+
+## 使用与变化
+
+Agent 的 `iris_locate` 和工作台定位使用共享 Vision Ports。目标先修剪，空目标在图片读取前拒绝；业务返回原图像素 bbox，保留 `found:false`、边界钳制和裁剪指令。只有完整正常终态的回答才解析 JSON；格式错误不会触发另一次模型生成。定位仍依赖模型判断，不保证精确像素边界。
+
+定位在提交前按实际账号/模型预算缩小发送副本，并显式应用 EXIF 方向。提示词给出真正发送图的尺寸，明确约定模型返回 0–1000 归一化坐标（左右为 x，上下为 y）；不是根据数字大小猜测坐标域。完成后对四角进行比例与 EXIF 逆变换，左上向下取整、右下向上取整，返回原文件的原始像素 bbox，与 Core 裁剪使用的坐标一致。DSH 用核验后的实际附件尺寸；候选切换不会复用上一模型的输入记录。CLI 和共享结果附安全 `input` 尺寸事实，`coordinateSpace: normalized-1000` 表示模型约定，公开 bbox 始终是原图像素。归一化精度和定位边界仍取决于模型。
+
+定位支持 Core 图片 `artifact_id`：Agent 的 `image_path`、`artifact_id`、`attachment_id` 三选一，动作和 CLI 使用路径或 Core ID 二选一。直接只读核验图片原字节/MIME，坐标按实际图片尺寸计算；不导出临时文件、不新增 Core 产物。Core 输入的工具结果注明 ID 和裁剪区域，避免把 ID 当成本机路径；工作台动作 JSON 保留 `artifactId`。现有文件/会话附件用法保留，CLI 示例见 [视觉 CLI](VISION_CLI.md)。
+
+`iris_media_summarize` 和工作台视频摘要可用 `video_path` 先经 ffmpeg 抽帧，或用 `frame_artifact_ids` 直接读取当前 DSH profile 中既有 Core 抽帧 Artifact，再用 Sharp 按时间顺序拼成一张带时间戳的 PNG。一次候选生成只发送这一张拼图，不逐帧请求模型；成功后提供同一张拼图供用户检查。修复时间戳标签缺少绘制空间，以及十帧以上按文件名字典序排列导致的时间顺序错误。
+
+`iris_video_frames` 的文字结果会给出可复用的 `frame_artifact_ids` 数组；将这些 ID 交给 `iris_media_summarize` 即可，原视频无需再次可用。已有帧只读、核验内容哈希，按原 `atSec` / `frameIndex` 排序，最多选择 20 帧；不调用 ffmpeg、不重新导出或写入 Core，其他 writer 存在时仍可摘要。结果保留 ID、原帧序号、时间戳及尺寸，展示所选帧时间范围，不猜测完整视频时长。不得同时指定视频路径、抽帧选项或 `transcribe:true`；已有台词通过 `transcribe_text` 显式提供。CLI 使用同一读取器，见 [视觉 CLI](VISION_CLI.md)。工作台现有表单仍输入视频路径，动作 API 也接受帧 ID。
+
+工作台消费显式转写文字。Agent 的视频文件模式保留原有 `transcribe` 选项：默认在视频有音轨且已配置转写供应商时提取音频，提交既有 Core 转写任务，观察成功后读取其文本 Artifact；也可显式提供 `transcribe_text`，失败时注明只分析画面。取消或超时直接终止摘要，不再进入视觉生成。已经提交的远端转写任务保留 Core 事实，可用任务工具继续查询。
+
+图片生成后的可选自述也消费共享端口。自述失败或取消时不返回半截描述，已完成的图片交付仍按原流程处理；提示词上下文和描述长度沿用原限制。
+
+## 整体调用控制
+
+定位、摘要和自述沿用 [单图视觉调用](VISION_MODEL.md) 的候选策略、正常终态及图片字节桥接。只有明确拒绝、正常空正文或本地不可用才允许下一候选；收到部分正文后的错误、截断、未知终态、取消和超时均停止操作。
+
+每次操作默认 120 秒。图片读取、抽帧、可选转写等待、拼图、元数据和全部视觉候选共用这一预算；每次视觉调用只使用剩余时间，总生成次数最多为有限候选表的长度。转写沿用 Core Task 的独立执行语义，不计入视觉生成次数。文字、图片和输出大小上限沿用 M3。
+
+预先取消不读取图片、不保存模型附件、不生成；在途取消传给 ffmpeg 和模型，停止后续帧处理及候选。Sharp 原生操作和同步 ffprobe 无法由 AbortSignal 强制打断，取消后不会消费迟到结果继续生成。DSH rc.2 的附件保存没有取消参数：模型桥接等待受操作预算限制，成功摘要的附件交付在模型操作结束后执行，前后检查调用方取消；迟到保存可能留下宿主附件。
+
+## 模块与验证
+
+`locate.js` / `summarize.js` 只消费图片或帧字节及模型端口；`composite-vision-routing.js` 复用 M3 的候选、预算和结果投影。DSH 入口负责附件、视频路径、可选 Core 转写与结果交付。纯定位、画面摘要和自述不创建 Core/legacy Task 或 Artifact；显式音轨转写产生既有 Core Task/Artifact。
+
+验证覆盖原 bbox 解析、时间戳实际像素、十二帧时序、一张拼图一次生成、取消/超时、Core 转写正文接线、真实安装的 DSH rc.2 工具和 HTTP 入口，以及无 DSH/Cordis 的 tarball 安装副本。2026-10-05 另以真实 `dsh` CLI 启动隔离 profile，使用已有 DashScope `qwen3-vl-flash` 完成定位、三色视频摘要、自述和收到正文后的取消，共七次模型请求；这些合成样本不代表复杂视频或目标定位质量。
+
+共享视觉迁移本身不增加公开 SDK export 或生产依赖；未被业务入口调用的 legacy 兼容实现仍保留。0.2.1 的 [独立视觉 CLI](VISION_CLI.md) 复用这些业务，提供严格显式模型选择；同时支持 Core 帧摘要、可选输入预算、HTML/Browser 和 S2V。

package/docs/CORE_RUNTIME_CONTRACT.md

@@ -1,12 +1,12 @@
-# Core Runtime v0 候选契约
+# Core Runtime v0 内部契约
 
-本文定义 0.2.0 的 Core Runtime 内部接口。内部接口在后续版本仍可能调整，npm 包不把它作为公开 API 导出；现有 `config.js`、`tasks.js` 和 `artifacts.js` 也尚未迁移。
+本文定义 Iris 0.2.2 沿用的 Core Runtime 内部接口，初版在 0.2.0 实现。内部接口在后续版本仍可能调整，npm 包不把它作为公开 API 导出；现有 `config.js`、`tasks.js` 和 `artifacts.js` 也尚未迁移。
 
 ## 目标与范围
 
 Core Runtime 由调用方显式创建、启动和释放。数据根、操作权限、取消和清理都属于实例；存储缓存与观察器接入后也必须遵守同一归属。Core 不推断 DSH profile，不读取 `ctx`，不启动浏览器或监听端口，也不在启动、Doctor 或能力枚举时触发供应商请求。
 
-0.2.0 包含 Runtime、Task/Attempt、Artifact Manifest、本地与媒体 Command，以及 DSH 对已迁移媒体任务的同源消费。s2v、视觉理解等未迁移能力仍走 legacy Host；完整迁移与公开 Core API 冻结留待后续版本。
+0.2.0 包含 Runtime、Task/Attempt、Artifact Manifest、本地与媒体 Command，以及 DSH 对已迁移媒体任务的同源消费。0.2.1 已迁移 S2V 与 HTML，单图视觉、OCR、定位、摘要及提示词预览通过共享 Model Ports 执行；纯视觉不自动创建 Task/Artifact。legacy 存储和兼容入口保留，公开 Core API 仍未冻结。
 
 ## 数据根和进程归属
 
@@ -19,6 +19,14 @@ Core Runtime 由调用方显式创建、启动和释放。数据根、操作权
 
 初版租约优先使用 Node 标准库和本地文件系统能力，不新增生产依赖。Android 共享存储、网络文件系统和异常退出后的恢复只有拿到真实证据后才声明支持；实现不得假设 systemd 或常驻 daemon 存在。
 
+0.2.2在原 v0 租约目录旁增加 `.iris-runtime-writer-v0.owner.json` 意图证据：完整私有 owner 先准备，再通过排他 hard link 原子发布，随后创建目录并链接 `owner.json`。新写者同时尊重目录和意图；创建中断仍保留完整 PID。文件系统不支持 hard link 时安全失败，不回退到可能半写的锁。Task、Artifact、配置格式和 CLI 参数不变，既有完整 v0 目录仍可诊断与显式恢复。
+
+正常释放先整体 rename 非空目录为本实例 UUID 的退役目录，最后撤下意图；不会先在占位目录里删除 owner。退役目录本身不占有固定租约，但若撤下意图前中断，剩余意图仍阻止普通 writer，需要在 owner 已退出且证据完整时显式恢复。意图撤下后的清理只涉及本实例退役证据，清理失败不阻止新 writer；遗留退役目录不会在下次启动时自动删除。
+
+恢复使用数据根中按前驱 UUID 排他发布的完整记录，保留原 owner，不替换或删除旧恢复步骤。Doctor 的 `phase` 可为 `owned`、`pending`、`recovering`；恢复再次中断时回显最新报告中的 PID，并复核链中每个 PID 均为 missing。并发恢复与旧观察被新 writer 接替均拒绝，不向新租约目录写入陈旧 claim。无 PID 的旧空目录、仅剩 `.owner.stale-*` 而缺少恢复 owner 的旧现场、未知文件、损坏或符号链接证据仍拒绝并保留。
+
+私有审计先记录退役授权和完整恢复链，再整体移走租约到审计记录指定的 `evidenceDirectory`。审计 JSON 的存在本身不证明最终解除成功：命令成功结果和退役目录是相应完成证据。异常退出的准备文件、退役目录与根中的未归档恢复记录保留，普通启动不清理。当前证据来自本机私有文件系统的进程 SIGKILL 与 I/O 故障注入，不承诺断电持久性或 Android 共享/网络文件系统支持；混用旧版本 writer 不纳入这些新增保证。
+
 ## 访问模式和操作分类
 
 | 模式 | `inspect` | `execute` | `recover` |
@@ -47,7 +55,7 @@ created --start--> started --dispose--> disposing --finish-dispose--> disposed
 
 ## 错误与结果边界
 
-候选稳定错误码：
+当前稳定错误码：
 
 - `IRIS_CORE_OPTIONS_INVALID`：选项或显式数据根无效；
 - `IRIS_CORE_STATE_INVALID`：生命周期顺序无效；
@@ -66,18 +74,19 @@ created --start--> started --dispose--> disposing --finish-dispose--> disposed
 
 ## 当前接口与后续范围
 
-当前候选实现包括：
+当前实现包括：
 
 - `normalizeCoreOptions()`：规范化显式数据根和 reader/writer 模式；
 - `createCoreRuntime()`：管理写者租约、状态、`AbortSignal`、在途操作和 cleanup；
 - `createCommandService()`：提供 `crop`、只读 `task.list/task.inspect`、显式单步 `task.observe`/`task.reobserve`（同一份实现，`reobserve` 是人工触发观察的对外命令名）、人工重新交付 `task.redeliver`（只开放 outcome=succeeded / deliveryState=failed，一次带 redelivery 标志的 re-poll + 下载，绝不 submit、绝不重新生成）、人工取消 `task.cancel`（只开放已受理未终态任务，只有 Provider 明确确认才写 canceled，不支持/无法确认保持真实状态）、人工重试为新任务 `task.retry`（只开放终态未成功交付任务；必须显式 confirm_billing 确认重复计费；新 Task 记录单向 retriedFrom 关系，候选链按宿主实况重新解析；Core 不持久化 Prompt，prompt 必须由调用方重新提供），以及 Artifact inspect/list/export/rebuild；Task reader 返回既有安全事实，不读取 Provider 配置，也不创建、修复或迁移记录；`observe/reobserve/redeliver/cancel` 只接受宿主注入的 Adapter resolver，`retry` 只接受宿主注入的候选链 resolver，Core 不读取配置路径；Task capability 现已覆盖 image、video、tts 与 transcribe——交付按 `provider-task-runner.js` 的 DELIVERY_PROFILES 冻结（video：`video/mp4` + `generated-video`；tts：`audio/mpeg`/`audio/wav` + `generated-audio`，同步 completed 同次调用内交付；transcribe：`text/plain` + `transcript`，正文物化为 UTF-8 Artifact），不共用不准确的图片交付语义；
+- 0.2.1 补齐 `media.diff/frames/html`、S2V 按候选上传、查询/批量管理与 Core 隔离/恢复；视觉和维护入口见 [CLI 管理](CLI_MANAGEMENT.md) 与 [视觉 CLI](VISION_CLI.md)。
 - Artifact Manifest v0：保存受控对象、SHA-256、关系边和可重建 Index，可跨 CLI 进程检查、导出和显式重建；Doctor 只报告孤立/未解析条目，不自动删除或修复。
 
-[Headless CLI](HEADLESS_CLI.md) 记录了当前开发接口，包括只读配置查询、Core Doctor 与陈旧租约显式恢复。FakeProvider 与各媒体 Profile 的离线生命周期测试已经存在；真实 Provider、Android 目视、跨平台 CI 和发布门禁仍须分别举证。未迁移能力保持 legacy 路径，不冒充 Core 事实。
+[Headless CLI](HEADLESS_CLI.md) 记录了当前接口，包括只读配置查询、Core Doctor 与陈旧租约显式恢复。FakeProvider 与各媒体 Profile 的离线生命周期测试已经存在；真实 Provider、Android 目视、跨平台 CI 和发布门禁仍须分别举证。legacy 数据与未迁移存储保持独立，不冒充 Core 事实。
 
 ## 非目标
 
 - 当前接口尚未作为 package export 或第三方 SDK 发布。0.2.0 的 F 阶段已正式决定：**不新增 `./core` 公开 export**——Root 插件与 `bin/dsh-iris` CLI 承载全部对外能力，内部模块（core-runtime、core-tasks、command-service、provider-task-runner、core-artifact*、core-user-projection）保持私有，可在 minor 版本间调整；冻结为公开 export 的决策顺延到 M2（0.3.0）的 Recipe/Serve 边界定稿后再审。届时一旦公开即写兼容策略与 semver 边界；
 - 不提供 standalone 服务、账号、多租户或额外监听端口；
-- 不包含新 Provider、收藏、标签、搜索或 Flow/Recipe；
+- 不预建缺少实际需求的 Provider 协议；收藏、标签、搜索与 Flow/Recipe 留待后续；
 - 不把 0.1.4 的模块级存储包装成实例存储，也不允许 CLI 与 DSH 无租约并发写同一数据根。

package/docs/DSH_CORE_MIGRATION.md

@@ -1,6 +1,8 @@
 # DSH → Core 渐进迁移
 
-本文描述 Iris 0.2.0 的实现与迁移边界。迁移逐条切换消费者，不原地改写 0.1.4 数据；未迁移能力继续使用原有实现。
+本文描述 **Iris 0.2.2** 的实现边界；0.2.0 建立的 Core 数据格式保持兼容。迁移逐条切换消费者，不原地改写 0.1.4 数据。
+
+0.2.1 已把 S2V、HTML、单图视觉、OCR、定位、摘要和提示词预览接入共享 Core Command 或 Model Ports，并补齐视觉 CLI、配置/查询/维护命令。图片按模型选择四种协议，Artifact ID 聊天编辑另存新作品并保留来源关系；输入预算仅处理发送副本。功能范围见 [发布说明](releases/0.2.1.md)。
 
 ## 已切换的执行链：本地媒体处理与新生成任务
 
@@ -23,7 +25,7 @@ Core runner 不拥有 timer，单次 observe 最多执行一次 poll，绝不 re
 - 启动扫描全部 Task 页，保守恢复 submitting、active、取消响应和交付中断窗口；仅接管仍有远端受理证据、且在自动窗口内的图片。旧无 binding Task 不猜测恢复配置。
 - timer 使用 unref，随插件 Fiber 清理；在途观察收到取消信号，旧回调不能清掉同一 Task 的新观察器。停止本地观察不宣称已取消远端任务。
 
-Headless CLI 使用同一控制面，但不自动循环：`task observe` 每次显式调用只 poll 一次，Provider 配置路径由 CLI 边界提供。
+Headless CLI 使用同一控制面：`task observe` 每次显式调用只 poll 一次；0.2.1 `task wait` 对原 Task 有界循环，超时中断在途请求、释放租约，绝不重提。Provider 配置路径由 CLI 边界提供。
 
 DSH 工作台现也开放同一份显式单步观察（D1 reobserve）：`POST /iris/api/core/task/:id/reobserve` 经 Command Service 命令 `task.reobserve`（与 `task.observe` 同实现），adapter/binding 恢复与 Host 观察节拍共用同一 resolver。用户任务区的 Core 投影行在服务端的行 DTO 标记 `observable`（已受理、有远端 ID、结果未定论、非终态）时显示「重新观察」按钮，点击后单次调用、禁用期间防重复，完成后复用刷新节拍重拉快照；高级诊断卡对符合同一受理事实门的任务提供同一动作。每次调用至多一次 poll，绝不 submit；终态、未受理、无远端 ID 或 binding 漂移的任务在网络与写入前被拒绝并返回稳定错误码。
 
@@ -35,7 +37,7 @@ DSH 工作台现也开放同一份显式单步观察（D1 reobserve）：`POST /
 
 ## 作品与只读诊断
 
-工作台只有一个作品库：Core 图片与旧 outputs 作品一起显示，原始输入 Artifact 不进入作品视图。Core 媒体路由 `/iris/api/core/artifact/<artifact_id>/media` 没有独立 token：它按随机 96-bit Artifact ID 读取，每次验证 SHA-256，并由默认回环/显式 trusted Host 与浏览器 `Origin`/`Sec-Fetch-Site` 守卫拒绝明确跨站请求。Artifact ID 持有者在可达受信 Host 时即可读取；Host allowlist 不等于身份认证。Host URL 不写回 Core。
+工作台只有一个作品库：统一展示 Core 与旧 outputs 的图片、视频、音频和文本，每页 24 个，支持媒体、来源及产物类型过滤；原始输入 Artifact 不进入作品视图。目录查询只读取已提交元数据和文件大小，图片卡直接按 Artifact ID 看图/OCR/聊天改图，详见 [工作台作品浏览与识别](WORKBENCH_ARTIFACTS.md)。Core 媒体路由 `/iris/api/core/artifact/<artifact_id>/media` 没有独立 token：它按随机 96-bit Artifact ID 读取，每次验证 SHA-256，并由默认回环/显式 trusted Host 与浏览器 `Origin`/`Sec-Fetch-Site` 守卫拒绝明确跨站请求。Artifact ID 持有者在可达受信 Host 时即可读取；Host allowlist 不等于身份认证。Host URL 不写回 Core。
 
 默认收起的“高级诊断 → Core 任务事实”展示同一批作品背后的 Task/Attempt，可展开、复制 ID 和打开图片，不是第二个作品库。`iris_task_status` 可查询同一 Core ID；CLI 指定同一 profile 数据根时可以 inspect/export，反向也成立。重复读取和附件投影不触发生成或修改 Core 事实。
 
@@ -53,7 +55,7 @@ Core 任务的提醒处置属于 **Host 偏好**（计划铁律：提醒已读/
 
 ## 视频迁移（E 阶段第一项）
 
-t2v/i2v 视频已迁到 Core，与图片共用 Task/Attempt 事实轴但**不共用图片状态机**：交付走冻结的视频 Profile（`lib/provider-task-runner.js` 的 `DELIVERY_PROFILES.video`：媒体白名单 `video/mp4`、Artifact kind `generated-video`、metadata 带 `capability`），观察用视频长轮询档（默认 6s/拍），受理、取消（当前真实协议不支持远端取消，not_supported 如实回落）、redeliver/retry 与 CLI/API/UI 控制面全部对视频生效。Agent 工具与工作台视频动作经 `submitCoreVideo` 落到 Core，**零 legacy 双写**（不再写 `tasks.json`/`outputs/`；旧视频任务继续 legacy 只读兼容）。同源媒体路由按 ID 播放 mp4；视频作品在任务区行内给出链接，不进入图片画廊网格。s2v 数字人（受理边界前需上传首帧与音频到临时存储）暂留 legacy 链路，后续单独迁移。真实 Provider 视频 canary 待验收。
+t2v/i2v 视频已迁到 Core，与图片共用 Task/Attempt 事实轴但**不共用图片状态机**：交付走冻结的视频 Profile（`lib/provider-task-runner.js` 的 `DELIVERY_PROFILES.video`：媒体白名单 `video/mp4`、Artifact kind `generated-video`、metadata 带 `capability`），观察用视频长轮询档（默认 6s/拍），受理、取消（当前真实协议不支持远端取消，not_supported 如实回落）、redeliver/retry 与 CLI/API/UI 控制面全部对视频生效。Agent 工具与工作台视频动作经 `submitCoreVideo` 落到 Core，**零 legacy 双写**（不再写 `tasks.json`/`outputs/`；旧视频任务继续 legacy 只读兼容）。同源媒体路由按 ID 播放 mp4；视频作品在任务区行内给出链接，0.2.1 也进入统一作品库并可按视频筛选。S2V 已迁入同一 Core：Attempt 写前落盘后，按实际候选上传首帧与音频。真实阿里云 wan2.2-s2v 的 480P/2 秒视频生成与导出哈希验收通过。
 
 ## 语音合成迁移（E 阶段第二项）
 
@@ -69,38 +71,65 @@ Core Command Service 已纳入两项确定性、零 Provider 的本地能力：`
 
 DSH 的 `iris_pixel_diff`、`iris_video_frames` 与工作台对应动作也消费上述 Command：Host 只解析图片附件/本地来源，并将已落盘的 Artifact 字节投影为附件或首帧预览。diff 的附件输入先形成 `host-input` Artifact，热力图保存 `derived-from` 关系；本地视频路径不伪造来源关系。结果提供 `artifactIds`，CLI 可从同一 Core 根检查和导出相同字节，DSH 不再为这两项另写 legacy Task 或 `outputs/`。
 
-图片、t2v/i2v 视频、TTS 与转写的正常提交和知情重试共用 `generation-input.js`：统一文本修剪、数量/时长/长度校验，并把 `img_data_url`、`audio_url` 转为 Adapter 的 `imgDataUrl`、`audioUrl`。非法输入在 Provider 提交和新 Task 创建前拒绝；CLI 仍返回 usage 退出码，Command 仍返回 `IRIS_COMMAND_INPUT_INVALID`。工作台清空可选文本框仍由 Host 解释为使用默认值。音频路径与签名地址不落 Core，上传和附件解析仍属于入口；S2V 的 legacy 参数链保持原边界。
+图片、t2v/i2v 视频、TTS 与转写的正常提交和知情重试共用 `generation-input.js`：统一文本修剪、数量/时长/长度校验，并把 `img_data_url`、`audio_url` 转为 Adapter 的 `imgDataUrl`、`audioUrl`。非法输入在 Provider 提交和新 Task 创建前拒绝；CLI 仍返回 usage 退出码，Command 仍返回 `IRIS_COMMAND_INPUT_INVALID`。工作台清空可选文本框仍由 Host 解释为使用默认值。音频路径与签名地址不落 Core，上传和附件解析仍属于入口；S2V 通过同一输入规范化和按候选上传链提交。
+
+定位、长图 OCR 和媒体摘要通过共享 Model Ports 执行；纯视觉不取得 Core writer，可选转写沿用 Core Task。HTML 通过独立 `media.html` Command 注入 Browser Port 并保存 Artifact，不归入无浏览器的 crop/diff/frames 原语。
+
+## Text/Vision 迁移
+
+[Text/Vision Model Port v0](MODEL_PORT_CONTRACT.md) 固定目标请求、完整结果、错误、取消/预算与 DSH 图片桥接边界。迁移顺序为纯契约/Fake Port → 提示词优化 → look/relook → OCR/定位/拼图摘要，逐个消费者举证。新链逐项修正取消后 fallback、缺终态的部分文字成功和 OCR 吞取消继续分块；旧链测试通过不能算作新契约已通过。
 
-依赖视觉模型或 Host Browser 的 `locate`、长图 OCR、媒体摘要和 HTML 渲染不进入这条本地命令链；它们留到中立 Text/Vision Port 冻结后再迁移，避免把网络模型或浏览器对象塞进 Core。
+M1 已包含纯契约、调用控制与 Fake Port。0.2.1 完成提示词 M2：DSH TextModel Port、共享优化核心、显式规则/确定性输出拼接和泡泡预览。Fake 与 DSH 事件 fixture 复用 conformance，已安装 rc.2 Runtime/WebServer 使用离线源适配器单独验收。v1 配置及公共 export 保持不变，无 Task/Artifact 写入；来源分离不代表模型语义注入防护完全解决。见 [提示词优化系统](PROMPT_OPTIMIZER.md)。
 
-## Text/Vision 下一步（M1 完成，消费者未迁移）
+0.2.1 已实现 HTTP/DSH Vision Port 并接入 Agent/工作台 look/relook 与显式视觉实测。完整终态、候选链总预算、取消停止切换和图片字节桥接分别验收，不写 Core Task/Artifact；允许经核验的 DSH 附件规范化，使用实际 MIME、尺寸和字节数；不匹配或损坏的引用仍在生成前拒绝。见 [单图视觉调用](VISION_MODEL.md)。M4 的 [OCR](OCR_MODEL.md) 与 [定位、拼图摘要及自述](COMPOSITE_VISION.md) 已全部接入同一端口：OCR 普通块失败形成明确部分结果，定位保留原像素 bbox，摘要每次候选发送同一张拼图，并从 Core 转写 Artifact 取正文。legacy 视觉兼容实现仍保留，业务入口不再调用。M5 独立视觉 CLI、显式模型选择、HTML/Browser、S2V 及摘要复用既有 Core 抽帧 Artifact 均已实现。
 
-[Text/Vision Model Port v0](MODEL_PORT_CONTRACT.md) 固定目标请求、完整结果、错误、取消/预算与 DSH 图片桥接边界。后续顺序为纯契约/Fake Port → 提示词优化 → look/relook → 定位/OCR/拼图摘要，逐个消费者举证。取消后 fallback、缺终态的部分文字成功、OCR 吞取消继续分块均列为待修行为，现有测试通过不能算作新契约已通过。
+## CLI 与图片编辑
 
-纯契约、调用控制与 Fake Port 已完成 M1，共用有限调用预算、严格结果验证与取消语义；真实 HTTP/DSH 适配器尚未接入。提示词优化继续讨论主动提示词组装与不可信输入隔离，本轮不迁移该消费者。M1 不增加 Task/Artifact 写入，不修改 v1 配置或公开 export。HTML/Browser、S2V 与自持文本能力目录独立处理；媒体摘要复用 Core 抽帧也需后续单独接线。
+S2V 数字人已迁移到共享 Core Task/Attempt/Artifact，DSH 与 CLI 在每个候选的 Attempt 内上传首帧和音频，受理未知停止切换，观察阶段不重新上传或提交。HTML 工具/action 共用 `media.html` Command；独立 CLI 显式提供 Chromium Browser Port，DSH 仍使用宿主浏览器，均保存 `html-screenshot` Artifact。
+
+图片生成支持模型级 DashScope/Images/聊天/Responses 协议。聊天编辑以 `source_artifact_id` 读取 Core 静态图片，各候选按自己的输入预算准备副本，新 Task 保存来源 ID，新 Artifact 记录 `derived-from`；来源参与删除/清理引用保护，原图不变。来源预检失败不创建 Task，未知受理不自动重提。
+
+账号/模型/分配管理、发现预览与合并、单模型实测、Task 有界等待、查询分页/过滤、显式批量查询/导出、JSON 文件/stdin 以及 Core 可恢复删除/清理均已实现，详见 [CLI 管理与补齐](CLI_MANAGEMENT.md)。提示词优化后续由用户另行安排，本次未扩展。
 
 ## 尚未迁移或开放
 
-- s2v 数字人视频的 Core Command/Task 消费；
-- 依赖 Text/Vision Model Port 或 Host Browser 的 locate、长图 OCR、媒体摘要与 HTML 渲染；
+- Text 的公开独立入口和显式自持文本模型选择；
 - 旧任务、旧作品 ID 与 Core ID 的显式映射；
-- Core Task/Artifact 删除、清理、孤儿 purge 与完整作品分页（提醒处置和人工控制面 reobserve/redeliver/cancel/retry 已开放）；
+- Core 隔离内容的永久 purge（CLI 和工作台的查询、批量操作及可恢复删除/恢复已开放）；
 - 真实 DSH 对话 attachment、浏览器进度/作品区和异步重启 canary。
 
-旧作品重新索引、删除、清空和孤儿清理仍只操作 legacy `outputs/`；Core Task/Artifact 在 DSH 工作台和 Headless CLI 中都保持只读。Doctor 会报告 Core 孤立对象、未提交 Manifest 与未解析条目，但不会删除或修复它们。Core 删除与清理能力计划在 0.2.x 开放；不要手动移动或删除 `core-v0` 中的 object、Manifest、record 或租约文件。
+旧作品重新索引、永久删除、清空和孤儿清理仍只操作 legacy `outputs/`；DSH 工作台已开放 Core 删除预览、可恢复隔离及事务恢复，复用 Headless CLI 的 `core delete/transactions/restore`，引用保护不变，关联任务必须明确选择，不自动级联。详见 [工作台作品管理](WORKBENCH_ARTIFACTS.md) 与 [CLI 管理](CLI_MANAGEMENT.md)。`core restore` 不覆盖原位置冲突。Doctor 会报告 Core 孤立对象、未提交 Manifest 与未解析条目，不删除或修复；永久 purge 留待 0.2.x。不要手动移动或删除 `core-v0` 中的 object、Manifest、record 或租约文件。
 
 ## 验证证据与限制
 
-- 2026-09-30 当前开发工作树已完成仓库外真实 tarball 安装验收：空项目安装当前包和 Sharp，不含 DSH/Cordis，也不复用仓库依赖。安装后的 CLI 实际完成 crop/diff/抽帧和四类 Provider fixture 生成，13 份 Artifact 的导出字节及 SHA-256 一致；跨进程 reader/导出零 Core 写入、零额外 Provider 请求。可在源码仓库执行 `node scripts/verify-headless-package.mjs` 复现，缓存完整时支持 `--offline`。本机为 Linux ARM64/PRoot、Node 22；这项证据不替代真实 Provider、DSH 异步重启或其他平台验收。
-- 完整离线回归为 96 个测试文件，lint 覆盖 151 个 JS/MJS 文件。同步、多产物、混合 failover、受理未知、交付失败、跨进程观察、零 legacy 双写、用户侧只读投影（五类真值表、零写入、局部降级、窄屏断言）与 D1 reobserve、D2 redeliver、D3 cancel、D4 retry（Command 门真值表零网络零写入、幂等矩阵、redelivery 标志、取消三分支如实语义与竞态防护、计费确认三层门、retriedFrom 关系与 prompt 零持久化、失败回落显式收敛、API 状态码/脱敏、CLI↔API 同一 Task 事实连续性、客户端投影门）均有 fixture；E 阶段视频、语音、转写迁移各有独立 conformance（视频长轮询多拍/mp4 Profile、语音同步双产物形态/音频 Profile、转写上传通道/文本物化 Profile）与 CLI/DSH 端到端 fixture。
-- 2026-09-19 最新完整门禁为 113 个测试文件、lint 173 个 JS/MJS 文件；新增证据包括 T-09 七阶段时间戳与旧记录兼容，以及 T-12 本地 diff/抽帧 CLI、Artifact 关系和路径脱敏。上一条 96/151 为早期迁移阶段的历史计数。
+2026-10-09 的实现快照通过 163 个测试文件、263 文件 lint、142 文件打包 dry-run，以及已安装 DSH rc.2 服务 31 项隔离检查。真实网关已验证生成 → Core Artifact → 按 ID 看图，以及来源 Artifact → 聊天编辑 → 新 Artifact；大图和小图分别通过 DSH 工具与工作台入口，原图哈希保持不变。正式版另通过版本一致性、实际 tarball 的源码校验、仓库外安装与跨平台 CI 发布检查；浏览器与重启范围见下文。
+
+以下保留此前工作台第二轮的验收快照，计数与包一致性仅对应当时源码：
+
+2026-10-08 工作台第二轮验收快照：145 个测试文件、240 文件 lint、已安装 DSH 0.2.0-rc.2 的 30 项服务检查全部通过。服务验收使用实际 Runtime/WebServer/附件/注册服务和本地模型 fixture，37 次 fixture 调用、0 外部请求；涵盖作品分页、原 PNG Artifact 看图/OCR、详情/ZIP 下载与同一 Core 隔离/恢复。
+
+同日仓库外无 DSH 安装验收通过 100 条命令、4 类媒体生成和 13 份 Artifact 导出/hash；之后的最终候选包包含 140 个文件，安装到新的空项目，文件与当时源码逐字一致，包内工作台查询/管理/客户端交互及 CLI 入口另验通过。工作台产生的隔离事务可由独立 CLI 恢复，再由 Host 读取相同 digest。以上针对受验源码与 tarball 快照，不表示后续文档更新或新改动已重新打包验证。
+
+用户已有绘图 → 识图 → TTS 的正向试用反馈；PNG/JPEG 排查确认 Core 原 PNG 未改写，DSH 会话附件可能经规范化编码，Core Artifact ID 与会话 attachment ID 用途不同。浏览器/移动端新入口的逐项操作、真实会话的完整操作复验，以及真实异步重启/CLI 接管仍待验。这些待验项不由上述 fixture 或单次试用反馈替代。
+
+以下保留能力范围和早期阶段的历史验证记录；旧测试计数、限流和 tarball 记录均按对应阶段解读。
+
+- 0.2.1 看图、定位和 OCR 已支持 Core 图片 `artifact_id`，CLI 与 DSH 工具/动作共用只读读取器；直接核验原字节/MIME和内容哈希，不导出临时图片、不创建 Task/Artifact，文件路径与定位/OCR 会话附件仍可使用。见 [视觉 CLI](VISION_CLI.md)。
+
+- 0.2.1 CLI 与 DSH Agent/动作的摘要已支持 `frame_artifact_ids`，共用 Core 只读帧读取器，核对哈希、保留时间戳和原帧序号，无需原视频或 ffmpeg，不重抽帧或写入 Core。视频文件模式保留原行为；已有帧消费显式转写文本。见 [视觉 CLI](VISION_CLI.md) 和 [复合视觉调用](COMPOSITE_VISION.md)。
+
+- 2026-09-30 的开发快照已完成仓库外真实 tarball 安装验收：空项目安装当时的包和 Sharp，不含 DSH/Cordis，也不复用仓库依赖。安装后的 CLI 实际完成 crop/diff/抽帧和四类 Provider fixture 生成，13 份 Artifact 的导出字节及 SHA-256 一致；跨进程 reader/导出零 Core 写入、零额外 Provider 请求。可在源码仓库执行 `node scripts/verify-headless-package.mjs` 复现，缓存完整时支持 `--offline`。本机为 Linux ARM64/PRoot、Node 22；这项证据不替代真实 Provider、DSH 异步重启或其他平台验收。
+- 早期迁移阶段的完整离线回归为 96 个测试文件，lint 覆盖 151 个 JS/MJS 文件。同步、多产物、混合 failover、受理未知、交付失败、跨进程观察、零 legacy 双写、用户侧只读投影（五类真值表、零写入、局部降级、窄屏断言）与 D1 reobserve、D2 redeliver、D3 cancel、D4 retry（Command 门真值表零网络零写入、幂等矩阵、redelivery 标志、取消三分支如实语义与竞态防护、计费确认三层门、retriedFrom 关系与 prompt 零持久化、失败回落显式收敛、API 状态码/脱敏、CLI↔API 同一 Task 事实连续性、客户端投影门）均有 fixture；E 阶段视频、语音、转写迁移各有独立 conformance（视频长轮询多拍/mp4 Profile、语音同步双产物形态/音频 Profile、转写上传通道/文本物化 Profile）与 CLI/DSH 端到端 fixture。
+- 2026-09-19 阶段记录的完整门禁为 113 个测试文件、lint 173 个 JS/MJS 文件；新增证据包括 T-09 七阶段时间戳与旧记录兼容，以及 T-12 本地 diff/抽帧 CLI、Artifact 关系和路径脱敏。此处与上一条 96/151 均为历史计数。
 - DSH 异步工具 fixture 实际执行注册后的工具，贯通 submit → poll → download → Core Artifact → attachment；另验证 active 崩溃接管、唯一 Attempt、端点漂移零 poll/零 Task 写入。
 - Headless CLI 与真实 DSH action 已用百炼同步模型完成图片生成，Manifest、同源媒体和 CLI 导出 hash 一致。这些证据不包含真实异步 Provider 或会话附件。
-- 最近一次真实对话验收在进入 Iris 前被 DSH 主模型的 429 限流阻断，未新增 Core Task/Artifact，也未调用媒体 Provider。未改动用户全局模型设置。
-- 早期候选 tarball 已在仓库外、无 DSH 包的临时项目安装并完成 crop/inspect；后续新增代码仍需最终候选重新打包审计。Windows CI 和安卓浏览器目视未以离线测试替代。
+- 此前一次真实对话验收在进入 Iris 前被 DSH 主模型的 429 限流阻断，未新增 Core Task/Artifact，也未调用媒体 Provider。未改动用户全局模型设置；这次阻断记录不代表后来用户试用的状态。
+- 早期候选 tarball 曾在仓库外、无 DSH 包的临时项目安装并完成 crop/inspect；2026-10-08 第二轮另完成上述最终候选包验收。后续新增改动仍按具体候选重新打包审计。Windows CI 和安卓浏览器目视未以离线测试替代。
 
 ## 后续验收
 
+两轮工作台功能实现后，拟把以下实际使用检查列为第三轮：浏览器/移动端作品区、真实对话中的 Core ID 与会话附件链路、隔离 profile 的异步任务重启及 CLI 接管。该安排由后续讨论提出，尚未执行；优先补足已有功能的现场证据，收藏/标签/搜索等新功能另行规划。
+
 Core 任务到工作台进度/提醒的只读安全投影已完成（五类状态、合并任务区、会话内一次性完成提示、损坏/缺媒体局部降级），人工控制面四个动作已全部开放（reobserve/redeliver/cancel/retry，CLI/API/UI 同一 Command Service，retry 三层强制计费确认）。图片、t2v/i2v、TTS、转写以及本地 crop/diff/抽帧已有 Core 执行链；接下来补恢复后真实会话附件、浏览器与异步重启证据，验证停止 DSH 后 CLI 仍可 inspect/observe/export。旧 ID 映射和尚未迁移能力按后续计划单独处理。
 
-发行验证覆盖最终 tarball、无 DSH 安装闭包、Linux/Windows CI 和真实安装的 rc.2 服务隔离检查；这些检查不替代付费 Provider、个人 profile 的停机接管/回退与逐项浏览器验收。上述剩余范围继续跟踪；未验证的宿主版本与 Provider 路径不作为支持声明。
+发布收口需重新验证最终 tarball、无 DSH 安装闭包、候选 Linux/Windows CI 和真实安装的 rc.2 服务隔离检查；这些检查不替代付费 Provider、个人 profile 的停机接管/回退与逐项浏览器验收。上述剩余范围继续跟踪；未验证的宿主版本与 Provider 路径不作为支持声明。

package/docs/DSH_RC2_ADAPTATION.md

@@ -4,6 +4,8 @@
 
 旧 DSH `>=0.1.2-rc.1 <0.1.3-0` 或 `0.1.5-rc.1` 按历史验证范围使用稳定包 `@mokuyoaxis/dsh-iris@0.1.4`。安装与 npm tarball 下载方式见 [README](../README.md#最快开始)。保留的旧桥接与 fixture 测试不构成 Iris 0.2.0 的旧宿主支持承诺。
 
+Iris 0.2.1 沿用相同 Node/DSH 要求，新增 Artifact 改图工具后共注册 15 个工具；最新服务隔离检查为 31 项。宿主适配与业务功能分别验收，浏览器限制见下文。
+
 ## 宿主边界的修正
 
 | 边界 | 问题与修正 |
@@ -27,10 +29,10 @@ node scripts/verify-dsh-host.mjs --dsh-root /absolute/path/to/@deepseek-ai/dsh
 
 脚本在仓库外创建新临时数据根，载入实际安装的 Cordis、加载器兼容检查、附件、工具、Skill、LLM、默认模型、WebServer 与客户端 SlotRegistry。模型使用本地 Fake Adapter，正常流遵循安装包的 `index` 和对象终态格式，并验证真实 Runtime 将异常转换为失败终态；禁止外部请求。会话日志和列表是显式 fixture，宿主进程入口是已核实 DSH bin 的模拟。实际 WebServer 只绑定临时 loopback 端口，退出时卸载所有 Fiber。临时目录与 `report.json` 保留供复核。
 
-它检查 14 个工具、2 项 Skill、Doctor 路由、DSH → Core diff → DSH 附件，以及四个客户端座位的注册和卸载。SlotRegistry 使用安装包中的真实代码，React/DOM 为 stub，因此不证明完整 Web profile 装载、实际组件渲染、点击和草稿写回。另用 `scripts/verify-headless-package.mjs --offline` 验证当前 tarball 在无 DSH/Cordis 安装树中执行 CLI 和 Artifact 导出。
+当前脚本检查 15 个工具、2 项 Skill、Doctor 路由、DSH → Core diff → DSH 附件，以及四个客户端座位的注册和卸载。SlotRegistry 使用安装包中的真实代码，React/DOM 为 stub，因此不证明完整 Web profile 装载、实际组件渲染、点击和草稿写回。另用 `scripts/verify-headless-package.mjs --offline` 验证当前 tarball 在无 DSH/Cordis 安装树中执行 CLI 和 Artifact 导出。
 
 ## 当前限制
 
 真实用户 profile 若禁用 Iris，路由不存在属于预期状态，不据此判定适配失败。启用后仍需实机验证工作台、会话附件选择、提示词预览/写回和媒体展示。验证脚本不自动启用、安装、重载或重启用户插件，也不运行付费探针。
 
-这次修正保留现有 `textModel.stream()` / `visionModel.analyze()` 消费链；没有将真实适配器或业务接入 [Model Port M1](MODEL_PORT_CONTRACT.md)。视觉完整终态、统一输出预算、候选控制和 OCR 取消的进一步收口仍按该契约的后续阶段验收，不能把 rc.2 桥接测试当作迁移完成证据。
+已发布 0.2.0 的 rc.2 修正保留原 `textModel.stream()` / `visionModel.analyze()` 消费链，没有将真实消费者接入 Model Port。0.2.1 已完成提示词 M2、单图视觉 M3、复合视觉 M4 和独立视觉 CLI，见 [Model Port](MODEL_PORT_CONTRACT.md)、[单图视觉调用](VISION_MODEL.md)、[OCR](OCR_MODEL.md) 和 [定位/摘要/自述](COMPOSITE_VISION.md)。安装 rc.2 离线检查覆盖真实 Runtime/Attachments/ToolRuntime/WebServer；2026-10-05 另由真正 `dsh` CLI 加载隔离 profile，原生模型定位、摘要、自述与流式取消七项检查通过。各业务分别验收，不能仅由 rc.2 桥接测试推断完成。

package/docs/FAULT_INJECTION.md

@@ -1,6 +1,6 @@
-# v0.1.3 故障注入矩阵
+# 故障注入矩阵
 
-状态：本矩阵全部使用本地 fixture、Fake Provider、Mock Fetch 或临时目录，不发送真实供应商请求。
+状态：本矩阵使用本地 fixture、Fake Provider、Mock Fetch 或临时目录，不发送真实供应商请求。前表记录 legacy Task v2 的受理与恢复语义；后表补充 Iris 0.2.2 的 Core、图片协议与视觉边界。
 
 | 场景 | 预期事实 | 自动重复提交 | 证据 |
 |---|---|---:|---|
@@ -23,4 +23,23 @@
 | 标为已读/恢复提醒 | 只写本地提醒审计元数据，不改变任务事实 | 0 | `task-manual-recovery-v2.mjs` |
 | 用户知情人工重试 | 独立确认、建立新 Task 关系并归档原提醒 | 明确授权后 1 | `task-manual-recovery-v2.mjs` |
 
+## 0.2.1 新增边界
+
+| 场景 | 预期事实 | 自动重复提交 | 证据 |
+|---|---|---:|---|
+| 短时 429 / 明确额度耗尽 | 前者冷却后恢复候选资格；后者停用至手动实测成功 | 遵守受理证据 | `model-rate-limit.mjs`、`model-rate-limit-async.mjs` |
+| 聊天/Responses 返回 200 但缺图片或缺完整终态 | 记录受理未知，停止候选；不把文字当作图片成功 | 0 | `chat-image-generation.mjs`、`responses-image-generation.mjs` |
+| 大图超发送预算、EXIF 旋转、OCR 分块与定位 | 只转换发送副本，保留来源字节；定位映射回原像素 | 仅有限视觉调用 | `vision-image-input.mjs`、`ocr-locate-image-input.mjs` |
+| Artifact 来源缺失/损坏或编辑失败 | 生成前核验；来源保持原样，已受理未知不重提 | 0 | `chat-image-edit.mjs`、`chat-image-edit-cli.mjs` |
+| Core 删除引用保护、隔离与恢复冲突 | 拒绝删除仍被引用的作品；可恢复隔离，冲突不覆盖 | 0 | `core-deletion-boundary.mjs`、`workbench-management.mjs` |
+
+## 0.2.2 新增边界
+
+| 场景 | 预期事实 | 自动重复提交 | 证据 |
+|---|---|---:|---|
+| writer 创建/释放/恢复在关键操作后强杀、恢复竞争 | 保留完整 owner/恢复证据；陈旧现场仅显式恢复，普通 writer 不抢占 | 0 | `core-lease-interruptions.mjs`、`runtime-recover.mjs` |
+| 16 MiB 视频/音频/文本文件接收或复制失败 | staging 不整文件读取；失败保持远端 succeeded，显式重交付不 submit | 0 | `provider-file-delivery.mjs` |
+| 忠实整理遗漏/重复/调换原文片段、建议或媒体混入 | 协议失败不交付成功预览；建议默认不进入正文，无隐藏第二次调用 | 0 | `prompt-optimizer-boundary.mjs`、`prompt-optimizer-api.mjs`、`prompt-optimizer-client.mjs` |
+| 生图本地尺寸拒绝、DNS/TLS/网络超时、HTTP 200 后正文中断 | 本地校验 not_accepted 且 fetch=0；传输失败 unknown，保留分类/阶段/可用错误码 | 0 | `image-transport-errors.mjs`、`image-task-acceptance-unknown.mjs` |
+
 矩阵的硬性规则是：只要已有 `accepted` 或 `unknown` 事实，任何自动路径的生成提交次数增量必须为 **0**。人工重试不属于自动恢复；它必须由用户逐次确认，并在数据中保留新旧 Task 的关系。