Skip to content
Back to search

genui

"Render structured interactive UI inline through the dsh-ui fence. Use for key points, emphasis, comparisons, flows, steps, status, data, demos, and interactions whenever structured presentation would be clearer than prose. Preserve conversation language for all user-visible text."

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today

Check it deeper on your machine

Its scripts were only partly scanned.

As a Claude Code plugin, install it and then ask Claude Code:

/plugin marketplace add keithmackay/mackayi/plugin install scanskillsafety@mackayiDo a deep scan of https://github.com/omdsh-dev/dsh-genui with scanskillsafety

Or from a terminal, clone it and run it:

git clone https://github.com/keithmackay/scanskillsafety-skill ~/.claude/skills/scanskillsafetynode ~/.claude/skills/scanskillsafety/cli.cjs --deep 'https://github.com/omdsh-dev/dsh-genui'

It checks the exact commit: every file, its packages against OSV (api.osv.dev), how it compares with this page's scan (findsafeskills.com receives the repository's address), and, if you agree, Claude reading every file with your own Claude subscription. It never runs the code.

Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/omdsh-dev--dsh-genui/badge.svg)](/listings/omdsh-dev--dsh-genui)

HTML

<a href="/listings/omdsh-dev--dsh-genui"><img src="/api/listings/omdsh-dev--dsh-genui/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

1. Prerequisites

Ensure your environment meets the following requirements: - **DSH Version**: `^0.2.0-rc.1 || ^0.2.1-rc.1 || ^0.2.2-alpha.2`. Packed browser acceptance covers `0.2.0-rc.1`, `0.2.1-rc.3` and the exact npm hosts `0.2.2-rc.1` (current `latest` / `next`) and `0.2.2-alpha.2`; `0.2.1-rc.4` and `0.2.1-rc.5` retain separate public-API, full-unit-suite and build checks. The current RC and alpha hosts require **Node.js >=24.9.0**. Its gallery, computed-field and Map acceptance uses official local replay; third-party sidebar integration is checked on rc.3. - **pnpm on PATH**: The `dsh plugin` CLI requires pnpm. If missing: run `corepack enable` or `npm i -g pnpm`, then **open a new terminal** and confirm `pnpm -v` prints a version number.

2. Install & Activate

Run a single command in your terminal (all dependencies are fetched automatically):

# Public npm package (works without an npm account)
dsh plugin --profile web add @changfenhuang/dsh-genui

> [!TIP] > **Adding only as a Node package?** Run `npm install @changfenhuang/dsh-genui`. Note that `npm install` only adds the dependency and does not register the plugin with DSH; use the `dsh plugin add` command above for DSH integration.

3. Verify in 60 Seconds

1. Restart the DSH web service and **hard refresh** your browser (`Cmd + Shift + R` or `Ctrl + F5`). 2. In a **new conversation session**, send:

   Use dsh-ui to draw a stats dashboard with a sortable service table.

3. **Expected result**: The reply renders an in-place interactive dashboard rather than a plain code block. 4. **Console activation check**: Open your browser Developer Tools Console and look for `[genui] client active; fence-channel=dom`.

---

> [!WARNING] > ### ⚠️ Installation Pitfalls to Avoid > > 1. **Watch the Package Scope (Crucial)**: > The package must be **`@changfenhuang/dsh-genui`**. npm hosts an unrelated, unscoped package named `dsh-genui` (a Vue/OpenTiny implementation by another maintainer); installing it will fail due to incompatible host peer dependencies. > 2. **Do Not Use `link:` on a Freshly Cloned Directory**: > `link:` alone does not bundle or resolve peer assets (mermaid, three.js, React). Use npm for standard usage; reserve `link:` strictly for local development (see [Developer Guide](#-developer-guide)). > 3. **Migrating from Legacy `@omdsh-dev`**: > If you installed from GitHub or the old org name before v0.9.2, clean up the stale key: > ```sh > dsh plugin --profile web remove @omdsh-dev/dsh-genui > dsh plugin --profile web add @changfenhuang/dsh-genui > ```

---

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

