@zephinel/dsh-intelligent-ui 0.2.2-26-10-21 → 0.4.0

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.
package/NOTICE CHANGED
@@ -50,5 +50,16 @@ zod
50
50
  MIT License.
51
51
  Full text: licenses/zod-LICENSE.
52
52
 
53
- React and React DOM are provided by the hosting DeepSeek Harness platform and
54
- are not bundled in this package.
53
+ SnapDOM — @zumer/snapdom
54
+ https://github.com/zumerlab/snapdom
55
+ MIT License, Copyright (c) 2025 ZumerLab.
56
+ Bundled for the browser-side answer image export.
57
+ Full text: licenses/snapdom-LICENSE.
58
+
59
+ React and React DOM
60
+ https://github.com/facebook/react
61
+ MIT License, Copyright (c) Meta Platforms, Inc. and affiliates.
62
+ The hosting DeepSeek Harness platform provides React for the client bundle;
63
+ the standalone interactive-page bundle additionally inlines React and
64
+ React DOM so the exported HTML runs without DSH.
65
+ Full text: licenses/react-LICENSE.
package/README.en.md CHANGED
@@ -1,3 +1,5 @@
1
+ <img src="icon.svg" alt="dsh-intelligent-ui" width="72" height="72" align="right">
2
+
1
3
  # dsh-intelligent-ui
2
4
 
3
5
  [中文](README.md) | English
