npm - deepseek-harness-intelligent-ui - Versions diffs - 0.2.2 → 0.2.3 - Mend

deepseek-harness-intelligent-ui 0.2.2 → 0.2.3

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (6) hide show

package/CHANGELOG.md CHANGED Viewed

@@ -6,6 +6,13 @@ All notable changes to this project are documented here. The format follows
 ## [Unreleased]
+## [0.2.3]
+### Changed
+- Verified against DeepSeek Harness 0.2.1-alpha.4 (install smoke test and the 24-check browser E2E pass with no code changes). It is now in `TESTED_DSH_VERSIONS`.
+- Redesigned both READMEs with animated SVG illustrations (hero, agent routing, widget streaming, security model), a highlights grid, badges, a compatibility table and collapsible sections. `npm run docs:art` regenerates the illustrations.
 ## [0.2.2]
 ### Fixed
@@ -57,6 +64,7 @@ All notable changes to this project are documented here. The format follows
   - The declarative component catalog (`ui_render`) and sandboxed streaming HTML widgets (`ui_render_widget`).
   - The `/ui` command and the guidance system-prompt section.
-[Unreleased]: https://github.com/dreamfarer-space/deepseek-harness-intelligent-ui/compare/v0.2.2...HEAD
+[Unreleased]: https://github.com/dreamfarer-space/deepseek-harness-intelligent-ui/compare/v0.2.3...HEAD
+[0.2.3]: https://github.com/dreamfarer-space/deepseek-harness-intelligent-ui/compare/v0.2.2...v0.2.3
 [0.2.2]: https://github.com/dreamfarer-space/deepseek-harness-intelligent-ui/compare/v0.2.1...v0.2.2
 [0.2.1]: https://github.com/dreamfarer-space/deepseek-harness-intelligent-ui/releases/tag/v0.2.1

package/README.md CHANGED Viewed

