前言¶
在 DSH 裏跑智能體時，常見需求是「讀當前頁、點按鈕、填表單」——若只靠終端或 Web UI 對話，會話與瀏覽器是兩套上下文，軌跡也不好和頁面操作對齊。單獨寫 Playwright 腳本又繞開 DSH 的插件與會話模型。下面介紹社區插件 dsh-browser-relay（維護者 xianmua，分類：聯網工具）：它在 DSH 與瀏覽器擴展之間做通信橋，擴展或頁面面板發起的任務會在 DSH 側創建真實會話（落在 ~/.dsh/sessions，可在 dsh web UI 查看與追問），頁面動作通過 relay 註冊的 browser_* 工具回橋到擴展執行；模型與網關仍用 DSH 自身配置，relay 不直接調用 LLM。
這是什麼¶
dsh-browser-relay 是 DSH 的 cordis 插件（npm 包名 dsh-browser-relay，當前資料中版本 0.7.24，許可證 MIT）。一句話：擴展或懸浮面板提交的任務 → relay 在 DSH 建會話 → agent 執行；瀏覽器命令入隊 → 擴展長輪詢取走 → PageController 執行 → 結果回傳。鑑權統一爲 relay token，擴展 zip 從本機嚮導下載時自動寫入口令，常規使用零手工配置。
- 目錄頁：https://www.skillhub.cn/plugins/xianmua/dsh-browser-relay
- 源碼與說明：https://github.com/xianmua/dsh-browser-relay
- 運行要求（package.json）：Node >=18，DSH >=0.2.1-rc.1
核心功能¶
會話與工具橋接¶
瀏覽器擴展「頁面 AI 助手」或業務頁掛載的面板裏提交的每個任務，經 relay 在 DSH 創建與會話列表可見的任務會話；agent 側可用 relay 提供的 browser_* 工具，實際 DOM 操作在擴展側完成。
本機嚮導與擴展¶
dsh web 啓動後 relay 監聽 http://127.0.0.1:9916/（默認端口 9916）。嚮導頁可下載 dsh-browser-extension.zip，口令與端點已寫入，解壓後在 Edge/Chrome 開發人員模式下「加載解壓縮的擴展」即可。工具欄點「頁面 AI 助手」圖標從面板發起任務；若報 invalid api key，在嚮導頁重新下載 zip 覆蓋擴展目錄即可。
頁面 script 接入（可不裝擴展）¶
業務頁 header 引入 relay 託管的 dsh-assistant.min.js，適合內網系統。直連本機示例：
<script src="http://127.0.0.1:9916/dsh-assistant.min.js" data-token="嚮導頁複製的口令"></script>
經後端代理時，data-base-url 指向代理前綴，代理需將該前綴下路由整體轉發到 relay；data-workspace、data-ai-level（L1–L5 或 none/page/site/dsh/all，默認 L4）可選。代理鑑權模式下可省略 data-token，由後端轉發時注入 Authorization: Bearer <口令>，避免口令暴露給頁面訪客。
遠程 DSH、本機瀏覽器¶
擴展設置頁可改 relay 地址，指向局域網內另一臺已啓動 relay 的機器。遠程需在 patch 中設置 host: 0.0.0.0（0.4.11+ 支持），並注意防火牆放行 9916/tcp；token 存於各機 ~/.dsh/browser-relay-token，不一致會導致任務無事件或 invalid api key。也可用 SSH 本地端口轉發連遠程，而不暴露 0.0.0.0。
智能等級與安全邊界¶
面板/擴展可設智能等級：L1 僅問答；L2 本頁讀寫禁導航；L3 同域可導航；L4 頁面 + DSH 工具（默認）；L5 瀏覽器與 DSH 全量。越權工具調用在執行層拒絕。9916 憑 token 鑑權；host: 0.0.0.0 時 token 爲內網唯一防線，不宜公網映射。
安裝與啓用¶
前提：本機已安裝並登錄 DSH（dsh 命令可用）。資料中的用戶安裝步驟如下，無需 git clone、無需 node、不碰源碼目錄。
① 安裝 relay（add 時自動登記掛載聲明）：
dsh plugin --profile web add dsh-browser-relay
② 啓動 DSH（relay 隨之啓動並生成本機口令）：
dsh web
③ 瀏覽器打開 http://127.0.0.1:9916/，按嚮導下載擴展 zip、加載擴展，即可使用。
遠程機器裝插件時，README 示例爲 dsh plugin --profile web add git+<插件倉庫地址> 並配合 relay-patch.yml 啓動；與 npm 包名安裝並列出現，按你的分發來源選用其一。
插件隨 dsh web 進程運行，權限與當前 DSH 進程一致；安裝前建議在 GitHub 查看源碼與 MIT 許可證及 bundled 組件說明。
典型用法與驗證¶
在任意已加載擴展或已掛載腳本的頁面，點擴展圖標或面板，輸入可復現的簡單任務，例如 README 中的「讀取頁面標題並返回」：
- 面板逐步顯示進度並返回結果。
- dsh web UI 會話列表出現以任務命名的會話，含完整對話與工具調用，可繼續追問。
- dsh web 終端可見類似
[dsh-browser-relay] 任務 #N 已創建 DSH 會話 ...的日誌。
注意：僅在 DSH web UI 裏直接對話不會橋接瀏覽器；瀏覽器相關操作需從擴展面板或頁面助手發起。
業務頁代理接入示例（推薦生產環境）：
<script src="/your-proxy/dsh-assistant.min.js"
data-base-url="/your-proxy"
data-token="嚮導頁複製的口令"
data-workspace="D:\工作區"
data-ai-level="L4"></script>
倉庫內 web-panel/test.html 可用於腳本加載、鑑權與表單等接入對照。
適用場景與注意¶
適合：已在用 DSH 做 agent，希望把「當前標籤頁 / 業務系統頁面」納入同一會話軌跡；內網系統用一行 script 掛懸浮助手；DSH 跑在服務器、瀏覽器在本機時，通過 relay 地址或 SSH 隧道組合使用。
不適合或需知：依賴本機或內網 relay 與 token，不是公網 SaaS 瀏覽器服務；CSP 嚴格的站點需放行對應 script-src；擴展與 relay 更新需按 README「擴展更新」一節重裝插件、重下 zip、擴展「重新加載」並刷新頁面。
常見問題對照（摘自 README）：打不開 9916 → 確認 dsh web 與 add 成功；「DSH 會話服務不可用」→ 須通過 dsh web 啓動；「當前會話沒有關聯的瀏覽器頁面任務」→ 從瀏覽器面板發起而非純 Web UI 對話。
結尾¶
dsh-browser-relay 把 DSH 插件生態裏的「一切皆插件」落到瀏覽器側：會話、模型配置留在 DSH，頁面自動化經 browser_* 與擴展/面板閉環，口令與嚮導把上手成本壓到 add + dsh web + 加載擴展幾步。