@@ -12,7 +14,10 @@
12
14
  Ported from [Open Intelligent UI](https://github.com/thesysdev/open-intelligent-ui) (MIT), with an Agent Skill (`intelligent-ui`) that the plugin registers automatically.
13
15
 
14
16
  > [!NOTE]
15
- > **Current status**: published on GitHub and npm as **`@zephinel/dsh-intelligent-ui@0.2.2-26-10-21`** (`latest`).
17
+ > **Current status**: published on GitHub and npm as **`@zephinel/dsh-intelligent-ui@0.4.0`** (`latest`). Custom styles, on-demand generation and the on-demand lifecycle/content-grounding fixes described below are all included in 0.4.0.
18
+
19
+ > [!TIP]
20
+ > **Want to try it now?** Install with one command: `dsh plugin --profile web add @zephinel/dsh-intelligent-ui`; restart the DSH process that serves the Web UI, then choose **This session only** from the **UI** control in the composer. See [Quick start](#quick-start) for the full path.
16
21
 
17
22
  ## What it looks like
18
23
 
@@ -24,13 +29,13 @@ Ported from [Open Intelligent UI](https://github.com/thesysdev/open-intelligent-
24
29
 
25
30
  ## Component tour
26
31
 
27
- The renderer is not a chat bubble around a paragraph — it is a full component library: **55 components, 73 functions, 5 action steps**. The three cards below are real renders from the extension: same renderer, same DSH theme tokens, no mockups:
32
+ The renderer is not a chat bubble around a paragraph — it is a full component library: **57 components, 73 functions, 5 action steps**. The three cards below are real renders from the extension: same renderer, same DSH theme tokens, no mockups:
28
33
 
29
- ![Layout and typography: Col, Row, Box, Grid, Card, Carousel, Popover, Divider, Spacer and 12 text components](assets/intelligent-ui-components-layout.webp)
34
+ ![Everything you can render: 57 components, 73 functions and 5 actions, plus the layout (11) and text (12) component groups](assets/intelligent-ui-components-layout.webp)
30
35
 
31
- ![Inputs, media and data: 13 form controls plus photos, tables, charts, maps and YouTube](assets/intelligent-ui-components-inputs.webp)
36
+ ![Inputs, media and data: 13 input components plus photos, tables, charts, maps and YouTube](assets/intelligent-ui-components-inputs.webp)
32
37
 
33
- ![Play and drawing: flip cards, the confetti trigger, ten SVG shape primitives and a sandboxed iframe game](assets/intelligent-ui-components-drawing.webp)
38
+ ![Play and drawing: flip cards, the confetti trigger, ten SVG drawing components and a sandboxed iframe game](assets/intelligent-ui-components-drawing.webp)
34
39
 
35
40
  ## More examples
36
41
 
@@ -40,19 +45,24 @@ The renderer is not a chat bubble around a paragraph — it is a full component
40
45
 
41
46
  On a narrow screen (about 380 px) the card switches to a single column, and maps and charts fit the card width; over-long chart category labels are trimmed instead of overflowing:
42
47
 
43
- ![The pour-over coffee calculator on a narrow screen: single-column cards, no horizontal overflow](assets/intelligent-ui-responsive.webp)
48
+ ![The pour-over coffee calculator on a narrow screen: single-column layout, no horizontal overflow](assets/intelligent-ui-responsive.webp)
44
49
 
45
50
  ## Capabilities
46
51
 
47
52
  | Capability | What it gives you |
48
53
  |---|---|
49
54
  | Interactive pages | Maps, photos, charts, checklists, forms, SVG drawings and mini-games are real components, not screenshots |
55
+ | Image export | Saves the rendered result as one PNG with a raw, rounded or card frame; background color and 1x/2x live on the Plugin detail page |
56
+ | Interactive-page export | Saves every card from the turn as a single-file HTML page; open it in a browser to keep interacting, and `@ToAssistant` copies its message plus a paste-back-into-DSH hint |
50
57
  | Local execution | `$variables`, `@Set` and `@functions` run in the browser; only `@ToAssistant` writes a message back |
51
- | Three-state switch | Off by default; "This session only" / "All sessions"; composer UI control or `/iui` commands |
58
+ | Switch and style | Global defaults on the Plugin detail page; composer overrides per session; built-in Auto / Card / Article and custom templates |
59
+ | Custom templates and visual themes | Reusable display preferences with light/dark palettes, font, radius, density and shadow; use, rename, edit or delete in My styles |
60
+ | Chat-native on-demand UI | No template required; choose On-demand UI in the UI panel, send a normal message, clarify with the built-in question tool when needed |
61
+ | Temporary results and optional saving | Inline style snapshots are ready to use, adjust or save later; no required preview, naming or saving |
52
62
  | Bilingual UI | Follows DSH's UI language; dictionaries live in `src/shared/locales.ts` |
53
63
  | Agent Skill | Registers `intelligent-ui` with the plugin so the model can load syntax, examples and troubleshooting on demand |
54
- | Plugin detail page | Plugins → Intelligent UI detail page: a Free composition switch; the default playbook, or a model-chosen layout when on |
55
- | Replayable | The generated program enters the session log as a tool argument and replays with history |
64
+ | Plugin detail page | Plugins → Intelligent UI detail page: Availability (global enable), Answer style (built-in or saved template), My styles management, Composition (Free-form layout) and Export (background color, resolution, whether images/pages remove follow-up blocks; on by default) |
65
+ | Replayable | Programs and temporary styles replay from recorded tool arguments; exported pages freeze the scheme at export time |
56
66
 
57
67
  ## Getting the code
58
68
 
@@ -63,12 +73,12 @@ git clone https://github.com/Zephinel/dsh-intelligent-ui.git
63
73
  cd dsh-intelligent-ui
64
74
  ```
65
75
 
66
- You can also install it from npm without a checkout (next section).
76
+ You can also install it from npm without a checkout (see [Quick start](#quick-start)).
67
77
 
68
78
  ## Prerequisites
69
79
 
70
- - **DSH 0.2.1** (the [`dsh` CLI](https://www.npmjs.com/package/@deepseek-ai/dsh)): the Host/Client halves and plugin protocol are developed against this version; the verified version is `0.2.1-rc.2`, and later versions are unverified.
71
- - **Node.js 24**: build, tests and `npm pack` are verified on Node 24; the Host bundle targets Node 22 (`target: 'node22'`), and the repository has no `engines` or `.nvmrc` pin, so verify a lower version yourself before using one.
80
+ - **DSH 0.2.1** (the [`dsh` CLI](https://www.npmjs.com/package/@deepseek-ai/dsh)): the Host/Client halves and plugin protocol are developed against this version; the verified version is `0.2.1-rc.2`, and later versions are unverified. Install with `npm install -g @deepseek-ai/dsh`.
81
+ - **[Node.js 24](https://nodejs.org/en/download)**: build, tests and `npm pack` are verified on Node 24; the Host bundle targets Node 22 (`target: 'node22'`), and the repository has no `engines` or `.nvmrc` pin, so verify a lower version yourself before using one.
72
82
  - **`@deepseek-ai/dsh-client-locale`**: the browser half requires a deployment that composes it; DSH Web 0.2.1 includes it by default, and without it the switch and card do not mount (the Host tool and prompt keep working).
73
83
 
74
84
  Confirm the tools are present:
@@ -88,7 +98,7 @@ Install from npm (prerequisites are in the previous section):
88
98
  dsh plugin --profile web add @zephinel/dsh-intelligent-ui
89
99
 
90
100
  # pin the current version
91
- dsh plugin --profile web add @zephinel/dsh-intelligent-ui@0.2.2-26-10-21
101
+ dsh plugin --profile web add @zephinel/dsh-intelligent-ui@0.4.0
92
102
 
93
103
  # or install from GitHub
94
104
  dsh plugin --profile web add github:Zephinel/dsh-intelligent-ui
@@ -99,37 +109,32 @@ Restart the DSH process that serves the Web UI (foreground `dsh web`: Ctrl+C, th
99
109
  **DSH Desktop** needs no terminal command — install it inside the app:
100
110
 
101
111
  1. Open **Plugins** in the sidebar → **Add plugin** (or the arrow → **Install a third-party plugin**).
102
- 2. Enter `@zephinel/dsh-intelligent-ui@0.2.2-26-10-21` (or just the package name for the latest), then click **Install**.
112
+ 2. Enter `@zephinel/dsh-intelligent-ui@0.4.0` (or just the package name for the latest), then click **Install**.
103
113
  3. When the install finishes, click **Enable now**; if the **UI** control does not appear, quit and reopen DSH Desktop.
104
114
 
105
115
  The desktop profile is owned by the Electron app, so `dsh plugin --profile desktop` is rejected. A mainland-China mirror can lag behind the official npm registry for a fresh release; switch the install source back to npm if the version is not found.
106
116
 
107
- For local development, install from a checkout. The extension has **no development server of its own** — it runs inside DSH. The loop is: build → install into the profile → restart DSH Web → open the URL it prints; the **UI** control appears when it worked. There is no watch mode: rebuild with `npm run build` and restart per the cache note below.
108
-
109
- ```bash
110
- cd /path/to/dsh-intelligent-ui
111
- npm install && npm run build
112
- node scripts/install.mjs # writes $DSH_HOME/profiles/web/cordis.patch.yml (automatic backup)
113
- ```
114
-
115
- > [!IMPORTANT]
116
- > After renaming the package or rebuilding `lib/client.js`, a page refresh may keep the old revision; restart the DSH process that serves the Web UI, then reopen the page.
117
-
118
- Then click the **UI** control, choose "This session only" or "All sessions" (or `/iui session` / `/iui global`), and ask, for example:
117
+ Then click the **UI** control, choose "This session only" (or `/iui on`), set the session Auto / Card / Article style in the same panel if needed, and ask, for example:
119
118
 
120
119
  ```text
121
120
  Plan two days in Shanghai, with checkboxes and adjustments
122
121
  ```
123
122
 
124
- See [Development and deployment](https://github.com/Zephinel/dsh-intelligent-ui/blob/main/docs/development.en.md) for uninstall, development and troubleshooting.
123
+ See [Development and deployment](https://github.com/Zephinel/dsh-intelligent-ui/blob/main/docs/development.en.md) for the local-checkout development loop, uninstall and troubleshooting; the extension has no development server of its own.
125
124
 
126
- ## Three-state switch
125
+ ## Switch and answer style
127
126
 
128
- ![The UI control on the right side of the composer: clicking it opens an "Off / This session only / All sessions" menu (screenshot from the English UI)](assets/intelligent-ui-toggle.png)
127
+ ![The composer UI control: Off / This session only / All sessions, plus Display style below an inset divider](assets/intelligent-ui-toggle.png)
129
128
 
130
- - **Off** (default): no `render_ui` schema in any session's request, and the ~8.5K-token generation prompt expands to nothing.
131
- - **This session only** / **All sessions**: scopes the current session or every session (including ones opened later); the **UI** control is equivalent to `/iui off|session|global`.
132
- - State is written atomically to `<DSH_HOME>/dsh-intelligent-ui.json` and survives a refresh or DSH restart; see [Architecture and behavior](https://github.com/Zephinel/dsh-intelligent-ui/blob/main/docs/architecture.en.md) for the full semantics (projection, cross-tab sync, service requirements).
129
+ ![Style panel: built-in Auto / Card / Article cards, Custom styles and On-demand UI at the bottom](assets/intelligent-ui-style-panel.webp)
130
+
131
+ - **Global defaults:** the Plugin detail page sets **Enable in all sessions** and **Answer style** for new sessions; choose a built-in style or a saved global template.
132
+ - **Session overrides:** Composer **UI** chip → **This session only** or **Display style** opens the panel: built-in Auto / Card / Article preview cards, **Custom styles** (saved templates), then **On-demand UI** at the bottom. **All sessions** follows the global switch for this session without turning it on globally. Commands are `/iui on|off|inherit` and `/iui style auto|card|article|inherit|<cs_id>`.
133
+ - **Auto** chooses compact Card for interactive/structured answers and Article for detailed/long-form ones. Article needs a `Toc`, collapsible `Section`s and substantive prose.
134
+ - **On-demand UI:** choosing it closes the panel, focuses the composer and shows a cancellable hint with examples. Examples fill without sending and preserve the existing draft. Send normally: clear requests render directly; material ambiguity uses the built-in `ask_user_question`, then generation continues after the answer.
135
+ - Session enable/style settings are written atomically to `<DSH_HOME>/dsh-intelligent-ui.json`. An on-demand operation changes neither setting; a temporary style is not the selected style. See [Architecture and behavior](https://github.com/Zephinel/dsh-intelligent-ui/blob/main/docs/architecture.en.md) for the boundaries.
136
+
137
+ ![Armed on-demand hint: examples fill the composer without sending](assets/intelligent-ui-on-demand-hint.webp)
133
138
 
134
139
  ## Usage
135
140
 
@@ -139,24 +144,51 @@ With the switch on, just ask in natural language, for example:
139
144
  - "Build a gear-shifting simulator for a 7-speed bicycle"
140
145
  - "Turn these tables into a sales dashboard I can filter"
141
146
  - "Introduce Chinese history, expandable by dynasty"
147
+ - Choose On-demand UI, then send "Make this analysis a compact dashboard; highlight key metrics with cards and charts"
148
+ - Choose Adjust style on the result, then send "Keep the content and use a more spacious reading layout"
142
149
 
143
150
  Once enabled, **any answer with structure defaults to a card** — including explanations, introductions, timelines, stages, comparisons and things to explore; Markdown is reserved for a single fact, a one- or two-sentence reply, an explicit request for text/document/code, or repeated render failures. When the switch is off the model cannot see `render_ui` and answers in plain text — that is not a failure; turn the switch on and ask again.
144
151
 
145
152
  To guarantee a card (or when the model still replies in text), invoke the skill explicitly with `/intelligent-ui` in a session where the switch is on; explicit invocation is treated as a direct instruction. You can also say "read the intelligent-ui skill and then build ... with render_ui".
146
153
 
147
- The extension also adds a **Free composition** switch on the **Plugins → Intelligent UI detail page**: off by default (the extension's design playbook); when on, the playbook is advisory and the model may choose components and layout for the content (the hard rules, theme tokens and readability still apply). The choice persists in the DSH settings document and applies to every session.
154
+ ![Temporary result: badge, Adjust style and Save as template](assets/intelligent-ui-temporary-result.webp)
155
+
156
+ ![The same temporary result under the fixed dark theme](assets/intelligent-ui-temporary-result-dark.webp)
157
+
158
+ A temporary result is ready to use. **Adjust style** binds that result and fills an adjustment prompt while preserving your draft; send it normally. **Save as template** optionally asks for a name, description and availability (this session or global). Saving reuses the validated result style, makes no new model request, and neither selects the template nor changes the global default. No preview, naming or saving is required before use.
159
+
160
+ ![Plugin detail page: global enable, default style, My styles management, composition and export](assets/intelligent-ui-settings.webp)
161
+
162
+ The Plugin detail page groups settings into **Availability**, **Answer style**, **My styles**, **Composition** and **Export**. My styles manages saved global templates: set as default, rename, edit description/display preferences, export JSON or delete. The composer manages global and session templates visible in that session. Generation happens in the composer; settings explain the entry without providing a generation workbench. Global values are the defaults for new sessions; a session override in the composer wins. **Free-form layout** only changes how strongly the design guidance is advisory; it is orthogonal to the answer style. **Export** stores the default background color, the 1x/2x resolution, and whether images/pages remove the whole `@ToAssistant` follow-up block (on by default).
163
+
164
+ Once an answer has rendered, a labeled **export pill** appears at the **far right** of the message action strip (visually distinct from the native copy / like / branch icons); only answers rendered by the extension have it. It can save every card from that turn as one PNG — **Raw** (the answer alone), **Rounded** (background color and rounded padding) or **Card** (padding, rounded corners and a soft shadow) — or export them as a single-file HTML page, which opens in a browser with the interactions intact; in that page `@ToAssistant` copies the message and shows the paste-back-into-DSH hint instead of calling DSH. The image contains the rendered cards only, not the Markdown text around them and not the export control itself. See [Architecture and behavior](https://github.com/Zephinel/dsh-intelligent-ui/blob/main/docs/architecture.en.md) for the full flow.
148
165
 
149
166
  ## Build, test and deploy
150
167
 
168
+ For local development from a fresh clone, install dependencies, build and write the local DSH profile:
169
+
170
+ ```bash
171
+ npm install
172
+ npm run build
173
+ node scripts/install.mjs
174
+ ```
175
+
176
+ Restart the DSH process serving the Web UI, then open the URL it prints; the **UI** control on the right of the composer means it worked. There is no development server and no watch mode; see [Development and deployment](https://github.com/Zephinel/dsh-intelligent-ui/blob/main/docs/development.en.md) for details and uninstall.
177
+
178
+ Everyday checks and packaging:
179
+
151
180
  ```bash
152
181
  npm run build # build the prompt, Host and Client bundle
153
182
  npm run check # build + Host/Client/packaging tests + renderer checks
154
183
  npm run pack:check # inspect the final npm pack file list
184
+ npm run test:browser # build first; 7 browser suites: on-demand, style panel, theme, image, interactive page, Article spacing, settings (Chrome required)
155
185
  ```
156
186
 
187
+ - Current Node tests: **179**; renderer parse/render **41/41** each, i18n **4** programs, typography **22/22**. Browser checks cover components/contracts; the on-demand main path (clear request → temporary-style card → save as template), free-form clarification when content is missing, and the real-data grounding rule have been verified with the real model in an isolated DSH Web instance; remaining scenarios are in the [verification record](https://github.com/Zephinel/dsh-intelligent-ui/blob/main/docs/verification.en.md).
188
+ - `node scripts/capture-screenshots.mjs` rebuilds panel, hint, temporary-result and settings captures at 2x in Chrome using fixed DSH tokens, production components and fake services. English UI; shell card glyphs use lucide stand-ins.
157
189
  - The typography check inside `npm run check` needs a local Chrome; without one that check is skipped and the remaining tests still run.
158
190
 
159
- The published artifact is a DSH bundle; deploying means installing the plugin into the target DSH profile. See [Development and deployment](https://github.com/Zephinel/dsh-intelligent-ui/blob/main/docs/development.en.md) for uninstall, local development and version notes.
191
+ The published artifact is a DSH bundle; deploying means installing the plugin into the target DSH profile. See [Development and deployment](https://github.com/Zephinel/dsh-intelligent-ui/blob/main/docs/development.en.md) for uninstall and version notes.
160
192
 
161
193
  ## Contributing
162
194
 
@@ -164,6 +196,7 @@ The published artifact is a DSH bundle; deploying means installing the plugin in
164
196
  - Run `npm run check` before submitting; there is no PR CI, so the local command is the gate. Releases are published by the GitHub Actions Trusted Publishing workflow (push a `v*` tag that matches `package.json`).
165
197
  - When behavior, copy or counts change, update the Chinese and English READMEs, `CHANGELOG.md`, and the matching documents under `docs/`; the sync rules live in `.agents/skills/sync-iui-docs/SKILL.md` (development-only, not shipped in the npm package).
166
198
  - Repository maintenance skills and doc-sync rules live under `.agents/skills/` (not shipped); AI coding agents also use `npm run check` as the pre-submit gate.
199
+ - Maintainer: [@Zephinel](https://github.com/Zephinel).
167
200
 
168
201
  ## Known limitations
169
202
 
@@ -171,18 +204,43 @@ The published artifact is a DSH bundle; deploying means installing the plugin in
171
204
  - The model occasionally generates invalid OpenUI Lang; Host validation returns precise errors, and it usually repairs them within the same turn (1–2 attempts in testing).
172
205
  - The map basemap relies on OpenFreeMap tiles, routes on the OSRM demo, and photos on Wikipedia/Wikimedia; when offline, maps degrade to a list of places and photos to placeholder blocks.
173
206
  - KaTeX uses global styles already loaded by the DSH shell; if those styles are removed, the Math component degrades to plain text.
174
- - The generation prompt is about 8.5K tokens and is **sent only when the switch covers that session** (all sessions, or the session is on the allowlist); when off, that cost is zero (the tool schema is absent too). Enabled requests are the same as the previous version, so DSH cache hits offset most of the cost.
207
+ - The generation prompt is about 9.5K tokens and is **sent only when the switch covers that session** (global on, or the session explicitly on); when off, that cost is zero (the tool schema is absent too). Article mode produces longer pages, so output tokens and render time increase accordingly.
175
208
  - The extension's UI copy follows DSH's UI language; the `/iui` Host replies, the command palette's command description and the README screenshots stay in English (the first two are DSH platform behavior).
209
+ - Image export does not capture sandboxed iframes (`HtmlView` mini-games), so that region is missing from the image; maps are captured through the preserved WebGL drawing buffer, and a browser without WebGL falls back to the map's own place-list presentation.
210
+ - Every card rendered by one turn is combined into one image; the image captures **what is currently rendered**, so it includes the interaction state at export time (checked items, active filters and so on). The export waits for in-card photos and image searches to settle (at most about 12.5 seconds); offline or still-pending photos are recorded from the placeholder state shown on the page.
211
+ - The interactive-page export inlines the renderer, the current theme and every card into one HTML file (about 3.4–4.9 MB), so it is large but install-free; maps, photos and other components still need the network. `@ToAssistant` in that page tries the clipboard and shows a toast; when the clipboard is unavailable the toast keeps the message for manual copying.
176
212
  - The browser half requires a deployment that composes `dsh-client-locale` (included by default in DSH Web 0.2.1); a minimal custom profile without it will not mount the switch or the card, while the Host tool and prompt keep working.
177
- - The configuration on the Plugin detail page requires the DSH settings services: a minimal custom profile without `dsh-settings` / `dsh-client-ui-settings` does not show it, and a Host/Client version mismatch can leave the switch unavailable. The free-composition switch only changes how strongly the prompt recommends the design playbook; it cannot guarantee every model ignores the defaults entirely.
213
+ - The configuration on the Plugin detail page requires the DSH settings services: a minimal custom profile without `dsh-settings` / `dsh-client-ui-settings` does not show it, and a Host/Client version mismatch can leave the switch unavailable. Global enable/style and free-form layout only change the prompt and page shape; no model is guaranteed to follow them perfectly, and session style overrides still rely on the Host-injected prompt.
214
+ - The interactive-page export needs the `webServer` service (included by default in DSH Web 0.2.1); a minimal custom profile without it cannot build the exported page, while image export is unaffected.
215
+
216
+ - Temporary styles live in recorded tool arguments/result snapshots, outside the catalog. Replay needs the call arguments in the loaded history window. Saving later depends on the bounded result registry (latest 200 records); an evicted result may still replay but cannot be saved. Saved templates and result snapshots persist in separate JSON files under `<DSH_HOME>`.
217
+ - Style creation/on-demand generation uses the deployment's default main-conversation model services; the extension supplies no separate generation model or draft interview service. `ask_user_question` is the structured clarification path; if unavailable, text questions are a degraded fallback — the hint stays and the next message continues the same operation without re-selecting On-demand UI (except after expiry, restart or failure).
218
+ - Operations are in memory: armed intent expires after 10 minutes; active operations cannot resume after restart and must be re-armed. Completed results survive. There is one active operation per session: re-arming replaces it while armed, while a bound running/clarifying operation rejects re-arming until explicitly cancelled. Clarification is limited to two rounds. A text-only completion without rendering returns to the pending/resume state and the next message continues; failed/interrupted turns show Retry/Dismiss guidance.
219
+ - Multi-tab binding is conservative: only the arming tab shows the hint, but the Host binds the next human message in the session without verifying its sending tab. Send from the arming tab and avoid concurrent messages in another tab.
220
+ - Custom themes apply to the renderer host; portaled popovers and sandboxed iframes keep the default theme, and semantic status colors remain renderer-owned. Exported pages freeze the light/dark scheme at export time.
221
+ - Saved-template directives are bounded display preferences (2,000 characters), with no authority over system, tool or safety rules. Limits are 40 global templates and 20 per session. Missing/deleted saved templates fall back to the default theme; inline temporary replay/export is catalog-independent.
222
+
223
+ ## FAQ
224
+
225
+ **Must I create a template, preview or name it first?** No. Choose On-demand UI and chat normally; use the result immediately. A name is needed only when you choose Save as template. Temporary results do not replace the selected session style.
226
+
227
+ **Can I save later or keep adjusting?** Yes. Use Adjust style or Save as template on that result. Saving uses the clicked result's version, not a later result. If the registry has evicted it, saving reports an unavailable snapshot.
228
+
229
+ **Why did clarification not continue generation?** A structured `ask_user_question` answer resumes the same operation; after a text question, the next message automatically continues it. Only expiry, restart, failure or interruption needs a re-arm/retry. Concurrent messages in multiple tabs may also consume the same intent.
230
+
231
+ **Why does an answer come back as plain text with no card?** First check that the switch is on for that session (the **UI** control in the composer, or `/iui on`). Even then the model may treat a single fact, a one- or two-sentence reply, or an explicit text/code request as a bounded exception. To force a card, invoke the skill explicitly with `/intelligent-ui` in a session where the switch is on. See [Usage](#usage).
232
+
233
+ **Why is there no export pill under an answer?** Only answers rendered by the extension have it; it is absent when the switch is off, the model replies in text, or rendering fails. See [Usage](#usage) and [Known limitations](#known-limitations).
234
+
235
+ **Why did the UI not change (or show an error) after rebuilding the plugin?** A page refresh may still load the old revision: restart the DSH process that serves the Web UI, then reopen the page. See [Development and deployment](https://github.com/Zephinel/dsh-intelligent-ui/blob/main/docs/development.en.md) for the exact errors and handling.
178
236
 
179
237
  ## Documentation
180
238
 
181
- - [Architecture and behavior](https://github.com/Zephinel/dsh-intelligent-ui/blob/main/docs/architecture.en.md): Host/Client component tree, the full three-state switch semantics, UI language and the Agent Skill.
182
- - [Development and deployment](https://github.com/Zephinel/dsh-intelligent-ui/blob/main/docs/development.en.md): install and uninstall, development commands, the restart tip after renaming/rebuilding, Host/Client version mismatch and the release layout.
239
+ - [Architecture and behavior](https://github.com/Zephinel/dsh-intelligent-ui/blob/main/docs/architecture.en.md): Host/Client component tree, the full switch and answer-style semantics, UI language, image and interactive-page export flows, and the Agent Skill.
240
+ - [Development and deployment](https://github.com/Zephinel/dsh-intelligent-ui/blob/main/docs/development.en.md): install and uninstall, development commands, the restart tip after renaming/rebuilding, Host/Client version mismatch, release layout and community marketplace maintenance.
183
241
  - [Verification record](https://github.com/Zephinel/dsh-intelligent-ui/blob/main/docs/verification.en.md): end-to-end verification, test and packaging results (historical).
184
242
  - [Changelog](https://github.com/Zephinel/dsh-intelligent-ui/blob/main/CHANGELOG.md): additions, changes and fixes per release.
185
243
 
186
244
  ## License
187
245
 
188
- This project is [MIT](LICENSE). It is based on Open Intelligent UI (MIT, Copyright (c) 2026 Thesys Inc.) and the OpenUI ecosystem; the browser bundle contains lucide-react (ISC), KaTeX (MIT), MapLibre GL JS (BSD-3-Clause) and zod (MIT). Full notices and license texts are in `NOTICE` and `licenses/`.
246
+ This project is [MIT](LICENSE). It is based on Open Intelligent UI (MIT, Copyright (c) 2026 Thesys Inc.) and the OpenUI ecosystem; the browser bundle contains lucide-react (ISC), KaTeX (MIT), MapLibre GL JS (BSD-3-Clause), zod (MIT) and SnapDOM (MIT); the standalone interactive-page bundle also inlines React / React DOM (MIT). Full notices and license texts are in `NOTICE` and `licenses/`.
package/README.md CHANGED
@@ -1,3 +1,5 @@
1
+ <img src="icon.svg" alt="dsh-intelligent-ui" width="72" height="72" align="right">
2
+
1
3
  # dsh-intelligent-ui
2
4
 
3
5
  中文 | [English](README.en.md)
@@ -12,7 +14,10 @@
12
14
  基于 [Open Intelligent UI](https://github.com/thesysdev/open-intelligent-ui)(MIT)移植,并附带一个随插件自动注册的 Agent Skill(`intelligent-ui`)。
13
15
 
14
16
  > [!NOTE]
15
- > **当前状态**:已发布到 GitHub 与 npm,npm 版本 **`@zephinel/dsh-intelligent-ui@0.2.2-26-10-21`**(`latest`)。
17
+ > **当前状态**:已发布到 GitHub 与 npm,npm 版本 **`@zephinel/dsh-intelligent-ui@0.4.0`**(`latest`)。自定义样式、按需生成以及按需生命周期与内容接地修复均已包含在 0.4.0 中。
18
+
19
+ > [!TIP]
20
+ > **想先跑起来?** 安装只需一条命令:`dsh plugin --profile web add @zephinel/dsh-intelligent-ui`;重启承载 Web UI 的 DSH 进程后,在输入框右侧的 **UI** 控件里选择「仅本会话」即可开启。完整步骤见[快速开始](#快速开始)。
16
21
 
17
22
  ## 效果
18
23
 
@@ -24,13 +29,13 @@
24
29
 
25
30
  ## 组件一览
26
31
 
27
- 渲染器不是把一段文字包进聊天气泡,而是一套完整的组件库:**55 个组件、73 个函数、5 种动作**。下面三张卡片都是扩展的真实渲染结果——同一套渲染器、同一套 DSH 主题 token,没有设计稿:
32
+ 渲染器不是把一段文字包进聊天气泡,而是一套完整的组件库:**57 个组件、73 个函数、5 种动作**。下面三张卡片都是扩展的真实渲染结果——同一套渲染器、同一套 DSH 主题 token,没有设计稿:
28
33
 
29
- ![布局与排版:Col、Row、Box、Grid、Card、Carousel、Popover、Divider、Spacer 与 12 个文本组件](assets/intelligent-ui-components-layout.webp)
34
+ ![一切可渲染的内容:57 个组件、73 个函数、5 类动作,以及布局(11 个)与文本(12 个)组件分组](assets/intelligent-ui-components-layout.webp)
30
35
 
31
- ![输入、媒体与数据:13 个表单控件,以及照片、表格、图表、地图与 YouTube](assets/intelligent-ui-components-inputs.webp)
36
+ ![输入、媒体与数据:13 个输入组件,以及照片、表格、图表、地图与 YouTube](assets/intelligent-ui-components-inputs.webp)
32
37
 
33
- ![交互与绘制:翻面卡、撒花开关、Svg 十种图元与沙盒 iframe 小游戏](assets/intelligent-ui-components-drawing.webp)
38
+ ![交互与绘制:翻面卡、撒花开关、十个 Svg 绘图组件与沙盒 iframe 小游戏](assets/intelligent-ui-components-drawing.webp)
34
39
 
35
40
  ## 更多示例
36
41
 
@@ -40,19 +45,24 @@
40
45
 
41
46
  窄屏下卡片自动切为单列,地图与图表按卡片宽度自适应;图表分类标签过长时会截断而不是溢出(约 380 px 宽):
42
47
 
43
- ![窄屏下的手冲咖啡计算器:单列卡片、无横向溢出](assets/intelligent-ui-responsive.webp)
48
+ ![窄屏下的手冲咖啡计算器:单列布局、无横向溢出](assets/intelligent-ui-responsive.webp)
44
49
 
45
50
  ## 核心能力
46
51
 
47
52
  | 能力 | 说明 |
48
53
  |---|---|
49
54
  | 交互页面 | 地图、照片、图表、清单、表单、SVG 绘图、小游戏都是真实组件,不是截图 |
55
+ | 导出图片 | 把该轮渲染结果保存为一张 PNG:原始 / 圆角 / 卡片三种美化;背景色与 1x/2x 在插件详情页设置 |
56
+ | 导出交互页面 | 把该轮全部卡片导出为单个 HTML 文件,浏览器打开后继续交互;`@ToAssistant` 改为复制文案并提示回 DSH 粘贴 |
50
57
  | 本地执行 | `$变量`、`@Set`、`@functions` 在浏览器运行;只有 `@ToAssistant` 回写消息 |
51
- | 三档开关 | 默认关闭;「仅本会话」/「全部会话」;输入框 UI 控件或 `/iui` 命令 |
58
+ | 开关与样式 | 全局默认在插件详情页;输入框 UI 控件按会话覆盖;内置 Auto / Card / Article 与自定义模板 |
59
+ | 自定义模板与视觉主题 | 保存可复用的展示偏好与明暗配色、字体、圆角、密度、阴影;在「我的样式」中使用、重命名、编辑或删除 |
60
+ | 聊天内按需生成 | 无需模板;在 UI 面板选择「按需生成」,正常发送需求,必要时用内置提问工具澄清 |
61
+ | 临时结果与可选保存 | 结果自带内联样式快照,可直接使用、调整样式或事后保存为模板;不强制预览、命名或保存 |
52
62
  | 双语界面 | 跟随 DSH 的界面语言;字典在 `src/shared/locales.ts` |
53
63
  | Agent Skill | 随插件注册 `intelligent-ui`,模型按需加载完整语法、示例与排障 |
54
- | 插件详情页 | 插件 → 智能 UI 详情页:自由布局开关;默认使用设计规范,开启后模型按内容自行组织版式 |
55
- | 可重放 | 生成程序作为工具参数进入会话日志,随历史重放 |
64
+ | 插件详情页 | 插件 → 智能 UI 详情页:可用性(全局启用)、回答样式(内置或已保存模板)、我的样式管理、编排方式(自由布局)、导出(背景色、分辨率、图片/页面导出是否移除追问区块,默认移除) |
65
+ | 可重放 | 程序与临时样式随工具参数重放;导出页面冻结导出时的主题方案 |
56
66
 
57
67
  ## 获取代码
58
68
 
@@ -63,12 +73,12 @@ git clone https://github.com/Zephinel/dsh-intelligent-ui.git
63
73
  cd dsh-intelligent-ui
64
74
  ```
65
75
 
66
- 也可以直接从 npm 安装,不需要 checkout(见下一节)。
76
+ 如果要提交改动,先 Fork 本仓库再克隆自己的副本;只想使用插件时,直接安装 npm 包即可(见[快速开始](#快速开始))。
67
77
 
68
78
  ## 前置条件
69
79
 
70
- - **DSH 0.2.1**([`dsh` CLI](https://www.npmjs.com/package/@deepseek-ai/dsh)):Host/Client 与插件协议按这个版本开发;实际验证版本是 `0.2.1-rc.2`,更晚版本未验证。
71
- - **Node.js 24**:构建、测试与 `npm pack` 都在 Node 24 下验证;Host 产物编译目标是 Node 22(`target: 'node22'`),仓库没有 `engines` 或 `.nvmrc` 版本锁,使用更低版本前请自行验证。
80
+ - **DSH 0.2.1**([`dsh` CLI](https://www.npmjs.com/package/@deepseek-ai/dsh)):Host/Client 与插件协议按这个版本开发;实际验证版本是 `0.2.1-rc.2`,更晚版本未验证。安装:`npm install -g @deepseek-ai/dsh`。
81
+ - **[Node.js 24](https://nodejs.org/en/download)**:构建、测试与 `npm pack` 都在 Node 24 下验证;Host 产物编译目标是 Node 22(`target: 'node22'`),仓库没有 `engines` 或 `.nvmrc` 版本锁,使用更低版本前请自行验证。
72
82
  - **`@deepseek-ai/dsh-client-locale`**:浏览器半边要求部署组合了它;DSH Web 0.2.1 默认包含,缺少时开关和卡片不会挂载(Host 工具与提示词仍可用)。
73
83
 
74
84
  确认工具存在:
@@ -88,7 +98,7 @@ dsh --version # 0.2.1 或 0.2.1-rc.2
88
98
  dsh plugin --profile web add @zephinel/dsh-intelligent-ui
89
99
 
90
100
  # 固定当前版本
91
- dsh plugin --profile web add @zephinel/dsh-intelligent-ui@0.2.2-26-10-21
101
+ dsh plugin --profile web add @zephinel/dsh-intelligent-ui@0.4.0
92
102
 
93
103
  # 或从 GitHub 安装
94
104
  dsh plugin --profile web add github:Zephinel/dsh-intelligent-ui
@@ -99,37 +109,32 @@ dsh plugin --profile web add github:Zephinel/dsh-intelligent-ui
99
109
  **DSH Desktop(桌面版)** 不需要终端命令,在应用内安装:
100
110
 
101
111
  1. 侧栏 **插件** → **添加插件**(或箭头 → **安装第三方插件**)。
102
- 2. 输入 `@zephinel/dsh-intelligent-ui@0.2.2-26-10-21`(或只填包名装最新版),点 **安装**。
112
+ 2. 输入 `@zephinel/dsh-intelligent-ui@0.4.0`(或只填包名装最新版),点 **安装**。
103
113
  3. 安装完成后点 **立即启用**;若输入框右侧没有 **UI** 控件,退出并重开 DSH Desktop。
104
114
 
105
115
  桌面版的 profile 由 Electron 应用独占管理,`dsh plugin --profile desktop` 会被拒绝。国内镜像可能晚于 npm 官方源同步刚发布的版本;装不到时把安装源切回 npm 官方源。
106
116
 
107
- 本地开发时从 checkout 安装。扩展**没有独立的开发服务器**——它运行在 DSH 里。开发回路是:构建 → 安装进 profile → 重启 DSH Web → 打开它打印的 URL;输入框右侧出现 **UI** 控件即成功。没有 watch 模式,改完重新 `npm run build`,并按下面的缓存提示重启。
108
-
109
- ```bash
110
- cd /path/to/dsh-intelligent-ui
111
- npm install && npm run build
112
- node scripts/install.mjs # 写入 $DSH_HOME/profiles/web/cordis.patch.yml(自动备份)
113
- ```
114
-
115
- > [!IMPORTANT]
116
- > 改了包名或重建 `lib/client.js` 后,只刷新页面可能拿到旧 revision;先重启承载 Web UI 的 DSH 进程,再打开页面。
117
-
118
- 然后在输入框右侧点 **UI** 控件,选择「仅本会话」或「全部会话」(或 `/iui session` / `/iui global`),直接提问,例如:
117
+ 然后在输入框右侧点 **UI** 控件,选择「仅本会话」(或 `/iui on`),需要时在同一面板里设置本会话的 Auto / Card / Article 样式,直接提问,例如:
119
118
 
120
119
  ```text
121
120
  帮我排一个上海两日游,要能勾选和调整
122
121
  ```
123
122
 
124
- 卸载、开发与排障见[开发与部署](https://github.com/Zephinel/dsh-intelligent-ui/blob/main/docs/development.md)。
123
+ 本地开发(从 checkout 构建并安装)、卸载与排障见[开发与部署](https://github.com/Zephinel/dsh-intelligent-ui/blob/main/docs/development.md);扩展没有独立的开发服务器。
125
124
 
126
- ## 三档开关
125
+ ## 开关与回答样式
127
126
 
128
- ![输入框右侧的 UI 控件:点击后弹出「关闭 / 仅本会话 / 全部会话」菜单(截图为英文界面)](assets/intelligent-ui-toggle.png)
127
+ ![输入框右侧的 UI 控件:Off / This session only / All sessions,以及分隔线下的 Display style](assets/intelligent-ui-toggle.png)
129
128
 
130
- - **关闭**(默认):所有会话的请求里都没有 `render_ui` schema,约 8.5K tokens 的生成提示词展开为空。
131
- - **仅本会话** / **全部会话**:控制当前会话或所有会话(包括之后新开的会话);输入框 **UI** 控件与 `/iui off|session|global` 等价。
132
- - 状态原子写入 `<DSH_HOME>/dsh-intelligent-ui.json`,刷新、DSH 重启后保留;完整语义(投影、跨标签同步、服务依赖)见[架构与行为](https://github.com/Zephinel/dsh-intelligent-ui/blob/main/docs/architecture.md)。
129
+ ![样式面板:内置 Auto / Card / Article 卡片、自定义样式与底部按需生成入口](assets/intelligent-ui-style-panel.webp)
130
+
131
+ - **全局默认**:插件详情页的「在所有会话中启用」与「回答样式」设置新会话默认值;可以选择内置样式或已保存的全局模板。
132
+ - **会话覆盖**:点 Composer 的 **UI** chip →「仅本会话」或「显示样式」进入面板。上方是内置 Auto / Card / Article 预览卡片,中间是「自定义样式」(已保存模板),底部是「按需生成」。「全部会话」表示本会话跟随全局开关,不会打开全局开关;`/iui on|off|inherit` 与 `/iui style auto|card|article|inherit|<cs_id>` 提供命令入口。
133
+ - **Auto** 由模型按请求选择:交互/结构化用紧凑 Card,详尽/深入/长文用 Article。Article 需要 `Toc`、可折叠 `Section` 和实质正文。
134
+ - **按需生成**:选择后面板关闭,焦点回到输入框,出现可取消的提示与示例;示例只填入内容,保留已有草稿,不自动发送。正常发送后,清晰需求直接渲染,有重要歧义时由内置 `ask_user_question` 结构化提问,回答后继续生成。
135
+ - 会话启用/样式设置原子写入 `<DSH_HOME>/dsh-intelligent-ui.json`;按需操作不改这些设置,临时样式也不是当前选中的样式。完整边界见[架构与行为](https://github.com/Zephinel/dsh-intelligent-ui/blob/main/docs/architecture.md)。
136
+
137
+ ![已武装的按需生成提示:示例只填入输入框,不发送](assets/intelligent-ui-on-demand-hint.webp)
133
138
 
134
139
  ## 使用
135
140
 
@@ -139,24 +144,51 @@ node scripts/install.mjs # 写入 $DSH_HOME/profiles/web/cordis.patch.yml(自
139
144
  - 「做一个 7 速自行车的换挡模拟器」
140
145
  - 「把这几张表变成一个可以筛选的销售看板」
141
146
  - 「介绍一下中国历史,要能按朝代展开」
147
+ - 先选「按需生成」,再发送「把这次分析做成紧凑仪表盘,用卡片和图表突出关键指标」
148
+ - 点结果下的「调整样式」,再发送「保留内容,改成留白更多的阅读版式」
142
149
 
143
150
  开启后,**有结构的回答默认用卡片呈现**——包括讲解、介绍、时间线、阶段、对比和可探索内容;文字只用于单个事实、一两句话的答复、你明确要文字/文档/代码,或渲染连续失败。开关没打开时,模型看不到 `render_ui`,会直接用文字回答——这不是故障;打开开关再问即可。
144
151
 
145
152
  如果一定要保证出卡片(或模型仍然回了文字),在开关已打开的会话里用 `/intelligent-ui` 显式调用技能;显式调用会被当作直接指令。也可以说「读取 intelligent-ui skill 然后用 render_ui 做一个…」。
146
153
 
147
- 扩展在 **插件 → 智能 UI 的详情页**里还有一个「自由布局」开关:默认关闭,使用扩展的设计规范;开启后,设计规范只作为建议,模型可以按内容自行选择组件与版式(技术硬规则、主题 token 与可读性不变)。该设置持久化在 DSH 的设置文档里,对所有会话生效。
154
+ ![临时结果:临时样式标记、调整样式与保存为模板](assets/intelligent-ui-temporary-result.webp)
155
+
156
+ ![同一临时结果在固定深色主题下的渲染](assets/intelligent-ui-temporary-result-dark.webp)
157
+
158
+ 临时结果可以立即使用。点「调整样式」会关联这张结果并在保留草稿的前提下填入调整提示,仍需正常发送;点「保存为模板」才填写名称、描述与可用范围(本会话或全局)。保存复用该结果的已校验样式,不再次生成,也不自动选中模板或更改全局默认;不要求先预览、命名或保存。
159
+
160
+ ![插件详情页:全局启用、默认样式、我的样式管理、编排方式与导出](assets/intelligent-ui-settings.webp)
161
+
162
+ 插件详情页按 **可用性**、**回答样式**、**我的样式**、**编排方式** 和 **导出** 分组。「我的样式」管理已保存的全局模板,可设为默认、重命名、编辑描述/展示偏好、导出 JSON 或删除;Composer 管理当前会话可见的全局与会话模板。生成入口在 Composer,设置页提供说明,不设生成工作台。全局值是新会话的默认;输入框 UI 控件里的会话值优先。**自由布局**只影响设计规范的建议强度,与回答样式正交。**导出** 保存图片的默认背景色、1x/2x 分辨率,以及图片/交互页面是否移除包含 `@ToAssistant` 追问的整个区块(默认移除)。
163
+
164
+ 回答渲染完成后,消息底部操作栏的**最右侧**会出现带「导出」字样的**药丸按钮**(只有扩展渲染的回答才有)。点开后可把该轮全部卡片保存为一张 PNG——**原始**(只截取答案本身)、**圆角**(背景色 + 圆角留白)或 **卡片**(留白、圆角与柔和阴影);也可以导出为单文件 HTML,直接在浏览器打开即可继续交互,页面里的 `@ToAssistant` 改为复制消息并提示回到 DSH 粘贴。导出的图片只包含渲染出的卡片,不包含聊天里的 Markdown 文字或导出按钮本身。完整流程见[架构与行为](https://github.com/Zephinel/dsh-intelligent-ui/blob/main/docs/architecture.md)。
148
165
 
149
166
  ## 构建、测试与部署
150
167
 
168
+ 从全新 clone 本地开发时,先安装依赖、构建并写入本地 DSH profile:
169
+
170
+ ```bash
171
+ npm install
172
+ npm run build
173
+ node scripts/install.mjs
174
+ ```
175
+
176
+ 重启承载 Web UI 的 DSH 进程,再打开它打印的 URL;输入框右侧出现 **UI** 控件即成功。扩展没有独立开发服务器,也没有 watch 模式;细节与卸载见[开发与部署](https://github.com/Zephinel/dsh-intelligent-ui/blob/main/docs/development.md)。
177
+
178
+ 日常检查与打包:
179
+
151
180
  ```bash
152
181
  npm run build # 生成 prompt、Host 与 Client bundle
153
182
  npm run check # 构建 + Host/Client/打包测试 + renderer 检查
154
183
  npm run pack:check # 检查 npm pack 的最终文件清单
184
+ npm run test:browser # 先构建;7 个浏览器套件:按需生成、样式面板、主题、图片、交互页面、Article 间距、设置(需要 Chrome)
155
185
  ```
156
186
 
187
+ - 当前 Node 测试 **179** 项;renderer 解析/渲染各 **41/41**,i18n **4** 个程序,排版 **22/22**。浏览器为组件/契约验证;按需生成主链路(清晰需求→临时样式卡片→保存为模板)、缺少内容时的自由输入澄清与真实数据来源约束,均已在隔离 DSH Web 实例中用真实模型验证;其余场景见[验证记录](https://github.com/Zephinel/dsh-intelligent-ui/blob/main/docs/verification.md)。
188
+ - `node scripts/capture-screenshots.mjs` 以固定 DSH token、生产组件与假服务在 Chrome 2x 重建面板、提示、临时结果与设置截图;英文 UI,卡片壳层图标用 lucide 替身。
157
189
  - `npm run check` 里的排版检查(typography)需要本机 Chrome;没有 Chrome 时该检查会跳过,其余测试仍会运行。
158
190
 
159
- 发布物是一个 DSH bundle;部署就是把插件安装进目标 DSH profile。卸载、本地开发与版本注意事项见[开发与部署](https://github.com/Zephinel/dsh-intelligent-ui/blob/main/docs/development.md)。
191
+ 发布物是一个 DSH bundle;部署就是把插件安装进目标 DSH profile。卸载与版本注意事项见[开发与部署](https://github.com/Zephinel/dsh-intelligent-ui/blob/main/docs/development.md)。
160
192
 
161
193
  ## 贡献
162
194
 
@@ -164,6 +196,7 @@ npm run pack:check # 检查 npm pack 的最终文件清单
164
196
  - 提交前运行 `npm run check`;仓库没有 PR CI,以本地命令结果为准。发布由 GitHub Actions 的 Trusted Publishing 工作流执行(推送与 `package.json` 版本一致的 `v*` tag)。
165
197
  - 行为、文案或计数变化时,中英 README、`CHANGELOG.md` 与 `docs/` 对应文档要一起更新;同步规则见 `.agents/skills/sync-iui-docs/SKILL.md`(开发环境使用,不随 npm 包发布)。
166
198
  - 仓库内的维护技能与文档同步规则在 `.agents/skills/`(不随 npm 包发布);AI 协作代理同样以 `npm run check` 作为提交前门槛。
199
+ - 维护者:[@Zephinel](https://github.com/Zephinel)。
167
200
 
168
201
  ## 已知限制
169
202
 
@@ -171,18 +204,43 @@ npm run pack:check # 检查 npm pack 的最终文件清单
171
204
  - 模型偶发生成不合法 OpenUI Lang;Host 校验会返回精确错误,通常同一轮内自修(实测 1–2 次)。
172
205
  - 地图底图依赖 OpenFreeMap 瓦片,路线依赖 OSRM demo,照片依赖 Wikipedia/Wikimedia;离线时地图降级为地点列表、照片降级为占位块。
173
206
  - KaTeX 使用 DSH 壳层已加载的全局样式;若该样式被移除,Math 组件会退化为纯文本。
174
- - 生成提示词约 8.5K tokens,**只在开关命中该会话时发送**(全部会话,或该会话在白名单里);关闭时这部分开销为 0(工具 schema 也不出现)。启用后的请求与旧版一致,DSH 缓存命中可抵消大部分成本。
207
+ - 生成提示词约 9.5K tokens,**只在开关命中该会话时发送**(全局开启,或该会话显式开启);关闭时这部分开销为 0(工具 schema 也不出现)。Article 模式会生成更长的页面,输出 token 与渲染时间相应增加。
175
208
  - 扩展 UI 文案随 DSH 界面语言切换;但 `/iui` 的 Host 返回文案、命令面板里的命令描述与 README 截图仍是英文(前两者是 DSH 平台行为)。
209
+ - 导出图片时,沙盒 iframe(`HtmlView` 里的小游戏)不会被截入图片,图片中该区域会缺失;地图通过保留 WebGL 绘制缓冲入图,禁用 WebGL 的浏览器会按地图自身的降级逻辑显示地点列表。
210
+ - 同一轮回复渲染出的多张卡片会合并成一张图片;导出的是**当前屏幕上渲染出的内容**,因此导出的图片会包含当时的交互状态(勾选项、筛选结果等)。导出会等待卡片内的图片加载和图片搜索完成(最多约 12.5 秒);离线或仍未就绪时按页面上的占位状态导出。
211
+ - 交互页面导出会把渲染器、当前主题与全部卡片内联进一个 HTML(约 3.4–4.9 MB),因此文件较大但无需安装;地图、照片等组件仍依赖网络。页面里的 `@ToAssistant` 会尝试写入剪贴板并弹出提示;剪贴板不可用时提示会保留原消息供手动复制。
176
212
  - 浏览器半边要求部署组合 `dsh-client-locale`(DSH Web 0.2.1 默认包含);最小自定义 profile 缺少它时开关和卡片不挂载,Host 工具与提示词仍可用。
177
- - 插件详情页里的配置依赖 DSH 的 settings 服务:最小自定义 profile 未组合 `dsh-settings` / `dsh-client-ui-settings` 时不出现;Host/Client 版本错位时开关可能显示为不可用。自由布局开关只改变提示词里设计规范的建议强度,不保证每个模型都完全不受默认规范影响。
213
+ - 插件详情页里的配置依赖 DSH 的 settings 服务:最小自定义 profile 未组合 `dsh-settings` / `dsh-client-ui-settings` 时不出现;Host/Client 版本错位时开关可能显示为不可用。全局启用/样式与自由布局只改变提示词与页面形态,不保证每个模型都完全遵守;会话样式覆盖仍以 Host 注入的提示词为准。
214
+ - 交互页面导出需要部署提供 `webServer` 服务(DSH Web 0.2.1 默认包含);最小自定义 profile 缺少它时无法导出交互页面,图片导出不受影响。
215
+
216
+ - 临时样式保存在工具参数/结果快照中,不进入模板库;历史工具参数仍在加载窗口时可重放。事后保存依赖有界结果注册表(最近 200 条),被淘汰的结果可能仍能重放但无法再保存。保存模板与结果快照在 `<DSH_HOME>` 的独立 JSON 文件中持久化。
217
+ - 样式创建/按需生成使用部署的默认主对话模型服务;扩展不提供独立生成模型或 draft 访谈服务。`ask_user_question` 是结构化澄清路径;工具不可用时降级为文字提问,文字轮结束后提示会保留,下一条消息继续同一操作,不需要重新选择「按需生成」(过期、重启或失败后除外)。
218
+ - 按需操作只在内存中:等待发送(armed)10 分钟过期,重启后活动操作无法恢复,需要重新武装;已完成结果不因此丢失。每会话最多一个活动操作:armed 时重新武装会替换,已绑定的 running/clarifying 拒绝重新武装且需先取消;最多两轮澄清。文本结束但未渲染时操作回到待继续状态,下一条消息继续;失败/中断会显示重试/关闭提示。
219
+ - 多标签页采用保守绑定:提示只显示在发起标签页,但 Host 绑定该会话的下一条人工消息,并不验证发送标签来源;请在发起标签页发送,避免另一标签同时发送。
220
+ - 自定义主题只应用到 renderer host,portaled Popover 与沙盒 iframe 保留默认主题;语义状态色保持渲染器定义。导出交互页面冻结导出时的明/暗方案,不随系统切换。
221
+ - 已保存模板的 directives 是有界展示偏好(最多 2,000 字符),不能覆盖系统、工具或安全规则;模板库上限为全局 40 个、每会话 20 个。删除/不可用的已保存模板按默认主题降级;内联临时结果的重放/导出不依赖模板库。
222
+
223
+ ## 常见问题
224
+
225
+ **必须先建模板、预览或命名吗?** 不需要。选「按需生成」后正常聊天,结果可以直接使用;只有主动「保存为模板」才需要名称。临时结果不会替换当前会话选中的样式。
226
+
227
+ **能晚些保存或继续调整吗?** 可以。使用那张结果下的「调整样式」或「保存为模板」;保存的是点选结果的版本,不会自动保存后来生成的版本。注册表已淘汰该结果时会提示快照不可用。
228
+
229
+ **为什么追问后没有继续生成?** 结构化 `ask_user_question` 回答会恢复同一操作;文字提问后,下一条消息会自动继续同一操作。只有过期、重启、失败或中断后才需要重新武装/重试。多个标签同时发送也可能消费同一意图。
230
+
231
+ **为什么回答只有文字、没有卡片?** 先确认该会话的开关已打开(输入框右侧 **UI** 控件,或 `/iui on`);开启后模型仍可能把单个事实、一两句话或明确的文字/代码请求当作有界例外。想强制出卡片时,在开关已打开的会话里用 `/intelligent-ui` 显式调用技能。详见[使用](#使用)。
232
+
233
+ **回答底部为什么没有「导出」按钮?** 只有扩展渲染出的回答才有这个药丸按钮;开关关闭、模型用文字回答或渲染失败时都不会出现。详见[使用](#使用)与[已知限制](#已知限制)。
234
+
235
+ **重建插件后 UI 没变化或报错?** 只刷新页面可能拿到旧 revision:先重启承载 Web UI 的 DSH 进程,再打开页面。具体错误信息与处理方式见[开发与部署](https://github.com/Zephinel/dsh-intelligent-ui/blob/main/docs/development.md)。
178
236
 
179
237
  ## 文档
180
238
 
181
- - [架构与行为](https://github.com/Zephinel/dsh-intelligent-ui/blob/main/docs/architecture.md):Host/Client 组件树、三档开关的完整语义、界面语言、Agent Skill。
182
- - [开发与部署](https://github.com/Zephinel/dsh-intelligent-ui/blob/main/docs/development.md):安装与卸载、开发命令、改名/重建后的重启提示、Host/Client 版本错位、发布物布局。
239
+ - [架构与行为](https://github.com/Zephinel/dsh-intelligent-ui/blob/main/docs/architecture.md):Host/Client 组件树、开关与回答样式的完整语义、界面语言、图片与交互页面导出流程、Agent Skill。
240
+ - [开发与部署](https://github.com/Zephinel/dsh-intelligent-ui/blob/main/docs/development.md):安装与卸载、开发命令、改名/重建后的重启提示、Host/Client 版本错位、发布物布局与插件市场维护。
183
241
  - [验证记录](https://github.com/Zephinel/dsh-intelligent-ui/blob/main/docs/verification.md):端到端验证、测试与打包结果(历史记录)。
184
242
  - [变更日志](https://github.com/Zephinel/dsh-intelligent-ui/blob/main/CHANGELOG.md):按版本记录新增、变更与修复(英文)。
185
243
 
186
244
  ## 许可证
187
245
 
188
- 本项目采用 [MIT](LICENSE) 许可证。基于 Open Intelligent UI(MIT, Copyright (c) 2026 Thesys Inc.)与 OpenUI 生态;浏览器 bundle 内含 lucide-react(ISC)、KaTeX(MIT)、MapLibre GL JS(BSD-3-Clause)、zod(MIT)。完整声明与许可证全文见 `NOTICE` 与 `licenses/`。
246
+ 本项目采用 [MIT](LICENSE) 许可证。基于 Open Intelligent UI(MIT, Copyright (c) 2026 Thesys Inc.)与 OpenUI 生态;浏览器 bundle 内含 lucide-react(ISC)、KaTeX(MIT)、MapLibre GL JS(BSD-3-Clause)、zod(MIT)与 SnapDOM(MIT);交互页面的独立 bundle 还内联 React / React DOM(MIT)。完整声明与许可证全文见 `NOTICE` 与 `licenses/`。
Binary file