生成式界面 valuz-ai/dsh-valuz-genui

dsh-valuz-genui

一个 DeepSeek Harness 插件，给模型提供 generate_ui 工具：由模型自己撰写 A2UI v0.9.1 文档并传给 generate_ui，浏览器把它渲染成聊天内联的交互式界面——图表、KPI 卡片、表格、表单、仪表盘——随模型书写调用而流式呈现，界面上的交互也会回传给模型。

这里没有嵌套的模型调用：界面就是模型自己流式输出的产物，所以能像围栏代码块一样实时出现，只消耗一轮模型调用，也不会因为第二个请求中途出错而失败。它构建在服务商无关的 valuz-genui 内核之上（76 个组件的 A2UI 目录、流式清洗器、React 渲染器）。

工作原理

- 撰写指南（系统提示词 + 技能）。 插件教模型撰写 A2UI，并通过调用 generate_ui 传入 messages（A2UI 消息对象数组）来交付。宿主支持技能时，一份精简指南（组件名 + 用途 + 消息契约）常驻，完整字段签名目录按需通过 genui 技能加载；否则完整指南留在系统提示词里。
- 流式渲染。 模型书写 generate_ui 参数时，每个 tool-call-delta 都会在工具运行之前作为临时的 assistant/live-chunk 抵达浏览器。以 generate_ui 调用 id 为键的会话节点会折叠这些增量，提取出目前已撰写的完整 A2UI 消息，并用 valuz 的 <A2UIRenderer> 渲染——尾部还在书写时，它会保留最后一个可用的界面。于是界面逐个组件地实时搭建起来。
- 落定 + 重放。 generate_ui 执行时（毫秒级——它只做校验，从不调用模型），会把规范文档持久化到 tool/result.meta。节点采用这份权威文档。实时块是进程本地的，模型尝试落定后就消失，所以落定之后以及重新加载时，节点会从持久的 tool/call 参数和 tool/result.meta 重建。
- 轮次结束。 轮次完成时，已落定的界面会在最终回复之后再次渲染，位于 dsh 折叠的进程视图之外，而进程内的副本收缩成一行引用。
- 交互。 在渲染出的界面上点击/提交，会作为普通用户消息回传给模型：<ui_action surface="…" component="…" name="…">{context}</ui_action>（模型可见 ⟺ 已记录）。模型用文本作答，或带着更新后的文档再次调用 generate_ui。

安装

兼容性

| 插件 | DeepSeek Harness |
| 0.2.x | 0.2.x（从 0.2.0-rc.2 起） |
| 0.1.x | 0.1.0-rc.6 到 0.1.1 |
dsh 0.2 替换了 0.1.x 使用的客户端 Conversation API，所以 0.1.x 在那里加载会失败，报 pending (waiting for service: conversationEvents)。dsh 会在安装和启动时检查插件声明的 peer 范围，所以不兼容的组合在加载前就会被拒绝。

装进一个已经配置好模型的现有配置档：

dsh plugin --profile web add @valuz/dsh-valuz-genui

npm 包自带预构建的 lib/，所以不需要构建步骤，也不需要 allowBuilds 条目。如果想固定到某个未发布的 commit，就从 git 安装 —— pnpm ≥ 10 会拦截 git 依赖的 prepare 构建，直到你放行；第一次 add 会失败，并打印出要复制进配置档 pnpm-workspace.yaml 的确切键名：

dsh plugin --profile web add github:valuz-ai/dsh-valuz-genui#<commit-sha>

allowBuilds:
'@valuz/dsh-valuz-genui@https://codeload.github.com/valuz-ai/dsh-valuz-genui/tar.gz/<commit-sha>': true

然后重启 dsh web 并强制刷新。让模型画个图表或仪表盘来验证。不需要额外配置 —— 模型用会话当前使用的任意模型来编写 UI。

本地开发

生成核心和渲染器来自 npm（@valuz/genui-core、@valuz/a2ui，出自 valuz-ai/valuz-genui）；客户端 bundle 在构建时把它们内联进去：

git clone https://github.com/valuz-ai/dsh-valuz-genui.git
cd dsh-valuz-genui && pnpm install && pnpm run check
install into a profile (rebuild lib/ first with pnpm run build)
dsh plugin --profile web add /absolute/path/to/dsh-valuz-genui

每次重新构建后都要重启 dsh web 并强制刷新。

工具

generate_ui(messages, title?)

