@mokuyoaxis/dsh-iris 0.1.4 → 0.2.1

package/docs/AGENT_QUICKSTART.md

@@ -0,0 +1,39 @@
+# 给 AI Agent 的简要 Prompt
+
+把下面一段交给负责安装或使用 Iris 的 Agent。版本与发布状态以当前 [README](../README.md) 为准；Iris 和 DSH 的版本号独立。
+
+当前安装版本为 Iris 0.2.1。先核对宿主与实际安装版本，再使用新视觉命令或 Artifact 改图；旧宿主仍固定安装 0.1.4。
+
+## 中文
+
+```text
+请根据本仓库 README，帮我安装并使用 Iris（@mokuyoaxis/dsh-iris）。
+先确认运行环境、目标 DSH profile，并用 dsh --version 核对宿主；Iris 0.2.x 要求 Node.js >=22.0.0（旧 npm 0.1.4 的历史要求为 >=20.10.0）：
+- DSH 0.2.0-rc.2：固定安装 dsh plugin --profile web add @mokuyoaxis/dsh-iris@0.2.1。
+- DSH >=0.1.2-rc.1 <0.1.3-0 或 0.1.5-rc.1：固定安装 dsh plugin --profile web add @mokuyoaxis/dsh-iris@0.1.4；只下载用 npm pack @mokuyoaxis/dsh-iris@0.1.4。
+- 其他 DSH 版本：先报告没有支持声明，不自行升级宿主或跳过版本检查。
+没有 DSH、希望用 CLI 时，按 docs/HEADLESS_CLI.md 使用 npm 0.2.1；npm 0.1.4 不含新的 Core 媒体 CLI。
+先用 --help 和 Doctor 核对实际版本与命令。Iris 0.2.1 支持 OpenAI 兼容图片与视觉工作流；其他协议与 music 是后续计划。
+从 dsh-market 安装也要核对实际包名、版本和兼容范围；市场缓存不代表支持旧宿主，不对旧 DSH 安装 latest。
+若使用其他 profile，把示例中的 web 换成已确认的目标。保留完整 scoped 包名，不把 dsh-iris 当作同一 npm 包。
+安装后检查 Doctor 和工具可达性，再执行我指定的媒体任务；不要输出 API Key，重启宿主前说明影响。
+查询、观察和重新取回不等于重新生成；任务已受理或受理未知时，不自动重新提交。
+最后报告所用 Iris/DSH 版本、安装来源和实际验证结果。
+```
+
+## English
+
+```text
+Help me install and use Iris (@mokuyoaxis/dsh-iris) according to this repository's README.
+Check the environment, target DSH profile, and dsh --version first; Iris 0.2.x requires Node.js >=22.0.0 (the published npm 0.1.4 historically requires >=20.10.0):
+- DSH 0.2.0-rc.2: pin dsh plugin --profile web add @mokuyoaxis/dsh-iris@0.2.1.
+- DSH >=0.1.2-rc.1 <0.1.3-0 or 0.1.5-rc.1: pin dsh plugin --profile web add @mokuyoaxis/dsh-iris@0.1.4; download only with npm pack @mokuyoaxis/dsh-iris@0.1.4.
+- Other DSH versions: report the missing support claim; do not upgrade the host or bypass its version checks automatically.
+For CLI use without DSH, follow docs/HEADLESS_CLI.md using npm 0.2.1; npm 0.1.4 does not include the new Core media CLI.
+Check --help, Doctor and the actual installed version before using commands. Iris 0.2.1 supports the OpenAI-compatible image and vision workflow; additional protocols and music remain future work.
+For dsh-market, check the actual package name, version, and compatibility range too. Cached listings do not establish older-host support; do not install latest on an old DSH host.
+Replace web with the confirmed profile when needed. Keep the scoped package name; unscoped dsh-iris is a different npm package.
+Check Doctor and tool availability after installation, then carry out my requested media task. Do not expose API keys; explain the impact before restarting the host.
+Inspect, observe, and redeliver do not create a new generation. Never resubmit automatically after accepted or unknown acceptance.
+Report the Iris/DSH versions, installation source, and actual validation results.
+```

package/docs/ARCHITECTURE.md

@@ -1,95 +1,118 @@
 # Iris 架构与边界
 
