前言¶
讓 Agent 幹瀏覽器裏的活，常見的做法是起一個 headless 瀏覽器：Agent 在裏面點按鈕、填表單，把截圖和日誌回傳給你。整個過程接近黑盒——頁面沒加載出來、選擇器失效、被登錄框擋住，你只能看日誌猜，想插手也沒有入口。
dsh-plugin-chrome 走的是另一條路：每個 DSH 會話開一個真實的、可見的 Chrome 窗口，畫面即時串流到 Web GUI，你在旁邊看着 Agent 操作，隨時可以自己點幾下接管。下面介紹它的功能、安裝和用法。
這是什麼¶
dsh-plugin-chrome 是 DeepSeek Harness（DSH）的瀏覽器可視化插件，由 jiaererw 維護，MIT 許可證，代碼在 GitHub 開源。它解決的問題是：Agent 操作瀏覽器時，你既能即時看到它在做什麼，也能隨時手動介入。
DSH 的理念是一切皆插件。這個插件裝進 profile 後，會話頂部會多出一個 Chrome 標籤頁，Agent 則自動獲得一套瀏覽器工具。
核心功能¶
每個會話一個可見窗口¶
每個 DSH 會話擁有一個可見的真實 Chrome 窗口（非 headless），使用隔離的 user-data-dir，不與日常瀏覽器混用。Agent 的每一步操作都能直接看到。
即時畫面串流¶
Web GUI 的 Chrome 標籤頁通過 Chrome screencast 即時串流窗口畫面，頁面活躍時幀流順暢。空閒頁面由心跳兜底強制截幀——靜默 3 秒後約每 2 秒一幀，畫面不會凍結。
16 個 chrome_* 工具¶
chrome_open / chrome_status / chrome_close / chrome_navigate
chrome_tabs / chrome_snapshot / chrome_screenshot / chrome_click
chrome_click_at / chrome_fill / chrome_type / chrome_press_key
chrome_hover / chrome_scroll / chrome_evaluate / chrome_wait
其中 chrome_tabs 覆蓋列表 / 新建 / 關閉 / 選擇四種操作；快照、截圖與點擊始終作用於當前選中的標籤頁。
快照與截圖¶
chrome_snapshot 返回帶穩定元素 uid 的緊湊可訪問性樹，點擊與填寫直接以 uid 爲目標，比傾倒整個 DOM 輕得多，也不容易因頁面結構變動而失效。
chrome_screenshot 是雙通道設計：圖片塊送入模型上下文，讓模型“看到”頁面；同時保存到面板的會話截圖歷史，歷史條目保留標題、URL、尺寸元數據，跨重啓保留。
安全設計¶
- CDP 不暴露固定端口；
- Web API 拒絕跨站請求（基於 Sec-Fetch-Site），並對 sessionId 做白名單校驗；
- 瀏覽器數據按會話隔離。
資源治理與生命週期¶
- 空閒窗口自動關閉，默認 10 分鐘，可配置；
- chrome_close 顯式關閉；插件卸載或宿主關閉時，會關閉它打開的所有窗口；
- 懶啓動：只在首次 chrome_* 調用或面板 Open 按鈕時才啓動 Chrome；
- 孤兒收養：DSH 異常退出遺留的 Chrome，插件通過 DevToolsActivePort 重連接管，而不是報錯失敗；
- 自動標籤頁恢復：每次操作確保存在可用標籤頁，避免窗口全是 chrome:// 內部頁時無法工作。
安裝與啓用¶
前置條件：已安裝 DeepSeek Harness (DSH)，機器上有 Chrome 或 Edge；插件要求 Node >= 20。
官方安裝命令：
npx -p @deepseek-ai/dsh dsh plugin --profile web add github:jiaererw/dsh-plugin-chrome
本地開發可以用本地路徑安裝：
npx -p @deepseek-ai/dsh dsh plugin --profile web add D:/harness/dsh-plugin-chrome
安裝後需重啓 DSH，每個會話頂部會出現 Chrome 標籤頁。
兩個可能遇到的問題：
1、如果 profile 的 cordis.patch.yml 裏還保留着舊的 dsh-plugin-chrome 手動掛載行（本地開發時加的），先移除再用 CLI 安裝，避免雙重掛載；
2、pnpm 的 strict-dep-builds 可能阻止安裝：在 profile 的 pnpm-workspace.yaml 的 allowBuilds 中加入 dsh-plugin-chrome: true 後重試。
配置¶
配置通過 profile 的 cordis.patch.yml 覆蓋插件行（整體替換）：
- id: dsh-plugin-chrome
config:
headless: false # 保持 false——可見窗口是本插件的意義
executablePath: '' # 留空自動檢測 Chrome/Edge，也可填絕對路徑
idleTimeoutMs: 600000 # 空閒自動關閉（0 禁用）
windowWidth: 1280
windowHeight: 900
screencastFrameSkip: 4 # 畫面抽幀（1 = 最流暢）
screencastQuality: 70 # JPEG 質量 1-100
maxSnapshotText: 60000 # 單次快照最大字符數
maxTabs: 16
extraArgs: '' # 額外的 Chrome 啓動參數
瀏覽器數據與截圖存放在 ~/.dsh/data/dsh-plugin-chrome/sessions/<sessionId>/，可用 dataRoot 覆蓋。
典型用法¶
讓 Agent 執行一句自然語言指令：
Open Chrome, go to https://example.com, take a screenshot, then click the “Login” button and fill in the username.
對應的工具流程是：chrome_open → chrome_navigate → chrome_screenshot（模型看到圖片）→ chrome_snapshot（拿到 uid）→ chrome_click / chrome_fill。
面板側的操作：
1、打開會話頂部的 Chrome 標籤頁，Live view 持續顯示窗口畫面；
2、側欄可以創建、切換、關閉標籤頁，與真實窗口同步；
3、隨時手動點擊真實窗口接管，Agent 下一次工具調用就能看到你的變更；
4、每次 chrome_screenshot 都存入面板截圖歷史，點擊縮略圖可放大查看。
幾個常見情況的處置：
- 自行關閉窗口後不用重裝，任意下一次 chrome_* 調用或面板 Open 按鈕會重新啓動；
- Agent 報 “unknown uid” 說明頁面已經變了，讓它重跑一次 chrome_snapshot；
- 面板黑屏時先檢查窗口是否在運行（頂部狀態點），首次啓動需要幾秒。
適用場景與注意事項¶
適合的人：
- 想即時盯着 Agent 瀏覽器操作、不放心純日誌回傳的；
- 調試瀏覽器自動化流程，需要看現場而不是猜日誌的；
- 有登錄態需求的任務——每個會話使用隔離 profile，登錄態不與日常瀏覽器互通（設計如此）。如需登錄，讓 Agent 在會話內完成，登錄態在會話內持久。
注意事項：
1、純文本模型慎用截圖。chrome_screenshot 會把圖片塊寫入會話歷史，若模型不接受圖片，後續每輪都會被拒絕（UNSUPPORTED_CONTENT: does not accept image input）且會話不再響應，重試無效。需要截圖的會話請使用支持視覺的模型，或在該會話中避免 chrome_screenshot；
2、headless 配置應保持 false，可見窗口是這個插件的核心；
3、安全提醒：插件以當前 dsh 進程的權限運行，安裝前請自行檢查源碼與許可證（本項目爲 MIT）。文中提到的社區目錄 skillhub.cn 是獨立站點，與 DeepSeek / 幻方無官方從屬關係。
結尾¶
dsh-plugin-chrome 把 Agent 的瀏覽器操作從黑盒變成現場：窗口可見、畫面即時、隨時接管，16 個工具加生命週期兜底讓它能在會話里長期穩定跑。如果你在用 DSH 做瀏覽器相關任務，值得一裝。
- 目錄頁：https://www.skillhub.cn/plugins/jiaererw/dsh-plugin-chrome
- GitHub：https://github.com/jiaererw/dsh-plugin-chrome
