前言¶
给智能体做浏览器交互时最常见的问题是：你能点击、能输入、能读文本，但任务结束后手上没有留下任何能复盘的东西。想回答「为什么页面当时显示的是那个值」「接口返回里到底说了什么」时，只能再跑一遍，还不一定复现。
已有做法大致两类：一类只做远程控制，截一张图或读一下 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 / 幻方没有官方从属关系。