-状态：v0.1.3 已发布实现；v0.1.4 已冻结 Host Adapter v0 契约，提供 test-only Local Host consumer，完成 DSH Adapter 消费者迁移与真实 DSH 隔离 canary，并实现 Provider Adapter v0 完整生命周期与 Host Doctor。
+状态：本文面向 **Iris 0.2.1**。0.2.0 建立实例化 Core Runtime、Headless CLI、共享 Provider 生命周期与 Task/Artifact 事实；0.2.1 补共享视觉、模型级图片协议、Artifact 编辑及维护入口。DSH 插件仅支持 `0.2.0-rc.2`，Node.js 最低为 22.0.0；旧宿主固定使用 npm `0.1.4`。Core 内部 API 尚未冻结为公共 SDK。
 
 ## 当前形态
 
-Iris 目前以 DeepSeek Harness 插件运行。DSH 提供 Agent 工具注册、会话附件、浏览器和 Web UI 插槽；Iris 自己负责供应商配置、媒体动作、可信任务、产物落盘、媒体授权路由和工作台投影。
+Iris 仍以一个 npm 包交付，但已有两个执行入口：DSH 插件负责 Agent 工具、会话附件、浏览器、Web UI 和后台观察；Headless CLI 在没有 DSH/Cordis 的进程中显式接收数据根与私有 Provider 配置。两者共用 Core Runtime、Provider Task Runner、Task/Artifact Store 和本地 Command，不能在同一数据根上同时充当写者。
 
 ```text
-DSH Host / Cordis
-  ├─ Agent tools ───────────────┐
-  ├─ Web slots / browser        │
-  └─ attachment/session ports   │
-                                ▼
-                    dsh-host-adapter.js
-                    （能力探测 / DTO / 生命周期）
-                                │ Host Adapter v0
-                                ▼
-                         actions.runAction
-                         ├─ provider adapters
-                         ├─ Task / Attempt v2
-                         ├─ media delivery
-                         └─ vision / local media tools
-                                │
-                                ▼
-                     $DSH_HOME/iris/v1
-                     providers.json · tasks.json
-                     artifacts.json · outputs/ · uploads/
+DSH Host / Cordis                         Headless CLI
+  ├─ Agent tools / Web UI                   ├─ explicit --data-root
+  ├─ attachment / browser ports             └─ private provider config
+  └─ bounded observation timers                       │
+               │                                      │
+     dsh-host-adapter.js                    bin/dsh-iris.js
+               │                                      │
+       dsh-core-adapter.js ────────────────┬───────────┘
+                                           ▼
+                                  Core Runtime v0
+                           explicit root · reader/writer
+                           lease · AbortSignal · disposal
+                              ┌────────────┴────────────┐
+                              ▼                         ▼
+                    Command Service v0          Provider Task Runner
+                    crop / diff / frames / html submit / observe /
+                    inspect / control           cancel / delivery
+                              └────────────┬────────────┘
+                                           ▼
+                         Core Task Store + Artifact Manifest
+                         records · objects · SHA-256 · index
+                                           │
+                    DSH: $DSH_HOME/iris/v1/core-v0
+                    CLI: explicit absolute data root
 ```
 
-`lib/index.js` 是 DSH 插件入口，`lib/dsh-host-adapter.js` 是服务端 DSH/Cordis 对象进入 Iris 的唯一映射边界；`lib/client.js` 内部用最小 client slot adapter 隔离 DSH UI Slot。`lib/api.js` 是工作台 HTTP 投影，不是真相来源。Task 的持久事实由 `lib/tasks.js` 管理。
+`lib/index.js` 是 DSH 插件装配入口，`lib/dsh-host-adapter.js` 是原始 DSH/Cordis 对象进入 Iris 的服务端边界；`lib/dsh-core-adapter.js` 只负责选择 DSH profile 的 Core 数据根、恢复 Provider 配置和投影 Host DTO。`bin/dsh-iris.js` 不启动 DSH，也不推断 profile。`lib/api.js` 与 `lib/client.js` 是 Host 投影，不是真相来源。
 
