前言¶
在 DeepSeek Harness（DSH）裏做前端或本地 Web 應用聯調時，常見做法是在對話界面裏嵌一個 iframe，指向 http://127.0.0.1:5173/ 這類地址。DSH 的 Web GUI 往往通過反向代理以 https 對外暴露；遠程瀏覽器打開時，127.0.0.1 會解析到瀏覽器所在機器，而不是跑 DSH 的那臺主機；同時 https 頁面加載 http 資源還會觸發混合內容攔截。結果是 iframe 裏看不到本機 dev server，或頁面一片空白。
dsh-web-preview（倉庫 qoqpqpq/dsh-web-preview）把 DSH 主機上的 loopback 服務經 DSH 同源路徑轉發出去，預覽仍走 https 且與 GUI 同源，從而規避上述問題。下面介紹它是什麼、能做什麼、如何安裝與配置。
這是什麼¶
維護者爲 qoqpqpq，在插件目錄中歸類爲客戶端（面向 DSH Web 端注入 UI 與路由）。一句話：在 DeepSeek Harness GUI 內預覽任意本機端口上的 Web 服務，並提供嵌入標籤頁、浮動窗口，以及 Console / Network / Errors 診斷面板。
官方簡介：Preview any local web server inside the DeepSeek Harness GUI — remote-browser-safe same-origin proxy with embed tab, floating window and Console/Network/Errors toolbox.
核心功能¶
以下能力均來自項目 README 與 package.json 說明。
遠程瀏覽器可用
- 不經由裸
localhostiframe，避免 mixed content、錯誤 localhost、以及 DSH 側不必要的 X-Frame-Options 問題（README 表述爲 remote-browser-safe）。
兩種 UI 入口
- Embedded tab：對話窗口中的「Web Preview」標籤（React slot 組件）。
- Floating window：
PREVIEW按鈕 + 可拖拽浮動窗，適合側欄式預覽。
診斷工具箱
- 可摺疊的 Console / Network / Errors 面板；插件向被代理的 HTML 注入捕獲腳本，將控制台輸出、fetch/XHR 與運行時錯誤 beacon 回主機緩衝，客戶端輪詢展示。
任意本地端口
- 工具欄可輸入
localhost:5173、127.0.0.1:8080等；客戶端將 origin 編碼爲/web-preview/__proxy/<origin>/<path>，主機再轉發到對應 loopback 服務，無硬編碼端口。
配置默認值
- 可通過 profile 預填工具欄 URL、固定默認 upstream，以及爲硬編碼根路徑（例如
/cesium/）配置 extra same-origin 別名。
實現分層（便於理解行爲）
| 層 | 作用 |
|---|---|
Client（client.js） |
註冊 conversation.view 標籤與 shell.overlay 浮動窗；將 loopback URL 改寫爲同源 /web-preview/__proxy/...；輪詢 /web-preview/__events 獲取診斷。 |
Host（index.js） |
在 DSH webServer 上註冊代理與診斷路由；轉發到 http://<origin>/<path>，向 HTML 注入捕獲腳本並緩衝診斷事件。 |
當前 package 版本爲 1.1.2，許可證 MIT。Node 引擎要求：^22.19.0 || >=24.0.0；peer 依賴含 @deepseek-ai/cordis（>=4.0.0）與 react（^18.2.0）。
安裝與啓用¶
從 DSH Plugin Market（或任意 curated registry 源）安裝，命令以 README 爲準：
dsh plugin --profile web add dsh-web-preview
安裝後重啓 dsh web。README 說明：啓動時無需額外審批——該插件爲 bundle，而非動態 Cordis 插件。
配置¶
所有配置項可選，寫在 profile patch 中該插件的 config: 下（loader 僅將 config: 傳給插件）。示例路徑與字段來自 README：
# ~/.dsh/profiles/web/cordis.patch.yml
- id: dsh-web-preview
config:
# Prefill the toolbar with this URL (client-side convenience).
defaultUrl: "http://127.0.0.1:4173/"
# Optional fixed upstream for the bare /web-preview/<path> form.
defaultUpstream: "http://127.0.0.1:4173"
# Extra DSH-origin prefixes forwarded to a local service. Needed when the
# previewed app makes root-absolute requests that must stay on the same
# origin but are NOT under /web-preview (e.g. Cesium's hardcoded /cesium/).
extraAliases:
- prefix: "/cesium"
origin: "127.0.0.1:4173"
path: "/cesium"
# Optional override for the browser-error log (defaults to the OS temp dir).
logPath: "/tmp/dsh-web-preview-errors.log"
若 defaultUpstream 爲空，只能通過工具欄輸入 URL 選擇目標；動態路徑 /web-preview/__proxy/<origin>/<path> 仍可在零配置下指向任意 localhost origin。
典型用法¶
- 按上一節安裝並重啓
dsh web。 - 在本機啓動 dev server（例如 Vite 默認
5173或 README 示例中的4173）。 - 打開 DSH Web GUI：使用對話區的 Web Preview 標籤，或點擊 PREVIEW 打開浮動窗。
- 在工具欄輸入目標，例如
http://127.0.0.1:4173/或localhost:5173；客戶端會自動改寫爲 DSH 同源代理 URL 並在 iframe 中加載。 - 需要排查頁面行爲時，展開 Console / Network / Errors 面板；必要時可對
/web-preview/__clear重置診斷緩衝（由插件 UI 或路由能力支持，緩衝上限 2000 條事件）。
路由均掛在 DSH 同源下，常見條目包括：
| 路由 | 方法 | 用途 |
|---|---|---|
/web-preview/__proxy/<origin>/<path> |
any | 動態轉發到 http://<origin>/<path> |
/web-preview/<path> |
any | 轉發到 defaultUpstream（需已配置） |
<alias.prefix>/<path> |
any | 按 extraAliases 轉發 |
/web-preview/__events |
GET | 拉取緩衝診斷（支持 ?since=<id>） |
/web-preview/__config |
GET | 解析後的插件配置（Client 讀取默認值） |
適用場景與注意¶
適合誰
- 通過遠程瀏覽器訪問 DSH（反向代理 +
https），又需要在 GUI 裏看本機 dev server 的前端或智能體界面開發者。 - 需要在 iframe 內快速看控制台與網絡請求、而不必單獨開瀏覽器 DevTools 的場景（能力以插件注入的捕獲腳本爲準）。
安全與權限
- README 說明：主機僅轉發客戶端編碼後的 loopback 目標，不會代理任意遠程 URL；loopback 在編碼前由客戶端校驗。
- 捕獲腳本運行在 iframe 內，受 iframe
sandbox約束，僅向 DSH 同源 beacon。 - 插件以當前 DSH 進程權限運行；安裝前請自行審閱 GitHub 源碼 與 MIT 許可證。社區目錄 SkillHub 插件頁 爲獨立站點，與 DeepSeek / 幻方無官方從屬關係。
DSH 生態強調「一切皆插件」；dsh-web-preview 解決的是 GUI 預覽本機 Web 服務時的同源與 mixed content 問題，並附帶基礎診斷面板。更多細節見目錄頁與倉庫 README。
