mokuyoaxis/dsh-iris

dsh-iris gives agents, the Iris workbench and a standalone CLI image, video, music, speech and visual understanding capabilities. Each image model can use DashScope, OpenAI Images, chat image generation or Responses. Shared Core Artifacts connect generation, vision, OCR and chat editing. The DSH workbench provides configuration and task management, while the 🫧 bubble offers draft optimization in the composer.

Music uses a Chat Completions interface with inline audio, confirmed model uses and function policies, configurable 502 retries, and playback/export. See Music setup and usage (Chinese).

Iris 0.2.6 can reference an existing DSH provider connection (Chinese), resolving its endpoint and API key per operation without storing a second key. It adds automatic, selected-only, and disabled function pools (Chinese): confirming a model's uses can enable automatic selection without a second assignment step. Discovery alone never expands the pool; existing lists and empty configurations retain their behavior. Selection uses stable priority with safe failover, without a round-robin cursor.

Provider directories refresh on demand with a 10-minute successful cache. Confirmed model-not-found failures exclude that connection's model and capability from subsequent requests while preserving configured models and historical success. Directory details start collapsed; failed refreshes retain the last complete snapshot, and new models still require approval of their uses.

A real generation example

Starting from the two-character draft “鸢尾花”: Iris composer optimization (deepseek-v4-flash, thinking off) → Alibaba Cloud Bailian qwen-image-3.0-pro generation · 2048×2048

Android 16 live UI

These captures come from an Android browser connected to DSH under Termux/PRoot Debian ARM64, using the default DSH skin. Public copies have no EXIF, XMP, or IPTC metadata.

🫧 in the conversation composer	Optimized draft written back

See the complete six-image workflow: before, glass preview panel, write-back, succeeded task, and artifact

The project is at an early stage; interfaces and configuration formats may still change between releases.

This documentation covers Iris 0.2.6. Pin the version when installing or upgrading, and check the host compatibility range below first.

Iris 0.2.6 provides a DSH plugin and a headless CLI sharing tasks, artifacts and model routing. It adds connection reuse, optional automatic function pools, directory synchronization and capability checks. Image import, native Qwen editing, music, three agent skills and synchronous delivery recovery remain available. Core internals have not been frozen as a public SDK.

Version support: Iris 0.2.6 retains the 12 exact DSH versions declared in 0.2.5; see the compatibility matrix. Node.js must be at least 22.0.0 and meet any higher host requirement. Connection reuse also requires the relevant public host services.

What's new in 0.2.6 and existing features

Choose a connection, confirm model uses, then call a function. Automatic pools use stable priority and safe failover, without cross-request round-robin.

• Persistent image import: save an existing image through the workbench, agent, or CLI for later vision, editing, and export. The source file stays intact and no model is called.
• Native Qwen editing: use supported DashScope Qwen image editing models as well as chat image models; edited images retain a link to their source.
• Connection reuse and function pools: reference a DSH API-key connection, and choose automatic, selected-only or disabled mode for each function. Confirming uses can also enable its automatic pool.
• Directories and checks: refresh directories before automatic requests and exclude confirmed missing models from later requests. Capability checks and advanced sections start collapsed; paid probes require separate confirmation.
• Older and transitional hosts: the twelve exact versions in the matrix share current features and use the same manifest, client peer and Doctor compatibility boundary.

Upgrades preserve your allowed scope: existing lists and missing or empty assignments do not become automatic. New directory entries still require confirmation of their uses; absence alone does not prove a model unavailable. Explicitly add host vision or enable it in the automatic vision pool. Existing tasks retain their bindings. See function pools.

See the 0.2.6 release notes for upgrade steps and validation limits, and the CHANGELOG. Older-host support was restored in 0.2.5; image import arrived in 0.2.4, and music and Skills in 0.2.3.

Future work includes additional protocol adapters and creative workflows; see the roadmap.

Two ways to use Iris

	Path A: DSH plugin	Path B: Headless CLI
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
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)	Explicit task observe; 0.2.2 also offers bounded task wait
Dependencies	A DSH version in the compatibility matrix, and Node.js ≥ 22 meeting host requirements	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.