-## 已稳定的核心候选
+0.2.1的 S2V 使用 Core Task/Attempt，HTML 使用 `media.html` 与显式 Browser Port；视觉和提示词预览通过共享 Model Ports 执行。纯视觉不创建 Task/Artifact，摘要主动转写仍使用 Core 任务。聊天改图属于媒体生成链，按来源 Artifact ID 创建新 Task 和关联产物。
+
+## 共享核心
 
 | 模块 | 职责 | DSH 运行时依赖 |
 |---|---|---:|
-| `task-semantics.js` | Task v2 枚举、旧状态与用户状态派生、自洽校验 | 无 |
-| `provider-contract.js` | 提交结果、受理边界、错误脱敏、候选调度 | 无 |
-| `provider-adapter.js` | Provider v0 生命周期、canonical 结果与统一调用边界 | 无 |
-| `provider-adapters.js` | DashScope / OpenAI Images 协议到 v0 的映射 | 无 |
-| `tasks.js` | Task/Attempt 持久化、观察、恢复与交付状态 | 无；数据根仍沿用 `DSH_HOME` |
-| `artifacts.js` | 作品库 v0 的最小索引、分页、重建、删除与独立媒体授权 | 无；数据根仍沿用 `DSH_HOME` |
-| `doctor.js` | 共用诊断结果模型；离线检查环境/数据，Host 模式检查安全能力快照与注册证据 | 无 |
-| `host-runtime.js` | 服务端成功注册账本与受限浏览器握手；不保存 live object | 无 |
-| `actions.js` | GUI 与 Agent 共用动作 | 只接收 Host Adapter；部分动作声明 Browser/会话端口 |
-| `dsh-host-adapter.js` | DSH capability detection、DTO 与生命周期映射 | 有；唯一服务端 DSH 运行时映射边界 |
-| `index.js` | DSH 工具、路由、Skill 与生命周期注册 | 有 |
-| `client.js` | DSH Web Slot、工作台、泡泡和提示词入口 | 有 |
-
-0.1.3 没有完整独立 Core 或 Local Host Adapter。0.1.4 先冻结并验证最小 Host Port、Local Host fixture 和 DSH capability detection；完整 Command Service 与非 DSH Provider 执行入口仍属于 0.2.0。
+| `core-contract.js` / `core-runtime.js` | 显式数据根、reader/writer 权限、单写者租约、取消与释放 | 无 |
+| `command-service.js` | 本地媒体命令、Task 控制面和 Artifact 查询/导出 | 无 |
+| `generation-input.js` | CLI、DSH 与重试共用的生成参数校验和 Provider 字段转换 | 无 |
+| `model-port-contract.js` / `model-invoker.js` | Text/Vision 内部契约、有限调用预算与取消 | 无 |
+| `core-tasks.js` | Core Task/Attempt 持久事实、受理与交付状态 | 无 |
+| `core-artifacts.js` / `core-artifact-store.js` | 对象、Manifest、SHA-256、关系边与可重建 Index | 无 |
+| `provider-contract.js` / `provider-adapter.js` | canonical 结果、错误脱敏、受理边界与 Provider v0 操作 | 无 |
+| `provider-adapters.js` | DashScope / Images / 聊天 / Responses 图片协议和可选输入准备 | 无 |
+| `vision-image-input.js` / `image-edit-input.js` | 视觉发送副本与聊天改图来源预检；Core 原图保持不变 | 无 |
+| `provider-task-runner.js` | 写前 Attempt、submit/poll/cancel/download 与 Profile 化交付 | 无 |
+| `core-doctor.js` / `core-lease-recovery.js` | 只读完整性诊断与需显式确认的陈旧租约恢复 | 无 |
+| `provider-catalog.js` | 显式 Provider 配置、能力候选和原 Task Adapter 恢复 | 无 |
+| `dsh-core-adapter.js` | DSH 数据根、后台观察与 Core 到 Host 的投影 | 有；DSH 专属边界 |
+| `dsh-host-adapter.js` / `index.js` | Host 能力映射、工具/路由/Skill 与生命周期装配 | 有 |
+| `client.js` | DSH Web Slot、统一任务/作品区、泡泡和提示词入口 | 有 |
+
+完整规则见 [Core Runtime v0](CORE_RUNTIME_CONTRACT.md)、[Artifact Manifest v0](ARTIFACT_MANIFEST.md)、[Provider Adapter v0](PROVIDER_ADAPTER_CONTRACT.md) 与 [DSH → Core 渐进迁移](DSH_CORE_MIGRATION.md)。这些仍是内部契约，不是第三方 SDK 兼容承诺。
 
 ## Task、Attempt 与 Artifact
 
