dsh-genui

为 DeepSeek Harness (DSH) 赋予原生交互式界面
文字回答依旧完整，富交互组件即刻上线。

English · 简体中文

🌐 在线产品站 · 🎬 界面演示 · 🚀 快速开始 · 🧩 核心特性 · 📖 组件语法 (SKILL.md)

dsh-genui 将大模型的文本回答无缝升级为安全、可交互的原生 DSH 界面。

例如当你询问「这个月订单表现如何？」，模型给出的回答不再只是一串文字，而是边打字边在正文中展开一张可排序的数据面板、一段内嵌音视频、一个可拖拽调参的函数图像、一组即时判卷的测验，或是一个常驻的会话工作区——文本与 UI 和谐共存，浑然一体。

🎬 真实界面预览

[!NOTE] 真实截图与录屏： 以下界面素材均直接截取自 DSH 真实对话环境中的渲染结果，无任何概念样机或预渲染伪造。

40 秒完整体验

回答中的三类典型输出

1. 监控面板：回答即仪表盘	2. 探索绘图：本地即时重绘	3. 结构排版：构建工作界面
数据洞察： 指标卡（Eyebrow）、可筛选可钻取的服务表、分组合计与 Spark/Ring 单元格直接内嵌在回答中。	即时交互： plot 绘制数学曲线；拖动参数滑块在浏览器端实时重绘，零模型往返延迟。	层级工作区： 标题引言、指标卡片、环形进度与章节分隔线，由模型声明式灵活编排。

✨ 对比：装之前 vs 装之后

🚀 快速开始

1. 环境准备

安装前请确认满足以下条件：

• DSH 版本：^0.2.0-rc.1 || ^0.2.1-rc.1（已在 dsh-v0.2.0-rc.1 与 dsh-v0.2.1-rc.2 上深度验证）
• pnpm 处于 PATH 中：dsh plugin 底层依赖 pnpm。如尚未安装，请执行 corepack enable 或 npm i -g pnpm，之后重新打开终端，确认 pnpm -v 可正常输出。

2. 一键安装与激活

在终端中执行以下命令（一键全自动拉取依赖）：

# 安装并激活至 DSH web profile（公开包，无需登录 npm）
dsh plugin --profile web add @changfenhuang/dsh-genui

[!TIP] 仅作为依赖引入？ 若仅作为 Node 项目依赖引入而不注入 DSH 宿主，执行 npm install @changfenhuang/dsh-genui 即可。

3. 60 秒验证

1. 重启 DSH web 服务，并在浏览器中执行硬刷新（Cmd + Shift + R 或 Ctrl + F5）。
2. 在 DSH 中开启一个新会话，发送以下指令：

   用 dsh-ui 画一个带可排序服务表的统计看板。
   

3. 预期效果：回答中的代码块将实时转变为精美的交互式仪表盘，而非原样文本。
4. 控制台激活检测：打开浏览器开发者工具 Console，若看到输出 [genui] client active; fence-channel=dom，说明客户端已成功激活。

[!WARNING]

⚠️ 安装避坑指南

1. 认准包名 Scope（极为关键）： 必须安装 @changfenhuang/dsh-genui。npm 上存在一个同名但无 Scope 的 dsh-genui（由其他维护者基于 Vue/OpenTiny 开发，与本插件完全不兼容），如不慎安装会被 DSH 宿主因 peer 依赖冲突拒绝。
2. 切勿使用 link: 安装刚 git clone 的目录： 纯 link: 不会自动安装 Mermaid、Three.js、React 等对等依赖，导致前端渲染报错。日常使用请走 npm 安装；仅本地源码开发时才使用 link（见开发者指南）。
3. 从旧包名 @omdsh-dev 迁移： 若在 v0.9.2 之前使用过 GitHub 源或旧组织名安装，请执行：

   dsh plugin --profile web remove @omdsh-dev/dsh-genui
   dsh plugin --profile web add @changfenhuang/dsh-genui
   

🧩 核心能力全景

dsh-genui 的所有组件与交互受严格的白名单规范约束，兼顾丰富表现力与高安全性。完整字段定义见 SKILL.md。

dsh-genui 核心能力矩阵
├── 🌊 1. 边流边渲染 (Streaming UI)
├── 🎨 2. 30+ 丰富组件生态 (Components Matrix)
├── ⚡ 3. 本地优先即时交互 (Local-First Experience)
├── 🔄 4. 闭环事件回传系统 (Action Event-Loop)
├── 📌 5. 常驻会话工作台 (Session Panel & Templates)
└── 🛡️ 6. 安全沙箱与容错自愈 (Safety & Self-Healing)

1. 🌊 边流边渲染 (Streaming UI)

