abiddotdev/dsh-visualizer

dsh-visualizer

一个 DeepSeek Harness 插件。visualizer 工具会在模型编写时，将一份自包含的 HTML 文档以流式方式传入聊天，并在沙盒化的内联框架中实时预览——Chart.js、外部 CDN 库，全都可以。完全不触碰工作区。

一个包同时提供两部分：面向模型的工具（lib/index.js）和 Web GUI 卡片（lib/client.js，通过包的 dsh.client 清单声明）。安装后，一个 bundle 层会同时挂载两者。无需手动编辑 profile 补丁。

一张计算机体系结构图正流式传入聊天，并在卡片中实时渲染

文档正流式传入聊天，并在卡片中实时渲染

每次生成的内容都可以从卡片下载为自包含的 .html（或 .svg）文件。无需服务器往返。

已完成的卡片还带有评论模式：切换行控件中的画笔控件，点击框架内的任意元素（或拖拽一个矩形），每次选取都会在渲染器下方变成一行评论，显示该元素的选择器、标记和文本。为每次选取写一条备注并发送——这些选取会组合成面向模型的一个 [widget] 回合，并附带定位器包，因此它可以精确编辑你指向的那些元素。按 Esc 或再次切换即可退出；模式关闭时文档保持原样运行。

完整长度的演示，每种产物类型一个：

1. 拉取请求流程概览 — 图表
2. 光合作用讲解 — 交互式
3. 计算机如何工作 — 模型图（如上所示）
4. 插件本身，由插件解释并渲染 — 自托管
5. 流式生成式 UI 亮点 — 亮点
6. 组合演示 — 一次运行中的多个用例

安装

需要 Node ^22.19 或 >=24，以及 0.1.2-rc.1 或更新版本的 DeepSeek Harness 安装（更旧的版本：见下方 Harness 版本）：

install into the default web profile
dsh plugin --profile web add 'git+https://github.com/abidhmuhsin/dsh-visualizer.git'

or install into any custom profile
dsh plugin --profile  add 'git+https://github.com/abidhmuhsin/dsh-visualizer.git'

首次运行会失败，并给出“Add the package to allowBuilds”的提示。这是 pnpm 的供应链门禁在 prepare 构建被加入允许列表之前对其进行的阻止；提示中带有确切的键，以 codeload URL 和解析出的提交为键。将该块粘贴到 ~/.dsh/profiles//pnpm-workspace.yaml 中的 allowBuilds: 下，然后重新运行。键会固定提交，因此在上游有新推送后，重新安装会打印出新的提示供粘贴。

Harness 版本
默认分支跟踪最新的 DeepSeek Harness 预发布版（0.1.2-rc.1 或更新版本）。0.1.2-alpha.3 将客户端 conversationEvents 服务重命名为 uiConversation，并把 Chat Node 从 dsh-client-ui-conversation 移到了新的 dsh-client-ui-chat 包中，因此该卡片无法在比这更旧的构建上挂载——工具会停在 pending (waiting for service: conversationEvents)。0.1.2-rc.1 的 Compact transcript 视图可以在回合关闭后把已结算的卡片折叠收起；关于本插件如何处理这一点，请参见下方的已结算卡片与 Compact transcript 视图。

在较旧的 harness（0.1.1-rc.2 及更早的 pre-alpha 构建）上，请改用 pre-alpha 兼容分支安装，并带上 ref 片段：

dsh plugin --profile  add 'git+https://github.com/abidhmuhsin/dsh-visualizer.git#pre-harness-0.1.2-alpha3-compat'

该分支是针对 pre-0.1.2-alpha.3 客户端 API 构建的插件的最后状态。它已被冻结——新功能只会进入默认分支——因此升级 harness 才是前进的方向。

已结算卡片与 Compact transcript 视图

Compact transcript 视图会在回合关闭后把已结算卡片的工具调用行折叠收起。本插件在此之前会让卡片保持原位存活，并在回合关闭后通过 harness 的 turn-tail 扩展点重新发布它——这是挺过折叠的唯一方式，因为该缺口在更早的时候并不存在。Normal 视图从不折叠，因此卡片就停留在它原本所在的位置，不会产生第二份副本。相关机制请参见 CHANGELOG.md。

或者从本地检出安装

若要折腾这个插件（或安装尚未推送的版本），请检出、构建，然后通过本地路径添加：

git clone https://github.com/abidhmuhsin/dsh-visualizer.git ~/tools/dsh-visualizer
cd ~/tools/dsh-visualizer
pnpm install
pnpm build

cd ~/tools/deepseek-harness
pnpm dsh plugin --profile visualizer add '/home/user/tools/dsh-visualizer'

本地路径会跳过 git fetch 和 allowBuilds 那一套，因为 pnpm build 已经生成了 lib/。不过加载器仍会从 profile 下已安装的副本导入。要获取更改：在检出目录中重新运行 pnpm build，然后再次 remove 并 add。

启动该 profile，并让模型“visualize …”；流式文档会在写入过程中内联显示。用 ref 片段固定某个发布版本（'git+https://github.com/abidhmuhsin/dsh-visualizer.git#v0.2.0'）。要移除：

