内联可视化卡片 anneqaq/dsh-widget

dsh-widget

为 DeepSeek Harness 提供内联可视化。模型用一次工具调用递交一个自包含的 SVG 或 HTML 片段，该片段就作为一张卡片渲染在对话里 —— 流程图、图表、时间线、对比表格、带标注的版式 —— 而不是被写成文字描述。

test
license
dsh

安装

从 GitHub 安装：

dsh plugin --profile web add github:anneqaq/dsh-widget

或者从一个本地检出安装：

dsh plugin --profile web add /absolute/path/to/dsh-widget

然后重启 dsh web。插件在启动时挂载，没有热重载。

确认配置树里出现了这一行：

dsh --profile web --dump-config | grep -A2 dsh-widget

如果 pnpm 报 ERR_PNPM_ADDING_TO_ROOT —— 自带的 web profile 是单包 workspace，因此触发了它的根检查 —— 放行根写入即可：

npm_config_ignore_workspace_root_check=true dsh plugin --profile web add github:anneqaq/dsh-widget

卸载：

dsh plugin --profile web remove dsh-widget

本包没有构建步骤，lib/ 已随仓库提交，所以从 git 安装不需要 prepare 脚本，也不需要 pnpm 的 allowBuilds 授权 —— 安装时不会在你的机器上执行任何构建代码。

使用

工作由模型完成，没有需要你配置的东西。要一个可视化的结果，它就会调用 render_widget：

把这个服务的请求生命周期画成一条时间线。

render_widget 接受四个参数：

| 参数 | 必填 | 含义 |
| html | 是 | 一个自包含的 SVG 或 HTML 片段。 |
| title | 否 | 卡片上方的标题；同时也是 frame 的标题。 |
| height | 否 | frame 高度（CSS 像素）。默认 420，钳制在 80–2000。 |
| allowScripts | 否 | 允许片段内执行脚本。默认关闭。 |

工具只返回一句简短确认。片段不会被回显进模型上下文 —— 卡片从记录下来的调用参数里读取它，因此一张大图在会话记录里只占一份，而不是两份。

工作原理

两半，同一个名字：

dsh-widget/
├── package.json dsh.bundle.patch + dsh.client，无依赖 ├── cordis.patch.yml 插入本插件的 node 半边行 ├── icon.svg 插件图标（显示元数据） ├── locale/ 显示元数据：en.json / zh.json ├── lib/ │ ├── index.js node 半边 → 注册工具 + 一段提示词 │ └── client.js 浏览器半边 → 渲染该工具的调用 └── test/ 36 项测试，不需要浏览器、不需要宿主

node 半边注册一个朴素的 ToolDefinition，以及一段陈述创作约定的系统提示词。
它不持有状态，也不绘制任何东西。

浏览器半边在按键索引的 tool.call.toolview 插槽里认领线名 render_widget。由于该插槽以线协议的工具名为键，这是纯增量的：它从不触碰自带的工具卡片。

没有构建步骤。 浏览器半边是用 shell 期望的
window.__ModuleLoader__.load({ id, factory }) 惰性 CJS 格式手写的，因此包直接
发布 lib/client.js —— 没有 tsdown，没有 TypeScript，没有打包器。它唯一 require 的是 react，而 react 是 shell 冻结的平台模块表成员。

完全没有依赖。 bundle 是通过它在 profile 下的真实路径加载的，所以像 @deepseek-ai/dsh-tools 这样的裸标识符只有在包自带 node_modules 时才能解析。
本包不导入任何东西，这正是它能从任意目录安装的原因 —— 包括符号链接的开发检出。
defineTool 助手本会生成的输入校验，改写在 lib/index.js 里。

隔离

片段由模型编写，因此按不可信内容处理。它通过沙箱化的 srcdoc frame 渲染，绝不通过应用自身 DOM 里的 dangerouslySetInnerHTML。

- sandbox="" —— 无脚本、不透明源。仅当调用方以 allowScripts: true 要求时才用
sandbox="allow-scripts"，且绝不与 allow-same-origin 同时出现（这一对会让
片段触及宿主文档）。
- frame 的 CSP 是 default-src 'none'，加上 img-src data: blob:、 style-src 'unsafe-inline'、connect-src 'none'。一个走神写下的 CDN 引入或一次 fetch 会失败关闭，而不是悄悄外泄数据。
- 卡片自身不持有主题状态。frame 注入应用当前正在绘制的调色板，通过
body[data-ds-dark-theme] 跟踪，因此实时切换主题会重新渲染 frame。

值得知道的限制

- 卡片在片段参数闭合时出现，而不是在它流式传输的过程中。读一个只到一半的片段会渲染出破损的标记，因此视图在 html 完整之前显示占位符 —— 这通常早于工具结果落地。
- 单片段 512 KB。 标记存放在会话日志里，所以这个上限同时约束会话记录和线上请求。
- frame 内没有网络，这是设计使然。一切都内联。
- 卡片是一个工具行，不是正文。 它渲染在调用所在的那一轮位置上。段落中间的内联渲染无法通过公开扩展点实现；tool.call.toolview 插槽是被认可的接缝。

兼容性

package.json 声明 engines.dsh 为 =0.1.2-rc.1 =0.1.5-alpha.1 =0.1.6-0 =0.1.7-0 =0.1.2-rc.1 <0.2.0 不接纳 0.1.5-rc.1。每个新的上游预发布元组都需要自己的子句。

本包在 0.1.7-rc.2 上开发与验证，并且故意不声明对 @deepseek-ai/dsh-* 的 peerDependencies：它不导入任何宿主包，而 peerDependencies 是一个强制的安装门禁（evaluatePluginCompatibility，失败即关闭），声明它会增加一道没有增加事实的门。engines.dsh 是声明式的，并且会被插件市场读取用于兼容性展示。

开发

npm test

36 项测试，不需要浏览器、不需要宿主。它们跑的是真实投影：决定卡片是否渲染的流式 JSON 恢复、frame 的 CSP，以及工具契约。

其中两项检查是刻意的回归护栏，而不是行为测试 —— 模块必须不导入任何东西， output.schema 必须保持闭合。两者编码的都是会在宿主启动时大声失败、而不是在单元测试时报错的错误。

许可证

MIT