前言¶
在 DeepSeek Harness（DSH）里让智能体改前端，常见的工作方式是：把 HTML 交给智能体，智能体改完，你再看渲染结果；不满意，再在对话里描述「按钮偏左、间距不对、这个区域换一版」。描述越含糊，返工越多，改完还得自己打开页面核对。
Visual Sandbox（@local/dsh-visual-sandbox，GitHub 仓库 Surenkh/dsh-visual-sandbox，维护者 Surenkh）把这个流程换了个方向。它把界面渲染到 DSH 右侧面板，你在上面用鼠标点选元素、写一行备注，插件把这些标注连同元素的选择器、尺寸、样式一起整理成一份结构化的目标清单，交给智能体只改你点过的那些块。下面介绍它的能力、安装方式和典型用法。
这是什么¶
Visual Sandbox 是一个 DSH 客户端插件，分类为客户端（client-side）。它的定位是「可标注的 UI 预览」：在 DSH 右侧打开一个工作台，渲染工作区里的 HTML 或本地 URL，提供四档预览框架（Responsive / Mobile / Tablet / Desktop），支持在元素级别标注，并把标注打包成精确的目标交给智能体做外科手术式修改。
它解决的问题是：UI 评审中「指哪儿打哪儿」，而不是用一段文字描述哪儿不对。
需要说明的是，本插件以当前 DSH 进程的权限运行。安装后它会加载进 DSH 客户端，因此安装前应先检查插件源码与许可证（README 声明为 MIT），确认符合你的使用环境。
核心功能¶
四档预览框架。 Responsive 为流式铺满，Mobile 为 390×844，Tablet 为 768×1024，Desktop 为 1024×720。固定尺寸的框架按可用宽度适配，纵向需要时滚动，因此 Mobile 框架能以接近实际尺寸显示，而不是被压到适配面板高度。框架在真正溢出画布前保持居中。
预览缩放。 支持 Fit、50%、75%、100%、110%、120%、125%、150%、200%。固定框架超出画布时可平移和滚动，移动端原型可以按实际尺寸或更大比例评审；Responsive 始终保持全出血。
元素级 Edit UI。 在 Select 中选 Element 或 Region，悬停时元素出现高亮轮廓和实时选择器标签，点击即可固定。弹出框里写备注，Enter 发送，Shift+Enter 换行。
外科手术式标注。 每条标注会带上编号、备注、所在的框架与视口（如 mobile 390x844）、唯一 CSS 路径、截断后的 outerHTML 和可见文本、像素矩形框与归一化百分比，以及布局、颜色、字体、边框、flex/grid、阴影等计算样式。会话注入给智能体的规则是：只修改这些目标。
版本快照。 工作区文件会记录真实的渲染历史——首次加载、每次智能体刷新、每次从磁盘重新读取，最新的在最前，默认选中 latest。内容完全相同的文档会折叠到上一条，而不是堆积。选择旧版本立即切换预览，不改动磁盘上的文件。快照存放在宿主内存中，按会话上限 8 个版本 / 8 MB；超过 2 MB 的文档仍可预览，但不计入记录。URL 预览或没有历史记录的文件，Version 字段呈禁用并显示 Latest。
来源自动识别。 插件会扫描工作区（跳过 node_modules、.git、.next、.nuxt 及缓存目录），按新到旧列出 HTML 文件，无活动来源时自动加载最新的。工作区预览会把本地样式表、脚本、图片、媒体、字体与 CSS url(...) 资源内联成一份自包含文档，并移除 CSP 与 base 标签。需要原始服务器的模块导入仍会失败，这类情况应改用实时 URL。
Expand Narrow Containers。 移除硬编码的移动端 demo 用的 max-width 包裹层，让移动优先的页面在较宽框架下铺满。仅对工作区预览生效。
跨域 URL 框架无法被 inspect，此时改为框选矩形，编号和备注流程一致。
安装与启用¶
前置条件是已安装 DeepSeek Harness（桌面应用或 dsh web）并且有可用 profile。插件以 bundle 包形式分发，按官方 README，需从克隆安装而非 npm。
先克隆仓库：
git clone https://github.com/Surenkh/dsh-visual-sandbox.git
然后在 ~/.dsh/profiles/<profile>/package.json 中注册：
{
"dependencies": {
"@local/dsh-visual-sandbox": "link:../../path/to/dsh-visual-sandbox"
},
"dsh": {
"profile": {
"bundles": [
"@deepseek-ai/dsh-base",
"@deepseek-ai/dsh-web-app",
"@local/dsh-visual-sandbox"
]
}
}
}
如果不想保留本地克隆，也可以用 git 依赖：
"@local/dsh-visual-sandbox": "github:Surenkh/dsh-visual-sandbox"
最后安装依赖：
cd ~/.dsh/profiles/<profile>
pnpm install
重启 Harness，并刷新一次应用页面，让客户端部分加载。插件随后会出现在右侧边栏的 guide 中，名为 Visual Sandbox。
升级方式与安装一致：git pull、pnpm install、重启、刷新。
典型用法¶
1、加载来源。在 Source 里输入工作区路径如 index.html，或从列表中选择，也可以粘贴 http://localhost:3000，按 Enter 加载。
2、选择框架。在 Device & Type 中选 Responsive、Mobile、Tablet 或 Desktop；对固定框架用 Preview scale 放大到 110%、120% 及以上，画布会在原型大于面板时滚动。
3、切换到 Edit UI。在 Select 中选 Element 或 Region，悬停某个块，它会显示轮廓并给出选择器，点击固定它。
4、逐个写备注。在弹出框中输入一行说明，按 Enter 提交。有多个错误块就重复这一步。
5、Send All。在对话里补充上下文，让智能体按标注做精确修改。
面板也可以由右上角的 sparkle 标记打开或关闭，或由智能体通过 open_visual_sandbox 打开。每次打开都会恢复该会话最新的预览，工作台不会落到空状态。
与智能体的配合¶
插件提供以下工具：
| 工具 | 用途 |
|---|---|
open_visual_sandbox |
打开工作台，可选传入 path、url 或 platformMode |
set_sandbox_platform_mode |
由智能体切换预览框架 |
get_visual_annotations |
以结构化目标形式返回标注队列 |
clear_visual_annotations |
修改完成后清空队列 |
refresh_visual_sandbox |
从磁盘重新加载预览 |
每个会话会带上一段提示词，其中包含两条强制的预览规则：不要在预览页面里伪造手机边框、Dynamic Island 或状态栏；当存在可预览文件变化时，自动重新打开或刷新沙箱。
当队列中存在标注时，这段提示词还会把每个目标以 ### Annotation #N 的形式注入，包含选择器、样式和文本，并附带外科手术式修改规则：只修改这些目标，然后调用 refresh_visual_sandbox。
适用场景与注意¶
适合需要在 DSH 里做前端评审、原型走查或迭代产物核对的场景：本地 .html 文件、dev server、Expo web、Flutter web、Tauri 或 Electron 渲染目标等本地 URL 都可以预览。
几点注意：
- 跨域 URL 无法 inspect 元素，只能框选矩形。
- 需要原服务器的模块导入在工作区预览里会失败，改用实时 URL。
- 超过 2 MB 的文档可以预览但不记录进版本历史；快照上限为每会话 8 个版本 / 8 MB。
- 插件以当前 DSH 进程权限运行，安装前应检查源码与许可证。本插件 MIT 许可，仓库中已提供 LICENSE 与 CHANGELOG。
- 社区目录是独立站点，与 DeepSeek / 幻方无官方从属关系，插件也不是 npm 包。
结尾¶
Visual Sandbox 的价值在于把「用文字描述界面问题」换成「在界面上点选问题并交给智能体」。四档框架、元素级标注和版本快照覆盖了从移动端到桌面端的评审需求，外科手术式修改规则降低了改错范围的风险。
目录页：https://www.skillhub.cn/plugins/Surenkh/dsh-visual-sandbox
GitHub：https://github.com/Surenkh/dsh-visual-sandbox
