dsh-iris

dsh-iris 为 Agent、Iris 工作台和独立 CLI 提供图像、视频、语音与视觉理解能力。图片模型可分别连接 DashScope、OpenAI Images、聊天生图或 Responses 接口；生成作品由共享 Core 管理，可按 Artifact ID 看图、OCR 和聊天改图。DSH 工作台集中配置与任务管理，🫧 泡泡提供对话草稿优化入口。

实际生成示例

从一句“鸢尾花”开始：Iris 对话框优化 Prompt（deepseek-v4-flash，thinking off）→ 阿里云百炼 qwen-image-3.0-pro 生成 · 2048×2048

Android 16 真机界面

以下截图来自 Android 浏览器连接 Termux/PRoot Debian ARM64 中的 DSH，使用 DSH 默认皮肤；公开图片均已移除 EXIF/XMP/IPTC 元数据。

对话输入区的 🫧 入口	优化结果写回输入框

查看完整六图流程：优化前、玻璃预览窗、写回、任务成功与实际产物

项目目前处于早期版本，接口和配置格式仍可能随版本迭代调整。

Iris 0.2.2 同时提供 DSH 插件与无 DSH 的 CLI，共用任务、产物和模型路由，升级可控提示词编辑与媒体运行可靠性，保留 OpenAI 兼容图片与视觉工作流。Core 内部接口尚未冻结为公共 SDK。

版本支持：Iris 0.2.x 要求 Node.js >=22.0.0，DSH 插件仅支持准确版本 0.2.0-rc.2。旧 DSH 使用下文列出的 @mokuyoaxis/dsh-iris@0.1.4，不要直接跟随 npm latest 更新。Iris 与 DSH 的版本号独立。

0.2.2 更新重点

可控提示词编辑与媒体运行可靠性，在既有 OpenAI 兼容图片与视觉工作流上继续完善。

• 提示词一般功能：折叠五用途、原稿与改动预览；默认忠实整理，明确改写与独立建议需用户选择。
• 明确功能模型池：能力来自配置或可信元数据，裸账号与名称不自动赋能；保留功能入口、有序候选和既有明确标签。
• Core 恢复与交付：保留 writer 创建/释放/恢复中断证据，非图片产物使用文件接收与分块哈希；不自动抢占租约或重新生成。
• 生图诊断：尺寸分隔符归一、合法长边和本地未受理校验；区分网络/正文故障、取消/超时与完整 HTTP 业务错误。
• 跨平台回归：修复中断夹具的根路径别名与分隔符假设，保留实际检查点验证。

完整变化和待验边界见 0.2.2 发布说明 与 CHANGELOG。

后续计划继续适配其他协议，并增加 Music 音乐生成功能，详见 路线图。

两条使用路径

两条路径读写同一份 Core Task/Artifact 事实：CLI 指向 DSH profile 的 core-v0 数据根即可 inspect/export DSH 生成的作品，反之亦然。同一数据根只允许一个写者。

安装体积提示：图像处理依赖 sharp 及其预编译二进制（约 27MB）。冷门平台（如部分 ARM proot 环境）安装失败时 dsh-iris doctor 可检出，图像类动作不可用，其余能力不受影响。

与 ai-paint 的关系

ai-paint 是 Iris 维护者本机未公开的前身项目，不是 Iris 的公开依赖，也不是用户需要下载、安装或自行创建的目录。没有该项目的用户直接按下文在 Iris 工作台配置供应商即可。

早期版本从维护者本机的 ai-paint 配置读取模型与凭据，既用于迁移前身项目，也让宿主进程可以在本地复用已有 API Key，避免为迁移而把密钥粘贴到 Agent 会话、命令行参数或文档中。0.1.1 将两者的配置彻底分离：Iris 只使用自己的配置；旧配置仅可通过把 IRIS_IMPORT_WORKBENCH_CONFIG 显式设为本地配置文件的绝对路径进行一次性导入，不会默认扫描 ai-paint，也不会在两边同步。该变量保存的是文件路径而不是 API Key，来源文件不会被修改；具体操作见用户指南。

