@changfenhuang/dsh-genui 0.9.1

package/src/client/toolview.tsx

@@ -0,0 +1,66 @@
+/**
+ * The `render_ui` tool's card in the tool row. The host projected the
+ * repaired spec into the result's `meta` (the tool's `presentationMeta`);
+ * this keyed toolview reads it and renders through GenuiBlock — the same
+ * renderer the ```dsh-ui fence uses. Falls back to a compact summary row
+ * when the meta is missing or invalid (e.g. a replay of a log recorded
+ * before the projection existed).
+ *
+ * Every settled spec is ALSO published to the session panel store: the
+ * conversation dock re-renders the same panel block in place, so repeated
+ * render_ui calls update one surface instead of stacking tool-row cards.
+ */
+import { useEffect, useMemo } from 'react'
+import type {} from '@deepseek-ai/dsh-client-runtime/client'
+import type { ToolCallViewProps } from '@deepseek-ai/dsh-client-ui-tool/client'
+import { GenuiBlock } from './GenuiBlock.tsx'
+import { ErrorBoundary } from './ErrorBoundary.tsx'
+import { repairGenuiSpec } from './guard.ts'
+import { toolStateKey } from './interaction-store.ts'
+import { applyPanelOperation } from './panel-store.ts'
+import css from './GenuiBlock.module.css'
+
+/**
+ * Keyed toolview for the `render_ui` tool. `block` is the settled result
+ * node once the call completes; while it runs (or on replay without meta)
+ * the summary fallback is shown.
+ */
+export function GenuiToolView({ toolName, block, sessionId }: ToolCallViewProps) {
+  // `meta` exists only on the settled result node; running calls (and
+  // replayed logs without the projection) fall back to the summary row.
+  // Memoized so the publish effect only fires when the settled spec
+  // actually changes (same block → same object → no panel churn).
+  const meta = 'meta' in block ? block.meta : undefined
+  const spec = useMemo(() => (meta === undefined ? null : repairGenuiSpec(meta)), [meta])
+  useEffect(() => {
+    // Publish the settled spec to the session panel (dock) as a REPLACE op
+    // with the result block's call identity and message seq: the same block
+    // re-rendered (replay/refresh) is idempotent, and an older result can
+    // never clobber a newer panel fence (real ordering in the fold). Running
+    // calls publish nothing — the panel keeps its last content.
+    if (spec !== null && spec.items.length > 0) {
+      applyPanelOperation(sessionId, {
+        sourceId: JSON.stringify(['render_ui', block.callId]),
+        order: ['seq' in block && typeof block.seq === 'number' ? block.seq : 0, -1, 0],
+        mode: 'replace',
+        spec,
+      })
+    }
+  }, [sessionId, spec, block])
+  if (spec === null || spec.items.length === 0) {
+    return (
+      <div className={css.toolFallback} data-genui-tool>
+        <span className={css.toolFallbackTitle}>{toolName}</span>
+        <span className={css.toolFallbackMeta}>{block.callId}</span>
+      </div>
+    )
+  }
+  return (
+    <div className={css.tool} data-genui-tool>
+      <ErrorBoundary label="工具卡片">
+        {/* callId is stable across replay → tool-card interaction state is durable */}
+        <GenuiBlock spec={spec} stateKey={toolStateKey(sessionId, block.callId)} />
+      </ErrorBoundary>
+    </div>
+  )
+}

package/src/css-modules.d.ts

@@ -0,0 +1,5 @@
+/** CSS Modules: bundlers compile *.module.css to a hashed class map. */
+declare module '*.module.css' {
+  const classes: Record<string, string>
+  export default classes
+}

package/src/index.ts

@@ -0,0 +1,12 @@
+/**
+ * Bundle source entry (plugin_check tool-bundle contract): the node-half
+ * surface the host loader resolves through `package.json#main`.
+ *
+ * The `import type {}` line is NOT decorative: importing the dsh client
+ * runtime's cordis Context augmentation BEFORE re-exporting the plugin keeps
+ * TypeScript's global-augmentation ordering deterministic — without it,
+ * TS 5.9 mis-resolves `ctx.sessions` in the client half when the plugin
+ * module is first reached through this root entry.
+ */
+import type {} from '@deepseek-ai/dsh-client-runtime/client'
+export * from './plugin/index'

