DSH Intelligent UI

为什么使用它

有些问题，需要亲手调节参数、比较选项，或看一遍过程。

DSH Intelligent UI 为这些问题提供交互式呈现。你描述目标，当前 DSH 模型调用工具生成界面，插件负责校验、显示和保存。界面中的按钮还可以携带当前参数，经过你的确认后，将问题送回原会话继续讨论。

核心能力

• 在聊天里直接操作：支持 HTML、CSS、JavaScript，以及 DOM、SVG、Canvas。生成过程中先显示静态预览，工具成功后再启用交互。
• 结果持续显示：使用独立的聊天结果节点，保留工具返回的界面；支持历史重放、重置和单文件 HTML 导出。
• 界面跟随宿主：适配 DSH 浅色/深色、字号和字体，内容自动测高，并显示可捕获的脚本运行错误。
• 常用组件开箱可用：六种模板、结构化文本表格、内置 Chart.js 4.5.1 和 Leaflet 1.9.4，无需生成代码加载 CDN。
• 高德地图接入：支持高德地点搜索与官方静态底图，保留地点标记、选点、缩放、平移和行程播放；Key 只在 Host 侧使用。
• 资源可追溯：保留原有 OpenFreeMap 与百科/Commons 图片模式，展示地点来源和图片署名；个别地点无法定位时明确提示，其余已确认地点继续显示。
• 交互回到原会话：追问经用户确认后提交，区分“等待确认”“已入队”和模型的运行、完成、失败或取消状态。
• 也能独立作为 MCP 使用：复用文档校验、模板和 HTML 装配；适合需要自行接入渲染容器的客户端。

快速开始

兼容性

使用预构建包安装

已有 DSH 0.2.1-rc.2 和正在使用的 Web profile 时，可以直接安装 Release 中的预构建包，无需克隆源码或本地编译：

dsh plugin --profile web add https://github.com/NingTiAn-byte/dsh-intelligent-ui/releases/download/v1.2.1/dsh-intelligent-ui.tgz --ignore-scripts

将 web 替换为实际 profile 名称。安装后按宿主提示刷新或重启；模型服务使用该 profile 自己的配置。下方是源码开发和独立实例的启动方式。

1. 获取并构建

git clone https://github.com/NingTiAn-byte/dsh-intelligent-ui.git
cd dsh-intelligent-ui
npm ci
npm run build
npm run check

构建使用锁文件中的 rc.2 SDK，不再依赖 alpha.4 源码链接。lib/、dist/ 和预览页面都是生成产物；从 Git 获取源码后需要先构建。

2. 离线预览

npm run preview

这会生成并打开本地演示页面，无需配置模型。你可以检查控件、计算、重置与追问确认；预览中的追问只记录演示请求，不会发送到 DSH。

在无图形环境中只生成页面并打印位置：

npm run preview -- --no-open

3. 在发行版 DSH 中启动

确认已安装 DSH 0.2.1-rc.2，在项目目录执行：

pwsh -NoProfile -File scripts/run-dsh.ps1

脚本会构建插件、创建独立 intelligent-ui Web profile、通过官方插件管理器安装本地目录，然后启动并打开浏览器。默认端口为 3098；未设置 DSH_HOME 时，配置和会话放在项目的 artifacts/dsh-home 下。

在新打开的 DSH 中配置模型服务，再发送下面的测试提示词。独立 profile 不会自动复制你日常客户端的模型配置和凭据。

# 端口已占用时
pwsh -NoProfile -File scripts/run-dsh.ps1 -Port 3099

# 只安装并检查合成配置，不启动服务
pwsh -NoProfile -File scripts/run-dsh.ps1 -Check

# 不自动打开浏览器
pwsh -NoProfile -File scripts/run-dsh.ps1 -NoOpen

# 自定义发行版官方 CLI 的位置
pwsh -NoProfile -File scripts/run-dsh.ps1 -DshCli '~\DeepSeek Harness\resources\runtime\cli\bin\dsh.cmd'

在对话中使用

描述你需要的界面即可；为了首次确认工具链，建议明确要求调用工具。

第一个交互界面

我想知道FFT算法的可视化表达是什么样的。

预期结果： 在 DSH 对话中生成可交互的 FFT 原理演示。若希望调节采样点数、输入信号或逐步观察计算过程，可以在提示词中补充这些要求；具体交互取决于模型生成的界面。

演示视频：FFT 原理可视化

实际操作录屏，约 49 秒：在聊天中查看 FFT 原理、切换输入信号并观察可视化结果。

https://github.com/user-attachments/assets/b8585aaf-acec-4aef-8c22-271d9712d46f

查看或下载原始 MP4

更多可复制的提示词

