前言¶
DSH 的理念是“一切皆插件”。在讓智能體處理網頁任務時，常見的卡點不只是“能不能點”或“能不能填”，還包括登錄、憑據邊界、登錄態保留，以及頁面視覺狀態是否可被理解。已有做法如果只是調用一個無頭瀏覽器，往往看不到窗口、不能人工接管登錄，登錄態也容易丟失。
dsh-browser-companion 針對這些問題，爲 DSH 提供一個瀏覽器插件：它讓智能體獲得一個持久 profile、可見窗口、人工登錄通道，以及一組相對安全的瀏覽器操作工具。
這是什麼¶
dsh-browser-companion 是一個個人 DSH 瀏覽器插件。它給智能體一個專用、持久、可見的瀏覽器環境，核心目標是：
- 智能體可以打開頁面、點擊、輸入、滾動、管理標籤頁等；
- 用戶可以在真實窗口中完成登錄、輸入密碼或完成 OAuth；
- 密碼和 OAuth secret 不經過智能體；
- cookie、localStorage 和登錄狀態保存在同一 profile 中，重啓後可繼續保留。
許可證爲 MIT。GitHub 倉庫地址爲：
https://github.com/Tianyu209/dsh-browser-companion
核心功能¶
持久瀏覽器 profile¶
插件會保留瀏覽器 profile 中的登錄態。已覈實的能力包括：
- 持久化 cookie；
- 持久化 localStorage；
- 持久化登錄狀態。
這意味着一些站點登錄一次後，後續任務可以複用同一 profile，而不是每次都重新登錄。
可見窗口¶
插件提供可見窗口模式，默認配置爲：
headless: false
也就是說，智能體操作瀏覽器時，用戶可以看到真實的瀏覽器窗口。這對觀察智能體動作、人工接管登錄比較重要。
人工登錄¶
插件提供 browser_login 和 browser_wait_login：
browser_login打開一個可見登錄窗口，由用戶自己輸入密碼或完成 OAuth；browser_wait_login等待登錄完成，判斷依據包括 cookie / URL。
密碼和 OAuth secret 由用戶在瀏覽器窗口中處理，不經過智能體。
瀏覽器操作工具¶
已覈實的 agent tools 包括：
open, snapshot, click, type, press, screenshot, see, select, check, upload, hover, scroll, tabs, status
其中幾個常用工具：
open：打開頁面；snapshot：獲取 accessibility snapshot / refs；click/type/press：基礎交互；select/check：表單控件操作；upload/hover/scroll/tabs/status：更細粒度的頁面操作。
安全邊界¶
插件對敏感輸入做了限制：
browser_type拒絕填寫密碼字段；- 智能體被要求不要填寫密碼字段；
- 密碼和 OAuth secret 由用戶在可見瀏覽器窗口中輸入。
視覺理解¶
browser_see 使用本地視覺模型（OpenAI-compatible）來輔助智能體理解圖片、視覺佈局或複雜界面。默認應優先使用 browser_snapshot，因爲它更快、成本更低，並帶有 refs；只有需要視覺判斷時再使用 browser_see。
如果 browser_see 未配置，它會返回友好消息，而不是中斷智能體。
安裝與啓用¶
先安裝依賴：
npm install -g agent-browser
agent-browser install
然後在 web profile 中添加插件：
dsh plugin --profile web add dsh-browser-companion
最後啓動或重啓 DSH：
dsh web
如果使用 pnpm，並且從 GitHub 安裝時遇到 agent-browser build script 被阻止，可以在 profile 的 pnpm-workspace.yaml 中加入：
allowBuilds:
agent-browser: true
然後重新安裝。
典型用法¶
下面是一個登錄流程：
1、智能體需要進入某個站點，但需要先登錄。
2、智能體調用 browser_login 打開可見登錄窗口。
3、用戶在窗口中完成登錄、輸入密碼或 OAuth 授權。
4、用戶告知智能體已完成。
5、智能體調用 browser_wait_login 等待登錄狀態確認。
6、智能體在同一 profile 的 cookie 狀態下繼續後續操作。
頁面讀取也有一個簡單原則：
1、默認使用 browser_snapshot，獲取快速、免費的 accessibility tree 與 refs。
2、只有遇到圖片、視覺佈局或複雜 UI 時，再使用 browser_see。
3、如果本地視覺模型未配置，browser_see 會給出友好提示。
可選配置¶
可以在 DSH WebUI 的插件設置中修改這些配置項：
executablePath：指定瀏覽器可執行文件；visionBaseUrl/visionModel：配置本地視覺模型，用於browser_see；profilePath：指定瀏覽器 profile 路徑。
需要自定義瀏覽器、視覺模型或 profile 位置時再修改即可。
適用場景與注意¶
適合以下場景：
- 需要 DSH 智能體完成網頁操作，但登錄必須人工完成；
- 需要保持瀏覽器登錄態，避免每次任務都重新登錄；
- 需要看到瀏覽器窗口，便於人工觀察和接管；
- 需要智能體理解圖片、視覺佈局或複雜 UI。
使用前注意：
- 插件會運行在本機，並以當前 dsh 進程權限執行；安裝前應檢查源碼和許可證。
- 不要提交真實路徑、token 或個人 profile 數據；使用示例配置並本地替換值。
- 密碼和 OAuth secret 始終由用戶在可見瀏覽器窗口中處理，不應作爲普通文本交給智能體。
browser_see依賴本地視覺模型配置；未配置時不會中斷智能體，但也不會提供視覺理解結果。
結尾¶
dsh-browser-companion 的價值比較具體：它把“智能體操作瀏覽器”和“人工登錄 / 憑據邊界”拆開了，同時保留可見窗口和持久 profile。對於希望 DSH 能處理真實網頁任務、又不想把密碼交給智能體的場景，它是一個比較直接的插件。
GitHub 倉庫：
https://github.com/Tianyu209/dsh-browser-companion
DSH 社區目錄：可按插件名 dsh-browser-companion 在 DSH 社區目錄中查找；本文不給出未覈實的目錄頁 URL。