package/src/plugin/index.ts

@@ -0,0 +1,173 @@
+/**
+ * GenUI plugin: teaches the model the ```dsh-ui fence syntax for emitting
+ * declarative UI components inline in its reply. The browser half renders the
+ * fence through GenuiBlock (ui-primitives); this host half only tells the
+ * model the language exists, so a session without the plugin simply never
+ * emits fences and nothing changes.
+ *
+ * The section is a convention section (order 100-199), placed after the bash
+ * guidance so the model sees it among its output-format rules.
+ * @module @changfenhuang/dsh-genui
+ */
+
+import { Context } from '@deepseek-ai/cordis'
+import type {} from '@deepseek-ai/dsh-system-prompt'
+import type {} from '@deepseek-ai/dsh-tools'
+import type { IncomingMessage, ServerResponse } from 'node:http'
+import { readFile } from 'node:fs/promises'
+import { join } from 'node:path'
+import { fileURLToPath } from 'node:url'
+import { createRenderUiTool, createValidateDshUiTool } from './tool.ts'
+
+/** Convention: tool guidance uses 100–199; bash's section is 104. */
+export const GENUI_SECTION_ORDER = 105
+
+/* ---------------- lazy engine asset route ---------------- */
+
+/**
+ * The mermaid/three engines ship as standalone IIFE bundles under
+ * `lib/assets/` and are fetched by the client ONLY when a spec needs them.
+ * 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.
+ */
+
+/** Route prefix under /plugins; anything under it is this plugin's asset. */
+const ASSET_ROUTE_PATH = '/plugins/@changfenhuang/dsh-genui/assets'
+
+/** Safe flat file names only: no slashes, no traversal, js assets only. */
+const ASSET_FILE_RE = /^[A-Za-z0-9][A-Za-z0-9._-]*\.js$/
+
+/** The handler itself (registered via the optional webServer probe). */
+async function serveGenuiAsset(req: IncomingMessage, res: ServerResponse): Promise<void> {
+  if (req.method !== 'GET' && req.method !== 'HEAD') {
+    res.writeHead(405)
+    res.end()
+    return
+  }
+  let pathname: string
+  try {
+    pathname = decodeURIComponent(new URL(req.url ?? '/', 'http://x').pathname)
+  } catch {
+    res.writeHead(400)
+    res.end()
+    return
+  }
+  const rel = pathname.startsWith(`${ASSET_ROUTE_PATH}/`) ? pathname.slice(ASSET_ROUTE_PATH.length) : null
+  if (rel === null) {
+    res.writeHead(404)
+    res.end()
+    return
+  }
+  const file = rel.slice(1)
+  if (!ASSET_FILE_RE.test(file)) {
+    res.writeHead(404)
+    res.end()
+    return
+  }
+  try {
+    // lib/index.js → ./assets/ = <pkg>/lib/assets/ (the tsdown asset outDir).
+    const dir = fileURLToPath(new URL('./assets/', import.meta.url))
+    const body = await readFile(join(dir, file))
+    res.writeHead(200, {
+      'content-type': 'text/javascript; charset=utf-8',
+      'cache-control': 'no-cache',
+    })
+    res.end(body)
+  } catch {
+    // Missing asset (old build) — a loud 404; the client shows its fallback.
+    res.writeHead(404)
+    res.end()
+  }
+}
+
+/** The fence language description injected into every assembled system prompt.
+ *  Deliberately slim: the `genui` skill carries the full component→field
+ *  mapping; this section keeps only the contract that must always be
+ *  present (fence syntax, type whitelist, and critical behavioral rules). */
+export const GENUI_SECTION_TEXT = `You can render interactive UI components INSIDE your reply — between paragraphs — by emitting a fenced block with the language tag \`dsh-ui\` containing a JSON spec:
+
+\`\`\`dsh-ui
+{"title":"可选标题","gap":14,"items":[...]}
+\`\`\`
+
+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
+- 展示: 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 (函数图)
+- 交互: 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)
+
+Rules:
+- 触发: 结构化表达优于纯文本时主动用（要点、强调、对比、流程、步骤、状态、数据、演示），纯问答与一句话不套 UI；一个主题一个主组件，每次 3–8 个组件，同一数据不重复出现。
+- JSON 严格: 坏围栏降级为代码块；≥3 节点或含 table 的围栏发出前调用 validate_dsh_ui，❌ 修好再发（若附「已自动修复」JSON 照抄即可）。
+- 规模: ≤200 节点、嵌套≤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 全列），本地判分。
+- Secrets ban: 不索取密码、API Key、Token、恢复码；需要时拒绝并解释。
+- Tool channel: render_ui 工具把同一 spec 渲染为工具行卡片（交付物型界面用）；围栏用于回答内联 UI。
+- Panel: "panel":true 只渲染进会话面板 dock 并原地更新；"append":true 追加合并（同标签 tabs 追加/新标签加入/尾部追加）；上限 200 节点/200 次追加，满了发 replace 重建。面板组件来的 [genui-action] 只回一个 panel:true 围栏 + 至多一行 10 字内确认，不解释、不用普通围栏。`
+
+/**
+ * Register the GenUI output-language section and the render_ui tool.
+ * @param ctx - cordis context.
+ */
+// `tools` is intentionally NOT injected: the service is optional for this
+// plugin — hosts without tool access keep the fence channel working. Cordis
+// inject entries are hard requirements, so the registry is probed at runtime
+// instead (see apply).
+export const inject = ['systemPrompt']
+
+export function apply(ctx: Context): void {
+  ctx.systemPrompt.section({
+    name: 'genui:fence',
+    order: GENUI_SECTION_ORDER,
+    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 })
+  })
+
+  // 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 })
+  })
+}

