[English](README.md) · **中文**
[](https://github.com/dreamfarer-space/deepseek-harness-intelligent-ui/actions/workflows/ci.yml)
[](https://www.npmjs.com/package/deepseek-harness-intelligent-ui)
[](https://www.npmjs.com/package/deepseek-harness-intelligent-ui)
[](docs/compatibility.md)
[](https://nodejs.org)
[](docs/compatibility.md)
[](LICENSE)
[演示](#-演示) · [快速开始](#-快速开始) · [如何选择](#-agent-如何选择呈现方式) · [组件](#-组件目录ui_render) · [沙箱组件](#-沙箱组件ui_render_widget) · [扩展](#-扩展) · [安全](#-安全模型) · [配置](#%EF%B8%8F-配置) · [质量](#-真实模型质量基线) · [开发](#-开发与验证)
为 [DeepSeek Harness](https://github.com/deepseek-ai/deepseek-harness)（DSH）提供**生成式、可交互的 UI**。用户用自然语言提问，Agent 自行决定怎样作答：
- **普通文本**：用文字最清楚的时候；
- **原生组件**：看板、数据表格、图表、散点图与热力图、时间线、带滑块的函数图像、KaTeX 公式、Mermaid 流程图、代码差异、文件树、JSON 树、表单和选择题卡片；
- 完全自定义的**沙箱实时组件**：Three.js 三维场景、Canvas 模拟、小应用。
界面随回答流式、渐进地出现。排序、筛选、滑块、旋转、缩放、切换标签页都在浏览器内即时响应，只有显式操作（按钮、表单、选择题、`Bridge.sendPrompt`）才会回到 Agent，可以在当前会话中继续，也可以新开会话。
本插件把 CopilotKit [OpenIntelligentUI](https://github.com/CopilotKit/OpenIntelligentUI) 的思路（Open Generative UI + A2UI 风格声明式组件）移植到 DSH 自带的扩展点上，不依赖 CopilotKit、LangGraph 或外部路由服务。
## ✨ 亮点
[质量基线](#-真实模型质量基线)的全部 11 个浏览器用例，由 **`deepseek-flash`** 在 DSH Web 0.2.0-rc.1 中现场生成（2026-10-16）：纯文本、图表、数据表、表单回传、`Plot`、Three.js 与「让模型修复」、停止 → 重新生成、两轮原位修改、Fast 3G、CDN 不可达、手机宽度。失败原样保留并标为 ✗。由 DeepSeek 鲸鱼娘解说（见[致谢](#致谢)）。完整视频：[docs/assets/real-model/demo.mp4](docs/assets/real-model/demo.mp4)（2 分 27 秒）。
插件注入一段系统提示（[`src/guidance.js`](src/guidance.js)），让模型每一轮自行选择：
- **普通文本**：寒暄、简短事实、解释说明、要复制的代码、工作区内的编程任务。
- **`ui_render`**：结构化内容，例如对比、要探索的数据、看板、流程、公式、函数、代码评审、在几个方案中做选择、收集输入。
- **`ui_render_widget`**：组件目录画不出的东西，例如三维、模拟、动画、游戏、自定义工具。
- **本地优先**：凡是能在浏览器里算出来的，都必须即时更新，不调用模型。
这些规则为什么在与重写版决策顺序做真实模型 A/B 后被保留，以及路由如何评测，见 [docs/presentation-routing.md](docs/presentation-routing.md)。
`/ui <需求>` 可强制以 UI 作答。
| 工具 | 适用场景 | 渲染方式 |
|---|---|---|
| `ui_render` | 结构化回答 | 固定目录中的原生 React 组件，随 JSON 流式渐进渲染 |
| `ui_patch` | 修改之前显示的界面 | 组件级操作，未改动的组件保留交互状态（[详情](#-原位增量更新ui_patch)） |
| `ui_render_widget` | 自定义可视化、三维、模拟、小应用 | 不透明源沙箱 iframe 中的 HTML/CSS/JS：先 CSS，再实时 morph HTML，最后执行 JS，全程**一个** iframe |
## 🧩 组件目录（`ui_render`）
| 类别 | 组件 |
|---|---|
| 布局 | `Card`、`Stack`、`Grid`、`Tabs`（支持键盘操作） |
| 文本与提示 | `Text`（markdown 子集）、`Code`、`Alert`、`Badge`、`Divider` |
| 数据 | `Stat`、`Progress`、`List`、`Timeline`；**`Table`** 数据表格：按类型排序（数值、ISO 日期、布尔）、搜索、按列筛选、分页、CSV/Markdown 导出 |
| 图表 | **`Chart`**（柱状、折线、面积、饼图；可堆叠，图例显隐，悬停/点按/键盘提示，数据导出）、**`Scatter`**（连续坐标散点图）、**`Heatmap`**（顺序或发散色标，缺失值单独标识） |
| 地图 | **`Map`**（地点标记、路线、分组；拖动/键盘平移缩放；内置离线世界轮廓，或使用你配置的瓦片底图） |
| 媒体 | **`Image`** 与 **`Gallery`**（https 图片，懒加载且不发送 Referer，说明文字与可点击署名，模态大图查看器支持方向键；加载失败时显示图片描述）；**`Video`**（YouTube / Bilibili / Vimeo 链接用官方播放器，用户点击播放后才加载；或 https 直链 .mp4/.webm 原生播放；始终附原视频链接） |
| 数学与图示 | **`Plot`**（y = f(x)，拖动滑块即时重绘；安全表达式编译器，不用 `eval`）、**`Math`**（KaTeX）、**`Mermaid`** |
| 代码与结构 | **`CodeDiff`**（多文件新旧对比或 unified patch）、**`FileTree`**（状态徽标）、**`JsonView`**（JSONPath、复制） |
| 交互 | `Button`、**`Choice`**（选择题卡片）、`Form`（文本、数字、范围滑块、下拉、勾选、日期、多行文本） |
- **先校验再渲染。** DSH 的工具 schema 不支持递归，所以界面以扁平节点列表加 id 引用传输。Host 会拒绝未知类型或属性、悬空或重复的 id、环、形状不一致（图表系列、热力图行列）、非有限数值、无法编译的 `Plot` 表达式、越界的地图坐标和超限数据，返回 `ok:false` 并附出错路径，模型据此修正后重试。
- **只渲染文本。** 单元格、代码、JSON 和标签都作为 React 文本渲染，不作为 HTML。CSV 导出遵循 RFC 4180，带 UTF-8 BOM，并防止表格公式注入。
- **可访问、自适应。** 图表可获得焦点并用键盘查看，树形组件使用 `role=tree`，触屏上控件更大；图表按卡片实际宽度布局，手机上坐标轴文字依然清晰。
- **`Math` 与 `Mermaid`** 在与组件相同的沙箱中从 CDN 白名单加载，CDN 不可达时显示静态降级；使用[离线资源包](docs/offline-resources.md)可完全离线。
### 选择题与新开会话
`Choice` 显示一个问题、若干选项卡片和两个按钮。**在当前会话中继续**会把选中项的 prompt 作为下一条消息发送；**新开会话**会在同一工作区创建新会话、提交该 prompt 并跳转过去。新会话不会复制当前对话历史，所以每个选项的 prompt 都是自包含的。`Button` 设置 `sessionTarget: "new"` 也能做到同样的事。启动过程是幂等的：双击、失败后重试或刷新页面都不会把任务启动两次。
后续组件（`Map`、`Calendar`）的路线图与设计说明：[docs/component-roadmap.md](docs/component-roadmap.md)。
## 🔁 原位增量更新（`ui_patch`）
用户要求修改之前显示的界面时（例如“把柱状图换成折线图，其余不变”），Agent 按组件 id 打补丁，不必重新发送整棵组件树。
- **标识：** 每次 `ui_render` 的结果都会给出界面的 `uiId` 和版本号 1；每个被接受的补丁都会给出新版本号和组件的 `id:类型` 概览。
- **操作：** `setProps`（合并，`unset` 删除）、`replaceNode`、`insertChild`、`removeNode`，按顺序执行，**要么全部生效，要么全部不生效**；新版本还要通过与全新 `ui_render` 相同的校验。
- **并发：** `baseVersion` 为必填；基于旧版本的补丁会被拒绝并告知当前版本，补丁不会并行执行。
- **作用范围：** Host 不保存状态，而是重放本会话自己的历史来重建当前版本，所以补丁只能作用于同一会话中的界面。
- **交互状态：** 组件 id 在各版本间不变，未被替换的组件保留排序、筛选、标签页、表单输入、提交锁定和滑块位置；被替换的组件状态重置。
- **显示：** 补丁流式生成时，上一版本保持可用；成功后新版本显示在回复下方，旧副本收起为“已更新为第 N 版”。被拒绝、失败或中断的补丁不改动任何内容。
- **沙箱组件**会被重新渲染而不是打补丁，`UI.state` 依然保留。
## 🪟 沙箱组件（`ui_render_widget`）
字段遵循 OpenIntelligentUI 的流式协议，顺序固定：`title`、`initialHeight`、`placeholderMessages`、`css`、`html`、`jsFunctions`、`jsExpressions`。`css` 完成前显示占位文字；随后打开预览 iframe，把部分 HTML 实时 morph 进去（[idiomorph](https://github.com/bigskysoftware/idiomorph)）；参数完整后，在**同一个 iframe 内原地定稿**并执行代码。
| 运行时辅助（全局 `UI`） | 作用 |
|---|---|
| `UI.three(el, opts)` | renderer、场景、灯光和 OrbitControls（拖动旋转，滚轮或双指缩放），按需渲染并自适应尺寸 |
| `UI.canvas(el, draw)` | 高清 2D 画布，尺寸或主题变化时自动重绘 |
| `UI.state` / `UI.setState()` | 持久化状态；带 `id` 的输入控件自动保存并恢复 |
| `UI.color('accent')` / `UI.css()` | 不透明主题色（可用于 three.js 和 Canvas）/ 原始 CSS 值 |
| `UI.onTheme(cb)`、`UI.scheme`、`UI.reducedMotion` | 响应主题变化与减少动效偏好 |
| `.ui-row`、`.ui-control`、`.ui-card`、`.ui-stage` | 辅助样式类 |
- **Bridge：** `Bridge.sendPrompt({ text })` 在宿主应答前禁用触发它的控件；`Bridge.openLink({ url })` 打开链接；`Websandbox.connection.remote.*` 为兼容 OpenIntelligentUI 而保留。
- **依赖库：** 通过 importmap 从 esm.sh 引入 `three`、`three/addons/…`、`d3`、`chart.js/auto`、`gsap`、`canvas-confetti`。
- **错误恢复：** 出现脚本错误时显示错误数量，并提供“重新加载”和“让模型修复”（把错误发给 Agent）。
### 显示位置与状态保持
- 回合进行中，UI 在工具调用处内联显示；从准备、执行到结果始终是同一个组件实例。
- 回合结束后，DSH 会把工具调用折叠进“过程”区域，插件把 UI **重新显示在回复下方**，内联处改为一行提示。
- 交互状态按界面保存在内存和 `localStorage` 中（有上限），移到回复下方或刷新页面后都会恢复；UI 本身从持久化的会话日志重建。
- 中途停止时保留已完成的部分（组件的静态预览或已生成的组件），并提供提示和“重新生成”；即使 DSH 丢弃了仍在流式输出的调用也是如此。
## 🔌 扩展
| | |
|---|---|
| **第三方组件** | 可信伴随插件可注册带版本和命名空间的组件，Host 与浏览器共用 props 校验，支持 React 渲染与禁用、卸载。模型输出不能注册或加载代码。[扩展接口与 GitDiffViewer 模板](docs/component-extensions.md) |
| **受控数据与动作** | `Table` 与 `Chart` 可共享按会话隔离的只读 `dataRef`，在本地搜索、筛选、排序和分页。可信宿主可注册经 Schema 校验的动作，只有用户原生点击才会执行，并有权限检查、写操作确认和幂等回执。[接入文档](docs/controlled-data-actions.md) |
| **便携渲染器** | `renderer/renderer.js` 可在 DSH Web 之外渲染已接受的 `ui_render`、`ui_patch` 和沙箱组件，例如在移动端 WebView 中。[远程客户端约定](docs/portable-renderer.md) |
| **离线资源** | 可选资源包内置锁定版本的 KaTeX/字体、Mermaid、Three.js、D3、Chart.js 和 canvas-confetti，公式、流程图和标准 3D 场景无需 CDN。[离线资源包](docs/offline-resources.md) |
## 🔒 安全模型
- **隔离：** `