-- 一个用户意图对应一个 Task；每个候选供应商调用对应一个稳定 Attempt。
-- Attempt 必须在可能发送计费请求前落盘。只有明确 `not_accepted` 才允许自动 failover。
-- 生成结果与本地交付是两类事实。生成成功后下载失败仍保持 `outcome=succeeded`。
-- 0.1.4 增加独立作品库 v0：`artifacts.json` 只保存文件、类型、大小、时间和随机令牌，因此清任务历史后仍可浏览作品；它不保存 Prompt、Provider、Model 或任务关系。
-- 正式 Artifact Manifest、内容哈希、谱系、收藏、标签和搜索仍属于 0.2.0+；作品库 v0 不是该公共契约。
-- 每次 v2 任务变更递增 Task `revision`；完整状态快照另带进程 `stateEpoch/stateRevision`，客户端拒绝同一 epoch 中迟到的旧快照。
+- 一个用户意图对应一个 Core Task；每次候选供应商调用对应一个稳定 Attempt。Attempt 必须在可能发送计费请求前落盘。
+- 只有明确 `not_accepted` 才允许自动切换候选；`accepted` 或 `unknown` 后禁止自动重提。重试会创建新 Task，并要求用户再次提供未持久化的输入和明确确认潜在费用。
+- 生成结果与本地交付是两类事实。远端成功后下载失败仍保持 `outcome=succeeded / deliveryState=failed`，可显式重新交付而不重新生成。
+- 新 Attempt 可选保存阶段时间戳与模型选择来源；旧记录缺少这些字段仍可读取。
+- Artifact Manifest v0 保存内容哈希、媒体类型、中性元数据和关系边；不保存 Prompt、API Key、签名 URL、Provider 端点或宿主绝对路径。
+- Core/CLI 已提供默认只读预览、明确选择与确认、文件隔离和恢复的删除/清理 Command，保护活跃 Task 和引用；索引更新只使用已提交记录，不升级或接回孤儿。DSH 作品区共用删除预览、隔离与事务恢复，永久 purge 未开放。Doctor 只报告，不自动修复。见 [CLI 管理与补齐](CLI_MANAGEMENT.md)。
 
-详细状态机见 [Task/Attempt v2 语义契约](TASK_SEMANTICS.md)，故障证据见 [故障注入矩阵](FAULT_INJECTION.md)。
+0.1.4 的 `tasks.json`、`artifacts.json`、`outputs/` 与上传目录继续作为 legacy 数据存在；Core 使用隔离的 `core-v0`。已迁移的新图片、视频、S2V、TTS 与转写任务不双写 legacy，回退到 0.1.4 时也不删除或改写 Core 数据。
 
 ## Provider 边界
 