package/src/plugin/invariant.ts

@@ -0,0 +1,30 @@
+/**
+ * Package-owned invariant companion for `@changfenhuang/dsh-genui`.
+ * @module @changfenhuang/dsh-genui/invariant
+ */
+
+/* jscpd:ignore-start */
+import type { Context } from '@deepseek-ai/cordis'
+import type { InvariantInstaller } from '@deepseek-ai/dsh-invariants'
+
+const PACKAGE_NAME = '@changfenhuang/dsh-genui'
+
+/** Cordis companion plugin name. */
+export const name = 'genui-invariant'
+/** Service required before the companion can reserve package ownership. */
+export const inject = ['invariants']
+
+/**
+ * No runtime invariant: this host plugin only registers a static prompt
+ * section; the section text is pinned by its own tests.
+ */
+const install: InvariantInstaller = () => {}
+
+/**
+ * Register this package's invariant companion.
+ * @param ctx - Cordis context carrying the invariant service.
+ * @returns the installed registration's disposer after setup succeeds.
+ */
+export const apply = (ctx: Context): Promise<() => void> =>
+  Promise.resolve(ctx.invariants.register(PACKAGE_NAME, install))
+/* jscpd:ignore-end */

package/src/plugin/node-shims.d.ts

@@ -0,0 +1,31 @@
+/**
+ * Minimal ambient declarations for the node: builtins the plugin node half
+ * uses (asset route: http/fs/path/url). The package compiles with
+ * `"types": []` and ships no @types/node devDependency, so these shims are
+ * the typecheck surface; tsdown bundles the real node modules at build time
+ * (platform: node). Declarations cover exactly the members in use.
+ * @module @changfenhuang/dsh-genui/plugin/node-shims
+ */
+
+declare module 'node:http' {
+  export interface IncomingMessage {
+    method?: string
+    url?: string
+  }
+  export interface ServerResponse {
+    writeHead(statusCode: number, headers?: Record<string, string>): ServerResponse
+    end(data?: string | Buffer): void
+  }
+}
+
+declare module 'node:fs/promises' {
+  export function readFile(path: string): Promise<Buffer>
+}
+
+declare module 'node:path' {
+  export function join(...paths: string[]): string
+}
+
+declare module 'node:url' {
+  export function fileURLToPath(url: URL): string
+}

