前言¶
DeepSeek Harness（dsh）是 DeepSeek 开源的智能体框架，官方定位是「Everything is a Plugin」：模型、工具、技能、会话、沙箱，一直到界面，都可以用插件增删，不必改框架源码。日常在 Web UI 里跟模型对话时，结果多半还是一段文字、一份 Markdown 表格，或者一张静态的 Mermaid 图。排序过程、参数模拟、方案对比这类内容，纯文字往往要来回解释，也不方便动手调一调。
dsh-visualize 就是冲着这件事来的。模型调用 visualize 之后，网页对话里会直接出现一张可交互卡片，用来做模拟器、图表、对比面板或 UI mockup。它由 Nagi-ovo 维护，社区目录归在「界面增强」。本文依据插件目录页和 GitHub 仓库交叉核实后写成。需要说明的是：DeepSeek Harness 插件库（deepseek-harness-plugin.com）是独立的社区目录，与 DeepSeek / 幻方没有官方从属关系，不能当成官方应用商店。
这是什么¶
dsh-visualize 是一款面向 DeepSeek Harness 的界面增强插件。仓库 npm 包名为 @dsh-external/dsh-visualize，许可证是 BSD-3-Clause，主要语言是 TypeScript。2026-08-17 从 GitHub 核实，仓库约 160 星；目录页收录时显示 90 星，星标以仓库一手数据为准。当前 package.json 版本为 0.1.2。
它解决的问题很具体：让模型不只回答一段文字，而是把一份 HTML fragment 渲染成对话里的沙箱卡片。用户侧通常不需要自己写工具调用，直接告诉模型想看什么即可；插件会注册 visualize 工具，并附带一份同名 skill，约定 fragment 该怎么写、主题变量怎么用、哪些外部资源可以加载。
核心功能¶
1、对话内的交互式卡片。模型写出 HTML fragment 后调用 visualize，Web UI 会在对话流里插入一张可交互卡片。仓库 README 写明适用方向包括模拟器、图表、对比面板和 UI mockup。捆绑 skill 把适用边界写得更细：有可调参数、动画或交互时才值得出卡片；只要一张静态节点图就能讲清楚，用 Mermaid 即可；用户要的是真实网站、页面组件或独立文件时，应落到项目文件，而不是对话卡片。
2、visualize 工具与捆绑 skill。节点侧把工具注册到 ctx.tools，把 visualize skill 注册到 ctx.skills。浏览器侧再按同一工具名挂上沙箱卡片。当前源码里，默认动作是 create，把 markup 作为 fragment 参数直接传入，可选 title 和 mode；需要修正已渲染卡片时，用 action: "update"，按卡片的 path 做一次精确的 old_str / new_str 替换。仓库 README 里曾写成 visualize(path, title?, mode?)，与当前工具实现不一致，安装后以仓库源码和捆绑 skill 为准。并排比较可以用 mode: "wide"，单张图表或整页 mockup 保持默认的 inline。
3、流式预览与会话重放。卡片会在模型还在生成 fragment 时就开始出现。完成后的 fragment 会写入会话工作区的 viz/ 目录，工具结果的 meta 里也会带上完整 fragment。会话重放时从持久化的工具结果恢复，不依赖原始 fragment 文件还在不在磁盘上。
4、主题跟随与沙箱隔离。卡片跟随 DSH 的明暗主题和鲸鱼蓝配色。渲染发生在不透明来源的 sandboxed iframe 中，不能接触宿主页面。CSP 会阻止网络请求、嵌套页面和表单提交，只允许从固定 CDN 加载静态资源：cdnjs.cloudflare.com、esm.sh、cdn.jsdelivr.net、unpkg.com、fonts.googleapis.com、fonts.gstatic.com、fonts.bunny.net。单个 fragment 默认上限是 1000000 字节，可通过配置项 maxFragmentBytes 调整。
5、非 Web 客户端的降级。package.json 把客户端平台标成 web。目前只在 Web UI 中渲染交互卡片；TUI 和 headless 客户端会显示普通工具结果。卡片内的按钮暂时不能向主对话发送 follow-up 消息。仓库 README 写明，灵感来自 Codex 桌面端的 /visualize；skill 的分层 reference 和 Chart.js 优先路线借鉴了 himself65/finance-skills 里的 generative-ui。
安装与启用¶
社区目录页给出的安装命令如下，在 DeepSeek Harness 终端中运行即可：
dsh plugin add github:Nagi-ovo/dsh-visualize
仓库 README 推荐把它装到 web profile，因为交互卡片只在 Web UI 里渲染：
dsh plugin --profile web add github:Nagi-ovo/dsh-visualize
# 如果 dsh web 正在运行，重启后刷新页面
目录页提醒：如需可复现安装，请固定 commit 哈希，把下面的 commit 换成仓库里的实际提交：
dsh plugin add github:Nagi-ovo/dsh-visualize#commit
安装后可以用下面的命令确认插件已经进入最终配置：
dsh --profile web --dump-config
需要改源码时，克隆仓库并在仓库目录运行 dsh plugin --profile web add .。README 写明构建产物已经提交，不需要额外构建。使用社区 plugin-registry（https://github.com/dsh-external/plugin-registry）的用户，也可以从「设置 → 插件」安装。
插件以当前 dsh 进程的权限运行，安装时可能执行代码。安装前请检查源代码仓库和许可证。
典型用法¶
装好以后，直接用自然语言告诉模型你想看什么。仓库 README 给的例子是：
做一个能调参数的排序算法可视化
模型会先加载捆绑的 visualize skill，写出一份 HTML fragment，再调用 visualize。用户侧通常看不到工具参数；如果要对照源码理解调用方式，当前实现大致是：
create（默认）：传入fragment（字面 HTML，不要带<html>/<head>/<body>/<!doctype>文档骨架），可选title、mode。update：传入已有卡片的path、title，以及一次精确的old_str→new_str替换。skill 约定小修正才用 patch（少于 20 行、少于 5 处，同一轮最多 4 次），更大改动应重新create。mode: "wide"：留给需要并排比较的多面板布局。
skill 还约定了几条 fragment 规则，写插件或排查渲染失败时用得上：
- 只提交 fragment，由卡片负责文档骨架、样式表、主题和 CSP。
- 根元素要有唯一 ID，脚本用
document.getElementById(...)定位，不要依赖document.currentScript。 - 内联
<style>和<script>可用；fetch、XHR、WebSocket 和表单提交会被策略拦住，失败时没有错误提示。 - 外部静态资源必须带固定版本，并且只允许从前面列出的 CDN 加载。
- 颜色使用主题变量或
light-dark()，不要自己声明color-scheme。
适用场景与注意事项¶
比较适合这些情况：算法或模拟需要拖滑条看变化；几组数据要并排对比；产品界面需要一张可点的 mockup，而不是再导出一份独立 HTML。不太适合：只要一张静态结构图、真正要交付到代码仓库里的页面，以及主要在 TUI / headless 里工作的流程。
使用时有几条边界需要记住。
- 交互卡片目前只在 Web UI 中渲染。TUI 和 headless 只会看到普通工具结果，不要指望同一套卡片出现在终端里。
- 卡片内的按钮暂时不能把消息发回主对话。需要模型根据你在卡片里的操作继续往下做时，还得在输入框里另说一句。
- 每次 patch 都会重载卡片，用户在卡片里输入、拖动或滚动的状态会丢掉，所以修正应尽量合并，而不是一条条改。
- 单个 fragment 默认不超过 1 MB。内联大数据要先抽样、降精度，去掉用不到的字段。
- 插件以当前 dsh 进程权限运行。安装前应阅读源码和 BSD-3-Clause 许可证，只安装你信任的来源；需要可复现环境时固定 commit。
小结¶
dsh-visualize 把「模型生成一段 HTML、Web UI 在对话里画出一张沙箱卡片」做成了可安装的 DSH 插件。对经常要看模拟、图表和对比面板的人来说，它补的是文字解释够不到的那一层交互，而不是再做一个独立的前端项目。
目录页：https://deepseek-harness-plugin.com/zh-CN/plugins/dsh-visualize/
GitHub：https://github.com/Nagi-ovo/dsh-visualize
