valuz-ai/dsh-valuz-genui

dsh-valuz-genui

一个 DeepSeek Harness 插件，为模型提供 generate_ui 工具：模型自身编写一份 A2UI v0.9.1 文档并将其传给 generate_ui，浏览器将其渲染为聊天内联的交互式界面——图表、KPI 卡片、表格、表单、仪表盘——在模型写出调用的同时流式呈现，其交互结果会回传给模型。

这里没有嵌套的模型调用：UI 就是模型自身流式输出的产物，因此它会实时出现（如同一个围栏代码块），只消耗一个模型回合，也不会因第二个请求的中途错误而失败。它构建于与提供商无关的 valuz-genui 核心之上（76 组件的 A2UI 目录、流式净化器、React 渲染器）。

工作原理

- 编写指南（系统提示词 + 技能）。 插件教会模型编写 A2UI，并通过调用 generate_ui 并传入 messages（A2UI 消息对象数组）来交付。当宿主支持技能时，一份精简指南（组件名称 + 用途 + 消息契约）始终开启，完整的字段签名目录则通过 genui 技能按需加载；否则完整指南会保留在系统提示词中。
- 流式渲染。 当模型写出 generate_ui 参数时，每个 tool-call-delta 都会在工具运行之前作为 assistant/chunk 到达浏览器。一个对话节点会折叠这些增量，提取出目前已编写的完整 A2UI 消息，并用 valuz 的  渲染它们——在尾部仍在编写时，它会保留最后一个完好的界面。因此界面会逐组件地实时构建起来。
- 落定 + 重放。 当 generate_ui 执行时（只需毫秒——它仅做校验，从不调用模型），它会将规范文档持久化到 tool/result.meta。该节点采用这份权威文档，而同一份 meta 会在重新加载/重放时重新渲染界面。
- 交互。 在已渲染界面上的点击/提交会作为一条普通用户消息回传给模型：{context}（模型可见 ⟺ 已记录）。模型以文本作答，或再次调用 generate_ui 并传入更新后的文档。

安装

安装到一个已配置好模型的现有 profile 中：

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

该 npm 包自带预构建的 lib/，因此无需构建步骤，也无需 allowBuilds 条目。若要改为固定到某个未发布的提交，请从 git 安装——此时 pnpm ≥ 10 会阻止该 git 依赖的 prepare 构建，直到你允许它为止；首次 add 会失败，并打印出要复制到该 profile 的 pnpm-workspace.yaml 中的确切键名：

dsh plugin --profile web add github:valuz-ai/dsh-valuz-genui#

allowBuilds:
'@valuz/dsh-valuz-genui@https://codeload.github.com/valuz-ai/dsh-valuz-genui/tar.gz/': 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。模型会收到一行回执。

配置

在你的 profile 的 cordis.patch.yml 中按 id 覆盖 valuz-genui 行：

| 键 | 默认值 | 含义 |
|---|---|---|
| maxDocumentBytes | 262144 | 序列化后 A2UI 文档的字节数上限（含）。 |
| alwaysOnFullGuide | false | 将完整的字段签名目录保留在系统提示中，而非按需加载 genui 技能。 |

已知限制与待办工作

- 常驻提示成本。 在宿主支持技能的情况下（ctx.skills，例如 web profile），只有一份精简指南（约 3.1k tokens：组件名称 + 一行用途 + 消息契约）始终常驻，而完整的字段签名目录（约 9k tokens）通过 genui 技能按需加载。在不存在技能能力的情况下（或 alwaysOnFullGuide: true 时），完整指南会保留在系统提示中。两者都是稳定的前缀（对 KV 缓存友好）。模型会被要求在编写前加载 genui 技能；猜测字段会导致组件被丢弃。
- 编写质量取决于模型。 A2UI 的 76 组件图比紧凑的 DSL 更丰富——也更难内联编写。复杂的仪表盘可能需要提示调优；sanitizer 会容忍并丢弃格式错误的组件，而不是让整个 surface 失败。
- 客户端 bundle 很大（约 3.5 MB）。 recharts、A2UI 渲染器和 markdown-it 都被内联。第二阶段会将图表引擎拆分为一个由插件提供的懒加载资源。
- 主题桥接较为粗糙。 渲染器会跟随浅色/深色模式，但尚未将 A2UI 的 --va2- token 映射到宿主的 --dsw-alias- 尺度上。核心语义 token（背景、文本、边框、强调色）可以通过注册的 a2ui 主题扩展进行映射；图表调色板位于 JS 中，需要渲染器支持。
- 交互通过模型往返。 每个  都会变成一条用户消息；目前还没有仅限本地的处理方式。
- 在 PTC（Code Mode）预设下没有 surface。 当 tool-presentation: mode: code 时，模型只能调用 run_code；generate_ui 从程序内部运行，因此模型流式输出的是 TypeScript 而不是 messages（没有实时渲染），并且嵌套结果被记录为 tool/code-dispatch——它携带 content 但不携带 meta——因此已结算的 surface 也永远不会出现；只有 run_code 的文本回执会出现。请使用 Standard 预设，或复制一个 mode: both 的预设，这样 generate_ui 仍然可以被直接调用。在 code 下渲染需要此节点匹配 tool/code-dispatch，并且 dsh 在该事件上携带 presentationMeta。
- 没有插件拥有的会话事件。 所有被持久化的内容都通过平台事件进行（流式调用使用 assistant/chunk，操作使用 user/message，已结算文档使用 tool/result.meta），这对于模型驱动的循环来说已经足够。临时 surface 状态（表单草稿、标签页选择）对模型不可见，应属于客户端存储，而不是日志。只有没有任何工具调用产生的 surface 更新（实时数据、宿主推送的面板）才需要插件事件，而 dsh 的 Session.append 目前无法将事件标记为 ignorable（第三方事件类型所必需）；当此类用例出现时，向上游提出该建议。
- 宿主契约加固。 客户端 bundle 手工复制了 dsh 的平台外部模块列表，并且 dsh 的 peer 范围是开放式的（>=0.1.0-rc.5）；未来更改其中任一内容的宿主可能会在加载时出错，而不会在安装时报错。计划：在 CI 中针对最新的 dsh 版本运行 check，在 dsh 发布稳定版本线后限制 peer 范围，并添加一个录制会话回放快照，将流式节点端到端固定下来。

许可证

MIT