生成一个交互式单摆演示，可以调节摆长和重力加速度。
提供开始、暂停和重置，展示周期公式、参数单位与理想模型假设。

用柱状图比较 A、B、C 三种方案的耗时：12、18、9 分钟。
数据来源注明“用户提供的演示数据”，保留可读的数据表。

使用高德地图介绍上海的豫园、外滩、南京东路、陆家嘴、武康路和新天地，城市指定上海。
按地点名称查询，提供地点卡片、选点和行程播放，并保留来源链接。

演示视频：上海六站行程地图

实际操作录屏，约 15 秒：查看高德底图上的六个地点、地点卡片和行程播放。

https://github.com/user-attachments/assets/f0c09349-31e8-40ab-8ec4-137fc49d2de1

查看或下载原始 MP4

生成一个复古风格的打砖块小游戏，支持键盘操作。
提供开始、暂停、重新开始、分数和操作说明。

演示视频：复古打砖块游戏

实际操作录屏，约 19 秒：展示聊天中生成的复古掌机界面与打砖块游戏。

https://github.com/user-attachments/assets/75ea5215-ed3f-4e43-b1ba-41be68d12751

查看或下载原始 MP4

如何验证主线

1. 模型调用工具：检查轨迹；默认先选择展示形式，再调用 UI、表格或专项工具。
2. 显示交互界面：确认出现卡片并能操作，而不只是模型声称“已生成”。
3. 保存与重放：等待本轮结束，刷新并重新打开同一会话，确认保存的界面仍可渲染。
4. 追问回到会话：在界面内发起追问，在宿主确认后，检查当前会话收到消息及模型回复。

保存的是界面文档和资源，不保证保留滑块位置、游戏分数等临时运行状态。重置或重新挂载会重新运行界面。导出的 HTML 可独立交互，但不能直接向 DSH 发送追问。

工具清单

默认 routing: model 时注册 11 个工具。关闭展示路由后为 10 个；模型在某一阶段能看到的渲染工具还会随当前展示选择变化。

展示路由是同一个会话模型的一次工具选择。需要 UI 时，先完成选择，再在后续模型步骤调用渲染工具；不需要可视化的问题可以直接用文字回答。

注册实现：Host 入口 · 专项工具 · 展示路由。

工作原理

flowchart LR
    A[用户描述需求] --> B[当前 DSH 模型]
    B --> C[选择展示形式并调用工具]
    C --> D[Host 校验并保存文档及资源]
    D --> E[持久聊天节点]
    E --> F[隔离 iframe 中显示和交互]
    D --> G[历史重放 / HTML 导出]
    F --> H[宿主确认追问]
    H --> B

Host 管理工具、资源获取和文档校验；Client 管理聊天节点、iframe、主题和消息桥接；DSH 继续管理模型、会话、队列与人工问答。界面资源保存在工具结果 metadata 中，重放时无需重新让模型生成整份界面。

生成代码在独立来源、sandbox="allow-scripts" 的 iframe 内运行。流式阶段不执行生成脚本；成功后启用脚本。追问和外链经受限桥接交给宿主确认。

工具失败时，卡片会显示可用的具体错误文本，历史重放也保留该错误；失败或中断的预览不会启用脚本。

界面与会话桥接

try {
  const receipt = await window.dshUI.sendPrompt('请解释当前参数对应的结果');
  // 这里只代表确认/入队结果，不代表模型已经回复。
} catch (error) {
  // 处理用户取消或提交失败。
}

const unsubscribe = window.dshUI.onRunStatus(event => {
  // 按 requestId 关联；completed 表示对应模型轮次完成。
  console.log(event.requestId, event.status);
});

还提供主题订阅、外链确认与错误报告。完整字段、版本和边界见 运行契约。

配置

高德地图

高德模式使用 Web服务 Key：Host 调用地点搜索、坐标转换和官方静态地图接口，Leaflet 负责聊天卡片中的显示和交互。不需要申请 Web端（JS API）Key；当前实现也不是高德 JS 动态瓦片地图。

1. 在高德控制台为应用申请 Web服务 Key。
2. 在插件根目录创建 .env，写入 DSH_AMAP_KEY=你的高德Web服务Key。默认自动读取该文件，与 DSH 的启动目录无关；修改后重启 DSH。也可用 amapEnvFile 指定其他 .env 路径。
3. 复制 amap.example.yml 为 preview/amap.local.yml，填入真实文件路径：

- id: intelligent-ui
  config:
    mapProvider: amap
    # amapEnvFile: 'D:/keys/.env' # Optional; defaults to the plugin root .env
    amapTimeoutMs: 15000

4. 用覆盖层启动独立 Web profile：