@@ -1,22 +1,81 @@
-# DeepSeek Harness Intelligent UI
+<div align="center">
-English | [中文](README.zh-CN.md)
+<img src="https://raw.githubusercontent.com/dreamfarer-space/deepseek-harness-intelligent-ui/main/docs/assets/readme/hero.svg" alt="DeepSeek Harness Intelligent UI: generative, interactive UI for DeepSeek Harness" width="100%">
-[![CI](https://github.com/dreamfarer-space/deepseek-harness-intelligent-ui/actions/workflows/ci.yml/badge.svg)](https://github.com/dreamfarer-space/deepseek-harness-intelligent-ui/actions/workflows/ci.yml) [![npm](https://img.shields.io/npm/v/deepseek-harness-intelligent-ui)](https://www.npmjs.com/package/deepseek-harness-intelligent-ui)
+**English** · [中文](README.zh-CN.md)
+[![CI](https://github.com/dreamfarer-space/deepseek-harness-intelligent-ui/actions/workflows/ci.yml/badge.svg)](https://github.com/dreamfarer-space/deepseek-harness-intelligent-ui/actions/workflows/ci.yml)
+[![npm](https://img.shields.io/npm/v/deepseek-harness-intelligent-ui?color=4d6bfe&label=npm)](https://www.npmjs.com/package/deepseek-harness-intelligent-ui)
+[![DSH](https://img.shields.io/badge/DeepSeek%20Harness-0.1.7%20%E2%80%93%200.2.x-22d3ee)](https://github.com/dreamfarer-space/deepseek-harness-intelligent-ui/blob/main/docs/compatibility.md)
+[![Node](https://img.shields.io/badge/node-%E2%89%A5%2022.13-34d399)](https://nodejs.org)
+[![OS](https://img.shields.io/badge/OS-Windows%20%7C%20Linux%20%7C%20macOS-a78bfa)](https://github.com/dreamfarer-space/deepseek-harness-intelligent-ui/blob/main/docs/compatibility.md)
+[![License: MIT](https://img.shields.io/badge/license-MIT-97a1c9)](LICENSE)
+[Demo](#-demo) · [Quick start](#-quick-start) · [How it decides](#-how-the-agent-decides) · [Widgets](#-sandboxed-widgets-ui_render_widget) · [Security](#-security-model) · [Configuration](#%EF%B8%8F-configuration) · [Develop](#-develop-and-verify)
+</div>
 Generative, interactive UI for [DeepSeek Harness](https://github.com/deepseek-ai/deepseek-harness) (DSH). Ask in plain language and the agent decides on its own whether to answer with text, with native components (dashboards, tables, charts, timelines, live function plots, KaTeX math, Mermaid diagrams, forms), or with a fully custom **sandboxed live widget** (Three.js scenes, canvas simulations, mini-apps). The UI renders progressively in the chat while the answer streams. Sliders, rotation, zoom, sorting and tabs respond instantly in the browser. Only explicit actions (a button, a form, `Bridge.sendPrompt`) go back to the agent.
 It ports the ideas of CopilotKit's [OpenIntelligentUI](https://github.com/CopilotKit/OpenIntelligentUI) (Open Generative UI + A2UI-style declarative components) onto DSH's own extension points. It needs no CopilotKit, LangGraph, or external router.
-## Demo
+## ✨ Highlights
+<table>
+<tr>
+<td width="33%" valign="top">
+### 🧠 Decides by itself
+No command needed. Each turn the agent picks text, native components or a live widget, guided by a system-prompt section.
+</td>
+<td width="33%" valign="top">
+### ⚡ Streams progressively
+Components appear while the JSON streams. Widgets morph into **one** iframe and finalize in place: no rebuild, no flash.
+</td>
+<td width="33%" valign="top">
+### 🖱️ Local first
+Sliders, rotate, zoom, sort, tabs and hover tooltips run in the browser and never call the model.
+</td>
+</tr>
+<tr>
+<td valign="top">
+### 🧩 20-component catalog
+Cards, grids, tabs, tables, charts, timelines, `Plot`, KaTeX `Math`, `Mermaid`, forms. Validated before it renders.
+</td>
+<td valign="top">
+### 🔒 Sandboxed by default
+Opaque-origin iframe, strict CSP, token-checked messages and a rate-limited bridge, all verified in a real browser.
+</td>
+<td valign="top">
+### 💾 State that survives
+Open tabs, sort order, form values, sliders and `UI.state` survive turn folding, page reloads and stopped generations.
+</td>
+</tr>
+</table>
+## 🎬 Demo
 ![DeepSeek Harness Intelligent UI demo](https://raw.githubusercontent.com/dreamfarer-space/deepseek-harness-intelligent-ui/v0.2.1/docs/assets/demo.gif)
 🎥 **Full-quality video (H.264, ~2 min):** [docs/assets/demo.mp4](https://github.com/dreamfarer-space/deepseek-harness-intelligent-ui/blob/v0.2.1/docs/assets/demo.mp4)
+> [!NOTE]
 > The recording comes from the real DSH Web 0.2.0-rc.1 with this plugin installed, driven by `npm run e2e:all -- --record`. The model behind it is the **scripted mock** in `scripts/e2e/` (no API key was available), so the answers are canned. Everything you see (streaming, rendering, interaction, the round trips, persistence, isolation) is the real plugin running in DSH.
->
-> To get an inline player on GitHub, drag `docs/assets/demo.mp4` into a GitHub comment or release editor and paste the resulting `https://github.com/user-attachments/assets/…` URL on its own line here. GitHub only renders inline video for uploaded attachments, not for repository files.
+<details>
+<summary><b>📸 Screenshot gallery</b> (dashboard, Three.js, math, forms, streaming, dark mode, phone, reload)</summary>
+<br>
 | Dashboard streams in, then settles | Three.js widget: R slider, rotate, zoom |
 |:---:|:---:|
@@ -36,7 +95,61 @@ It ports the ideas of CopilotKit's [OpenIntelligentUI](https://github.com/Copilo
 |:---:|:---:|:---:|
 | ![Dark](https://raw.githubusercontent.com/dreamfarer-space/deepseek-harness-intelligent-ui/v0.2.1/docs/assets/screenshots/11b-dark-widget.png) | ![Mobile](https://raw.githubusercontent.com/dreamfarer-space/deepseek-harness-intelligent-ui/v0.2.1/docs/assets/screenshots/12-mobile-dark.png) | ![Reload](https://raw.githubusercontent.com/dreamfarer-space/deepseek-harness-intelligent-ui/v0.2.1/docs/assets/screenshots/14-reload.png) |
-## How the agent decides
+To get an inline player on GitHub, drag `docs/assets/demo.mp4` into a GitHub comment or release editor and paste the resulting `https://github.com/user-attachments/assets/…` URL on its own line here. GitHub only renders inline video for uploaded attachments, not for repository files.
+</details>
+## 🚀 Quick start
+You need [DeepSeek Harness](https://github.com/deepseek-ai/deepseek-harness) **0.1.7 – 0.2.x** (`>=0.1.7-rc.1 <0.3.0`) and Node.js ≥ 22.13, on Windows, Linux or macOS. Nothing is compiled during install. The package ships its prebuilt browser bundle and declares no install scripts.
+```sh
+dsh plugin --profile web add deepseek-harness-intelligent-ui
+```
+Then restart DSH Web (`dsh web`) and ask for something visual, for example *"compare Q1–Q4 revenue by channel"* or *"let me explore x²+y²+z²=2Rz in 3D"*.
+To have your environment checked first, use the guided installer instead. It verifies Node, the `dsh` version, pnpm and the profile, then runs the same `dsh plugin add`:
+```sh
+npx deepseek-harness-intelligent-ui install            # --profile <name>, --dsh <path>, --dry-run
+npx deepseek-harness-intelligent-ui doctor             # diagnose only
+```
+| Task | Command |
+|---|---|
+| Upgrade | `dsh plugin --profile web add deepseek-harness-intelligent-ui@latest` |
+| Try a prerelease (only when the `next` dist-tag exists) | `dsh plugin --profile web add deepseek-harness-intelligent-ui@next` |
+| Pin a version | `dsh plugin --profile web add deepseek-harness-intelligent-ui@0.2.3` |
+| Uninstall | `dsh plugin --profile web remove deepseek-harness-intelligent-ui` (or `npx deepseek-harness-intelligent-ui uninstall`) |
+| From a checkout | `dsh plugin --profile web add file:/path/to/deepseek-harness-intelligent-ui` |
+<details>
+<summary><b>🩺 Troubleshooting</b></summary>
+<br>
+- *`pnpm was not found`*: DSH installs plugins with pnpm. Run `corepack enable` (it ships with Node) or `npm i -g pnpm`.
+- *`… is incompatible with dsh X`*: your DSH is outside the supported range. Upgrade DSH (`npm i -g @deepseek-ai/dsh@latest`) or check [compatibility](https://github.com/dreamfarer-space/deepseek-harness-intelligent-ui/blob/main/docs/compatibility.md) for a plugin release that supports it.
+- *Upgrading from 0.1.x (`dsh-intelligent-ui` via `file:`)*: run `dsh plugin --profile web remove dsh-intelligent-ui` first. Both packages insert the same `intelligent-ui` row, and `doctor` reports the conflict.
+- *The UI does not appear*: restart DSH Web after installing, and make sure you started the profile you installed into (`dsh web`).
+</details>
+### Compatibility
+| DeepSeek Harness | Install smoke test | Browser E2E (24 checks) |
+|---|:---:|:---:|
+| `0.1.7-rc.2` | ✅ | ✅ |
+| `0.2.0-rc.1` | ✅ | ✅ |
+| `0.2.0-rc.2` (`latest`) | ✅ | ✅ |
+| `0.2.1-alpha.2` | ✅ | ✅ |
+| `0.2.1-alpha.4` (`alpha`) | ✅ | ✅ |
+CI runs the matrix on Windows, Linux and macOS, nightly too, so new DSH releases are caught early. Details: [docs/compatibility.md](https://github.com/dreamfarer-space/deepseek-harness-intelligent-ui/blob/main/docs/compatibility.md).
+## 🧠 How the agent decides
+<img src="https://raw.githubusercontent.com/dreamfarer-space/deepseek-harness-intelligent-ui/main/docs/assets/readme/routing.svg" alt="The agent routes each prompt to plain text, ui_render or ui_render_widget; local interactions never call the model, explicit actions go back to the agent" width="100%">
 The plugin injects a system-prompt section (`src/guidance.js`) that makes the model route each turn itself. There is no command and no external router:
@@ -47,33 +160,44 @@ The plugin injects a system-prompt section (`src/guidance.js`) that makes the mo
 `/ui <request>` still exists to force a UI answer.
-## Tools
 | Tool | Use it for | Rendering |
 |---|---|---|
 | `ui_render` | Structured answers | Native React components from a fixed catalog, rendered progressively as the JSON streams |
 | `ui_render_widget` | Custom visuals, 3D, simulations, mini-apps | HTML/CSS/JS in an opaque-origin sandboxed iframe: CSS first, HTML morphed in live, JS last, all in **one** iframe |
-### Component catalog (`ui_render`)
+## 🧩 Component catalog (`ui_render`)
-`Card`, `Stack`, `Grid`, `Tabs` (keyboard navigable), `Text` (markdown subset), `Code`, `Alert`, `Badge`, `Divider`, `Stat`, `Progress`, `List`, `Table` (sortable), `Chart` (bar / line / area / pie, stacked, hover tooltip, toggleable legend), `Timeline`, **`Plot`** (y = f(x) with parameter sliders that redraw instantly; expressions run in a safe compiler, never `eval`), **`Math`** (KaTeX), **`Mermaid`** (flowchart, sequence, class, state, ER, gantt, mindmap…), `Button` (sends a prompt), and `Form` (text, number, **range slider**, select, checkbox, date, textarea; submits the values as a message).
+| Category | Components |
+|---|---|
+| Layout | `Card`, `Stack`, `Grid`, `Tabs` (keyboard navigable) |
+| Text & callouts | `Text` (markdown subset), `Code`, `Alert`, `Badge`, `Divider` |
+| Data | `Stat`, `Progress`, `List`, `Table` (sortable), `Timeline` |
+| Charts | `Chart`: bar / line / area / pie, stacked, hover tooltip, toggleable legend |
+| Math & diagrams | **`Plot`** (y = f(x) with parameter sliders that redraw instantly; expressions run in a safe compiler, never `eval`), **`Math`** (KaTeX), **`Mermaid`** (flowchart, sequence, class, state, ER, gantt, mindmap…) |
+| Interaction | `Button` (sends a prompt), `Form` (text, number, **range slider**, select, checkbox, date, textarea; submits the values as a message) |
 A UI travels as a **flat node list with id references**, because DSH's tool-schema subset has no recursion. The Host validates it before acknowledging: unknown types or props, dangling or duplicate ids, cycles, two parents, chart length mismatches, `Plot` expressions that do not compile, slider defaults out of range, and so on. Problems come back as `ok:false` with paths, so the model can fix them and retry.
 `Math` and `Mermaid` render inside the same sandbox as widgets, loading KaTeX or Mermaid from the CDN allowlist. No third-party code runs in the DSH page and the host bundle stays small (~127 KB). If the CDN is unreachable, the source text is shown instead.
-### Widgets (`ui_render_widget`)
+## 🪟 Sandboxed widgets (`ui_render_widget`)
+<img src="https://raw.githubusercontent.com/dreamfarer-space/deepseek-harness-intelligent-ui/main/docs/assets/readme/widget-streaming.svg" alt="Widget fields stream in order: placeholder, then a live preview with morphed HTML, then the same iframe is finalized and the code runs" width="100%">
 Fields follow the OpenIntelligentUI streaming contract, **in this order**: `title`, `initialHeight`, `placeholderMessages`, `css`, `html`, `jsFunctions`, `jsExpressions`.
 - **Streaming:** placeholder lines show until `css` is complete. Then a preview frame opens and the cleaned partial `html` is morphed in ([idiomorph](https://github.com/bigskysoftware/idiomorph)). When the arguments are complete, the **same frame is finalized in place**: the final HTML is morphed and the code runs. There is no rebuild, blank flash or height jump.
 - **Runtime helpers** (global `UI`):
-  - `UI.three(el, { camera, target, autoRotate })` returns a renderer, scene, lights and OrbitControls (drag rotates, wheel/pinch zooms), renders on demand, and handles resize.
-  - `UI.canvas(el, draw)` gives a HiDPI 2D canvas that is redrawn on resize and theme change.
-  - `UI.state` / `UI.setState()` persist state. Inputs with an `id` are persisted and restored automatically.
-  - `UI.color('accent')` returns an opaque theme color for three.js/canvas, and `UI.css()` returns a raw value.
-  - `UI.onTheme(cb)`, `UI.scheme` and `UI.reducedMotion` are also available.
-  - Helper classes: `.ui-row`, `.ui-control`, `.ui-card`, `.ui-stage`.
+  | Helper | What it does |
+  |---|---|
+  | `UI.three(el, { camera, target, autoRotate })` | Renderer, scene, lights and OrbitControls (drag rotates, wheel/pinch zooms); renders on demand and handles resize |
+  | `UI.canvas(el, draw)` | HiDPI 2D canvas, redrawn on resize and theme change |
+  | `UI.state` / `UI.setState()` | Persisted state; inputs with an `id` are persisted and restored automatically |
+  | `UI.color('accent')` / `UI.css()` | Opaque theme color for three.js/canvas / raw CSS value |
+  | `UI.onTheme(cb)`, `UI.scheme`, `UI.reducedMotion` | React to theme and motion preferences |
+  | `.ui-row`, `.ui-control`, `.ui-card`, `.ui-stage` | Helper classes |
 - **Bridge:** `Bridge.sendPrompt({ text })` disables the clicked control until the host answers, so double clicks cannot queue duplicates. `Bridge.openLink({ url })` opens links, and `Websandbox.connection.remote.*` is kept for OpenIntelligentUI compatibility.
 - **Libraries:** an importmap maps `three`, `three/addons/…`, `d3`, `chart.js/auto`, `gsap` and `canvas-confetti` to esm.sh.
 - **Recovery:** script errors show a count with **Reload** and **Ask to fix** (the latter sends the errors to the agent).
@@ -87,56 +211,20 @@ Fields follow the OpenIntelligentUI streaming contract, **in this order**: `titl
   - If the call already reached DSH, the view keeps the finished part (a static widget preview or the completed components) with a notice and a **Regenerate** button.
   - If the user stops while the arguments are still streaming, DSH drops the call entirely. The plugin stashes what was streamed and shows it beneath the stopped turn the same way.
-## Security model
+## 🔒 Security model
+<img src="https://raw.githubusercontent.com/dreamfarer-space/deepseek-harness-intelligent-ui/main/docs/assets/readme/security.svg" alt="Widgets run in an opaque-origin sandboxed iframe under a strict CSP; access to the host page is blocked and only token-checked postMessage calls reach the rate-limited bridge" width="100%">
 - **Widget isolation:** widgets run in `<iframe sandbox="allow-scripts allow-forms">` with `srcdoc` and **no** `allow-same-origin`. They cannot reach the DSH page, its cookies or storage, or its API. The E2E checks this in the browser: `parent.document`, `localStorage` and `document.cookie` all throw `SecurityError`, `fetch` is blocked, and `window.origin === "null"`.
-- **CSP:**
-  - `default-src 'none'`.
-  - Scripts, styles, fonts and images load only from `cdnAllowlist`.
-  - `connect-src 'none'` unless `allowNetwork` is on.
-  - `form-action 'none'` and `base-uri 'none'`.
+- **CSP:** `default-src 'none'`; scripts, styles, fonts and images load only from `cdnAllowlist`; `connect-src 'none'` unless `allowNetwork` is on; `form-action 'none'` and `base-uri 'none'`.
 - **Messages from the frame:** they are accepted only from that frame's `contentWindow`, must carry a per-frame random token, and are shape-checked. Persisted widget state is size-limited JSON. The E2E checks that forged messages from the page or the frame are dropped.
-- **`sendPrompt` limits:**
-  - It is refused during the first second after mount.
-  - At most one send every 2 seconds.
-  - Text is capped at `sendPromptMaxChars`.
-  - The message is queued as a normal user message.
+- **`sendPrompt` limits:** refused during the first second after mount; at most one send every 2 seconds; text capped at `sendPromptMaxChars`; queued as a normal user message.
 - **`openLink`:** https only, optionally restricted to `openLinkAllowedOrigins`.
 - **Catalog:** text renders as React elements, never raw HTML. `Plot` expressions are compiled by a tokenizer/parser over a fixed math function table, with no `eval`, `Function`, or property access.
-## Install
-You need [DeepSeek Harness](https://github.com/deepseek-ai/deepseek-harness) **0.1.7 – 0.2.x** (`>=0.1.7-rc.1 <0.3.0`) and Node.js ≥ 22.13, on Windows, Linux or macOS. Nothing is compiled during install. The package ships its prebuilt browser bundle and declares no install scripts.
+## ⚙️ Configuration
-```sh
-dsh plugin --profile web add deepseek-harness-intelligent-ui
-```
-To have your environment checked first, use the guided installer instead. It verifies Node, the `dsh` version, pnpm and the profile, then runs the same `dsh plugin add`:
-```sh
-npx deepseek-harness-intelligent-ui install            # --profile <name>, --dsh <path>, --dry-run
-npx deepseek-harness-intelligent-ui doctor             # diagnose only
-```
-| Task | Command |
-|---|---|
-| Upgrade | `dsh plugin --profile web add deepseek-harness-intelligent-ui@latest` |
-| Try a prerelease (only when the `next` dist-tag exists) | `dsh plugin --profile web add deepseek-harness-intelligent-ui@next` |
-| Pin a version | `dsh plugin --profile web add deepseek-harness-intelligent-ui@0.2.2` |
-| Uninstall | `dsh plugin --profile web remove deepseek-harness-intelligent-ui` (or `npx deepseek-harness-intelligent-ui uninstall`) |
-| From a checkout | `dsh plugin --profile web add file:/path/to/deepseek-harness-intelligent-ui` |
-Supported DSH versions and the CI matrix are in [docs/compatibility.md](https://github.com/dreamfarer-space/deepseek-harness-intelligent-ui/blob/v0.2.2/docs/compatibility.md).
-**Troubleshooting**
-- *`pnpm was not found`*: DSH installs plugins with pnpm. Run `corepack enable` (it ships with Node) or `npm i -g pnpm`.
-- *`… is incompatible with dsh X`*: your DSH is outside the supported range. Upgrade DSH (`npm i -g @deepseek-ai/dsh@latest`) or check [compatibility](https://github.com/dreamfarer-space/deepseek-harness-intelligent-ui/blob/v0.2.2/docs/compatibility.md) for a plugin release that supports it.
-- *Upgrading from 0.1.x (`dsh-intelligent-ui` via `file:`)*: run `dsh plugin --profile web remove dsh-intelligent-ui` first. Both packages insert the same `intelligent-ui` row, and `doctor` reports the conflict.
-- *The UI does not appear*: restart DSH Web after installing, and make sure you started the profile you installed into (`dsh web`).
-Restart DSH Web afterwards. The bundle patch inserts the plugin row automatically. To change settings, add to your profile's `cordis.patch.yml`:
+The bundle patch inserts the plugin row automatically. To change settings, add to your profile's `cordis.patch.yml`:
 ```yaml
 - id: intelligent-ui
@@ -157,7 +245,7 @@ Restart DSH Web afterwards. The bundle patch inserts the plugin row automaticall
 | `sendPromptMaxChars` | `4000` | Longest message a widget, button or form may send |
 | `openLinkAllowedOrigins` | `[]` | If non-empty, the only origins `openLink` may open |
-## Develop and verify
+## 🛠 Develop and verify
 ```sh
 npm install
@@ -168,11 +256,42 @@ npm run e2e:all     # build → install into a temp DSH home → mock model + re
 npm run e2e:all -- --record   # also re-records docs/assets/demo.mp4 / demo.gif (needs ffmpeg)
 npm run e2e:all -- --spec ./deepseek-harness-intelligent-ui-<v>.tgz   # E2E the packed tarball instead of the checkout
 npm run smoke -- --spec ./deepseek-harness-intelligent-ui-<v>.tgz     # install smoke test (no browser): version gate, bundle row, DSH Web boot
+npm run docs:art    # regenerate the animated README illustrations in docs/assets/readme/
 ```
-The E2E runs on Windows, Linux and macOS. It finds Chrome per platform (set `CHROME_PATH` to override) and uses `DSH_BIN` to test another `dsh` binary. CI runs everything on all three OSes against every supported DSH line ([compatibility](https://github.com/dreamfarer-space/deepseek-harness-intelligent-ui/blob/v0.2.2/docs/compatibility.md)).
+The E2E runs on Windows, Linux and macOS. It finds Chrome per platform (set `CHROME_PATH` to override) and uses `DSH_BIN` to test another `dsh` binary. CI runs everything on all three OSes against every supported DSH line ([compatibility](https://github.com/dreamfarer-space/deepseek-harness-intelligent-ui/blob/main/docs/compatibility.md)).
-**Releasing** (maintainers):
+- **Layout:** `src/` is the Host half (plain ESM, no build). `client-src/` is the browser half (TSX, bundled with esbuild). `client/client.js` is committed and published so npm, `file:` and git installs need no build step. CI fails if it is stale. Never add a `prepare`/`postinstall` script, because DSH's pnpm blocks plugin build scripts.
+- Requires Chrome (`CHROME_PATH`), `dsh` on PATH and, for `--record`, `ffmpeg`. Headless Chrome uses SwiftShader for WebGL.
+<details>
+<summary><b>✅ What the browser E2E checks</b> (<code>scripts/e2e/browser.mjs</code>)</summary>
+<br>
+Report: [`docs/e2e-report.json`](https://github.com/dreamfarer-space/deepseek-harness-intelligent-ui/blob/v0.2.1/docs/e2e-report.json).
+- Plain Q&A stays text.
+- The dashboard streams progressively.
+- Chart hover, table sort and tabs are local.
+- A form round-trip returns a new UI.
+- The preview iframe is finalized in place.
+- The Three.js scene renders, and the R slider, drag-rotate and wheel-zoom work.
+- The `Bridge.sendPrompt` round trip works.
+- KaTeX and Mermaid render.
+- Plot sliders work.
+- Earlier UIs keep their state.
+- Stop → static preview → Regenerate works.
+- The sandbox is isolated and forged messages are ignored.
+- Dark theme reaches cards and widgets.
+- Phone width has no overflow.
+- A reload restores the UIs and their state.
+- No plugin console errors appear.
+</details>
+<details>
+<summary><b>📦 Releasing</b> (maintainers)</summary>
+<br>
 See [release security and OIDC setup](https://github.com/dreamfarer-space/deepseek-harness-intelligent-ui/blob/main/docs/releasing.md).
@@ -185,27 +304,11 @@ See [release security and OIDC setup](https://github.com/dreamfarer-space/deepse
    - creates the GitHub Release with the changelog section and the tarball.
 4. Run `npm run release:check` to perform the same preflight locally.
-- **Layout:** `src/` is the Host half (plain ESM, no build). `client-src/` is the browser half (TSX, bundled with esbuild). `client/client.js` is committed and published so npm, `file:` and git installs need no build step. CI fails if it is stale. Never add a `prepare`/`postinstall` script, because DSH's pnpm blocks plugin build scripts.
-- **What the E2E checks** (`scripts/e2e/browser.mjs`, report in [`docs/e2e-report.json`](https://github.com/dreamfarer-space/deepseek-harness-intelligent-ui/blob/v0.2.1/docs/e2e-report.json)):
-  - Plain Q&A stays text.
-  - The dashboard streams progressively.
-  - Chart hover, table sort and tabs are local.
-  - A form round-trip returns a new UI.
-  - The preview iframe is finalized in place.
-  - The Three.js scene renders, and the R slider, drag-rotate and wheel-zoom work.
-  - The `Bridge.sendPrompt` round trip works.
-  - KaTeX and Mermaid render.
-  - Plot sliders work.
-  - Earlier UIs keep their state.
-  - Stop → static preview → Regenerate works.
-  - The sandbox is isolated and forged messages are ignored.
-  - Dark theme reaches cards and widgets.
-  - Phone width has no overflow.
-  - A reload restores the UIs and their state.
-  - No plugin console errors appear.
-- Requires Chrome (`CHROME_PATH`), `dsh` on PATH and, for `--record`, `ffmpeg`. Headless Chrome uses SwiftShader for WebGL.
+</details>
-## Real-model Evaluation
+<details>
+<summary><b>🤖 Real-model evaluation</b></summary>
+<br>
 The API suite checks model routing, tool-argument schemas, and selected requested components or data across 15 prompts. It does **not** execute model-generated widgets in a browser or verify factual data, visual quality, physics, or interaction behavior. The separate browser E2E uses scripted model responses.
@@ -227,6 +330,8 @@ node scripts/run-real-model-suite.mjs all
 Each invocation writes only that run's cases to `docs/real-model-eval-report.json`. A partial run does not merge older cases into a new timestamp. Failed assertions/API calls exit with code 1; an invalid category or missing key fails before changing the report. Keep keys out of git.
+</details>
 ## Limitations
 - Widgets, Math and Mermaid need the CDN allowlist to be reachable. Offline, Math/Mermaid fall back to source text and `UI.three` reports a script error.

package/README.zh-CN.md CHANGED Viewed

@@ -1,8 +1,19 @@
-# DeepSeek Harness Intelligent UI（智能界面）
+<div align="center">
-[English](README.md) | 中文
+<img src="https://raw.githubusercontent.com/dreamfarer-space/deepseek-harness-intelligent-ui/main/docs/assets/readme/hero.zh.svg" alt="DeepSeek Harness Intelligent UI：为 DeepSeek Harness 带来生成式、可交互的界面" width="100%">
-[![CI](https://github.com/dreamfarer-space/deepseek-harness-intelligent-ui/actions/workflows/ci.yml/badge.svg)](https://github.com/dreamfarer-space/deepseek-harness-intelligent-ui/actions/workflows/ci.yml) [![npm](https://img.shields.io/npm/v/deepseek-harness-intelligent-ui)](https://www.npmjs.com/package/deepseek-harness-intelligent-ui)
+[English](README.md) · **中文**
+[![CI](https://github.com/dreamfarer-space/deepseek-harness-intelligent-ui/actions/workflows/ci.yml/badge.svg)](https://github.com/dreamfarer-space/deepseek-harness-intelligent-ui/actions/workflows/ci.yml)
+[![npm](https://img.shields.io/npm/v/deepseek-harness-intelligent-ui?color=4d6bfe&label=npm)](https://www.npmjs.com/package/deepseek-harness-intelligent-ui)
+[![DSH](https://img.shields.io/badge/DeepSeek%20Harness-0.1.7%20%E2%80%93%200.2.x-22d3ee)](https://github.com/dreamfarer-space/deepseek-harness-intelligent-ui/blob/main/docs/compatibility.md)
+[![Node](https://img.shields.io/badge/node-%E2%89%A5%2022.13-34d399)](https://nodejs.org)
+[![OS](https://img.shields.io/badge/OS-Windows%20%7C%20Linux%20%7C%20macOS-a78bfa)](https://github.com/dreamfarer-space/deepseek-harness-intelligent-ui/blob/main/docs/compatibility.md)
+[![License: MIT](https://img.shields.io/badge/license-MIT-97a1c9)](LICENSE)
+[演示](#-演示) · [快速开始](#-快速开始) · [如何选择](#-agent-如何选择呈现方式) · [沙箱组件](#-沙箱组件ui_render_widget) · [安全](#-安全模型) · [配置](#%EF%B8%8F-配置) · [开发](#-开发与验证)
+</div>
 为 [DeepSeek Harness](https://github.com/deepseek-ai/deepseek-harness)（DSH）提供**生成式、可交互的 UI**。用户用自然语言提问，Agent 自行决定怎样作答：
@@ -14,17 +25,63 @@
 本插件把 CopilotKit [OpenIntelligentUI](https://github.com/CopilotKit/OpenIntelligentUI) 的思路（Open Generative UI + A2UI 风格声明式组件）移植到 DSH 自带的扩展点上，不依赖 CopilotKit、LangGraph 或外部路由服务。
-## 演示
+## ✨ 亮点
+<table>
+<tr>
+<td width="33%" valign="top">
+### 🧠 自主决策
+无需任何命令。每一轮由 Agent 依据系统提示，自行选择文本、原生组件或实时组件。
+</td>
+<td width="33%" valign="top">
+### ⚡ 流式渐进
+JSON 还在生成，组件就已出现。实时组件在**同一个** iframe 中 morph 并原地定稿，不重建、不闪烁。
+</td>
+<td width="33%" valign="top">
+### 🖱️ 本地优先
+滑块、旋转、缩放、排序、标签页、悬停提示都在浏览器内完成，不调用模型。
+</td>
+</tr>
+<tr>
+<td valign="top">
+### 🧩 20 种组件
+卡片、栅格、标签页、表格、图表、时间线、`Plot`、KaTeX `Math`、`Mermaid`、表单，渲染前先校验。
+</td>
+<td valign="top">
+### 🔒 默认沙箱隔离
+不透明源 iframe、严格 CSP、带 token 的消息校验、限流的 Bridge，全部在真实浏览器中实测。
+</td>
+<td valign="top">
+### 💾 状态不丢失
+标签页、排序、表单值、滑块和 `UI.state` 在回合折叠、页面刷新、中途停止后都能恢复。
+</td>
+</tr>
+</table>
+## 🎬 演示
 ![DeepSeek Harness Intelligent UI 演示](https://raw.githubusercontent.com/dreamfarer-space/deepseek-harness-intelligent-ui/v0.2.1/docs/assets/demo.gif)
 🎥 **高清视频（H.264，约 2 分钟）：** [docs/assets/demo.mp4](https://github.com/dreamfarer-space/deepseek-harness-intelligent-ui/blob/v0.2.1/docs/assets/demo.mp4)
-> **录制方式：** 演示视频录自真实的 DSH Web 0.2.0-rc.1，装好本插件后由 `npm run e2e:all -- --record` 自动驱动。
->
-> **关于模型：** 背后的模型是 `scripts/e2e/` 中的**脚本化 mock**（当时没有 API Key），回答内容是预设的。画面中的流式渲染、交互、双向通信、持久化和隔离，都是插件在 DSH 中真实运行的结果。
->
-> **在 GitHub 内联播放：** 把 `docs/assets/demo.mp4` 拖进 GitHub 的评论或 Release 编辑框，再把生成的 `https://github.com/user-attachments/assets/…` 链接单独一行粘贴到这里。GitHub 只对上传的附件内联播放视频，不支持仓库内的文件。
+> [!NOTE]
+> 演示视频录自真实的 DSH Web 0.2.0-rc.1，装好本插件后由 `npm run e2e:all -- --record` 自动驱动。背后的模型是 `scripts/e2e/` 中的**脚本化 mock**（当时没有 API Key），回答内容是预设的。画面中的流式渲染、交互、双向通信、持久化和隔离，都是插件在 DSH 中真实运行的结果。
+<details>
+<summary><b>📸 截图集</b>（看板、Three.js、公式、表单、流式预览、深色主题、手机、刷新）</summary>
+<br>
 | 看板流式出现并定稿 | Three.js 组件：R 滑块、旋转、缩放 |
 |:---:|:---:|
@@ -43,7 +100,61 @@
 |:---:|:---:|:---:|
 | ![深色](https://raw.githubusercontent.com/dreamfarer-space/deepseek-harness-intelligent-ui/v0.2.1/docs/assets/screenshots/11b-dark-widget.png) | ![移动端](https://raw.githubusercontent.com/dreamfarer-space/deepseek-harness-intelligent-ui/v0.2.1/docs/assets/screenshots/12-mobile-dark.png) | ![刷新](https://raw.githubusercontent.com/dreamfarer-space/deepseek-harness-intelligent-ui/v0.2.1/docs/assets/screenshots/14-reload.png) |
-## Agent 如何选择呈现方式
+**在 GitHub 内联播放：** 把 `docs/assets/demo.mp4` 拖进 GitHub 的评论或 Release 编辑框，再把生成的 `https://github.com/user-attachments/assets/…` 链接单独一行粘贴到这里。GitHub 只对上传的附件内联播放视频，不支持仓库内的文件。
+</details>
+## 🚀 快速开始
+需要 [DeepSeek Harness](https://github.com/deepseek-ai/deepseek-harness) **0.1.7 – 0.2.x**（`>=0.1.7-rc.1 <0.3.0`）和 Node.js ≥ 22.13，Windows、Linux、macOS 均可。安装过程不需要编译：npm 包自带预构建的浏览器端 bundle，也没有任何安装脚本。
+```sh
+dsh plugin --profile web add deepseek-harness-intelligent-ui
+```
+然后重启 DSH Web（`dsh web`），试着提一个需要可视化的问题，例如 *“按渠道对比 Q1–Q4 营收”* 或 *“让我在 3D 里探索 x²+y²+z²=2Rz”*。
+也可以用引导式安装器。它会先检查 Node、`dsh` 版本、pnpm 和 profile，检查通过后执行同样的 `dsh plugin add`：
+```sh
+npx deepseek-harness-intelligent-ui install            # 可选 --profile <名称>、--dsh <路径>、--dry-run
+npx deepseek-harness-intelligent-ui doctor             # 只诊断，不做修改
+```
+| 操作 | 命令 |
+|---|---|
+| 升级 | `dsh plugin --profile web add deepseek-harness-intelligent-ui@latest` |
+| 试用预发布版（仅在存在 `next` 标签时） | `dsh plugin --profile web add deepseek-harness-intelligent-ui@next` |
+| 固定版本 | `dsh plugin --profile web add deepseek-harness-intelligent-ui@0.2.3` |
+| 卸载 | `dsh plugin --profile web remove deepseek-harness-intelligent-ui`（或 `npx deepseek-harness-intelligent-ui uninstall`） |
+| 从源码目录安装 | `dsh plugin --profile web add file:/path/to/deepseek-harness-intelligent-ui` |
+<details>
+<summary><b>🩺 常见问题</b></summary>
+<br>
+- *提示 `pnpm was not found`*：DSH 用 pnpm 安装插件。运行 `corepack enable`（Node 自带）或 `npm i -g pnpm`。
+- *提示 `… is incompatible with dsh X`*：当前 DSH 版本不在支持范围内。可以升级 DSH（`npm i -g @deepseek-ai/dsh@latest`），或在[兼容性文档](https://github.com/dreamfarer-space/deepseek-harness-intelligent-ui/blob/main/docs/compatibility.md)里找支持该版本的插件发行版。
+- *从 0.1.x 升级（以前用 `file:` 安装的 `dsh-intelligent-ui`）*：先运行 `dsh plugin --profile web remove dsh-intelligent-ui`。新旧两个包会插入同一个 `intelligent-ui` 行，`doctor` 能检测到这种冲突。
+- *界面没有出现*：安装后要重启 DSH Web，并确认启动的是安装插件时指定的 profile（`dsh web`）。
+</details>
+### 兼容性
+| DeepSeek Harness | 安装冒烟测试 | 浏览器 E2E（24 项） |
+|---|:---:|:---:|
+| `0.1.7-rc.2` | ✅ | ✅ |
+| `0.2.0-rc.1` | ✅ | ✅ |
+| `0.2.0-rc.2`（`latest`） | ✅ | ✅ |
+| `0.2.1-alpha.2` | ✅ | ✅ |
+| `0.2.1-alpha.4`（`alpha`） | ✅ | ✅ |
+CI 每天定时在 Windows、Linux、macOS 上跑完整矩阵，DSH 一发新版就能发现问题。详见 [docs/compatibility.md](https://github.com/dreamfarer-space/deepseek-harness-intelligent-ui/blob/main/docs/compatibility.md)。
+## 🧠 Agent 如何选择呈现方式
+<img src="https://raw.githubusercontent.com/dreamfarer-space/deepseek-harness-intelligent-ui/main/docs/assets/readme/routing.zh.svg" alt="Agent 把每次提问路由到纯文本、ui_render 或 ui_render_widget；本地交互不调用模型，显式操作才回到 Agent" width="100%">
 插件注入一段系统提示（`src/guidance.js`），让模型每一轮自行选择，用户无需输入任何命令：
@@ -54,7 +165,12 @@
 `/ui <需求>` 命令仍然保留，用于强制以 UI 作答。
-## 组件目录（`ui_render`）
+| 工具 | 适用场景 | 渲染方式 |
+|---|---|---|
+| `ui_render` | 结构化回答 | 固定目录中的原生 React 组件，随 JSON 流式渐进渲染 |
+| `ui_render_widget` | 自定义可视化、三维、模拟、小应用 | 不透明源沙箱 iframe 中的 HTML/CSS/JS：先 CSS，再实时 morph HTML，最后执行 JS，全程**一个** iframe |
+## 🧩 组件目录（`ui_render`）
 | 类别 | 组件 |
 |---|---|
@@ -69,33 +185,31 @@
 - **`Form`**：字段类型有文本、数字、**范围滑块**、下拉、勾选、日期、多行文本。
 - **`Button` 与 `Form`**：点击或提交后，内容作为下一条用户消息发给 Agent。
-**传输与校验：** DSH 的工具 schema 不支持递归，所以界面以**扁平节点列表加 id 引用**的形式传输。Host 先校验再确认，检查项包括：
-- 未知类型或属性；
-- id 悬空、重复或成环；
-- 一个节点有多个父节点；
-- 图表数据长度不一致；
-- `Plot` 表达式无法编译、参数默认值越界等。
-发现问题时返回 `ok:false` 并附带出错路径，模型据此修正后重试。
+**传输与校验：** DSH 的工具 schema 不支持递归，所以界面以**扁平节点列表加 id 引用**的形式传输。Host 先校验再确认，检查项包括未知类型或属性；id 悬空、重复或成环；一个节点有多个父节点；图表数据长度不一致；`Plot` 表达式无法编译、参数默认值越界等。发现问题时返回 `ok:false` 并附带出错路径，模型据此修正后重试。
 **`Math` 与 `Mermaid` 的渲染：** 两者在与组件相同的沙箱中，从 CDN 白名单加载 KaTeX 或 Mermaid。第三方代码不在 DSH 页面中运行，宿主包体积保持在约 127 KB。CDN 不可用时，显示源码文本。
-## 沙箱组件（`ui_render_widget`）
+## 🪟 沙箱组件（`ui_render_widget`）
+<img src="https://raw.githubusercontent.com/dreamfarer-space/deepseek-harness-intelligent-ui/main/docs/assets/readme/widget-streaming.zh.svg" alt="组件字段按顺序流式到达：先显示占位，再实时 morph 预览，最后在同一个 iframe 中定稿并执行代码" width="100%">
 字段顺序固定：`title`、`initialHeight`、`placeholderMessages`、`css`、`html`、`jsFunctions`、`jsExpressions`。
 - **流式过程：**
   1. `css` 完成前，显示占位文字。
-  2. `css` 完成后打开预览 iframe，把清洗过的部分 HTML 实时 morph 进去。
+  2. `css` 完成后打开预览 iframe，把清洗过的部分 HTML 实时 morph 进去（[idiomorph](https://github.com/bigskysoftware/idiomorph)）。
   3. 参数完整后，在**同一个 iframe 内原地定稿**：morph 最终 HTML，然后执行代码。iframe 不重建，没有白屏闪烁，高度也不跳动。
 - **运行时辅助（全局 `UI`）：**
-  - `UI.three(el, opts)`：返回 renderer、场景、灯光和 OrbitControls（拖动旋转，滚轮或双指缩放），按需渲染并自适应尺寸。
-  - `UI.canvas(el, draw)`：高清 2D 画布，尺寸或主题变化时自动重绘。
-  - `UI.state` / `UI.setState()`：持久化状态；带 `id` 的输入控件会自动保存并恢复。
-  - `UI.color('accent')`：返回不透明的主题色，可直接用于 three.js 和 Canvas。
-  - `UI.onTheme(cb)`、`UI.scheme`、`UI.reducedMotion`：响应主题变化与减少动效偏好。
-  - 辅助样式类：`.ui-row`、`.ui-control`、`.ui-card`、`.ui-stage`。
+  | 辅助方法 | 作用 |
+  |---|---|
+  | `UI.three(el, opts)` | 返回 renderer、场景、灯光和 OrbitControls（拖动旋转，滚轮或双指缩放），按需渲染并自适应尺寸 |
+  | `UI.canvas(el, draw)` | 高清 2D 画布，尺寸或主题变化时自动重绘 |
+  | `UI.state` / `UI.setState()` | 持久化状态；带 `id` 的输入控件会自动保存并恢复 |
+  | `UI.color('accent')` / `UI.css()` | 不透明主题色（可直接用于 three.js 和 Canvas）/ 原始 CSS 值 |
+  | `UI.onTheme(cb)`、`UI.scheme`、`UI.reducedMotion` | 响应主题变化与减少动效偏好 |
+  | `.ui-row`、`.ui-control`、`.ui-card`、`.ui-stage` | 辅助样式类 |
 - **Bridge：**
   - `Bridge.sendPrompt({ text })`：在宿主应答前，自动禁用触发它的按钮，防止重复提交。
   - `Bridge.openLink({ url })`：打开链接。
@@ -103,7 +217,7 @@
 - **依赖库：** 通过 importmap 从 esm.sh 引入 `three`、`three/addons/…`、`d3`、`chart.js/auto`、`gsap`、`canvas-confetti`。
 - **错误恢复：** 出现脚本错误时显示错误数量，并提供“重新加载”和“让模型修复”两个按钮。后者会把错误信息发给 Agent。
-## 显示位置与状态保持
+### 显示位置与状态保持
 - **显示位置：**
   - 回合进行中，UI 在工具调用处内联显示。从准备、执行到结果，始终是同一个组件实例，交互状态不会丢。
@@ -113,61 +227,41 @@
   - 已进入会话日志的调用：保留已完成的部分（组件的静态预览，或已生成的组件），并显示提示和“重新生成”按钮。
   - 参数仍在流式输出时就被停止的调用：DSH 会整体丢弃它。插件会暂存已生成的内容，同样在被停止的回合下方显示。
-## 安全模型
-- **隔离：**
-  - iframe 设置 `sandbox="allow-scripts allow-forms"` 并使用 `srcdoc`，**不加** `allow-same-origin`。
-  - E2E 在浏览器中实测：访问 `parent.document`、`localStorage`、`cookie` 均抛出 `SecurityError`，`fetch` 被拦截，`window.origin` 为 `"null"`。
-- **CSP：**
-  - `default-src 'none'`；
-  - 脚本、样式、字体、图片只能来自 `cdnAllowlist`；
-  - 默认 `connect-src 'none'`；
-  - `form-action 'none'`、`base-uri 'none'`。
-- **消息校验：**
-  - 宿主只接受来自该 iframe 的 `contentWindow`、带随机 token、且格式合法的消息。
-  - 持久化的组件状态是有大小上限的 JSON。
-  - E2E 实测，从页面或 iframe 伪造的消息都会被丢弃。
-- **sendPrompt 限制：**
-  - 挂载后 1 秒内拒绝发送；
-  - 2 秒内最多发送一次；
-  - 长度受 `sendPromptMaxChars` 限制；
-  - 以普通的排队用户消息发送。
-- **openLink：** 只允许 https，可用白名单进一步限制。
-- **Plot 表达式：** 由分词器和解析器编译，只能调用固定的数学函数表，无法使用 `eval`、`Function` 或访问属性。
+## 🔒 安全模型
-## 安装
+<img src="https://raw.githubusercontent.com/dreamfarer-space/deepseek-harness-intelligent-ui/main/docs/assets/readme/security.zh.svg" alt="组件运行在不透明源沙箱 iframe 中并受严格 CSP 约束；访问宿主页面会被拦截，只有通过 token 校验的 postMessage 才能到达限流的 Bridge" width="100%">
-需要 [DeepSeek Harness](https://github.com/deepseek-ai/deepseek-harness) **0.1.7 – 0.2.x**（`>=0.1.7-rc.1 <0.3.0`）和 Node.js ≥ 22.13，Windows、Linux、macOS 均可。安装过程不需要编译：npm 包自带预构建的浏览器端 bundle，也没有任何安装脚本。
+- **隔离：** iframe 设置 `sandbox="allow-scripts allow-forms"` 并使用 `srcdoc`，**不加** `allow-same-origin`。E2E 在浏览器中实测：访问 `parent.document`、`localStorage`、`cookie` 均抛出 `SecurityError`，`fetch` 被拦截，`window.origin` 为 `"null"`。
+- **CSP：** `default-src 'none'`；脚本、样式、字体、图片只能来自 `cdnAllowlist`；默认 `connect-src 'none'`；`form-action 'none'`、`base-uri 'none'`。
+- **消息校验：** 宿主只接受来自该 iframe 的 `contentWindow`、带随机 token、且格式合法的消息。持久化的组件状态是有大小上限的 JSON。E2E 实测，从页面或 iframe 伪造的消息都会被丢弃。
+- **sendPrompt 限制：** 挂载后 1 秒内拒绝发送；2 秒内最多发送一次；长度受 `sendPromptMaxChars` 限制；以普通的排队用户消息发送。
+- **openLink：** 只允许 https，可用 `openLinkAllowedOrigins` 白名单进一步限制。
+- **Plot 表达式：** 由分词器和解析器编译，只能调用固定的数学函数表，无法使用 `eval`、`Function` 或访问属性。
-```sh
-dsh plugin --profile web add deepseek-harness-intelligent-ui
-```
+## ⚙️ 配置
-也可以用引导式安装器。它会先检查 Node、`dsh` 版本、pnpm 和 profile，检查通过后执行同样的 `dsh plugin add`：
+安装后 bundle patch 会自动插入 `intelligent-ui` 这一行。要修改配置，在 profile 的 `cordis.patch.yml` 中添加：
-```sh
-npx deepseek-harness-intelligent-ui install            # 可选 --profile <名称>、--dsh <路径>、--dry-run
-npx deepseek-harness-intelligent-ui doctor             # 只诊断，不做修改
+```yaml
+- id: intelligent-ui
+  config:
+    allowNetwork: true
+    cdnAllowlist: [https://esm.sh, https://cdn.jsdelivr.net]
 ```
-| 操作 | 命令 |
-|---|---|
-| 升级 | `dsh plugin --profile web add deepseek-harness-intelligent-ui@latest` |
-| 试用预发布版（仅在存在 `next` 标签时） | `dsh plugin --profile web add deepseek-harness-intelligent-ui@next` |
-| 固定版本 | `dsh plugin --profile web add deepseek-harness-intelligent-ui@0.2.2` |
-| 卸载 | `dsh plugin --profile web remove deepseek-harness-intelligent-ui`（或 `npx deepseek-harness-intelligent-ui uninstall`） |
-| 从源码目录安装 | `dsh plugin --profile web add file:/path/to/deepseek-harness-intelligent-ui` |
-安装后需要重启 DSH Web。bundle patch 会自动插入 `intelligent-ui` 这一行。要修改配置，在 profile 的 `cordis.patch.yml` 中添加 `- id: intelligent-ui` 和对应的 `config:`，配置项见英文 README 的表格。支持的 DSH 版本和 CI 测试矩阵见 [docs/compatibility.md](https://github.com/dreamfarer-space/deepseek-harness-intelligent-ui/blob/v0.2.2/docs/compatibility.md)。
-**常见问题**
-- *提示 `pnpm was not found`*：DSH 用 pnpm 安装插件。运行 `corepack enable`（Node 自带）或 `npm i -g pnpm`。
-- *提示 `… is incompatible with dsh X`*：当前 DSH 版本不在支持范围内。可以升级 DSH（`npm i -g @deepseek-ai/dsh@latest`），或在[兼容性文档](https://github.com/dreamfarer-space/deepseek-harness-intelligent-ui/blob/v0.2.2/docs/compatibility.md)里找支持该版本的插件发行版。
-- *从 0.1.x 升级（以前用 `file:` 安装的 `dsh-intelligent-ui`）*：先运行 `dsh plugin --profile web remove dsh-intelligent-ui`。新旧两个包会插入同一个 `intelligent-ui` 行，`doctor` 能检测到这种冲突。
-- *界面没有出现*：安装后要重启 DSH Web，并确认启动的是安装插件时指定的 profile（`dsh web`）。
+| 配置项 | 默认值 | 含义 |
+|---|---|---|
+| `enableCatalog` | `true` | 注册 `ui_render` |
+| `enableWidget` | `true` | 注册 `ui_render_widget` |
+| `injectGuidance` | `true` | 注入“何时使用 UI”的系统提示 |
+| `cdnAllowlist` | esm.sh、jsdelivr、unpkg | 组件（以及 Math/Mermaid）可加载资源的来源 |
+| `allowNetwork` | `false` | 允许组件对上述来源发起 `fetch` 和 WebSocket |
+| `maxWidgetHeight` | `2400` | iframe 最大高度（px） |
+| `maxWidgetBytes` | `400000` | 超过此大小的组件会被拒绝 |
+| `sendPromptMaxChars` | `4000` | 组件、按钮、表单单条消息的最大长度 |
+| `openLinkAllowedOrigins` | `[]` | 非空时，`openLink` 只能打开这些来源 |
-## 开发与验证
+## 🛠 开发与验证
 ```sh
 npm install
@@ -178,13 +272,16 @@ npm run e2e:all               # 构建 → 安装到临时 DSH 目录 → mock
 npm run e2e:all -- --record   # 同时重新录制 docs/assets/demo.mp4 / demo.gif（需要 ffmpeg）
 npm run e2e:all -- --spec ./deepseek-harness-intelligent-ui-<版本>.tgz   # 改为对 npm pack 打出的包做 E2E
 npm run smoke -- --spec ./deepseek-harness-intelligent-ui-<版本>.tgz     # 安装冒烟测试（不需要浏览器）
+npm run docs:art              # 重新生成 docs/assets/readme/ 下的 README 动画插图
 ```
 E2E 可以在 Windows、Linux、macOS 上运行。它会按平台自动查找 Chrome（可用 `CHROME_PATH` 指定），`DSH_BIN` 可指定其他 `dsh` 可执行文件。检查项见 `scripts/e2e/browser.mjs`，最近一次报告在 [`docs/e2e-report.json`](https://github.com/dreamfarer-space/deepseek-harness-intelligent-ui/blob/v0.2.1/docs/e2e-report.json)。GitHub Actions 会在三个系统上，针对每个受支持的 DSH 版本跑完全部测试。
 `client/client.js` 已提交到仓库并随包发布，所以 npm、`file:` 和 git 安装都不需要构建。不要添加 `prepare` 或 `postinstall` 脚本，因为 DSH 使用的 pnpm 会拦截插件的构建脚本。
-**发布流程**（维护者）：
+<details>
+<summary><b>📦 发布流程</b>（维护者）</summary>
+<br>
 发布安全与 OIDC 配置见[维护者说明](https://github.com/dreamfarer-space/deepseek-harness-intelligent-ui/blob/main/docs/releasing.md)。
@@ -197,7 +294,11 @@ E2E 可以在 Windows、Linux、macOS 上运行。它会按平台自动查找 Ch
    - 用 CHANGELOG 的对应小节和 tarball 创建 GitHub Release。
 4. 本地可以先运行 `npm run release:check` 做同样的预检。
-## 真实模型评测
+</details>
+<details>
+<summary><b>🤖 真实模型评测</b></summary>
+<br>
 API 测试套件覆盖 15 个提示词，检查模型路由、工具参数格式，以及部分指定组件和数据。它**不会在浏览器中执行模型生成的组件**，也不验证数据事实、视觉质量、物理正确性或交互行为。独立浏览器 E2E 使用脚本化模型回复。
@@ -219,6 +320,8 @@ node scripts/run-real-model-suite.mjs all
 每次仅将本次用例写入 `docs/real-model-eval-report.json`，分类运行不混入旧结果。断言或 API 请求失败时返回退出码 1；类别错误或密钥缺失会在改写报告前退出。请勿将密钥提交到 git。
+</details>
 ## 已知限制
 - 沙箱组件、`Math` 和 `Mermaid` 需要能访问 CDN 白名单。离线时，`Math` 和 `Mermaid` 退回显示源码，`UI.three` 会报告脚本错误。

package/client/client.js CHANGED Viewed

@@ -1,4 +1,4 @@
-/* deepseek-harness-intelligent-ui 0.2.2 — generated by scripts/build-client.mjs; do not edit. */
+/* deepseek-harness-intelligent-ui 0.2.3 — generated by scripts/build-client.mjs; do not edit. */
 window.__ModuleLoader__.load({ id: "deepseek-harness-intelligent-ui", factory: (require) => {
 var module = { exports: {} }; var exports = module.exports;
 "use strict";var Re=Object.defineProperty;var Dn=Object.getOwnPropertyDescriptor;var qn=Object.getOwnPropertyNames;var Hn=Object.prototype.hasOwnProperty;var Bn=(e,t,n)=>t in e?Re(e,t,{enumerable:!0,configurable:!0,writable:!0,value:n}):e[t]=n;var Wn=(e,t)=>{for(var n in t)Re(e,n,{get:t[n],enumerable:!0})},Vn=(e,t,n,r)=>{if(t&&typeof t=="object"||typeof t=="function")for(let i of qn(t))!Hn.call(e,i)&&i!==n&&Re(e,i,{get:()=>t[i],enumerable:!(r=Dn(t,i))||r.enumerable});return e};var Jn=e=>Vn(Re({},"__esModule",{value:!0}),e);var z=(e,t,n)=>Bn(e,typeof t!="symbol"?t+"":t,n);var Zr={};Wn(Zr,{apply:()=>Yr,inject:()=>Xr,promptSession:()=>zn});module.exports=Jn(Zr);var Ie=Object.freeze({sin:[1,Math.sin],cos:[1,Math.cos],tan:[1,Math.tan],asin:[1,Math.asin],acos:[1,Math.acos],atan:[1,Math.atan],atan2:[2,Math.atan2],sinh:[1,Math.sinh],cosh:[1,Math.cosh],tanh:[1,Math.tanh],exp:[1,Math.exp],ln:[1,Math.log],log:[1,Math.log10],log10:[1,Math.log10],log2:[1,Math.log2],sqrt:[1,Math.sqrt],cbrt:[1,Math.cbrt],abs:[1,Math.abs],sign:[1,Math.sign],floor:[1,Math.floor],ceil:[1,Math.ceil],round:[1,Math.round],min:[-1,Math.min],max:[-1,Math.max],pow:[2,Math.pow],hypot:[-1,Math.hypot]}),Lt=Object.freeze({pi:Math.PI,e:Math.E,tau:2*Math.PI}),_t=(e,t)=>Object.prototype.hasOwnProperty.call(e,t)?e[t]:void 0,Ut=500;function Kn(e){let t=[],n=0;for(;n<e.length;){let r=e[n];if(r===" "||r==="	"||r===`

package/package.json CHANGED Viewed

@@ -1,6 +1,6 @@
 {
   "name": "deepseek-harness-intelligent-ui",
-  "version": "0.2.2",
+  "version": "0.2.3",
   "description": "DeepSeek Harness Intelligent UI: generative, interactive UI in the chat (declarative component catalog + sandboxed streaming HTML widgets), inspired by CopilotKit OpenIntelligentUI.",
   "keywords": [
     "deepseek-harness",
@@ -28,7 +28,7 @@
     "./package.json": "./package.json"
   },
   "bin": {
-    "deepseek-harness-intelligent-ui": "./bin/cli.mjs"
+    "deepseek-harness-intelligent-ui": "bin/cli.mjs"
   },
   "files": [
     "bin",
@@ -68,7 +68,8 @@
     "version": "node scripts/build-client.mjs && git add client/client.js",
     "prepublishOnly": "node scripts/build-client.mjs && git diff --exit-code -- client/client.js && vitest run",
     "release:check": "node scripts/ci/release-check.mjs",
-    "smoke": "node scripts/ci/smoke.mjs"
+    "smoke": "node scripts/ci/smoke.mjs",
+    "docs:art": "node scripts/docs/readme-art.mjs"
   },
   "peerDependencies": {
     "@deepseek-ai/cordis": "~4.0.4 || >=4.0.5-alpha.0 <4.1.0-0",

package/src/compat.js CHANGED Viewed

@@ -12,7 +12,7 @@
 export const SUPPORTED_DSH_RANGE = '>=0.1.7-rc.1 <0.3.0-0 || >=0.2.0-0 <0.2.0 || >=0.2.1-0 <0.2.1';
 /** Versions the CI compatibility matrix installs the packed plugin into. */
-export const TESTED_DSH_VERSIONS = Object.freeze(['0.1.7-rc.2', '0.2.0-rc.1', '0.2.0-rc.2', '0.2.1-alpha.2']);
+export const TESTED_DSH_VERSIONS = Object.freeze(['0.1.7-rc.2', '0.2.0-rc.1', '0.2.0-rc.2', '0.2.1-alpha.2', '0.2.1-alpha.4']);
 /** Lowest Node.js version DSH itself requires. */
 export const MIN_NODE_VERSION = '22.13.0';