dsh-visual-card
中文 | English
可视化回答插件：AI 交一段 HTML，在对话里渲染成一个可交互的窗口——能点、能用键盘操作、能全屏、能导出。
效果
工具调用后，本轮回答下方出现一个窗口：
- 顶部工具条：标题 + 全屏 / 复制 / 下载
- 内容区是 AI 写的 HTML，脚本会真正执行（按钮、canvas、动画都能跑）
- 颜色自动跟随当前亮/暗主题
能做什么
- 图表、色板、布局示意
- 可点击的演示（切换状态、翻页、展开细节）
- 完整的小游戏（WASD 移动、canvas 逐帧动画）
- 需要键盘操作时，点进窗口才接管键盘，窗口外按键照常进输入框
键盘规则
| 操作 | 行为 |
|---|
| 点进窗口 | 窗口接管键盘，标题栏提示「键盘已交给窗口」 |
| 按 Esc | 释放键盘，回到输入框 |
| 点窗口外 | 自动释放 |
| 鼠标 | 始终正常（悬停、滚动、点击都不用先聚焦） |
实现上用了 iframe：AI 生成的脚本通常监听 document 的键盘事件，如果和宿主共用同一个文档，窗口外按键也会触发它。iframe 有独立的事件作用域，焦点不在里面就收不到键。
工具
render_visual({
title: '标题',
html: '<div>...</div>',
// height 可选：不给就按内容自动定高（推荐）
})
高度是自动的：宽度固定后，内容多高卡片就多高，不套固定框。内容超过设置的比例上限时，改为卡片内部滚动 —— 再大的卡片也不会逼你滚动整个对话才能看全貌。
写 HTML 时用主题变量，不要写死颜色：
--v-bg-base、--v-bg-layer-1/2、--v-border、--v-text、--v-text-dim、--v-brand、--v-success/warn/error
设置
设置 → 可视化：
| 项 | 作用 |
|---|
| 高度上限 | 卡片高度按内容自动决定；超过这个比例（40–100% 视口高）就改成卡片内部滚动，不逼你滚动整个对话才能看全貌 |
| 允许执行脚本 | 关掉后按钮、动画、小游戏都不运行，只显示静态内容。脚本运行在宿主页面里，这是唯一的安全风险来源 |
| 每个会话保留轮数 | 超出的旧轮次在写入时丢弃（10–2000） |
| 每轮最多卡片数 | 一轮里超过这个数量只留最新的（1–50） |
| 清空历史 | 清掉 cards.json，带二次确认 |
改动即时保存到 ~/.dsh/visual/settings.json。
存储
卡片按「会话 + 轮次」落盘到 ~/.dsh/visual/cards.json，重启后仍在。保留轮数与每轮上限由设置决定。
删掉这个目录只会丢失历史可视化，不影响功能。
安装
推荐用 DSH 内置插件安装程序。 打开「设置 → 内置插件」，在安装输入框里粘贴下面这一串（就是 pnpm add 后面的地址），点安装，再重启应用：
github:MCJF28/dsh-visual-card
安装程序会自动把包写进 dsh.profile.bundles，不用手动改任何文件。
习惯命令行的话：先完全退出应用，再在 profile 目录执行
cd ~/.dsh/profiles/desktop
pnpm add github:MCJF28/dsh-visual-card
然后把包名加进 dsh.profile.bundles，重启应用。
安全说明
AI 生成的脚本运行在宿主页面里，不是沙箱。这是「能点击、能跑小游戏」的必然代价。
插件只约束「不引用外部资源」，不做代码审查。自己用没问题；如果要在不信任 AI 输出的场景里用，请先自行加沙箱。
已知限制
- 卡片固定渲染在本轮回答下方，不能插入正文中间——宿主的对话节点是固定 19 种，插件无法新增节点类型
turnTail 槽位只在本轮结束后渲染，所以流式输出期间看不到卡片
English | 中文
Visual answers for DeepSeek Harness: the model hands over a block of HTML and it renders as an interactive window inside the conversation — clickable, keyboard-operable, fullscreen-capable, exportable.
What it looks like
After the tool call, a window appears below the turn's answer:
- Toolbar: title plus Fullscreen / Copy / Download
- The content area is the model's HTML, and its scripts really run (buttons, canvas, animation all work)
- Colors follow the active light/dark theme automatically
What you can build
- Charts, color swatches, layout sketches
- Clickable demos (state toggles, paging, expanding detail)
- Complete small games (WASD movement, per-frame canvas animation)
- When a demo needs the keyboard, clicking into the window takes it over; keys outside keep going to the composer
Keyboard rules
| Action | Behavior |
|---|
| Click into the window | The window takes the keyboard; the title bar says so |
| Press Esc | Release the keyboard, back to the composer |
| Click outside | Released automatically |
| Mouse | Always works — hover, scroll and click need no focus first |
The implementation uses an iframe. Scripts generated by the model typically listen for keydown on document; if they shared the host document, keys pressed anywhere would reach them. An iframe has its own event scope, so it only receives keys while focus is inside.
Tool
render_visual({
title: 'Title',
html: '<div>...</div>',
// height is optional; omit it and the card sizes itself to its content (recommended)
})
Height is automatic: once the width is fixed, the card is as tall as its content — no fixed frame. When the content exceeds the configured cap, the card scrolls internally, so even a large card never forces you to scroll the whole conversation.
Use theme variables instead of hard-coded colors:
--v-bg-base, --v-bg-layer-1/2, --v-border, --v-text, --v-text-dim, --v-brand, --v-success/warn/error
Settings
Settings → Visual:
| Item | Effect |
|---|
| Height cap | Card height follows its content; above this share of the viewport (40–100%) the card scrolls internally instead of forcing a page scroll |
| Allow scripts | When off, buttons, animation and games do not run — only static content renders. Scripts run inside the host page, which is the only source of risk here |
| Turns kept per conversation | Older turns are dropped on write (10–2000) |
| Max cards per turn | Beyond this many in one turn only the newest are kept (1–50) |
| Clear history | Deletes cards.json, behind a second confirmation |
Changes save immediately to ~/.dsh/visual/settings.json.
Storage
Cards are persisted per conversation and turn to ~/.dsh/visual/cards.json, so they survive a restart. Retention is governed by the settings above.
Deleting the directory only loses visual history; functionality is unaffected.
Install
The built-in plugin installer is the recommended way. Open Settings → Built-in Plugins, paste the string below into the install box — it is exactly what follows pnpm add — then press install and restart the app:
github:MCJF28/dsh-visual-card
The installer writes the package into dsh.profile.bundles for you; no manual file edits.
Prefer the command line? Quit the app completely first, then from the profile directory:
cd ~/.dsh/profiles/desktop
pnpm add github:MCJF28/dsh-visual-card
Add the package name to dsh.profile.bundles yourself and restart the app.
Security
Scripts generated by the model run inside the host page — this is not a sandbox. That is the unavoidable cost of "clickable, can run games".
The plugin only enforces "no external resources" and performs no code review. Fine for personal use; if you point it at model output you do not trust, add a sandbox first.
Known limits
- Cards always render below the turn's answer and cannot be placed mid-text: the host supports a fixed set of 19 conversation node kinds, and a plugin cannot add one
- The
turnTail slot only renders after the turn closes, so nothing appears while the answer is still streaming
