@mokuyoaxis/dsh-iris 0.1.4 → 0.2.0

package/CHANGELOG.md

@@ -4,6 +4,58 @@
 
 ## [Unreleased]
 
+暂无。
+
+## [0.2.0] - 2026-10-01
+
+Iris 0.2.0 要求 Node.js ≥ 22.0.0，DSH 插件仅支持 `0.2.0-rc.2`；旧宿主继续固定安装 `@mokuyoaxis/dsh-iris@0.1.4`。包名与仓库名保留，第二个真实 Host Adapter 完成后再更名。
+
+### Added
+
+- 增加中英文 [Agent 简要 Prompt](docs/AGENT_QUICKSTART.md)，按宿主版本选择固定 npm 0.2.0 或 0.1.4，并明确 CLI、profile 与任务观察的使用边界。
+- 增加 [Text/Vision Model Port v0 内部契约](docs/MODEL_PORT_CONTRACT.md)，约定共享输入、完整终态、取消/预算、安全错误与逐项迁移门禁；真实 DSH/CLI 消费者尚未切换。
+- 实现 Text/Vision M1 纯契约与调用控制，包含单次/整体预算、显式候选策略、取消与晚到结果处理，并补 test-only Fake Port 和共用离线 conformance；真实适配器、提示词优化及视觉消费者尚未接入，未新增公开 export。
+- 增加像素块几何母题的 IRIS 标志与图形标（彩色/单色/反白共 6 个 SVG），由 `scripts/gen-logo.mjs` 从设计矩阵可复现生成，含最小尺寸、留白与配色规范（`docs/assets/logo/`）；初始泡泡采用同源内联像素图形标，后续曲线替换见下方 Changed；0.1.x 渐变临时字标不再使用，源码文件暂留作历史兼容。
+- 增加 Core 任务的注意力处置（Host 偏好式，与 legacy 体验对齐）：工作台 attention 行（失败/取回失败/受理未知）提供「不再提醒」与「移除」，已受理行提供「恢复提醒」，高级诊断保留完整记录并标注处置状态、可「恢复显示」。处置存于 `$DSH_HOME/iris/v1/core-attention.json`（0600、原子写、损坏降级为无偏好），**零 Core 写入**——任务与产物记录绝不删除。重试成功自动静默：若某 attention 任务存在 `retriedFrom` 指向它的后继且后者已成功交付，则旧任务从任务区自动静默（纯事实派生，刷新不回归；后继后续失败则静默随之撤销）。CLI 无提醒概念，不受影响。
+
+- 发布 Headless CLI：无需加载 DSH 即可执行本地裁剪、图片 diff、视频抽帧及图片/视频/语音/转写任务，并跨进程观察任务、检查和导出 Artifact。
+- Headless CLI 增加只读的 `providers list`、`capabilities list` 与显式数据根 Core Doctor；异常退出后可经 Doctor 核对并回显陈旧 owner PID，使用 `runtime recover` 写私有审计后释放租约。活跃或证据不完整时拒绝恢复，不自动解锁。
+- 增加实例化 Core Runtime，提供显式数据根、单写者租约、reader、取消和有序释放。
+
+### Changed
+
+- 0.2.0 的 Node.js 最低要求统一为 22.0.0，npm 元数据、Doctor、README、用户指南与 CI 同步。Node 22 已包含上游退出阶段 FinalizationRegistry 无限循环修复（nodejs/node#51290）；补充确定性退出回归及最低版本重复退出验证，移除临时 GDB 取证步骤。已发布 0.1.4 的历史要求不变。
+- 0.2.0 的 DSH engines、五项可选客户端 peers 和 Host Doctor 收敛到准确的 `0.2.0-rc.2`，不再声明旧 DSH 支持；已发布 Iris 0.1.4 的历史范围不变，README 和用户指南补充 `@mokuyoaxis/dsh-iris@0.1.4` 固定安装与 npm tarball 下载方式。
+- 悬浮泡泡以曲线鸢尾花 SVG 替换像素块剪影，采用紫色花瓣、金色花心与青绿叶片；提供透明矢量源和按钮概念预览，保留现有健康状态与交互。
+- 适配 DSH `0.2.0-rc.2`，通过真实安装服务隔离验收；未推定其他 0.2 版本兼容，已发布 npm 0.1.4 包不包含这些后续修改。验证范围见 [rc.2 适配说明](docs/DSH_RC2_ADAPTATION.md)。
+- CLI、DSH 与知情重试共用四类生成的参数规范化：文本修剪、图片数量、视频时长及 size/voice 长度使用同一规则，非法参数在提交前拒绝。DSH 的 diff/抽帧工具和工作台动作消费已有 Core Command，结果保存为 Artifact 并可经 CLI 导出；宿主继续负责附件展示。
+- 协议工厂改用内部注册表；媒体协议与视觉类型分别处理。导入和重载保留用户显式配置，未知协议在联网前返回稳定错误；未知端点的自动 OpenAI Images 兼容回退带 `protocolInferred` 标记，并在供应商管理区提示确认。
+- CLI 与 DSH 共用配置模型解析，均接受裸模型名与供应商复合引用；运行时不再注入厂商默认模型。旧裸账号的兼容目录改为在配置写入时物化，CLI 读取不迁移配置；显式空模型池仍保持为空。
+- 模型发现改为合并更新：手工项优先、保留远端未再返回的旧项、按 ID 去重，编辑已有模型也会标记为手工配置。
+- CLI 与 DSH 的供应商可用性及旧分配对象解析共用规则：未声明 `enabled` 时默认启用，缺少端点或必要凭据时不进入候选链；旧 `{providerId, id}` 分配格式在两入口一致生效。
+- 临时文件上传统一经过 Provider Adapter 的可选 `prepareInput` 能力；DashScope 由协议闭包持有凭据与端点，OpenAI Images 在上传前明确拒绝。上传错误统一脱敏为未受理分类，但 Core 转写的准备失败不伪造已落盘的 Task/Attempt。
+
+- 精简 README、路线图和 Core/Host 契约，把版本施工记录留在 CHANGELOG 与验收文档。
+- DSH 继续加载同一个 npm 插件入口；Core 与 Host Adapter 分离，不引入额外 daemon。
+- 阿里云百炼支持独立 Workspace `mediaBaseUrl`、官方模型目录分页与能力元数据；模型池保持有序安全 failover，并保护用户手工能力覆盖。
+
+### Fixed
+
+- 修复 Model Port 使用超大合法 timeout 时，deadline 浮点舍入放大剩余预算而导致端口误判为非法输入的问题；剩余预算不超过原始输入，并补确定性边界回归。
+- 修复 DSH 会话附件扫描丢失字节数和尺寸导致真实 `readImage()` 完整性检查失败；rc.2 默认视觉候选明确绑定 Provider/模型并先确认图片能力；客户端支持主视图持有者和无参数快照通知，并随插件卸载释放会话订阅。
+- 修复 Core 知情重试直接透传外部字段的问题：转写的 `audio_url` 和图生视频的 `img_data_url` 现在分别转换为 Adapter 所需字段，保留重新提供的音频地址与首帧；未知参数不会静默丢弃。
+- 关闭 Runtime 时，已接纳的操作会先收到取消信号并完成收束，避免操作尚未建立上下文就被释放。
+- Artifact 导出不覆盖已有文件，检查会拒绝缺失或大小不一致的对象。
+- CLI 对可捕获的 SIGINT/SIGTERM 会中止在途请求并释放写者租约；`auth:'none'` 的媒体请求不再发送空的 Bearer 头或沿用旧 Key，缺省 bearer 配置仍要求 Key。
+- 修复显式租约恢复在中途 I/O 失败时引用未定义状态变量的问题；失败仍返回稳定的恢复错误码，并尽力保留原租约与审计证据。
+
+- 明确 0.2.0 的 Core 生命周期末端边界：DSH 工作台现有删除、清空与孤儿清理只作用于 legacy `outputs/`，DSH 与 Headless CLI 都不删除 Core Task/Artifact；Doctor 只报告孤立对象、未提交 Manifest 和未解析条目。Core 删除与清理继续列入 0.2.x，不建议手工改动 `core-v0`。
+
+### Security
+
+- 同一物理数据根只允许一个 writer；reader 不创建、修复或迁移数据。
+- Headless Command 结果和错误不返回输入文件或数据根的绝对路径。
+
 ## [0.1.4] - 2026-09-10
 
 ### Added