最快开始

先用 dsh --version 核对宿主版本，并确认 pnpm 在 PATH 中。Iris 版本与 DSH 版本独立，按以下组合选择：

旧 DSH：安装稳定版 0.1.4

在上述旧 DSH 范围内，将固定版本加入 Web profile：

dsh plugin --profile web add @mokuyoaxis/dsh-iris@0.1.4
dsh web

需要单独下载 npm 发布包时：

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 文档。0.1.4 不包含 0.2.0 的 Core 媒体 CLI，也不包含 DSH rc.2 的后续适配。

DSH 0.2.0-rc.2：安装 0.2.2

安装固定版本到 Web profile：

dsh plugin --profile web add @mokuyoaxis/dsh-iris@0.2.2
dsh web

插件在下一次 DSH 启动时装载。Web UI 默认位于 http://127.0.0.1:3080；启动输出带认证参数时请打开完整 URL。更新后需重新加载后端并刷新客户端。

独立 CLI：安装 0.2.2

在自己的项目中安装，无需 DSH：

npm install @mokuyoaxis/dsh-iris@0.2.2
npx dsh-iris --help

dsh-market 安装时的版本选择

市场条目应对应完整包名 @mokuyoaxis/dsh-iris。安装前同时核对市场显示的 Iris 版本与本机 dsh --version：0.2.2 仅用于 DSH rc.2；旧宿主使用上面的固定 @0.1.4 命令。市场目录与 npm 信息可能有缓存，以实际 npm 包的 dsh.engines.dsh 和 Node engines 为准；市场中可见不代表任意 DSH 版本兼容。

npm 上无 scope 的 dsh-iris 属于另一款插件。安装和更新 Iris Media 时必须保留完整包名 @mokuyoaxis/dsh-iris。

首次启动后，打开“设置 → Iris 工作台 → + 添加供应商”，填入供应商 Base URL 和 API Key，再点“发现模型”。单供应商可以先使用自动能力分配。完整步骤、图片协议选择和故障转移说明见用户指南。

配置完成后，最小指令可以是：

使用 iris_draw_image：画一只坐在蓝色窗边的白猫。
总结我刚上传的这张图片。
用 Iris 总结 /absolute/path/demo.mp4，再把摘要合成为语音。

DSH 的 profile 与插件命令由官方安装说明定义。生成图片、视频或语音可能产生供应商费用。

给 AI Agent 的可复制安装与使用提示见 Agent 简要 Prompt。

功能概览

• 图像生成、文生视频、图生视频和 S2V 数字人视频
• 文本转语音与音频转写
• 看图问答、长图 OCR、目标定位、裁剪和像素差异分析
• 视频抽帧与多模态内容摘要
• 异步任务跟踪、重启恢复和带授权令牌的媒体播放
• 独立作品库：清除任务历史后仍可浏览本地作品，并可重新索引旧 outputs/
• 多供应商模型池，以及按 供应商 + 模型 分配能力
• 浏览器上传、会话附件和宿主路径三种文件来源
• 独立于工作台的对话框提示词优化，支持当前会话模型与 JSON 固定模型路由

使用前准备

• 满足所用 DeepSeek Harness 版本要求的 Node.js；Iris 0.2.2 最低为 22.0.0，旧 npm 0.1.4 的历史要求为 20.10.0
• 一个可用的 DeepSeek Harness 环境，以及 PATH 中的 pnpm
• 至少一个受支持的媒体或视觉服务供应商
• 从视频文件抽帧或摘要时，需要系统提供 ffmpeg 与 ffprobe；复用 Core 帧摘要无需这两个工具

安装插件后，在 Iris 工作台中添加供应商并为所需能力分配模型。供应商密钥保存在宿主侧的 Iris 配置中；POSIX 系统上 Iris 自有目录和文件分别收紧为 0700 与 0600，界面和接口不会返回完整密钥。Windows 的 mode 不等同于 ACL，仍需依赖当前用户目录和系统账户权限。

DeepSeek Harness 适配

