可视化卡片 MCJF28/dsh-visual-card

dsh-visual-card

可视化回答插件：AI 交一段 HTML，在对话里渲染成一个可交互的窗口——能点、能用键盘操作、能全屏、能导出。

效果

工具调用后，本轮回答下方出现一个窗口：

- 顶部工具条：标题 + 全屏 / 复制 / 下载
- 内容区是 AI 写的 HTML，脚本会真正执行（按钮、canvas、动画都能跑）
- 颜色自动跟随当前亮/暗主题

能做什么

- 图表、色板、布局示意
- 可点击的演示（切换状态、翻页、展开细节）
- 完整的小游戏（WASD 移动、canvas 逐帧动画）
- 需要键盘操作时，点进窗口才接管键盘，窗口外按键照常进输入框

键盘规则

| 操作 | 行为 |
| 点进窗口 | 窗口接管键盘，标题栏提示「键盘已交给窗口」 |
| 按 Esc | 释放键盘，回到输入框 |
| 点窗口外 | 自动释放 |
| 鼠标 | 始终正常（悬停、滚动、点击都不用先聚焦） |

实现上用了 iframe：AI 生成的脚本通常监听 document 的键盘事件，如果和宿主共用同一个文档，窗口外按键也会触发它。iframe 有独立的事件作用域，焦点不在里面就收不到键。

工具

render_visual({
title: '标题', html: '...', // 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-visual-card

安装程序会自动写进 dsh.profile.bundles，不用手改任何文件。

命令行方式（先完全退出应用）：

cd ~/.dsh/profiles/desktop
pnpm add dsh-visual-card

然后把包名加进 dsh.profile.bundles，重启应用。

安全说明

AI 生成的脚本运行在宿主页面里，不是沙箱。这是「能点击、能跑小游戏」的必然代价。

插件只约束「不引用外部资源」，不做代码审查。自己用没问题；如果要在不信任 AI 输出的场景里用，请先自行加沙箱。

已知限制

- 卡片固定渲染在本轮回答下方，不能插入正文中间——宿主的对话节点是固定 19 种，插件无法新增节点类型
- turnTail 槽位只在本轮结束后渲染，所以流式输出期间看不到卡片

DeepSeek Harness 的可视化回答：模型交出一段 HTML，在对话里渲染成一个可交互的窗口——能点、能用键盘操作、能全屏、能导出。

效果

工具调用后，本轮回答下方出现一个窗口：

- 工具条：标题 + 全屏 / 复制 / 下载
- 内容区是模型的 HTML，脚本会真正执行（按钮、canvas、动画都能跑）
- 颜色自动跟随当前亮/暗主题

能做什么

- 图表、色板、布局示意
- 可点击的演示（切换状态、翻页、展开细节）
- 完整的小游戏（WASD 移动、canvas 逐帧动画）
- 演示需要键盘时，点进窗口才接管键盘；窗口外按键照常进输入框

键盘规则

| 操作 | 行为 |
| 点进窗口 | 窗口接管键盘，标题栏会提示 |
| 按 Esc | 释放键盘，回到输入框 |
| 点窗口外 | 自动释放 |
| 鼠标 | 始终正常——悬停、滚动、点击都不用先聚焦 |
实现用 iframe 隔离。模型生成的脚本通常监听 document 上的 keydown；如果它们和宿主文档共用同一个 document，你在任何地方按键都会传到脚本里。iframe 有独立的事件作用域，只有焦点在 iframe 内时才会收到按键。

工具

render_visual({
title: 'Title',
html: '...',
// height is optional; omit it and the card sizes itself to its content (recommended)
})

高度自动：宽度固定后，卡片高度随内容变化，没有固定画框。内容超过配置的上限时，卡片内部滚动，所以再大的卡片也不会逼你滚动整个对话。

用主题变量，不要写死颜色：

--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-visual-card

安装器会替你写入 dsh.profile.bundles 条目，不用手动改文件。

从命令行安装（先完全退出应用）：

cd ~/.dsh/profiles/desktop
pnpm add dsh-visual-card

把包名加进 dsh.profile.bundles，重启应用。

安全

模型生成的脚本在宿主页面内运行，这不是沙箱。这是「可点击、能跑游戏」绕不开的代价。

插件只强制「不加载外部资源」，不做代码审查。个人使用没问题；如果你要指向不信任的模型输出，先加沙箱。

已知限制

- 卡片始终渲染在当轮回答下方，无法插到正文中间：宿主只支持固定的 19 种对话节点类型，插件加不了新类型
- turnTail 槽位要等轮次结束后才渲染，所以回答还在流式输出时看不到卡片