@@ -171,7 +223,8 @@
 - 上传采用流式限额、临时 `.part` 文件和原子落盘，失败时会清理未完成文件。
 - 修改状态的路由拒绝明确的跨站请求，媒体文件继续使用随机能力令牌访问。
 
-[Unreleased]: https://github.com/mokuyoaxis/dsh-iris/compare/v0.1.4...HEAD
+[Unreleased]: https://github.com/mokuyoaxis/dsh-iris/compare/v0.2.0...HEAD
+[0.2.0]: https://github.com/mokuyoaxis/dsh-iris/compare/v0.1.4...v0.2.0
 [0.1.4]: https://github.com/mokuyoaxis/dsh-iris/compare/v0.1.3...v0.1.4
 [0.1.3]: https://github.com/mokuyoaxis/dsh-iris/compare/v0.1.2...v0.1.3
 [0.1.2]: https://github.com/mokuyoaxis/dsh-iris/compare/v0.1.1...v0.1.2

package/README.en.md

@@ -3,7 +3,7 @@
 </p>
 
 <p align="center">
-  <img src="docs/assets/iris-wordmark.svg" width="520" alt="IRIS wordmark">
+  <img src="docs/assets/logo/iris-interim-flower.png" width="400" alt="IRIS line-art iris flower (interim logo)">
 </p>
 
 <h1 align="center">Iris Media for DSH</h1>
@@ -13,7 +13,7 @@
 <p align="center">
   <a href="#deepseek-harness-adaptation"><img alt="DeepSeek Harness compatible" src="https://img.shields.io/badge/DeepSeek%20Harness-compatible-4D6BFE.svg?style=flat-square"></a>
   <a href="https://www.npmjs.com/package/@mokuyoaxis/dsh-iris"><img alt="npm version" src="https://img.shields.io/npm/v/%40mokuyoaxis%2Fdsh-iris.svg?style=flat-square"></a>
-  <a href="https://nodejs.org/"><img alt="Node.js 20.10 or newer" src="https://img.shields.io/badge/Node.js-%3E%3D20.10-339933.svg?style=flat-square&amp;logo=nodedotjs&amp;logoColor=white"></a>
+  <a href="https://nodejs.org/"><img alt="Node.js 22 or newer" src="https://img.shields.io/badge/Node.js-%3E%3D22-339933.svg?style=flat-square&amp;logo=nodedotjs&amp;logoColor=white"></a>
   <a href="https://github.com/mokuyoaxis/dsh-iris/actions/workflows/ci.yml"><img alt="CI" src="https://github.com/mokuyoaxis/dsh-iris/actions/workflows/ci.yml/badge.svg"></a>
   <a href="LICENSE"><img alt="MIT License" src="https://img.shields.io/badge/license-MIT-1689FF.svg?style=flat-square"></a>
 </p>
