前言¶
在 DSH Web UI 裏修改代碼時，經常需要同時看項目運行結果和工作區文件。@dsh-external/dsh-web-preview-float 提供兩個獨立懸浮窗：預覽 iframe 與代碼文件樹。它通過官方擴展點掛載，不改 DSH 核心。
這是什麼¶
@dsh-external/dsh-web-preview-float 是 DeepSeek Harness（DSH）Web UI 的懸浮預覽插件，由 WJNCT55555 維護。當前版本爲 0.1.0，許可證爲 MIT。GitHub 倉庫爲 https://github.com/WJNCT55555/dsh-web-preview-float。
它提供兩個可拖拽、可拉伸、可縮小的獨立懸浮窗：
- 預覽窗：使用
iframe直連項目 dev server。 - 代碼窗：提供工作區文件樹和代碼內容查看/編輯。
插件依賴官方擴展點 ctx.webServer、ctx.fs、ctx.sandboxPolicy 和自包含 DOM portal，不改 DSH 核心。
核心功能¶
預覽窗¶
預覽窗使用 iframe 加載項目 dev server。URL 會自動從項目 package.json 腳本探測，常見映射如下：
Vite→5173
Next/CRA→3000
Astro→4321
如果探測結果不適合當前項目，可以手動修改 URL。
窗口控制支持：
- 常用寬高比預設：
16:9 / 4:3 / 3:2 / 21:9 / 9:16 / 9:18 / 9:19.5 - 鎖定比例，使手動拉伸時保持比例
- 直接輸入
寬×高自定義尺寸 - 常用分辨率預設：
1920×1080 / 1366×768 / 390×844等 - 放大/還原，超出屏幕時自動縮放適配
代碼窗¶
代碼窗提供工作區文件樹，支持懶加載目錄，點擊文件查看內容。也可以直接編輯：點擊「編輯」進入編輯態，修改後點擊「保存」或按 Ctrl+S 確認寫入。
保存時會彈出確認，確認後寫入文件，並記錄 web-preview/code-edit 會話事件到 DSH 日誌。當前代碼窗爲純文本顯示，語法高亮未做。
對於二進制或超大文件（>256KB），會提示文件過大；寫操作限制在 1MB 內。
窗口狀態¶
兩個懸浮窗標題欄都有放大/還原按鈕，可一鍵放大到貼合屏幕。最小化成膠囊後也可以直接拖動。懸浮窗位置/大小狀態保存在內存中，刷新後回到默認位置。
安裝與啓用¶
README 給出的啓用方式是作爲 profile 的 patch 層安裝。插件自帶的 cordis.patch.yml 會插入以下配置：
- id: dsh-web-preview-float
name: '@dsh-external/dsh-web-preview-float'
安裝後重啓 DSH Web：
dsh web
瀏覽器裏會出現兩個懸浮窗。
本地開發¶
如果需要本地開發，先執行：
pnpm install
pnpm run typecheck
pnpm run test
pnpm run build
構建會產出 lib/index.js（node 半）和 lib/client.js（瀏覽器半）。
本地開發依賴 @deepseek-ai/cordis。它是 vendored 包，不在 npm 上；package.json 的 devDependencies 使用 link: 指向 harness checkout 的 vendor/cordis。
peerDependencies 聲明如下：
{
"@deepseek-ai/cordis": "^4.0.1-rc.1",
"react": "^18.2.0",
"react-dom": "^18.2.0"
}
典型用法¶
1、安裝後重啓 dsh web，瀏覽器裏會出現兩個懸浮窗。
2、在預覽窗中確認 URL。URL 會自動從項目 package.json 腳本探測（Vite→5173、Next/CRA→3000、Astro→4321），也可以手改。
3、在代碼窗中點擊文件查看內容；點擊「編輯」進入編輯態，修改後點擊「保存」或按 Ctrl+S 確認寫入。
4、需要調整視圖時，使用標題欄的放大/還原按鈕，或把窗口最小化成膠囊後拖動。
5、預覽窗可選擇寬高比預設（如 16:9、9:16）或分辨率預設（如 1920×1080、390×844），也可以直接輸入寬×高。
適用場景與注意¶
適合在 DSH Web UI 裏邊改代碼邊看 dev server 頁面效果，同時快速瀏覽工作區文件的場景。
插件會用到 ctx.webServer、ctx.fs、ctx.sandboxPolicy 等官方擴展點，並且代碼窗保存會寫入項目文件。因此安裝前應檢查源碼和許可證，並確認你信任當前項目與當前 DSH 進程權限。
當前版本爲 0.1.0，語法高亮未做，懸浮窗位置/大小狀態不會跨刷新保留。
