前言¶

在 DSH 的插件方式下，瀏覽器能力可以作爲原生工具接入 Agent 的工具管道。dsh-cloak-browser 解決的是：Agent 需要打開頁面、完成交互、讀取渲染結果時，瀏覽器會話狀態保留在 DSH 的工具調用中，併爲每個 Agent 維護隔離的 BrowserContext。頁面狀態以受限快照和短引用返回，Agent 可以繼續基於這些引用執行下一步操作。

這是什麼¶

maxiaovivi/dsh-cloak-browser 是一個由 maxiaovivi 維護的 DSH 插件包，定位是：

Native CloakBrowser tools for DeepSeek Harness with per-agent browser sessions and snapshot references.

它把 DSH 與 CloakBrowser 接入到一起：DSH 側負責 Agent、工具調用和附件能力，CloakBrowser 側負責瀏覽器啓動、輸入和瀏覽器二進制分發。已覈實資料明確說明：該倉庫不是 DeepSeek 或 CloakHQ 官方項目，也不代表這兩個組織背書。

核心能力¶

下面是已覈實資料中列出的主要能力：

• Native DSH tools：提供 schema、canonical JSON results、UI presentation 和 Code Mode compatibility。
• Lazy browser startup：Chromium 只在 Agent 調用瀏覽器工具時啓動。
• One isolated BrowserContext per Agent：Agent 結束或插件卸載時自動關閉對應上下文。
• Automatic bounded page snapshots：導航和交互後返回限定範圍的頁面快照，並附帶短生命週期元素引用，例如 p1:s3:e8。
• 瀏覽器工具覆蓋 navigation、click、fill、select、keyboard、wait、extraction、screenshot、tab 和 lifecycle。
• Durable DSH image attachments：面向支持圖像的模型保存圖像附件；文本路由使用文本快照回退。
• Optional humanized mouse、typing 和 scrolling，通過 CloakBrowser 提供。
• Automatic license-plan detection：已驗證的 Free key 可不經用戶確認直接啓動；同一 DSH 進程內的本地 Free-session 併發啓動會被串行化。
• Proxy-aware GeoIP consistency：當代理環境變量存在時自動啓用；其運行時依賴已打包。
• Domain allow/deny rules、explicit local/private-address blocking、page and output limits、cooperative cancellation 和 browser cleanup。
• A resident routing prompt：讓瀏覽器用於 rendered 或 interactive 任務；簡單公開文本查找繼續走更輕量的 web search/fetch tools。

安裝與啓用¶

前置條件¶

已覈實資料給出的要求包括：

• Node.js 20 or newer
• DeepSeek Harness (DSH) 0.1.0-rc.6
• 已抓取資料中的 package.json 顯示版本爲 0.3.0
• peerDependencies 爲 @deepseek-ai/dsh-llm ^0.1.0-rc.6 和 @deepseek-ai/dsh-tools ^0.1.0-rc.6

從 GitHub 安裝¶

先添加插件：

dsh plugin --profile web add -w github:maxiaovivi/dsh-cloak-browser

然後確認插件已組合進 profile：

dsh --profile web --dump-config | grep -A24 cloak-browser

重啓 DSH 使插件生效：

dsh --profile web

上面的命令沿用已覈實資料中的示例 profile web。如果當前 DSH 環境使用其他 profile，請按實際環境調整命令中的 profile 名稱。

可選環境變量¶

許可證 key 和代理地址不應寫入 cordis.patch.yml 或工具參數中。資料要求把它們導出到啓動 DSH 的環境中：

export CLOAKBROWSER_LICENSE_KEY='your-license-key'       # optional
export CLOAKBROWSER_PROXY_URL='http://user:pass@host:port' # optional
dsh --profile web

Free key 與無 key 路徑¶

如果沒有 license key，CloakBrowser 會選擇其可用的 free build。首次瀏覽器使用時會下載並校驗大約 200 MB 的 Chromium archive。解壓後的緩存可能在 ~/.cloakbrowser 下佔用明顯更大的磁盤空間。資料明確說明不需要執行 playwright install chromium。

