dsh-browser-tool：DSH 瀏覽器工具

DSH（DeepSeek Harness）採用“一切皆插件”的架構。在需要讓 Agent 在會話中驅動 Chromium、打開標籤頁、執行腳本或觀察頁面時，dsh-browser-tool 是核心組件。該工具移植自 oh-my-pi 的 browser 工具，保持了 open / run / close 的三段式語義，並提供了 Browser Relay 模式以接管用戶本地的真實 Chrome。

目前該倉庫已歸檔，開發工作已遷移至 mtaech/melon 倉庫。

安裝與啓用¶

安裝前必須先停止正在運行的 dsh 進程。在服務運行期間修改依賴樹會導致運行中的進程讀到殘缺的模塊。

安裝插件：

    dsh plugin --profile <你的 profile> add dsh-browser-tool

或者通過 npm 直接添加：

    cd ~/.dsh/profiles/<你的 profile>
    pnpm add github:mtaech/dsh-browser-tool

註冊到 Profile：
在該 profile 的 package.json 中，將插件添加到 dsh.profile.bundles 數組（建議放最後）：

    {
      "dsh": {
        "profile": {
          "bundles": ["@deepseek-ai/dsh-base", "@deepseek-ai/dsh-web-app", "dsh-browser-tool"]
        }
      }
    }

配置 Sharp：
截圖功能依賴 sharp 的原生模塊，pnpm 默認會跳過其構建腳本。需在 profile 的 pnpm-workspace.yaml 中放行：

    allowBuilds:
      sharp: true

驗證：
重啓 dsh 後，檢查配置是否生效：

    dsh --profile <你的 profile> --dump-config | grep dsh-browser-tool

核心功能¶

open：瀏覽器來源¶

支持四種瀏覽器來源，通過 action:"open" 啓動：

headless：進程內啓動無頭 Chromium，使用 puppeteer-core + @puppeteer/browsers 自動下載，支持 stealth 注入。
spawned：detached 啓動指定可執行文件（桌面應用或自研 App），通過空閒 CDP 端口 attach，關閉時隨進程回收。
connected：連接已有 CDP 端點（通過環境變量 DSH_BROWSER_CDP_URL），不擁有瀏覽器，釋放時只 disconnect。
relay：通過本地 Browser Relay 接管用戶正在使用的 Chrome，支持標籤頁分組排隊和 debugger ban 恢復。

run：腳本執行¶

在標籤頁中運行 JS 單元，提供豐富的 API：

作用域：page、browser、tab（支持 goto/observe/ariaSnapshot/screenshot/extract/click/type/fill/press/scroll/drag/waitFor*/evaluate/select/uploadFile/ref 等）。
輸出：支持文本流輸出、自動 resize 至模型像素預算的截圖、以及 JSON 返回值。
輔助函數：display、print、console、assert、wait、sleep。
錯誤處理：如果調用了 omp 專屬 helper（如 read/write/env/tree/agent/parallel/pipeline/phase/log/budget），會明確報錯。

close：生命週期¶

關閉標籤頁，並可配置是否同時 kill 瀏覽器進程。

relay CLI¶

提供本地服務端命令：
* serve：啓動 HTTP+WS 服務，僞裝 Chrome CDP discovery 接口。
* install：把擴展裝入 ~/.dsh/browser-relay/extension。
* status：查看服務狀態。

配置與環境變量¶

通過環境變量 DSH_BROWSER_* 控制行爲（均爲可選）：

DSH_BROWSER_ENABLED：0 時禁用工具。
DSH_BROWSER_HEADLESS：1 時默認使用 headless 模式。
DSH_BROWSER_RELAY / DSH_BROWSER_RELAY_URL：1 時走 relay 模式（默認 http://127.0.0.1:9224）。
DSH_BROWSER_CDP_URL：默認 connected 目標。
DSH_BROWSER_SCREENSHOT_DIR：截圖落盤目錄。
DSH_BROWSER_NO_WEBP：1 時模型副本使用 PNG。
DSH_BROWSER_INSTALL_CHROME：0 不自動下載 Chromium。
DSH_BROWSER_DONOR_CACHE：額外的 Chromium 複用來源（如 oh-my-pi 的緩存）。
PUPPETEER_EXECUTABLE_PATH / DSH_BROWSER_EXECUTABLE：指定 Chromium 可執行文件。

依賴項說明¶

該插件聲明 @deepseek-ai/dsh-tools 和 @deepseek-ai/schemastery 爲 peerDependencies。DSH 通過符號鏈接農場將宿主運行時暴露給插件。若將其寫入 dependencies，pnpm 會安裝副本，導致跨實例讀取模塊實例爲 undefined，引發調度錯誤。安裝時請勿將其寫入 dependencies。

Chromium 複用策略¶

啓動 headless Chromium 時，按以下順序解析可執行文件：
1. 環境變量 PUPPETEER_EXECUTABLE_PATH / DSH_BROWSER_EXECUTABLE。
2. 系統已安裝的 Chrome/Chromium。
3. 本包緩存裏已有的 Chrome for Testing。
4. 其他工具緩存：直接複製 DSH_BROWSER_DONOR_CACHE、~/.omp/puppeteer、PUPPETEER_CACHE_DIR 等，不重新下載。
5. 以上均無，才從 Chrome for Testing 下載。

典型用法¶

# 1. 打開一個非 headless 的標籤頁
browser action:"open" name:"wiki" url:"https://en.wikipedia.org" headless:false

# 2. 在標籤頁內運行腳本，觀察並點擊登錄
browser action:"run" name:"wiki" code:"await tab.observe(); await tab.click('text/Log in');"

# 3. 關閉標籤頁
browser action:"close" name:"wiki"

# 4. 啓動 Browser Relay 服務
dsh-browser-relay serve

注意事項¶

歸檔狀態：本倉庫已歸檔，Issue 與 PR 請在 mtaech/melon 倉庫處理。
權限：插件以當前 dsh 進程的權限運行，請檢查源碼與許可證。
結構：核心邏輯移植自 oh-my-pi，包括 open、run、close 三段式流程以及 tab API 實現。

GitHub 倉庫