SKILL.md · Manifest · 429 lines
  1. ---
  2. name: genui
  3. description: "Render structured interactive UI inline through the dsh-ui fence. Use for key points, emphasis, comparisons, flows, steps, status, data, demos, and interactions whenever structured presentation would be clearer than prose. Preserve conversation language for all user-visible text."
  4. ---
  5. # GenUI — 生成式 UI 输出规范
  6. 本文的 MUST(必须)、MUST NOT(禁止)、SHOULD(推荐、存在合理理由时可取舍)、SHOULD NOT(通常不推荐)和 MAY(可选)按 RFC 2119 解释。组件字段、合法 JSON 和用户明确的语言与呈现要求属于 MUST;是否用 UI 及选择哪个合适组件通常属于 SHOULD;card 容器属于 MAY。
  7. **Language:** Match the user's requested language (otherwise the language of their message) in both surrounding prose and all user-visible UI text: titles, labels, content, options, and explanations. Chinese examples below illustrate the schema only; do not switch the conversation to Chinese after loading this skill. Keep JSON keys, component types, IDs, and actions unchanged. An English request gets English prose and UI text; a Chinese request gets Chinese prose and UI text. `<user-language ...>` tokens are meta-placeholders only. Replace every one with actual content in the conversation language; never emit these placeholders literally.
  8. 你可以**在回答正文中间**输出可交互 UI 组件:写一个 `dsh-ui` 围栏(fenced block with language tag `dsh-ui`),内含 JSON 规格,渲染器会把这一整块画成真实组件,文字照常穿插在前后。组件**就是回答的一部分**,不是工具调用。
  9. ```dsh-ui
  10. {"title":"<user-language text>","gap":14,"items":[...]}
  11. ```
  12. ## 围栏书写铁律(先读这一节)
  13. 围栏开头那一行的语言标记**统一写 `dsh-ui`**,不要添加标点、引号或注释。渲染器会容错大小写、首尾空格和部分尾部标点;其他语言标记不会作为 GenUI 接管,用户会看到普通代码块。
  14. | 写法 | 结果 |
  15. | --- | --- |
  16. | ` ```dsh-ui ` | ✅ 渲染 |
  17. | ` ```dsh-ui> ` | ✅ 容错渲染;生成时仍应去掉 `>` |
  18. | ` ```dsh-ui ` 带行尾空格 | ✅ 渲染(自动 trim) |
  19. | ` ``` DSH-UI ` | ✅ 渲染(忽略大小写) |
  20. | ` ```dshui ` / ` ```ds-ui ` | ❌ 不是合法标记 |
  21. 此前同一模型曾在同一会话里写出 **182** 个 ` ```dsh-ui> ` 围栏并导致静默失效;现在已对这类尾部标点统一容错。写围栏时**只写 `dsh-ui` 这六个字符**,不要加任何标点、引号、注释;收尾必须是单独一行的 ` ``` `。
  22. 围栏位置:只写在**回答正文**里。写进 reasoning / 思考块不会渲染,用户看不到。
  23. SVG 可通过 `dsh-ui` 中的 `svg` 组件展示,也可以直接输出 `svg` 代码围栏,显示「预览/源码」切换。
  24. ### Panel
  25. 在围栏 JSON 顶层设置 `"panel":true`,内容会在当前会话的 Panel 中显示并原位更新。设置 `"append":true` 可以追加并合并内容;Panel 最多容纳 200 个节点或接受 200 次追加,达到上限时发送替换内容重新建立 Panel。收到来自 Panel 的 `[genui-action]` 后,回复一个 `panel:true` 围栏,并可附带至多一行、10 字以内的确认文字。
  26. 公式:`$...$` / `\(...\)` 为行内公式,`$$...$$` / `\[...\]` 为独立公式;支持矩阵、分段函数、多行对齐推导,以及加粗/高亮内的公式。正文、列表、键值、表头/单元格、卡片/步骤/时间线/标签页标题、题目与说明、按钮与表单标签、指标、媒体说明和图表外层标题共用此能力。JSON 字符串中的反斜杠必须双写,如 `"content": "\\(\\frac{a}{b}\\)"`。代码源码、输入值/占位符、原生下拉选项和图表引擎内部绘图文本仍遵循各自的原生格式,不解析富文本。数学语法以 KaTeX 为准,不执行 HTML、外部资源或脚本;不支持 LaTeX 文档编译、加载任意宏包。
  27. ## 组件词汇(只允许这些 type)
  28. 布局:`text` `row` `col` `grid` `card` `carousel` `divider` `spacer` `arrow` `hero`
  29. 展示:`stat` `badge` `progress` `list` `table` `keyvalue` `avatar` `image` `image-group` `compare` `audio` `video` `timeline` `file-tree` `breadcrumb` `diff` `json` `code` `callout` `steps` `icon` `blocks`
  30. 图表:`chart`(bars/line/donut,可多序列)`plot`(数学函数图)`echart`(ECharts 全功能图表)`map`
  31. 交互:`button` `input` `select` `checkbox` `radio` `switch` `slider` `textarea` `editor` `date-picker` `segmented-control` `tabs` `accordion` `copy` `link` `submit` `popover` `choices`
  32. 高级:`svg` `mermaid` `diagram` `scene3d` `quiz` `entity-card`
  33. ### 布局
  34. - text: `{"type":"text","size":"display|h1|h2|h3|body|muted|caption","content":"...","align":"left|center|right"?}`(`tone:"danger|success|warning|info|muted"` 给整行文字上语义色,不用套 badge;`mono:true` 走等宽字体,用于十六进制/二进制/标识符,不带行内代码底色)(`size:"display"` 比标题大一档,作引言/开篇点题句,**一条回答 ≤1**;`center:true` 是旧写法,等价 `align:"center"`,新写一律用 `align`)
  35. - row / col: `{"type":"row"|"col","items":[...],"wrap":true?,"spacer":true?,"gap":n?}`;`row.justify:"center"` 主轴居中(图标+标题那种图头);`col.width:n`(1-100)给这一列占行宽的百分比,不写就按内容宽
  36. - grid: `{"type":"grid","cols":n,"items":[...]}`;`columns` 可作为 `cols` 的别名,校验会提示使用规范字段。
  37. - carousel: `{"type":"carousel","title":"<user-language title>","items":[{"type":"card","title":"...","items":[...]}],"itemWidth":240?,"gap":3?}` — 原生节点横向滚动;最多 24 项,宽度 80–640px 且不超过轨道宽度的 85%;默认宽度 240px。`gap` 数值乘以 4px,省略时为 12px,负数按 0 处理。导航按钮每次滚动轨道宽度的 85%,仅在内容溢出时显示,触摸设备直接滑动轨道。不自动播放。轨道聚焦时支持左右键 / Home / End,卡片内表单按原提交规则工作。浏览与滑动不发 action;子组件自身声明的 action 按既有交互规则触发。流式输出只在尾部追加卡片以保留已有输入路径。
  38. - hero: `{"type":"hero","title":"<user-language title>","subtitle":"<user-language text>","value":"99.96%","label":"<user-language metric>","delta":"+0.02%","spark":[...],"tone":"accent|success|warning|danger"}` — **封面块**:eyebrow + 超大数字(52px,带入场计数)+ 标题 + 副标题 + tone 渐变底色。**一条回答最多用一个**,放在最前面当视觉锚点
  39. - span: 任意节点都可加 `"span":2`(grid 子节点占几列)——bento 排版的唯一原语:一张 `span:2` 宽卡配一张窄卡,比一列方块堆下去好看得多
  40. - card: `{"type":"card","title":"...","items":[...]}`;`"tone":"info|success|warning|danger"` 给卡片语义底色(用于结论卡/风险卡);`"accent":"#f59e0b"` 指定强调色(边框 + 标题 + 极淡底色);`"flat":true` 去掉阴影、换成极淡中性底——**图里的面板必须用 flat**,否则每层都像浮起的卡片,叠两层就脏了;`"eyebrow":"<user-language 小引题>"` 在标题上方加一行 meta 小字(把多张卡分章时用——**连续同章的卡片不要每张都加**,一段回答 ≤3 个)
  41. - palette: `chart` / `echart` 都支持 `"palette":["#ff8800","#3ecf8e"]` 覆盖分类色板(默认跟随宿主主题)。**只有语义上需要指定颜色时才写**(成本=红、收益=绿),否则跟随主题更稳
  42. - divider: `{"type":"divider"}`;**带章节名** `{"type":"divider","label":"<user-language 章节名>"}`(线 + 小标签居中,作章节切换:报告从摘要切入数据、图表册开新章时用一段;卡片/列表内部、连续同主题内容之间**不要用**,一条回答 ≤3 个); spacer: `{"type":"spacer"}`
  43. ### 展示
  44. - stat: `{"type":"stat","label":"...","value":"...","delta":"+12.4%|-3%"}`(`-` 开头自动红、`+` 绿);可选 `"spark":[3,5,4,8,6]` 画一条微趋势线(2–60 个有限数值);`"size":"hero"` 渲染超大数字(一条回答最多用一次,作为视觉锚点)
  45. - badge: `{"type":"badge","label":"...","tone":"success|warn|danger|accent","icon":"emoji?"}`
  46. - progress: `{"type":"progress","label":"...","value":0-100,"valueLabel":"70%"}`;`"variant":"ring"` 画环形进度,`"target":70` 在轨道上标出目标刻度
  47. - avatar: `{"type":"avatar","name":"...","color":"#hex?"}`
  48. - image: `{"type":"image","src":"/mmx-files/result.png","alt":"<user-language description>"}` — 展示浏览器可访问的 http(s) 或同源相对图片地址;懒加载;围栏里不接受 `file:`/`data:` 等本地或主动协议(导出时内嵌的 data: 图片由导出器生成,不是这层输入);`"caption":"<user-language 图注>"` 在图**下方**加说明行(来源/解读/署名;`alt` 是图**上方**的标签行,两者分工不同);图片可点击,原地打开原生对话框查看原图(Esc / 关闭返回并恢复焦点)
  49. - image-group: `{"type":"image-group","title":"<user-language title>","items":[{"src":"/mmx-files/a.png","alt":"<description>","caption":"<caption>"},{"src":"/mmx-files/b.png","alt":"<description>"}]}` — 最多 24 张图片按长宽比自适应换行;点击原生 lightbox 放大,左右键 / Home / End 切图,Esc / 关闭按钮返回并恢复焦点。沿用 image 的 http(s) / 相对地址限制;不接受 file/data/javascript。只做本地浏览,不发 action;需要模型动作请在旁边放独立 button。追加 / 重排保留当前 src;当前图片移除后关闭查看器;相同 src 按出现次序区分。空列表与图片加载失败都有明确状态。导出 HTML 会把导出时能读到的同源图片内嵌成 data: URL(跨域或读取失败时保留原地址),离线打开也能看到图。[完整用法与验收](docs/gallery.md)。
  50. - compare: `{"type":"compare","title":"<user-language title>","before":{"src":"/shot-before.png","label":"<user-language label>","caption":"<caption>"},"after":{"src":"/shot-after.png","label":"<user-language label>"},"mode":"side|stack|slider","height":260}` — **两张图成对呈现**:改动前后、方案 A/B、原图与重绘。`before`/`after` 都必填,缺一侧整节点丢弃(不是降级成单图)。`mode`:`side`(默认,容器够宽时并排,窄于 560px 自动竖排)、`stack`(始终竖排,适合长截图)、`slider`(单框中间一条可拖动分割线,指针拖动 / 触摸 / 方向键 / Home / End 都能用)。`height` 是框高上限 120–640(默认 260),图片按 contain 装进框内、不裁切。标签 `label` 常显,不靠悬停;点击图片原地开原生对话框放大,Esc / 关闭返回并恢复焦点。图片地址沿用 image 的 http(s) / 相对地址限制;只做本地浏览不发 action。**汇报改动(修了什么、前后差异)时默认用它**,而不是表格或纯文字清单——读者要的是「变成什么样了」,不是字段名。只在两张图必须被对照阅读时才用;同一批无关截图用 image-group。
  51. **本机截图怎么进回答**:`image` / `image-group` / `compare` 的 `src` 只接受浏览器能拿到的地址。本机文件走宿主已有的鉴权文件路由,直接写 URL,不用搬文件、不用配目录:
  52. `/api/file?path=<绝对路径,percent-encoded>`(例:`/api/file?path=%2FUsers%2Fme%2Fproj%2F.a.png`)。宿主用同一个路由渲染 Markdown 里的本地图片,支持 png/jpeg/webp/gif/svg,带大小上限与沙箱策略。典型用法:同一处改动前后各截一张,用 `compare` 摆出来,而不是用文字描述"改了什么"。
  53. - audio: `{"type":"audio","src":"/mmx-files/result.mp3","alt":"<user-language description>","loop":true?}` — 原生控制条;用户主动播放,不自动播放;仅 http(s) 或同源相对地址
  54. - video: `{"type":"video","src":"/mmx-files/result.mp4","alt":"<user-language description>","poster":"/mmx-files/poster.jpg"?,"loop":true?,"muted":true?,"aspectRatio":"16:9|4:3|1:1|9:16"?}` — 原生播放/音量/全屏控制;不自动播放
  55. - list: `{"type":"list","items":["..."] 或 [{"title":"...","desc":"..."}] 或嵌套节点(如 {"type":"badge","label":"TS"})}` — 行内可嵌节点(计入节点预算);记录中的 `label`/`name` 归一化为 `title`,`description`/`content`/`text`/`body`/`detail` 归一化为 `desc`;只有正文时将正文用作标题,未知字段会收到警告
  56. - table: `{"type":"table","columns":["..."],"rows":[["...","..."]],"types":["text|num|delta|bar|badge"]?,"details":[[...]]?,"total":true?}` — 表头点击本地排序(升/降/还原,零往返);数值感知:千分位(`1,234`)、`k/m/b`、`万/亿`、`%`、货币符号都能按真实数值比较,纯数值列自动右对齐;**带符号单元格自动着色**(`+12.4%` 绿、`-3` 红,无需额外字段);`types` 可按列指定 `bar`(0-100 内联进度条)、`ring`(0-100 小环)、`spark`(单元格写 `"3,5,4,8"` 画微趋势线)、`badge`(胶囊标签)、`delta`(强制涨跌色)、`num`(强制右对齐)、`index`(行号)、`group`(首列当分组标题:该行只有第一格有内容时渲染成跨列小标题);`"total":true` 追加合计行(数值列自动求和);**`"export":true`**:表格上方出现「复制 Markdown / 复制 CSV」两个小按钮(纯本地剪贴板,不发请求);**`"filter":"输入框id"`**:把表格和某个 input/select 绑定,读者输入即时过滤(`filterColumn` 可限定列)——数据多时**默认就该配一个**;**`"sortField":"下拉id"`** 用下拉的值(列名)排序;**`"details"` 与 rows 同序**,第 i 项是该行展开后的内容(可放任意组件,`null` = 该行不可展开)——首列出现 chevron,点开在整行下方展开明细,适合「主表 + 明细」;**`"wrap":true`** 开启长文本排版:单元格、长标识符和行内代码自动折行,保留显式换行;列有可读宽度下限,窄容器仍可横向滚动,嵌套表格独立选择模式(默认关闭,数据表保持单行紧凑;当某列是整句描述时开启)
  57. - keyvalue: `{"type":"keyvalue","pairs":[{"key":"...","value":"..."}]}`
  58. - timeline: `{"type":"timeline","items":[{"title":"...","desc":"...","time":"..."}]}`
  59. - file-tree: `{"type":"file-tree","items":[{"name":"...","type":"file|dir","children":[...]?}]}` — 目录行可点击折叠/展开(本地,零往返)
  60. - breadcrumb: `{"type":"breadcrumb","items":["<user-language text>","<user-language text>","<user-language text>"]}`
  61. - diff: `{"type":"diff","diffs":[{"path":"...","oldText":"..."|null,"newText":"..."}]}`
  62. - json: `{"type":"json","value":...}`(JSON 树查看器)
  63. - code: `{"type":"code","lang":"ts","code":"..."}`
  64. - callout: `{"type":"callout","tone":"info|success|warning|error","title":"...","content":"..."}` — 用于单条强调、提醒或风险摘要;`content` 是文本字符串,可用 JSON `"\n"` 分行。多条独立事项用 `list` 的 `{title,desc}` 保留逐项层次
  65. - steps: `{"type":"steps","current":n,"steps":[{"title":"...","desc":"..."}]}`
  66. - arrow: `{"type":"arrow","dir":"down|right","length":16-96,"label":"..."}` — 图里两个块之间的**细线连接件**(1.4px 线宽 + V 形箭头,固定长度)。上下流程图一律用它,**不要用文字「↓」**:字符箭头跟着文字基线走,撑不开间距
  67. - icon: `{"type":"icon","name":"Nodes","tone":"info|success|warning|danger|muted|default","size":16|20|24|32,"tile":true,"label":"<user-language 无障碍名>"}` — 内置图标集(749 个可忠实渲染;64 个内联秒开,其余首次使用时载入,完整名单见 ICON-NAMES.md)。`tile:true` 画成**淡色圆角方底**,用于阶段卡/语义标记;不带 `tile` 是跟随文字色的行内图标。`label` 可省略(纯装饰),成对出现时只给一个加 label
  68. - blocks: `{"type":"blocks","title":"...","rows":[{"label":"初始","cells":["0","1","2"],"color":"#64748b"}],"columns":n?,"caption":"..."}` — **色块图解**:按行分组的格子。三种形态同一个结构:① 阶梯图(每行格子数不同,各行自己等分宽度,如 8→4→2→1)② 等分块(一行 4 块)③ 泳道图(`columns` 固定列数,`cells` 里写 `"—"` 或留空)。`color` 省略时用强调色淡底;文字颜色按亮度自动反转(深底白字/浅底黑字)。**有「分成几份、逐轮推进、分组对照」的结构就用它,不要手写 svg 坐标。** `caption` 必写:一句话说明每格代表什么
  69. - 行级 `"variant":"outline"`:细边框不填充,用于**矩阵**(每格都是一个框);`"variant":"plain"`:连框都不画,用于**位串**(`1 0 1 0 0 0 0 0` 读起来是数字不是表格)——只有带 `tone`/`color` 的格子会画出底色
  70. - 格子可以写成对象:`{"text":"1","tone":"danger","sub":"SF"}` —— `tone`(accent/success/warning/danger/muted)给**单个格子**上语义色,`sub` 在格子下方挂一行小字(位名、序号、角色)。`color` 可显式指定十六进制,优先于 tone
  71. - 例:`{"columns":8,"rows":[{"variant":"outline","cells":[{"text":"1","tone":"danger","sub":"SF"},"0","1","1","0","0","1","0","0"]}],"caption":"最高位为 1,所以 SF=1。"}`
  72. 内置图标名:以下 **64 个内联在包里、立即渲染**,优先从这里面选:
  73. Check CheckCircle Info InfoCircle Warning Error X Plus Minus Circle ArrowDown ArrowUp ArrowRight ArrowLeft ArrowCurvedRight Function Functions Operator Atom Nodes Connect Share Branch Grid GridAlt Stack Cube Storage Chart Trending Pulse Speed Timer Clock TableFilled Code SquareCode Terminal File FileCode Folder Link Paperclip Lightbulb Book BookOpen GraduationCap Flask Lab Brain Robot Sparkles ShieldCheck Lock Globe WebsiteNetwork Search MagnifyingGlassSearch PluginPuzzle Settings Bolt Compass
  74. 其余 **685 个按需载入**(首次用到时拉取约 1 MB,此后本页全部可用)。完整名单在本 SKILL 同目录的 `ICON-NAMES.md`——需要猜名字时读它或 grep 它,不要在对话里穷举。
  75. ### 图表
  76. - chart: `{"type":"chart","kind":"bars|line|donut","data":[{"label":"...","value":n,"color":"#hex?"}],"series":[{"label":"...","data":[...]}]?,"horizontal":true?}` — bars 默认;line 趋势;donut 占比;**series:bars 是分组柱,line 是多序列折线;每个 `series[].data` 使用 `[{"label":"Q1","value":30},{"label":"Q2","value":45}]` 这样的对象数组,不是 `[30,45]` 这样的纯数字数组**;**`horizontal:true` 画横向柱**(排行/长标签首选);**`stacked:true` 把 series 堆叠**(构成/占比随时间);堆叠段够高时数值直接印在段内,鼠标悬停任意柱/段/点/扇区都会弹出即时 tooltip(堆叠显示该段数值 + 合计)。v3 渲染:宽度自适应、Y 轴 1/2/5 刻度、单序列负值在零线以下真实绘制、line 带面积渐变与抽稀 X 标签、donut 图例显示数值与百分比。**≤8 个点的快速对比用 chart;多序列、需要缩放/交互或数据量大时用 echart**
  77. - plot: `{"type":"plot","series":[{"expr":"a*sin(b*x)","label":"...","color":"#hex?","params":[{"name":"a","value":1,"min":0,"max":5,"animateTo":3,"durationMs":4000,"loop":true},{"name":"b","value":1,"min":0.5,"max":5}]}],"xMin":-6.28,"xMax":6.28,"title":"..."}` — SVG 函数图;**series 可带 `"kind":"line|area|scatter"`**(缺省 line;area 填色到基线;scatter 散点);**params 渲染成实时滑块**(拖动即时重绘,**y 轴锁定**=只变曲线不变数轴);**animateTo 参数会显示播放按钮**(自动动画演示);SVG 可拖拽平移、滚轮缩放;表达式支持 sin/cos/tan/asin/acos/atan/sqrt/cbrt/exp/log/ln/abs/floor/ceil/round/min/max/pow,常量 pi/e/tau,变量 x(其他字母=参数)
  78. - echart: `{"type":"echart","title":"...","height":300,"preset":"bar|line|area|pie|scatter","data":[{"label":"...","value":n}],"series":[...]?}` — **ECharts 全功能图表**,视觉效果远超 `chart`(渐变、tooltip、动画、图例交互);**preset 模式**:用和 `chart` 一样的 `data`/`series` 格式,自动构建主题化的 ECharts 配置(颜色跟随宿主主题);**preset 一览**(只写 preset + data/series/links,主题自动跟随):
  79. `bar` · `line` · `area` · `pie` · `scatter` · **`radar`**(每 series 一个多边形,指标取第一条 series 的 label)· **`gauge`**(每个 datum 一个仪表,适合单 KPI)· **`funnel`**(漏斗/转化)· **`treemap`**(体积/层级占比)· **`sankey`**(流向,用 `links:[{from,to,value}]`)· **`graph`**(关系图,`links` 驱动,节点大小随连接数)· **`heatmap`**(`series` 当行、第一条 series 的 label 当列)· **`bigline`**(长序列 + 内置缩放)· **`wordCloud`**(词云,`data:[{label,value}]` 的 value 表示权重;颜色跟随 `palette` 或主题调色板)
  80. **full option 模式**:传 `"option":{...}` 直接写 ECharts 原生配置(支持 ECharts 内置图表及已注册的 `wordCloud` 词云扩展;其他第三方扩展不保证可用),option 中的函数会被过滤(只接受数据)。选择原则:**chart 轻量(无额外下载)适合 ≤8 点的快速对比;echart 视觉更丰富(渐变、tooltip、图例交互、dataZoom),但会按需下载约 1MB 引擎,多序列/大屏/交互场景优先**
  81. ### 交互
  82. **本地优先(v2.6)**:UI 自己能做的状态变化——判卷、判题、重置、展开、选中——一律本地即时完成,**零模型往返**。action 只用于必须模型参与的事(生成新内容、执行工具、下一步建议)。**交互组件必须带 action:不带 action 的按钮渲染为禁用态,用户点不了;带 action 的按钮点击后有「已触发」本地反馈。**
  83. - button: `{"type":"button","label":"...","tone":"primary|danger|success|ghost","full":true?,"small":true?,"icon":"emoji?","action":"refresh"?}`
  84. - **秘密禁令**:不得索取或生成密码、API Key、访问令牌、恢复码等秘密输入;遇到此类需求直接拒绝并解释
  85. - input: `{"type":"input","label":"...","placeholder":"...","inputType":"text|email|color|number","value":"...","action":"name"?,"id":"field-id"?}` — `color` 使用浏览器原生取色器,值使用 `#RRGGBB`;`number` 可作为 Computed 数值输入;action 在失焦**和回车**时触发(回车带 `submit:true`);**blur 仅值有变化才发送**(聚焦又离开不产生空往返);payload 带 `id` 帮模型定位字段;带 `id` 的值刷新后保留、并被 submit 收集进 `fields`
  86. - select: `{"type":"select","label":"...","options":["...","..."],"selected":下标?,"action":"pick"?,"id":"field-id"?}` — `selected` 预选某选项(缺省显示「请选择…」占位,不静默预选第一项);带 `id` 的选择跨刷新保留并进 submit 的 `fields`
  87. - date-picker: `{"type":"date-picker","label":"...","mode":"single|range","value":"YYYY-MM-DD 或 YYYY-MM-DD/YYYY-MM-DD","min":"YYYY-MM-DD","max":"YYYY-MM-DD","id":"field-id"}` — 使用浏览器原生日期控件;日期必须是真实日历日期,范围模式的值是开始和结束日期组成的 ISO 区间;范围输入完整且有效后,带 `id` 的值进入共享状态与 submit 的 `fields`
  88. - segmented-control: `{"type":"segmented-control","label":"...","options":["...","..."],"value":"...","id":"field-id","action":"pick"}` — 胶囊式单选控件;带 `id` 时选中值进入共享状态,可用于 `when` 更新同级组件,也会进入 submit 的 `fields`;`action` 可选,设置后每次选择都会发送该 action
  89. - checkbox: `{"type":"checkbox","label":"<user-language option>","checked":true?,"action":"toggle"?,"group":"group-id"?}` — 默认保持逐次 `action` 行为;**加 `group` 进入多选聚合模式**:同组 checkbox 可反复勾选/取消,变化只在本地记录、不发逐次 action,兄弟 `submit` 一次性把该组已选 label 作为字符串数组放进 `answers`(例如 `{"styles":["<user-language option>","<user-language option>"]}`)
  90. - slider: `{"type":"slider","label":"...","min":0,"max":100,"step":1,"value":n?,"action":"name"?,"id":"field-id"?}` — 数值表单滑块:实时显示数值;带 `id` 跨刷新保留并进 submit 的 `fields`(拖拽经防抖合并成一次 action)
  91. - radio(**legacy,仅用于兼容老围栏**:试卷与决策都改用 `choices`。`choices` 的 `group` + `answer` + `explanation` + 兄弟 `submit` 已覆盖本地判分,且每个选项还能带代价与证据。新回答不要再用 radio): `{"type":"radio","label":"<user-language label>","options":["<user-language option>","<user-language option>"],"selected":n?,"action":"pick"?}` — 单选;**加 `"group":"group-id"` 进入聚合模式**:选择只本地记录、不发往返;可设置 `"answer":正确下标或标签` 和 `"explanation":"<user-language explanation>"`,在纯 radio 且没有其他待发送表单状态时本地判卷
  92. - choices: `{"type":"choices","title":"<user-language title>","prompt":"<user-language question>","mode":"single|multi","max":2,"submit":"<button label>","action":"<action>","items":[{"label":"<option>","hint":"<one-line cost>","meta":"P0","recommended":true},{"label":"<option>","hint":"...","disabled":true,"reason":"<why unavailable>"}]}` — **要读者做决定的列表**,不是读的列表:每个选项自带一行代价(`hint`)、可选证据(`meta`,右对齐等宽)、`recommended` 推荐标记、`disabled` + `reason`(保留在列表里而不是删掉,读者要看得到为什么不行)。`mode` 默认单选;`multi` 配 `max` 控制上限。选中的行左侧有强调条 + 淡底,提交后显示「已发送 · 仍可修改」并且**允许继续改**(改了就清掉已发送状态)。**需要模型接收选择并推进对话时,必须同时提供 `submit` 和非空 `action`**,点击提交后回传 `{question, selected, mode}`。缺少 `action` 时选择仅保存在当前界面,无法推进对话,界面会提前提示;试卷题目可通过 `group` 和同一 fence 中的 `submit` 收集答案。最多 8 项——超过 8 项说明这是一张表,不是一次选择。
  93. - link: `{"type":"link","label":"...","href":"https://..."?}` — 仅 http(s)/mailto 协议被接受;无 `href` 时渲染为纯文本样式(不会假装可点)
  94. - when(**任何节点都能带的条件显隐**): `{"field":"<id 或 group>","op":"eq|neq|in|not-in|gt|gte|lt|lte|empty|not-empty|checked","value":...}` — 条件读的是**当前 block 自己的状态**:`input/select/slider/textarea/editor/date-picker/segmented-control/map/diagram` 按 `id`,`radio/checkbox/choices` 按 `group`。满足才渲染,不满足整棵子树都不出现;状态变化即时生效,不需要模型往返。字段显隐条件不能互相形成循环引用。
  95. - **典型用法**:选了「公司主体」才出现「税号」;金额 > 1000 才出现「分期」;选了「自定义」才展开参数(`eq`);多选里含「其他」才出现补充输入(`in`)。
  96. - **两条硬规则**:① 隐藏节点不渲染,读者看不到就绝不会提交它的旧值(`submit` 的 `fields`/`answers` 会剔除隐藏键);② 隐藏字段不算「未填」,不会把提交按钮卡成不可用。
  97. - 缺省行为:没有 block 状态时(导出 HTML、面板无 provider)条件无法求值,节点**保持可见**——宁可多显示,也不静默删掉导出文档的一整个分支。
  98. - `in`/`not-in` 的 `value` 必须是数组;`gt`/`gte`/`lt`/`lte` 两边都按数字比较,非法数字视为不满足。
  99. - submit: `{"type":"submit","label":"<user-language action>","action":"grade","groups":["q1","styles"],"resetAction":"redo"?}` — 聚合按钮:`groups` 引用当前 block 中的 submission member key,来源为 `radio.group`、`checkbox.group`、`input.id`、`textarea.id`、`editor.id`、`select.id`、`slider.id`、`date-picker.id`、`segmented-control.id`、`map.id`、`diagram.id`;radio 需已选择,checkbox 组需至少选择一项,普通 field 的值需在 trim 后非空。`groups` 控制提交所需成员与完成进度;未设置时,至少有一个已完成成员即可提交。纯 radio 范围含 `answer` 且本次没有范围外 payload 时可本地判卷;其余场景一次发送 `[genui-action]`,payload 继续收集当前 block 中已填写的表单状态,字段名称保持 `answers`、`fields`、`total`、`answered`
  100. - switch: `{"type":"switch","label":"...","checked":true?,"action":"toggle"?}`
  101. - textarea: `{"type":"textarea","label":"...","placeholder":"...","rows":n?,"value":"...","action":"save"?,"id":"field-id"?}` — action 在失焦和 **Ctrl/Cmd+Enter** 时触发;blur 仅值有变化才发送;带 `id` 的值刷新后保留
  102. - editor: `{"type":"editor","id":"draft","label":"正文","value":"初始文本","placeholder":"继续编辑","rows":8}` — 纯文本编辑;编辑内容实时同步到当前区块;启用状态持久化且存储成功时,刷新可以恢复;可复制当前文字;带 `id` 的值也可由 sibling `submit` 统一提交
  103. - entity-card: `{"type":"entity-card","name":"Ada Lovelace","image":"https://example.com/ada.png","description":"数学家","metadata":[{"label":"领域","value":"计算机科学"}],"href":"https://example.com/source","sourceLabel":"来源","actions":[{"label":"查看详情","action":"open-ada"}]}` — 展示实体图片、名称、描述、元数据、来源链接和操作按钮;操作按钮通过 `action` 发送给宿主
  104. - popover: `{"type":"popover","label":"说明","content":"补充信息","trigger":"click","placement":"top"}` — 补充说明可设为 `click` 或 `hover` 触发;支持键盘焦点、Escape 和外部点击关闭,位置会在视口边缘自动调整
  105. - tabs: `{"type":"tabs","tabs":[{"label":"...","items":[...]}]}` — 空 tab 可以省略 `items`,会按空数组处理
  106. - accordion: `{"type":"accordion","items":[{"title":"...","items":[...]}]}`
  107. ```json dsh-ui
  108. {"items":[{"type":"date-picker","label":"Travel dates","mode":"range","value":"2026-10-12/2026-10-18","min":"2026-10-01","max":"2026-10-31","id":"travel_dates"},{"type":"segmented-control","label":"View","options":["Agenda","Map"],"value":"Agenda","id":"view"},{"type":"text","content":"Map view selected","when":{"field":"view","op":"eq","value":"Map"}}]}
  109. ```
  110. - copy: `{"type":"copy","label":"<user-language action>","text":"<user-language text>","expandable":true?,"previewLines":n?}` · [docs/copy-preview.md](docs/copy-preview.md)
  111. **状态持久化(v2.7)**:radio 答案、checkbox 分组选择、交卷锁定、输入值和 Editor 草稿按「会话 + 内容指纹」自动保存——用户刷新页面/重开会话,同一块 UI 的状态原样恢复;你重渲染**相同内容**会保留用户状态,渲染**新内容**(换题等)自动从头开始。
  112. ```dsh-ui
  113. {"items":[{"type":"editor","id":"reply","label":"回复草稿","value":"你好,","rows":6},{"type":"entity-card","name":"Ada Lovelace","description":"数学家","metadata":[{"label":"领域","value":"计算机科学"}],"href":"https://example.com/ada","actions":[{"label":"查看详情","action":"open-ada"}]},{"type":"popover","label":"保存说明","content":"编辑内容会保存在当前区块中。","trigger":"click","placement":"top"}]}
  114. ```
  115. **卷子模式(多道选择题)**:每题一个 radio(带唯一 `group` + `answer` + `explanation`),最后放一个 submit(`groups` 列出全部题号)——用户全部选完点交卷,**分数和对错当场在 UI 里出现**,不用等你。只有换新题/进阶建议才发 action。不要每题单独发 action(会刷屏)。
  116. ### 高级
  117. - svg: `{"type":"svg","title":"<user-language title>","height":300,"code":"<svg xmlns=\"http://www.w3.org/2000/svg\" viewBox=\"0 0 200 100\"><rect width=\"200\" height=\"100\" fill=\"#534ab7\"/></svg>"}` — 独立 SVG 图片预览;`title`/`height` 可省略,height 为 100–800,code 最多 12,000 字符,超限会拒绝而不会截断;验证工具返回字段路径、实际长度和上限,请精简或拆成多个 svg 后重验。必须提供完整 SVG 文档(含 xmlns),建议带 viewBox。使用隔离图片模式,不支持脚本、宿主 CSS 或外部资源;图形无法加载时显示源码和提示。
  118. - mermaid: `{"type":"mermaid","code":"graph TD\\nA-->B"}` — flowchart/sequence/class/gantt/pie/er/state/journey;主题自动跟随宿主(暗/浅);渲染完成后点图打开原生对话框查看大图,滚轮缩放、拖拽平移、工具栏放大/缩小/重置,Esc / 关闭 / 点遮罩返回并把焦点放回图表;弹层复用同一份已消毒 SVG,打开时不重跑渲染
  119. - diagram: `{"type":"diagram","kind":"architecture","id":"selectedNode","title":"<user-language title>","variant":"light|dark|editorial","nodes":[...],"edges":[...],"theme":{...}}` — **编辑级交互图解**(27 种视觉类型)。节点: `{"id":"a","label":"<user-language label>","description":"<detail shown after selection>","type":"focal|backend|store|external|input|optional|security","x":40,"y":40,"w":128,"h":48,"sub":"<user-language text>","tag":"<user-language text>"}`;边: `{"from":"a","to":"b","label":"<user-language label>","kind":"solid|dashed|accent|link"}`。用户可点击节点或按 Enter / Space 选择节点;图解会突出选中节点并显示说明。`id` 指定共享字段,所选节点 ID 可供其他组件的 `when.field` 读取。选择在本地更新,不触发模型 action。**规则由渲染器强制**: 正交连接器(r=8 弯折、禁止斜线)、4px 网格、语义 token(paper/ink/muted/accent)、焦点色 ≤2 个、复杂度预算(≤9 节点/≤12 边)、z-order(箭头在节点后)、边标签 6-10px 间隙。27 种 kind:architecture / it-state / flowchart / sequence / state / er / timeline / swimlane / quadrant / radar / loop / nested / tree / org-chart / layers / venn / pyramid / bar / line / gantt / scatter / high-level / process / medallion / data-flow / dp-integration / dp-security-matrix。**坐标类 kind**(architecture/it-state/high-level/process/medallion/data-flow/dp-integration)用 x/y/w/h 精确定位;**规则类 kind** 只给数据自动排版。架构/流程/层次结构优先用 diagram(自动布局需求才用 `mermaid`)。
  120. - scene3d: `{"type":"scene3d","title":"...","meshes":[{"shape":"box|sphere|cone|cylinder|torus","color":"#hex?","size":n|[w,h,d]?,"position":[x,y,z]?,"rotation":[rx,ry,rz]?,"scale":n?|[...]?}],"ambient":0-2?,"background":"#hex?"}` — 3D WebGL,可拖拽旋转、滚轮缩放;mesh 数量 1–5 个
  121. - quiz: `{"type":"quiz","question":"...","options":[{"label":"...","correct":true?,"feedback":"..."?}],"explanation":"...","id":"..."?,"action":"answer"?}` — 教学问答:点选即判题、可重试;`id` 变化时重置;带 action 时另回传 `{type:'quiz',question,answer,correct}`
  122. ## 什么时候用:内容类型 → 组件映射
  123. 使用倾向遵循当前系统提示中的 fenceSection 档位和用户要求:full 主动用于比较、趋势、流程依赖和交互任务,不必等用户提醒;minimal 不主动规定使用频率。用户明确要求纯文字时以用户为准。
  124. **没有组件数量配额,也不按条数或回答长度触发。** 下面的表是选择组件的词汇表,不是固定版式;不要把每条回答拼成同一个形状。
  125. 选型时先看内容的核心任务:比较、计算、做决定或看结构,再找最小的合适组件承载。普通解释和短清单默认用正文,只有比较、关系表达或交互确有帮助时才使用组件。一个回答通常只有一个真正的主组件,其余都是它的证据或操作。
  126. | 你要呈现的内容 | 用这些组件 |
  127. |---|---|
  128. | 并列结论 / 要点罗列(≥2 条) | `list`、`keyvalue` |
  129. | 单条重点强调 / 警告 / 注意事项 | `callout`(info/success/warning/error)、`badge`、`stat` |
  130. | 多项风险 / 注意事项 | `list`;需要统一风险底色时用 `card.tone` + `list` |
  131. | 数据对比 / 趋势 / 占比 | `chart`(bars/line/donut)、`echart`(ECharts 全功能)、`table` |
  132. | 关键指标数字 / 进度状态 | `stat`、`progress`、`badge` |
  133. | 回答的视觉锚点(第一个组件) | `hero`(封面块,一条回答最多一个) |
  134. | 想排版不呆板 | `grid` + 子节点 `span`(bento:宽窄混排) |
  135. | 数据多、需要读者自己找 | `input`(id)+ `table`/`chart`/`list` 的 `filter` 绑定 |
  136. | 流程 / 步骤 / 阶段 / 时间线 | `steps`、`timeline`、`mermaid`(flowchart/sequence/gantt) |
  137. | 架构 / 系统拓扑 / 数据流 / 品牌图 | `diagram`(编辑级,27 种类型;自动布局需求才用 `mermaid`) |
  138. | 目录 / 文件结构 / 层级关系 | `file-tree`、`mermaid`、`accordion` |
  139. | 状态一览 / 检查结果 | `badge` + `table` + `progress` 组合 |
  140. | 代码 / 配置 / 改动对比 | `code`、`diff`、`json` |
  141. | 图片 / 截图 / 图表预览 | `image` |
  142. | 语音 / 音乐 / AI 视频 / 演示录像 | `audio`、`video` |
  143. | 两个方案 / 选项对比 | `table`、`tabs`、`diff` |
  144. | 教学 / 自测 / 判断题 | `quiz` |
  145. | 数学函数 / 曲线关系 | `plot`(可带参数滑块、动画) |
  146. | 需要用户操作 / 筛选 / 反馈 | `button`、`input`、`select`、`checkbox`、`radio`、`switch`、`tabs` |
  147. | 3D 物体 / 空间布局 | `scene3d` |
  148. 多项风险需要统一底色时,复用 `card` 包含 `list`;普通要点直接用 `list`。卡片的严重风险色是 `danger`,提示框对应的是 `error`。
  149. ```json dsh-ui
  150. {"items":[{"type":"card","tone":"warning","title":"<user-language risk summary>","items":[{"type":"list","items":[{"title":"<user-language item title>","desc":"<user-language description>"},{"title":"<user-language item title>","desc":"<user-language description>"},{"title":"<user-language item title>","desc":"<user-language description>"}]}]}]}
  151. ```
  152. **别用的情况**:一句话能说清的事、纯闲聊、用户明确说不要 UI、以及"为了炫技硬塞"——组件服务内容,不是内容服务组件。
  153. ## 行内富文本(文字类回答的底座)
  154. `text.content`、`list` 项、`table` 文本列、`keyvalue` 值、`callout` 标题与正文里可以直接写四种行内标记——**重点留在句子里,不必为一个词单起一个组件**:
  155. | 写法 | 渲染 |
  156. |---|---|
  157. | `` `code` `` | 行内代码胶囊 |
  158. | `**加粗**` | 强调(不换行、不成块) |
  159. | `==高亮==` | 极淡底色标记 |
  160. | `[文字](https://…)` | 行内链接(http/https/mailto;围栏会话中的本地文件链接支持右侧栏打开与行号定位;无效目标及独立 HTML artifact 中的本地文件链接显示为普通文字) |
  161. | JSON `"\n"`(真实换行符) | 换行——**多段文字写同一个字段**,不要为换行拆成多个节点 |
  162. 不嵌套、不解析 HTML(每个标记生成 React 元素,不走 innerHTML;`<br>` 字面显示,换行用 `"\n"`);标记没闭合时原样显示。表格文本、`badge`、`delta` 单元格、分组标题和明细首格支持现有 http/https/mailto 外链与本地文件链接,可直接用于日报的来源列;无效目标仍显示为普通文字。点击链接不会同时折叠分组或展开明细。表头不解析链接,`bar`、`spark`、`ring`、`index` 等专用数值单元格保持原有展示。
  163. 文字字段只支持行内富文本。`text.content`、`callout.content`、`list` 项、`keyvalue` 值、`table` 单元格等字段中不要嵌入 Markdown 表格或连续三个及以上反引号、波浪号组成的代码围栏;表格使用 `table`,代码使用 `code`,代码改动使用 `diff`,结构化 JSON 使用 `json`。误写入文字字段的代码围栏连同内部标记保持原文,未闭合时从围栏标记开始保持原文。`validate_dsh_ui` 返回 `warning=block_markdown` 时,按照 `replacement` 改写结构节点并重新验证。
  164. ## 回答级版式:不默认套 card 容器,焦点唯一
  165. **规则来自设计规范,不是口味**(`design` skill 的 `references/design-reference.md`):
  166. 通用圆角矩形 `card` 不作为默认容器;这限制的是容器样式,不是 GenUI 的使用频率。`table`、`chart`、`list` 等组件可以直接使用。只有内容确实需要分组边界时才包卡片。
  167. 「如果替换内容不需要改布局,那就是模板,重做」。
  168. ### 三条判据(不设组件数量上限)
  169. 1. **内容适配**:使用倾向按当前档位执行,选择能承载比较、趋势、结构或交互任务的组件,不为套样式把普通解释拆成组件。
  170. 2. **焦点唯一**:一条回答只有一个视觉焦点(最大那张图或那组数字);其余组件的视觉权重必须明显更低,靠尺寸/位置/色彩强度拉开,**不是靠数组件个数**。
  171. 3. **不重复**:同一批数据不做两种表达(表格与图表二选一)。
  172. ### 卡片(`card`)只在有明确用途时用
  173. - 需要**并排**的 `grid` 子项(没有边界就分不清内容归属);
  174. - 承载**数据对象**:表格、图、keyvalue、指标组;
  175. - 同组风险需要**统一语义底色**:`card.tone` 包含 `list`,保留逐项标题与说明。
  176. 普通单段文字、普通列表、已经自带边界的表格/图表,**不要包卡**。用 `h3` 标题 + 正文 + 间距代替。
  177. ### 层级靠字,不靠框
  178. - 卡片标题 16px / 字重 650 / 句首大小写(**不是** 12.5px 全大写小标签);
  179. - 12.5px 全大写只用于 eyebrow(如 hero 上方那一行);
  180. - 大字号带负字距(≥32px 约 -0.022em,20–28px 约 -0.012em),数字列 `tabular-nums`;
  181. - CJK 正文行高 1.7,长段落行宽 ≤68ch;
  182. - 表面对比遵循规范:浅色相邻表面明度差 ≥4%,或阴影 ≥ `0 1px 3px rgba(0,0,0,0.10)`;深色靠半透明白叠加(卡片约 4%,抬升面 8%),投影在深色几乎无效。
  183. ### 不要
  184. - 装饰性编号(①②③):该分点用 `list`,该分节用标题;
  185. - 同一套骨架每条回答复用(标题栏 → 卡片网格 → 表格 → callout);
  186. - 为了"显得丰富"堆组件:读者找不到重点就是失败。
  187. ### 怎么验证没模板化
  188. `node scripts/genui-usage-audit.mjs` 输出「版式多样性」:不同版式签名数、最常见签名占比、归一化熵(越接近 1 越多样)、每回答 card 数分布。熵明显下降或 card 数不降反升,就说明规则没生效。
  189. ## 范例:示范「判断」,不要照抄组件序列
  190. 每个范例后面都跟着**什么时候不要这样**。组件多是好事——只要每个都在承载不同信息、并且有焦点和层次;真正的毛病是重复表达、以及把纯文字段落包进卡片。
  191. ### 1. 状态汇报(多点 + 有构图)
  192. ```json dsh-ui
  193. {"items":[{"type":"grid","cols":4,"items":[{"type":"stat","label":"<user-language metric>","value":"26","delta":"#123–#148"},{"type":"stat","label":"<user-language metric>","value":"0"},{"type":"stat","label":"<user-language metric>","value":"556","delta":"<user-language status>"},{"type":"stat","label":"<user-language metric>","value":"45"}]},{"type":"table","columns":["<user-language column>","<user-language column>","<user-language column>"],"types":["text","badge","text"],"rows":[["<user-language text>","<user-language status>","<user-language text>"],["<user-language text>","<user-language status>","<user-language text>"]]},{"type":"callout","tone":"info","title":"<user-language title>","content":"<user-language text>"}]}
  194. ```
  195. 不要这样:把同一句话既写进正文又放进卡片;也不要为每条信息配一张卡(4 个 stat 排一行就够)。
  196. ### 2. 解释/教学(文字为主,一个点睛组件)
  197. ```json dsh-ui
  198. {"items":[{"type":"text","size":"body","content":"<user-language text>"},{"type":"list","items":[{"title":"<user-language title>","desc":"<user-language description>"},{"title":"<user-language title>","desc":"<user-language description>"}]},{"type":"callout","tone":"warning","title":"<user-language title>","content":"<user-language text>"}]}
  199. ```
  200. 不要这样:每段都配一个组件;把一句话拆成好几个 text 节点(用行内标记就够了)。
  201. ### 3. 对比选型
  202. ```json dsh-ui
  203. {"items":[{"type":"table","columns":["<user-language column>","<user-language column>","<user-language column>"],"types":["text","text","badge"],"rows":[["<user-language text>","<user-language text>","<user-language status>"],["<user-language text>","<user-language text>","<user-language status>"]]},{"type":"callout","tone":"success","title":"<user-language title>","content":"<user-language text>"}]}
  204. ```
  205. 不要这样:表格里放同一批数据后又画一张图。
  206. 反例(这条会被围栏校验直接拒绝,所以别抄):
  207. ```json dsh-ui-bad
  208. {"items":[{"type":"chart","kind":"donut","data":[{"label":"A","value":1}],"series":[{"label":"B","data":[{"label":"B","value":2}]}]}]}
  209. ```
  210. 为什么拒:`series` 只对 `bars`/`line` 有效;环形图给了 `series` 属于契约冲突,围栏会**静默降级为代码块**。
  211. ### 4. 排查诊断(顺序即叙事)
  212. ```json dsh-ui
  213. {"items":[{"type":"steps","current":1,"steps":[{"title":"<user-language step>","desc":"<user-language description>"},{"title":"<user-language step>","desc":"<user-language description>"},{"title":"<user-language step>","desc":"<user-language description>"}]},{"type":"diff","diffs":[{"path":"PlotBlock.tsx","oldText":"e.preventDefault()","newText":"if (!e.metaKey && !e.ctrlKey) return"}]},{"type":"callout","tone":"info","title":"<user-language title>","content":"<user-language text>"}]}
  214. ```
  215. 不要这样:把"复现/定位/修复"写成三个卡片并列(那是流程,用 steps)。
  216. ### 5. 数据结论(一个主图 + 明细)
  217. ```json dsh-ui
  218. {"items":[{"type":"chart","kind":"line","data":[],"series":[{"label":"<user-language series>","data":[{"label":"<user-language point>","value":8},{"label":"<user-language point>","value":12},{"label":"<user-language point>","value":9}]}]},{"type":"table","columns":["<user-language column>","<user-language column>","<user-language column>"],"types":["text","num","delta"],"rows":[["<user-language text>","8","-4%"],["<user-language text>","12","+50%"]]}]}
  219. ```
  220. 不要这样:图与表用同一粒度表达同一批数据(图看趋势、表看明细才不重复)。
  221. ### 6. 短回答:正确地不套组件
  222. > 这个改动我先不做了——它要动宿主的输入组件,而你说了不碰宿主。
  223. 不要这样:一句话的结论配 stat + 表格 + callout。**没有内容就不发组件,这是对的,不算漏发。**
  224. ## 版式参考:几个见过的好形状(不是起点,也不是菜单)
  225. 下面这些是真实回答里出现过、读起来顺手的几种排法,放在这里供参考。**它们不是"先挑一个再填内容"的模板**:从内容和读者要做的动作出发,需要时借用其中一段,不需要就自己组合。
  226. 尤其不要因为"这份数据像主表明细"就把整条回答套进那个骨架——同一个问题问三次,三次都该长得不一样,因为三次的答案不一样。
  227. ### 阶段图(讲清「分几步 / 怎么变」的默认结构)
  228. 适用:一个过程有 2–4 个阶段,或一份数据被分成若干块、逐轮合并。
  229. ```json dsh-ui
  230. {"items":[{"type":"text","size":"h2","content":"<user-language 过程名>"},{"type":"card","items":[{"type":"row","items":[{"type":"icon","name":"Function","tone":"info","tile":true},{"type":"col","gap":2,"items":[{"type":"text","size":"h3","content":"<user-language 阶段一:名称>"},{"type":"text","size":"muted","content":"<user-language 这一步做什么>"}]}]},{"type":"arrow","length":22},{"type":"row","items":[{"type":"icon","name":"Nodes","tone":"success","tile":true},{"type":"col","gap":2,"items":[{"type":"text","size":"h3","content":"<user-language 阶段二:名称>"},{"type":"text","size":"muted","content":"<user-language 这一步做什么>"}]}]}]},{"type":"blocks","rows":[{"cells":["<user-language 块 0>","<user-language 块 1>","<user-language 块 2>","<user-language 块 3>"],"color":"#3d7eb8"}],"caption":"<user-language 每块代表什么>"}]}
  231. ```
  232. 何时不用:只有一步就别画阶段图;纯数值对比用 `chart`,别把数字塞进色块。
  233. ### 主表明细(数据问答的默认结构)
  234. 适用:用户问的数据要「先看总量 → 再筛 → 再钻某一行」。
  235. ```json dsh-ui
  236. {"items":[{"type":"grid","cols":2,"items":[{"type":"stat","label":"<user-language metric>","value":"<user-language value>","delta":"+3.1%"},{"type":"stat","label":"<user-language metric>","value":"<user-language value>"}]},{"type":"input","label":"<user-language filter>","placeholder":"<user-language hint>","id":"master-filter"},{"type":"table","filter":"master-filter","columns":["<user-language column>","<user-language column>","<user-language column>"],"types":["text","num","badge"],"rows":[["<user-language text>","128","<user-language status>"],["<user-language text>","190","<user-language status>"],["<user-language text>","250","<user-language status>"]],"details":[[{"type":"keyvalue","pairs":[{"key":"<user-language key>","value":"<user-language value>"}]}],null,[{"type":"progress","value":91,"target":80,"label":"<user-language metric>"}]]}]}
  237. ```
  238. 何时不用:行数 ≤5 不要配 `filter`;没有逐行明细可展开就别配 `details`;展开行里只放该行自己的信息,不要塞与该行无关的图表。
  239. ### 结论卡(分析收尾的默认结构)
  240. 适用:指标 + 一个明确判断 + 可执行的下一步(周报结论、复盘、健康度检查)。
  241. ```json dsh-ui
  242. {"items":[{"type":"grid","cols":3,"items":[{"type":"stat","label":"<user-language metric>","value":"<user-language value>","delta":"+2.4%"},{"type":"stat","label":"<user-language metric>","value":"<user-language value>"},{"type":"stat","label":"<user-language metric>","value":"<user-language value>","delta":"-1.2%"}]},{"type":"card","tone":"success","title":"<user-language title>","items":[{"type":"text","size":"body","content":"<user-language text>"},{"type":"progress","value":72,"target":80,"label":"<user-language metric>","valueLabel":"72%"}]},{"type":"row","items":[{"type":"button","label":"<user-language action>","tone":"primary","action":"<action-name>"},{"type":"button","label":"<user-language action>","tone":"ghost","action":"<action-name>"}]}]}
  243. ```
  244. 何时不用:结论还不成立时不要硬造结论卡(先摆数据,让读者自己看);没有真实可执行的下一步就不要放按钮;`tone` 只有在确实传递语义(好/坏/险)时才用。
  245. ### 封面页(报告开篇的默认结构)
  246. 适用:正式报告/复盘/评审材料的**第一屏**——一个大数字定调,一句引言点题,三张摘要卡预告正文。
  247. ```json dsh-ui
  248. {"items":[{"type":"hero","label":"<user-language metric>","value":"99.96%","delta":"+0.02%","tone":"accent","title":"<user-language title>","subtitle":"<user-language text>"},{"type":"text","size":"display","content":"<user-language statement>"},{"type":"divider","label":"<user-language chapter>"},{"type":"grid","cols":3,"items":[{"type":"card","title":"<user-language title>","items":[{"type":"stat","label":"<user-language metric>","value":"<user-language value>"}]},{"type":"card","title":"<user-language title>","items":[{"type":"stat","label":"<user-language metric>","value":"<user-language value>"}]},{"type":"card","title":"<user-language title>","items":[{"type":"stat","label":"<user-language metric>","value":"<user-language value>"}]}]}]}
  249. ```
  250. 何时不用:短回答不需要封面(hero 已是唯一焦点,再加 `display` 就是两个焦点);hero 与 `display` 同屏时,后面不要再出现 h1 级大标题;普通问答直接给答案,不要套封面。
  251. ### 对比页(方案权衡的默认结构)
  252. 适用:两个(至多三个)方案/版本/选型的正面对决——定性取舍进卡,定量差异进表。
  253. ```json dsh-ui
  254. {"items":[{"type":"grid","cols":2,"items":[{"type":"card","tone":"success","title":"<user-language option>","items":[{"type":"list","items":["<user-language text>","<user-language text>"]}]},{"type":"card","tone":"warning","title":"<user-language option>","items":[{"type":"list","items":["<user-language text>","<user-language text>"]}]}]},{"type":"table","columns":["<user-language column>","<user-language column>","<user-language column>"],"types":["text","num","num"],"rows":[["<user-language text>","8","12"],["<user-language text>","5","9"]]}]}
  255. ```
  256. 何时不用:只有单一方案时就是普通陈述,不要硬摆两张卡假装权衡;卡与表要承载**不同粒度**(卡给取舍理由、表给数值对比),两边复制同一批数字就是重复表达。
  257. ### 时间线叙事(过程复盘的默认结构)
  258. 适用:有先后顺序的过程/事故/迭代叙事——时间线主叙事,收尾一张卡给汇总结论。
  259. ```json dsh-ui
  260. {"items":[{"type":"timeline","items":[{"title":"<user-language milestone>","desc":"<user-language description>","time":"<user-language date>"},{"title":"<user-language milestone>","desc":"<user-language description>","time":"<user-language date>"},{"title":"<user-language milestone>","desc":"<user-language description>","time":"<user-language date>"}]},{"type":"card","title":"<user-language title>","items":[{"type":"keyvalue","pairs":[{"key":"<user-language key>","value":"<user-language value>"},{"key":"<user-language key>","value":"<user-language value>"}]}]}]}
  261. ```
  262. 何时不用:两步以内的小流程用正文一句话讲清;纯日志列举不要套卡,`timeline` 单独就够。
  263. ### 测验页(教学自测的默认结构)
  264. 适用:教学/检查理解——两题以上的成组测验,radio 组带答案与解析,`submit` 聚合交卷本地判卷。
  265. ```json dsh-ui
  266. {"items":[{"type":"radio","label":"<user-language question>","group":"q1","options":["<user-language option>","<user-language option>","<user-language option>"],"answer":1,"explanation":"<user-language explanation>"},{"type":"radio","label":"<user-language question>","group":"q2","options":["<user-language option>","<user-language option>"],"answer":0,"explanation":"<user-language explanation>"},{"type":"submit","label":"<user-language action>","action":"grade","groups":["q1","q2"]}]}
  267. ```
  268. 何时不用:单一知识点用单个 `radio`(自带本地判卷)或 `quiz` 组件,不需要 submit 组卷;题目多于 5 个拆成多条回答分批发。
  269. ### Computed(输入驱动计算)
  270. 交互区内随输入变化的数字 MUST 绑定计算字段,包括说明文字和公式里的当前值;MUST NOT 另写一份固定数字。需要展示初始算例时 MUST 明确标注“初始值”,避免用户改值后把旧数字误认为当前结果。
  271. 在规格根部用 `computed` 声明有序无关的计算字段。表达式只支持数字、字段 ID、括号、`+ - * / % ^` 和 `sin cos tan asin acos atan sqrt cbrt exp log ln abs floor ceil round min max pow` 白名单函数,以及 `pi/e/tau` 常量;不执行 JavaScript。字段 ID 以字母或下划线开头,后续可含数字,最多 64 个字符。表达式最多 512 个字符、嵌套最多 32 层、每份规格最多 50 个计算字段;未声明字段、循环依赖和无效数值会显示为无效输入,图表会跳过无效点。
  272. `{{fieldId}}` 只引用 `computed` 中声明的计算字段,用于规格标题、文本、表格文字单元格和统计卡片等展示文字。输入字段 ID 只在 `expr` 内读取;要显示输入原值,先声明别名,如 `{"id":"shownPeople","expr":"people"}`,再写 `{{shownPeople}}`,不要直接写 `{{people}}`。未知引用会在校验时报告。代码、SVG、Mermaid 源码及 JSON 等原始数据保留原文。输入字段与计算字段重名时,该字段及依赖它的计算字段均显示为无效输入。`chart`、`echart` 的数据点和 `table` 单元格使用 `{"$computed":"fieldId"}` 引用数值。完整 ECharts `option` 中的数据值也可使用该引用。`format` 可设置 `locale`、`style`(`decimal|currency|percent`)、`currency` 和小数位范围。表格显示格式化文字,排序使用原始数值。`number` 输入接受带正负号的小数及科学计数法十进制值;十六进制、二进制和八进制写法无效。暂时无法解析的编辑内容保留在输入框中,不会覆盖上一次有效计算值;必填字段处于无效编辑状态时,提交按钮会禁用并显示提示。
  273. ```dsh-ui
  274. {"computed":[{"id":"annual","expr":"monthly*12","format":{"locale":"zh-CN","style":"currency","currency":"CNY","maximumFractionDigits":0}},{"id":"tax","expr":"annual*rate","format":{"locale":"zh-CN","style":"currency","currency":"CNY","maximumFractionDigits":0}}],"items":[{"type":"input","id":"monthly","label":"月收入","inputType":"number","value":"10000"},{"type":"input","id":"rate","label":"税率","inputType":"number","value":"0.1"},{"type":"stat","label":"年度收入","value":"{{annual}}"},{"type":"stat","label":"预估税额","value":"{{tax}}"},{"type":"chart","kind":"bars","data":[{"label":"收入","value":{"$computed":"annual"}},{"label":"税额","value":{"$computed":"tax"}}]},{"type":"table","columns":["项目","金额"],"rows":[["年度收入",{"$computed":"annual"}],["预估税额",{"$computed":"tax"}]]}]}
  275. ```
  276. ## 使用规则
  277. 1. **按呈现位置选择通道**:正文内联内容使用围栏;工具结果区域的独立 UI 使用 `render_ui`(仅在该工具可用时);持续更新的会话面板使用 `panel:true`。围栏和工具都支持交互状态保存,不以是否交互或是否保存状态区分。围栏一闭合就立即渲染(不等整条回答结束),前后可以自然衔接文字。
  278. 2. **组合优先**:复杂界面用 `grid`+`card`+`stat`+`table` 拼,不要追求单一巨型组件
  279. 3. **JSON 必须严格合法**:调用校验工具后,`next=emit_fence` 时逐字复制 `native_fence_json` 或 `validated_json`;`next=emit_repaired_fence` 时逐字复制 `repaired_json`。不要凭记忆重新拼写 JSON,也不要在复制后增删节点、改文案或改括号;要改内容就修改规格并重新验证。未通过校验时按诊断修正,不以渲染器可能补齐标点或括号为交付依据。
  280. 3.5. **字段名逐个核对**:未知组件类型(包括 `Card` / `Text` 等大小写误写)以及缺失必填字段会被校验工具拒绝。正文可保留其余有效组件;无法修复时展示源码和诊断,不会假报渲染成功。`tabs[].items` 必须提供(允许显式空数组),`content` 可作为别名;`card.body` / `card.content` 会归一化为 `items` 并提示。高频误写:`callout` 正文是 `content`(不是 text/body);`table` 要 `columns` + `rows`(只给二维 rows 时首行会当表头);`keyvalue` 要 `pairs:[{key,value}]`;`diff` 是 `diffs`;图片/音视频是 `src`;`code` 是 `code`、`copy` 是 `text`。拿不准就调 `validate_dsh_ui`,不要凭直觉命名。
  281. 4. **不要嵌套围栏**:dsh-ui 里不要再包 ``` 代码围栏
  282. 5. **深色主题友好**:配色选深底亮色;UI 主题跟随应用
  283. 6. **场景判断**:根据组件是否能帮助读者理解或操作来决定是否使用,并遵循当前系统提示的档位;需要组件时,查阅上面的映射表选择合适的组件。
  284. 7. **图表范围**:`plot` 给合理 xMin/xMax(如 -3.14 到 3.14);3D 场景 mesh 少而精
  285. 8. **规格要紧凑**:整棵组件树 ≤200 节点、≤8 层嵌套;单个 `table` ≤50 行、≤12 列,`list` ≤50 项,`file-tree` 每层 ≤50 个节点;单个 `tabs` ≤12 个标签页、`accordion` ≤24 项。超出限制的内容会被截断,并由 `validate_dsh_ui` 报告;长内容请分成多个组件,并在发出围栏前调用 `validate_dsh_ui` 检查。
  286. 9. **一个主题选一个主组件**:命中映射表后选**一种**组件承载,同一信息不要用两种组件重复表达(同一批数据又画 bars 又画 donut = 冗余)
  287. 10. **一个主题一个主组件**:不要把同一件事拆成五块小组件凑数量;宁缺毋滥,纯文字讲清就不出。反例:该用 `table` 对比时写三段 `text`;一个 `stat` 能说清的事套 `card`+`grid`;与内容无关的 `scene3d` 炫技——3D 只在内容本身就是几何/空间时才用
  288. 12. **给命令就给能直接粘的**:多行 python 一律写成 heredoc 包装的**一整段** shell 代码块(`python - <<'PY'` … `PY`),不要用 `python -c "…"` 配反斜杠续行——续行在复制/粘贴里最容易碎成多行,用户还得自己拼回 heredoc。单行表达式才用 `-c`,且必须真的在一行内写完。示例:
  289. ````text
  290. cd /path/to/repo
  291. python - <<'PY'
  292. import json
  293. d = json.load(open('report.json'))
  294. print(d.get('status'))
  295. PY
  296. ````
  297. 同理:需要用户执行的脚本放进 `code` 节点(`lang`: `bash`/`python`)或正文围栏,并保证**从第一行到最后一行一次粘进终端就能跑**。
  298. 11. **先验后发(复杂 UI)**:发出 ```dsh-ui 围栏前,若 spec ≥3 个组件、含 `table`,或任一组件接近资源上限,先调用 `validate_dsh_ui` 工具(参数 `spec` 传围栏内的 JSON 文本)验证;返回 `next=fix_and_revalidate` 就按诊断修正后重新验证;返回 `next=emit_fence` 再发出;返回 `next=emit_repaired_fence` 时直接照抄 `repaired_json` 发出,无需再次验证;简单 UI(≤2 个组件且未接近资源上限)不必验证,渲染器会自动修复大部分标点/括号错误
  299. ### 地图 `map`:地点选择与内联路线
  300. 需要让用户比较地点、选择候选位置或查看示意路线时,使用原生 `map`,不要用静态图片伪装交互地图。默认是无街道底图的离线坐标地图,真实标记与路线由 MapLibre 渲染。地点列表始终可用。
  301. ```dsh-ui
  302. {"items":[{"type":"map","id":"stop","title":"候选地点(合成示例)","locations":[{"id":"a","label":"地点 A","coordinates":[12.49,41.89]},{"id":"b","label":"地点 B","coordinates":[12.51,41.90]}],"routes":[{"id":"r","label":"示意路线,非导航","coordinates":[[12.49,41.89],[12.51,41.90]]}]},{"type":"submit","label":"确认地点","action":"choose_stop","groups":["stop"]}]}
  303. ```
  304. - `locations` 必填,最多 50 项:`id` 唯一且稳定,`label`,`coordinates: [经度, 纬度]`,可选 `description`。坐标必须有限,经度 [-180,180]、纬度 [-90,90];不确定坐标时不要编造真实地点。
  305. - 可选 `routes` 最多 8 条,每条有 `id`、`label`、2–500 对内联坐标。只接受 LineString 路径,不调用导航、地理编码或远程 GeoJSON。不要声称路线可安全通行、距离或预计时间已核实。
  306. - 可选 `center`、`zoom`(0–20)、`height`(200–640)、`selected`(地点 ID)。选中标记与列表双向同步;缩放、重置视图、清除选择都只在本地执行。
  307. - `id` 复用表单字段持久化,独立 `submit` 才发送 `fields[id] = 选中地点 ID`。不要在 map 上写 `action`。
  308. - 不允许在模型 JSON 中设置 style、source URL、worker URL、API key 或凭据,不请求地理位置权限。外部底图只能由可信宿主配置。导出保留离线坐标地图,不导出宿主的私有样式配置;分享前审查地点隐私。
  309. - 资源或 WebGL 不可用时明确降级为可操作地点列表与路线坐标,不把降级描述成完整地图。完整契约见 `docs/map.md`。