Optional legacy configuration import

For a new installation, add a provider or reference a DSH connection in the Iris workbench. Iris uses its own configuration and does not scan other projects by default.

If you already have an ai-paint configuration, set IRIS_IMPORT_WORKBENCH_CONFIG to its absolute file path for a one-time provider import. Iris leaves the source untouched and does not keep configurations synchronized. The variable holds a file path, not an API key. See the user guide for details.

Quickest start

Check the host with dsh --version and ensure pnpm is on your PATH. Iris and DSH have independent version numbers; Iris 0.2.6 retains the twelve exact hosts listed in the compatibility matrix.

Your DSH	Iris choice	Source
Exact 0.1.2 / 0.1.5 / 0.1.7 / 0.2 versions in the matrix	0.2.6	Pinned npm version
Versions outside the matrix	Not yet validated	Check the actual host interfaces

DSH plugin: install 0.2.6

Install the pinned release into your Web profile:

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

The plugin loads on the next DSH start. The web UI defaults to http://127.0.0.1:3080; open the complete URL if startup output includes authentication parameters. Reload the backend and refresh the web client after updating.

Standalone CLI: install 0.2.6

Install in your own project without DSH:

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

Download the package separately with npm pack @mokuyoaxis/dsh-iris@0.2.6. Users who need historical Iris0.1.4 can still pin it; see the matrix for its DSH/Node requirements. It lacks the current Core media CLI and later features.

Choosing a version in dsh-market

The marketplace entry should resolve to the full package name @mokuyoaxis/dsh-iris. Check its Iris version and your local dsh --version against the compatibility matrix for that release. Catalog and npm data may be cached. The actual package's top-level engines.dsh, Node requirement, and client peers define its 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", reference a DSH connection or enter your endpoint and key, and choose the media protocol. Synchronize the directory and confirm model uses; first-time setup can enable automatic selection in the same step. Selected-only mode still requires a list. See function pools and the user guide (Chinese).

Once configured, minimal instructions can be as simple as:

Use iris_draw_image: draw a white cat sitting by a blue window.
Summarize the image I just uploaded.
Summarize /absolute/path/demo.mp4 with Iris, then turn the summary into speech.

DSH profiles and plugin commands follow the official installation docs. Generating images, videos, or speech may incur provider charges.

For a copyable installation and usage prompt, see Agent quickstart prompt.

Feature overview

• Image generation, text-to-video, image-to-video, and S2V digital-human video
• Music generation, text-to-speech, and audio transcription
• Visual question answering, long-image OCR, target grounding, cropping, and pixel-diff analysis
• Video frame extraction and multimodal video summarization
• Asynchronous task tracking, restart recovery, and token-authorized media playback
• An independent work library that survives task-history cleanup and can re-index older outputs/
• A multi-provider model pool with per provider + model capability assignment
• Three file sources: browser upload, session attachments, and host paths
• Workbench-independent composer prompt optimization with current-session and JSON-configured fixed model routing

Prerequisites

• A Node.js version that satisfies your DeepSeek Harness release's requirement; Iris 0.2.x 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 for extracting frames or summarizing a video file; summaries of existing Core frames need neither

After installing the plugin, add a provider in the Iris workbench and assign models to the capabilities you need. Provider keys are kept in Iris's host-side configuration; on POSIX systems, Iris's own directories and files are tightened to 0700 and 0600 respectively, and neither the UI nor the API ever returns full keys. On Windows, file modes are not equivalent to ACLs — keep relying on your user directory and system account permissions.

DeepSeek Harness adaptation

dsh-iris remains a native DSH plugin. Iris 0.2.6 registers 17 agent tools, including import, editing, and music, and uses host routing, attachments, models, 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.

