dsh-browser-lens

dsh-browser-lens

给 DeepSeek Harness 一副真浏览器的手和眼：操作你自己的 Chrome / Edge（点击、中文输入、滚动、下拉）， 并且能把一个页面整份抓下来——DOM、无障碍树、截图、Cookie、本地存储、控制台、每一条网络请求（HAR）、 资源瀑布、性能指标，全部落盘成一个可以离线复盘的证据包。

不打包 Chromium，不依赖 puppeteer / Playwright，零运行时依赖（只要 Node 22+）。 启动的是你本机已经装好的浏览器，登录态、插件、证书都是你自己的；窗口就在桌面上， 你可以随时接管（扫码、过验证码、点授权），agent 在旁边看、接着干。

┌─────────────────────────────┐         ┌──────────────────────────────┐
│  DeepSeek Harness (host)    │  CDP    │  你的 Chrome / Edge          │
│  dsh-browser-lens ──────────┼────────▶│  --remote-debugging-port     │
│  12 个 browser_* 工具        │ WebSocket│  独立 profile，登录态可复用  │
└─────────────────────────────┘         └──────────────────────────────┘

---

为什么需要它

模型的困境一直很具体：

• 看不见网页。web_fetch 拿到的只是 HTML 文本，SPA 一片空白，动态渲染的内容永远是空的。
• 点不了按钮。搜索、翻页、登录、填表单，全靠人手动复制粘贴。
• 起不了浏览器。很多 agent 跑在受限沙箱里（比如 Windows 的作业对象沙箱）， Chromium 的多进程架构需要命名管道，一启动就 crash（mojo ... Check failed: 拒绝访问 (0x5)）。

前两个是能力问题，第三个是环境问题。插件跑在宿主进程里，不受 shell 沙箱限制—— 这正是把浏览器放进插件而不是脚本的原因。

它解决什么

层	能力	对应工具
看	页面大纲：标题层级、可交互元素（每个带可直接用的 CSS selector + 坐标）、表单、表格、图片、正文、meta	browser_snapshot
抓	整页证据包：DOM / AX 树 / 截图 / Cookie / 存储 / 控制台 / 全部请求 / HAR / 性能	browser_capture
动	真实鼠标点击、键盘输入（支持中文）、快捷键、滚动、悬停、下拉选择	browser_act

关键设计：给模型的是「可操作的结构」，不是一堆 HTML。 browser_snapshot 返回的每个可交互元素都自带 selector，模型直接拿着它去 browser_act， 不需要猜 CSS、不需要数 div。

安装

方式一：插件市场（推荐）

在 DeepSeek Harness 里打开 Plugins → Discover，搜索 browser-lens，点安装。 （市场索引源 https://cdn.jsdelivr.net/npm/dsh-plugin-catalog/index.json）

方式二：命令行

dsh plugin --profile desktop add dsh-browser-lens

方式三：源码

git clone https://github.com/wanwujiehuyi-web/dsh-browser-lens
cd dsh-browser-lens
dsh plugin --profile desktop add "$(pwd)"

装好后重启 Harness（或让 HMR 自己热更），工具列表里会出现 12 个 browser_* 工具。

快速上手

直接用自然语言说：

「打开 https://example.com，看看这页有什么，然后点『Learn more』」

或者自己拼：

// 1. 启动浏览器（有头：窗口会出现在桌面上）
{ "tool": "browser_launch", "headless": false }

// 2. 打开网址，等网络空闲
{ "tool": "browser_open", "url": "https://news.ycombinator.com" }

// 3. 看页面：可交互元素都带 selector 和坐标
{ "tool": "browser_snapshot", "format": "outline" }

// 4. 点它
{ "tool": "browser_act", "action": "click", "text": "More" }

// 5. 在输入框里打中文 + 回车
{ "tool": "browser_act", "action": "type", "selector": "#q", "value": "生成式 3D 建模", "enter": true }

// 6. 整页抓下来复盘
{ "tool": "browser_capture" }

12 个工具

工具	做什么
browser_launch	启动或复用本机 Chrome/Edge，开调试端口（默认 9333），独立 profile
browser_close	关闭标签页 / 断开连接 / 连浏览器一起关
browser_tabs	标签页管理：list / new / close / activate
browser_open	打开网址并等就绪（load / networkidle / domcontentloaded）
browser_snapshot	看页面：outline（推荐）/ text / html / ax / links / forms / tables / resources / perf
browser_act	click / type / press / scroll / hover / select / wait；定位支持 selector、文字、坐标
browser_eval	在页面里执行 JS 取回结果（复杂取数、改样式）
browser_screenshot	截图存盘：视口 / 整页（最多 20000px）/ 单个元素
browser_capture	全量抓取成一个目录（见下）
browser_inspect	快速看 network / console / cookies / storage / perf / resources / errors / history
browser_network	网络录制开关 + 导出 HAR
browser_pdf	页面打印成 PDF 存盘

