dsh-browser-control：讓 DSH 智能體複用你日常 Chrome 登錄態的 CDP 插件

前言¶

給智能體接瀏覽器，常見做法是起一個乾淨的 headless 實例。問題在於登錄態：很多頁面需要已登錄的 Cookie 才能看到真實內容，每次都要在隔離環境裏重新登錄，成本很高。而直接在日常使用的 Chrome 上開 --remote-debugging-port，新版 Chrome 已經明確禁止——默認 user-data-dir 不允許開調試端口。

下面介紹 dsh-browser-control，一個 DeepSeek Harness（DSH）插件，用 CDP（Chrome DevTools Protocol）驅動瀏覽器，核心賣點正是登錄態複用：它能把你日常 Chrome 的登錄狀態搬進一個隔離的調試實例，讓智能體直接以「已登錄」的身份導航、截圖、抓報錯、執行 JS。

這是什麼¶

dsh-browser-control 是由 PangYiMing 維護的 DSH 插件，當前版本 0.1.0，MIT 許可證。它通過 CDP 控制瀏覽器，提供：

複用日常 Chrome 登錄態
頁面導航與截圖
抓取 console / pageError / networkError
在頁面執行任意 JS
移動端視口與 UA 仿真

插件依賴 ws ^8.18.0，peerDependencies 爲 @deepseek-ai/dsh-tools 與 @deepseek-ai/cordis，要求 Node >= 20.11。

核心能力¶

登錄態複用啓動器¶

scripts/launch.sh 負責起一個 :9222 端口的 CDP 調試實例。它的做法不是直接改日常 Chrome 的啓動參數，而是：

把日常 Chrome 的登錄態文件（Cookies / Login Data / Local Storage / IndexedDB 等）只讀拷貝到隔離目錄 /tmp/chrome-e2e-profile；
用這個隔離目錄起調試實例。

幾個設計細節：

單向不回寫：調試實例不會污染日常 Chrome 的數據；
懶同步：只在首次或指定 --refresh 時才重新拷貝；
端口探測複用：實例已在跑就直接複用，不重複啓動；
精確 pkill：關閉時只殺調試實例，不誤傷日常瀏覽器。

原理與實現細節見倉庫裏的 docs/cdp-login-reuse.md。

CDP 驅動腳本¶

scripts/drive.mjs 負責具體的瀏覽器操作：導航 / 截圖 / console / eval / mobile 仿真。導航完成後輸出一段 JSON，包含 title、url（注意是 SPA 跳轉後的最終地址）、bodyPreview、console、pageErrors、networkErrors 以及 screenshot 路徑。也就是說，一次導航就能拿到頁面文本預覽和三類報錯信息，方便智能體直接判斷頁面狀態。

封裝爲 6 個 DSH 工具¶

安裝插件後，以下 browser_* 工具會自動註冊進 agent 的工具集：

工具	說明
`browser_status`	探測 CDP 實例是否在跑（默認 9222）
`browser_launch`	冪等啓動 CDP 調試 Chrome（複用日常登錄態；`refresh` 強制重同步）
`browser_kill`	關閉 CDP 調試實例
`browser_open`	導航到 URL 並返回 title / 最終 URL / 文本預覽 / console / pageError / networkError / 截圖
`browser_screenshot`	導航並截圖，返回截圖路徑
`browser_eval`	導航後在頁面執行 JS 表達式並返回結果

安裝¶

兩種方式。npm 命令要等插件發佈到 npm 後纔可用：

dsh plugin --profile demo add dsh-browser-control

或直接從 GitHub 源碼安裝，源碼安裝需要 prepare 構建：

dsh plugin --profile demo add github:PangYiMing/dsh-browser-control

典型用法¶

腳本層面可以直接跑這兩個文件。先起調試實例：

./scripts/launch.sh   # 起 :9222 調試實例（複用日常 Chrome 登錄態；已在跑則複用）

launch.sh 還支持 --refresh / --kill / --status 三個參數，分別對應強制重同步登錄態、關閉實例、查看狀態。

再驅動瀏覽器導航並截圖：

node scripts/drive.mjs "<url>" \
  --out /tmp/shot.png \
  [--mobile] [--wait 4000] [--eval "<expr>"]

三個可選參數：

--mobile：390x844 視口 + iPhone UA 仿真；
--wait 4000：等待毫秒數；
--eval "<expr>"：在頁面執行任意 JS，可用來驗證 DOM 狀態、讀 window 全局、調庫 API。

在 agent 會話裏則不需要記命令，用自然語言觸發即可：

browser_launch 起 Chrome，然後 browser_open 打開 https://example.com 截圖給我看

canvas 截圖避坑¶

如果頁面用 G6 / echarts / D3 / WebGL 這類可視化庫畫 canvas，直接截圖可能拿到空白。原因是後臺 tab 的 raf 會被節流，渲染根本沒跑。插件的處理是：新建 tab + Page.bringToFront + 踢 raf。作者還特別提醒：判斷是否渲染完成時別用 getImageData。細節見 docs/cdp-canvas-pitfalls.md。

適用場景與注意¶

適合的場景：讓智能體檢查需要登錄的頁面、排查前端報錯（console / pageError / networkError 一次抓全）、驗證可視化頁面渲染結果、做移動端視口下的頁面檢查。

邊界也要清楚。路線圖中已完成的是登錄態複用啓動器、CDP 驅動和 6 個 browser_* 工具；尚未完成點擊 / 填表 / 表單交互、Playwright 後端、多標籤 / 多窗口管理。也就是說，當前它偏向「看」和「讀」，還不是一個完整的瀏覽器操作方案。

另外提醒一點：插件以當前 dsh 進程的權限運行，安裝前建議先到倉庫檢查源碼與許可證（MIT，見 ./LICENSE），確認符合自己的安全要求。

結尾¶

dsh-browser-control 解決的是智能體操作瀏覽器時最常見的登錄態問題，同時把導航、截圖、報錯抓取打包成一次調用就能拿全的 JSON 輸出。如果你在用 DSH 做智能體開發，需要讓 agent「登錄着看網頁」，可以試試。

目錄頁：https://www.skillhub.cn/plugins/PangYiMing/dsh-browser-control
GitHub：https://github.com/PangYiMing/dsh-browser-control