package/src/plugin/tool.ts

@@ -0,0 +1,330 @@
+/**
+ * The `render_ui` tool: a model-facing channel that renders a GenUI spec as
+ * an interactive card in the conversation TOOL ROW (route A of the design
+ * doc). The ```dsh-ui fence channel renders inline in the reply; this tool
+ * renders in the tool row and rides the harness's result `meta` projection:
+ * `presentationMeta` stores the repaired spec, the browser toolview
+ * (`src/client/toolview.tsx`) reads it from the result node and renders.
+ *
+ * Zero runtime harness imports, deliberately: an external plugin's node half
+ * must not depend on the harness module graph at runtime (the profile
+ * resolves only the plugin package itself). The definition is therefore a
+ * plain `ToolDefinition` object — the exact shape `defineTool` returns — with
+ * the arguments schema authored as JSON Schema (the harness validates args
+ * and output with the same JSON Schema validator defineTool uses). Deep
+ * validation, deterministic repair, and resource limits live in the shared
+ * guard (`src/client/guard.ts`), which the schema deliberately stays loose
+ * enough to reach.
+ * @module @changfenhuang/dsh-genui/plugin/tool
+ */
+
+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 { completeFenceJson } from '../shared/fence-repair.ts'
+
+/**
+ * Arguments schema: an open `spec` slot. The schema must NOT reject anything
+ * the guard could repair — the model's component trees are imperfect by
+ * nature, and the guard heals them; argument validation would only strand
+ * them. `additionalProperties: false` keeps the call shape honest.
+ *
+ * `spec` IS typed `object` on purpose: the guard can only repair plain
+ * records (a serialized JSON string, array, or scalar root is unusable), so
+ * argument validation rejecting non-objects loses nothing repairable — and
+ * it stops the model from double-encoding the tree as a string (observed
+ * twice in the wild), failing fast with a clear schema error instead.
+ */
+const RENDER_UI_PARAMETERS: Record<string, unknown> = {
+  type: 'object',
+  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).',
+      // 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
+      // specs mid-stream). Declaring the known top-level fields gives the
+      // bridge a concrete shape to serialize directly, while the schema stays
+      // deliberately open (unknown keys tolerated, `items` elements are free
+      // objects) so the guard — not the schema — remains the repair authority.
+      properties: {
+        title: { type: 'string', description: 'Short title shown as the card banner.' },
+        gap: { type: 'number', description: 'Vertical gap between root items in px.' },
+        panel: { type: 'boolean', description: 'Panel-only: renders into the session panel dock instead of the message flow.' },
+        items: {
+          type: 'array',
+          description: 'Root component list (white-listed vocabulary).',
+          items: { type: 'object' },
+        },
+      },
+    },
+  },
+  required: ['spec'],
+  additionalProperties: false,
+}
+
+/** The tool's canonical value is a short model-facing summary string. */
+const RENDER_UI_OUTPUT_SCHEMA: JsonSchemaNode = { type: 'string', description: 'One-line human-readable render summary for the model.' }
+
+/**
+ * Read the `spec` argument defensively (presenters run on replayed args).
+ *
+ * The harness tool-call bridge has been observed to deliver arguments in
+ * shapes other than the authored `{ spec: <object> }`:
+ * - `{ spec: "<JSON string>" }` — spec serialized to text;
+ * - `{ arguments: "<JSON string>" }` / `{ arguments: <object> }` — a
+ *   double-encoded wrapper from the SDK tool-call bridge (seen live in the
+ *   web GUI: small specs arrived wrapped this way, large specs arrived with
+ *   their JSON corrupted mid-stream);
+ * - a bare JSON string (double-encoded root).
+ * Each shape is unwrapped here so the guard can repair the actual tree.
+ * Corrupted JSON cannot be recovered (bytes were lost in transit): it yields
+ * `undefined` plus a diagnostic log line for the transport-layer bug.
+ */
+function specOf(args: unknown): unknown {
+  if (typeof args === 'string') {
+    return parseSpecJson(args, 'bare-string')
+  }
+  if (typeof args !== 'object' || args === null) return undefined
+  const record = args as Record<string, unknown>
+  if ('spec' in record) {
+    const s = record.spec
+    if (typeof s === 'string') return parseSpecJson(s, 'spec-string')
+    return unwrapSpec(s, 'spec')
+  }
+  if ('arguments' in record) {
+    const a = record.arguments
+    if (typeof a === 'string') return parseSpecJson(a, 'arguments-string')
+    if (typeof a === 'object' && a !== null) return unwrapSpec(a, 'arguments')
+  }
+  return undefined
+}
+
+/**
+ * Peel nested `{ spec: ... }` wrapper layers. Observed bridge shapes nest the
+ * authored `spec` object one or more levels deep (e.g. the serialized text
+ * inside `{ arguments: "..." }` is itself `{ spec: { title, gap, items } }`),
+ * so unwrapping stops only at a value that carries no `spec` key.
+ */
+function unwrapSpec(value: unknown, shape: string): unknown {
+  if (typeof value === 'object' && value !== null) {
+    const record = value as Record<string, unknown>
+    if ('spec' in record) {
+      const s = record.spec
+      if (typeof s === 'string') return parseSpecJson(s, `${shape}/spec-string`)
+      return unwrapSpec(s, `${shape}/spec`)
+    }
+  }
+  return value
+}
+
+/** Try to decode a serialized spec; log a diagnostic when it is broken. */
+function parseSpecJson(raw: string, shape: string): unknown {
+  try {
+    return unwrapSpec(JSON.parse(raw), shape)
+  } catch (error: unknown) {
+    const detail = error instanceof Error ? error.message : String(error)
+    const pos = /position (\d+)/.exec(detail)?.[1] ?? '?'
+    console.error(`[genui-tool] spec wrapped as ${shape} but its JSON is broken (${raw.length} bytes, error at ${pos}); cannot recover — bytes lost in transit`)
+    return undefined
+  }
+}
+
+/** Total node count of a repaired spec — the shared guard traversal
+ * (`countGenuiNodes`) so the tool reports the SAME number the panel fold and
+ * validation use. A local walker used to under-count specs whose content
+ * lives inside tabs/accordion/file-tree (their children are not `.items`). */
+function countNodes(spec: GenuiSpec): number {
+  return countGenuiNodes(spec, GENUI_LIMITS.maxNodes)
+}
+
+/** Tool-call title shared by the pending and completed presentations. */
+function cardTitle(args: unknown): string | undefined {
+  const spec = repairGenuiSpec(specOf(args))
+  return spec === null ? undefined : `渲染 UI：${spec.title ?? '未命名'}`
+}
+
+/**
+ * Build the render_ui tool definition. Registered by the plugin node half;
+ * `ctx.tools.register` consumes it exactly like a `defineTool` result.
+ */
+export function createRenderUiTool(): ToolDefinition {
+  return {
+    name: 'render_ui',
+    description:
+      'Render an interactive UI card in the conversation tool row by passing a GenUI spec (a white-listed component tree; the same vocabulary as the ```dsh-ui fence, see the system prompt). '
+      + 'Use it when the user asks for a structured panel, dashboard, or form that belongs in the tool row rather than inline in the reply. '
+      + 'The card is interactive client-side (tabs, buttons, inputs, switches); components carrying an "action" field send [genui-action] back to you when the user interacts, and you should re-render the updated UI.',
+    parameters: RENDER_UI_PARAMETERS,
+    output: {
+      schema: RENDER_UI_OUTPUT_SCHEMA,
+      render(_args: unknown, value: JsonValue): ContentBlock[] {
+        return [{ type: 'text', text: String(value) }]
+      },
+      presentationMeta(args: unknown): JsonValue {
+        // The browser toolview reads the repaired spec from result meta. The
+        // spec is JSON-safe by construction (only string/number/boolean/array
+        // fields after repair), so the widening cast is lossless.
+        return repairGenuiSpec(specOf(args)) as unknown as JsonValue
+      },
+    },
+    async execute(args: unknown): Promise<JsonValue> {
+      const spec = repairGenuiSpec(specOf(args))
+      if (spec === null) {
+        return 'render_ui：spec 无效 —— 根对象需要 "items" 数组（组件树白名单见系统提示词），请修正后重试。'
+      }
+      const title = spec.title ?? '未命名'
+      return `已渲染 UI「${title}」（${countNodes(spec)} 个组件）。用户现在可以看到这张卡片；组件带 action 时，用户交互会以 [genui-action] 消息发回给你，届时请重新渲染更新后的界面。`
+    },
+    presentCall(args: unknown): GenericCallView | undefined {
+      const title = cardTitle(args)
+      return title === undefined ? undefined : { card: 'generic', title, kind: 'other' }
+    },
+    presentResult(args: unknown): GenericResultView | undefined {
+      const title = cardTitle(args)
+      return title === undefined ? undefined : { card: 'generic', title }
+    },
+  }
+}
+
+/**
+ * The `validate_dsh_ui` tool: a model-facing pre-flight check for the
+ * ```dsh-ui fence channel. The model calls it with the JSON text it is about
+ * to put inside a fence; it reports whether the body parses as a valid GenUI
+ * spec, and when it does not, WHERE it breaks and WHAT is likely wrong
+ * (bracket counts, common typo classes) so the model can fix and re-validate
+ * before emitting — turning "render a red banner after the fact" into
+ * "verify before you send". Purely local: no LLM, no network, no DOM.
+ */
+const VALIDATE_DESCRIPTION =
+  'Validate the JSON body of a ```dsh-ui fence BEFORE emitting it — use for non-trivial specs (≥3 nodes or containing a table); skip for trivial ones (≤2 nodes). '
+  + 'Pass the exact JSON text you are about to put inside the fence as the "spec" argument (a string). '
+  + 'Returns ✅ when it parses as a valid GenUI spec, or ❌ with the exact position, bracket counts, and likely causes when it does not — fix the JSON, re-validate, and only then emit the fence. '
+  + 'When the JSON is broken but repairable (unescaped quotes, trailing commas, missing closers), the ❌ reply INCLUDES the auto-repaired JSON — copy it verbatim into the fence instead of rewriting by hand.'
+
+const VALIDATE_PARAMETERS: Record<string, unknown> = {
+  type: 'object',
+  properties: {
+    spec: {
+      oneOf: [
+        { type: 'string', description: 'The exact JSON text of the fence body.' },
+        { type: 'object', description: 'The spec object (serialized before validation).' },
+      ],
+      description: 'The dsh-ui fence body to validate: pass the JSON as a string for an exact check, or as the spec object.',
+    },
+  },
+  required: ['spec'],
+  additionalProperties: false,
+}
+
+/** Read the fence-body text from the call args (string preferred, object serialized). */
+function fenceTextOf(args: unknown): string | null {
+  if (typeof args === 'string') return args
+  if (typeof args !== 'object' || args === null) return null
+  const record = args as Record<string, unknown>
+  const s = 'spec' in record ? record.spec : 'arguments' in record ? record.arguments : undefined
+  if (typeof s === 'string') return s
+  if (typeof s === 'object' && s !== null) return JSON.stringify(s)
+  return null
+}
+
+/** Count structural brackets outside string literals. */
+function bracketCounts(raw: string): { '{': number; '}': number; '[': number; ']': number } {
+  const counts = { '{': 0, '}': 0, '[': 0, ']': 0 }
+  let inString = false
+  let escaped = false
+  for (let i = 0; i < raw.length; i++) {
+    const ch = raw[i]!
+    if (escaped) {
+      escaped = false
+      continue
+    }
+    if (inString) {
+      if (ch === '\\') escaped = true
+      else if (ch === '"') inString = false
+      continue
+    }
+    if (ch === '"') {
+      inString = true
+      continue
+    }
+    if (ch === '{') counts['{'] += 1
+    else if (ch === '}') counts['}'] += 1
+    else if (ch === '[') counts['['] += 1
+    else if (ch === ']') counts[']'] += 1
+  }
+  return counts
+}
+
+/** Short structural hint from bracket counts (empty when balanced). */
+function bracketDiagnostic(raw: string): string {
+  const c = bracketCounts(raw)
+  const diffs: string[] = []
+  if (c['{'] !== c['}']) {
+    const d = c['{'] - c['}']
+    diffs.push(`{ ×${c['{']} / } ×${c['}']} → ${d > 0 ? `缺 ${d} 个 }` : `多 ${-d} 个 }`}`)
+  }
+  if (c['['] !== c[']']) {
+    const d = c['['] - c[']']
+    diffs.push(`[ ×${c['[']} / ] ×${c[']']} → ${d > 0 ? `缺 ${d} 个 ]` : `多 ${-d} 个 ]`}`)
+  }
+  return diffs.length === 0 ? '' : `  括号计数：${diffs.join('；')}（长表格最易在收尾处错位，如把 ]]}]} 写成 ]}]}]}）\n`
+}
+
+const COMMON_CAUSES =
+  '常见原因：① 收尾括号错位/缺失（{ 与 }、[ 与 ] 数量不相等）② 字符串值内用了半角引号 "（中文引语请用 “” 或 「」）③ 尾随逗号 ④ 字符串未闭合'
+
+/** Build the validate_dsh_ui tool definition (registered alongside render_ui). */
+export function createValidateDshUiTool(): ToolDefinition {
+  return {
+    name: 'validate_dsh_ui',
+    description: VALIDATE_DESCRIPTION,
+    parameters: VALIDATE_PARAMETERS,
+    output: {
+      schema: { type: 'string', description: 'Validation verdict for the model.' },
+      render(_args: unknown, value: JsonValue): ContentBlock[] {
+        return [{ type: 'text', text: String(value) }]
+      },
+    },
+    async execute(args: unknown): Promise<JsonValue> {
+      const raw = fenceTextOf(args)
+      if (raw === null || raw.trim() === '') {
+        return '❌ validate_dsh_ui：缺少 spec 参数 —— 把围栏 JSON 文本作为 spec 传入。'
+      }
+      let parsed: unknown
+      try {
+        parsed = JSON.parse(raw)
+      } catch (error: unknown) {
+        const detail = error instanceof Error ? error.message : String(error)
+        // Pre-emission, both repair tiers are safe (no streaming half exists
+        // in a validation call). When the repair succeeds, hand the model the
+        // 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\`\`\``
+        }
+        return `❌ dsh-ui 围栏 JSON 解析失败：${detail}。\n${bracketDiagnostic(raw)}  自动修复未能恢复（结构损坏），请按错误信息修正后重新调用本工具验证，通过后再发出围栏。\n${COMMON_CAUSES}`
+      }
+      const spec = repairGenuiSpec(parsed)
+      if (spec === null) {
+        return '❌ 不是合法 GenUI spec：根对象需要 "items" 数组，且每个节点 type 必须在白名单内（见系统提示词）。请修正后重新验证。'
+      }
+      const validCount = countNodes(spec)
+      const declaredCount = countDeclaredGenuiNodes(parsed, GENUI_LIMITS.maxNodes + 1)
+      if (declaredCount > validCount) {
+        return `❌ 验证未通过：检测到声明了 ${declaredCount} 个组件，但仅成功解析出 ${validCount} 个（有 ${declaredCount - validCount} 个组件因字段格式异常被丢弃）。常见原因：table 的 columns/rows 不是二维字符串数组、tabs 的 items/content 缺失、嵌套组件字段类型不符。请修正后重新验证。`
+      }
+      return `✅ dsh-ui spec 合法（${validCount} 个组件），可以发出围栏。`
+    },
+    presentCall(): GenericCallView | undefined {
+      return { card: 'generic', title: '验证 dsh-ui 围栏', kind: 'other' }
+    },
+    presentResult(): GenericResultView | undefined {
+      return { card: 'generic', title: '验证 dsh-ui 围栏' }
+    },
+  }
+}