前言¶
給智能體做瀏覽器交互時最常見的問題是：你能點擊、能輸入、能讀文本，但任務結束後手上沒有留下任何能復盤的東西。想回答「爲什麼頁面當時顯示的是那個值」「接口返回裏到底說了什麼」時，只能再跑一遍，還不一定復現。
已有做法大致兩類：一類只做遠程控制，截一張圖或讀一下 DOM；另一類把能力拆得很細，但取證動作要靠自己拼。dsh-omni-browser 把控制和取證合併成 16 個 omni_* 工具：通過 CDP 驅動本機已安裝的 Chrome / Edge / Chromium，同時把 DOM、可訪問性樹、帶響應體的 HAR、控制台日誌、Cookie 與各類存儲、截圖、PDF、屏幕錄像寫進同一個帶 manifest 的時間戳目錄。倉庫裏不再內置 Chromium，也沒有云端服務，代碼不依賴 npm 包。
下面介紹這個插件由誰維護、怎麼裝、怎麼用、哪些地方需要注意。
插件由 wanwujiehuyi-web 維護，託管在 GitHub 上，在 DSH 社區目錄中歸爲「聯網工具」分類。倉庫 MIT 許可，版本 0.1.0，是一個偏底層的瀏覽器控制與取證工具。
它解決了什麼問題¶
普通瀏覽器插件給的是遙控能力；這個插件在此基礎上多了一個「取證相機」。一次調用 omni_capture 就會產出目錄，裏面包含頁面快照、可訪問性樹、HAR、控制台日誌、各類存儲、截圖、PDF 與屏幕錄像幀。目標是讓智能體的每一步操作都有可復現、可歸檔的證據。
適用方向包括：真實站點上的智能體調研、需要可復現的缺陷報告、合規或存檔快照、需要拿到網絡層真實數據的抓取、以及排查「爲什麼頁面顯示的是這個值」。
安裝與啓用¶
官方給出的安裝命令是：
dsh plugin --profile desktop add github:wanwujiehuyi-web/dsh-omni-browser
如果該插件尚未進入 DSH 市場註冊表，可以先用本地檢出方式在 DSH GUI 中安裝：
plugin_manager → install_bundle → /absolute/path/to/dsh-omni-browser
運行環境要求：DSH 啓用 tools 服務、Node 22 及以上、本機已安裝 Chrome / Edge / Chromium。
安裝後插件會在 cordis.patch.yml 中掛載配置，功能通過環境變量或 config 開啓。
核心功能¶
插件註冊了 16 個工具，可以直接在 DSH 中調用：
omni_status：查看 Chrome 是否在運行、有哪些標籤頁、版本與 profile，可launch/close/restart。omni_open：打開 URL，可複用標籤頁或新建，等待load/domcontentloaded/networkidle。omni_tabs：list/new/close/activate。omni_page：讀取頁面內容，模式包括snapshot、text、html、ax、links、forms、meta、outline、frames、resources。omni_act：click、dblclick、hover、focus、type、press、scroll、select、check、uncheck、upload、drag、wait、back、forward、reload，產生的是真實輸入事件。omni_eval：在頁面內執行 JS 並返回 JSON。omni_screenshot：viewport/fullpage/element/clip，輸出真實文件。omni_pdf：把當前頁打印爲 PDF。omni_network：list、body（單個響應體）、har、stats、save、clear。omni_console：list/clear/save控制台消息與未捕獲異常。omni_storage：all、cookies、local、session、indexeddb、cache、sw、save。omni_capture：一次調用產出完整取證目錄。omni_harvest：限定範圍的多頁抓取，每頁一個取證目錄。omni_record：對標籤頁錄屏 N 秒，輸出 JPEG 幀與 manifest。omni_download：enable（設置下載目錄）、wait、list。omni_perf：metrics、trace、coverage、resources。
元素定位支持四種寫法：{ "selector": "#id" }、{ "text": "Sign in" }、{ "ref": "ax:1234" }（ax 引用來自 omni_page mode=ax）、{ "x": 100, "y": 200 }。
典型用法¶
實際操作按「開頁 → 看快照 → 取證」三步走。
omni_open { "url": "https://example.com" }
omni_page { "mode": "snapshot" }
omni_capture { "name": "example" }
先看 omni_page 的快照確認頁面狀態，再執行取證。omni_capture 的返回類似：
{
"ok": true,
"dir": "D:\\work\\omni-capture\\example-20261105-151230",
"manifestPath": ".../manifest.json",
"fileCount": 14,
"totalBytesText": "1.8 MB",
"files": [{ "path": "page.png", "bytes": 184212 }, "..."]
}
目錄內容是固定的幾類產物：
manifest.json schema + per-artifact status + timings
page.json title, url, meta, outline, links, forms, counts
page.png viewport screenshot
page-full.png full-page screenshot (beyond the fold)
page.pdf print-to-PDF (vector text)
dom.html rendered DOM (outerHTML)
text.txt readable innerText
ax.json accessibility tree (roles/names/values/backend ids)
network.har.json HAR 1.2: headers, timings, post data, bodies
network.json compact request list
bodies/0001-*.json response bodies (failures by default, all with bodies:"all")
console.json console messages + uncaught exceptions
storage.json cookies + localStorage/sessionStorage/IndexedDB/CacheStorage
cookies.json cookies only
perf.json runtime metrics
resources.json resource tree with sizes
各部分是優雅降級的：如果 PDF 或某個響應體拿不到，其餘文件仍會寫出，manifest 裏記錄對應錯誤。
倉庫自帶離線測試，針對本地 fixture 站點跑：
node test/smoke.mjs # CDP transport health check
node test/tools.test.mjs # all 16 tools end-to-end
配置項¶
配置都是可選的，寫在插件 config（cordis.patch.yml）或環境變量裏：
| Env | 含義 | 默認值 |
|---|---|---|
OMNI_CHROME_PATH |
瀏覽器可執行文件 | 自動探測 Chrome/Edge/Chromium |
OMNI_PORT |
CDP 端口（0 表示自動選空閒端口） |
0 |
OMNI_HEADLESS |
1 / 0 |
1 |
OMNI_USER_DATA_DIR |
瀏覽器 profile 目錄 | ~/.dsh/omni-browser/profile-<DSH profile> |
OMNI_OUTPUT_DIR |
取證目錄位置 | <cwd>/omni-capture/<timestamp>/ |
OMNI_HOME |
插件數據目錄 | ~/.dsh/omni-browser |
插件使用獨立 browser profile，不會碰個人 Chrome 會話。在同一 profile 目錄內登錄後 cookie 會在多次運行之間保留，適合需要登錄態的任務。
適用場景與注意事項¶
適合的場景：智能體在真實站點上做調研、需要給出可復現證據的缺陷報告、合規與存檔快照、需要網絡層真實數據的抓取任務。
要注意的幾點：
1、插件以當前 DSH 進程的權限運行，能訪問該進程可訪問的網絡與文件系統。安裝前建議先讀一遍源碼，確認 cordis.patch.yml 中註冊的能力與環境變量符合預期，再決定是否啓用；許可證爲 MIT。
2、取證目錄裏可能包含 session cookie、請求頭裏的 token、頁面正文等內容，應視爲敏感數據。如果只需要鍵名不需要值，omni_storage 可傳 includeValues: false 做脫敏。
3、瀏覽器 profile 默認是隔離的，但輸入進去的內容是真實的，跑高風險自動化時建議用專用賬號，不要複用個人賬號密碼。
4、該工具面向你已被授權訪問的站點，不是繞過訪問限制的抓取工具，也不解決 CAPTCHA。
結尾¶
dsh-omni-browser 的價值在於把「驅動瀏覽器」和「留下可復盤的證據」做成一條流水線，使智能體執行完瀏覽器任務後，不需要再靠口頭描述還原現場。適合需要頻繁操作真實站點、並且關心可復現性的開發者。
插件目錄頁：https://www.skillhub.cn/plugins/wanwujiehuyi-web/dsh-omni-browser
GitHub：https://github.com/wanwujiehuyi-web/dsh-omni-browser
DSH 的理念是「一切皆插件」，上述目錄頁屬於獨立社區站點，與 DeepSeek / 幻方沒有官方從屬關係。
