dsh-pilot：基於 DSH 會話權限的瀏覽器自動化插件

前言¶

在 DSH 插件生態中，驅動瀏覽器的工具不少，大多通過讀取頁面的無障礙樹來工作，這是行業慣例，而非特色。關鍵在於權限模型。現有的插件通常只在工具調用的入口點檢查權限，這使得重定向、頁面內的鏈接點擊或歷史導航輕易繞過檢查。

dsh-pilot 修正了這一點。它不自己發明一套權限系統，而是直接讀取 DSH 會話自身的批准立場，並在網絡層通過請求攔截強制執行。這意味着無論頁面如何跳轉，只要會話沒有授權，導航就會被阻斷。

核心功能¶

該插件提供以下工具，用於在瀏覽器上下文中操作頁面：

pilot_navigate：處理 goto、後退、前進、刷新和標籤頁操作。這是唯一受 origin 限制的入口，決策在網絡層強制執行（包含重定向、鏈接跳轉和歷史移動）。
pilot_snapshot：返回頁面的無障礙樹，元素帶有 [ref=eX] 標記。支持 Shadow DOM 和同源 iframe。
pilot_act：通過 ref 執行點擊、輸入、按鍵、懸停、選擇、勾選、取消勾選和上傳。會報告控制台錯誤及是否觸發了導航。
pilot_wait：等待選擇器、文本、URL 片段或網絡空閒。返回 satisfied: false 而非盲目的重試循環。
pilot_screenshot：將視口或全頁 PNG 截圖保存到工作區，供人工查看。
pilot_close：在任務完成後關閉標籤頁。

安裝與啓用¶

安裝該插件需要 Node.js 版本在 ^22.19 或 >=24 之間。

dsh plugin --profile web add dsh-pilot

插件會自動使用已安裝的 Google Chrome 或 Microsoft Edge。若需使用 Chromium，需先運行 npx playwright install chromium 並在配置中設置 browserChannels: [chromium]。

權限模型¶

權限模型完全基於 DSH 會話，而非插件內部邏輯。

本地訪問：localhost 總是可用，前端測試無需額外配置。
預授權來源：通過 allowedOrigins 預先授權已知的良好來源。
會話跟隨：其餘訪問遵循 newOriginPolicy（默認爲 auto）：
- 會話批准策略爲 ask 時，對每個來源詢問用戶一次。
- 會話處於 danger-full-access（批准策略爲 never）時，靜默允許。
- 無批准通道（無人值守自動化）時，拒絕訪問。
網絡層邊界：決策在瀏覽器上下文的請求攔截器中執行，因此重定向、頁面內鏈接點擊和後退/前進操作無法繞過此檢查。彈窗（window.open）會在到達時被關閉。
憑證衛生：默認拒絕向密碼字段輸入內容，除非部署設置了 allowPasswordFields: true。上傳限制在工作區文件，下載指定目錄。

配置示例¶

在 DSH 的插件配置中，dsh-pilot 支持以下參數：

- id: pilot
  name: dsh-pilot
  config:
    headless: true
    browserChannels: [chrome, msedge, chromium]
    viewportWidth: 1280
    viewportHeight: 800
    navigationTimeoutMs: 15000
    actionTimeoutMs: 5000
    waitMaxMs: 60000
    snapshotMaxChars: 24000
    maxTabs: 8
    allowedOrigins: []
    newOriginPolicy: auto       # auto | ask | deny | allow
    allowPasswordFields: false
    profileDir: ''              # 留空表示每次運行使用隔離上下文
    screenshotDir: .dsh-pilot
    downloadDir: .dsh-pilot/downloads
    maxConsoleMessages: 100
    registerSkill: true

啓用 profileDir 可讓智能體在持久化的瀏覽器配置文件中操作，但需瞭解由此帶來的安全風險（已登錄狀態可能被訪問）。

已知限制¶

已批准來源的累積：已批准的 origin 會隨插件實例生命週期累積，並在同一 DSH 進程的會話間共享（即共享一個瀏覽器上下文）。
Canvas 內容：Canvas 渲染的內容無無障礙語義，pilot_screenshot 僅能將其展示給人類，截圖轉視覺模型的路線尚在計劃中。
無頭渲染差異：無頭模式下的渲染行爲與桌面瀏覽器存在差異，包括指針鎖定、部分 GPU 路徑以及操作系統對話框。
Ref 機制維護成本：Ref 機制基於 Playwright 內部實現。雖然 ariaSnapshot({ mode: 'ai' }) 是公開的，但將 ref 轉換爲選擇器的 aria-ref= 引擎未公開，且 Locator.ariaRef() 在 Playwright 1.60 中被移除。因此 playwright-core 被鎖定在 ~1.62.0 版本，後續版本更新需重新驗證 Shadow DOM 和 iframe 場景。
名稱衝突：該名稱並非唯一。guo6x/dsh-pilot 是一個較早的、不同的插件，安裝時需注意區分。

生態背景¶

DSH 插件獨立於 DeepSeek 或幻方官方應用商店，屬於社區目錄管理的插件生態。dsh-pilot 維護者 Viger1 還開發了 dsh-preview（視覺檢查）、dsh-review（缺陷審查）和 dsh-design（設計約束）等插件，它們可獨立安裝共存。

插件目錄：https://www.skillhub.cn/plugins/Viger1/dsh-pilot
源碼倉庫：https://github.com/Viger1/dsh-pilot