前言¶

在 DSH（deepseek-harness）的对话客户端里，模型输出的 SVG、HTML 或图表数据通常只能以代码块的形式出现，想看效果要手动复制到文件里再打开。dsh-visualizer 要解决的正是这一步：它是一个不改 DSH 源码的外部插件，让模型在对话流中直接渲染结构化图表和 SVG/HTML 小组件——图表用 echarts 画，小组件边生成边显示。

下面介绍它的定位、核心功能、安装方式与典型用法。

这是什么¶

dsh-visualizer 由 Moses14159 维护，当前版本 0.3.0，MIT 许可证。一句话定位：不改 DSH 源码，让模型在对话中即时生成可视化内容——流式 SVG/HTML 小组件，以及结构化图表（ChartSpec → echarts）。

实现上，它复用 DSH 已有的 assistant/chunk 与 tool/call + tool/result 会话事件，不修改 DSH 源码。插件面向 web 平台，客户端注入 @deepseek-ai/dsh-client-runtime。

核心功能¶

两类输出，三条交付路径¶

1、结构化图表：模型调用 visualize 工具并传入 spec，支持 bar / line / area / pie / scatter，用 echarts 渲染，并跟随 DSH 主题（--dsw-alias-* tokens）。
2、流式小组件：模型在回复中直接写 svg / html 围栏，插件复用已有的 assistant/chunk 事件，把内容逐 token 渲染到沙箱 iframe，随生成逐帧更新。
3、完整小组件：模型通过 visualize 的 widget 参数交付完整 widget，经过校验和持久化，可在 host 回放。

双侧校验¶

host 侧的 execute 与客户端折叠共用同一套纯函数解析器（chartspec / widget）。模型输出如果有漂移，不会静默通过校验。

安全隔离¶

widget 代码原样插入 sandbox="" 的 iframe，并配合 CSP default-src 'none'。设计上没有可被绕过的 sanitizer，隔离靠 iframe 沙箱完成。

渲染体验与降级¶

• SVG 按固有宽高比缩放，卡片带 fit / 1.5× / 2× 缩放和状态徽章（generating / truncated / done）。
• 校验或渲染失败时优雅降级：回退为普通代码块或 JSON 卡片，不留空行、不抛错。

纯模块，可独立测试¶

核心逻辑全部写成不依赖 DSH 的纯模块，97 个单元测试可以在 Node 中独立运行。

安装与启用¶

先确认前置条件：本地已安装 DSH（deepseek-harness）且 dsh web 可用；Node.js 20+（engines: node >=20）；插件依赖 DSH 的 @deepseek-ai/dsh-client-runtime、@deepseek-ai/dsh-llm、@deepseek-ai/dsh-tools（见 peerDependencies）。

满足条件后，用官方命令把插件装进 web profile：

dsh plugin --profile web add github:Moses14159/dsh-visualizer

两点注意：

1、从 Git 安装的插件会在安装时通过 prepare 脚本构建。出于安全考虑，pnpm 默认阻止构建脚本；如果安装时被提示，需要在 profile 的 pnpm-workspace.yaml 中添加相应的 allowBuilds 键，然后重跑安装命令。
2、README 提到，一旦 dsh-visualizer 发布到 npm，也可以按名称安装：dsh plugin --profile web add dsh-visualizer。

安装完成后，插件会注册 visualize 工具，客户端侧注入 @deepseek-ai/dsh-client-runtime。

典型用法¶

经过上面的步骤，打开 dsh web 的对话，直接对模型说即可。下面这些例子来自 README，可以照着复现。

想要结构化图表，说 “draw a chart with visualize”，模型会调用 visualize 并传入 spec。图表负载形如（kind 支持 bar | line | area | pie | scatter）：

{ "spec": {
    "kind": "bar",
    "title": "Shenzhen · 7-day temperature",
    "xAxis": ["Sat", "Sun", "Mon", "Tue", "Wed", "Thu", "Fri"],
    "yName": "°C",
    "series": [{ "name": "Max", "data": [32, 32, 30, 31, 29, 31, 32] }]
} }

想要流式小组件，说 “write an SVG badge / HTML widget”，模型会在回复中直接流式写 svg / html 围栏（围栏内是一段 <svg>…</svg> 或 HTML），随生成逐帧渲染。

想要完整小组件卡片，说 “Help me generate a weather card for Shenzhen right now”，模型会调用 visualize 并传 widget 参数（HTML），渲染为沙箱小组件卡片。widget 负载形如：

{ "widget": { "kind": "svg", "code": "<svg ...>…</svg>", "title": "Card title" } }

还有两个可以直接试的说法：

• “Use visualize to draw a chart of tomorrow’s 24-hour temperature change in Beijing”：模型传 spec（line），用 echarts 渲染。
• “Draw a bar chart, a pie chart, and a weather card at the same time”：模型多次调用 visualize，并在对话流中排版图表和卡片。

README 提示：这些例子要求模型加载 visualize 工具（安装插件后注册）。如果模型没有主动调用，把想要的效果描述清楚即可，它会倾向于调用 visualize。

适用场景与注意¶

适合的人群和场景：

• 日常在 dsh web 客户端调试模型，希望直接在对话里看到图表、徽章、卡片，而不是复制代码块的开发者。
• 需要模型输出结构化图表（趋势、占比、散点等）或小组件的场景。
• 想了解不改源码的 DSH 外部插件怎么写的开发者：插件核心逻辑是不依赖 DSH 的纯模块，源码和 97 个单元测试都在仓库里。

使用前注意：

1、插件以当前 dsh 进程的权限运行。安装任何第三方插件前，建议先检查源码与许可证；本项目许可证为 MIT，源码在 GitHub 仓库中。
2、环境要求：Node.js 20+，本地已安装 DSH 且 dsh web 可用。
3、从 Git 安装时如遇 pnpm 阻止构建脚本，按安装一节的 allowBuilds 说明处理。
4、widget 代码是原样插入 sandbox="" iframe 并配合 CSP default-src 'none' 运行的，不经过 sanitizer；对模型生成的内容保持常规判断。

小结¶

dsh-visualizer 的价值在于路径短：不改 DSH 源码，复用已有的 assistant/chunk 与 tool/call + tool/result 事件，就能让模型在对话流里渲染结构化图表和 SVG/HTML 小组件；双侧校验、iframe 沙箱、失败降级都有明确设计，核心逻辑可独立测试。

• GitHub 仓库：https://github.com/Moses14159/dsh-visualizer
• 社区插件目录页：https://www.skillhub.cn/plugins/Moses14159/dsh-visualizer （该目录为独立社区站点，与 DeepSeek、幻方无官方从属关系）