@zephinel/dsh-intelligent-ui 0.3.0-26-10-22 → 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/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,7 @@
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.3.0-26-10-22`** (`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.
16
18
 
17
19
  > [!TIP]
18
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.
@@ -53,11 +55,14 @@ On a narrow screen (about 380 px) the card switches to a single column, and maps
53
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 |
54
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 |
55
57
  | Local execution | `$variables`, `@Set` and `@functions` run in the browser; only `@ToAssistant` writes a message back |
56
- | Switch and style | Global defaults on the Plugin detail page; the composer UI control overrides per session; Auto / Card / Article |
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 |
57
62
  | Bilingual UI | Follows DSH's UI language; dictionaries live in `src/shared/locales.ts` |
58
63
  | Agent Skill | Registers `intelligent-ui` with the plugin so the model can load syntax, examples and troubleshooting on demand |
59
- | Plugin detail page | Plugins → Intelligent UI detail page: Availability (global enable), Answer style (Auto / Card / Article), Composition (Free-form layout) and Export (background color, resolution, whether images/pages remove follow-up blocks; on by default) |
60
- | 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 |
61
66
 
62
67
  ## Getting the code
63
68
 
@@ -93,7 +98,7 @@ Install from npm (prerequisites are in the previous section):
93
98
  dsh plugin --profile web add @zephinel/dsh-intelligent-ui
94
99
 
95
100
  # pin the current version
96
- dsh plugin --profile web add @zephinel/dsh-intelligent-ui@0.3.0-26-10-22
101
+ dsh plugin --profile web add @zephinel/dsh-intelligent-ui@0.4.0
97
102
 
98
103
  # or install from GitHub
99
104
  dsh plugin --profile web add github:Zephinel/dsh-intelligent-ui
@@ -104,7 +109,7 @@ Restart the DSH process that serves the Web UI (foreground `dsh web`: Ctrl+C, th
104
109
  **DSH Desktop** needs no terminal command — install it inside the app:
105
110
 
106
111
  1. Open **Plugins** in the sidebar → **Add plugin** (or the arrow → **Install a third-party plugin**).
107
- 2. Enter `@zephinel/dsh-intelligent-ui@0.3.0-26-10-22` (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**.
108
113
  3. When the install finishes, click **Enable now**; if the **UI** control does not appear, quit and reopen DSH Desktop.
109
114
 
110
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.
@@ -119,14 +124,17 @@ See [Development and deployment](https://github.com/Zephinel/dsh-intelligent-ui/
119
124
 
120
125
  ## Switch and answer style
121
126
 
122
- ![The composer UI control: Off / This session only / Follow global, plus Display style below an inset divider](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)
128
+
129
+ ![Style panel: built-in Auto / Card / Article cards, Custom styles and On-demand UI at the bottom](assets/intelligent-ui-style-panel.webp)
123
130
 
124
- ![The This-session style panel: Auto / Card / Article for this session, or follow the global choice](assets/intelligent-ui-style-panel.webp)
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.
125
136
 
126
- - **Global defaults:** the Plugin detail page's **Enable in all sessions** decides whether new sessions start on; the **Display style** control under **Answer style** sets the default Auto / Card / Article.
127
- - **Session overrides:** the composer **UI** control changes only the current session; choosing **This session only** opens the style panel. `/iui on|off|inherit` and `/iui style auto|card|article|inherit` are equivalent.
128
- - **Auto** lets the model choose: compact Card for interactive/structured answers, Article for detailed/in-depth/long-form ones. Article pages need a `Toc`, collapsible `Section`s and substantive prose, not a skeleton.
129
- - Session 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.
137
+ ![Armed on-demand hint: examples fill the composer without sending](assets/intelligent-ui-on-demand-hint.webp)
130
138
 
131
139
  ## Usage
132
140
 
@@ -136,26 +144,48 @@ With the switch on, just ask in natural language, for example:
136
144
  - "Build a gear-shifting simulator for a 7-speed bicycle"
137
145
  - "Turn these tables into a sales dashboard I can filter"
138
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"
139
149
 
140
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.
141
151
 
142
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".
143
153
 
144
- ![Plugin detail page: availability, answer style, composition and export](assets/intelligent-ui-settings.webp)
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.
145
159
 
146
- The Plugin detail page groups its settings into **Availability**, **Answer style**, **Composition** and **Export**. 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).
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).
147
163
 
148
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.
149
165
 
150
166
  ## Build, test and deploy
151
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
+
152
180
  ```bash
153
181
  npm run build # build the prompt, Host and Client bundle
154
182
  npm run check # build + Host/Client/packaging tests + renderer checks
155
183
  npm run pack:check # inspect the final npm pack file list
156
- npm run test:browser # optional: real-browser E2E (style panel + image export + interactive page + Article spacing + custom color picker; Chrome required)
184
+ npm run test:browser # build first; 7 browser suites: on-demand, style panel, theme, image, interactive page, Article spacing, settings (Chrome required)
157
185
  ```
158
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.
159
189
  - The typography check inside `npm run check` needs a local Chrome; without one that check is skipped and the remaining tests still run.
160
190
 
161
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.
@@ -183,8 +213,21 @@ The published artifact is a DSH bundle; deploying means installing the plugin in
183
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.
184
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.
185
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
+
186
223
  ## FAQ
187
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
+
188
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).
189
232
 