browser_capture 里有什么

一个目录，index.md 是摘要，其余是原始证据：

capture-20261105-150432/
├── index.md              # 人/模型先读这个：标题、URL、统计、正文前 4000 字
├── meta.json             # 抓取时间、视口、目标页信息
├── page.html             # 原始 DOM（含动态渲染后的结果）
├── page.txt              # 正文纯文本
├── outline.json          # 标题层级 / 可交互元素 / 表单 / 表格 / 图片 / meta
├── ax.json               # 无障碍树（最接近"人看到什么"）
├── screenshot-full.png   # 整页截图
├── screenshot-viewport.png
├── cookies.json          # 含 httpOnly（走 CDP，不是 document.cookie）
├── storage.json          # localStorage / sessionStorage / IndexedDB / CacheStorage
├── console.json          # 控制台消息（log / warn / error / 页面异常）
├── errors.json           # 未捕获异常与 CSP 违规
├── network.json          # 每一条请求：方法、URL、状态、类型、响应头、耗时、请求体
├── har.json              # 标准 HAR 1.2，可直接丢进 Chrome DevTools / Fiddler 分析
├── resources.json        # 资源瀑布（performance resource timing）
└── perf.json             # DCL / load / FCP、JS 堆、DOM 节点数等

典型用途：调研网站结构、排查线上问题、留证、把网页变成离线可分析的语料。

设计取舍

为什么用本机浏览器，不打包？ 打包 Chromium 要下载 150MB+，还要跟着上游版本升级。用一个已经存在的浏览器， 零下载、零构建，而且用户自己的登录态和扩展都在——这才是「帮人干活」需要的。

为什么零依赖？ Node 22 自带 WebSocket，CDP 就是 JSON 消息，自己实现一个 300 行的客户端就够了 （lib/cdp.mjs）。不引入 puppeteer，就不会有版本冲突、原生模块编译、Electron 打包三重麻烦。

为什么有头模式是默认？ 无头快，但过不了人机验证、看不到渲染差异、用户也没法接手。 有头模式下窗口就在桌面上，agent 点、用户也能点，是协作而不是黑箱。

为什么抓无障碍树？ agent 需要的是「这页能做什么」，AX 树正好是这个：role + name + 状态，比 DOM 短一个数量级， 而且天然过滤掉装饰性元素。

安全

• 调试端口只监听 127.0.0.1（Chromium 默认行为，额外加了 --remote-allow-origins 限制来源）
• 用独立 profile（默认在 Harness 数据目录下），不碰你日常浏览的 Cookie
• browser_capture 会把 Cookie / 存储落盘——产物目录按敏感数据处理，别提交进 git
• 登录、支付这类动作，建议有头模式 + 人在场

环境要求

• DeepSeek Harness >= 0.2.1-rc.1 < 0.3.0（由 dsh.engines.dsh 声明）
• Node.js >= 22（用到内置 WebSocket）
• Windows / macOS / Linux 上任一：Chrome、Edge、Brave、Chromium
• 可用 BROWSER_LENS_CHROME 环境变量指定浏览器路径，BROWSER_LENS_DIR 指定数据目录

测试

# 离线：假浏览器 + 假网络，验证 12 个工具的协议层与序列化（18 项）
node test/mock.mjs

# 真浏览器：启动 → 导航 → 点击 → 中文输入 → 回车 → 截图 → 抓取（需要能起 Chrome）
node test/live.mjs https://example.com

# 端到端：完全走插件工具层（13 项，含本地 HTTP 服务验证 cookie / storage / HAR）
node test/e2e.mjs

实测：Chrome 156 上 mock 18/18、e2e 13/13 通过。

已知限制

• 只驱动「本插件启动的」或「已在同端口监听」的浏览器；不接管用户已开着的普通窗口（那是另一种设计，见 dsh-native-browser）
• iframe 内部元素需要在 frame 上下文里操作（当前版本大纲里会列出 iframe 及其位置）
• 关闭 shadow DOM 内部的元素需要先 browser_eval 拿宿主路径
• 不支持同时并排驱动多个不同端口的浏览器实例（一个宿主进程一个默认实例）
• 下载（Page.setDownloadBehavior）尚未封装成工具

License

MIT © wanwujiehuyi-web