前言¶

在 DSH 插件場景裏，模型經常需要輸出結構化的界面內容：圖表、KPI 卡片、表格、表單、儀表盤。如果只讓模型輸出文本或代碼，前端還得自己解析、渲染、處理交互；如果引入額外的嵌套模型調用，鏈路又會變長。

dsh-valuz-genui 的思路是：給模型提供一個 generate_ui 工具，讓模型自己生成 A2UI v0.9.1 文檔，瀏覽器在聊天內將其渲染爲交互式界面。下面介紹它的定位、能力、安裝方式、配置項和已知限制。

這是什麼¶

dsh-valuz-genui 是 valuz-ai 維護的 DeepSeek Harness 插件，許可證爲 MIT。它是一個 Web 客戶端插件，package.json 中聲明 dsh.client.platform 爲 web。

它的核心價值是：模型在一次模型回合中生成 UI，瀏覽器在聊天內渲染，並且不發起嵌套模型調用。它基於 valuz-genui core，使用 A2UI catalog、streaming sanitizer 和 React renderer。

核心能力¶

generate_ui 工具¶

插件給模型提供 generate_ui 工具，調用形式爲：

generate_ui(messages, title?)

其中：

• messages：模型書寫的 A2UI v0.9.1 消息對象數組。
• messages 中 createSurface 在前，隨後是 updateComponents / updateDataModel。
• 恰好一個組件的 id 爲 root。
• title 可選，用作短 surface 標題。

聊天內渲染¶

瀏覽器會在聊天內將 A2UI 文檔渲染爲交互式界面，包括：

• 圖表；
• KPI 卡片；
• 表格；
• 表單；
• 儀表盤。

渲染髮生在當前聊天上下文中，而不是額外頁面或外部面板。

流式生成¶

模型在書寫 generate_ui 參數時，瀏覽器會流式渲染已生成的部分。UI 作爲模型自身輸出即時出現，而不是一次性等待完整文檔結束後再顯示。

交互回傳¶

用戶在渲染界面上的點擊或提交，會作爲普通用戶消息返回給模型。模型可以根據這些交互繼續回答文本，或再次調用 generate_ui 生成更新後的界面。

校驗與重放¶

生成文檔會被校驗，然後持久化到 tool/result.meta。在 reload / replay 時，插件會根據該結果重新渲染 surface。

A2UI 文檔校驗會丟棄 schema-invalid components，而不是讓整個 surface 失敗。

Authoring guide¶

插件通過 system prompt 與 skill 向模型提供 authoring guide。

在支持 skills 的宿主中，完整目錄可以按需加載；如果沒有 skill 能力，或者配置了 alwaysOnFullGuide: true，完整目錄會保留在 system prompt 中。

安裝與啓用¶

基本安裝¶

要求：

Node.js >=22.19

將插件安裝到已經配置好模型的現有 profile：

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

npm 包攜帶預構建 lib/，無需構建步驟或 allowBuilds 條目。

基本使用無需額外配置。

安裝後驗證¶

安裝後，先重啓 dsh web，再對瀏覽器做 hard-refresh。然後讓模型生成一個圖表或儀表盤，用於確認 surface 能正常出現在聊天中。

固定未發佈 commit¶

如果需要固定一個未發佈 commit，可以改用 git 安裝：

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

如果 pnpm 版本 >=10，git 依賴的 prepare build 可能需要允許後才成功。

本地開發¶

本地開發時，可以這樣做：

git clone https://github.com/valuz-ai/dsh-valuz-genui.git
cd dsh-valuz-genui && pnpm install && pnpm run check
dsh plugin --profile web add /absolute/path/to/dsh-valuz-genui

之後按正常流程重啓 dsh web 並 hard-refresh。

配置¶

可以在 profile 的 cordis.patch.yml 中覆蓋以下配置項：

如果希望完整 authoring guide 始終出現在 system prompt 中，可以設置：

alwaysOnFullGuide: true

適用場景與注意¶

適合誰¶

這個插件適合希望模型在 DSH 聊天中直接產出可交互 UI 的場景，尤其是圖表、儀表盤、表單、表格這類需要用戶點擊或提交的界面。

安裝前注意¶

插件會以當前 dsh 進程權限運行。安裝前建議檢查源碼與許可證。當前已覈實資料中的許可證爲 MIT。

Authoring guide 成本¶

始終開啓的 authoring guide 有 prompt 成本。

如果沒有 skill 能力，或者設置了 alwaysOnFullGuide: true，完整目錄會保留在 system prompt 中。模型如果猜測字段，可能導致組件被丟棄。

客戶端 bundle¶

客戶端 bundle 較大，約 3.5 MB。

主題橋接¶

主題橋接較粗：未完整映射 A2UI --va2-* tokens 到 host --dsw-alias-* scale。

交互路徑¶

所有交互都通過模型往返，暫無 local-only handling。

PTC / Code Mode preset¶

在 PTC / Code Mode preset 下不會出現 surface。應使用 Standard preset，或 mode: both。

Session events¶

沒有 plugin-owned session events。臨時 surface state 不屬於 model-visible log。

宿主兼容性¶

peer ranges 開放，且 client bundle 手抄 dsh 模塊列表。未來宿主變更可能影響加載。

已覈實資料中的 peerDependencies 包括：

@deepseek-ai/cordis ^4.0.1
多個 @deepseek-ai/dsh-* 包 >=0.1.0-rc.5
React ^18.2.0 || ^19.0.0

完整 dependencies 清單未在本次已覈實資料中完整給出，安裝前仍建議查看倉庫中的 package.json。

鏈接¶

• GitHub：https://github.com/valuz-ai/dsh-valuz-genui
• 目錄頁：本次已覈實資料未提供目錄頁 URL。