@mokuyoaxis/dsh-iris 0.1.0 → 0.1.2

package/CHANGELOG.md

@@ -6,6 +6,75 @@
 
 当前没有尚未发布的用户可见变更。
 
+## [0.1.2] - 2026-09-06
+
+### Changed
+
+- 提示词优化器不再默认继承主会话的 High/Low thinking 档位；新增 `generation.reasoningEffort` 策略，默认在模型元数据明确支持时关闭推理，并在面板显示思考策略与输出预算，降低推理 token 挤占正文和意外增费的风险。
+
+- 提示词优化器按 DSH `modelSelection.current` 投影读取当前会话模型，避免界面已有选择时仍误回退为“DSH 默认模型”。
+
+- 对外展示名使用 “Iris Media for DSH”，npm 包名继续保留为 `@mokuyoaxis/dsh-iris`，安装文档始终使用完整 scoped 名称。
+
+### Added
+
+- 新增独立于 Iris 工作台的 DSH 对话框提示词优化器：输入区只保留无边框、无文字的 🫧 入口，进入带背景模糊和柔和光影的半透明玻璃悬浮窗；窄屏自动切换为安全区自适应、可内部滚动的底部面板。支持通用、图片、视频和首尾帧视频目标，默认使用当前会话模型，先预览后写回且绝不自动发送。
+
+- 新增独立的 `prompt-optimizer.json` 配置：面板可导入/导出 JSON、固定其他 DSH provider/model、一键恢复 Iris 默认 Prompt，并可单独关闭对话入口；入口关闭后工作台、Agent 工具和任务后台继续运行。
+
+- 插件启用时通过 DSH Skill registry 自动注册随包的 `iris-verify-ui` 与 `iris-compose-media`；用户无需克隆本仓库或把会话工作目录切到 Iris。
+
+- README 首屏新增一张可追溯到供应商、模型与提示词的真实 Iris 生成图片。
+
+- 新增 Android 16 真机截图画廊，记录通用提示词优化、图片 Prompt 优化、写回、任务成功和实际产物；公开副本统一移除 EXIF/XMP/IPTC 元数据。中英文 README 直接展示三张关键截图，根目录 `screenshots.json` 为插件市场声明四张精选素材。
+
+- README 新增三张示意图：插件架构总览、生成任务生命周期与受理边界，以及「看图 → 重绘 → 自检」组合工作流示例（附 SVG 与可编辑 drawio 源文件）。
+
+- 新增英文版 `README.en.md` 并在两份 README 顶部互设语言切换链接；npm 包清单纳入英文版。
+
+- 新增 `scripts/gen-diagrams.mjs`：README 三张示意图由单一脚本再生成，每次运行同步产出 PNG、SVG 与可编辑 drawio 源文件。
+
+### Fixed
+
+- 泡泡快捷任务不再混入失败、取消或无产物的旧记录，只显示当前运行任务与最近成功产物；完整历史和错误仍保留在 Iris 工作台。
+
+- 常用区与 Iris 工作台的功能状态灯改为挂载后直接读取共享供应商状态：启用的 API 且具备相应能力时常驻绿色，不再要求逐张点开卡片；当前执行报错后立即变暗。
+
+- Cordis 运行时行 ID 改为唯一的 `mokuyoaxis-dsh-iris`，避免与另一款 `dsh-iris` 插件同装时按短 ID 相互覆盖；文档说明手动 profile 覆盖的迁移方式。
+
+### Security
+
+- 随包 Skill 直接从已安装的 Iris 包读取，不扫描额外项目或用户目录，也不改变默认 filesystem Skill provider 配置。
+
+## [0.1.1] - 2026-09-05
+
+### Changed
+
+- 明确 ai-paint 是维护者未公开的本地前身而非用户依赖；插件默认启动不再读取其固定路径，仅在用户显式设置 `IRIS_IMPORT_WORKBENCH_CONFIG` 时由宿主本地一次性导入，已有供应商时跳过。
+- `npm test` 使用 Node.js 调度器，移除 POSIX Shell 循环，保留逐文件进程隔离和失败即停。
+- 对齐公开路线图与 `v0.1.0` 标签，区分当前 DSH 插件能力和未来宿主无关 Core/CLI/工作台。
+- 工作台新增安全的媒体协议自动判断与显式选择；模型实测改为按能力触发，真实调用前确认，视频与转写不再提交空样本探针。
+- 测试临时目录改用系统 API 并自动清理；`ffmpeg` 探测不再依赖 POSIX `which`。
+- 增加 Linux/Windows × Node.js 20.10/22 CI 矩阵和发布前完整测试钩子。
+- 新增标签驱动的 Release 工作流：推送 `vX.Y.Z` 标签即自动跑全量测试、校验标签与 package.json 版本一致、创建附 tarball 的 GitHub Release 并发布 npm（含 provenance；未配置 `NPM_TOKEN` 时仅跳过 npm 发布）。
+- Node.js 最低版本调整为 20.10；20.9 无法解析当前图片依赖使用的 JSON import attributes。
+
+### Fixed
+
+- 修复 DSH 0.1.2+ Web 客户端按完整 npm 包名校验时，Iris 仍以旧短名注册而导致整个插件组合包加载失败的问题；同时将客户端依赖声明对齐新版的 Renderer/Session 服务。
+- 旧配置为 `null` 或供应商凭据字段类型错误时，跳过无效内容而不使导入崩溃。
+- 语法合法但根节点、供应商、模型、任务或分配结构错误的持久化文件现在会被隔离并安全重建，不再静默丢失后续更新。
+- 大媒体下载改为流式原子落盘，避免把完整视频一次性载入内存，并清理失败的临时文件。
+- Windows CI：Skill 测试先归一化 CRLF 再解析 frontmatter，并新增 `.gitattributes` 强制所有平台以 LF 检出（Windows runner 默认 `core.autocrlf=true` 曾致 `npm test` 失败）。
+- Windows CI：`tests/pixels.mjs` 改用 `fileURLToPath` 解析模块路径；`URL.pathname` 在 Windows 上返回 `/D:/...`，拼出的非法临时目录路径使该测试进程直接崩溃。
+- 上传接口竞态：写入流改为惰性创建、`.part` 清理等待 fd 关闭，空上传或提前失败的请求不再可能残留孤儿 `.part` 文件。
+
+### Security
+
+- DashScope 凭据在网络请求发出前绑定到阿里云官方 HTTPS 域名，阻止错误协议配置把 API Key 发给第三方端点。
+- POSIX 上统一以 `0700` 目录和 `0600` 文件保存 Iris 配置、任务、上传及产物；启动时收紧既有 Iris 树且不跟随符号链接。
+- `/iris/*` 默认只接受回环 Host；LAN/反向代理需显式配置 `IRIS_TRUSTED_HOSTS`，公开文档明确该列表不替代身份认证。
+
 ## [0.1.0] - 2026-09-04
 
 ### Added