- messages —— 模型编写的 A2UI v0.9.1 消息对象数组：先是 createSurface，然后是 updateComponents / updateDataModel；有且只有一个组件的 id 是 "root"。写成原生 JSON（不是字符串化的 blob），所以能干净地流式传输并校验。
- title —— 可选的简短 surface 标题。

工具会校验文档、固定 catalog id、丢弃 schema 非法的组件（同级组件保留），并把所有内容持久化到 tool/result.meta。模型会收到一行回执。

配置

在配置档的 cordis.patch.yml 里按 id 覆盖 valuz-genui 那一行：

| 键 | 默认值 | 含义 |
| maxDocumentBytes | 262144 | 序列化后 A2UI 文档的字节上限（含边界）。 |
| alwaysOnFullGuide | false | 把完整的字段签名 catalog 常驻在系统提示词里，而不是用按需加载的 genui 技能。 |

已知限制与待办工作

- 在已完成的回合中的位置。 dsh 会把已完成回合的过程（技能加载、推理、工具调用）折叠进一个「Completed in Ns」折叠区。因此插件会在回合末尾、最终回复之后，通过 dsh 的 conversation.chat.turnTail 插槽展示已完成回合中已定稿的界面，并把过程里的每个界面替换成一行引用。标题相同的后续界面算作修订，所以回合末尾只出现最新的那个；标题不同的界面都会出现。从未定稿的界面（比如被中断的调用）留在过程里。
- 常驻提示词开销。 宿主支持技能时（ctx.skills，例如 web 配置档），只有一份精简指南常驻（约 3.1k token：组件名 + 一行用途 + 消息契约），完整的字段签名目录（约 9k token）通过 genui 技能按需加载。没有技能能力时（或 alwaysOnFullGuide: true），完整指南留在系统提示词里。两者都是稳定前缀（对 KV 缓存友好）。模型会被告知在编写前先加载 genui 技能；靠猜字段会丢组件。
- 编写质量取决于模型。 A2UI 的 76 组件图比紧凑 DSL 更丰富，也更难内联编写。复杂仪表盘可能需要调提示词；清洗器会容忍并丢弃格式错误的组件，而不是让整个界面失败。
- 客户端包很大（约 3.5 MB）。 recharts、A2UI 渲染器和 markdown-it 都内联了。阶段 2 会把图表引擎拆成按需加载、由插件提供的资源。
- 主题桥接比较粗糙。 渲染器跟随浅色/深色，但还没有把 A2UI 的 --va2- token 映射到宿主的 --dsw-alias- 色阶上。核心语义 token（背景、文字、边框、强调色）可以通过注册的 a2ui 主题扩展映射；图表调色板在 JS 里，需要渲染器支持。
- 交互要经模型往返。 每个 <ui_action> 都会变成一条用户消息；目前还没有纯本地处理。
- PTC（Code Mode）预设下没有界面。 用 tool-presentation: mode: code 时，模型只能调用 run_code；generate_ui 在程序内部运行，所以模型流式输出的是 TypeScript 而不是 messages（没有实时渲染），嵌套结果记成 tool/ptc-dispatch —— 它带 content 但不带 meta —— 于是已定稿的界面也不会出现；只有 run_code 的文本回执会。用 Standard 预设，或者复制一份预设改成 mode: both，这样 generate_ui 仍能直接调用。要在 code 下渲染，需要这个节点匹配 tool/ptc-dispatch，并且 dsh 在该事件上带上 presentationMeta。
- 没有插件自有的会话事件。 所有持久化的内容都走平台事件（tool/call 对应发起的调用，user/message 对应操作，tool/result.meta 对应落定的文档），这对模型驱动的循环来说已经够用。临时的界面状态（表单草稿、标签页选择）对模型不可见，应该放在客户端存储里，而不是日志里。只有某次界面更新不产生任何工具调用时（实时数据、宿主推送的面板），才需要插件事件，而 dsh 的 Session.append 无法把事件标记为 ignorable，dsh 也拒绝为第三方插件注册事件类型。
- 宿主契约加固。 客户端 bundle 手工镜像了 dsh 的平台模块列表（packages/client/web/src/platform.ts 里的 PLATFORM_MODULES），所以宿主一旦改动它，就可能破坏加载。dsh 的 peer 版本范围被限制在一个 minor 线上（>=0.2.0-rc.2 <0.3.0），所以 dsh 每发一个新 minor，插件就得跟着发版。计划：在 CI 里对最新的 dsh 发行版跑 check，并加一个录制会话回放快照，把流式节点端到端钉住。

License

MIT