• 回答即界面：组件内嵌在回复正文中，跟随模型 Token 流式吐出，边生成边即时挂载，无需等待整段回复输出完毕。
• 零破坏降级：若未安装或禁用插件，dsh-ui 围栏将退回为优雅的 Markdown 代码块，绝不破坏会话内容。

2. 🎨 30+ 丰富组件生态 (Components Matrix)

• 展示与排版：包含指标卡（stat，支持 Hero 超大字号与微趋势线 Sparkline）、表格（table）、时间线（timeline）、代码对比（diff）、步骤条（steps）、文件树（file-tree，支持点击展开折叠）、提示卡（callout）、徽章（badge）等。
• 高级表格：
  • 点击表头纯本地排序（升序/降序/还原，支持千分位、百分比、货币及万/亿数值感知）；
  • 单元格支持 bar 进度条、ring 环形、spark 趋势线，带正负符号数值自动着色；
  • 一键支持数据导出（复制 Markdown / CSV）与即时文本过滤（Filter）。
• ECharts 深度集成 (echart)：
  • 预设简写模式（preset）：支持 bar、line、area、pie、scatter、radar、gauge、funnel、treemap、sankey、graph、heatmap、bigline、wordCloud 等数十种图形，配色自动匹配 DSH 主题；
  • 完整配置模式（option）：支持原生 ECharts 选项，轻松开启 DataZoom、VisualMap 等高级特性；
  • 按需异步加载：ECharts 引擎（~1MB）独立打包，未调用图表组件的会话绝不加载多余代码。
• 数学函数绘图 (plot)：
  • 支持多曲线绘制（line / area / scatter），公式支持三角函数、对数、幂运算等；
  • 动态参数滑块：拖动滑块前端毫秒级重绘，锁定 Y 轴，支持自动动画循环演示。
• Mermaid & 3D 场景：支持流程图、序列图及轻量 3D 模型渲染，引擎按需异步加载。
• 原生多媒体：支持浏览器可直达的音频（audio）与视频（video）嵌入播放，包含封面图、比例自适应及播放控制。
• 数学公式集成：基于 KaTeX，支持行内公式 $...$、块级公式 $$...$$，支持矩阵与多行推导。

3. ⚡ 本地优先即时交互 (Local-First Experience)

• 本地优先原则：前端界面能够独立完成的操作（表格排序、过滤、内容展开/收起、标签切换、参数重绘、测验判题），一律在浏览器本地即时完成，绝不进行不必要的模型往返。
• 测验与本地判卷 (quiz / submit)：
  • 单题测验点击即在本地判题、展示解析并支持重试；
  • 多题问卷/表单可通过 submit 统一交卷，支持 groups 必填项控制与进度感知。
• 状态持久化：表单输入、单选多选与测验进度基于「会话 + 内容指纹」自动存入缓存（LRU 200 块），刷新页面或重开会话无缝恢复。

4. 🔄 闭环事件回传系统 (Action Event-Loop)

• 真实动作闭环：当按钮或表单带上 action 字段时，用户的点击或提交会即时组装为结构化事件回传给大模型，触发下一轮智能分析。
• 诚实交互设计：未声明 action 的按钮自动渲染为禁用态，杜绝“看起来可点但无反应”的假交互；点击有效按钮触发即刻给予视觉反馈。
• 智能防抖：按钮与切换项单次手势单次发送，连续滑块拖动自动开启尾沿防抖，仅回传最终停顿值。

5. 📌 常驻会话工作台 (Session Panel & Templates)

• 常驻 Dock 面板：支持通过 /panel 指令或 panel: true 将 UI 固化在输入框上方；支持鼠标拖拽边框调整高度；支持 append: true 增量追加标签页。
• 模板中心与成就系统：
  • 模板中心：点击 Dock 顶部的「模板」即可预览 11 类典型业务场景模板，一键插词唤起模型；
  • 探索成就：内置 12 项探索趣味成就，本地计数记录使用足迹。

6. 🛡️ 安全沙箱与容错自愈 (Safety & Self-Healing)

• 严格安全防线：所有组件严格受白名单结构约束，杜绝一切外部代码注入与 eval 执行；严禁索取与收集密码、API Key 等任何敏感凭据，密码类输入强制打码且绝不持久化。
• 同回合轮内自修 (Fence Steer Repair)：若模型生成的 dsh-ui 围栏存在格式缺陷，插件自动捕获错误并在同一回合内将精确节点诊断反馈给模型，触发自主纠正与重发（可配置 fenceFeedback: false 关闭）。
• 节点级自愈降级：单个语法异常节点被静默舍弃，同级其他正常组件继续完好渲染，绝不因个别节点错误拖垮整屏界面；Mermaid 常见语法缺陷自动修复重试。

💻 快速示例

