前言¶
在 DSH（DeepSeek Harness）裏做聯網或表單類任務時，常見做法是再套一層「瀏覽器 Agent」：多一個 LLM、多一套 API key，步驟還往往藏在黑盒裏。若你希望 DSH 自己的 agent 就是大腦——寫出的 Python 留在會話歷史裏、可讀可審計——就需要把瀏覽器控制面直接註冊成會話工具。
dsh-browser-harness（維護者 chaserchan）做的是這件事：把 browser-use 的 Browser Harness 接到 DSH，讓 agent 通過 browser_run 執行 Python，在本地驅動真實 Chrome（導航、點擊、填表、無障礙樹、JS/CDP、截圖）。不需要額外的 LLM，也不需要 API key（Autopilot 除外，見後文）。插件在 SkillHub 分類爲「聯網工具」，倉庫 chaserchan/dsh-browser-harness，許可 MIT。
這是什麼¶
Browser Harness 不是「又一個 LLM agent」，而是給 coding agent 用的瀏覽器控制面。DSH agent 寫每一行 Python，Harness 在 Chrome 上執行；狀態主要落在 daemon 附着的那塊標籤頁上，而不是跨次調用的 Python 進程變量裏。
插件當前版本 0.4.4（以 package.json 爲準），面向 web profile 的 DSH（engines.dsh 要求 >=0.1.0-rc.6 <0.2.0，Node >=22.13）。
核心功能¶
會話工具¶
| 工具 | 作用 |
|---|---|
browser_run({ code, timeoutMs?, lane? }) |
把一段 Python 交給 Harness 執行；print() 輸出即返回值；返回 {ok, exitCode, stdout, stderr, hint}。ok=false 時先讀 hint。 |
browser_status({}) |
體檢：命令解析來源、模式、BU_NAME/CDP、doctor、autopilot 狀態；browser_run 報錯時先調它。 |
browser_autopilot({ url, goal, lane? }) |
目標式自動化；僅配置了 TypeSafe API Key 時可用（未配置時工具拒絕，且系統提示詞不注入該工具）。 |
插件還會把 函數速查表與操作紀律 注入系統提示詞，agent 知道 Harness 側有哪些函數、哪些不存在。
人機協同（0.2.0 起）¶
典型場景：開發者賬號申請、平臺註冊、複雜表單——agent 能填的自動填，登錄/驗證碼/掃碼等交還用戶。
流程概括：
agent：打開頁面 → show_tab() 讓你看到 → form_fields() 摸清表單 → 普通字段自動填
agent：遇到登錄/驗證碼/掃碼/支付 → show_tab() + 說明「這步你來」
你： 在瀏覽器裏完成
agent：wait_url_change() 檢測跳轉 → 繼續 → page_brief() 彙報
每個 browser_run 會自動注入 helper（零 import 直調），例如：
ax_list() # 可交互元素 [{role,name,cx,cy}]
ax_click(role=None, text=None)
form_fields()
fill_field(字段名, 值)
show_tab()
wait_url_change(舊url)
page_brief() # {url,title,elements,text}
人機協同需要 看得到 Chrome：默認 dedicated（有頭專用瀏覽器）即可，agent 與你在同一標籤頁交替操作。
多會話併發：lane 車道（0.3.0 起）¶
多個 DSH 會話共用一個 harness daemon 會搶「當前 tab」。0.3.0 起可爲 browser_run 指定 lane：每個 lane = 獨立具名 daemon（BU_NAME=<buPrefix>-<lane>）+ 持久專屬標籤頁，跨 lane 可真並行，同一 lane 內調用串行。
browser_run({ code, lane: "apple" }) # 任務 A
browser_run({ code, lane: "router" }) # 任務 B，與 A 並行
單任務可不傳 lane（按會話隔離）；多任務並行時爲每個並行任務固定 lane 名，同一任務始終帶同一 lane。調試可用 browser_status({}) 的 lanes.active，或 browser_run({ code: 'print(list_tabs())', lane: 'apple' }) 查看某車道 tab。
Autopilot（0.4.0，條件啓用）¶
配置 TypeSafe API Key 後，可用 Jev（TypeSafe 開源的 System One 瀏覽器模型，非 LLM）做目標式自動化：
browser_autopilot({ url: "https://...", goal: "完成開發者賬號註冊並進入控制台" })
沒配 key：工具直接拒絕，模型甚至看不到該工具。配了 key：settings 熱加載即可用。執行還需本機安裝 jev-ultrafast，並在插件 config 中設置 autopilotCommand（例如 'uvx jev-ultrafast'）。Key 也可通過環境變量 TYPESAFE_API_KEY / TEXT_MODEL_API_KEY（設置面板優先）。
安裝與啓用¶
1. 安裝 Harness CLI（前置）¶
uv tool install browser-use # 完整版（含 agent 庫，依賴較多）
# 或更輕的等價物（推薦）：
uv tool install browser-harness # 同一份 harness，依賴只有 4~5 個純 Python 包
裝完建議立刻關閉 Harness 默認遙測（stdout 尾部最多 20KB 會上報）：
browser-use telemetry disable
2. 安裝 DSH 插件¶
dsh plugin --profile web add dsh-browser-harness
或從本地路徑：
dsh plugin --profile web add file:/path/to/dsh-browser-harness
裝完後 dsh --profile web --dump-config 中應出現：
- id: browser-harness
name: dsh-browser-harness
配置要點¶
在 profile 的 cordis.patch.yml 裏用 id 定向覆蓋（不要 - insert:）：
- id: browser-harness
config:
mode: dedicated # dedicated（默認）| system
command: browser-use # 或 browser-harness，或絕對路徑
timeoutMs: 120000
cdpPort: 9334
chromeArgs: ['--proxy-server=http://127.0.0.1:7890'] # 需要代理時
| 鍵 | 默認 | 說明 |
|---|---|---|
mode |
dedicated |
自起專用 Chrome，與日常瀏覽器隔離；system 附着正在用的 Chrome |
command |
自動解析 | Harness 可執行文件；建議顯式配置（見「已知陷阱」） |
buName |
dsh-browser |
具名 daemon 的後臺 tab |
cdpUrl / cdpPort |
空 / 9334 |
自帶 CDP 時填 cdpUrl |
userDataDir |
~/.dsh-browser-profile |
dedicated 獨立配置目錄 |
chromeArgs |
[] |
代理、窗口大小等 |
timeoutMs |
120000 |
單次執行預算，上限 600000 |
restoreTab |
true |
是否用 BU_NAME 獨立後臺 tab |
autopilotCommand |
空 | jev 運行體命令 |
同配置也可用環境變量：DSH_BROWSER_USE_MODE / DSH_BROWSER_USE_BIN / DSH_BROWSER_USE_PORT / DSH_BROWSER_USE_PROFILE。
TypeSafe / Text Model Key 在 DSH 設置頁 → 通用設置 → 瀏覽器自動化（本插件註冊的配置區）。
典型用法¶
最小驗證思路¶
browser_status({})確認command、commandSource、模式與 CDP。browser_run({ code: '...' })裏寫 Harness Python（如打開 URL、print標題）；輸出在stdout。- 需要與用戶交替操作時，在代碼裏調用
show_tab()、wait_url_change()等 helper。 - 多會話並行時爲各任務固定
lane字符串。
具體 Harness API 以插件注入的速查表爲準；README 中的 e2e 思路是「真機打開網頁並把 title 打回來」（見倉庫 node test/e2e.mjs）。
適用場景與注意¶
適合：需要在 DSH 會話裏可復現地操作真實頁面——抓信息、填表、半自動註冊、與用戶在同一 Chrome 標籤上協同——且接受「agent 寫 Python、Harness 執行」的架構。
權限與安全：browser_run 允許 agent 執行 任意 Python，是代碼執行式設計的固有屬性；插件不額外提權、不提供沙箱。只在你信任的環境使用；安裝前請自行查看源碼與 MIT 許可證。插件以當前 dsh 進程權限運行。
已知陷阱（README 原文要點）：
- PATH 上的
browser-use可能是舊版原子 CLI（如 v0.12.3），不認 stdin Python 協議；報錯時看browser_status.command與commandSource，並建議顯式設config.command。 - 插件已在用戶代碼前前置
ensure_daemon()，緩解冷啓動超時。 - 每次
browser_run是新 Python 進程，變量不跨調用；持久狀態在 tab。 - 同一 daemon 只有一個當前 tab；無 lane 時插件內部串行排隊。
- dedicated 模式 Chrome 不繼承系統代理；外網需
chromeArgs配代理。
結尾¶
dsh-browser-harness 把 Browser Harness 註冊爲 DSH 工具，本地、無額外 LLM/API key 即可用 Python 驅動 Chrome；可選 TypeSafe key 啓用 browser_autopilot。社區目錄頁：SkillHub - dsh-browser-harness；源碼與完整說明：GitHub - chaserchan/dsh-browser-harness。
