前言¶
在 DeepSeek Harness（DSH）里做智能体或日常对话时，模型经常输出图表说明、布局示意或可点按的演示，但纯 Markdown 或代码块只能「看」，很难在同一轮回答里直接操作。把 HTML 贴进外部浏览器又打断对话流。
dsh-visual-card 是面向 DSH 客户端的插件：模型通过工具交出一段 HTML，插件在本轮回答下方渲染成带工具条的可交互窗口，支持全屏、复制与下载，并能把卡片按会话与轮次持久化。下面介绍它的定位、能力与安装用法。
这是什么¶
- 包名：
dsh-visual-card（仓库 MCJF28/dsh-visual-card） - 维护者：MCJF28
- 分类：客户端（
dsh.client，平台 web，immediately: true） - 版本：1.0.0（以 package.json 为准）
- 许可证：MIT
插件解决的是「可视化回答落在对话内」：AI 生成交互式 HTML，用户在 Harness 里即可点击、用键盘操作（在规则范围内）、全屏查看或导出，配色跟随当前亮/暗主题。
核心功能¶
渲染形态¶
工具调用完成后，本轮回答下方出现一个窗口（宿主使用 turnTail 槽位，流式输出结束前轮次未闭合时不会出现卡片）：
- 顶部工具条：标题，以及全屏、复制、下载
- 内容区为模型提供的 HTML，允许执行脚本时按钮、canvas、动画等会真正运行
- 颜色通过主题变量适配，而非写死色值
能承载的内容类型¶
资料中列举的用途包括：图表、色板、布局示意；可点击演示（状态切换、翻页、展开细节）；以及完整小游戏（例如 WASD 移动、canvas 逐帧动画）。需要键盘时，点进窗口才接管键盘；在窗口外按键仍进入输入框。
键盘与 iframe¶
实现上使用 iframe，使 AI 脚本监听 document 的键盘事件时，不会在窗口外误触发。规则摘要：
| 操作 | 行为 |
|---|---|
| 点进窗口 | 窗口接管键盘，标题栏提示「键盘已交给窗口」 |
| 按 Esc | 释放键盘，回到输入框 |
| 点窗口外 | 自动释放 |
| 鼠标 | 悬停、滚动、点击无需先聚焦窗口 |
模型侧工具¶
模型可调用 render_visual，传入标题与 HTML；height 可选，省略时按内容自动定高（推荐）。
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。
设置与存储¶
在应用内 设置 → 可视化 可配置（改动即时写入 ~/.dsh/visual/settings.json）：
| 项 | 作用 |
|---|---|
| 高度上限 | 内容高度超过视口高度的设定比例（40–100%）时，卡片内部滚动 |
| 允许执行脚本 | 关闭后仅静态展示；脚本是唯一的安全风险来源 |
| 每个会话保留轮数 | 10–2000，超出旧轮次在写入时丢弃 |
| 每轮最多卡片数 | 1–50，超出只保留最新 |
| 清空历史 | 删除 cards.json，带二次确认 |
卡片按「会话 + 轮次」写入 ~/.dsh/visual/cards.json，重启后仍在；保留策略由上述设置决定。删除 ~/.dsh/visual 只会丢失历史可视化，不影响插件功能。
已知限制¶
- 卡片只能出现在本轮回答下方，不能插入正文中间（宿主对话节点类型固定，插件无法新增节点类型）
turnTail在本轮结束后才渲染，流式过程中看不到卡片
安装与启用¶
DSH 生态里插件通常通过内置安装或 profile 依赖接入；本插件不要凭仓库名自行拼接未在文档出现的 CLI 命令。
推荐：内置插件安装程序。 打开「设置 → 内置插件」，粘贴包名并安装，然后重启应用：
dsh-visual-card
安装程序会自动写入 dsh.profile.bundles，无需手改文件。
命令行方式（需先完全退出应用）：
cd ~/.dsh/profiles/desktop
pnpm add dsh-visual-card
将包名加入 dsh.profile.bundles 后重启应用。
插件以当前 DSH 进程权限运行；安装前可在 GitHub 查看源码与 MIT 许可证，自行评估是否满足使用场景。
典型用法¶
- 按上一节完成安装并重启 DSH。
- 在对话中让模型调用
render_visual，传入title与完整html字符串。 - 若需要交互或小游戏，在设置中保持「允许执行脚本」开启；仅展示静态页面时可关闭以降低风险。
- 需要长时间操作时点击卡片内部以接管键盘，用 Esc 或点击外部释放。
- 使用工具条全屏查看，或通过复制、下载带走 HTML。
模型写 HTML 时引用主题变量，可避免在亮/暗主题切换时出现对比度问题。
适用场景与注意¶
适合：个人或可信环境下的 Harness 对话——需要图表、演示页、轻量交互原型或小游戏，且希望结果留在会话里并可再次打开。
安全：README 明确说明，AI 生成的脚本运行在宿主页面里，并非隔离沙箱；这是可点击、可跑小游戏的代价。插件仅约束不引用外部资源，不做代码审查。若面对不可信模型输出，应自行增加沙箱或关闭脚本执行。
生态说明：社区目录 SkillHub 上的 dsh-visual-card 页 与 GitHub 仓库由社区维护，与 DeepSeek / 幻方无官方从属关系；DSH 本身遵循「一切皆插件」的扩展方式。
结尾¶
dsh-visual-card 把「一段 HTML」变成对话内的可交互卡片，并配套高度策略、键盘焦点、持久化与导出能力。若你正在 DSH 里做可视化回答或交互演示，可按文档安装 dsh-visual-card，从 render_visual 与主题变量入手。
- 目录页：https://www.skillhub.cn/plugins/MCJF28/dsh-visual-card
- GitHub：https://github.com/MCJF28/dsh-visual-card