-0.1.4 已实现内部 Provider Adapter v0：`provider-adapter.js` 固定 discovery、submit、poll、cancel、download 与 error mapping 六类操作和 canonical 结果；`provider-adapters.js` 将 DashScope 与 OpenAI Images 映射到契约；`adapters.js` 只保留注入式低层 HTTP transport。动作、恢复、重新交付、模型发现与能力探测不再直接绕过该生命周期边界。
+Provider Adapter v0 固定 discovery、submit、poll、cancel、download 与 error mapping 六类生命周期操作；提交前的临时输入上传是可选准备能力，不自动成为 Core 事实。协议实现只接收显式凭据、模型和媒体端点，Core 保存复合模型身份与非敏感 binding，不保存端点原文。
+
+Core Runner 不拥有后台 timer。Headless `task observe` 每次最多 poll 一次，`task wait` 仅在本次命令内有界观察；DSH 的有界自动观察属于 Host，插件释放时停止 timer 并中止在途观察，但不会把“停止本地观察”写成“远端已取消”。端点或协议 binding 漂移时恢复在联网前拒绝。
+
+每个操作必须明确声明 supported 或 unsupported。当前 DashScope 与 OpenAI Images 媒体协议没有经过验证的远端取消实现，因此取消请求如实返回 not-supported，而不是伪造 canceled。完整受理与错误规则见 [Provider 提交契约 v0](PROVIDER_SUBMISSION_CONTRACT.md)。
+
+## Text/Vision 共享边界
+
+[Text/Vision Model Port v0](MODEL_PORT_CONTRACT.md) 的纯契约、调用控制与 test-only Fake Port 已发布于 0.2.0。它以 `describe()` 和单轮 `complete()` 统一文本/视觉输入、正常终态、预算、取消与安全错误；图片以字节和 MIME 进入共享层，模型选择、会话与附件桥接保留在入口/适配器。
+
+0.2.1通过 `prompt-optimizer-core.js` → `model-invoker.js` → `dsh-text-model-adapter.js` 接入首个提示词消费者；`prompt-optimizer.js` 继续拥有 v1 配置、模型选择、reasoning 策略和 Host 投影。共享核心不读取 Host/配置/Store，不取得 writer，也不创建媒体 Task/Attempt/Artifact。规则与预览见 [提示词优化系统](PROMPT_OPTIMIZER.md)。
+
+单图视觉将 Agent/工作台 look/relook 和显式视觉实测接入 `vision-core.js` 与 HTTP/DSH Vision Port：共享 120 秒整体预算、完整终态与候选策略，图片桥接核验原图与实际附件，接受合法宿主规范化。DSH 附件保存属于宿主副作用，不是 Core Artifact；rc.2 保存不可取消的限制如实保留。见 [单图视觉调用](VISION_MODEL.md)。视觉 CLI 复用这些业务；可选 `visionInput` 在入口层控制发送副本。未新增公共 SDK export，自持文本目录和独立提示词入口另行安排。
 
-每个操作必须明确声明 supported 或 unsupported。DashScope 的远端 cancel 尚无经过验证的实现，OpenAI Images 的同步路径没有 poll/cancel，它们均以能力事实公开，而不是在运行时以“方法不存在”失败。完整规则见 [Provider Adapter v0 生命周期契约](PROVIDER_ADAPTER_CONTRACT.md)，四态受理规则见 [Provider 提交契约 v0](PROVIDER_SUBMISSION_CONTRACT.md)。
+OCR 切片通过 `ocr-model-routing.js` 在入口解引用前建立整体 operation，`ocr.js` 仅接收图片字节和模型端口，使用现有 Sharp 做有限分块；全部块复用 `completeVision`，没有每块重置计时或调用额度。普通块失败可以产生明确部分结果，取消/超时终止整次操作；不取得 Core writer 或写入 Task/Artifact。见 [长图 OCR](OCR_MODEL.md)。
 
-Provider 健康事实位于配置层，以 Provider × Model × Capability 为键保存最近成功、决定性认证失败和临时观察。动作层只在真实 Provider 生命周期结果或显式探针后写入；API 投影按当前 failover 候选汇总，客户端只渲染快照，不自行猜测可用性。成功与明确认证失败的有效窗口均为 7 天；429、网络、5xx、内容安全、取消和 unknown 不会推翻窗口内成功。详见 [Provider 与能力健康状态](PROVIDER_HEALTH.md)。
+定位、拼图摘要与生成后自述复用 `runVisionOperation`，`locate.js` / `summarize.js` 消费共享端口；入口处理附件、抽帧和可选 Core 转写，摘要读取已成功转写的文本 Artifact。纯视觉业务不写 Task/Artifact。legacy 视觉兼容实现保留，现有入口不再调用。见 [复合视觉调用](COMPOSITE_VISION.md)。
 
-## Host Port 清单
+## Host Port 与 Headless 边界
 
-| 能力 | 当前来源 | 缺失时行为 |
+| 能力 | DSH 来源 | 缺失或 Headless 时行为 |
 |---|---|---|