Save an uploaded or local image as a persistent Artifact for viewing, editing and export; see image import (Chinese).

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
0.2.2	Only 0.2.0-rc.2	Installed-service checks cover 15 tools and 31 boundaries; complete browser/mobile and real asynchronous restart acceptance remain pending
0.2.3	Only 0.2.0-rc.2	Adds music and a third skill; check actual loading with Host Doctor after upgrading
0.2.4	0.2.0-rc.2 or 0.2.1-alpha.4	17 tools / 3 skills; actual SDK, loader, and client slot isolation checks; full browser and hot reload checks remain separate
0.2.5	12 exact versions across the 0.1.2 / 0.1.5 / 0.1.7 / 0.2 lines; see the matrix	Official SDK isolation checks including Music and Qwen dispatch; old profiles also load the actual installed package
0.2.6	Retains the 12 exact versions declared in 0.2.5	Adds connection reuse, function pools and directories; connection reuse requires public host services; see this version's release notes

See the compatibility matrix for the current scope and rc.2 adaptation notes for historical changes. npm 0.1.4 does not contain these later adaptations.

Version 0.2.5 adapts to host API capabilities and declares support for the exact versions tested. Other versions need separate validation. Checks cover loading, tools, Skills, routes and client slots; full browser interaction and old-data upgrades remain separate. Doctor identifies the boundaries it can observe at runtime.

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.

Tools

Generation, speech, and tasks

Tool	Purpose
iris_draw_image	Generate images from a prompt
iris_import_image	Save a local or session image as a persistent Artifact for later operations
iris_edit_image	Edit a source Artifact with a chat image model or supported native Qwen edit model, preserving provenance
iris_generate_video	Text-to-video, image-to-video, or S2V digital-human video
iris_generate_music	Generate music from a description and save playable, downloadable audio
iris_speak_text	Synthesize speech from text
iris_transcribe_audio	Transcribe audio to text
iris_task_status	Check the status and outputs of one task or the recent tasks

Vision and image processing

Tool	Purpose
iris_look_at_image	Ask a question about an image and get a vision model's answer
iris_relook_attachment	Re-inspect an image attachment from the session with a new question
iris_long_ocr	Recognize text in tall screenshots or long images, chunk by chunk
iris_locate	Ground a target in an image and return pixel coordinates
iris_crop	Crop an image by pixel region
iris_pixel_diff	Compare two images and produce diff statistics and a heatmap
iris_html_screenshot	Render an HTML string to a screenshot in a restricted environment

Video processing

Tool	Purpose
iris_video_frames	Extract frames evenly from a video
iris_media_summarize	Summarize a video from sampled frames plus optional audio transcription

File inputs

Look, locate and OCR accept a local path, session attachment or Core image artifact_id; summaries can reuse frame_artifact_ids. Artifact inputs are read-only and checked against their MIME type and content hash. PNG/JPEG/WebP inputs need no manual JPEG conversion. See vision CLI.

Look, OCR chunks, locate and chat editing prepare sending copies using account/model budgets, with an 8 MiB default. Core originals, downloaded dimensions and hashes stay intact. OCR reports resizing and small-text risk; locate returns source-pixel coordinates. See input budgets.

Image editing uses a source Artifact ID and saves a linked new image through a chat image model or, in 0.2.4, supported native DashScope Qwen models. See Artifact editing and workbench management for supported models, filtering, selection, downloads and recovery.

Iris accepts three file sources, in the recommended order:

1. Browser upload — best for local files and cross-environment access; 64 MB per file.
2. Session attachments — best for reusing media already uploaded or generated in the current session.
3. Host paths — best for large files the host can read directly. Enter the path as seen by the host process; it is not always the path on the machine your browser runs on.

Uploads are stored under $DSH_HOME/iris/v1/uploads/ and kept for 7 days by default. For path-picking advice on different platforms, see File access across environments (Chinese).

Conversation prompt optimization

Version 0.2.2 extends per-operation rules, assembly without a model call and editable comparisons. It groups general, image creation, image editing, video and S2V targets in a collapsible section. The interface defaults to faithful grouping of original text in its original order; rewriting requires an explicit choice, and optional suggestions are fetched and adopted separately. Default instructions follow the project's Skills; custom v1 configuration and the existing text API remain compatible. Rules are not persisted and no standalone prompt CLI is added. See the prompt optimizer guide.