dsh-iris 仍按 DSH 原生插件装载。0.2.2 服务端注册 15 个 Agent 工具（含改图），并使用宿主提供的路由、附件、模型和生命周期能力；Web 客户端接入设置页、会话输入区与全局悬浮层。插件不会启动额外服务或监听端口。

rc.2 修正与验证范围见适配说明；已发布 npm 0.1.4 包不包含这项后续适配。

Iris 0.2.x 不再声明支持旧 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 包，见路线图。

工具

生成、语音与任务

视觉与图像处理

视频处理

文件输入

看图、定位和 OCR 可使用本地路径、会话附件或 Core 图片 artifact_id；摘要可直接复用 frame_artifact_ids。Artifact 输入只读核验 MIME 与内容哈希，无需原文件或临时导出，PNG/JPEG/WebP 不需要用户先转成 JPG。命令示例见 视觉 CLI。

看图、OCR 每块、定位和聊天改图按账号/模型预算准备发送副本，默认 8 MiB，可调整大小与最长边；Core 原图、下载尺寸和哈希保持不变。OCR 标明缩小后的实际尺寸与细字风险，定位返回原图像素坐标。详见 视觉输入预算。

Core 图片改图直接使用来源 ID，修改版另存为新作品；聊天改图仅支持配置了聊天生图协议的模型。作品分页、过滤、跨页选择、下载与回收操作见 工作台作品管理。

Iris 支持三种文件来源，推荐顺序如下：

1. 浏览器上传：适合本地文件和跨环境访问，单文件上限为 64 MB。
2. 会话附件：适合复用当前会话中已经上传或生成的媒体。
3. 宿主路径：适合宿主可以直接读取的大文件。这里填写的是宿主进程看到的路径，不一定等同于浏览器所在系统的路径。

上传内容保存在 $DSH_HOME/iris/v1/uploads/，默认保留 7 天。不同系统下的路径选择建议见文件访问与跨环境。

对话框提示词优化

0.2.2 在既有按次规则、只组装和可编辑对照预览上增加一般功能。一般功能可折叠，提供通用、画图、改图、视频与数字人用途，默认忠实整理保留原文和句序；改写表达需明确选择，补充建议单独获取和采纳。默认指令贴近项目 Skills，既有自定义 v1 配置与旧 API 文字协议保留。规则不持久化，未新增独立提示词 CLI。功能及边界见 提示词优化系统。

Iris 会在 DSH 对话输入区提供一个无边框、无文字的“🫧”入口，不需要打开 Iris 工作台。点击后打开带背景模糊、半透明层次和柔和光影的玻璃悬浮窗；桌面端靠近输入区显示，窄屏与 Android 浏览器自动切换为带安全区和内部滚动的底部面板。它只读取当前未发送的纯文本草稿；结果先预览，用户确认后才写回输入框，不会自动发送。含 @ 或 / 结构化引用的草稿暂不改写，以免引用身份丢失。

默认使用当前会话选中的主模型；会话尚未选定模型时回退到 DSH 默认模型。优化请求不携带聊天历史、工具、附件或工作区，只发送当前草稿与目标模板。为避免推理模型在正文前耗尽生成预算，默认 generation.reasoningEffort 为 off-if-supported：仅在 DSH 模型元数据明确支持关闭 thinking 时禁用推理，否则使用供应商默认值，并且不再继承主会话的 High/Low 档位。可在 JSON 中改为 provider-default、inherit 或模型声明的具体 effort ID；成本与稳定性优先时，建议使用 fixed 路由指定轻量非思考模型。用户也可以导出 prompt-optimizer.json，将 route.mode 改为 fixed 并指定其他已在 DSH 注册的 provider 与 model，然后从面板重新导入。面板提供“恢复默认”，可还原 Iris 内置 Prompt、目标模板、会话模型路由和生成参数。该对话入口可以单独关闭，并从 Iris 工作台重新启用；关闭不会停用工作台、Agent 工具或任务后台。优化调用可能产生对应文本模型的费用。

模型分配与故障转移

Iris 按功能组织有序模型候选池，能力分配使用 providerId::modelId 区分执行器。同名模型来自不同供应商或账号时是独立选项；阿里云百炼可为媒体请求单独配置 Workspace mediaBaseUrl。

