@mokuyoaxis/dsh-iris
Multi-provider image, video, and speech generation, transcription, visual understanding, and prompt optimization with an integrated Iris workbench for DeepSeek Harness.
The plugin will be installed here. Keep web if you are unsure.
npx -y @deepseek-ai/dsh plugin --profile web add @mokuyoaxis/dsh-iris@0.1.4
Iris is published as @mokuyoaxis/dsh-iris and currently resolves to version 0.1.4. The Hub verifies its manifest and preserves the exact installation source for reproducible installs.
简体中文 | English
Iris 多模态生产运行时 · 当前通过 DeepSeek Harness 插件使用
dsh-iris 为 Agent 和 Iris 工作台提供图像、视频、语音与视觉理解能力，也能直接优化 DSH 对话框中的任意提示词。它可以连接 DashScope 百炼及 OpenAI Images 兼容服务；完整配置和任务管理集中在 Iris 工作台，右下角的 Iris 泡泡提供快捷入口。
从一句“鸢尾花”开始：Iris 对话框优化 Prompt（
deepseek-v4-flash，thinkingoff）→ 阿里云百炼qwen-image-3.0-pro生成 · 2048×2048
以下截图来自 Android 浏览器连接 Termux/PRoot Debian ARM64 中的 DSH，使用 DSH 默认皮肤；公开图片均已移除 EXIF/XMP/IPTC 元数据。
| 对话输入区的 🫧 入口 | 优化结果写回输入框 |
|---|---|
| DSH 对话输入区中的 Iris 泡泡入口 | Iris 将优化结果写回 DSH 输入框 |
项目目前处于早期版本，接口和配置格式仍可能随版本迭代调整。
Iris 的长期方向是可独立运行、可接入不同 Agent 宿主的媒体生产核心。DeepSeek Harness 是首个受支持宿主；当前版本仍需要 DSH，独立 Core、CLI 和工作台属于后续路线，尚未提供。
ai-paint 是 Iris 维护者本机未公开的前身项目，不是 Iris 的公开依赖，也不是用户需要下载、安装或自行创建的目录。没有该项目的用户直接按下文在 Iris 工作台配置供应商即可。
早期版本从维护者本机的 ai-paint 配置读取模型与凭据，既用于迁移前身项目，也让宿主进程可以在本地复用已有 API Key，避免为迁移而把密钥粘贴到 Agent 会话、命令行参数或文档中。0.1.1 将两者的配置彻底分离：Iris 只使用自己的配置；旧配置仅可通过把 IRIS_IMPORT_WORKBENCH_CONFIG 显式设为本地配置文件的绝对路径进行一次性导入，不会默认扫描 ai-paint，也不会在两边同步。该变量保存的是文件路径而不是 API Key，来源文件不会被修改；具体操作见用户指南。
已经安装受支持的 DeepSeek Harness（>=0.1.2-rc.1 <0.1.3-0 或 0.1.5-rc.1）且 pnpm 在 PATH 中时，把 Iris 加入 Web profile：
dsh plugin --profile web add @mokuyoaxis/dsh-iris
dsh web
npm 上无 scope 的
dsh-iris属于另一款插件。安装和更新 Iris Media 时必须保留完整包名@mokuyoaxis/dsh-iris。
从当前源码目录试用时，把第一条命令中的 @mokuyoaxis/dsh-iris 换成 .。插件会在下一次 DSH 启动时装载，Web UI 默认位于 http://127.0.0.1:3080。
首次启动后，打开“设置 → Iris 工作台 → + 添加供应商”，填入 DashScope Base URL 和 API Key，再点“发现模型”。单供应商可以先使用自动能力分配。完整步骤、OpenAI Images 兼容配置和故障转移说明见用户指南。
配置完成后，最小指令可以是：
使用 iris_draw_image：画一只坐在蓝色窗边的白猫。
总结我刚上传的这张图片。
用 Iris 总结 /absolute/path/demo.mp4，再把摘要合成为语音。
DSH 的 profile 与插件命令由官方安装说明定义。生成图片、视频或语音可能产生供应商费用。
outputs/供应商 + 模型 分配能力pnpmffmpeg 与 ffprobe安装插件后，在 Iris 工作台中添加供应商并为所需能力分配模型。供应商密钥保存在宿主侧的 Iris 配置中；POSIX 系统上 Iris 自有目录和文件分别收紧为 0700 与 0600，界面和接口不会返回完整密钥。Windows 的 mode 不等同于 ACL，仍需依赖当前用户目录和系统账户权限。
dsh-iris 按 DeepSeek Harness 插件形态提供服务端与 Web 客户端入口：服务端注册 14 个 Agent 工具，并复用宿主的工具、路由和生命周期服务；客户端通过 DSH 模块加载器接入设置页、会话输入区和全局悬浮层。插件不会启动独立服务或额外监听端口。
当前自动化测试覆盖插件装载、工具注册、客户端槽位和路由行为。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.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 为准。
| 工具 | 用途 |
|---|---|
iris_draw_image | 根据提示词生成图片 |
iris_generate_video | 生成文生视频、图生视频或 S2V 数字人视频 |
iris_speak_text | 将文本合成为语音 |
iris_transcribe_audio | 将音频转写为文本 |
iris_task_status | 查询单个任务或最近任务的状态和产物 |
| 工具 | 用途 |
|---|---|
iris_look_at_image | 对图片提问并获得视觉模型回答 |
iris_relook_attachment | 使用新问题重新查看会话中的图片附件 |
iris_long_ocr | 分块识别长截图或长图文字 |
iris_locate | 定位图片中的目标并返回像素坐标 |
iris_crop | 按像素区域裁剪图片 |
iris_pixel_diff | 比较两张图片并生成差异统计和热力图 |
iris_html_screenshot | 在受限环境中将 HTML 字符串渲染为截图 |
| 工具 | 用途 |
|---|---|
iris_video_frames | 从视频中均匀抽取画面帧 |
iris_media_summarize | 结合画面帧和可选音频转写生成视频摘要 |
Iris 支持三种文件来源，推荐顺序如下：
上传内容保存在 $DSH_HOME/iris/v1/uploads/，默认保留 7 天。不同系统下的路径选择建议见文件访问与跨环境。
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 工具或任务后台。优化调用可能产生对应文本模型的费用。
能力分配使用 providerId::modelId 作为模型身份。同名模型如果来自不同供应商或不同账号，会被视为两个独立选项。
生成类能力可以配置多个候选模型。Iris 只有在供应商明确证明未受理时才会尝试下一个候选；500、超时、断网、响应缺失、轮询失败和本地落盘失败都不会授权自动重提。远端服务一旦受理任务，Iris 只会恢复观察或交付，以免产生重复任务或重复计费。
工作台把观察暂停、受理/结果未知和生成成功但交付失败单列为“需要处理”。“重新观察”不会提交；“重新交付”不会重新生成；“标为已读/恢复提醒”只改变本地提醒队列；只有“知情重试”会创建新任务，并要求用户逐次确认潜在重复费用。新任务创建后，原提醒自动归档但保留未知事实和新旧任务关联。任务语义、架构、安全边界与故障证据分别见 TASK_SEMANTICS.md、ARCHITECTURE.md、SECURITY.md 和 FAULT_INJECTION.md。
转写是独立的 transcribe 能力，不会占用 TTS 或视觉能力的模型配置。
工作台与主泡泡使用四色健康状态：灰色表示未配置，蓝色表示已配置但尚未验证或成功证据已超过 7 天，绿色表示对应“供应商 × 模型 × 能力”近期实测或真实任务成功，暗红色只表示明确的 401/403 或认证/权限失败。界面同时显示文字和证据时间；关键供应商配置变化会使旧证据失效。
Iris 不做后台探测。429、网络、5xx、内容安全、取消和受理未知不会把近期绿色改成红色，也不会触发隐形重试或费用。模型池可逐项实测视觉、图片和 TTS；视频与转写必须用真实任务验证。Host Doctor 只核验 DSH/Iris 的装载与 Host Port，不会验证供应商或模型。完整状态、failover 汇总和安全规则见 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 版本、插件、14 个工具、两项 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/：
| 位置 | 内容 |
|---|---|
providers.json | 供应商、能力分配和脱敏健康证据，文件权限为 0600 |
prompt-optimizer.json | 用户导入的优化 Prompt、目标模板、模型路由和生成参数，文件权限为 0600 |
tasks.json | 任务元数据和附件索引，最多保留 500 条 |
artifacts.json | 作品库最小索引与随机访问令牌，不含 Prompt、Provider 或任务关系 |
outputs/ | 生成和处理后的媒体文件 |
uploads/ | 浏览器上传的临时输入副本 |
0.1.1 首次装载时会收紧既有 $DSH_HOME/iris/v1/ 树的 POSIX 权限，不修改文件内容，也不跟随符号链接。大媒体下载采用流式私有临时文件与原子替换，不再把整段视频载入内存。
异步任务会在后台轮询。插件重启后，可以继续接管仍在远端执行的任务。取消信号会传递到本地等待与轮询流程；是否能取消远端计算，取决于供应商接口。
作品库与任务历史相互独立：清理终态任务不会删除作品，新旧媒体可在工作台分页浏览，也可用“找回本地作品”重新扫描 outputs/。删除作品或清空作品库会删除实际文件并单独确认；详见作品库 v0。收藏、标签和搜索留待完整 Artifact Manifest。
音频和视频通过带随机令牌的 Iris 媒体链接访问。图片会尽量转存为 DSH 持久附件，方便在会话中继续使用。
/iris/* 默认只接受回环 Host；LAN 或反向代理必须显式设置 IRIS_TRUSTED_HOSTS，修改状态的请求还会检查跨站来源。IRIS_TRUSTED_HOSTS 不是认证机制。对公网或不可信网络开放 DSH 时，必须在反向代理或宿主层配置身份认证与 HTTPS。sharp 包含原生组件；主要支持 glibc Linux、Windows 和 macOS。裸 Termux 等非标准运行环境可能需要额外处理。ffmpeg 与 ffprobe。插件启用时会通过 DSH Skill registry 自动注册两个随包 Skill：
| Skill | 适用场景 |
|---|---|
iris-verify-ui | 组合截图、语义检查、元素定位、裁剪和像素比较，完成有证据的 UI 验收 |
iris-compose-media | 组合两个以上 Iris 工具，完成看图后绘图、图片转视频、视频总结配旁白或 S2V 等媒体工作流 |
从 0.1.2 起，只要宿主提供 DSH Skill registry，普通 npm 安装用户在任意项目目录中都能发现并加载它们，不需要克隆本仓库或另外配置 Skill 搜索目录。项目目录中存在同名 Skill 时，仍按 DSH 原生优先级使用项目版本；Skill registry 不可用时，14 个 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 20.10/22 矩阵，发布前钩子会重新运行完整测试。原生 Windows/WSL 的 DSH 宿主烟测仍待实机验证。
发布由 v* 标签触发 .github/workflows/release.yml：跑完整测试后打包，用工作流内置 GITHUB_TOKEN 创建 GitHub Release（附 tarball，发布说明取自 CHANGELOG 对应章节），并在配置了 NPM_TOKEN secret 时发布到 npm。本机无需任何 GitHub 凭据。