示例 1：核心业务指标看板

模型在正文中输出以下 dsh-ui 围栏（规范化 JSON）：

{
  "title": "2026 Q3 业务运行概览",
  "items": [
    {
      "type": "row",
      "items": [
        { "type": "stat", "label": "总营收", "value": "¥128,430", "delta": "+12.4%", "spark": [40, 55, 60, 85, 120] },
        { "type": "stat", "label": "支付订单数", "value": "1,024", "delta": "-3.1%", "spark": [90, 85, 80, 75, 70] },
        { "type": "progress", "label": "季度目标完成率", "value": 82, "variant": "ring" }
      ]
    }
  ]
}

示例 2：ECharts 丰富折线与柱状图

{
  "title": "月度营收走势分析",
  "items": [
    {
      "type": "echart",
      "title": "2026 上半年走势",
      "preset": "bar",
      "data": [
        { "label": "1月", "value": 98 },
        { "label": "2月", "value": 112 },
        { "label": "3月", "value": 128 },
        { "label": "4月", "value": 145 },
        { "label": "5月", "value": 160 }
      ]
    }
  ]
}

更多高级组件（函数绘图、表格排序过滤、测验表单等）的完整协议规范，请参阅 SKILL.md。

⚙️ 架构与运行机制

sequenceDiagram
    autonumber
    actor User as 用户
    participant Host as DSH 宿主 / 大模型
    participant DOM as DSH 对话 DOM
    participant GenUI as GenUI 客户端渲染器
    participant Assets as 动态资产服务 (ECharts/Three)

    User->>Host: 提问（例如："分析近期订单趋势"）
    Host-->>DOM: 流式输出 Markdown 正文与 ```dsh-ui 围栏
    DOM->>GenUI: 捕获围栏节点并进行白名单结构规范化
    alt 依赖重型图表引擎
        GenUI->>Assets: 动态按需加载引擎脚本
        Assets-->>GenUI: 注入完成
    end
    GenUI->>DOM: 原地挂载独立 React 组件树，实时流式上屏
    opt 本地即时交互
        User->>GenUI: 点击表单排序 / 拖动函数滑块 / 答题判卷
        GenUI-->>User: 毫秒级即时前端重绘与状态持久化
    end
    opt 触发闭环 Action
        User->>GenUI: 点击触发模型交互的按钮
        GenUI->>Host: 回传结构化 Action 数据流
        Host-->>DOM: 模型响应下一轮分析或更新常驻 Panel
    end

成果导出能力

对渲染完成的 GenUI 内容，支持点击菜单导出为：

• 独立 .html：内嵌渲染核心、样式、KaTeX 字体及所用图表引擎，脱离 DSH 也能在任意浏览器中离线打开与交互。
• .genui.json：完整保存规范化后的 Spec 结构与持久化交互状态。

🧑‍💻 开发者指南

本地开发联调（Link 模式）

git clone https://github.com/omdsh-dev/dsh-genui.git
cd dsh-genui
pnpm install

# 本地联调构建并软链至 DSH
dsh plugin --profile web add link:$PWD

常用命令

pnpm run check           # 类型检查 + 单元测试 + 构建
pnpm run test            # 运行 Vitest 测试套件
pnpm run check:host-api dsh-v0.2.1-rc.2  # 检查当前发布版 DSH 的公开接口
node scripts/verify-pack.mjs --keep  # 生成并打包校验 tarball

端到端 E2E 验证

• 视觉回归 E2E（无需模型 API Key）：

  npx tsx scripts/e2e-visual.mts          # 生成全量组件截图与交互验证断言
  

• 真机闭环 E2E（调用模型真实响应）：

  export DSH_ROOT=/path/to/deepseek-harness-0.2.1-rc.2
  export DSH_BIN="$DSH_ROOT/apps/cli/lib/bin.js"
  DEEPSEEK_API_KEY=sk-... node scripts/e2e.mjs
  

进阶配置项

若需自定义插件行为，可在用户 profile 的 cordis.patch.yml 中调整：

- id: genui
  name: '@changfenhuang/dsh-genui'
  config:
    renderUiTool: false   # 关闭额外注入的 render_ui 工具调用，仅保留正文 dsh-ui 围栏与 panel
    fenceFeedback: false  # 关闭模型生成失败时的同回合自动 steer 纠错

❓ 常见问题排查 (FAQ)

dsh plugin --profile web remove @changfenhuang/dsh-genui
dsh plugin --profile web add @changfenhuang/dsh-genui

🗺️ 路线图评估 (Roadmap)

🔗 链接与致谢

• Linux.do 社区讨论
• 欢迎访问 在线产品站 体验更多特性

📄 开源许可

本项目遵循 MIT License 开源协议。