dsh plugin --profile  remove dsh-visualizer

它如何挂载

该包声明了一个 dsh.bundle 清单（dsh.bundle.patch → ./cordis.patch.yml），因此 dsh plugin add 会自行将其安装为一个 profile 补丁层。该层会为这个包插入一行加载器记录：

- 宿主 Loader 导入 lib/index.js；其 apply() 注册面向模型的 visualizer 工具。
- Web GUI 的客户端模块系统会扫描 Loader 条目，查找声明了 dsh.client 清单的包，并提供 lib/client.js，由其渲染流式卡片和已定稿行。

配置

bundle 层已经插入了 loader 行，因此覆盖配置需要在 profile 自身的 patch 层（~/.dsh/profiles//cordis.patch.yml）中，以扁平的、按 id 定位的 patch 条目来覆盖。不要把它包在 insert: 里——那会追加第二行，而不是覆盖已安装的那一行。完整选项列表，按当前默认值如下：

- id: dsh-visualizer
config:
maxArtifactBytes: 262144      # 每次调用的渲染大小限制，单位为字节
guideTool: true               # false = 移除 visualizer_guide 配方工具（渲染工具保留）
guideTypes: [chart, diagram, mockup, interactive, art]   # 要教授并允许的类型
shareArtifacts: true          # false = 不进行磁盘镜像、不提供 serve 路由，也不提供 Share 控件
artifactDir: ~/.dsh/visualizer/artifacts        # 遵循 $DSH_HOME
artifactRetentionDays: 30     # 激活时清理早于该天数的 artifact；0 表示禁用
shareKey: ''                  # 固定链接密钥，使链接在重启后仍然有效

guideTypes 会同时收窄两个 guide 界面：被禁用的类型会在工具的参数边界处被拒绝，而未知 id 或空列表会导致插件加载失败。

工作原理

该工具将 html 声明为其 schema 的最后一个参数，因此记录下来的调用参数会携带一个不断增长的文档前缀，而模型正在流式输出。卡片会在一个 null-origin 沙箱 iframe 中实时绘制该前缀；在 dispatch 时，最终 DOM 会完成协调，脚本运行一次。一份创作指南会教模型何时使用每种 artifact 类型（chart、diagram、mockup、interactive、art）以及如何创作它——系统提示中有一行清单，而更深入的按类型配方则通过 visualizer_guide 工具按需提供，从而让常驻提示保持精简。定稿时的静态检查会检查完成的文档（编译，但从不执行），并将缺陷报告回模型，以便在当轮内修复。

渲染出的文档可以通过一个小型桥接进行回传：脚本可以提交后续聊天提示（sendPrompt，经过验证并限流）、打开 http(s) 链接（openLink，会检查 scheme），以及跨渲染持久化状态（window.storage，按标题命名空间隔离——重新生成的 dashboard 能找到它之前的值）。文档会继承应用的 theme token，并且卡片内部的锚点点击绝不会让应用发生导航：片段会在原地滚动，外部链接会通过同一验证关卡。卡片会内联显示加载/运行时脚本失败，而不是静默地什么都不渲染。window.share（{exported, url}，外加一个 dsh-share-status window 事件）会告诉文档其自身当前的分享状态——只读；文档可以观察自己是否已被分享，但绝不能自行触发分享，因为那始终是一个有意的、一键式的 chrome 操作。
一张已定稿的卡片在分享前提供四种操作——全屏（将卡片扩展至视口大小；按 Escape 或再次点击即可退出）、下载（通过 Blob 生成自包含的 .html/.svg，无需服务器往返）、复制 HTML，以及导出（下一节介绍）——分享之后还会多出三种：分享、复制分享链接和取消分享。当文档失败时——某个库从未加载，或某个脚本抛出了异常——卡片的错误提示会再多出一项：一键请求模型修复渲染，因为定稿时的检查只编译脚本而不运行它们，所以它自身永远看不到这些失败。

分享

在你主动要求之前，不会向磁盘写入任何内容。点击导出会告诉宿主镜像一次已定稿的调用：宿主直接从自己的持久会话日志中读取该调用的 title/html——绝不从浏览器发送的任何内容中读取——检查它确实是一次已定稿且成功的 visualizer 调用，然后将其写入一个由两个平面各自独立地从 (title, html) 推导出的名称之下。再次导出同一次调用是无害的空操作——相同的字节、相同的名称、相同的文件。

写入确认后，导出按钮的位置会变成分享（在新标签页中打开 /artifacts/visualizer/?k=），旁边还会出现另外两个控件：复制分享链接（将该地址放入剪贴板，无需离开聊天）和取消分享——需要二次点击，先预备再确认，就像画廊自带的删除功能一样，而不是原生确认对话框——它会从磁盘移除导出文件，并将卡片恢复到分享前的状态。复制分享链接和取消分享只会在确实有内容被分享后才出现；在那之前没有任何东西可复制或取消分享。