@@ -44,7 +44,23 @@ These captures come from an Android browser connected to DSH under Termux/PRoot
 
 The project is at an early stage; interfaces and configuration formats may still change between releases.
 
-Iris's long-term direction is a media production core that can run on its own and plug into different agent hosts. DeepSeek Harness is the first supported host, and the current version still requires DSH — a standalone Core, CLI, and workbench are on the roadmap but not yet available.
+Iris is evolving toward a media production core that can run independently and plug into different agent hosts. Version 0.2.0 provides both a DSH plugin and a headless CLI media path (crop, image/video/TTS/transcription submission, task observation, artifact export). Core internals have not been frozen as a public SDK.
+
+> Version support: Iris `0.2.0` requires Node.js `>=22.0.0` and its DSH plugin supports only the exact host version `0.2.0-rc.2`. Older DSH hosts should pin `@mokuyoaxis/dsh-iris@0.1.4` as described below instead of following npm latest. Iris and DSH have independent version numbers.
+
+## Two ways to use Iris
+
+| | Path A: DSH plugin (0.2.0) | Path B: Headless CLI (0.2.0) |
+|---|---|---|
+| Who it's for | DeepSeek Harness users who want agent tools, the workbench, and in-chat prompt optimization | Users who want media generation, task tracking, and artifact export from the command line without DSH |
+| Entry point | Choose a pinned release under "Quickest start" below | `dsh-iris run ...` — see [Headless CLI](docs/HEADLESS_CLI.md) |
+| Data location | `$DSH_HOME/iris/v1/` (Core data root `core-v0`) | Any absolute path passed via `--data-root` |
+| Automatic observation | Yes (bounded DSH host ticks + restart takeover) | No — explicit single-step `task observe` |
+| Dependencies | DSH `0.2.0-rc.2` and Node.js ≥ 22 | Node.js ≥ 22 and `sharp` only (`ffmpeg` for video frames) |
+
+Both paths read and write the same Core Task/Artifact facts: point the CLI at the `core-v0` data root of a DSH profile to inspect/export DSH-generated artifacts, and vice versa. Only one writer is allowed per data root.
+
+> Install size note: image processing depends on `sharp` and its prebuilt binaries (~27 MB). On uncommon platforms (e.g. some ARM proot environments) a failed sharp install is detected by `dsh-iris doctor`; image actions become unavailable while everything else keeps working.
 
 ## Relationship with ai-paint
 
@@ -54,16 +70,47 @@ Early versions read models and credentials from the maintainer's local ai-paint
 
 ## Quickest start
 
-With a supported DeepSeek Harness (`>=0.1.2-rc.1 <0.1.3-0` or `0.1.5-rc.1`) installed and `pnpm` on your PATH, add Iris to the Web profile:
+Check the host with `dsh --version` and ensure `pnpm` is on your PATH. Iris and DSH have independent version numbers; choose a matching combination:
+
+| Your DSH | Iris choice | Source |
+|---|---|---|
+| `0.2.0-rc.2` | `0.2.0` | Pinned npm release |
+| `>=0.1.2-rc.1 <0.1.3-0` or `0.1.5-rc.1` | Stable `0.1.4` | Pinned npm release |
+| Other versions | No current support claim | Check host adaptation before installing |
+
+### Older DSH: install stable 0.1.4
+
+For the older DSH range above, add the pinned release to the Web profile:
 
 ```bash
-dsh plugin --profile web add @mokuyoaxis/dsh-iris
+dsh plugin --profile web add @mokuyoaxis/dsh-iris@0.1.4
 dsh web
 ```
 
