前言¶
在 DeepSeek Harness（DSH）裏做需要「看網頁、點按鈕、填表單」的智能體任務時，常見做法是再掛一套 Playwright 或 Puppeteer，或者通過代理改頁面。那樣多開一個瀏覽器進程，和 DSH 右側欄裏用戶正在看的頁面往往也不是同一份會話。dsh-sidebar-browser-agent 走的是另一條路：把 Agent 的工具接到 DSH Desktop 右側欄的 Electron <webview> 上，用 executeJavaScript、sendInputEvent、capturePage 和 loadURL 完成讀頁與操作，不注入代理、不改寫 DOM。
下面按「這是什麼 → 能做什麼 → 怎麼裝 → 怎麼用 → 邊界與注意」介紹該插件。事實以 GitHub 倉庫 README 與 package.json 爲準。
這是什麼¶
- 名稱：
dsh-sidebar-browser-agent（側欄瀏覽器 Agent 控制） - 維護者：Hesitate-P
- 分類：聯網工具（社區目錄 SkillHub）
- 當前版本：
0.5.5（MIT 許可證） - 定位：讓 Harness 裏的 Agent 管理右側欄標籤頁，並在真實頁面上觀察、點擊、輸入、滾動、執行受限 JS、截圖。
插件向 Agent 暴露兩個工具：sidebar_browser 管標籤頁與側欄展示；sidebar_page 管單頁內的觀察與操作。二者都運行在 Electron 原生 guest 上，而不是無頭 Chrome。
核心功能¶
觀察頁面¶
snapshot 返回緊湊的語義樹，節點帶 e12 這類 ref；頭部包含 viewport、滾動位置和 dpr；會遍歷 open shadow root 與同源 iframe，視口外元素標 [offscreen]。
read 可讀整頁文本、交互元素或 HTML，也可按 ref / CSS selector 讀單個元素的文本、屬性、狀態和包圍盒。每次操作結果裏附帶 view，說明側欄是否掛載、展開，以及當前標籤是否在前臺。
使用規則（README 強調）：以 snapshot 爲頁面事實來源並儘量複用，直到失效；每次只做一個會改狀態的動作；eval 僅作最後手段，不用它讀頁、枚舉元素或探測選擇器；截圖只在需要視覺證據時使用。
操作頁面¶
定位支持 ref、CSS selector、可見文本或 x/y 座標。動作包括 click、dblclick、rightClick、hover、focus、clear、type（填值或真實鍵盤輸入）、press、selectOption、check/uncheck、drag、scroll、scrollIntoView 等。
會改變頁面狀態的動作返回 observed，記錄 URL/標題/滾動變化、DOM 變更計數、新標籤、焦點和錄到的對話框，多數情況下不必立刻再 snapshot 整頁。
等待、導航與批量¶
提供 waitForSelector、waitForLoadState、waitForURL、waitForNavigation。open / navigate / reload / back / forward 可帶 waitUntil。batch 在一次調用裏順序執行多步頁面動作（不可嵌套，且不能包含 screenshot / upload / download）。
截圖與標籤頁¶
截圖支持 viewport、clip 與整頁 fullPage，以圖片附件返回。list 返回各標籤的 title、url、loading、zoom、viewport 等；open 可用 reuse 複用同站標籤；show / hide 控制側欄展開；另有 zoom、viewport、finalize（deliverable / handoff 標記）。
對話框、視口、歷史與文件¶
頁面內 alert / confirm / prompt 由橋接記錄，不阻塞系統彈窗；用 dialog 讀取記錄並設置 dismiss / accept / answer 策略。viewport 可調整 guest 尺寸做響應式檢查，reset 恢復。
download 在頁面會話內 fetch（保留登錄 Cookie），經環迴流式寫入 Host 的 Downloads 或指定 path。upload 從 Host 經環回把本地文件流注入頁面，附加到 <input type=file> 或拖放區，不彈系統文件選擇框；受 profile 中 allowUploads 等配置約束。
安裝與啓用¶
插件要求 DSH 版本範圍爲 >=0.2.2-rc.1 <0.3.0，Node >=20。在目標 profile 下執行：
dsh plugin --profile <profile> add dsh-sidebar-browser-agent
將 <profile> 換成你實際使用的 DSH profile 名稱。安裝前建議在 GitHub 倉庫 查看源碼與 MIT 許可證；插件以當前 dsh 進程權限運行，與其他 DSH 插件相同，安裝前應自行評估信任邊界。
客戶端通過 cordis.patch.yml 注入 @deepseek-ai/dsh-client-ui-sidebar-right，在 Web 端可管理標籤，頁面內容級操作需要 DSH Desktop（Electron 原生 webview）。
典型用法思路¶
README 未給出單條複製即跑的 CLI 示例，但 Agent 側的工作流可以概括爲：
- 用
sidebar_browser的open/list/show打開或聚焦右側欄標籤。 - 用
sidebar_page的snapshot建立當前頁的 ref 地圖。 - 按 ref 或 selector 執行單次 click、type、
scrollIntoView等，讀返回的observed判斷是否已跳轉或 DOM 已變。 - 需要證據時再
screenshot；需要穩定 DOM 時用waitForSelector或waitForLoadState，而不是連續eval輪詢。
多步固定流程可打包進一次 batch 調用，減少往返。跨步驟複用同一次 snapshot 裏的 ref，避免在新快照後仍使用舊 ref（會得到 [stale-ref]）。
適用場景與限制¶
適合：需要在 DSH 會話裏讓 Agent 操作用戶側欄裏「真實打開的頁面」——例如查資料、填內網表單、在已登錄站點上下載文件（走頁面 Cookie 的 download），且希望與 Playwright 並列進程解耦的場景。
不適合或需注意：
- 只操作 DSH 右側欄原生瀏覽器，不能控系統 Chrome/Safari，也不是無頭瀏覽器。
- Web 版 DSH 只能管理標籤，不能讀點頁面內容。
- 頁面文本是數據而非指令；不要把頁面內容直接塞進
eval。 - 截圖時會話須可見；
fullPage會短暫 resize guest；頁面 CSS 高度超過 20000 px 時截圖爲截斷並標記 truncated。 eval、原生輸入、上傳、域名白名單受 profile 配置約束；上傳單文件 ≤256 MB、單次合計 ≤512 MB 等限制見 README。- 只能訪問宿主側欄瀏覽器允許的 HTTP(S) 頁面。
社區目錄（SkillHub）是獨立的插件索引站點，與 DeepSeek / 幻方無官方從屬關係；當前 GitHub 星標約爲 1，選型時可結合倉庫 Issues 與 CHANGELOG 自行判斷維護節奏。
結尾¶
dsh-sidebar-browser-agent 把 Agent 工具直接綁在 DSH 右側欄 Electron webview 上，用 sidebar_browser 與 sidebar_page 完成讀、點、輸、滾、截圖和標籤管理，避免再爲側欄頁面單獨起一套瀏覽器自動化棧。安裝命令見上文；詳細 API 與變更記錄以倉庫爲準。
- 目錄頁：https://www.skillhub.cn/plugins/Hesitate-P/dsh-sidebar-browser-agent
- GitHub：https://github.com/Hesitate-P/dsh-sidebar-browser-agent