Iris adds a borderless, text-free “🫧” control directly to the DSH composer, so the workbench does not need to be open. It opens a translucent glass panel with background blur and soft depth; on narrow screens and Android browsers it becomes a safe-area-aware, internally scrollable bottom sheet. It reads only the current unsent plain-text draft. The result is previewed first and is written back only after confirmation; Iris never sends it automatically. Drafts containing structured @ or / references are left untouched for now so their identities are not lost.

By default, the optimizer uses the model selected for the current session and falls back to DSH's default model when the session has none. The request carries no chat history, tools, attachments, or workspace content—only the current draft and target template. To prevent reasoning tokens from exhausting the generation budget before visible text is complete, generation.reasoningEffort defaults to off-if-supported: reasoning is disabled only when DSH model metadata explicitly advertises such an effort; otherwise the provider default is used, and the session High/Low setting is not inherited. JSON may select provider-default, inherit, or an exact effort ID advertised by the model. For predictable cost and latency, use a fixed route with a lightweight non-reasoning model. You can also export prompt-optimizer.json, change route.mode to fixed, name another provider and model already registered in DSH, and import it again. “Reset to defaults” restores Iris's built-in prompt, target templates, session-model routing, and generation settings. The composer control can be disabled independently and re-enabled from the Iris workbench; disabling it does not stop the workbench, agent tools, or task runtime. An optimization call may incur charges from the selected text model.

Model assignment and failover

Iris organizes ordered model candidates by function. Capability assignments identify each executor with providerId::modelId; the same model name from a different provider or account is a separate option. Alibaba Cloud media calls may use a separate Workspace mediaBaseUrl.

Version 0.2.2 uses explicit function labels, legacy capability bindings, or provider capability metadata. Bare accounts and model names no longer grant capabilities. Discovery retains unlabelled models; assign their functions in the workbench or with CLI models caps. Existing explicit labels, assignment order and safe failover are preserved. Earlier 0.2.1 inference no longer grants capabilities to bare accounts or model names.

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, Core may only resume observation or delivery. The music entry point separately supports configured, bounded HTTP 502 retries as linked new tasks; these may consume extra quota and can be disabled with retry_502: 0. See Music.

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, Architecture, Security, and the Fault-injection matrix.

Transcription is a separate transcribe capability and does not consume the TTS or vision model configuration.

Capability health and model verification

The workbench and main bubble show gray for unconfigured, blue for unverified, green for success within seven days, and muted red for authentication or permission failures. The 0.2.2 also shows amber for temporary 429 cooldown and bright red for confirmed free quota or budget exhaustion, with a reason and recovery condition.

Iris performs no background probes. Temporary 429 responses use Retry-After, or a 60-second default cooldown. Expiry restores candidate eligibility without a verification request. Confirmed free quota or budget exhaustion persists across restarts until an explicit model test succeeds; test buttons remain available. Vision, image, and TTS have built-in test samples; video and transcription tests require real input through the CLI. Network errors, 5xx responses, content-safety failures, cancellation, and unknown acceptance do not overwrite recent success evidence. Host Doctor only checks loading and host ports. See Provider and capability health.

Offline diagnostics

No DSH installation or running host is required, and no provider request is sent:

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

The installed binary is dsh-iris. Exit code 0 is healthy, 1 means warnings, and 2 means hard errors. Offline Doctor checks Node.js, sharp, ffmpeg/ffprobe, a real but cleaned-up storage write probe, configuration, models/assignments, task semantics, temporary files, and orphaned or missing artifacts.

A running DSH instance also provides a “Host diagnostics” card and /iris/api/doctor JSON protected by Iris's Host and browser-origin guards. These guards do not authenticate users. Doctor checks the host version, plugin, 17 tools and three skills, four route groups, host capabilities, client version, and four UI slots. It reads safe registration evidence without calling Browser, models, or providers. See Host Doctor.

Composed workflow example

Three bundled skills guide single media operations, creative workflows, and UI acceptance. The existing "look → redraw → self-check" example below is one optional route: review follows the requested goal, useful outputs remain available, and music is an optional asset step.

