@mokuyoaxis/dsh-iris 0.1.3 → 0.2.0

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` 且 `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 的后续适配。
+
+### 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
+```
 
-从当前源码目录试用时，把第一条命令中的 `@mokuyoaxis/dsh-iris` 换成 `.`。插件会在下一次 DSH 启动时装载，Web UI 默认位于 `http://127.0.0.1:3080`。
+插件会在下一次 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)
@@ -86,13 +135,14 @@ DSH 的 profile 与插件命令由[官方安装说明](https://github.com/deepse
 - 看图问答、长图 OCR、目标定位、裁剪和像素差异分析
 - 视频抽帧与多模态内容摘要
 - 异步任务跟踪、重启恢复和带授权令牌的媒体播放
+- 独立作品库：清除任务历史后仍可浏览本地作品，并可重新索引旧 `outputs/`
 - 多供应商模型池，以及按 `供应商 + 模型` 分配能力
 - 浏览器上传、会话附件和宿主路径三种文件来源
 - 独立于工作台的对话框提示词优化，支持当前会话模型与 JSON 固定模型路由
 
 ## 使用前准备
 
-- 满足所用 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`
@@ -101,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 客户端接入设置页、会话输入区与全局悬浮层。插件不会启动额外服务或监听端口。
 
-当前自动化测试覆盖插件装载、工具注册、客户端槽位和路由行为。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` 为最低基线。
+| 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；已有用户实机演示反馈，逐项浏览器操作与异步重启/回退继续验收 |
 
-Iris 0.1.1–0.1.3 明确支持 DSH `>=0.1.2-rc.1 <0.1.3-0`，不再兼容 0.1.0/0.1.1 的旧客户端 Runtime。DSH 仍在快速演进，后续预览版须经验证后再扩大范围；兼容徽章不代表官方认证。若 DSH 要求更高 Node 版本，以 DSH 为准。
+rc.2 修正与验证范围见[适配说明](docs/DSH_RC2_ADAPTATION.md)；已发布 npm 0.1.4 包不包含这项后续适配。
+
+Iris 0.2.0 不再声明支持旧 DSH；旧版的历史验收不自动覆盖当前版本。DSH `0.2.0` 正式版及其他 rc 同样未列入支持范围。自动化测试分别检查服务端装载、工具与 Skill 注册、路由、客户端 bundle 和 Slot；其中一层失效时，Doctor 应指出具体边界。
+
+Core 与 DSH Adapter 正在分离，DSH 继续加载同一个 npm 包，Adapter 把宿主能力映射给 Core。若 DSH 修改 API，修复应限制在 Adapter 和客户端桥接；Core 的任务和产物语义不随宿主版本改变。0.2.0 已提供无 DSH CLI；第二个真实 Host Adapter 完成并验收后再移除名称中的 `dsh` 前缀，届时发布新的 npm 包，见[路线图](docs/ROADMAP.md)。
 
 ## 工具
 
@@ -156,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)。
 
@@ -166,6 +224,12 @@ Iris 会在 DSH 对话输入区提供一个无边框、无文字的“🫧”入
 
 转写是独立的 `transcribe` 能力，不会占用 TTS 或视觉能力的模型配置。
 
+## 能力健康与模型验证
+
+工作台与主泡泡使用四色健康状态：灰色表示未配置，蓝色表示已配置但尚未验证或成功证据已超过 7 天，绿色表示对应“供应商 × 模型 × 能力”近期实测或真实任务成功，暗红色只表示明确的 401/403 或认证/权限失败。界面同时显示文字和证据时间；关键供应商配置变化会使旧证据失效。
+
+Iris 不做后台探测。429、网络、5xx、内容安全、取消和受理未知不会把近期绿色改成红色，也不会触发隐形重试或费用。模型池可逐项实测视觉、图片和 TTS；视频与转写必须用真实任务验证。Host Doctor 只核验 DSH/Iris 的装载与 Host Port，不会验证供应商或模型。完整状态、failover 汇总和安全规则见 [Provider 与能力健康状态](docs/PROVIDER_HEALTH.md)。
+
 ## 离线诊断
 
 无需安装或启动 DSH，也不会发送供应商请求：