0.2.2 只采用明确功能标签、旧能力字段绑定或供应商能力元数据，裸账号和名称不再自动赋能。发现保留未标注模型，可在工作台“设置功能”或 CLI models caps 中明确用途；已有明确标签优先，分配顺序和安全切换保持。旧 0.2.1 的裸账号与模型名称推断不再用于功能赋能。

生成类能力可以配置多个候选模型。每次请求都从有序列表首项开始，并非 round-robin；Iris 只有在供应商明确证明未受理时才会尝试下一个候选；500、超时、断网、响应缺失、轮询失败和本地落盘失败都不会授权自动重提。远端服务一旦受理任务，Iris 只会恢复观察或交付，以免产生重复任务或重复计费。

工作台把观察暂停、受理/结果未知和生成成功但交付失败单列为“需要处理”。“重新观察”不会提交；“重新交付”不会重新生成；“标为已读/恢复提醒”只改变本地提醒队列；只有“知情重试”会创建新任务，并要求用户逐次确认潜在重复费用。新任务创建后，原提醒自动归档但保留未知事实和新旧任务关联。任务语义、架构、安全边界与故障证据分别见 TASK_SEMANTICS.md、ARCHITECTURE.md、SECURITY.md 和 FAULT_INJECTION.md。

转写是独立的 transcribe 能力，不会占用 TTS 或视觉能力的模型配置。

能力健康与模型验证

工作台与主泡泡用颜色和文字显示健康状态：灰色未配置，蓝色待验证，绿色表示对应“供应商 × 模型 × 能力”7 天内成功，暗红色表示明确认证/权限失败。0.2.2 另以琥珀色显示短时 429 冷却，红色显示已确认额度或预算耗尽，并给出原因和恢复条件。

Iris 不做后台探测。短时 429 遵从 Retry-After，缺失时冷却 60 秒；到期恢复候选资格，不自动调用验证。明确免费额度或预算耗尽则停用至手动实测成功，重启后仍跳过；实测按钮保持可用。模型池可逐项实测视觉、图片和 TTS，视频与转写可用 CLI 实测命令提供真实素材。网络、5xx、内容安全、取消和受理未知不覆盖近期成功。Host Doctor 只核验装载与 Host Port。完整规则见 Provider 与能力健康状态。

离线诊断

无需安装或启动 DSH，也不会发送供应商请求：

npx @mokuyoaxis/dsh-iris doctor
npx @mokuyoaxis/dsh-iris doctor --json

安装后的二进制名是 dsh-iris。退出码 0 表示正常、1 表示有警告、2 表示有硬错误。离线 Doctor 检查 Node、sharp、ffmpeg/ffprobe、数据目录真实写入、配置、模型/分配、任务语义、临时文件和孤儿/缺失产物。

运行中的 DSH 另在 Iris 工作台提供“宿主诊断”卡片，并公开已认证的 /iris/api/doctor JSON：检查 DSH 版本、插件、当前工具、两项 Skill、四组路由、Browser/附件/模型能力、客户端版本和四个 UI Slot。它只读取安全快照与注册证据，不调用 Browser、模型或 Provider；详见 Host Doctor。

组合工作流示例

Iris 自带两个 Agent Skills（iris-verify-ui 与 iris-compose-media），把多个工具编排成有界、可复核的媒体工作流。下例是「看图 → 重绘 → 自检」：先理解原图，再生成，复核针对具体偏差，只有复核通过才交付。

仓库的 docs/assets/diagrams/ 另提供 SVG 版本与可编辑 drawio 源文件；npm 包只随附 README 直接展示的 PNG。

数据与任务

运行数据默认位于 $DSH_HOME/iris/v1/：

0.1.1 首次装载时会收紧既有 $DSH_HOME/iris/v1/ 树的 POSIX 权限，不修改文件内容，也不跟随符号链接。大媒体下载采用流式私有临时文件与原子替换，不再把整段视频载入内存。