The repository also carries SVG versions and editable drawio sources under docs/assets/diagrams/; the npm package ships only the PNGs shown above. Diagram labels are currently in Chinese.

Data and tasks

Runtime data lives under $DSH_HOME/iris/v1/ by default:

Location	Contents
providers.json	Providers, capability assignments, and redacted health evidence; file mode 0600
prompt-optimizer.json	Imported optimizer prompt, target templates, model route, and generation settings; file mode 0600
core-v0/	New tasks, attempts, Artifact objects, manifests and recoverable quarantine transactions
tasks.json	Legacy task metadata and attachment indexes; up to 500 records
artifacts.json	Legacy work-library index and random access tokens; no prompt, provider, or task relationship
outputs/	Legacy generated and processed media
uploads/	Temporary copies of browser uploads

On first load, 0.1.1 tightens POSIX permissions across an existing $DSH_HOME/iris/v1/ tree without modifying file contents or following symlinks. Large media downloads stream to a private temporary file and are moved into place atomically, instead of loading a whole video into memory.

Asynchronous tasks are polled in the background. After a plugin restart, Iris can re-adopt tasks that are still running remotely. Cancellation signals propagate through local waits and polling; whether the remote computation itself can be cancelled depends on the provider's API.

The work library has its own lifecycle: clearing terminal task history does not delete works, and older media can be recovered by re-indexing outputs/. Legacy deletion removes actual files with separate confirmation; see Work library v0. Core deletion uses preview and recoverable quarantine; see workbench management. Favorites, tags and search remain future work.

Legacy media links carry random capability tokens. Core media uses random Artifact IDs and host/browser origin guards. Images are, wherever possible, also saved as DSH durable attachments so they stay usable in the conversation.

Security notes

• Provider keys are never returned by status endpoints.
• 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.
• HTML screenshots render inside a sandboxed page without same-origin privileges; scripts and external network access are disabled by default.
• Legacy media links use random capability tokens; Core media reads verify Artifact content hashes. A host allowlist does not replace user authentication.
• Iris provides no account system of its own; multi-user isolation and access control are the responsibility of the DeepSeek Harness deployment.

Known limitations

• sharp bundles native components; glibc Linux, Windows, and macOS are the primary targets. Non-standard environments such as bare Termux may need extra work.
• Video-file frame extraction and summaries require system-installed ffmpeg and ffprobe; summaries of existing Core frames need neither.
• HTML screenshots load no remote scripts, fonts, or images; inline the resources you need first.
• Under WSL, containers, and remote deployments, browser paths usually cannot be handed to the host directly — prefer uploading files.
• Provider model lists are candidate sets only; whether a model truly supports a capability is settled by real calls.

Agent Skills

The DSH skill registry receives three bundled skills:

Skill	When to use
iris-use	Single generation/editing, vision/OCR, speech, music, task queries, and artifact delivery
iris-compose-media	Image revisions, video assets, narration, S2V, and optional music
iris-verify-ui	Interface reproduction and screenshot acceptance, including confirmed failure

Skills work independently of the session working directory. Project skills retain precedence, and tools still load when the registry is unavailable. All three use the shared capability and artifact contract.

To select a skill explicitly, use DSH's /name form:

/iris-use Generate a rock soundtrack and return its audio artifact and playback link

/iris-compose-media Inspect my uploaded product photo, create a matching poster, then verify the requested constraints

/iris-verify-ui Compare the current screenshot with the reference, locate regressions, and return an evidence-based verdict

Natural-language requests and direct tool calls remain available. iris-use guides single operations; composition guides multi-step work, with music added only when requested. Skills do not replace tool loading or model assignment, or alter task and cost-confirmation boundaries.

Development and verification

Run in the project directory:

npm test

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 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 first from docs/releases/<version>.md, otherwise from the matching CHANGELOG section), and npm publish happens when an NPM_TOKEN secret is configured. No local GitHub credentials are needed.

Documentation

• User guide (Chinese)
• Changelog (Chinese)
• Roadmap (Chinese)
• File access across environments (Chinese)
• Android 16 screenshot gallery
• Task/Attempt v2 semantics (Chinese)

License

MIT