@@ -49,5 +118,7 @@
 - 上传采用流式限额、临时 `.part` 文件和原子落盘，失败时会清理未完成文件。
 - 修改状态的路由拒绝明确的跨站请求，媒体文件继续使用随机能力令牌访问。
 
-[Unreleased]: https://github.com/mokuyoaxis/dsh-iris/compare/v0.1.0...HEAD
+[Unreleased]: https://github.com/mokuyoaxis/dsh-iris/compare/v0.1.2...HEAD
+[0.1.2]: https://github.com/mokuyoaxis/dsh-iris/compare/v0.1.1...v0.1.2
+[0.1.1]: https://github.com/mokuyoaxis/dsh-iris/compare/v0.1.0...v0.1.1
 [0.1.0]: https://github.com/mokuyoaxis/dsh-iris/releases/tag/v0.1.0

package/README.en.md

@@ -0,0 +1,245 @@
+<p align="center">
+  <sub><a href="README.md">简体中文</a> | English</sub>
+</p>
+
+<p align="center">
+  <img src="docs/assets/iris-wordmark.svg" width="520" alt="IRIS wordmark">
+</p>
+
+<h1 align="center">Iris Media for DSH</h1>
+
+<p align="center"><strong>A multimodal media production runtime · currently shipped as a DeepSeek Harness plugin</strong></p>
+
+<p align="center">
+  <a href="#deepseek-harness-adaptation"><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://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>
+
+dsh-iris gives agents and the Iris workbench image, video, speech, and visual understanding capabilities, and it can optimize any draft directly in the DSH composer. It connects to Alibaba Cloud DashScope (Bailian) and to OpenAI Images–compatible services. Configuration and task management live in the Iris workbench, and a floating Iris bubble in the bottom-right corner is the quick entry point.
+
+## A real generation example
+
+<p align="center">
+  <img src="docs/assets/examples/iris-flower-generated.webp" width="720" alt="A violet-blue iris generated from a prompt optimized by Iris">
+</p>
+
+> 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 |
+|---|---|
+| ![Iris bubble control in the DSH composer](docs/assets/screenshots/prompt-general-before.webp) | ![Iris writes the optimized prompt back to the DSH composer](docs/assets/screenshots/prompt-general-after.webp) |
+
+<p align="center">
+  <img src="docs/assets/screenshots/image-task-succeeded.webp" width="520" alt="Succeeded image task in the Iris workbench">
+</p>
+
+> [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.
+
+Iris's long-term direction is a media production core that can run on its own and plug into different agent hosts. DeepSeek Harness is the first supported host, and the current version still requires DSH — a standalone Core, CLI, and workbench are on the roadmap but not yet available.
+
+## Relationship with ai-paint
+
+`ai-paint` is the maintainer's local, unpublished predecessor of Iris. It is not a public dependency, and users never need to download, install, or create it. Without that project, simply configure providers in the Iris workbench as described below.
+
+Early versions read models and credentials from the maintainer's local ai-paint configuration — partly to migrate the predecessor project, and partly so the host process could reuse an existing API key locally instead of pasting keys into agent sessions, command-line arguments, or documents. Version 0.1.1 separates the two configurations completely: Iris uses only its own configuration. The old one can be imported exactly once, and only by explicitly setting `IRIS_IMPORT_WORKBENCH_CONFIG` to the absolute path of the local config file. Iris never scans for ai-paint by default and never syncs the two sides. The variable carries a file path, not an API key, and the source file is left untouched. See the [user guide](user_guide.md) for details.
+
+## Quickest start
+
+With DeepSeek Harness `0.1.2-rc.1` installed and `pnpm` on your PATH, add Iris to the Web profile:
+
+```bash
+dsh plugin --profile web add @mokuyoaxis/dsh-iris
+dsh web
+```
+
+> 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.
+
+To try it from a source checkout, replace `@mokuyoaxis/dsh-iris` in the first command with `.`. The plugin loads the next time DSH starts; the web UI defaults to `http://127.0.0.1:3080`.
+
+After the first start, open "Settings → Iris workbench → + Add provider", enter your DashScope base URL and API key, then click "Discover models". A single provider can start with automatic capability assignment. Full steps, OpenAI Images–compatible configuration, and failover notes are in 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.
+
+## Feature overview
+
+![Iris architecture overview](docs/assets/diagrams/iris-architecture.png)
+
+- Image generation, text-to-video, image-to-video, and S2V digital-human video
+- 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
+- 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; dsh-iris itself requires at least 20.10
+- A working DeepSeek Harness environment with `pnpm` on the PATH
+- At least one supported media or vision provider
+- `ffmpeg` and `ffprobe` on the system, for video frame extraction and video summaries
+
+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 ships as a native DSH plugin with a server side and a web client. The server registers 14 agent tools and reuses the host's tool, routing, and lifecycle services; the client hooks into the settings page, the conversation input area, and the global floating layer through DSH's module loader. The plugin never starts a separate service or listens on an extra port.
+
+Automated tests currently cover plugin loading, tool registration, client seats, and routing behavior. Version 0.1.1 completed host smoke tests on Linux ARM64 — in both a clean and a real web profile — against DSH `0.1.2-rc.1` on Node.js `22.23.2`: the browser startup graph, the full combined bundle, the Iris client factory, and the three UI seats present at that time were verified. The fourth prompt-optimizer seat added in 0.1.2 has now been rendered in a live Android browser; configuration loading, a real session-model optimization with thinking actually `off`, preview write-back, independent disabling and re-enabling, and the loop from a short draft to a succeeded image-generation task are verified. Browser-side cancellation and JSON operations have automated HTTP/configuration coverage; a step-by-step live-device record is still pending. Iris itself keeps Node.js `>=20.10` as its own floor.
+
+Iris 0.1.1–0.1.2 explicitly supports DSH `>=0.1.2-rc.1 <0.1.3-0` and no longer works with the legacy client runtime of DSH 0.1.0/0.1.1. DSH is still evolving quickly; later preview versions must pass verification before the supported range widens, and the compatibility badge is not an official certification. If DSH requires a newer Node.js, DSH wins.
+
+## Tools
+
+### Generation, speech, and tasks
+
+| Tool | Purpose |
+|---|---|
+| `iris_draw_image` | Generate images from a prompt |
+| `iris_generate_video` | Text-to-video, image-to-video, or S2V digital-human video |
+| `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
+
+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
+
+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 to prevent overlap and overflow. It reads only the current unsent plain-text draft and offers general, image, video, and start-to-end-frame video targets. 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
+
+Capability assignment uses `providerId::modelId` as the model identity. The same model name from a different provider or account counts as two independent options.
+
+Generation capabilities accept multiple candidate models. Iris only tries the next candidate when the upload, the submission, or a synchronous generation fails; once a remote service has accepted a task, Iris never resubmits it automatically — that is how duplicate tasks and double billing are avoided. Accepted asynchronous tasks remain under the task system's watch.
+
+![Task lifecycle and acceptance boundary](docs/assets/diagrams/iris-task-lifecycle.png)
+
+Transcription is a separate `transcribe` capability and does not consume the TTS or vision model configuration.
+
+## Composed workflow example
+
+Iris ships two agent skills (`iris-verify-ui` and `iris-compose-media`) that chain multiple tools into bounded, reviewable media workflows. The example below is "look → redraw → self-check": understand the source image first, then generate, review against concrete mismatches, and only deliver once the review passes.
+
+![Composed workflow example](docs/assets/diagrams/iris-workflow-compose.png)
+
+SVG versions and editable drawio sources of the figures above live in [`docs/assets/diagrams/`](docs/assets/diagrams/). Diagram labels are currently in Chinese.
+
+## Data and tasks
+
+Runtime data lives under `$DSH_HOME/iris/v1/` by default:
+
+| Location | Contents |
+|---|---|
+| `providers.json` | Providers and capability assignments; file mode 0600 |
+| `prompt-optimizer.json` | Imported optimizer prompt, target templates, model route, and generation settings; file mode 0600 |
+| `tasks.json` | Task metadata and attachment indexes; up to 500 records |
+| `outputs/` | 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.
+
+Audio and video are served through Iris media links that carry random capability tokens. 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 domains; any other base URL defaults 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.
+- Media links use random capability tokens, and file paths are resolved only from task records.
+- 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 frame extraction and video summaries require system-installed `ffmpeg` and `ffprobe`.
+- 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
+
+When the plugin is enabled, it automatically registers the two bundled skills through the DSH skill registry:
+
+| Skill | When to use |
+|---|---|
+| [`iris-verify-ui`](.dsh/skills/iris-verify-ui/SKILL.md) | Combine screenshots, semantic inspection, element grounding, cropping, and pixel comparison into evidence-based UI acceptance |
+| [`iris-compose-media`](.dsh/skills/iris-compose-media/SKILL.md) | Chain two or more Iris tools into media workflows: inspect-then-draw, image-to-video, video summary with narration, S2V, and more |
+
+From 0.1.2, as long as the host provides the DSH skill registry, regular npm installs can discover and load both skills from any project directory — no need to clone this repository or configure a skill search path. When the project directory contains same-name skills, DSH's native precedence keeps using the project versions; if the skill registry is unavailable, the 14 Iris tools still load on their own.
+
+## 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 20.10/22 matrix, 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 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)
+
+## License
+
+[MIT](LICENSE)

package/README.md

@@ -1,32 +1,68 @@
+<p align="center">
+  <sub>简体中文 | <a href="README.en.md">English</a></sub>
+</p>
+
 <p align="center">
   <img src="docs/assets/iris-wordmark.svg" width="520" alt="IRIS 彩色字标">
 </p>
 
-<h1 align="center">dsh-iris</h1>
+<h1 align="center">Iris Media for DSH</h1>
 
-<p align="center"><strong>DeepSeek Harness 的多供应商媒体与视觉工具箱</strong></p>
+<p align="center"><strong>Iris 多模态生产运行时 · 当前通过 DeepSeek Harness 插件使用</strong></p>
 
 <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="CHANGELOG.md"><img alt="Version 0.1.0" src="https://img.shields.io/badge/version-0.1.0-7C5CFC.svg?style=flat-square"></a>
-  <a href="https://nodejs.org/"><img alt="Node.js 20.9 or newer" src="https://img.shields.io/badge/Node.js-%3E%3D20.9-339933.svg?style=flat-square&amp;logo=nodedotjs&amp;logoColor=white"></a>
-  <a href="#开发与验证"><img alt="npm test" src="https://img.shields.io/badge/tests-npm%20test-2EA44F.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://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>
 
-dsh-iris 为 Agent 和 Iris 工作台提供图像、视频、语音与视觉理解能力。它可以连接 DashScope 百炼及 OpenAI Images 兼容服务；完整配置和任务管理集中在 Iris 工作台，右下角的 Iris 泡泡提供快捷入口。
+dsh-iris 为 Agent 和 Iris 工作台提供图像、视频、语音与视觉理解能力，也能直接优化 DSH 对话框中的任意提示词。它可以连接 DashScope 百炼及 OpenAI Images 兼容服务；完整配置和任务管理集中在 Iris 工作台，右下角的 Iris 泡泡提供快捷入口。
+
+## 实际生成示例
+
+<p align="center">
+  <img src="docs/assets/examples/iris-flower-generated.webp" width="720" alt="由 Iris 优化提示词并生成的蓝紫色鸢尾花">
+</p>
+
+> 从一句“鸢尾花”开始：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 元数据。
+
+| 对话输入区的 🫧 入口 | 优化结果写回输入框 |
+|---|---|
+| ![DSH 对话输入区中的 Iris 泡泡入口](docs/assets/screenshots/prompt-general-before.webp) | ![Iris 将优化结果写回 DSH 输入框](docs/assets/screenshots/prompt-general-after.webp) |
+
+<p align="center">
+  <img src="docs/assets/screenshots/image-task-succeeded.webp" width="520" alt="Iris 工作台中的图片任务成功详情">
+</p>
+
+> [查看完整六图流程：优化前、玻璃预览窗、写回、任务成功与实际产物](docs/screenshots.md)
 
 项目目前处于早期版本，接口和配置格式仍可能随版本迭代调整。
 
+Iris 的长期方向是可独立运行、可接入不同 Agent 宿主的媒体生产核心。DeepSeek Harness 是首个受支持宿主；当前版本仍需要 DSH，独立 Core、CLI 和工作台属于后续路线，尚未提供。
+
+## 与 ai-paint 的关系
+
+`ai-paint` 是 Iris 维护者本机未公开的前身项目，不是 Iris 的公开依赖，也不是用户需要下载、安装或自行创建的目录。没有该项目的用户直接按下文在 Iris 工作台配置供应商即可。
+
+早期版本从维护者本机的 ai-paint 配置读取模型与凭据，既用于迁移前身项目，也让宿主进程可以在本地复用已有 API Key，避免为迁移而把密钥粘贴到 Agent 会话、命令行参数或文档中。0.1.1 将两者的配置彻底分离：Iris 只使用自己的配置；旧配置仅可通过把 `IRIS_IMPORT_WORKBENCH_CONFIG` 显式设为本地配置文件的绝对路径进行一次性导入，不会默认扫描 ai-paint，也不会在两边同步。该变量保存的是文件路径而不是 API Key，来源文件不会被修改；具体操作见[用户指南](user_guide.md#从旧工作台显式导入)。
+
 ## 最快开始
 
-已经安装 DeepSeek Harness 且 `pnpm` 在 PATH 中时，把 Iris 加入 Web profile：
+已经安装 DeepSeek Harness `0.1.2-rc.1` 且 `pnpm` 在 PATH 中时，把 Iris 加入 Web profile：
 
 ```bash
 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 兼容配置和故障转移说明见[用户指南](user_guide.md)。
@@ -43,6 +79,8 @@ DSH 的 profile 与插件命令由[官方安装说明](https://github.com/deepse
 
 ## 功能概览
 
+![Iris 架构总览](docs/assets/diagrams/iris-architecture.png)
+
 - 图像生成、文生视频、图生视频和 S2V 数字人视频
 - 文本转语音与音频转写
 - 看图问答、长图 OCR、目标定位、裁剪和像素差异分析
@@ -50,21 +88,24 @@ DSH 的 profile 与插件命令由[官方安装说明](https://github.com/deepse
 - 异步任务跟踪、重启恢复和带授权令牌的媒体播放
 - 多供应商模型池，以及按 `供应商 + 模型` 分配能力
 - 浏览器上传、会话附件和宿主路径三种文件来源
+- 独立于工作台的对话框提示词优化，支持当前会话模型与 JSON 固定模型路由
 
 ## 使用前准备
 
-- 满足所用 DeepSeek Harness 版本要求的 Node.js；dsh-iris 自身最低为 20.9
+- 满足所用 DeepSeek Harness 版本要求的 Node.js；dsh-iris 自身最低为 20.10
 - 一个可用的 DeepSeek Harness 环境，以及 PATH 中的 `pnpm`
 - 至少一个受支持的媒体或视觉服务供应商
 - 使用视频抽帧和视频摘要时，需要系统提供 `ffmpeg` 与 `ffprobe`
 
-安装插件后，在 Iris 工作台中添加供应商并为所需能力分配模型。供应商密钥只保存在宿主侧，界面和接口不会返回完整密钥。
+安装插件后，在 Iris 工作台中添加供应商并为所需能力分配模型。供应商密钥保存在宿主侧的 Iris 配置中；POSIX 系统上 Iris 自有目录和文件分别收紧为 `0700` 与 `0600`，界面和接口不会返回完整密钥。Windows 的 mode 不等同于 ACL，仍需依赖当前用户目录和系统账户权限。
 
 ## DeepSeek Harness 适配
 
 dsh-iris 按 DeepSeek Harness 插件形态提供服务端与 Web 客户端入口：服务端注册 14 个 Agent 工具，并复用宿主的工具、路由和生命周期服务；客户端通过 DSH 模块加载器接入设置页、会话输入区和全局悬浮层。插件不会启动独立服务或额外监听端口。
 
-当前自动化测试覆盖插件装载、工具注册、客户端槽位和路由行为。由于项目尚未声明 DSH 的最低或最高版本，兼容徽章表示项目已按当前 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` 为最低基线。
+
+Iris 0.1.1–0.1.2 明确支持 DSH `>=0.1.2-rc.1 <0.1.3-0`，不再兼容 0.1.0/0.1.1 的旧客户端 Runtime。DSH 仍在快速演进，后续预览版须经验证后再扩大范围；兼容徽章不代表官方认证。若 DSH 要求更高 Node 版本，以 DSH 为准。
 
 ## 工具
 
@@ -107,14 +148,30 @@ Iris 支持三种文件来源，推荐顺序如下：
 
 上传内容保存在 `$DSH_HOME/iris/v1/uploads/`，默认保留 7 天。不同系统下的路径选择建议见[文件访问与跨环境](docs/file-access-across-environments.md)。
 
+## 对话框提示词优化
+
+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 只会在上传、提交或同步生成阶段失败时尝试下一个候选项；远端服务一旦受理任务，就不会自动重新提交，以免产生重复任务或重复计费。已经受理的异步任务由任务系统继续跟踪。
 
+![生成任务生命周期与受理边界](docs/assets/diagrams/iris-task-lifecycle.png)
+
 转写是独立的 `transcribe` 能力，不会占用 TTS 或视觉能力的模型配置。
 
+## 组合工作流示例
+
+Iris 自带两个 Agent Skills（`iris-verify-ui` 与 `iris-compose-media`），把多个工具编排成有界、可复核的媒体工作流。下例是「看图 → 重绘 → 自检」：先理解原图，再生成，复核针对具体偏差，只有复核通过才交付。
+
+![组合工作流示例](docs/assets/diagrams/iris-workflow-compose.png)
+
+图的 SVG 版本与可编辑 drawio 源文件位于 [`docs/assets/diagrams/`](docs/assets/diagrams/)。
+
 ## 数据与任务
 
 运行数据默认位于 `$DSH_HOME/iris/v1/`：
@@ -122,10 +179,13 @@ Iris 支持三种文件来源，推荐顺序如下：
 | 位置 | 内容 |
 |---|---|
 | `providers.json` | 供应商和能力分配，文件权限为 0600 |
+| `prompt-optimizer.json` | 用户导入的优化 Prompt、目标模板、模型路由和生成参数，文件权限为 0600 |
 | `tasks.json` | 任务元数据和附件索引，最多保留 500 条 |
 | `outputs/` | 生成和处理后的媒体文件 |
 | `uploads/` | 浏览器上传的临时输入副本 |
 
+0.1.1 首次装载时会收紧既有 `$DSH_HOME/iris/v1/` 树的 POSIX 权限，不修改文件内容，也不跟随符号链接。大媒体下载采用流式私有临时文件与原子替换，不再把整段视频载入内存。
+
 异步任务会在后台轮询。插件重启后，可以继续接管仍在远端执行的任务。取消信号会传递到本地等待与轮询流程；是否能取消远端计算，取决于供应商接口。
 
 音频和视频通过带随机令牌的 Iris 媒体链接访问。图片会尽量转存为 DSH 持久附件，方便在会话中继续使用。
@@ -133,7 +193,10 @@ Iris 支持三种文件来源，推荐顺序如下：
 ## 安全说明
 
 - 供应商密钥不会通过状态接口返回。
-- 修改状态的 HTTP 请求会检查跨站来源，降低第三方页面触发付费操作的风险。
+- DashScope 媒体协议只允许把密钥发送到阿里云官方 HTTPS 域名；其他 Base URL 默认推断为 OpenAI Images 兼容协议。
+- `/iris/*` 默认只接受回环 Host；LAN 或反向代理必须显式设置 `IRIS_TRUSTED_HOSTS`，修改状态的请求还会检查跨站来源。
+- `IRIS_TRUSTED_HOSTS` 不是认证机制。对公网或不可信网络开放 DSH 时，必须在反向代理或宿主层配置身份认证与 HTTPS。
+- 模型实测只按单项能力运行，并在真实供应商调用前确认；视频和转写不会用空样本自动提交付费探针。
 - HTML 截图在不具备同源权限的沙箱页面中渲染，脚本和外部网络默认不可用。
 - 媒体链接使用随机能力令牌，文件路径只从任务记录解析。
 - Iris 不提供独立账号体系，多用户隔离和访问控制由 DeepSeek Harness 部署负责。
@@ -148,14 +211,14 @@ Iris 支持三种文件来源，推荐顺序如下：
 
 ## Agent Skills
 
-源码和 npm 包附带两个仓库级预览 Skill：
+插件启用时会通过 DSH Skill registry 自动注册两个随包 Skill：
 
 | Skill | 适用场景 |
 |---|---|
 | [`iris-verify-ui`](.dsh/skills/iris-verify-ui/SKILL.md) | 组合截图、语义检查、元素定位、裁剪和像素比较，完成有证据的 UI 验收 |
 | [`iris-compose-media`](.dsh/skills/iris-compose-media/SKILL.md) | 组合两个以上 Iris 工具，完成看图后绘图、图片转视频、视频总结配旁白或 S2V 等媒体工作流 |
 
-当 DSH 会话以本仓库为项目目录且启用了文件系统 Skill 服务时，可以直接发现它们。当前版本尚未在插件启用时自动向其他项目注册这些 Skill；14 个 Iris 工具不受影响。
+从 0.1.2 起，只要宿主提供 DSH Skill registry，普通 npm 安装用户在任意项目目录中都能发现并加载它们，不需要克隆本仓库或另外配置 Skill 搜索目录。项目目录中存在同名 Skill 时，仍按 DSH 原生优先级使用项目版本；Skill registry 不可用时，14 个 Iris 工具仍可独立装载。
 
 ## 开发与验证
 
@@ -165,12 +228,17 @@ Iris 支持三种文件来源，推荐顺序如下：
 
 测试覆盖配置合并、模型身份、任务生命周期、生成动作、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 凭据。
+
 ## 文档
 
 - [用户指南](user_guide.md)
 - [变更记录](CHANGELOG.md)
 - [路线图](docs/ROADMAP.md)
 - [文件访问与跨环境](docs/file-access-across-environments.md)
+- [Android 16 真机截图画廊](docs/screenshots.md)
 
 ## License
 

package/cordis.patch.yml

@@ -1,3 +1,3 @@
 - insert:
-    - id: dsh-iris
+    - id: mokuyoaxis-dsh-iris
       name: '@mokuyoaxis/dsh-iris'