-| 工具注册与 Fiber 生命周期 | DSH `ctx.tools` / `ctx.effect` | 对应工具不注册；其余能力继续装载 |
-| Web 路由 | DSH `webServer` 或 `httpServer` | 工作台 API、媒体链接和 HTML 渲染不可用 |
-| UI Slot | DSH Web Client | 不影响 Host 侧任务与离线 Doctor |
-| Browser | DSH browser service | 仅 HTML 截图不可用 |
-| 会话附件与输入草稿 | DSH session/input ports | 退化为 Iris 自有产物或浏览器上传 |
-| Skills registry | DSH skills service | 随包 Skill 不自动注册；核心动作仍可用 |
+| 工具注册与 Fiber 生命周期 | `ctx.tools` / `ctx.effect` | 不注册 DSH 工具；CLI/Core 不受影响 |
+| Web 路由 | `webServer` 或 `httpServer` | 无工作台 API 和同源媒体路由；CLI 直接导出 Artifact |
+| UI Slot | DSH Web Client | 不影响 Core Task、Artifact 与离线 Doctor |
+| Browser | DSH browser service | CLI 可显式提供独立 Chromium Browser Port；未提供时 HTML 不可用 |
+| 会话附件与输入草稿 | session/input ports | CLI 使用显式文件或 JSON 输入，不创建会话对象 |
+| Skills registry | DSH skills service | 随包 Skill 不自动注册；CLI/Core 仍可用 |
 
-这些依赖由 `dsh-host-adapter.js` 映射为命名端口，`index.js` 只负责 DSH 插件装配和生命周期入口；客户端 Slot 探测留在 client bundle 的最小 adapter 内。Command、API、提示词优化和视觉后端不接收原始 `ctx`。test-only Local Host fixture 使用同一契约验证无 DSH 降级，但不等同于独立宿主。
+Command、Core Store、Provider Runner 和 Headless CLI 不接收原始 `ctx`、会话对象或 Browser 对象。Host URL、attachment 与 UI 文案只在 DSH 投影层产生。
 
-## 事件与 UI
+## 事件、UI 与媒体读取
 
-Host Doctor 通过已认证的 `/iris/api/doctor` 返回能力和装载证据；客户端只在 Slot 回调实际执行后向 `/iris/api/host-client` 回报插件版本、协议号和 Slot 名称。诊断不调用端口、Browser、模型或 Provider，详见 [Host Doctor](HOST_DOCTOR.md)。
+DSH 工作台把 Core 与 legacy Task 合并到一个用户任务区，把 Core 与旧 `outputs/` 的图片、视频、音频和文本合并到一个作品区。普通投影只有五类用户状态；原始 Attempt 事实留在高级诊断。刷新、展开、关闭、读取作品和查询状态都不得触发 submit、poll 或隐式修复。
 
-任务、配置和作品索引写入会触发节流 SSE 快照。每份快照都有进程 epoch 与单调序号；慢消费者进入背压后只保留最新快照，重连仍通过持久化全量状态收敛。工作台只展示稳定人类状态，内部事实轴保留在 API 详情中供诊断和人工动作判断。
+Core 媒体路由按随机 Artifact ID 读取并逐次验证 SHA-256；它没有独立 token。浏览器请求还受可信 Host、`Origin`/`Sec-Fetch-Site` 和 `Referrer-Policy: no-referrer` 约束。Artifact ID 是持有者标识，不等于多租户认证；Iris 与 DSH 仍处于同一本机信任域。
 
-## 非目标
+## 非目标与发布边界
 
-- 不在 0.1.4 启动独立常驻服务或复制 DSH 聊天界面。
-- 不迁移到 SQLite/JSONL，不破坏旧任务读取。
-- 0.1.4 不新增 Gemini、Fal 或 Replicate 分支；Provider conformance 完成后仍保持版本范围。
-- 不把离线 Doctor 的成功等同于 DSH Host、浏览器或真实供应商已可用。
+- `0.2.1` 不启动独立常驻服务，也不复制 DSH 聊天界面。
+- 不迁移到 SQLite/JSONL，不原地改写 0.1.4 数据，不自动接管不确定的写者租约。
+- 0.2.1 未新增原生 Gemini、Fal、Replicate 或本地模型协议；注册表只是后续接入点。
+- 不把离线测试、一次 canary 或 Headless 可运行等同于公开 Core API 已冻结。
+- 发布检查覆盖版本元数据、实际包审计、仓库外安装与跨平台 CI；浏览器/移动端和真实异步重启范围单独记录，不由程序化检查推定通过。

package/docs/ARTIFACT_LIBRARY.md

@@ -1,12 +1,12 @@
-# Iris 作品库 v0
+# Iris legacy 作品库 v0
 
