DSH Preview Plugin：在 iframe 中嵌入開發服務器並透明代理 SPA 流量

前言¶

DeepSeek Harness (DSH) 的設計理念是“一切皆插件”。在開發智能體或 Web 應用時，在 DSH 中直接預覽本地開發服務器的頁面是一個常見需求。傳統的預覽方式往往難以處理單頁應用（SPA）的路由跳轉、靜態資源加載以及後端 API 代理。dsh-preview-plugin 插件通過在 iframe 中嵌入開發服務器並提供透明的 SPA 代理，解決了這些問題。

是什麼¶

這是一個爲 DSH 提供的實時預覽標籤頁組件，由 RaulLazaro 維護。它允許將任意開發服務器嵌入到 DSH Web GUI 的預覽標籤頁中，並支持單頁應用的路徑代理和多應用 monorepo 場景。

安裝與啓用¶

啓用該插件需要修改 DSH Web 配置的 package.json。

添加爲依賴項
在 package.json 的 dependencies 字段中添加：

    {
      "dependencies": {
        "dsh-preview-plugin": "file:~/workspace/dsh-preview-plugin"
      }
    }

添加到 bundles
在 package.json 的 dsh.profile.bundles 數組中添加 dsh-preview-plugin：

    {
      "dsh": {
        "profile": {
          "bundles": [
            "...",
            "dsh-preview-plugin"
          ]
        }
      }
    }

重啓 DSH
執行重啓命令以加載插件：

    systemctl restart dsh

典型用法¶

基礎預覽¶

在 VPS 上啓動開發服務器（例如 npm run dev -- --host 0.0.0.0 --port 3000）。
打開 DSH Web GUI 的 Preview 標籤頁。
在 URL 字段輸入端口號（如 3000）並點擊 Go。
字段會自動切換到當前頁面路徑（例如 /preview/3000/laptops?page=2#specs），支持隨時編輯並按回車跳轉。

多應用 Monorepo¶

如果前端和後端運行在不同端口（例如前端 4321，後端 Payload CMS 3001），可以配置多端口代理：
1. 啓動兩個服務器。
2. 打開 Preview 標籤頁。
3. 在 URL 字段輸入前端端口（如 4321），在 Backend 字段輸入後端端口（如 3001，多個端口用逗號分隔）。
4. 點擊 Go。此時 API 請求（如 http://localhost:3001/api/...）會自動通過 /preview/3001/api/... 代理到 iframe 內。

Agent 工具¶

Agent 可以使用 set_preview_port 工具編程式配置端口：

set_preview_port(port: 4321, backendPorts: [3001])

工作原理與特性¶

SPA 代理：插件註冊了 /preview/:port/* 路由。對於靜態資源直接代理；對於 SPA 導航，返回根 HTML 由客戶端路由處理。
智能路由：支持片段鏈接（#section）跳轉，支持根相對資源（如 /assets/photo.png）和 srcset 的自動重寫。
真實流量：支持 fetch、XMLHttpRequest 以及表單提交，保持 Method、Body、Cookie 和 Set-Cookie 頭，實現完整的登錄和寫操作。
持久化：預覽配置（前端端口 + 後端端口）存儲在 ${DSH_HOME:-~/.dsh}/preview-plugin.json，重啓後自動恢復。
安全性：代理僅針對 127.0.0.1，iframe 沙箱屬性爲 allow-scripts allow-same-origin allow-forms allow-popups。

注意事項¶

非配置 URL 跳轉：瀏覽器原生的 location.href、location.assign 和 location.replace 無法被腳本攔截。插件會檢測到這些跳轉並嘗試將路徑重載回代理規則下，但應用內部應使用相對路徑或 import.meta.env.BASE_URL 來構建 URL。
端口限制：端口驗證僅允許 1 到 5 位數字。
權限：插件以 DSH 進程權限運行，安裝前應檢查源碼與許可證（MIT）。

結尾¶

該插件爲 DSH 提供了便捷的開發預覽能力，相關資源可在 GitHub 上查看：https://github.com/RaulLazaro/dsh-preview-plugin