-> The unscoped `dsh-iris` on npm belongs to a different plugin. Always keep the fully scoped name `@mokuyoaxis/dsh-iris` when installing or updating Iris Media.
+To download the published npm package separately:
+
+```bash
+npm pack @mokuyoaxis/dsh-iris@0.1.4
+```
+
+This writes a `.tgz` to the current directory. Use `npm install @mokuyoaxis/dsh-iris@0.1.4` if you only want a regular npm dependency; that does not add a DSH profile layer. Pinning `@0.1.4` keeps selecting the old stable release after latest changes. See [npm pack](https://docs.npmjs.com/cli/v11/commands/npm-pack/). Version 0.1.4 does not contain the 0.2.0 Core media CLI or the later DSH rc.2 adaptation.
 
-To try it from a source checkout, replace `@mokuyoaxis/dsh-iris` in the first command with `.`. The plugin loads the next time DSH starts; the web UI defaults to `http://127.0.0.1:3080`.
+### DSH 0.2.0-rc.2: install 0.2.0
+
+Install the pinned npm release into the Web profile:
+
+```bash
+dsh plugin --profile web add @mokuyoaxis/dsh-iris@0.2.0
+dsh web
+```
+
+The plugin loads the next time DSH starts; the web UI defaults to `http://127.0.0.1:3080`. Open the complete URL if startup output includes authentication parameters. Version 0.2.0's compatibility metadata admits only DSH rc.2.
+
+### Choosing a version in dsh-market
+
+The marketplace entry should resolve to the full package name `@mokuyoaxis/dsh-iris`. Check both its displayed Iris version and your local `dsh --version` before installing: 0.2.0 is for DSH rc.2; older hosts should use the pinned `@0.1.4` commands above. Catalog and npm information may be cached. The actual npm package's `dsh.engines.dsh` and Node engines determine its declared requirements; a visible listing does not imply support for every DSH release.
+
+> The unscoped `dsh-iris` on npm belongs to a different plugin. Always keep the fully scoped name `@mokuyoaxis/dsh-iris` when installing or updating Iris Media.
 
 After the first start, open "Settings → Iris workbench → + Add provider", enter your DashScope base URL and API key, then click "Discover models". A single provider can start with automatic capability assignment. Full steps, OpenAI Images–compatible configuration, and failover notes are in the [user guide](user_guide.md) (Chinese).
 
@@ -77,6 +124,8 @@ Summarize /absolute/path/demo.mp4 with Iris, then turn the summary into speech.
 
 DSH profiles and plugin commands follow the [official installation docs](https://github.com/deepseek-ai/deepseek-harness/blob/master/docs/user/develop/basic/publish.md). Generating images, videos, or speech may incur provider charges.
 
+For a copyable installation and usage prompt, see [Agent quickstart prompt](docs/AGENT_QUICKSTART.md).
+
 ## Feature overview
 
 ![Iris architecture overview](docs/assets/diagrams/iris-architecture.png)
@@ -93,7 +142,7 @@ DSH profiles and plugin commands follow the [official installation docs](https:/
 
 ## Prerequisites
 
-- A Node.js version that satisfies your DeepSeek Harness release's requirement; dsh-iris itself requires at least 20.10
+- A Node.js version that satisfies your DeepSeek Harness release's requirement; Iris 0.2.0 requires at least 22.0.0, while the published npm 0.1.4 historically requires 20.10.0
 - A working DeepSeek Harness environment with `pnpm` on the PATH
 - At least one supported media or vision provider
 - `ffmpeg` and `ffprobe` on the system, for video frame extraction and video summaries
@@ -102,11 +151,19 @@ After installing the plugin, add a provider in the Iris workbench and assign mod
 
 ## DeepSeek Harness adaptation
 
-dsh-iris ships as a native DSH plugin with a server side and a web client. The server registers 14 agent tools and reuses the host's tool, routing, and lifecycle services; the client hooks into the settings page, the conversation input area, and the global floating layer through DSH's module loader. The plugin never starts a separate service or listens on an extra port.
+dsh-iris remains a native DSH plugin. Its server registers 14 agent tools and uses host-provided routing, attachment, model, and lifecycle services. The web client contributes settings, composer, and global-overlay UI. Iris does not start another service or listen on an extra port.
+
+| Iris version | DSH range | Verification |
+|---|---|---|
+| Published stable `0.1.4` | `>=0.1.2-rc.1 <0.1.3-0` | Historical clean and daily Web profiles on Linux ARM64 |
+| Published stable `0.1.4` | `0.1.5-rc.1` | Historical daily Android/Linux profile checks |
+| `0.2.0` | Only `0.2.0-rc.2` | Installed-service isolation checks, Core diff, and SlotRegistry; user demonstration reported successful, with detailed browser actions and asynchronous restart/rollback verification continuing |
+
+See the [rc.2 adaptation notes](docs/DSH_RC2_ADAPTATION.md) for scope. The published npm 0.1.4 package does not contain these later changes.
 
-Automated tests currently cover plugin loading, tool registration, client seats, and routing behavior. Version 0.1.1 completed host smoke tests on Linux ARM64 — in both a clean and a real web profile — against DSH `0.1.2-rc.1` on Node.js `22.23.2`: the browser startup graph, the full combined bundle, the Iris client factory, and the three UI seats present at that time were verified. The fourth prompt-optimizer seat added in 0.1.2 has now been rendered in a live Android browser; configuration loading, a real session-model optimization with thinking actually `off`, preview write-back, independent disabling and re-enabling, and the loop from a short draft to a succeeded image-generation task are verified. Browser-side cancellation and JSON operations have automated HTTP/configuration coverage; a step-by-step live-device record is still pending. Iris itself keeps Node.js `>=20.10` as its own floor. Version 0.1.4 additionally completed a live host load of 14 tools, two Skills, four route groups, and four UI slots on a daily DSH `0.1.5-rc.1` host.
+Iris 0.2.0 no longer claims older DSH support; historical validation does not automatically cover this version. DSH `0.2.0` stable and other rc versions are also outside its support range. Automated checks cover server loading, tool and Skill registration, routes, the client bundle, and UI slots separately so Doctor can identify which boundary failed.
 
-Iris 0.1.4 explicitly supports the two verified DSH windows `>=0.1.2-rc.1 <0.1.3-0` and `0.1.5-rc.1`, and no longer works with the legacy client runtime of DSH 0.1.0/0.1.1. Other preview versions have no host canary and are not claimed as compatible; the range widens only after verification passes, and the compatibility badge is not an official certification. If DSH requires a newer Node.js, DSH wins.
+Core and the DSH Adapter are being separated: DSH keeps loading the same npm package, while the Adapter maps host capabilities into Core. A DSH API change should require an Adapter or client-bridge fix, not a rewrite of Task or Artifact semantics. Version 0.2.0 includes the headless CLI. The `dsh` prefix will be removed after a second real Host Adapter is implemented and accepted, with a new npm package at that point; see the [roadmap](docs/ROADMAP.md).
 
 ## Tools
 
@@ -157,9 +214,9 @@ By default, the optimizer uses the model selected for the current session and fa
 
 ## Model assignment and failover
 
-Capability assignment uses `providerId::modelId` as the model identity. The same model name from a different provider or account counts as two independent options.
+Capability assignment uses `providerId::modelId` as the model identity. The same model name from a different provider or account counts as two independent options. Discovery prefers provider capability metadata, falls back to name rules, and preserves explicit user overrides. Alibaba Cloud media calls may use a separate Workspace `mediaBaseUrl`.
 
-Generation capabilities accept multiple candidate models. Iris tries the next candidate only when the provider explicitly proves that the request was not accepted. A 500 response, timeout, disconnect, missing response, polling failure, or local persistence failure never authorizes automatic resubmission. Once accepted, Iris may only resume observation or delivery.
+Generation capabilities accept multiple candidate models. Every request starts at the head of the ordered list; this is safe failover, not round-robin. Iris tries the next candidate only when the provider explicitly proves that the request was not accepted. A 500 response, timeout, disconnect, missing response, polling failure, or local persistence failure never authorizes automatic resubmission. Once accepted, Iris may only resume observation or delivery.
 
 The workbench lists paused observation, unknown acceptance/outcome, and successful generation with failed delivery under “Needs attention.” Re-observe never submits; re-deliver never regenerates; acknowledge/restore only changes the local reminder queue; only an explicitly confirmed informed retry creates a linked new task and may incur duplicate charges. Creating that task archives the original reminder while preserving its unknown facts and audit link. See [Task semantics](docs/TASK_SEMANTICS.md), [Architecture](docs/ARCHITECTURE.md), [Security](docs/SECURITY.md), and the [Fault-injection matrix](docs/FAULT_INJECTION.md).
 
@@ -218,7 +275,7 @@ Audio and video are served through Iris media links that carry random capability
 ## Security notes
 
 - Provider keys are never returned by status endpoints.
-- The DashScope media protocol only sends keys to official Alibaba Cloud HTTPS domains; any other base URL defaults to the OpenAI Images–compatible protocol.
+- The DashScope media protocol only sends keys to official Alibaba Cloud HTTPS, regional, or Workspace domains. A separate `mediaBaseUrl` may split media from vision/chat traffic; other addresses default to the OpenAI Images–compatible protocol.
 - `/iris/*` accepts loopback Host headers only by default; LAN or reverse-proxy deployments must set `IRIS_TRUSTED_HOSTS` explicitly, and state-changing requests are also checked against cross-site origins.
 - `IRIS_TRUSTED_HOSTS` is not an authentication mechanism. When exposing DSH to the public internet or an untrusted network, configure authentication and HTTPS at the reverse proxy or host layer.
 - Paid model probes run one capability at a time and always confirm before a real provider call; video and transcription never submit empty-sample paid probes automatically.
@@ -263,7 +320,7 @@ Run in the project directory:
 
 Tests cover config merging, model identity, task lifecycle, generation actions, HTTP/SSE routing, client interactions, and security boundaries. The project is pure ES Modules with no build step.
 
-The test scheduler runs on Node.js, launching one process per file and stopping at the first failure — no Bash involved. Temporary directories use system APIs and are cleaned up on exit. GitHub Actions defines a Linux/Windows × Node.js 20.10/22 matrix, and a pre-release hook re-runs the full suite. DSH host smoke tests on native Windows/WSL are still pending real-machine verification.
+The test scheduler runs on Node.js, launching one process per file and stopping at the first failure — no Bash involved. Temporary directories use system APIs and are cleaned up on exit. GitHub Actions defines a Linux/Windows × Node.js 22.0.0/latest 22.x matrix, with repeated natural-exit checks on the minimum version, and a pre-release hook re-runs the full suite. DSH host smoke tests on native Windows/WSL are still pending real-machine verification.
 
 Releases are triggered by `v*` tags through `.github/workflows/release.yml`: the full test suite runs first, then the tarball is packaged, a GitHub Release is created with the workflow's built-in `GITHUB_TOKEN` (tarball attached; release notes taken from the matching CHANGELOG section), and npm publish happens when an `NPM_TOKEN` secret is configured. No local GitHub credentials are needed.
 

package/README.md

@@ -3,7 +3,7 @@
 </p>
 
 <p align="center">
-  <img src="docs/assets/iris-wordmark.svg" width="520" alt="IRIS 彩色字标">
+  <img src="docs/assets/logo/iris-interim-flower.png" width="400" alt="IRIS 线稿鸢尾花（临时标志）">
 </p>
 
 <h1 align="center">Iris Media for DSH</h1>
@@ -13,7 +13,7 @@
 <p align="center">
   <a href="#deepseek-harness-适配"><img alt="DeepSeek Harness compatible" src="https://img.shields.io/badge/DeepSeek%20Harness-compatible-4D6BFE.svg?style=flat-square"></a>
   <a href="https://www.npmjs.com/package/@mokuyoaxis/dsh-iris"><img alt="npm version" src="https://img.shields.io/npm/v/%40mokuyoaxis%2Fdsh-iris.svg?style=flat-square"></a>
-  <a href="https://nodejs.org/"><img alt="Node.js 20.10 or newer" src="https://img.shields.io/badge/Node.js-%3E%3D20.10-339933.svg?style=flat-square&amp;logo=nodedotjs&amp;logoColor=white"></a>
+  <a href="https://nodejs.org/"><img alt="Node.js 22 or newer" src="https://img.shields.io/badge/Node.js-%3E%3D22-339933.svg?style=flat-square&amp;logo=nodedotjs&amp;logoColor=white"></a>
   <a href="https://github.com/mokuyoaxis/dsh-iris/actions/workflows/ci.yml"><img alt="CI" src="https://github.com/mokuyoaxis/dsh-iris/actions/workflows/ci.yml/badge.svg"></a>
   <a href="LICENSE"><img alt="MIT License" src="https://img.shields.io/badge/license-MIT-1689FF.svg?style=flat-square"></a>
 </p>
@@ -44,7 +44,23 @@ dsh-iris 为 Agent 和 Iris 工作台提供图像、视频、语音与视觉理
 
 项目目前处于早期版本，接口和配置格式仍可能随版本迭代调整。
 
-Iris 的长期方向是可独立运行、可接入不同 Agent 宿主的媒体生产核心。DeepSeek Harness 是首个受支持宿主；当前版本仍需要 DSH，独立 Core、CLI 和工作台属于后续路线，尚未提供。
+Iris 的长期方向是可独立运行、可接入不同 Agent 宿主的媒体生产核心。0.2.0 同时提供 DSH 插件与无 DSH 的 CLI 媒体链路（crop、图片/视频/语音/转写提交、任务观察、作品导出）。Core 内部接口尚未冻结为公共 SDK。
+
+> 版本支持：Iris `0.2.0` 要求 Node.js `>=22.0.0`，DSH 插件仅支持准确版本 `0.2.0-rc.2`。旧 DSH 使用下文列出的 `@mokuyoaxis/dsh-iris@0.1.4`，不要直接跟随 npm latest 更新。Iris 与 DSH 的版本号独立。
+
+## 两条使用路径
+
+| | 路径 A：DSH 插件（0.2.0） | 路径 B：Headless CLI（0.2.0） |
+|---|---|---|
+| 适合谁 | 已在使用 DeepSeek Harness，想要 Agent 工具、工作台和对话内提示词优化 | 想在无 DSH 环境用命令行完成媒体生成、任务跟踪和作品导出 |
+| 入口 | 按下文「最快开始」选择固定版本 | `dsh-iris run ...`，见 [Headless CLI](docs/HEADLESS_CLI.md) |
+| 数据位置 | `$DSH_HOME/iris/v1/`（Core 数据根 `core-v0`） | 显式 `--data-root` 指定的任意绝对路径 |
+| 自动观察 | 有（DSH Host 有界节拍 + 重启接管） | 无，显式单步 `task observe` |
+| 依赖 | DSH `0.2.0-rc.2`、Node.js ≥ 22 | 仅 Node.js ≥ 22 与 `sharp`（视频抽帧另需 `ffmpeg`） |
+
+两条路径读写同一份 Core Task/Artifact 事实：CLI 指向 DSH profile 的 `core-v0` 数据根即可 inspect/export DSH 生成的作品，反之亦然。同一数据根只允许一个写者。
+
+> 安装体积提示：图像处理依赖 `sharp` 及其预编译二进制（约 27MB）。冷门平台（如部分 ARM proot 环境）安装失败时 `dsh-iris doctor` 可检出，图像类动作不可用，其余能力不受影响。
 
 ## 与 ai-paint 的关系
 
@@ -54,16 +70,47 @@ Iris 的长期方向是可独立运行、可接入不同 Agent 宿主的媒体
 
 ## 最快开始
 
-已经安装受支持的 DeepSeek Harness（`>=0.1.2-rc.1 <0.1.3-0` 或 `0.1.5-rc.1`）且 `pnpm` 在 PATH 中时，把 Iris 加入 Web profile：
+先用 `dsh --version` 核对宿主版本，并确认 `pnpm` 在 PATH 中。Iris 版本与 DSH 版本独立，按以下组合选择：
+
+| 你的 DSH | Iris 选择 | 安装来源 |
+|---|---|---|
+| `0.2.0-rc.2` | `0.2.0` | 固定 npm 版本 |
+| `>=0.1.2-rc.1 <0.1.3-0` 或 `0.1.5-rc.1` | 稳定版 `0.1.4` | 固定 npm 版本 |
+| 其他版本 | 暂无当前支持声明 | 先核对宿主适配，不能按相邻版本推定兼容 |
+
+### 旧 DSH：安装稳定版 0.1.4
+
+在上述旧 DSH 范围内，将固定版本加入 Web profile：
 
 ```bash
-dsh plugin --profile web add @mokuyoaxis/dsh-iris
+dsh plugin --profile web add @mokuyoaxis/dsh-iris@0.1.4
 dsh web
 ```
 
-> npm 上无 scope 的 `dsh-iris` 属于另一款插件。安装和更新 Iris Media 时必须保留完整包名 `@mokuyoaxis/dsh-iris`。
+需要单独下载 npm 发布包时：
+
+```bash
+npm pack @mokuyoaxis/dsh-iris@0.1.4
+```
+
+命令会在当前目录生成 `.tgz`。只需安装为普通 npm 依赖时可使用 `npm install @mokuyoaxis/dsh-iris@0.1.4`；这不会自动把插件加入 DSH profile。固定 `@0.1.4` 可在 latest 更新后继续取得旧稳定版本，见 [npm pack 文档](https://docs.npmjs.com/cli/v11/commands/npm-pack/)。0.1.4 不包含 0.2.0 的 Core 媒体 CLI，也不包含 DSH rc.2 的后续适配。
 
-从当前源码目录试用时，把第一条命令中的 `@mokuyoaxis/dsh-iris` 换成 `.`。插件会在下一次 DSH 启动时装载，Web UI 默认位于 `http://127.0.0.1:3080`。
+### DSH 0.2.0-rc.2：安装 0.2.0
+
+从 npm 安装固定版本到 Web profile：
+
+```bash
+dsh plugin --profile web add @mokuyoaxis/dsh-iris@0.2.0
+dsh web
+```
+
+插件会在下一次 DSH 启动时装载，Web UI 默认位于 `http://127.0.0.1:3080`；启动输出带认证参数时请打开完整 URL。0.2.0 的兼容元数据仅放行 DSH rc.2。
+
+### dsh-market 安装时的版本选择
+
+市场条目应对应完整包名 `@mokuyoaxis/dsh-iris`。安装前同时核对市场显示的 Iris 版本与本机 `dsh --version`：0.2.0 仅用于 DSH rc.2；旧宿主使用上面的固定 `@0.1.4` 命令。市场目录与 npm 信息可能有缓存，以实际 npm 包的 `dsh.engines.dsh` 和 Node engines 为准；市场中可见不代表任意 DSH 版本兼容。
+
+> npm 上无 scope 的 `dsh-iris` 属于另一款插件。安装和更新 Iris Media 时必须保留完整包名 `@mokuyoaxis/dsh-iris`。
 
 首次启动后，打开“设置 → Iris 工作台 → + 添加供应商”，填入 DashScope Base URL 和 API Key，再点“发现模型”。单供应商可以先使用自动能力分配。完整步骤、OpenAI Images 兼容配置和故障转移说明见[用户指南](user_guide.md)。
 
@@ -77,6 +124,8 @@ dsh web
 
 DSH 的 profile 与插件命令由[官方安装说明](https://github.com/deepseek-ai/deepseek-harness/blob/master/docs/user/develop/basic/publish.md)定义。生成图片、视频或语音可能产生供应商费用。
 
+给 AI Agent 的可复制安装与使用提示见 [Agent 简要 Prompt](docs/AGENT_QUICKSTART.md)。
+
 ## 功能概览
 
 ![Iris 架构总览](docs/assets/diagrams/iris-architecture.png)
@@ -93,7 +142,7 @@ DSH 的 profile 与插件命令由[官方安装说明](https://github.com/deepse
 
 ## 使用前准备
 
-- 满足所用 DeepSeek Harness 版本要求的 Node.js；dsh-iris 自身最低为 20.10
+- 满足所用 DeepSeek Harness 版本要求的 Node.js；Iris 0.2.0 最低为 22.0.0，旧 npm 0.1.4 的历史要求为 20.10.0
 - 一个可用的 DeepSeek Harness 环境，以及 PATH 中的 `pnpm`
 - 至少一个受支持的媒体或视觉服务供应商
 - 使用视频抽帧和视频摘要时，需要系统提供 `ffmpeg` 与 `ffprobe`
@@ -102,11 +151,19 @@ DSH 的 profile 与插件命令由[官方安装说明](https://github.com/deepse
 
 ## DeepSeek Harness 适配
 
-dsh-iris 按 DeepSeek Harness 插件形态提供服务端与 Web 客户端入口：服务端注册 14 个 Agent 工具，并复用宿主的工具、路由和生命周期服务；客户端通过 DSH 模块加载器接入设置页、会话输入区和全局悬浮层。插件不会启动独立服务或额外监听端口。
+dsh-iris 仍按 DSH 原生插件装载。服务端注册 14 个 Agent 工具，并使用宿主提供的路由、附件、模型和生命周期能力；Web 客户端接入设置页、会话输入区与全局悬浮层。插件不会启动额外服务或监听端口。
+
+| Iris 范围 | DSH 范围 | 验证记录 |
+|---|---|---|
+| 已发布稳定版 `0.1.4` | `>=0.1.2-rc.1 <0.1.3-0` | 历史 Linux ARM64 干净与日常 Web profile 验收 |
+| 已发布稳定版 `0.1.4` | `0.1.5-rc.1` | 历史 Android/Linux 日常 profile 验收 |
+| `0.2.0` | 仅 `0.2.0-rc.2` | 真实安装服务隔离验收、Core diff 与 SlotRegistry；已有用户实机演示反馈，逐项浏览器操作与异步重启/回退继续验收 |
+
+rc.2 修正与验证范围见[适配说明](docs/DSH_RC2_ADAPTATION.md)；已发布 npm 0.1.4 包不包含这项后续适配。
 
-当前自动化测试覆盖插件装载、工具注册、客户端槽位和路由行为。0.1.1 已在 Linux ARM64 的干净与真实 Web profile 中，使用 DSH `0.1.2-rc.1`、Node.js `22.23.2` 完成宿主烟测；浏览器启动图、完整组合 bundle、Iris 客户端工厂和当时的三个 UI 座位均已验证。0.1.2 新增的第四个提示词优化座位已在 Android 浏览器真机确认渲染，配置读取、真实会话模型优化（实际 thinking `off`）、预览写回、独立关闭与重新启用，以及从短草稿到图片生成任务成功的闭环均已验证；浏览器端取消和 JSON 操作已有自动化 HTTP/配置覆盖，尚待补充真机逐项记录。Iris 自身仍以 Node.js `>=20.10` 为最低基线。0.1.4 另在 Android/Linux 日常 DSH `0.1.5-rc.1` 上完成 14 工具、2 项 Skill、4 组路由与 4 个 UI Slot 的实机装载验证。
+Iris 0.2.0 不再声明支持旧 DSH；旧版的历史验收不自动覆盖当前版本。DSH `0.2.0` 正式版及其他 rc 同样未列入支持范围。自动化测试分别检查服务端装载、工具与 Skill 注册、路由、客户端 bundle 和 Slot；其中一层失效时，Doctor 应指出具体边界。
 
-Iris 0.1.4 明确支持 DSH `>=0.1.2-rc.1 <0.1.3-0` 与 `0.1.5-rc.1` 这两个已实测窗口，不再兼容 0.1.0/0.1.1 的旧客户端 Runtime。其余预览版未经宿主 canary，不宣称兼容，验证通过后再扩大范围；兼容徽章不代表官方认证。若 DSH 要求更高 Node 版本，以 DSH 为准。
+Core 与 DSH Adapter 正在分离，DSH 继续加载同一个 npm 包，Adapter 把宿主能力映射给 Core。若 DSH 修改 API，修复应限制在 Adapter 和客户端桥接；Core 的任务和产物语义不随宿主版本改变。0.2.0 已提供无 DSH CLI；第二个真实 Host Adapter 完成并验收后再移除名称中的 `dsh` 前缀，届时发布新的 npm 包，见[路线图](docs/ROADMAP.md)。
 
 ## 工具
 
@@ -157,9 +214,9 @@ Iris 会在 DSH 对话输入区提供一个无边框、无文字的“🫧”入
 
 ## 模型分配与故障转移
 
-能力分配使用 `providerId::modelId` 作为模型身份。同名模型如果来自不同供应商或不同账号，会被视为两个独立选项。
+能力分配使用 `providerId::modelId` 作为模型身份。同名模型如果来自不同供应商或不同账号，会被视为两个独立选项。模型发现优先采用供应商返回的能力元数据，名称规则只作兜底，用户手工标注最终生效；阿里云百炼可为媒体请求单独配置 Workspace `mediaBaseUrl`。
 
-生成类能力可以配置多个候选模型。Iris 只有在供应商明确证明未受理时才会尝试下一个候选；500、超时、断网、响应缺失、轮询失败和本地落盘失败都不会授权自动重提。远端服务一旦受理任务，Iris 只会恢复观察或交付，以免产生重复任务或重复计费。
+生成类能力可以配置多个候选模型。每次请求都从有序列表首项开始，并非 round-robin；Iris 只有在供应商明确证明未受理时才会尝试下一个候选；500、超时、断网、响应缺失、轮询失败和本地落盘失败都不会授权自动重提。远端服务一旦受理任务，Iris 只会恢复观察或交付，以免产生重复任务或重复计费。
 
 工作台把观察暂停、受理/结果未知和生成成功但交付失败单列为“需要处理”。“重新观察”不会提交；“重新交付”不会重新生成；“标为已读/恢复提醒”只改变本地提醒队列；只有“知情重试”会创建新任务，并要求用户逐次确认潜在重复费用。新任务创建后，原提醒自动归档但保留未知事实和新旧任务关联。任务语义、架构、安全边界与故障证据分别见 [`TASK_SEMANTICS.md`](docs/TASK_SEMANTICS.md)、[`ARCHITECTURE.md`](docs/ARCHITECTURE.md)、[`SECURITY.md`](docs/SECURITY.md) 和 [`FAULT_INJECTION.md`](docs/FAULT_INJECTION.md)。
 
@@ -218,7 +275,7 @@ Iris 自带两个 Agent Skills（`iris-verify-ui` 与 `iris-compose-media`），
 ## 安全说明
 
 - 供应商密钥不会通过状态接口返回。
-- DashScope 媒体协议只允许把密钥发送到阿里云官方 HTTPS 域名；其他 Base URL 默认推断为 OpenAI Images 兼容协议。
+- DashScope 媒体协议只允许把密钥发送到阿里云官方 HTTPS、地域或 Workspace 域名；可用独立 `mediaBaseUrl` 与视觉/对话端点分流，其他地址默认推断为 OpenAI Images 兼容协议。
 - `/iris/*` 默认只接受回环 Host；LAN 或反向代理必须显式设置 `IRIS_TRUSTED_HOSTS`，修改状态的请求还会检查跨站来源。
 - `IRIS_TRUSTED_HOSTS` 不是认证机制。对公网或不可信网络开放 DSH 时，必须在反向代理或宿主层配置身份认证与 HTTPS。
 - 模型实测只按单项能力运行，并在真实供应商调用前确认；视频和转写不会用空样本自动提交付费探针。
@@ -263,7 +320,7 @@ Iris 自带两个 Agent Skills（`iris-verify-ui` 与 `iris-compose-media`），
 
 测试覆盖配置合并、模型身份、任务生命周期、生成动作、HTTP/SSE 路由、客户端交互和安全边界。项目采用 ES Modules，不需要构建步骤。
 
-测试调度使用 Node.js，逐文件启动独立进程，首个失败即停止，不依赖 Bash；临时目录使用系统 API 并在退出时清理。GitHub Actions 定义 Linux/Windows × Node.js 20.10/22 矩阵，发布前钩子会重新运行完整测试。原生 Windows/WSL 的 DSH 宿主烟测仍待实机验证。
+测试调度使用 Node.js，逐文件启动独立进程，首个失败即停止，不依赖 Bash；临时目录使用系统 API 并在退出时清理。GitHub Actions 定义 Linux/Windows × Node.js 22.0.0/最新 22.x 矩阵，并在最低版本重复检查进程自然退出；发布前钩子会重新运行完整测试。原生 Windows/WSL 的 DSH 宿主烟测仍待实机验证。
 
 发布由 `v*` 标签触发 `.github/workflows/release.yml`：跑完整测试后打包，用工作流内置 `GITHUB_TOKEN` 创建 GitHub Release（附 tarball，发布说明取自 CHANGELOG 对应章节），并在配置了 `NPM_TOKEN` secret 时发布到 npm。本机无需任何 GitHub 凭据。