-状态：v0.1.4 候选实现。
+状态：自 v0.1.4 实现，Iris 0.2.1 保留兼容。本文只描述旧 `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

@@ -0,0 +1,60 @@
+# Artifact Manifest v0
+
+Artifact Manifest v0 自 Iris 0.2.0 引入，0.2.1 沿用同一内部格式，尚未作为公开 package API 冻结。它不替换 0.1.4 的 `outputs/` 与 `artifacts.json`；后续 Host 迁移只能显式、逐件复制旧作品，失败时保留原文件。
+
+## 存储与提交顺序
+
+```text
+artifact-store/v0/
+├── objects/<artifact-id>.<ext>
+├── manifests/<artifact-id>.json
+├── records/<artifact-id>.json
+└── index.json
+```
+
+写入顺序固定为 `object → manifest → record → index`：
+
+- object 是受控媒体内容；
+- manifest 保存 SHA-256、媒体类型、大小、中性元数据和关系边；
+- record 是最小提交标记。只有 record、manifest 与 object 一致的 Artifact 才属于已提交事实；
+- index 只是分页查询缓存。它可以损坏或丢失，不影响按稳定 ID 检查已提交 Artifact。
+
+Index 更新失败不会撤销已经提交的 Artifact，避免调用方因本地缓存错误重新生成或重复付费。显式 `artifact rebuild` 会从提交记录和旁车 Manifest 重建 Index。
+
+## 内容完整性
+
+Manifest 使用小写十六进制 SHA-256，并同时记录字节数。`inspect`、`export`、`list` 和重建都会核验对象；即使文件大小不变，内容被替换也返回 `IRIS_ARTIFACT_DIGEST_MISMATCH`。
+
+哈希通过固定大小分块读取，不把完整视频再次载入内存。Manifest、错误和 CLI 结果不保存输入路径、旧作品文件名、DSH URL 或供应商下载 URL。
+
+## 关系边
+
+关系方向固定为“当前 Artifact 指向既有 Artifact”。v0 支持：
+
+- `derived-from`
+- `preview-of`
+- `frame-of`
+- `transcript-of`
+- `audio-for`
+
+创建时目标必须已经存在且通过完整性检查，重复边会被拒绝。目标后续丢失时，来源 Artifact 仍保持可用；重建报告 `danglingRelations`，不会级联删除或猜测修复关系。
+
+## 重建与孤儿
+
+`rebuildCoreArtifactIndex()` 属于 writer 的显式 `recover` 操作，reader 不会偷偷修复：
+
+- 早期 Core v0 单文件记录：计算真实哈希，生成 Manifest，并将 record 升级为提交标记；
+- object + manifest、缺 record：验证后补写提交标记；
+- 只有命名和媒体扩展合法的 object：计算哈希，以 `kind=recovered`、`metadata.recovered=true` 补全；
+- manifest 缺 object、哈希不匹配、结构损坏或未知文件：不进入 Index、不自动删除，只计入 `invalid` 或 `unresolved`。
+
+原子写入过程中遗留的临时文件也属于 unresolved 现场。自动清理和数据删除需要单独的用户授权，不属于 rebuild。
+
+`adoptCoreArtifactFile()` 用于后续渐进接回 0.1.4 作品：来源必须是明确的普通文件，Core 复制内容并计算哈希，既不移动来源，也不在 Manifest 中保存来源路径。批量扫描和旧 ID 映射留给 DSH 消费迁移阶段。
+
+## 当前限制
+
+- Manifest 和 record 格式仍是内部候选，版本发布前可能调整；
+- 当前没有删除、去重、垃圾回收或关系编辑 API；
+- 进程崩溃窗口已通过 fixture 验证；突然断电后的持久性仍取决于宿主文件系统，v0 不宣称跨文件系统事务或 `fsync` 级保证；
+- Android 共享存储、网络文件系统和原生 Windows 的恢复行为仍需各自的真实验证。

package/docs/CLI_MANAGEMENT.md

@@ -0,0 +1,181 @@
+# CLI 配置与任务管理
+
+本文面向 Iris 0.2.1，沿用 `dsh-iris` 入口，无需启动 DSH，未新增生产依赖。安装 `npm install @mokuyoaxis/dsh-iris@0.2.1` 后运行 `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`。真实请求只由显式执行生成、发现、实测或观察命令触发。
+
+## 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.1**。长图分块另见 [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。