前言¶
在 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
