dsh-visualize

<strong>简体中文</strong> | <a href="README.en.md">English</a>

让 DSH 不只回答一段文字。模型调用 visualize 后，Web UI 会在对话里直接出现一张可交互卡片，用来做模拟器、图表、对比面板或 UI mockup。

安装

推荐用 npm 装到 DSH 的 web profile：

dsh plugin --profile web add @nagi-ovo/dsh-visualize
# 如果 dsh web 正在运行，重启后刷新页面

也可以从 GitHub 安装：dsh plugin --profile web add github:Nagi-ovo/dsh-visualize。可以运行 dsh --profile web --dump-config 确认插件已经进入最终配置。需要修改源码时，克隆仓库并在仓库目录运行 dsh plugin --profile web add .；构建产物已经提交，不需要额外构建。使用社区 plugin-registry 的用户也可以从「设置 → 插件」安装。

兼容 DSH 0.1.1-rc.2 到 0.2.1-rc.2。

怎么用

直接告诉模型你想看什么，例如「做一个能调参数的排序算法可视化」。模型调用 visualize，把整段 HTML fragment 直接作为 fragment 参数传入（可选 title、mode），卡片在模型生成参数时就开始渲染。适合并排比较的内容可以使用 mode: "wide"。要修正已经画出的卡片，模型用 action: "update" 加上卡片的 path 和一处 old_str → new_str 替换，不必重发整段 markup；path 只用于 update。

要做的东西比一张聊天卡片大时，比如带筛选的数据看板、多视图工具、全屏模拟或完整的桌面端 mockup，模型会用 mode: "page" 做一个独立页面。对话里显示一张启动卡片：标题、一行说明（summary 参数）、页面的实时缩略图和「打开页面」按钮，点按钮后页面在新标签页里全尺寸打开。浏览器拦下新标签页时，可以点「在对话中展开」直接在对话里查看。用 update 改过页面后，已经打开的标签页不会自动刷新，再点一次「打开页面」即可。

卡片会跟随 DSH 的明暗主题，默认风格使用鲸鱼蓝配色（其他风格见下文）。聊天栏放不下时，点卡片标题行右侧的「在新窗口打开」按钮，可以在新标签页里全尺寸查看，页面沿用打开那一刻的主题，内容仍在同样的 sandboxed iframe 里运行。会话重放时，页面从持久化的工具结果恢复，不依赖原始 fragment 文件仍然存在。

每张卡片的 fragment 另存一份到 ~/.dsh/visualize/sessions/<会话 id>/<标题>-<hash>.<style>.html（设置了 DSH_HOME 时在 $DSH_HOME/visualize/ 下），按会话分开，不写进你的项目目录，git status 不会出现 viz/。update 改写的就是这份文件。旧版本写在工作区 viz/ 下的卡片仍然可以 update，原地修改。插件不会自动清理这些文件，需要时可以直接删除 ~/.dsh/visualize/，已有会话的卡片照常重放。

卡片也能显示它自己加载不了的图片：agent 刚存进工作区的图（matplotlib 画的 PNG、论文里的 figure），或者任意公开的网络图片。模型写 <img data-viz-src="figs/loss.png"> 或 <img data-viz-src="https://…">，调用执行时插件读取文件或下载图片，确认内容确实是 PNG、JPEG、GIF、WebP 或 SVG（单张不超过 5 MB，每张卡片合计不超过 12 MB、最多 16 张），然后存到卡片旁边的 ~/.dsh/visualize/sessions/<会话 id>/images/。卡片渲染时从那里取图，所以模型的上下文和会话日志里都没有图片字节，日志里每张图只记一条很短的引用。某张图失败时，卡片在原位显示一个带 alt 文字的占位框，其余部分照常渲染；工具结果会告诉模型哪张图失败、原因是什么，方便它改路径。用 update 改卡片时，已经下载过的网络图片直接复用，工作区文件重新读取，所以重新生成的图在下一次修改后就会显示出来。这项功能需要 DSH 0.1.7 及以上；更早的版本里卡片只显示占位框，工具结果会说明原因。

DSH 默认会把已完成回合的工具过程折叠起来。折叠时，这一轮画出的卡片会再显示在最终回答下方，不用展开过程也能看到；「工作步骤展示」选「完全展开」时则只在原位显示。

卡片可以把内容交回对话。测验、选项、表单这类卡片在你点下按钮后，会把一句话（比如「我选了 B，帮我解释为什么 A 不对」）填进输入框。消息不会自动发出，你可以改完再发，也可以不发。改选另一个选项时，新的话会替换卡片刚才写进去的那句；输入框里有你自己写或改过的内容时，卡片不会覆盖它，只会弹出一条提示。这项功能需要 DSH 0.1.7 及以上；在新窗口打开的卡片不支持，卡片会隐藏这类按钮。

卡片会记住你在里面做的选择：拖过的滑块、勾选的选项、填写的文字、选中的标签页，以及模型用 dshViz.state 保存的其他选择（比如选中的节点、当前步骤）。刷新页面、重新打开会话、模型用 update 修改卡片之后，卡片都会恢复成你离开时的样子；重新画的新卡片从默认值开始。状态只存在这个浏览器里，放在 DSH 页面的 localStorage 中（键名以 dsh-visualize:state: 开头），按会话和卡片分开，不会上传，也不会同步到别的设备或浏览器；换一个端口打开 DSH 也算另一个站点。每张卡片最多 16 KB，所有卡片合计最多 256 KB，超出时最久没改动的卡片先被清掉。想全部清空，在浏览器开发者工具的 Application → Local Storage 里删掉这些键，或者清除这个站点的数据。页面卡片的缩略图和在新窗口打开的卡片会显示已保存的状态，但新窗口里的改动不会保存。浏览器禁止存储时（例如某些隐私模式），状态只在当前页面里保留：切换主题、修改卡片不会丢，刷新后就没了。

模型有时会在卡片还没真正交到你手上时就结束回答：最后一次 visualize 调用失败了却没有重试；卡片画出来了，但还带着会让它坏掉的 lint 警告（脚本查找不存在的元素 id、沙箱里加载不到的相对 URL）；把 HTML/SVG 当代码块贴进了回答；或者说了「我来画一张卡片」就停下了。遇到这些情况，插件会在这一轮结束前给模型发一句简短的提醒（steer），让它在同一轮里接着修好或补上调用。判断偏保守：你要的就是 HTML 代码或文件、这一轮写了项目文件、回合被你中断或出错时都不会提醒；颜色写死这类只影响风格的警告不算；每轮最多提醒 2 次，同一个问题只提醒一次。不需要的话，在 cordis.patch.yml 里这个插件的 config 下加 selfRepair: false。

卡片风格

插件内置 5 种卡片风格，默认是 whale。在 DSH 里点左下角「更多」→「设置」→「可视化」，每种风格都有一张按当前明暗主题实时渲染的预览卡，点一下就保存，下一张卡片立即生效，不用重启。

这个页面需要 DSH 0.1.7 及以上（宿主的设置表单 configForms 和 /api 路由；0.1.7 里「设置」在侧边栏左下角）。更早的版本里页面要么不出现，要么只给出下面的写法，请直接在 <DSH_HOME>/profiles/web/cordis.patch.yml（默认 ~/.dsh/profiles/web/cordis.patch.yml）里加：

…