@@ -175,7 +239,9 @@ npx @mokuyoaxis/dsh-iris doctor
 npx @mokuyoaxis/dsh-iris doctor --json
 ```
 
-安装后的二进制名是 `dsh-iris`。退出码 `0` 表示正常、`1` 表示有警告、`2` 表示有硬错误。Doctor 检查 Node、sharp、ffmpeg/ffprobe、数据目录真实写入、配置、模型/分配、任务语义、临时文件和孤儿/缺失产物；它不会判断运行中的 DSH、浏览器或真实 Provider 是否在线。
+安装后的二进制名是 `dsh-iris`。退出码 `0` 表示正常、`1` 表示有警告、`2` 表示有硬错误。离线 Doctor 检查 Node、sharp、ffmpeg/ffprobe、数据目录真实写入、配置、模型/分配、任务语义、临时文件和孤儿/缺失产物。
+
+运行中的 DSH 另在 Iris 工作台提供“宿主诊断”卡片，并公开已认证的 `/iris/api/doctor` JSON：检查 DSH 版本、插件、14 个工具、两项 Skill、四组路由、Browser/附件/模型能力、客户端版本和四个 UI Slot。它只读取安全快照与注册证据，不调用 Browser、模型或 Provider；详见 [Host Doctor](docs/HOST_DOCTOR.md)。
 
 ## 组合工作流示例
 
@@ -183,7 +249,7 @@ Iris 自带两个 Agent Skills（`iris-verify-ui` 与 `iris-compose-media`），
 
 ![组合工作流示例](docs/assets/diagrams/iris-workflow-compose.png)
 
-图的 SVG 版本与可编辑 drawio 源文件位于 [`docs/assets/diagrams/`](docs/assets/diagrams/)。
+仓库的 [`docs/assets/diagrams/`](docs/assets/diagrams/) 另提供 SVG 版本与可编辑 drawio 源文件；npm 包只随附 README 直接展示的 PNG。
 
 ## 数据与任务
 
@@ -191,9 +257,10 @@ Iris 自带两个 Agent Skills（`iris-verify-ui` 与 `iris-compose-media`），
 
 | 位置 | 内容 |
 |---|---|
-| `providers.json` | 供应商和能力分配，文件权限为 0600 |
+| `providers.json` | 供应商、能力分配和脱敏健康证据，文件权限为 0600 |
 | `prompt-optimizer.json` | 用户导入的优化 Prompt、目标模板、模型路由和生成参数，文件权限为 0600 |
 | `tasks.json` | 任务元数据和附件索引，最多保留 500 条 |
+| `artifacts.json` | 作品库最小索引与随机访问令牌，不含 Prompt、Provider 或任务关系 |
 | `outputs/` | 生成和处理后的媒体文件 |
 | `uploads/` | 浏览器上传的临时输入副本 |
 
@@ -201,17 +268,19 @@ Iris 自带两个 Agent Skills（`iris-verify-ui` 与 `iris-compose-media`），
 
 异步任务会在后台轮询。插件重启后，可以继续接管仍在远端执行的任务。取消信号会传递到本地等待与轮询流程；是否能取消远端计算，取决于供应商接口。
 
+作品库与任务历史相互独立：清理终态任务不会删除作品，新旧媒体可在工作台分页浏览，也可用“找回本地作品”重新扫描 `outputs/`。删除作品或清空作品库会删除实际文件并单独确认；详见[作品库 v0](docs/ARTIFACT_LIBRARY.md)。收藏、标签和搜索留待完整 Artifact Manifest。
+
 音频和视频通过带随机令牌的 Iris 媒体链接访问。图片会尽量转存为 DSH 持久附件，方便在会话中继续使用。
 
 ## 安全说明
 
 - 供应商密钥不会通过状态接口返回。
-- DashScope 媒体协议只允许把密钥发送到阿里云官方 HTTPS 域名；其他 Base URL 默认推断为 OpenAI Images 兼容协议。
+- DashScope 媒体协议只允许把密钥发送到阿里云官方 HTTPS、地域或 Workspace 域名；可用独立 `mediaBaseUrl` 与视觉/对话端点分流，其他地址默认推断为 OpenAI Images 兼容协议。
 - `/iris/*` 默认只接受回环 Host；LAN 或反向代理必须显式设置 `IRIS_TRUSTED_HOSTS`，修改状态的请求还会检查跨站来源。
 - `IRIS_TRUSTED_HOSTS` 不是认证机制。对公网或不可信网络开放 DSH 时，必须在反向代理或宿主层配置身份认证与 HTTPS。
 - 模型实测只按单项能力运行，并在真实供应商调用前确认；视频和转写不会用空样本自动提交付费探针。
 - HTML 截图在不具备同源权限的沙箱页面中渲染，脚本和外部网络默认不可用。
-- 媒体链接使用随机能力令牌，文件路径只从任务记录解析。
+- 媒体链接使用随机能力令牌，文件路径只从任务记录或最小作品索引解析。
 - Iris 不提供独立账号体系，多用户隔离和访问控制由 DeepSeek Harness 部署负责。
 
 ## 已知限制
@@ -233,6 +302,16 @@ Iris 自带两个 Agent Skills（`iris-verify-ui` 与 `iris-compose-media`），
 
 从 0.1.2 起，只要宿主提供 DSH Skill registry，普通 npm 安装用户在任意项目目录中都能发现并加载它们，不需要克隆本仓库或另外配置 Skill 搜索目录。项目目录中存在同名 Skill 时，仍按 DSH 原生优先级使用项目版本；Skill registry 不可用时，14 个 Iris 工具仍可独立装载。
 
+用户想稳定指定方法时，可直接用 DSH 的 `/name` 形式：
+
+```text
+/iris-compose-media 分析我上传的产品照，生成同构图海报，再检查是否符合要求
+
+/iris-verify-ui 对比当前截图和参考图，定位偏差并给出有证据的结论
+```
+
+也可以继续用自然语言让 Agent 自动发现。单步绘图、OCR、转写等无需强行唤起组合 Skill，直接说需求或指定对应 Iris 工具即可。Skill 只规划工具链，不会绕过 Iris 的任务、费用确认和安全边界。
+
 ## 开发与验证
 
 在项目目录运行：
@@ -241,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 凭据。