已驗證的 Free key 會直接啓動，不要求用戶確認。同一 DSH 進程內的併發本地 Free-session 啓動會被串行化。該插件不能撤銷屬於其他機器或異常遺留進程的會話。

代理與 GeoIP¶

當代理 URL 存在時，插件會自動啓用 CloakBrowser 的 GeoIP matching。首次使用時可能會下載約 70 MB 的 GeoLite database，並放入同一個緩存目錄。

舊版本遷移¶

已覈實資料說明：0.1.1 及之後的版本會複用 profile 中已有的 dsh-tools 和 dsh-llm runtime instances。如果之前安裝過 0.1.0，重新安裝前需要先卸載一次：

dsh plugin --profile web remove -w dsh-cloak-browser
dsh plugin --profile web add -w github:maxiaovivi/dsh-cloak-browser

完成後重啓 DSH。

卸載¶

執行：

dsh plugin --profile web remove -w dsh-cloak-browser

然後重啓 DSH。資料說明，~/.cloakbrowser 下緩存的瀏覽器二進制由 CloakBrowser CLI 單獨管理。

典型用法¶

已覈實資料給出的推薦流程如下：

browser_open(url)
  → Free, paid, or keyless: launches directly without asking
  → occupied Free seat: returns not_started without retrying in a loop
  → returns snapshot + refs
  → browser_click / browser_type / browser_select → returns next snapshot + refs
  → browser_close when the browser task is complete

也就是說，Agent 先打開目標頁面，插件返回頁面快照和短引用；隨後 Agent 基於這些引用執行點擊、輸入或選擇；每次交互後再返回下一輪快照和引用；任務完成後調用 browser_close 結束瀏覽器任務。

對於支持圖像的模型，插件使用 Durable DSH image attachments；對於文本路由，使用文本快照作爲回退。

適用場景與注意¶

適合的場景¶

• Agent 需要打開已渲染頁面並完成交互。
• 需要點擊、填寫、選擇、鍵盤輸入、等待、提取、截圖、標籤頁管理和瀏覽器生命週期管理。
• 希望在 DSH 內部隔離多個 Agent 的瀏覽器狀態，避免跨 Agent 泄露。
• 希望瀏覽器工具返回結構化快照和短引用，而不是讓 Agent 自己維護大量頁面 DOM。
• 希望通過路由提示，把簡單公開文本查找留給更輕量的 web search/fetch tools。

使用前注意¶

1、該插件運行在啓動 DSH 的環境中，並使用當前 DSH 進程可獲得的權限。安裝前應檢查源碼、策略、工具邊界和許可證。

2、許可證類型方面，已覈實資料只說明 package.json 的 files 列出了 LICENSE 文件名，但沒有給出具體許可證類型。不要把它當作已確認的 MIT、Apache 或其他許可證。

3、憑據不應放在 cordis.patch.yml 或工具參數中，應導出到啓動 DSH 的環境中。

4、首次使用可能產生明顯磁盤佔用：無 key 路徑首次會下載約 200 MB Chromium archive；代理路徑首次可能下載約 70 MB GeoLite database。

5、Free-session 的佔用狀態只適用於本地併發場景。無法撤銷其他機器或異常遺留進程持有的會話。

6、該倉庫是社區維護項目，不是 DeepSeek 或 CloakHQ 官方項目，也不代表這兩個組織背書。

結尾¶

dsh-cloak-browser 的核心是把 CloakBrowser 的瀏覽器能力做成 DSH 原生工具：按 Agent 隔離瀏覽器上下文，返回受限快照和短引用，並保留導航、交互、截圖、附件、代理 GeoIP、Free-session 串行化和安全邊界等能力。

GitHub 倉庫地址：

https://github.com/maxiaovivi/dsh-cloak-browser