为 DeepSeek Harness (DSH) 赋予原生交互式界面
文字回答依旧完整，富交互组件即刻上线。
English · 简体中文
🌐 在线产品站 ·
🎬 界面演示 ·
🚀 快速开始 ·
🧩 核心特性 ·
📖 组件语法 (SKILL.md)
dsh-genui 将大模型的文本回答无缝升级为安全、可交互的原生 DSH 界面。
例如当你询问「这个月订单表现如何？」，模型给出的回答不再只是一串文字，而是边打字边在正文中展开一张可排序的数据面板、一段内嵌音视频、一个可拖拽调参的函数图像、一组即时判卷的测验，或是一个常驻的会话工作区——文本与 UI 和谐共存，浑然一体。
> [!IMPORTANT]
> 本仓库是 @changfenhuang/dsh-genui 0.14.0 的 fork（包名保持不变，可原位替换上游），版本 0.14.0-fork.3。相对上游：图示引擎替换为 pele（1.02 MB，较 mermaid −70%，CSS 变量实时跟主题，白名单加 mindmap/timeline），并新增能力——chart 的 kind:"area"、input 原生 date/datetime-local/time/number 类型与 min/max/step 约束、table 自动分页（pageSize，行上限提至 200），以及上游 Computed 计算字段（输入驱动的本地响应式重算，取自上游 0.15.0 修复线）。完整记录见 FORK.md 与 CHANGELOG。本 fork 未发布到 npm——下方「快速开始」区分了上游 npm 安装与本 fork 的源码构建安装。
🎬 真实界面预览
> [!NOTE]
> 真实截图与录屏： 以下界面素材均直接截取自 DSH 真实对话环境中的渲染结果，无任何概念样机或预渲染伪造。演示素材沿用上游仓库——fork 完整继承这里展示的整套组件面，仅图示引擎不同（pele 替换 mermaid）。
40 秒完整体验
https://github.com/user-attachments/assets/f5db33ec-7471-4d4a-a85b-79c9962ab4ef
（若 GitHub 视频播放器加载较慢，点击封面即可直接下载查看 原始 MP4；四幕测试提示词详见 demo-prompts.md）
回答中的三类典型输出
| 1. 监控面板：回答即仪表盘 | 2. 探索绘图：本地即时重绘 | 3. 结构排版：构建工作界面 |
|---|---|---|
| 数据洞察： 指标卡（Eyebrow）、可筛选可钻取的服务表、分组合计与 Spark/Ring 单元格直接内嵌在回答中。 | 即时交互： plot 绘制数学曲线；拖动参数滑块在浏览器端实时重绘，零模型往返延迟。 |
层级工作区： 标题引言、指标卡片、环形进度与章节分隔线，由模型声明式灵活编排。 |
✨ 对比：装之前 vs 装之后
| 场景 | 传统纯文本回答 | 安装 dsh-genui 之后 |
|---|---|---|
| 业务监控 | “本月收入 ¥128,430，环比 +12.4%，转化率稍有下滑……” | 一行文字分析 + 紧贴正文的收入/订单/转化率指标卡、动态趋势图与进度条。 |
| 数据筛选 | 必须再发送一段提问要求模型重新生成表格。 | 表格自带本地点击排序与实时过滤框，无需重新请求模型。 |
| 深入探索 | 想要调整参数看趋势，必须反复调用模型对话。 | 拖动参数滑块，函数曲线在前端毫秒级重绘，带播放动画演示。 |
| 后续操作 | 复制文本自己另找工具处理。 | 面板自带「刷新」「切换视图」按钮，点击通过 Action 闭环驱动模型执行下一步。 |
🚀 快速开始
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. 安装与激活
按需求二选一：
方式 A —— npm 安装上游市场版（稳定版本，不含本 fork 的增量：pele 引擎、area 图、表格自动分页、Computed 计算字段等）：
# 安装并激活至 DSH web profile（公开包，无需登录 npm）
dsh plugin --profile web add @changfenhuang/dsh-genui
> [!TIP]
> 仅作为依赖引入？ 若仅作为 Node 项目依赖引入而不注入 DSH 宿主，执行 npm install @changfenhuang/dsh-genui 即可。
方式 B —— 源码构建本 fork（即本仓库；未发布 npm——lib/ 不入库，必须先构建；细节见 FORK.md）：
git clone https://github.com/Asaiuta/dsh-genui-enhanced.git
cd dsh-genui-enhanced
pnpm install # 提示时放行 esbuild 的构建脚本
# 构建门禁（pnpm 11 的坑见 FORK.md）
./node_modules/.bin/tsc -p tsconfig.json # 类型检查——要求零错误
./node_modules/.bin/tsdown # 产出 lib/（client.js、index.js、assets/*）
dsh plugin --profile web add link:$PWD
3. 60 秒验证
- 重启 DSH web 服务，并在浏览器中执行硬刷新（
Cmd + Shift + R或Ctrl + F5）。 - 在 DSH 中开启一个新会话，发送以下指令：
用 dsh-ui 画一个带可排序服务表的统计看板。
- 预期效果：回答中的代码块将实时转变为精美的交互式仪表盘，而非原样文本。
- 控制台激活检测：打开浏览器开发者工具 Console，若看到输出
[genui] client active; fence-channel=dom，说明客户端已成功激活。
> [!WARNING]
> ### ⚠️ 安装避坑指南
>
> 1. 认准包名 Scope（极为关键）：
> 必须安装 @changfenhuang/dsh-genui。npm 上存在一个同名但无 Scope 的 dsh-genui（由其他维护者基于 Vue/OpenTiny 开发，与本插件完全不兼容），如不慎安装会被 DSH 宿主因 peer 依赖冲突拒绝。
> 2. 切勿对未构建的目录使用 link:：
> 纯 link: 不会自动安装图示引擎、Three.js、React 等对等依赖——先 pnpm install 并跑完构建门禁、确保 lib/ 存在后再 link（即上文方式 B）。日常安装上游市场版请走 npm（方式 A）。
> 3. 从旧包名 @omdsh-dev 迁移：
> 若在 v0.9.2 之前使用过 GitHub 源或旧组织名安装，请执行：
> sh
> 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）；
- 自动分页（fork.2）：超过 15 行的表格本地翻页；
pageSize可覆盖每页行数，合计与导出始终按全量数据计算。 - 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 场景：流程图、序列图、甘特图、ER 图、gitGraph、思维导图与时间线（12 种白名单图型）由 pele 引擎驱动（fork：较 mermaid −70% 资产体积，换主题时已渲染图形实时重排）；另有轻量 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/Asaiuta/dsh-genui-enhanced.git
cd dsh-genui-enhanced
pnpm install # 提示时放行 esbuild 的构建脚本
# 本地联调构建并软链至 DSH
dsh plugin --profile web add link:$PWD
常用命令
pnpm install # devDeps；放行 esbuild 的构建脚本
./node_modules/.bin/tsc -p tsconfig.json # 类型门禁——要求零错误
./node_modules/.bin/tsdown # 产出 lib/（client.js、index.js、assets/*）
./node_modules/.bin/vitest run # 单元测试
> 上游的 npm-script 入口（pnpm run build / check、scripts/*.mjs 辅助脚本与 E2E 装置）不在本 fork 的 npm 快照内。以上三条即本 fork 的构建门禁；pnpm 11 的注意事项见 FORK.md（直接调用二进制，不要经 pnpm exec/pnpm run）。
进阶配置项
若需自定义插件行为，可在用户 profile 的 cordis.patch.yml 中调整：
- id: genui
name: '@changfenhuang/dsh-genui'
config:
renderUiTool: false # 关闭额外注入的 render_ui 工具调用，仅保留正文 dsh-ui 围栏与 panel
fenceFeedback: false # 关闭模型生成失败时的同回合自动 steer 纠错
❓ 常见问题排查 (FAQ)
Q: 为什么生成的 dsh-ui 仍然显示为普通代码块？
- 打开浏览器开发者工具（F12），切换到 Console 面板；
- 检索是否有
[genui] client active; fence-channel=dom日志：
- 若没有：说明客户端 Bundle 尚未被 DSH 宿主激活。请检查dsh plugin list确认插件已正确安装，并尝试重启 DSH web 与硬刷新浏览器；
- 若已有：检查模型输出的代码块标签是否准确为dsh-ui，且内容为合法的 JSON。
Q: 提示 "pnpm not found on PATH"？
DSH 的插件管理需要调用宿主系统的 pnpm。请在系统终端执行 corepack enable 或 npm i -g pnpm，安装完成后新开一个终端窗口再执行 dsh plugin add。
Q: npm install 返回 404？
本包是公开包（无需任何 npm 账号授权）。可先执行 npm view @changfenhuang/dsh-genui version 查看最新公开版本。若刚发布可能存在几分钟镜像同步延迟，请稍后重试。
Q: 3D 场景、Mermaid 或 ECharts 无法渲染？
图形重型引擎采用按需加载机制（首次使用时通过插件内置的静态路由拉取）。请先硬刷新网页（Cmd + Shift + R）；如果仍失败，可尝试重新安装插件：
dsh plugin --profile web remove @changfenhuang/dsh-genui
dsh plugin --profile web add @changfenhuang/dsh-genui
（注：上述 npm 命令重装的是上游市场版；若要刷新本 fork 的安装，请重新构建并 link——见「快速开始」方式 B。）
Q: 渲染 dsh-ui 时界面出现白屏？
当前版本强依赖 DSH ^0.2.0-rc.1 || ^0.2.1-rc.1。如运行在较老版本的 DSH 上可能存在 React 上下文兼容问题，请升级 DSH 宿主。
🗺️ 路线图评估 (Roadmap，继承自上游)
| 探索方向 | 评估结论 | 决策理由 |
|---|---|---|
| 增量 Diff Patch | 暂不做 | 一条围栏仅消耗 200–800 Token，全量重发代价极小且极其稳定；Patch 差异协议的模型遵循成本与出错率反而偏高。 |
| 细粒度 Action 回传 | ✅ 已上线 | 按钮/表单离散手势立即回传；连续滑块拖动尾沿防抖，确保流畅度与模型上下文整洁。 |
| 跨会话深度状态继承 | 暂不做 | 新一轮对话由模型更新新 UI，状态重置是更合理的自然行为；流式输出期间状态已完整保留。 |
| 独立画廊与多语言抽取 | 暂不做 | 画廊素材已由 demo-prompts、gallery.ts 与 README 全面覆盖；核心内置文案仅数处，保持极简轻量。 |
🔗 链接与致谢
- 上游项目：omdsh-dev/dsh-genui——组件画廊、演示与发布说明见上游仓库。
- Linux.do 社区讨论
- 欢迎访问 在线产品站 体验更多特性
📄 开源许可
本项目与上游一样遵循 MIT License 开源协议；第三方声明见 THIRD_PARTY_NOTICES.md。
