@changfenhuang/dsh-genui 0.9.9 → 0.10.0

package/src/client/spec.ts

@@ -10,7 +10,13 @@
  */
 
 /** One node in the component tree. */
-export type GenuiNode =
+/** Layout hints accepted by every node: `span` is how many columns the node
+ *  occupies as a direct child of a `grid` (bento layouts). */
+export interface GenuiLayoutHints {
+  span?: number
+}
+
+export type GenuiNode = (
   | GenuiText
   | GenuiRow
   | GenuiCol
@@ -26,6 +32,7 @@ export type GenuiNode =
   | GenuiVideo
   | GenuiBadge
   | GenuiStat
+  | GenuiHero
   | GenuiProgress
   | GenuiDivider
   | GenuiList
@@ -55,6 +62,7 @@ export type GenuiNode =
   | GenuiBreadcrumb
   | GenuiQuiz
   | GenuiDiagram
+) & GenuiLayoutHints
 
   | GenuiEChart
 
@@ -194,19 +202,41 @@ export interface GenuiBadge {
   icon?: string
 }
 
+/** Cover band: the answer's focal point. One per fence — an eyebrow label, an
+ *  oversized metric, a title and a subtitle on a soft tinted surface. */
+export interface GenuiHero {
+  type: 'hero'
+  title: string
+  subtitle?: string
+  /** Oversized metric, e.g. "99.96%" / "3.2x". */
+  value?: string
+  /** Eyebrow label above the metric. */
+  label?: string
+  delta?: string
+  spark?: number[]
+  tone?: 'accent' | 'success' | 'warning' | 'danger'
+}
+
 export interface GenuiStat {
   type: 'stat'
   label: string
   value: string
   delta?: string
+  /** Optional micro trend line (finite numbers, 2..60 points). */
+  spark?: number[]
+  /** `hero` renders one oversized number — use it once per fence as the anchor. */
+  size?: 'hero'
 }
 
 export interface GenuiProgress {
   type: 'progress'
-  label?: string
-  /** 0..100 */
   value: number
+  label?: string
   valueLabel?: string
+  /** `bar` (default) draws a track; `ring` draws a circular gauge. */
+  variant?: 'bar' | 'ring'
+  /** Optional target marker on the bar track (0-100). */
+  target?: number
 }
 
 export interface GenuiDivider {
@@ -247,11 +277,17 @@ export interface GenuiGrid {
 export interface GenuiCard {
   type: 'card'
   title?: string
+  /** Semantic tint for the card surface (default: neutral). */
+  tone?: 'info' | 'success' | 'warning' | 'danger'
+  /** Explicit accent (hex) driving the border, title and wash. */
+  accent?: string
   items: GenuiNode[]
 }
 
 export interface GenuiList {
   type: 'list'
+  /** Field id of an input/select: its value filters the items locally. */
+  filter?: string
   items: Array<string | { title: string; desc?: string } | GenuiNode>
 }
 
@@ -259,7 +295,30 @@ export interface GenuiTable {
   type: 'table'
   columns: string[]
   rows: Array<Array<string | number>>
-}
+  /** Per-column cell type; missing = auto (numeric right-align, signed delta). */
+  types?: TableCellType[]
+  /** Append a 合计 footer row (numeric columns are summed). */
+  total?: boolean
+  /** Show 复制 Markdown / 复制 CSV chips above the table. */
+  export?: boolean
+  /** Optional master-detail payload, positionally aligned with `rows`:
+   *  `details[i]` is what row i expands into (omit / empty = not expandable). */
+  details?: Array<GenuiNode[] | null>
+  /** Field id of an input/select: its live value filters the rows locally
+   *  (substring match), so the table is searchable without a model round trip. */
+  filter?: string
+  /** Restrict `filter` to one column index (default: every column). */
+  filterColumn?: number
+  /** Field id of a select whose value is a column header: sorts by it locally. */
+  sortField?: string
+}
+
+/** How a table column's cells render.
+ *  - `bar` / `ring`: the cell is read as 0-100
+ *  - `spark`: the cell is a number list ("3,5,4,8") drawn as a mini trend
+ *  - `index`: the 1-based row number (cell content is ignored)
+ *  - `delta` / `num` / `badge` / `text`: text treatments. */
+export type TableCellType = 'text' | 'num' | 'delta' | 'bar' | 'badge' | 'spark' | 'ring' | 'index' | 'group'
 
 export interface GenuiChartDatum {
   label: string
@@ -272,8 +331,16 @@ export interface GenuiChart {
   /** Chart shape: bars (default), line (trend), donut (share). */
   kind?: 'bars' | 'line' | 'donut'
   data: GenuiChartDatum[]
-  /** Multi-series grouped bars: one series of data per entry. */
+  /** Multi-series: grouped bars, or one line per entry when kind is line. */
   series?: Array<{ label: string; color?: string; data: GenuiChartDatum[] }>
+  /** Bars only: horizontal bars (rankings, long category labels). */
+  horizontal?: boolean
+  /** Bars + series: stack the series instead of grouping them. */
+  stacked?: boolean
+  /** Explicit categorical palette (hex) — overrides the host theme colours. */
+  palette?: string[]
+  /** Field id of an input/select: its value filters the categories locally. */
+  filter?: string
 }
 
 export interface GenuiTab {
@@ -691,7 +758,9 @@ export interface GenuiDiagram {
 
 /** Preset chart kinds the `echart` node can build from `data`/`series` without
  * a full ECharts option. Each maps to a themed option template. */
-export type EChartPreset = 'bar' | 'line' | 'area' | 'pie' | 'scatter'
+export type EChartPreset =
+  | 'bar' | 'line' | 'area' | 'pie' | 'scatter'
+  | 'radar' | 'gauge' | 'funnel' | 'treemap' | 'sankey' | 'graph' | 'heatmap' | 'bigline'
 
 /** ECharts node: renders a full ECharts chart. Two modes:
  *
@@ -720,6 +789,10 @@ export interface GenuiEChart {
   data?: GenuiChartDatum[]
   /** Multi-series for preset mode (same shape as `chart.series`). */
   series?: Array<{ label: string; color?: string; data: GenuiChartDatum[] }>
+  /** Node/edge data for the `sankey` and `graph` presets. */
+  links?: Array<{ from: string; to: string; value?: number }>
+  /** Explicit categorical palette (hex) for preset mode. */
+  palette?: string[]
   /** Full ECharts option object. When present, `preset`/`data`/`series` are
    * ignored. This is a pass-through to `echarts.setOption`. */
   option?: Record<string, unknown>

package/src/plugin/index.ts

@@ -28,9 +28,9 @@ import { createRenderUiTool, createValidateDshUiTool } from './tool.ts'
  * This route serves them from the plugin's own package directory through the
  * host webserver service — the longest-prefix rule lets it win over the
  * generic `/plugins` bundle route, and no host source change is needed. The
- * service is optional at this plugin's start time (same ordering reality as
- * the tools registry), so registration probes immediately AND on the
- * `internal/service` event, exactly like the tools registration below.
+ * service is optional at this plugin's start time, so a dependency fiber owns
+ * the registration and follows the webserver through late binding, replacement,
+ * and plugin reloads.
  */
 
 /** Route prefix under /plugins; anything under it is this plugin's asset. */
@@ -94,16 +94,26 @@ export const GENUI_SECTION_TEXT = `You can render interactive UI components INSI
 
 The spec is a white-listed component tree rendered inline where the fence sits. Only these \`type\` values; the \`genui\` skill, when available, carries the full content→component mapping and per-component field details:
 
-- 布局: text · row · col · grid · card · divider · spacer
+- 布局: text · row · col · grid · card · divider · spacer · hero（封面块：超大数字 + 标题 + tone 渐变底色，一条回答最多一个）
 - 展示: badge · stat · progress · list · table · keyvalue · avatar · audio · video · timeline · file-tree · breadcrumb · callout · steps · diff · json · code · copy
-- 图表: chart {"type":"chart","kind":"bars|line|donut","data":[{"label":"...","value":n,"color":"#hex?"}],"series":[...]?}（series 仅 bars；未知扩展字段可通过校验，但原生 chart repair/render 会忽略） · echart (preset|option) · plot (函数图)
+- 图表: chart {"kind":"bars|line|donut","data":[{"label":"...","value":n}],"series":[{"label":"...","data":[...]}]?,"horizontal":true?,"stacked":true?}（series：bars 分组/堆叠 / line 多序列；horizontal 横向柱） · echart (preset: bar/line/area/pie/scatter/radar/gauge/funnel/treemap/sankey/graph/heatmap/bigline，或 option 直通) · plot (函数图)
 - 交互: button · input · textarea · select · checkbox · switch · slider · radio · submit · quiz · link · tabs · accordion
 - 高级: mermaid (flowchart/sequence/class/gantt/pie/er/state/journey) · diagram (编辑级架构/流程图，27 种 kind) · scene3d (3D WebGL)
 
+**默认就该出 UI**：出现下列情况至少出一个围栏：
+- ≥3 条并列要点 → \`list\`；数字对比 → \`table\`；指标/进度/状态 → \`stat\`/\`progress\`/\`badge\`
+- 步骤/时间线 → \`steps\`/\`timeline\`/\`mermaid\`；架构/流程 → \`diagram\` 或 \`mermaid\`；风险/结论 → \`callout\`；代码/改动 → \`code\`/\`diff\`/\`json\`
+- 行内富文本：\`text\`/\`list\`/表格文本列/\`keyvalue\`/\`callout\` 里可写 \`code\`、**加粗**、==高亮==、[文字](url)：重点留在句中，不必为一个词单起组件。
+- 默认无卡 ≠ 少用组件：硬触发照常出组件，**组件多不是问题**——判据是每个组件承载不同信息、有焦点与层次、同一批数据不重复表达。卡片只用于并排项与数据对象；单段文字用「标题 + 正文 + 间距」。
+
+**发回答前最后自检一次**：这段内容里有没有 ≥3 条并列要点、任何对比、任何数字/指标、任何步骤或流程？有就先转成组件再开口。**状态汇报、进度说明、提交与改动清单同样算**——不要因为它是"说明文"就用纯文字写。这一条踩过的坑：连续几条汇报全靠文字，一条围栏都没发。
+- 趋势/占比 → \`chart\`（≤8 点）或 \`echart\`（多序列/要交互时）；配色默认跟随主题，只有语义需要时才用 \`palette\` / \`card.accent\`；排版用 grid 子节点的 \`"span":2\` 跨列做宽窄混排（bento），不要一列方块堆到底；数据多时给 \`table\`/\`chart\`/\`list\` 配一个 \`input\`(id) + \`filter\` 绑定，读者能就地筛选，不用再问一遍
+
+**字段速查**（完整见 genui skill）：\`stat\` \`{"label","value","delta"?}\` · \`table\` \`{"columns","rows","types"?,"total"?,"details"?,"filter"?,"export"?}\` · \`callout\` \`{"tone","title","content"}\` · \`progress\` \`{"value","variant"?,"target"?}\`
+
 Rules:
-- 触发: 结构化表达优于纯文本时主动用（要点、强调、对比、流程、步骤、状态、数据、演示），纯问答与一句话不套 UI；一个主题一个主组件，每次 3–8 个组件，同一数据不重复出现。
 - JSON 严格: 坏围栏降级为代码块；≥3 节点或含 table 的围栏发出前调用 validate_dsh_ui，❌ 修好再发（若附「已自动修复」JSON 照抄即可）。
-- 规模: ≤200 节点、嵌套≤8 层（超出被截断）；3D mesh 1–5；plot 给合理 xMin/xMax。
+- 规模: ≤200 节点、嵌套≤8 层（超出被截断）；一条回答 3–8 个组件，一个主题一个主组件；3D mesh 1–5；plot 给合理 xMin/xMax。
 - LOCAL-FIRST + actions: UI 能自己做的状态变化（判卷、判题、重置、展开、选中）就地完成，零往返；action 只用于必须模型参与的事。交互组件带 "action":"name"，交互以 [genui-action] name + 组件数据回传，届时重渲染更新 UI；无 action 的按钮禁用。
 - Durable state: 交互状态按「会话+内容指纹」持久化——刷新/重放恢复；重渲染相同内容保留，新内容重置。
 - 卷子模式: 每题一个 radio（group+answer+explanation）+ 一个 submit（groups 全列），本地判分。
@@ -167,49 +177,27 @@ export function apply(ctx: Context): void {
     order: ctx.systemPrompt.getSectionOrder('STRUCTURED_OUTPUT'),
     text: GENUI_SECTION_TEXT,
   })
-  // The tools service is optional: hosts without tool access (or minimal
-  // compositions) keep the fence channel; only when the registry exists does
-  // the render_ui tool join the model's tool set. `reflect.get(name, false)`
-  // is cordis's non-throwing optional service lookup (the proxy's own trap
-  // uses it) — property access without inject would throw instead.
-  //
-  // Start-up ordering: this plugin injects only `systemPrompt`, so cordis
-  // starts it EARLY — before the tools provider (which injects deeper
-  // dependencies) has bound its service. A one-shot probe at apply time
-  // therefore misses the registry on real hosts (the fence section lands,
-  // the tool never registers). Fix: probe immediately AND subscribe to
-  // `internal/service` (emitted by cordis on every service binding), so the
-  // registration lands the moment `tools` appears, whatever the order.
-  let registered = false
-  const tryRegister = (value: { register(tool: unknown): unknown } | undefined): void => {
-    if (registered) return
-    const tools = value ?? ctx.reflect.get('tools', false) as { register(tool: unknown): unknown } | undefined
-    if (tools === undefined) return
-    tools.register(createRenderUiTool())
-    tools.register(createValidateDshUiTool())
-    registered = true
-  }
-  tryRegister(undefined)
-  ctx.on('internal/service', (name: string, value: unknown) => {
-    if (name === 'tools') tryRegister(value as { register(tool: unknown): unknown })
+  // Hosts without tool access keep the fence channel. The dependency fiber
+  // starts whenever tools becomes available and unloads its registrations
+  // before either the service or this plugin is replaced.
+  ctx.inject(['tools'], (toolsCtx) => {
+    toolsCtx.effect(function* () {
+      yield toolsCtx.tools.register(createRenderUiTool())
+      yield toolsCtx.tools.register(createValidateDshUiTool())
+    }, 'dsh-genui: model tools')
   })
 
   ctx.inject(['skills'], (skillCtx) => {
     skillCtx.skills.registerProvider(() => bundledSkillProvider())
   })
 
-  // Lazy-engine asset route: same optional-probe pattern as the tools
-  // registry — the webserver service may bind after this plugin starts.
-  let assetsRegistered = false
-  const tryRegisterAssets = (value: { register(route: unknown): unknown } | undefined): void => {
-    if (assetsRegistered) return
-    const webServer = value ?? ctx.reflect.get('webServer', false) as { register(route: unknown): unknown } | undefined
-    if (webServer === undefined) return
-    webServer.register({ kind: 'prefix', path: ASSET_ROUTE_PATH, handler: serveGenuiAsset })
-    assetsRegistered = true
-  }
-  tryRegisterAssets(undefined)
-  ctx.on('internal/service', (name: string, value: unknown) => {
-    if (name === 'webServer') tryRegisterAssets(value as { register(route: unknown): unknown })
+  // webServer.register returns a raw disposer, so an explicit effect binds the
+  // route to the dependency fiber instead of leaving it in the host route table.
+  ctx.inject(['webServer'], (webCtx) => {
+    const webServer = webCtx.reflect.get('webServer') as { register(route: unknown): () => void }
+    webCtx.effect(
+      () => webServer.register({ kind: 'prefix', path: ASSET_ROUTE_PATH, handler: serveGenuiAsset }),
+      'dsh-genui: asset route',
+    )
   })
 }

package/src/plugin/tool.ts

@@ -44,7 +44,11 @@ const RENDER_UI_PARAMETERS: Record<string, unknown> = {
   properties: {
     spec: {
       type: 'object',
-      description: 'GenUI component tree (white-listed vocabulary, see the dsh-ui fence section in the system prompt). Deep-validated and repaired by the renderer. Pass the spec as a JSON OBJECT — never as a serialized JSON string (a string fails argument validation).',
+      description: [
+      'Render structured UI for the user (tool-row card). USE THIS whenever the answer contains ≥3 parallel points, a comparison, numbers/metrics, a step sequence, a flow, or a status/report — do NOT write those as markdown bullets or a markdown table.',
+      'Same white-listed vocabulary as the ```dsh-ui fence (see the GenUI system-prompt section). Pick the fence when the UI belongs in the message body; pick this tool when the deliverable is a self-contained card.',
+      'Deep-validated and repaired by the renderer. Pass the spec as a JSON OBJECT — never as a serialized JSON string (a string fails argument validation).',
+    ].join(' '),
       // Structural hints for the tool-call bridge. A bare `object` here was
       // observed to make some bridge layers stringify the whole spec into an
       // OpenAI-style `{ arguments: "<JSON>" }` wrapper (and to corrupt long

package/tsdown.config.ts

@@ -189,5 +189,6 @@ export default [
   clientConfig,
   assetConfig('mermaid', 'src/client/asset-mermaid.ts'),
   assetConfig('three', 'src/client/asset-three.ts'),
-  assetConfig('echarts', 'src/client/asset-echarts.ts'),
+  assetConfig('echarts-core', 'src/client/asset-echarts-core.ts'),
+  assetConfig('echarts-full', 'src/client/asset-echarts.ts'),
 ]