- 名称包含标题的 kebab-case 短横线命名 slug，加上精确内容的摘要——-.html|.svg（hex-chart-performance-metrics-3531….html）。相同的渲染，永远相同的链接；内容改变后会在旧链接旁边生成一个新链接。下载只保留 slug。
- 链接内嵌能力密钥。 默认情况下，每次 harness 启动都会签发一个随机密钥，因此链接会在重启后失效（再次导出即可重新签发）；在配置中设置 shareKey 可固定一个密钥，链接便能在重启后继续有效。任何持有有效链接的人都可以打开它——请像对待机密一样对待它；这是不可猜测性，而非按用户认证。同一个密钥也用于限制导出请求本身，并设有速率限制以遏制脚本化循环。
- 构造上即安全。 分享的 HTML 在沙盒化框架内运行（无法访问你的会话、cookie 或工作区），并遵循与内联卡片相同的 CDN 允许列表；分享的 SVG 行为如同已剥离脚本的普通图片。响应带有 no-store 和加固标头，且只有常规导出文件可被提供——其他任何内容都会得到相同的未找到页面。
- 多层访问控制。 共享链接位于 harness 自身身份验证之后——没有有效的 harness 会话，就没有路由——并且在此之上，每个链接还携带上文所述的启动时能力密钥。两者缺一即失败关闭。只有真正在当前活跃会话中成功结算为 visualizer 的调用才能被导出——请求指定的是调用，而非字节，因此无法让宿主写入它自己尚未记录的内容。
- 内务管理。 早于 artifactRetentionDays（默认 30，0 = 永不）的产物会在插件激活时清扫——固定产物（见下文）无论时间多久均豁免。在没有 Web 服务器（TUI/无头）或没有活跃会话存储的配置上，共享功能根本不会出现。

产物库。 一个 Artifacts 标签页位于 Chat 旁边（如果你的 harness 构建有轨迹视图，也位于其旁边）：磁盘上当前所有导出，固定项优先，然后按最新排序，每项都有 Pin、Open、Copy link 和 Delete——只有有人明确导出的调用，而非每次渲染（在点击 Export/Copy-link 之前不会写入任何内容）。它读取的是 Share 控件写入的同一个导出目录，因此你在会话中选择共享的任何内容即使其原始聊天消息滚出视野后仍可访问。Pin 会将产物浮动到列表顶部，并使其免于保留清扫——单击即可，可逆，无需确认步骤。搜索框可按标题、类型（HTML/SVG）、日期筛选，仅固定项筛选标签可进一步缩小范围，计数显示当前显示的数量占总数的多少。切换到该标签页时总会重新获取；手动 Refresh 也会拾取在已停留在该标签页时结算的渲染。Delete 在删除任何内容前需要第二次点击——点击一次以准备，再次点击以确认；几秒后或你点击其他地方时它会自行还原（并移除该产物的固定，如果有的话）。该标签页本身仅在 shareArtifacts 启用时出现，与卡片的 Share 控件相同。

生产环境加固提示： 为获得更强的隔离，在生产环境中从与主 Web UI 不同的域提供产物（例如，将 artifactDir 指向 CDN 或静态主机发布的路径，主应用链接到该路径）。生成的页面随后与你的已认证界面完全不共享源——这是对 LLM 编写内容可用的最强纵深防御。静态发布者无法检查每次启动的密钥（?k=），因此请将此设置与固定的 shareKey 配对——跨重启稳定，且易于带入发布层所应用的任何门控。

“未找到”的回答意味着以下之一：harness 在使用默认每次启动密钥时重启了（从聊天中重新打开文档并重新共享），活跃的 shareKey 不再与链接中内置的密钥匹配，或者产物已过其保留窗口。

结算时文档检查
当一次调用尘埃落定，execute() 会静态检查已完成的文档（src/inspect.ts）。脚本主体只被编译，从不执行，因此语法错误会在无副作用的情况下暴露出来。属性按标签逐一扫描以查找重复项，id 检查重复定义，url(#…)/href="#…" 引用检查悬空目标；内联事件处理器接受同样的编译检查。

判定结果搭载在工具结果上，而工具结果是模型自己的通道。一次干净的渲染会显示 document check passed；有缺陷的渲染会列出其发现（带行号，最多六条），并附上在同一轮内修复并重新渲染的指令。工具结果会被记录，因此重放的会话会精确复现该判定。

该检查是启发式的，且有意保持保守。对于导入语句无法被干净提取的模块脚本，它拒绝作出判断，而不是冒险给出错误判定；它也无法对已经流式输出的内容设卡：其保证是作者引入的缺陷会在同一轮内被指出并修复，而不是保证从未绘制过任何中间帧。

开发

pnpm install
pnpm test     # vitest unit tests for both halves
pnpm build    # tsc emits lib/types declarations, tsdown bundles lib/ runtime + lib/client.js

两半都遵循 DeepSeek Harness 插件契约（ctx.effect() 注册、/invariant 下的不变量伴随模块）。客户端 bundle 保留加载器的惰性 CJS 工厂产物格式以及跨插件纯净规则：平台模块保持外部化，其余全部内联。