异步任务会在后台轮询。插件重启后，可以继续接管仍在远端执行的任务。取消信号会传递到本地等待与轮询流程；是否能取消远端计算，取决于供应商接口。

作品库与任务历史相互独立：清理终态任务不会删除作品，新旧媒体可在工作台分页浏览，也可用“找回本地作品”重新扫描 outputs/。旧版作品删除会删除实际文件并单独确认，见 作品库 v0；Core 作品先预览，再移入可恢复回收区，见 作品管理。收藏、标签和搜索仍为后续功能。

旧版媒体通过带随机令牌的链接访问；Core 媒体以随机 Artifact ID 读取，受宿主与浏览器来源守卫保护。图片会尽量转存为 DSH 持久附件，方便在会话中继续使用。

安全说明

• 供应商密钥不会通过状态接口返回。
• DashScope 媒体协议只允许把密钥发送到阿里云官方 HTTPS、地域或 Workspace 域名；可用独立 mediaBaseUrl 与视觉/对话端点分流，其他地址默认推断为 OpenAI Images 兼容协议。
• /iris/* 默认只接受回环 Host；LAN 或反向代理必须显式设置 IRIS_TRUSTED_HOSTS，修改状态的请求还会检查跨站来源。
• IRIS_TRUSTED_HOSTS 不是认证机制。对公网或不可信网络开放 DSH 时，必须在反向代理或宿主层配置身份认证与 HTTPS。
• 模型实测只按单项能力运行，并在真实供应商调用前确认；视频和转写不会用空样本自动提交付费探针。
• HTML 截图在不具备同源权限的沙箱页面中渲染，脚本和外部网络默认不可用。
• 旧版媒体链接使用随机能力令牌，Core 媒体按 Artifact ID 核验内容哈希；宿主 allowlist 不替代用户认证。
• Iris 不提供独立账号体系，多用户隔离和访问控制由 DeepSeek Harness 部署负责。

已知限制

• sharp 包含原生组件；主要支持 glibc Linux、Windows 和 macOS。裸 Termux 等非标准运行环境可能需要额外处理。
• 视频文件抽帧和摘要依赖系统安装的 ffmpeg 与 ffprobe；复用 Core 帧无需这两个工具。
• HTML 截图不加载远程脚本、字体或图片；需要的资源应先内联。
• WSL、容器和远程部署中，浏览器路径通常不能直接交给宿主读取，请优先上传文件。
• 供应商返回的模型清单只是候选集合，模型是否真正支持某项能力仍以实际调用为准。

Agent Skills

插件启用时会通过 DSH Skill registry 自动注册两个随包 Skill：

从 0.1.2 起，只要宿主提供 DSH Skill registry，普通 npm 安装用户在任意项目目录中都能发现并加载它们，不需要克隆本仓库或另外配置 Skill 搜索目录。项目目录中存在同名 Skill 时，仍按 DSH 原生优先级使用项目版本；Skill registry 不可用时，Iris 工具仍可独立装载。

用户想稳定指定方法时，可直接用 DSH 的 /name 形式：

/iris-compose-media 分析我上传的产品照，生成同构图海报，再检查是否符合要求

/iris-verify-ui 对比当前截图和参考图，定位偏差并给出有证据的结论

也可以继续用自然语言让 Agent 自动发现。单步绘图、OCR、转写等无需强行唤起组合 Skill，直接说需求或指定对应 Iris 工具即可。Skill 只规划工具链，不会绕过 Iris 的任务、费用确认和安全边界。

开发与验证

在项目目录运行：

npm test

测试覆盖配置合并、模型身份、任务生命周期、生成动作、HTTP/SSE 路由、客户端交互和安全边界。项目采用 ES Modules，不需要构建步骤。

测试调度使用 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，发布说明优先取自 docs/releases/<版本>.md，否则取 CHANGELOG 对应章节），并在配置了 NPM_TOKEN secret 时发布到 npm。本机无需任何 GitHub 凭据。

文档

• 用户指南
• 变更记录
• 路线图
• 文件访问与跨环境
• Android 16 真机截图画廊
• Task/Attempt v2 语义契约

License

MIT