@changfenhuang/dsh-genui 0.9.3 → 0.9.7

package/src/plugin/chart-contract.ts

@@ -0,0 +1,103 @@
+import { validateGenuiChartSemantics } from '../client/guard.ts'
+
+/** Plain object helper for raw model-authored specs. */
+function obj(value: unknown): Record<string, unknown> | undefined {
+  return typeof value === 'object' && value !== null && !Array.isArray(value)
+    ? value as Record<string, unknown>
+    : undefined
+}
+
+/**
+ * Visit chart nodes through the component-bearing containers understood by
+ * the GenUI guard. This deliberately does not recursively inspect arbitrary
+ * objects (for example `json.value` or `echart.option`), where a nested
+ * `{type:"chart"}` is data rather than a GenUI node.
+ */
+function visitChartNodes(
+  value: unknown,
+  visit: (node: Record<string, unknown>, at: string) => void,
+): void {
+  function walkNode(value: unknown, at: string): void {
+    const node = obj(value)
+    if (node === undefined || typeof node.type !== 'string') return
+    if (node.type === 'chart') visit(node, at)
+
+    if ((node.type === 'row' || node.type === 'col' || node.type === 'grid' || node.type === 'card') && Array.isArray(node.items)) {
+      walk(node.items, `${at}.items`)
+      return
+    }
+    if (node.type === 'tabs' && Array.isArray(node.tabs)) {
+      for (let index = 0; index < node.tabs.length; index++) {
+        const tab = obj(node.tabs[index])
+        if (tab === undefined) continue
+        const items = tab.items !== undefined ? tab.items : tab.content
+        if (Array.isArray(items)) walk(items, `${at}.tabs[${index}].items`)
+        else walkNode(items, `${at}.tabs[${index}].items`)
+      }
+      return
+    }
+    if (node.type === 'accordion' && Array.isArray(node.items)) {
+      for (let index = 0; index < node.items.length; index++) {
+        const item = obj(node.items[index])
+        if (item === undefined) continue
+        const items = item.items !== undefined ? item.items : item.content
+        if (Array.isArray(items)) walk(items, `${at}.items[${index}].items`)
+        else walkNode(items, `${at}.items[${index}].items`)
+      }
+      return
+    }
+    if (node.type === 'list' && Array.isArray(node.items)) {
+      for (let index = 0; index < node.items.length; index++) {
+        walkNode(node.items[index], `${at}.items[${index}]`)
+      }
+    }
+  }
+
+  function walk(list: unknown, path: string): void {
+    if (!Array.isArray(list)) return
+    for (let index = 0; index < list.length; index++) {
+      walkNode(list[index], `${path}[${index}]`)
+    }
+  }
+
+  const root = obj(value)
+  if (root === undefined) return
+  if (!Array.isArray(root.items) && root.type === 'chart') walkNode(root, 'spec')
+  else walk(root.items, 'items')
+}
+
+/**
+ * Validate the native chart contract all the way to something the renderer
+ * can actually draw. The shared guard still owns field/type validation; this
+ * layer adds renderer-specific invariants that would otherwise produce an
+ * empty line/donut chart or a grouped-bars shell with no points.
+ */
+export function validateRenderableChartSemantics(value: unknown): string[] {
+  const errors = validateGenuiChartSemantics(value)
+  visitChartNodes(value, (node, at) => {
+    const kind = node.kind === undefined ? 'bars' : node.kind
+
+    if (Array.isArray(node.data) && node.data.length === 0) {
+      errors.push(`${at}.data must not be empty`)
+    }
+    if (Array.isArray(node.series)) {
+      if (node.series.length === 0) errors.push(`${at}.series must not be empty`)
+      for (let index = 0; index < node.series.length; index++) {
+        const series = obj(node.series[index])
+        if (series !== undefined && Array.isArray(series.data) && series.data.length === 0) {
+          errors.push(`${at}.series[${index}].data must not be empty`)
+        }
+      }
+    }
+
+    if (kind === 'line' || kind === 'donut') {
+      if (node.series !== undefined) {
+        errors.push(`${at}.series is only supported for bars`)
+      }
+      if (node.data === undefined) {
+        errors.push(`${at}.data is required for ${kind}`)
+      }
+    }
+  })
+  return errors
+}