pwsh -NoProfile -File scripts/run-dsh.ps1 -ImageNetworkPatch preview/amap.local.yml

已有客户端应将相同配置应用到其实际使用的 profile，然后完全退出并重启。不要通过 CLI 直接启动保留的 desktop profile，它由 Electron 客户端管理。

Key 不进入生成界面、工具结果或导出的 HTML；也不要将密钥文件提交 Git。preview/amap.local.yml 已被忽略，但放在其他位置的密钥文件需要自行排除。

调用地图工具时建议提供 city。显式坐标输入的 coordinateSystem 默认为 wgs84；若已有高德坐标，应声明 gcj02，避免重复转换。请求有节流和有限重试，权限、配额和网络错误仍会明确报告。未配置高德的 profile 不会自动切换，旧历史文档也不会被改写。

通用参数

通过 DSH profile 的插件配置或额外 patch 覆盖参数。仓库的 默认 patch 定义插件入口；下面的覆盖层可配合启动脚本 -ImageNetworkPatch 使用，该参数实际上接收通用的额外 patch 文件。

- id: intelligent-ui
  config:
    maxDocumentChars: 200000
    minHeight: 180
    maxHeight: 900
    routing: model
    imagesEnabled: true
    imageMaxBytes: 256000
    imageTimeoutMs: 15000
    imageProxyUrl: ''
    mapCacheDir: ''
    mapProvider: openfreemap
    amapEnvFile: ''
    amapKeyFile: ''
    amapTimeoutMs: 15000

初始高度与自动内容测高是两个概念，自动测高支持 180～4000 px。完整配置定义见 src/index.ts。

独立 MCP

MCP 版提供 13 个资源、3 个提示和 7 个工具。它返回装配后的 HTML 与结构化文档；是否显示成界面，由接入的 MCP 客户端决定。

npm run build
npm run verify:mcp
npm run mcp

使用构建生成的 preview/mcp.config.json，或将以下示例中的路径替换为实际绝对路径：

{
  "mcpServers": {
    "dsh-intelligent-ui": {
      "command": "node",
      "args": ["/absolute/path/to/dsh-intelligent-ui/lib/mcp-stdio.js"]
    }
  }
}

MCP 工具为 assemble_document、assemble_saved_document、get_intelligent_ui_template、render_intelligent_chart、render_intelligent_map、plan_intelligent_ui、render_intelligent_workflow。它们与 DSH 的工具集合不同。

需要复制到另一台机器时，可复制整个 dist/mcp，在目标目录执行 npm install --ignore-scripts，再运行 node mcp-stdio.js。本机配置文件含绝对路径，被 Git 忽略。

运行边界

• 生成脚本不能直接操作宿主 DOM、加载任意远程脚本或随意发起网络请求；外部资源由受控 Host 能力处理。
• 保存的文档与资源可重放；首次图片/街道获取仍需联网，旧 NASA/USGS 模式可能使用固定来源远程图块。
• 高德是固定区域底图快照，放大不会增加细节；所有模式的行程连线都是顺序直线，不代表道路规划。
• 原生表格是只读文本表格，没有内置排序、筛选和分页；需要这些交互时使用通用 UI 工具。
• 会议选择不创建日历预约，工作流展示不执行任务，插件不自带业务数据库。
• 可捕获运行错误不等于能恢复死循环或浏览器崩溃。生成游戏、计算逻辑和科学模拟需要核对正确性。

开发与贡献

src/
├── index.ts       # Host 入口、配置与通用工具
├── host/          # 地点、图片、地图、展示路由、追问关联
├── client/        # 聊天节点、iframe、桥接与主题
├── shared/        # 文档协议、校验、模板与组件
└── mcp/           # 独立 stdio MCP 服务
preview/           # 离线演示与浏览器测试页面
scripts/           # 构建、检查、启动与验证
tests/             # 单元、Host 集成及真实浏览器测试
vendor/            # 固定版本第三方资源与许可

浏览器测试优先使用 DSH_TEST_BROWSER；Windows 自动发现 Edge，否则需要 npx playwright install chromium。默认回归使用受控测试，不调用真实模型；真实模型端到端体验与联网资源需要另行检查。

欢迎通过 Issue 提交可复现问题，或通过 Pull Request 改进模板、兼容性和文档。报告时附上 DSH/插件版本、profile 类型、复现提示词、工具轨迹与已脱敏日志；不要提交密钥、带访问令牌的 URL 或私人会话。

许可与致谢

本项目采用 MIT License。依赖的 Chart.js、Leaflet、图片与地图数据保留各自许可和署名，详见 第三方说明 与 地图测试数据署名。

感谢 DeepSeek Harness、Model Context Protocol、Chart.js 与 Leaflet 提供的基础能力。