简体中文 | English
Iris Media for DSH
A multimodal media production runtime · DSH plugin and standalone CLI
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](docs/MUSIC.md) (Chinese).
Iris 0.2.7 can [reference an existing DSH provider connection](docs/DSH_PROVIDER_CONNECTIONS.md) (Chinese), resolving its endpoint and API key per operation without storing a second key. It adds [automatic, selected-only, and disabled function pools](docs/FUNCTION_MODEL_POOLS.md) (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](docs/screenshots.md)
The project is at an early stage; interfaces and configuration formats may still change between releases.
This document describes **Iris 0.2.7**. Pin the version when installing or upgrading, and check the host compatibility range below first.
Iris 0.2.7 provides a DSH plugin and a headless CLI sharing tasks, artifacts and model routing. This release fixes host screenshots and adds persistent image workflows, a local API, and explicit Core Skill installation. Connection reuse, function pools, directory synchronization, and existing media features remain available. Core internals have not been frozen as a public SDK.
Version 0.2.7 includes host screenshot adaptation, address resolution, an explicit screenshot check, an internal application runtime with [DSH instance ownership](docs/DSH_RUNTIME.md), a [first persistent image-edit workflow](docs/IMAGE_FLOW.md), a [local API that is read-only by default](docs/LOCAL_API.md), and [explicit local uploads and Run creation](docs/LOCAL_CREATION.md) (Chinese); see the [0.2.7 release notes](docs/releases/0.2.7.md). The source checkout retains a [standalone web demo for 0.3.0](docs/WEB_PROTOTYPE.md) (Chinese) to show the intended workflow. UI and interaction polish is deferred to the 0.3.0 development phase. The demo uses built-in samples without model calls or charges; execution/cancellation APIs and real workbench integration remain on the [0.3 roadmap](docs/ROADMAP.md#03-及以后).
> Version support: Iris 0.2.7 retains the 12 exact DSH versions declared in 0.2.5; see the [compatibility matrix](docs/DSH_COMPATIBILITY.md). 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.7 and existing features
**Improve host screenshots and use image workflows and Skills outside DSH.** Function pools retain stable priority and safe failover, without cross-request round-robin.
- **Host screenshots:** consume PNG data through Core, respect browser download-directory restrictions, use actual listening metadata, and offer an explicit screenshot check.
- **Image workflows and local API:** persist CLI steps, tasks, comparisons, and selection. The API is read-only by default; uploads and creation require opt-in, while HTTP execution/cancellation remain future work.
- **Core Skill installation:** distribute `iris-core` with CLI image guidance; explicitly install to Kimi or a supplied scan directory, preserve local changes, and archive managed updates/removals.
- **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](docs/FUNCTION_MODEL_POOLS.md).
See the [0.2.7 release notes](docs/releases/0.2.7.md) for upgrade steps and validation limits, and the [CHANGELOG](CHANGELOG.md). Older-host support was restored in [0.2.5](docs/releases/0.2.5.md); image import arrived in [0.2.4](docs/releases/0.2.4.md), and music and Skills in [0.2.3](docs/releases/0.2.3.md).
Future work includes additional protocol adapters and creative workflows; see the [roadmap](docs/ROADMAP.md#后续功能方向).
## 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](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) | 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` (`ffmpeg` and `ffprobe` 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 or export artifacts, and vice versa. Read-only inspection can coexist with a writer; export is a write operation and returns busy if that data root already has a writer.
> Image processing depends on `sharp` and its platform binaries. Failure to load `sharp` can also prevent the CLI or plugin from starting. Repair the dependency installation first, then run `dsh-iris doctor` to check the environment.
## 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](user_guide.md) 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.7 retains the twelve exact hosts listed in the [compatibility matrix](docs/DSH_COMPATIBILITY.md).
| Your DSH | Iris choice | Source |
|---|---|---|
| Exact 0.1.2 / 0.1.5 / 0.1.7 / 0.2 versions in the matrix | `0.2.7` | Pinned npm version |
| Versions outside the matrix | Not yet validated | Check the actual host interfaces |
### DSH plugin: install 0.2.7
Install the pinned release into your Web profile:
```bash
dsh plugin --profile web add @mokuyoaxis/dsh-iris@0.2.7
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.7
Install in your own project without DSH:
```bash
npm install @mokuyoaxis/dsh-iris@0.2.7
npx dsh-iris --help
```
Download the package separately with `npm pack @mokuyoaxis/dsh-iris@0.2.7`. 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](docs/DSH_COMPATIBILITY.md) 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](docs/FUNCTION_MODEL_POOLS.md) and the [user guide](user_guide.md) (Chinese).
Once configured, minimal instructions can be as simple as:
```text
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](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
- 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.7 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](docs/IMAGE_IMPORT.md) (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.7` | Retains the 12 exact versions declared in 0.2.6 | Screenshot fixes, instance runtime, image workflows, local API, and Core Skill; standalone Web remains a source-only demo |
| `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 that release's notes |
See the [compatibility matrix](docs/DSH_COMPATIBILITY.md) for the current scope and [rc.2 adaptation notes](docs/DSH_RC2_ADAPTATION.md) 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](docs/ROADMAP.md).
## 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](docs/VISION_CLI.md).
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](docs/CLI_MANAGEMENT.md#看图输入预算).
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](docs/CLI_MANAGEMENT.md#artifact-聊天改图) and [workbench management](docs/WORKBENCH_ARTIFACTS.md) 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](docs/file-access-across-environments.md) (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](docs/PROMPT_OPTIMIZER.md).
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](docs/MUSIC.md).
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).
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](docs/PROVIDER_HEALTH.md).
## Offline diagnostics
No DSH installation or running host is required, and no provider request is sent:
```bash
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](docs/HOST_DOCTOR.md).
## 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/`](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](docs/ARTIFACT_LIBRARY.md). Core deletion uses preview and recoverable quarantine; see [workbench management](docs/WORKBENCH_ARTIFACTS.md). 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
Version 0.2.7 adds a host-independent [`iris-core`](skills/iris-core/SKILL.md) for image import, generation, editing, and retrieval through the existing standalone CLI. Instructions are in English with Chinese titles. Explicit `skills install/status/uninstall` commands support Kimi or a supplied scan directory, preserve local changes, and archive managed updates/removals. See [loading and scope](docs/CORE_SKILLS.md). These resources and commands ship in npm 0.2.7. The three DSH skills below remain registered as before; a formal MCP integration is still future work.
The DSH skill registry receives three bundled skills:
| Skill | When to use |
|---|---|
| [`iris-use`](.dsh/skills/iris-use/SKILL.md) | Single generation/editing, vision/OCR, speech, music, task queries, and artifact delivery |
| [`iris-compose-media`](.dsh/skills/iris-compose-media/SKILL.md) | Image revisions, video assets, narration, S2V, and optional music |
| [`iris-verify-ui`](.dsh/skills/iris-verify-ui/SKILL.md) | 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](.dsh/skills/iris-use/references/media-contract.md).
To select a skill explicitly, use DSH's `/name` form:
```text
/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/.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](user_guide.md) (Chinese)
- [Changelog](CHANGELOG.md) (Chinese)
- [Roadmap](docs/ROADMAP.md) (Chinese)
- [File access across environments](docs/file-access-across-environments.md) (Chinese)
- [Android 16 screenshot gallery](docs/screenshots.md)
- [Task/Attempt v2 semantics (Chinese)](docs/TASK_SEMANTICS.md)
## License
[MIT](LICENSE)