前言¶

在 DeepSeek Harness（DSH）的工作流中，智能體負責編寫代碼並聲稱任務完成。常見的問題是，智能體往往只依據源代碼讀取來判定工作結束，卻不會主動打開瀏覽器驗證實際渲染效果。這導致前端可能存在報錯、佈局異常或交互失效，最終需要人工介入。

簡介¶

dsh-preview 是一個工作流插件，由 Viger1 維護。它爲 DSH 智能體提供了一雙“眼睛”：一套無頭瀏覽器驗證工具和一個捆綁的 frontend-verify 技能。

與單純的瀏覽器工具不同，它的核心價值在於流程。它強制智能體執行一個閉環驗證流程，在智能體宣稱工作完成前，先完成打開頁面、檢查控制台、讀取佈局、交互測試、截圖記錄和修復錯誤的動作。

核心功能¶

插件提供 6 個瀏覽器工具和 1 個自檢技能。

瀏覽器工具¶

• browser_open：打開 http(s) URL 或本地文件/目錄（自動通過 127.0.0.1 服務）。返回頁面 ID 及加載時的控制台錯誤。
• browser_console：捕獲自頁面加載後的控制台消息和失敗的網絡請求。
• browser_read：確定性無視覺讀取。讀取文本、HTML 或特定選擇器的樣式（包含邊界框和關鍵計算樣式）。
• browser_interact：對選擇器執行點擊、輸入、按鍵或滾動操作，並報告交互引起的錯誤。
• browser_screenshot：保存視口、全頁面或單元素 PNG 到工作區。
• browser_close：在驗證完成後關閉頁面。

frontend-verify 技能¶

這是一個自動化驗證循環，將上述工具串聯起來：
1. 打開頁面
2. 檢查控制台
3. 讀取佈局事實
4. 執行交互
5. 截圖記錄
6. 修復問題
7. 重新驗證

該技能會如實報告驗證通過的內容，以及明確指出無法驗證的部分（例如 GPU 渲染精度或指針鎖定手感），而不是籠統地聲稱完成。

安裝¶

在終端執行以下命令即可安裝：

dsh plugin --profile web add dsh-preview

配置¶

插件配置位於 profile 的 cordis.patch.yml 中。以下是默認配置示例：

- id: preview
  name: dsh-preview
  config:
    headless: true
    browserChannels: [chrome, msedge, chromium]
    viewportWidth: 1280
    viewportHeight: 800
    navigationTimeoutMs: 15000
    actionTimeoutMs: 5000
    screenshotDir: .dsh-preview
    maxReadChars: 20000
    maxConsoleMessages: 100
    allowedHosts: []          # 允許訪問的額外主機名
    registerSkill: true       # 啓用內置的 frontend-verify 技能

安全模型規定：
* localhost / 127.0.0.1 / ::1 永遠被允許。
* 其他主機默認拒絕，需在 allowedHosts 中顯式授權。
* 本地路徑以只讀方式在臨時 127.0.0.1 端口提供服務。

注意事項¶

1. 運行環境：需要安裝 Node.js，版本要求爲 ^22.19 || >=24。
2. 瀏覽器支持：插件使用 Playwright，支持你機器上的任意 Chromium（Chrome 和 Edge 會自動檢測，否則需運行 npx playwright install chromium 並配置 browserChannels）。
3. 渲染差異：無頭渲染與真實桌面瀏覽器存在差異。指針鎖定、部分 GPU 代碼路徑和 OS 對話框的行爲可能不同。內置技能會提示智能體注意這些差異。
4. 視覺能力：目前沒有視覺描述能力。機器驗證通過 browser_read 和 browser_console 進行，截圖僅用於人類查看。
5. 進程模型：每個 dsh 進程共享一個瀏覽器進程。頁面是輕量的，但並行運行的智能體會共享該進程。

總結¶

dsh-preview 將“驗證”從人工任務轉化爲智能體的內置能力。它不提供額外的“超能力”，而是建立了一套嚴謹的驗證紀律，讓智能體在完成代碼構建後，能自主完成前端驗收閉環。