190
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).
@@ -194,7 +237,7 @@ The published artifact is a DSH bundle; deploying means installing the plugin in
194
237
  ## Documentation
195
238
 
196
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.
197
- - [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.
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.
198
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).
199
242
  - [Changelog](https://github.com/Zephinel/dsh-intelligent-ui/blob/main/CHANGELOG.md): additions, changes and fixes per release.
200
243
 
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,7 @@
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.3.0-26-10-22`**(`latest`)。
17
+ > **当前状态**:已发布到 GitHub 与 npm,npm 版本 **`@zephinel/dsh-intelligent-ui@0.4.0`**(`latest`)。自定义样式、按需生成以及按需生命周期与内容接地修复均已包含在 0.4.0 中。
16
18
 
17
19
  > [!TIP]
18
20
  > **想先跑起来?** 安装只需一条命令:`dsh plugin --profile web add @zephinel/dsh-intelligent-ui`;重启承载 Web UI 的 DSH 进程后,在输入框右侧的 **UI** 控件里选择「仅本会话」即可开启。完整步骤见[快速开始](#快速开始)。
@@ -53,11 +55,14 @@
53
55
  | 导出图片 | 把该轮渲染结果保存为一张 PNG:原始 / 圆角 / 卡片三种美化;背景色与 1x/2x 在插件详情页设置 |
54
56
  | 导出交互页面 | 把该轮全部卡片导出为单个 HTML 文件,浏览器打开后继续交互;`@ToAssistant` 改为复制文案并提示回 DSH 粘贴 |
55
57
  | 本地执行 | `$变量`、`@Set`、`@functions` 在浏览器运行;只有 `@ToAssistant` 回写消息 |
56
- | 开关与样式 | 全局默认在插件详情页;输入框 UI 控件按会话覆盖;Auto / Card / Article 三档样式 |
58
+ | 开关与样式 | 全局默认在插件详情页;输入框 UI 控件按会话覆盖;内置 Auto / Card / Article 与自定义模板 |
59
+ | 自定义模板与视觉主题 | 保存可复用的展示偏好与明暗配色、字体、圆角、密度、阴影;在「我的样式」中使用、重命名、编辑或删除 |
60
+ | 聊天内按需生成 | 无需模板;在 UI 面板选择「按需生成」,正常发送需求,必要时用内置提问工具澄清 |
61
+ | 临时结果与可选保存 | 结果自带内联样式快照,可直接使用、调整样式或事后保存为模板;不强制预览、命名或保存 |
57
62
  | 双语界面 | 跟随 DSH 的界面语言;字典在 `src/shared/locales.ts` |
58
63
  | Agent Skill | 随插件注册 `intelligent-ui`,模型按需加载完整语法、示例与排障 |
59
- | 插件详情页 | 插件 → 智能 UI 详情页:可用性(全局启用)、回答样式(Auto / Card / Article)、编排方式(自由布局)、导出(背景色、分辨率、图片/页面导出是否移除追问区块,默认移除) |
60
- | 可重放 | 生成程序作为工具参数进入会话日志,随历史重放 |
64
+ | 插件详情页 | 插件 → 智能 UI 详情页:可用性(全局启用)、回答样式(内置或已保存模板)、我的样式管理、编排方式(自由布局)、导出(背景色、分辨率、图片/页面导出是否移除追问区块,默认移除) |
65
+ | 可重放 | 程序与临时样式随工具参数重放;导出页面冻结导出时的主题方案 |
61
66
 
62
67
  ## 获取代码
63
68
 
@@ -68,7 +73,7 @@ git clone https://github.com/Zephinel/dsh-intelligent-ui.git
68
73
  cd dsh-intelligent-ui
69
74
  ```
70
75
 
71
- 也可以直接从 npm 安装,不需要 checkout(见[快速开始](#快速开始))。
76
+ 如果要提交改动,先 Fork 本仓库再克隆自己的副本;只想使用插件时,直接安装 npm 包即可(见[快速开始](#快速开始))。
72
77
 
73
78
  ## 前置条件
74
79
 
@@ -93,7 +98,7 @@ dsh --version # 0.2.1 或 0.2.1-rc.2
93
98
  dsh plugin --profile web add @zephinel/dsh-intelligent-ui
94
99
 
95
100
  # 固定当前版本
96
- dsh plugin --profile web add @zephinel/dsh-intelligent-ui@0.3.0-26-10-22
101
+ dsh plugin --profile web add @zephinel/dsh-intelligent-ui@0.4.0
97
102
 
98
103
  # 或从 GitHub 安装
99
104
  dsh plugin --profile web add github:Zephinel/dsh-intelligent-ui
@@ -104,7 +109,7 @@ dsh plugin --profile web add github:Zephinel/dsh-intelligent-ui
104
109
  **DSH Desktop(桌面版)** 不需要终端命令,在应用内安装:
105
110
 
106
111
  1. 侧栏 **插件** → **添加插件**(或箭头 → **安装第三方插件**)。
107
- 2. 输入 `@zephinel/dsh-intelligent-ui@0.3.0-26-10-22`(或只填包名装最新版),点 **安装**。
112
+ 2. 输入 `@zephinel/dsh-intelligent-ui@0.4.0`(或只填包名装最新版),点 **安装**。
108
113
  3. 安装完成后点 **立即启用**;若输入框右侧没有 **UI** 控件,退出并重开 DSH Desktop。
109
114
 
110
115
  桌面版的 profile 由 Electron 应用独占管理,`dsh plugin --profile desktop` 会被拒绝。国内镜像可能晚于 npm 官方源同步刚发布的版本;装不到时把安装源切回 npm 官方源。
@@ -119,14 +124,17 @@ dsh plugin --profile web add github:Zephinel/dsh-intelligent-ui
119
124
 
120
125
  ## 开关与回答样式
121
126
 
122
- ![输入框右侧的 UI 控件:Off / This session only / Follow global,以及分隔线下的 Display style](assets/intelligent-ui-toggle.png)
127
+ ![输入框右侧的 UI 控件:Off / This session only / All sessions,以及分隔线下的 Display style](assets/intelligent-ui-toggle.png)
128
+
129
+ ![样式面板:内置 Auto / Card / Article 卡片、自定义样式与底部按需生成入口](assets/intelligent-ui-style-panel.webp)
123
130
 
124
- ![选择「仅本会话」后的样式面板:本会话 Auto / Card / Article 与跟随全局](assets/intelligent-ui-style-panel.webp)
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)。
125
136
 
126
- - **全局默认**:插件详情页里的「在所有会话中启用」决定新会话是否默认开启;「回答样式」里的「显示样式」决定默认的 Auto / Card / Article。
127
- - **会话覆盖**:输入框 **UI** 控件只改当前会话,选择「仅本会话」后打开样式面板;`/iui on|off|inherit` 与 `/iui style auto|card|article|inherit` 等价。
128
- - **Auto** 由模型按请求选择:交互/结构化用紧凑 Card,详尽/深入/长文用 Article 阅读页。Article 需要 `Toc`、可折叠 `Section` 和实质正文,不是骨架。
129
- - 会话状态原子写入 `<DSH_HOME>/dsh-intelligent-ui.json`,刷新、DSH 重启后保留;完整语义(投影、服务依赖)见[架构与行为](https://github.com/Zephinel/dsh-intelligent-ui/blob/main/docs/architecture.md)。
137
+ ![已武装的按需生成提示:示例只填入输入框,不发送](assets/intelligent-ui-on-demand-hint.webp)
130
138
 
131
139
  ## 使用
132
140
 
@@ -136,26 +144,48 @@ dsh plugin --profile web add github:Zephinel/dsh-intelligent-ui
136
144
  - 「做一个 7 速自行车的换挡模拟器」
137
145
  - 「把这几张表变成一个可以筛选的销售看板」
138
146
  - 「介绍一下中国历史,要能按朝代展开」
147
+ - 先选「按需生成」,再发送「把这次分析做成紧凑仪表盘,用卡片和图表突出关键指标」
148
+ - 点结果下的「调整样式」,再发送「保留内容,改成留白更多的阅读版式」
139
149
 
140
150
  开启后,**有结构的回答默认用卡片呈现**——包括讲解、介绍、时间线、阶段、对比和可探索内容;文字只用于单个事实、一两句话的答复、你明确要文字/文档/代码,或渲染连续失败。开关没打开时,模型看不到 `render_ui`,会直接用文字回答——这不是故障;打开开关再问即可。
141
151
 
142
152
  如果一定要保证出卡片(或模型仍然回了文字),在开关已打开的会话里用 `/intelligent-ui` 显式调用技能;显式调用会被当作直接指令。也可以说「读取 intelligent-ui skill 然后用 render_ui 做一个…」。
143
153
 
144
- ![插件详情页:可用性、回答样式、编排方式与导出四组设置](assets/intelligent-ui-settings.webp)
154
+ ![临时结果:临时样式标记、调整样式与保存为模板](assets/intelligent-ui-temporary-result.webp)
155
+
156
+ ![同一临时结果在固定深色主题下的渲染](assets/intelligent-ui-temporary-result-dark.webp)
157
+
158
+ 临时结果可以立即使用。点「调整样式」会关联这张结果并在保留草稿的前提下填入调整提示,仍需正常发送;点「保存为模板」才填写名称、描述与可用范围(本会话或全局)。保存复用该结果的已校验样式,不再次生成,也不自动选中模板或更改全局默认;不要求先预览、命名或保存。
145
159
 
146
- 插件详情页按 **可用性**、**回答样式**、**编排方式** 和 **导出** 分组。全局值是新会话的默认;输入框 UI 控件里的会话值优先。**自由布局**只影响设计规范的建议强度,与回答样式正交。**导出** 保存图片的默认背景色、1x/2x 分辨率,以及图片/交互页面是否移除包含 `@ToAssistant` 追问的整个区块(默认移除)。
160
+ ![插件详情页:全局启用、默认样式、我的样式管理、编排方式与导出](assets/intelligent-ui-settings.webp)
161
+
162
+ 插件详情页按 **可用性**、**回答样式**、**我的样式**、**编排方式** 和 **导出** 分组。「我的样式」管理已保存的全局模板,可设为默认、重命名、编辑描述/展示偏好、导出 JSON 或删除;Composer 管理当前会话可见的全局与会话模板。生成入口在 Composer,设置页提供说明,不设生成工作台。全局值是新会话的默认;输入框 UI 控件里的会话值优先。**自由布局**只影响设计规范的建议强度,与回答样式正交。**导出** 保存图片的默认背景色、1x/2x 分辨率,以及图片/交互页面是否移除包含 `@ToAssistant` 追问的整个区块(默认移除)。
147
163
 
148
164
  回答渲染完成后,消息底部操作栏的**最右侧**会出现带「导出」字样的**药丸按钮**(只有扩展渲染的回答才有)。点开后可把该轮全部卡片保存为一张 PNG——**原始**(只截取答案本身)、**圆角**(背景色 + 圆角留白)或 **卡片**(留白、圆角与柔和阴影);也可以导出为单文件 HTML,直接在浏览器打开即可继续交互,页面里的 `@ToAssistant` 改为复制消息并提示回到 DSH 粘贴。导出的图片只包含渲染出的卡片,不包含聊天里的 Markdown 文字或导出按钮本身。完整流程见[架构与行为](https://github.com/Zephinel/dsh-intelligent-ui/blob/main/docs/architecture.md)。
149
165
 
150
166
  ## 构建、测试与部署
151
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
+
152
180
  ```bash
153
181
  npm run build # 生成 prompt、Host 与 Client bundle
154
182
  npm run check # 构建 + Host/Client/打包测试 + renderer 检查
155
183
  npm run pack:check # 检查 npm pack 的最终文件清单
156
- npm run test:browser # 可选:真实浏览器 E2E(样式面板 + 图片导出 + 交互页面 + Article 间距 + 自定义选色器,需要本机 Chrome)
184
+ npm run test:browser # 先构建;7 个浏览器套件:按需生成、样式面板、主题、图片、交互页面、Article 间距、设置(需要 Chrome)
157
185
  ```
158
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 替身。
159
189
  - `npm run check` 里的排版检查(typography)需要本机 Chrome;没有 Chrome 时该检查会跳过,其余测试仍会运行。
160
190
 
161
191
  发布物是一个 DSH bundle;部署就是把插件安装进目标 DSH profile。卸载与版本注意事项见[开发与部署](https://github.com/Zephinel/dsh-intelligent-ui/blob/main/docs/development.md)。
@@ -183,8 +213,21 @@ npm run test:browser # 可选:真实浏览器 E2E(样式面板 + 图片导
183
213
  - 插件详情页里的配置依赖 DSH 的 settings 服务:最小自定义 profile 未组合 `dsh-settings` / `dsh-client-ui-settings` 时不出现;Host/Client 版本错位时开关可能显示为不可用。全局启用/样式与自由布局只改变提示词与页面形态,不保证每个模型都完全遵守;会话样式覆盖仍以 Host 注入的提示词为准。
184
214
  - 交互页面导出需要部署提供 `webServer` 服务(DSH Web 0.2.1 默认包含);最小自定义 profile 缺少它时无法导出交互页面,图片导出不受影响。
185
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
+
186
223
  ## 常见问题
187
224
 
225
+ **必须先建模板、预览或命名吗?** 不需要。选「按需生成」后正常聊天,结果可以直接使用;只有主动「保存为模板」才需要名称。临时结果不会替换当前会话选中的样式。
226
+
227
+ **能晚些保存或继续调整吗?** 可以。使用那张结果下的「调整样式」或「保存为模板」;保存的是点选结果的版本,不会自动保存后来生成的版本。注册表已淘汰该结果时会提示快照不可用。
228
+
229
+ **为什么追问后没有继续生成?** 结构化 `ask_user_question` 回答会恢复同一操作;文字提问后,下一条消息会自动继续同一操作。只有过期、重启、失败或中断后才需要重新武装/重试。多个标签同时发送也可能消费同一意图。
230
+
188
231
  **为什么回答只有文字、没有卡片?** 先确认该会话的开关已打开(输入框右侧 **UI** 控件,或 `/iui on`);开启后模型仍可能把单个事实、一两句话或明确的文字/代码请求当作有界例外。想强制出卡片时,在开关已打开的会话里用 `/intelligent-ui` 显式调用技能。详见[使用](#使用)。
189
232
 
190
233
  **回答底部为什么没有「导出」按钮?** 只有扩展渲染出的回答才有这个药丸按钮;开关关闭、模型用文字回答或渲染失败时都不会出现。详见[使用](#使用)与[已知限制](#已知限制)。
@@ -194,7 +237,7 @@ npm run test:browser # 可选:真实浏览器 E2E(样式面板 + 图片导
194
237
  ## 文档
195
238
 
196
239
  - [架构与行为](https://github.com/Zephinel/dsh-intelligent-ui/blob/main/docs/architecture.md):Host/Client 组件树、开关与回答样式的完整语义、界面语言、图片与交互页面导出流程、Agent Skill。
197
- - [开发与部署](https://github.com/Zephinel/dsh-intelligent-ui/blob/main/docs/development.md):安装与卸载、开发命令、改名/重建后的重启提示、Host/Client 版本错位、发布物布局。
240
+ - [开发与部署](https://github.com/Zephinel/dsh-intelligent-ui/blob/main/docs/development.md):安装与卸载、开发命令、改名/重建后的重启提示、Host/Client 版本错位、发布物布局与插件市场维护。
198
241
  - [验证记录](https://github.com/Zephinel/dsh-intelligent-ui/blob/main/docs/verification.md):端到端验证、测试与打包结果(历史记录)。
199
242
  - [变更日志](https://github.com/Zephinel/dsh-intelligent-ui/blob/main/CHANGELOG.md):按版本记录新增、变更与修复(英文)。
200
243
 
Binary file
Binary file