README.md · README · 448 lines
  1. <div align="center">
  2. <img src="./assets/genui-logo.svg" width="380" alt="GenUI for DeepSeek Harness">
  3. <p align="center">
  4. <strong>Generative UI for DeepSeek Harness (DSH)</strong><br>
  5. Interactive, rich components rendered inline alongside the model's textual responses.
  6. </p>
  7. [![npm version](https://img.shields.io/npm/v/@changfenhuang/dsh-genui.svg?style=flat-square&color=3B82F6)](https://www.npmjs.com/package/@changfenhuang/dsh-genui)
  8. [![DSH Compatibility](https://img.shields.io/badge/DSH-^0.2.0--rc.1%20||%20^0.2.1--rc.1%20||%20^0.2.2--alpha.2-10B981?style=flat-square)](https://github.com/omdsh-dev/dsh-genui)
  9. [![License: MIT](https://img.shields.io/badge/License-MIT-amber.svg?style=flat-square)](LICENSE)
  10. [![TypeScript](https://img.shields.io/badge/TypeScript-Ready-blue?style=flat-square&logo=typescript)](https://www.typescriptlang.org/)
  11. [![Topic: dsh-plugin](https://img.shields.io/badge/ecosystem-dsh--plugin-purple?style=flat-square)](https://github.com/topics/dsh-plugin)
  12. <p align="center">
  13. <strong>English</strong> · <a href="./README.zh-CN.md">简体中文</a>
  14. </p>
  15. <p align="center">
  16. <a href="https://omdsh-dev.github.io/dsh-genui/"><strong>🌐 Live Product Site</strong></a> ·
  17. <a href="#-real-interface-showcase"><strong>🎬 Real Demo</strong></a> ·
  18. <a href="#-quick-start"><strong>🚀 Quick Start</strong></a> ·
  19. <a href="#-capability-matrix"><strong>🧩 Feature Matrix</strong></a> ·
  20. <a href="./SKILL.md"><strong>📖 Component Syntax (SKILL.md)</strong></a>
  21. </p>
  22. </div>
  23. ---
  24. `dsh-genui` turns DeepSeek Harness (DSH) assistant replies into **safe, fully interactive UI surfaces**.
  25. Ask “How are this month’s orders doing?”, and instead of plain text or raw code blocks, the response streams out an **interactive sortable data table**, **audio/video players**, **draggable function plots**, **self-grading quizzes**, or a **persistent workspace dock** — all embedded seamlessly within the conversation.
  26. ---
  27. ## 🎬 Real Interface Showcase
  28. > [!NOTE]
  29. > **Real Interface Captures:** All recordings and screenshots below are captured directly from real DSH interface rendering — no conceptual mockups or faked pre-renders.
  30. ### 40-Second Walkthrough
  31. <div align="center">
  32. https://github.com/user-attachments/assets/f5db33ec-7471-4d4a-a85b-79c9962ab4ef
  33. <p align="center">
  34. <a href="./assets/demo.mp4"><img src="./assets/demo-thumb.png" width="88%" alt="Preview of the complete dsh-genui walkthrough video"></a>
  35. <br><em>(Click the thumbnail to download the <a href="./assets/demo.mp4">original MP4</a> if the GitHub video player fails to load. The prompt sequence is documented in <a href="./demo-prompts.md">demo-prompts.md</a>.)</em>
  36. </p>
  37. </div>
  38. ### Three Concrete Real Outputs
  39. | 1. Monitoring Panel: Answer is the Dashboard | 2. Function Plot: Drag to Redraw Instantly | 3. Composable Hierarchy: Work Surface |
  40. | :--- | :--- | :--- |
  41. | ![Monitoring Panel](./assets/showcase-panel.png) | ![Function Plot](./assets/showcase-plot.png) | ![Composable Hierarchy](./assets/showcase.png) |
  42. | **Data Insights:** Eyebrow stats, filterable/drill-down service table, grouped totals, and spark/ring cells directly live in the assistant reply. | **Zero-Latency Exploration:** `plot` draws mathematical curves; drag parameter sliders to re-calculate and redraw locally in real time. | **Structured Hierarchy:** Display quotes, stat cards, ring progress, and labeled chapter dividers composed declaratively by the model. |
  43. ---
  44. ## ✨ Before vs. After
  45. | Scenario | Plain Text Response | With dsh-genui |
  46. | :--- | :--- | :--- |
  47. | **Business Overview** | “Revenue this month is ¥128,430 (+12.4% MoM); conversion rate is slightly dipping…” | One line of concise prose + 3 stat cards (revenue/orders/conversion), a trend chart, and a progress bar rendered right beside it. |
  48. | **Data Exploration** | Type another prompt to ask the model to re-sort or filter. | Click table headers to **sort numbers locally**, or use the search box to filter rows in real time. |
  49. | **Parameter Tuning** | Re-prompt the model and wait for another full generation. | Drag sliders to see curves update in **sub-millisecond speed** with animation preview. |
  50. | **Next Actions** | Copy text and manually perform follow-up tasks elsewhere. | Click interactive action buttons (e.g. “Refresh”, “Switch View”) to trigger **bidirectional model event loops**. |
  51. ---
  52. ## 🚀 Quick Start
  53. ### 1. Prerequisites
  54. Ensure your environment meets the following requirements:
  55. - **DSH Version**: `^0.2.0-rc.1 || ^0.2.1-rc.1 || ^0.2.2-alpha.2`. Packed browser acceptance covers `0.2.0-rc.1`, `0.2.1-rc.3` and the exact npm hosts `0.2.2-rc.1` (current `latest` / `next`) and `0.2.2-alpha.2`; `0.2.1-rc.4` and `0.2.1-rc.5` retain separate public-API, full-unit-suite and build checks. The current RC and alpha hosts require **Node.js >=24.9.0**. Its gallery, computed-field and Map acceptance uses official local replay; third-party sidebar integration is checked on rc.3.
  56. - **pnpm on PATH**: The `dsh plugin` CLI requires pnpm. If missing: run `corepack enable` or `npm i -g pnpm`, then **open a new terminal** and confirm `pnpm -v` prints a version number.
  57. ### 2. Install & Activate
  58. Run a single command in your terminal (all dependencies are fetched automatically):
  59. ```sh
  60. # Public npm package (works without an npm account)
  61. dsh plugin --profile web add @changfenhuang/dsh-genui
  62. ```
  63. > [!TIP]
  64. > **Adding only as a Node package?** Run `npm install @changfenhuang/dsh-genui`. Note that `npm install` only adds the dependency and does not register the plugin with DSH; use the `dsh plugin add` command above for DSH integration.
  65. ### 3. Verify in 60 Seconds
  66. 1. Restart the DSH web service and **hard refresh** your browser (`Cmd + Shift + R` or `Ctrl + F5`).
  67. 2. In a **new conversation session**, send:
  68. ```text
  69. Use dsh-ui to draw a stats dashboard with a sortable service table.
  70. ```
  71. 3. **Expected result**: The reply renders an in-place interactive dashboard rather than a plain code block.
  72. 4. **Console activation check**: Open your browser Developer Tools Console and look for `[genui] client active; fence-channel=dom`.
  73. ---
  74. > [!WARNING]
  75. > ### ⚠️ Installation Pitfalls to Avoid
  76. >
  77. > 1. **Watch the Package Scope (Crucial)**:
  78. > The package must be **`@changfenhuang/dsh-genui`**. npm hosts an unrelated, unscoped package named `dsh-genui` (a Vue/OpenTiny implementation by another maintainer); installing it will fail due to incompatible host peer dependencies.
  79. > 2. **Do Not Use `link:` on a Freshly Cloned Directory**:
  80. > `link:` alone does not bundle or resolve peer assets (mermaid, three.js, React). Use npm for standard usage; reserve `link:` strictly for local development (see [Developer Guide](#-developer-guide)).
  81. > 3. **Migrating from Legacy `@omdsh-dev`**:
  82. > If you installed from GitHub or the old org name before v0.9.2, clean up the stale key:
  83. > ```sh
  84. > dsh plugin --profile web remove @omdsh-dev/dsh-genui
  85. > dsh plugin --profile web add @changfenhuang/dsh-genui
  86. > ```
  87. ---
  88. ## 🧩 Capability Matrix
  89. Every component and behavior is guarded by the strict `dsh-ui` specification. See [SKILL.md](./SKILL.md) for full JSON schema details.
  90. ```
  91. dsh-genui Capabilities
  92. ├── 🌊 1. Streaming & Realtime Mounting
  93. ├── 🎨 2. 30+ Component Ecosystem
  94. ├── ⚡ 3. Local-First Responsiveness
  95. ├── 🔄 4. Bidirectional Action Event Loop
  96. ├── 📌 5. Persistent Session Workspace & Templates
  97. └── 🛡️ 6. Sandboxing, Guards & Self-Healing
  98. ```
  99. ### 1. 🌊 Streaming & Realtime Mounting
  100. - **Answer-as-UI**: Components stream into the conversation as tokens arrive, mounting incrementally without waiting for the full reply to finish.
  101. - **Graceful Fallback**: If the plugin is absent or disabled, fences degrade cleanly to standard Markdown code blocks without breaking the chat history.
  102. ### 2. 🎨 30+ Component Ecosystem
  103. - **Display & Typography**: Hero banner, Stat cards (`stat` with eyebrow labels, deltas, and sparklines), Tables, Timelines, Code Diffs, Step progress, File trees (interactive expand/collapse), Callouts, and Badges.
  104. - **Content Font Size**: Card typography grows with the host's Appearance → Content Font Size setting above 17px. At 17px or below, each component keeps its existing size. Standalone HTML exports keep their existing sizes.
  105. - **Advanced Tables**:
  106. - Click headers to **sort locally** (ascending / descending / reset) with smart parsing for numbers, currency, commas, percentages, and `k/m/b` units;
  107. - Columns support inline progress bars (`bar`), rings (`ring`), sparklines (`spark`), and badges;
  108. - One-click data export (Copy Markdown / CSV) and instant client-side text filtering (`filter`).
  109. - **ECharts Integration (`echart`)**:
  110. - **Preset Mode**: Shorthand presets (`bar`, `line`, `area`, `pie`, `scatter`, `radar`, `gauge`, `funnel`, `treemap`, `sankey`, `graph`, `heatmap`, `bigline`, `wordCloud`) that adapt automatically to host light/dark themes;
  111. - **Full Option Mode**: Full native ECharts options for advanced features like DataZoom and VisualMap;
  112. - **On-Demand Lazy Loading**: The ~1 MB ECharts engine is loaded asynchronously only when an `echart` block is encountered.
  113. - **Mathematical Function Plots (`plot`)**:
  114. - Multi-series plotting with expressions (trig, log, exp, power);
  115. - **Live Parameter Sliders**: Drag sliders to redraw curves instantly at 60 FPS; supports auto-animation loops.
  116. - **Mermaid & 3D Visuals**: Flowcharts, sequence diagrams, and lightweight 3D models with on-demand asset loading. A rendered Mermaid diagram opens a zoomable SVG dialog on click: wheel zoom, drag pan, zoom/reset controls, Esc, Close or backdrop to close with focus restored.
  117. - **Native Galleries**: `carousel` composes existing cards and forms in a responsive, keyboard-navigable horizontal track; `image-group` opens images in a local lightbox with focus restoration. Navigation does not invoke model actions. [Examples and verification](docs/gallery.md).
  118. - **Native Media**: Inline playback for accessible audio and video URLs, with poster images, aspect ratios, and controls; a single `image` opens a zoom dialog on click and returns focus to the picture when it closes.
  119. - **KaTeX Math Rendering**: Inline math (`$...$`) and display blocks (`$$...$$`), supporting matrices and multi-line equations.
  120. ### 3. ⚡ Local-First Responsiveness
  121. - **Zero-Latency Interactions**: State transitions that the frontend can handle alone (sorting, filtering, accordion toggling, slider redraws, tab switches) execute **entirely client-side** without round-trips to the model.
  122. - **Quizzes & Submission (`quiz` / `submit`)**:
  123. - Single quizzes evaluate instantly with explanations and retry options;
  124. - Multi-question assessments support batch grading and progress tracking with the `groups` schema.
  125. - **Durable Persistence**: User inputs, form fields, and quiz states persist across page reloads via session fingerprints (LRU cache of 200 blocks).
  126. ### 4. 🔄 Bidirectional Action Event Loop
  127. - **Closed-Loop Interactions**: Interactive elements equipped with an `action` payload package user events back to the model to trigger follow-up reasoning.
  128. - **Honest UI Guarantee**: Buttons without an `action` render disabled to eliminate "dead clicks"; active buttons show immediate visual feedback upon trigger.
  129. - **Debounced Delivery**: Discrete taps send immediately; continuous slider drags apply trailing-edge debounce to prevent message flooding.
  130. ### 5. 📌 Persistent Session Workspace & Templates
  131. - **Session Dock Panel**: Open a persistent dock above the composer via `/panel` or `panel: true`; resize by dragging its border; append tabs incrementally with `append: true`.
  132. - **Template Center & Badges**:
  133. - **Templates**: Browse 11 pre-built scenario templates directly from the dock to kickstart prompts;
  134. - **Achievements**: Unlock 12 built-in local exploration badges as you interact with various components.
  135. ### 6. 🛡️ Sandboxing, Guards & Self-Healing
  136. - **Security by Design**: Strictly whitelisted JSON components; zero script injection or `eval`; **strict prohibition of passwords or secret collection**.
  137. - **Same-Turn Fence Steering**: If a generated fence fails validation, diagnostic errors are fed back to the model within the **same turn** so it can self-correct (can be disabled via `fenceFeedback: false`).
  138. - **Resilient Fallbacks**: Malformed nodes are safely discarded while siblings render normally (single node errors never crash the fence); Mermaid syntax glitches are automatically repaired.
  139. ---
  140. ## 💻 Quick Examples
  141. ### Example 1: Executive KPI Dashboard
  142. The model emits the following `dsh-ui` code block:
  143. ```dsh-ui
  144. {
  145. "title": "Q3 2026 Executive Overview",
  146. "items": [
  147. {
  148. "type": "row",
  149. "items": [
  150. { "type": "stat", "label": "Total Revenue", "value": "¥128,430", "delta": "+12.4%", "spark": [40, 55, 60, 85, 120] },
  151. { "type": "stat", "label": "Completed Orders", "value": "1,024", "delta": "-3.1%", "spark": [90, 85, 80, 75, 70] },
  152. { "type": "progress", "label": "Quarterly Target", "value": 82, "variant": "ring" }
  153. ]
  154. }
  155. ]
  156. }
  157. ```
  158. ### Example 2: ECharts Revenue Trend
  159. ```dsh-ui
  160. {
  161. "title": "Revenue Breakdown",
  162. "items": [
  163. {
  164. "type": "echart",
  165. "title": "Monthly Performance",
  166. "preset": "bar",
  167. "data": [
  168. { "label": "Jan", "value": 98 },
  169. { "label": "Feb", "value": 112 },
  170. { "label": "Mar", "value": 128 },
  171. { "label": "Apr", "value": 145 },
  172. { "label": "May", "value": 160 }
  173. ]
  174. }
  175. ]
  176. }
  177. ```
  178. > For the comprehensive specification and full component catalog, refer to [SKILL.md](./SKILL.md).
  179. ---
  180. ## ⚙️ Architecture & How It Works
  181. ```mermaid
  182. sequenceDiagram
  183. autonumber
  184. actor User as User
  185. participant Host as DSH Host / LLM
  186. participant DOM as Conversation DOM
  187. participant GenUI as GenUI Client Renderer
  188. participant Assets as On-Demand Assets (ECharts/Three)
  189. User->>Host: Prompt (e.g. "Analyze recent order trends")
  190. Host-->>DOM: Streams Markdown prose & ```dsh-ui fence
  191. DOM->>GenUI: Detects fence and normalizes schema against whitelist
  192. alt Requires Heavy Engines
  193. GenUI->>Assets: Dynamically fetches engine bundles
  194. Assets-->>GenUI: Assets loaded
  195. end
  196. GenUI->>DOM: Mounts React component tree incrementally
  197. opt Client-Side Local Actions
  198. User->>GenUI: Sort table / Drag plot slider / Answer quiz
  199. GenUI-->>User: Instant sub-millisecond local update
  200. end
  201. opt Model Action Feedback
  202. User->>GenUI: Click interactive action button
  203. GenUI->>Host: Dispatches structured action payload
  204. Host-->>DOM: Model responds with next-step reasoning / updates panel
  205. end
  206. ```
  207. ### Artifact Exporting
  208. Completed GenUI blocks can be exported on demand:
  209. - **Standalone `.html`**: Inlines the lightweight renderer, CSS styles, KaTeX fonts, required chart engines, and the same-origin images it can read so the interactive UI can be viewed and tested offline in any browser.
  210. - **`.genui.json`**: Retains the normalized specification and durable interaction states for storage and portability.
  211. ---
  212. ## 🧑‍💻 Developer Guide
  213. ### Local Development (Link Mode)
  214. ```sh
  215. git clone https://github.com/omdsh-dev/dsh-genui.git
  216. cd dsh-genui
  217. pnpm install
  218. # Build and link into your DSH web profile
  219. dsh plugin --profile web add link:$PWD
  220. ```
  221. ### Useful Commands
  222. ```sh
  223. pnpm run check # Type checks + full unit test suite + build
  224. pnpm run test # Run Vitest unit tests
  225. pnpm run check:host-api dsh-v0.2.1-rc.3 # Check the retained rc.3 host API
  226. pnpm run check:host-api dsh-v0.2.1-rc.4 # Check the earlier rc.4 API
  227. pnpm run check:host-api dsh-v0.2.1-rc.5 # Check the earlier rc.5 API, full suite and build
  228. pnpm run check:host-api dsh-v0.2.2-rc.1 # Check the current npm latest / next API, full suite and build
  229. pnpm run check:host-api dsh-v0.2.2-alpha.2 # Check the supported npm alpha API, full suite and build
  230. node scripts/verify-pack.mjs --keep # Verify and inspect npm tarball
  231. ```
  232. ### End-to-End (E2E) Testing
  233. CI and the release workflow install `0.2.2-alpha.2` from npm with `node scripts/prepare-published-host.mjs 0.2.2-alpha.2`, then verify the packed plugin in a fresh web profile. This lane uses `DSH_HOST_LAYOUT=registry` and `DSH_HOST_VERSION=0.2.2-alpha.2` with the returned `DSH_ROOT` and `DSH_BIN`; the source-host lanes remain pinned to their official tags. The same registry-host lane also installs `0.2.2-rc.1`, with `DSH_HOST_VERSION=0.2.2-rc.1`. Registry-host checks pin Cordis framework dependencies to the versions recorded in each host’s published manifest so later dependency resolution cannot change the host graph. Both current RC and alpha API, gallery/computed and Linux Map checks must pass before npm publication. Actions use official local replay; Android device and original Windows Desktop acceptance remain separate.
  234. - **Visual E2E Smoke (No Model API Key Required)**:
  235. ```sh
  236. npx tsx scripts/e2e-visual.mts # Boots headless Chrome, tests gallery rendering and asserts interactions
  237. ```
  238. - **Real-Model Integration E2E**:
  239. ```sh
  240. export DSH_ROOT=/path/to/deepseek-harness-0.2.1-rc.3
  241. export DSH_BIN="$DSH_ROOT/apps/cli/lib/bin.js"
  242. DEEPSEEK_API_KEY=sk-... node scripts/e2e.mjs
  243. ```
  244. ### Advanced Profile Configurations
  245. To customize plugin behaviors, add configurations under `cordis.patch.yml` in your profile:
  246. ```yaml
  247. - id: genui
  248. name: '@changfenhuang/dsh-genui'
  249. config:
  250. renderUiTool: false # Disable registering the render_ui tool card (fences and panel remain active)
  251. fenceFeedback: false # Disable automatic same-turn steer correction on malformed fences
  252. fenceSection: full # full (default), minimal, or false
  253. ```
  254. `fenceSection` controls both fence guidance detail and usage preference:
  255. | Mode | Behavior |
  256. | --- | --- |
  257. | `full` (default) | Provides syntax and essential rules, and proactively uses components for comparisons along shared dimensions, numerical trends, process dependencies, and user interaction, without waiting for a reminder. |
  258. | `minimal` | Keeps only the fence example and the requirement to load the GenUI skill; user instructions determine usage preference. |
  259. | `false` | Omits the `genui:fence` section. |
  260. Requirement words follow [RFC 2119](https://www.rfc-editor.org/rfc/rfc2119): valid JSON, current fields, and explicit user language and presentation requirements are MUST rules. In `full`, using appropriate UI for comparisons, trends, dependencies, and interaction is SHOULD guidance; card wrappers are MAY. `full` sets no list-length trigger or component quota. Ordinary explanations and short lists default to prose. Modes guide behavior rather than guaranteeing a fixed usage rate.
  261. Use fences for inline reply content, `render_ui` for a standalone UI in the tool result, and `panel:true` for the session panel that updates in place. Both fences and tools preserve interaction state; choose by placement. `card` is an optional container: avoiding unnecessary card wrappers does not mean avoiding GenUI.
  262. Skill availability is resolved in the current agent's tool view, including preset-owned loaders; a global `skill` registration is not required. The visible tool must expose the Skill loader contract, and `genui` must allow model invocation. When the skill already includes current fields, no component reference is injected. An older skill receives only missing or changed field descriptions in `genui:reference`; appended user preferences do not trigger a full reference. User skill files remain untouched, and current system fields take precedence over loaded older fields.
  263. If a compatible loader or model-invocable GenUI skill is unavailable, a compact field reference is supplied for fence guidance or an available `render_ui` tool. `fenceSection: false` omits fence guidance; disabling both fence guidance and `render_ui` also omits the reference. Neither setting disables fence rendering or panels. The dsh-go `genui:native` section and tool definitions have independent guidance and token costs. Loading the full skill for an actual UI response still consumes context; this change removes the unconditional duplicate catalog rather than making that load free.
  264. ### Embedding into Other Applications
  265. You can import `GenuiBlock`, `GenuiActionContext`, and `processGenuiSpec` from `@changfenhuang/dsh-genui/embed` to embed the renderer into any React application supporting CSS Modules.
  266. ### dsh-go integration
  267. The dsh-go integration uses the App’s existing native cards, inline choices and plugin panels; no App patch or replacement APK is needed. The complete web spec stays authoritative. Native panels support choices, switches, buttons, submissions, local grading, tabs, accordions, copy and confirmed HTTPS links. Validation can produce one JSON fence readable by both renderers. Panels currently require the local-engine dsh-go bridge; SSH and relay hosts retain native tool cards. Advanced graphics and free-text input remain explicit limitations. See [capabilities and verification](docs/dsh-go.md).
  268. ### Theming: non-opaque host canvases
  269. Every surface resolves through one chain: `--dsl-g-surface` → `--dsh-genui-surface` → `--dsw-alias-bg-layer-2` → … → `#fff`. A skin that paints the page itself (wallpaper, glass / translucent look) can pin the surface once without touching the host's own tokens:
  270. ```css
  271. :root { --dsh-genui-surface: rgba(255, 255, 255, 0.58); }
  272. body[data-ds-dark-theme] { --dsh-genui-surface: rgba(32, 32, 34, 0.54); }
  273. ```
  274. `callout` and toned `card` washes are painted *over* that surface, so they stay readable on any canvas. `card.flat` and `table` are surface-less by design (a printed block, a bare data grid) and would show a non-opaque page through — they fill only when a skin asks for it:
  275. ```css
  276. :root {
  277. --dsh-genui-surface: rgba(255, 255, 255, 0.58); /* cards, callouts, controls */
  278. --dsh-genui-surface-flat: var(--dsh-genui-surface); /* card.flat */
  279. --dsh-genui-surface-table: var(--dsh-genui-surface); /* table */
  280. }
  281. ```
  282. Leaving the last two unset keeps today's look (transparent table, 2.5% printed flat card); pointing them at `var(--dsh-genui-surface)` gives all three one fill. Wrapping a table in a `card` fills it too, since the parent surface shows through (issue #398).
  283. ---
  284. ### Sidechat surfaces (optional)
  285. GenUI can render settled `dsh-ui` fences on provider-declared sidechat surfaces. BetterSidebar uses its `registerSidechatSurfaceAdapter` capability; other providers can expose the optional `genuiSidechat` Cordis service. Each surface carries its owning thread identity and prompt callback, so actions and interaction state stay within that child thread. Streaming rows and unsupported or invalid fences keep their original Markdown.
  286. See [the sidechat surface adapter contract](docs/sidechat-surfaces.md). BetterSidebar support requires a release containing [its provider implementation](https://github.com/omdsh-dev/DSH-better-sidebar/pull/1033); the released 0.28.0 does not expose `registerSidechatSurfaceAdapter`. The DSH native Side Chat provider must expose `genuiSidechat` to enable this integration.
  287. ## ❓ FAQ & Troubleshooting
  288. <details>
  289. <summary><strong>Q: Why are dsh-ui fences still showing up as raw code blocks?</strong></summary>
  290. 1. Open your browser Developer Tools (F12) and inspect the Console.
  291. 2. Search for the log `[genui] client active; fence-channel=dom`:
  292. - **If missing**: The client bundle was not activated by the host. Verify that `dsh plugin list` shows the plugin as active, restart DSH web, and hard refresh your browser;
  293. - **If present**: Check whether the code block language identifier is strictly `dsh-ui` and that its body contains valid JSON.
  294. </details>
  295. <details>
  296. <summary><strong>Q: Error: "pnpm not found on PATH"?</strong></summary>
  297. DSH plugin management calls `pnpm` under the hood. Run `corepack enable` or `npm i -g pnpm`, then **open a new terminal window** before running `dsh plugin add`.
  298. </details>
  299. <details>
  300. <summary><strong>Q: npm install returns 404?</strong></summary>
  301. The package is public and requires no login. Verify the package name via `npm view @changfenhuang/dsh-genui version`. If a version was published very recently, allow a few moments for registry mirrors to synchronize.
  302. </details>
  303. <details>
  304. <summary><strong>Q: 3D scene, Mermaid, or ECharts does not render?</strong></summary>
  305. Heavier engines are lazy-loaded through plugin-provided static routes upon their first appearance. Hard refresh your browser (`Cmd + Shift + R`). If the issue persists, reinstall the package:
  306. ```sh
  307. dsh plugin --profile web remove @changfenhuang/dsh-genui
  308. dsh plugin --profile web add @changfenhuang/dsh-genui
  309. ```
  310. </details>
  311. <details>
  312. <summary><strong>Q: The chat screen goes blank when rendering a fence?</strong></summary>
  313. This version requires DSH `^0.2.0-rc.1 || ^0.2.1-rc.1 || ^0.2.2-alpha.2`. Older host versions lack necessary React slot/context capabilities; please upgrade DSH.
  314. </details>
  315. ---
  316. ## 🗺️ Roadmap Evaluation
  317. | Exploration Area | Decision | Rationale |
  318. | :--- | :---: | :--- |
  319. | **Incremental Diff Patching** | Declined | A fence costs only 200–800 tokens; resending is fast and safe. Teaching models a patch diff protocol introduces high friction and hallucination rates. |
  320. | **Granular Action Delivery** | ✅ Done | Discrete gestures send immediately; continuous slider drags apply trailing-edge debounce to keep chat context clean. |
  321. | **Cross-Session Replay Persistence** | Declined | Resetting on replay is the more natural expectation when the model updates the UI; state is preserved seamlessly during streaming. |
  322. | **Separate Gallery / i18n Strings** | Declined | The component gallery is covered by `demo-prompts`, `gallery.ts`, and README screenshots; the core bundle carries only 6 built-in UI strings. |
  323. ---
  324. ## 🔗 Links & Community
  325. - [Linux.do Community Discussion](https://linux.do)
  326. - Visit the [Live Product Site](https://omdsh-dev.github.io/dsh-genui/) to explore more demos.
  327. ---
  328. ## 📄 License
  329. This project is licensed under the [MIT License](LICENSE).
  330. ### Interactive maps
  331. The `map` node combines lazy MapLibre markers and inline routes with an
  332. always-available keyboard-operable location list. Selection stays local and can
  333. be persisted/submitted as a stable location ID through the existing fields
  334. contract. The default is an offline blank coordinate map, not a street basemap;
  335. external styles belong to trusted host configuration, never model JSON.
  336. See [the map contract and embedding/export guide](docs/map.md).

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.