前言¶

在 DeepSeek Harness（DSH）環境中，智能體在瀏覽器中的操作通常基於一次性配置文件。每次運行都是一個全新的瀏覽器實例，沒有 Cookies、沒有已登錄狀態，也無法使用個人安裝的擴展程序。這導致智能體無法訪問需要身份驗證的頁面，也無法複用已配置的環境。

本插件通過提供持久化的 Yandex Browser 配置文件以及基於 Chrome DevTools Protocol（CDP）的頁面控制能力，解決了這一問題。它允許智能體在同一個瀏覽器實例中工作，且配置文件中的登錄狀態和擴展可以長期保留。

這是什麼¶

這是一個 DeepSeek Harness 插件，由用戶 DmitPerson42 維護。其核心功能是啓動一個帶有持久化配置文件的 Yandex Browser，並在端口 9222 上開啓 CDP 通信，從而讓智能體能夠直接讀取和操作頁面內容。

插件不依賴 MCP（Model Context Protocol），而是直接通過 CDP 與瀏覽器交互。它主要包含三個模塊：yandex_browser（管理生命週期）、yandex_page（讀取內容）和 yandex_act（執行動作）。

核心功能¶

插件通過 CDP 協議（默認端口 9222）與瀏覽器通信，配置文件存儲在 %USERPROFILE%\.dsh\browsers\yandex。

1. yandex_browser：生命週期管理

   • status：檢查瀏覽器運行狀態、版本、端點地址、配置文件路徑及當前打開的標籤頁。
   • start：啓動瀏覽器。如果瀏覽器已運行，此命令會跳過啓動過程。
   • open：在瀏覽器中打開指定 URL。如果瀏覽器未啓動，會自動先啓動。
   • login：打開登錄頁面（默認爲 Yandex Passport），供用戶手動輸入憑據。
   • tabs：列出當前所有打開的標籤頁。
   • close：關閉瀏覽器。注意：這會關閉所有標籤頁，但會保留配置文件中的登錄狀態。

2. yandex_page：頁面讀取

   • text：獲取頁面文本，並附帶交互元素（基於 aria-label、title、placeholder）的描述，便於識別複雜的 Web 組件。
   • eval：在頁面上下文中執行 JavaScript 表達式並返回結果。
   • screenshot：保存頁面截圖。支持 fullPage 參數以截取完整頁面。
   • tabs：返回標籤頁 ID 列表，並標記出由插件創建的標籤頁。

3. yandex_act：頁面操作

   • navigate：跳轉 URL。
   • click：通過 CSS 選擇器或可見文本點擊元素。
   • type：在輸入框中輸入文本（支持 React 表單），可配置是否發送回車。
   • key：模擬按鍵（Enter, Tab, Escape, 方向鍵等）。
   • activate：激活並顯示特定標籤頁。
   • close / close_created：關閉指定標籤頁或關閉所有由插件自動創建的標籤頁。
   • wait：等待指定元素出現。

安裝與啓用¶

通過 CLI 安裝插件：

dsh plugin --profile web add github:DmitPerson42/dsh-yandex-browser

安裝完成後，需要修改配置文件以啓用插件。插件通過 dsh.bundle.patch 宣告自身，並依賴 cordis.patch.yml 來注入配置。

在 ~/.dsh/profiles/web/cordis.patch.yml 中添加以下內容（需根據實際環境調整路徑）：

- insert:
    - id: yandex-browser
      name: "file:///<你的用戶目錄>/.dsh/plugins/dsh-yandex-browser/lib/index.js"
      config:
        autoStart: true

配置項說明：
* autoStart：設置爲 true 可在插件加載時自動啓動瀏覽器，確保後續命令可用。
* cdpEndpoint：默認爲 http://localhost:9222（必須使用 localhost 而非 127.0.0.1）。
* profileDir：默認爲 %USERPROFILE%\.dsh\browsers\yandex。
* tabStateFile：記錄插件創建的標籤頁 ID，用於後續清理。

典型用法¶

一次典型的操作流程如下：

1. 檢查瀏覽器狀態：yandex_browser action: "status"。
2. 打開目標頁面：yandex_browser action: "open" url: "https://..."。
3. 讀取頁面內容以理解當前狀態：yandex_page action: "text"。
4. 執行點擊或輸入操作：yandex_act action: "click" selector: "..." 或 yandex_act action: "type" selector: "..." value: "..."。

關於登錄：
插件本身不會自動輸入密碼。智能體需要調用 yandex_browser action: "login"，在彈出的瀏覽器窗口中由用戶手動輸入賬號密碼。爲了保持會話，建議勾選“記住我”。

關於標籤頁清理：
插件創建的標籤頁是臨時的“垃圾數據”。在任務結束後，必須調用 yandex_act action: "close_created" 來關閉所有由智能體打開的標籤頁，以保持環境整潔。

適用場景與注意¶

該插件適合需要在瀏覽器環境中進行長期會話操作、需要複用已登錄狀態或使用特定擴展的 DSH 場景。

使用前請注意以下事實：
* 權限要求：插件以當前 DSH 進程的權限運行，請確保配置文件目錄有寫入權限。
* 本地迴環：CDP 連接必須使用 localhost（支持 IPv4/IPv6 雙棧），直接使用 127.0.0.1 可能因瀏覽器綁定地址不同而失敗。
* JS 語法限制：在 cordis.patch.yml 的 args 中，!!js 語法不會被解析。MCP 服務器配置（如 CDP 端點）需使用字符串字面量，不能使用環境變量拼接。
* 源碼審查：插件使用 MIT 許可證，但在生產環境使用前，建議審查源碼以確保符合安全要求。

結語¶

通過使用該插件，DSH 智能體獲得了在真實瀏覽器環境中工作的能力，結合持久化配置文件，能夠更自然地處理需要登錄、擴展或複雜交互的任務。