package/src/plugin/index.ts

@@ -13,9 +13,11 @@
 import { Context } from '@deepseek-ai/cordis'
 import type {} from '@deepseek-ai/dsh-system-prompt'
 import type {} from '@deepseek-ai/dsh-tools'
+import type { SkillProvider } from '@deepseek-ai/dsh-skill'
 import type { IncomingMessage, ServerResponse } from 'node:http'
+import { readFileSync } from 'node:fs'
 import { readFile } from 'node:fs/promises'
-import { join } from 'node:path'
+import { basename, dirname, join, resolve } from 'node:path'
 import { fileURLToPath } from 'node:url'
 import { createRenderUiTool, createValidateDshUiTool } from './tool.ts'
 
@@ -98,7 +100,7 @@ The spec is a white-listed component tree rendered inline where the fence sits.
 
 - 布局: text · row · col · grid · card · divider · spacer
 - 展示: badge · stat · progress · list · table · keyvalue · avatar · audio · video · timeline · file-tree · breadcrumb · callout · steps · diff · json · code · copy
-- 图表: chart (bars|line|donut) · echart (preset|option) · plot (函数图)
+- 图表: chart {"type":"chart","kind":"bars|line|donut","data":[{"label":"...","value":n,"color":"#hex?"}],"series":[...]?}（series 仅 bars；未知扩展字段可通过校验，但原生 chart repair/render 会忽略） · echart (preset|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)
 
@@ -123,6 +125,46 @@ Rules:
 // instead (see apply).
 export const inject = ['systemPrompt']
 
+const BUNDLED_SKILL_RANK = 600
+const BUNDLED_SKILL_PROVIDER = 'dsh-genui'
+const BUNDLED_SKILL_DESCRIPTION = 'GenUI 完整组件与字段规范，用于生成 dsh-ui 结构化交互界面。'
+const BUNDLED_SKILL_INVOCATION = { modelInvocable: true, userInvocable: true } as const
+
+/** Register through the provider path so source=bundled also gets bundled precedence. */
+function bundledSkillProvider(): SkillProvider {
+  const moduleDirectory = dirname(fileURLToPath(new URL(import.meta.url)))
+  const path = basename(moduleDirectory) === 'plugin'
+    ? resolve(moduleDirectory, '../../SKILL.md')
+    : resolve(moduleDirectory, '../SKILL.md')
+  const raw = readFileSync(path, 'utf8')
+  const end = raw.indexOf('\n---\n', 4)
+  if (!raw.startsWith('---\n') || end < 0) throw new Error('genui SKILL.md has invalid frontmatter')
+  return {
+    name: BUNDLED_SKILL_PROVIDER,
+    list: () => Promise.resolve([{
+      name: 'genui',
+      description: BUNDLED_SKILL_DESCRIPTION,
+      invocation: BUNDLED_SKILL_INVOCATION,
+      source: 'bundled',
+      provider: BUNDLED_SKILL_PROVIDER,
+      path,
+      resourceBase: { kind: 'directory', path: dirname(path) },
+      rank: BUNDLED_SKILL_RANK,
+      locator: path,
+    }]),
+    get: () => Promise.resolve({
+      name: 'genui',
+      description: BUNDLED_SKILL_DESCRIPTION,
+      invocation: BUNDLED_SKILL_INVOCATION,
+      source: 'bundled',
+      provider: BUNDLED_SKILL_PROVIDER,
+      path,
+      resourceBase: { kind: 'directory', path: dirname(path) },
+      content: raw.slice(end + 5),
+    }),
+  }
+}
+
 export function apply(ctx: Context): void {
   ctx.systemPrompt.section({
     name: 'genui:fence',
@@ -156,6 +198,10 @@ export function apply(ctx: Context): void {
     if (name === 'tools') tryRegister(value as { register(tool: unknown): unknown })
   })
 
+  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

package/src/plugin/tool.ts

@@ -22,8 +22,11 @@ import type { ContentBlock } from '@deepseek-ai/dsh-llm'
 import type { JsonValue } from '@deepseek-ai/dsh-session'
 import type { GenericCallView, GenericResultView, JsonSchemaNode, ToolDefinition } from '@deepseek-ai/dsh-tools'
 import type { GenuiSpec } from '../client/spec.ts'
-import { GENUI_LIMITS, countDeclaredGenuiNodes, countGenuiNodes, repairGenuiSpec } from '../client/guard.ts'
+import {
+  GENUI_LIMITS, countDeclaredGenuiNodes, countGenuiNodes, repairGenuiSpec,
+} from '../client/guard.ts'
 import { completeFenceJson } from '../shared/fence-repair.ts'
+import { validateRenderableChartSemantics } from './chart-contract.ts'
 
 /**
  * Arguments schema: an open `spec` slot. The schema must NOT reject anything
@@ -172,7 +175,12 @@ export function createRenderUiTool(): ToolDefinition {
       },
     },
     async execute(args: unknown): Promise<JsonValue> {
-      const spec = repairGenuiSpec(specOf(args))
+      const input = specOf(args)
+      const chartErrors = validateRenderableChartSemantics(input)
+      if (chartErrors.length > 0) {
+        throw new Error('render_ui spec invalid: ' + chartErrors.join('; '))
+      }
+      const spec = repairGenuiSpec(input)
       if (spec === null) {
         return 'render_ui：spec 无效 —— 根对象需要 "items" 数组（组件树白名单见系统提示词），请修正后重试。'
       }
@@ -277,6 +285,12 @@ function bracketDiagnostic(raw: string): string {
 const COMMON_CAUSES =
   '常见原因：① 收尾括号错位/缺失（{ 与 }、[ 与 ] 数量不相等）② 字符串值内用了半角引号 "（中文引语请用 “” 或 「」）③ 尾随逗号 ④ 字符串未闭合'
 
+/** Return the model-facing chart field failure for one parsed fence body. */
+function chartValidationFailure(value: unknown): string | undefined {
+  const errors = validateRenderableChartSemantics(value)
+  return errors.length === 0 ? undefined : `❌ chart 字段验证失败：\n- ${errors.join('\n- ')}`
+}
+
 /** Build the validate_dsh_ui tool definition (registered alongside render_ui). */
 export function createValidateDshUiTool(): ToolDefinition {
   return {
@@ -304,11 +318,18 @@ export function createValidateDshUiTool(): ToolDefinition {
         // FIXED JSON instead of asking it to re-author the fix — re-writing
         // the whole fence by hand is where the next typo comes from.
         const repaired = completeFenceJson(raw)
-        if (repaired !== null && repairGenuiSpec(JSON.parse(repaired.text) as unknown) !== null) {
-          return `❌ dsh-ui 围栏 JSON 解析失败：${detail}。\n${bracketDiagnostic(raw)}  已自动修复 ${repaired.repairs} 处，下面是修复后的 JSON，直接作为围栏正文发出即可（无需再验证）：\n\`\`\`\n${repaired.text}\n\`\`\``
+        if (repaired !== null) {
+          const repairedValue = JSON.parse(repaired.text) as unknown
+          const chartFailure = chartValidationFailure(repairedValue)
+          if (chartFailure !== undefined) return chartFailure
+          if (repairGenuiSpec(repairedValue) !== null) {
+            return `❌ dsh-ui 围栏 JSON 解析失败：${detail}。\n${bracketDiagnostic(raw)}  已自动修复 ${repaired.repairs} 处，下面是修复后的 JSON，直接作为围栏正文发出即可（无需再验证）：\n\`\`\`\n${repaired.text}\n\`\`\``
+          }
         }
         return `❌ dsh-ui 围栏 JSON 解析失败：${detail}。\n${bracketDiagnostic(raw)}  自动修复未能恢复（结构损坏），请按错误信息修正后重新调用本工具验证，通过后再发出围栏。\n${COMMON_CAUSES}`
       }
+      const chartFailure = chartValidationFailure(parsed)
+      if (chartFailure !== undefined) return chartFailure
       const spec = repairGenuiSpec(parsed)
       if (spec === null) {
         return '❌ 不是合法 GenUI spec：根对象需要 "items" 数组，且每个节点 type 必须在白名单内（见系统提示词）。请修正后重新验证。'