侧边栏浏览器 alesha-pro/dsh-sidebar-browser

dsh-sidebar-browser

English · Русский

这是 DSH Desktop（DeepSeek Harness）的插件，让模型能用内置浏览器。它加了 17 个 browser_ 工具，可以在右侧边栏打开和关闭标签页，并在其中读取、点击、输入、滚动和截图。它用的就是你正在看的那个 Browser 标签页，而且按正常方式启动应用就能用。

真实会话，4 倍速：模型在侧边栏标签页里导航、搜索、滚动，并高亮出答案。

DSH Desktop 自带这个浏览器，但只给人用。包 @deepseek-ai/dsh-client-ui-sidebar-browser 注册了一个 UI 标签页，没有任何模型工具，它的宿主端只有一行 function apply() {}。我找到的其他浏览器插件，要么驱动单独的 Chrome 或 Chromium 窗口，要么靠解包 app.asar 去够到侧边栏，而后者在 macOS 上会让应用的代码签名失效。这个插件直接在侧边栏标签页里工作，不改动 DeepSeek Harness.app。

快速开始

在 DSH Desktop 里打开 Plugins，按 Add plugin，输入包名：

dsh-sidebar-browser-cdp

同一个输入框里填 Git 地址也行，而且总是安装最新提交：

github:alesha-pro/dsh-sidebar-browser#path:/plugin

DSH 通过 pnpm 安装，而 pnpm 在你只给一个裸包名时，会跳过不到一天前发布的版本。所以发布后的头一天，裸包名装到的是上一个版本。加上版本号，比如 dsh-sidebar-browser-cdp@0.3.0，或者用 Git 地址拿当前版本。0.2.0 及更早的版本需要带调试端口启动应用。

按 Install，再按 Enable now。DSH 自己下载插件和它的依赖。开一个新会话，让智能体在浏览器里做点什么。它会自己用 browser_open 打开标签页，或者在你右侧边栏已经开着的 Browser 标签页里干活。

不需要任何启动参数。这样安装的插件住在 desktop 配置档里，每个工作区都能用。

在终端里装也一样，先把应用关掉：

DSH="/Applications/DeepSeek Harness.app/Contents/Resources/runtime/cli/bin/dsh"
"$DSH" plugin --profile desktop add dsh-sidebar-browser-cdp

桌面应用在那个路径下自带 dsh 命令行。如果 dsh 已经在你的 PATH 里，直接用那个就行。

从本地克隆安装

想改插件的时候用这个。dsh plugin add <path> 是链接文件夹，不是复制，所以插件需要有自己的 node_modules。

git clone https://github.com/alesha-pro/dsh-sidebar-browser.git
cd dsh-sidebar-browser/plugin
npm install
"$DSH" plugin --profile desktop add "$PWD"

要求

DSH Desktop 0.2.0-rc.2。这里的一切都是我在该构建（Electron 44、Chrome 152）上、在 macOS 上实测的。Windows 和 Linux 未测试。
* 需要有一个已打开的 DSH Desktop 窗口。插件有一半运行在窗口里，工具通过它和页面通信。
* 页面工具需要一个已加载 URL 的 Browser 标签页。shell 会延迟创建 webview，所以必须先调用 browser_open，或者手动打开一个标签页。
* 调试端口是可选的，提供下面说的 2 项功能。需要时用 open -a "DeepSeek Harness" --args --remote-debugging-port=9222 启动应用。

工具

| 工具 | 作用 |
| browser_open | 打开新的 Browser 标签页，侧边栏折叠时展开它，并加载 URL |
| browser_close | 按标题关闭侧边栏标签页，或关闭当前标签页，或折叠侧边栏 |
| browser_tabs | 列出浏览器标签页，并显示当前受控的是哪一个 |
| browser_snapshot | 标题、URL，以及可交互元素的编号列表 |
| browser_navigate | 在当前标签页打开 URL |
| browser_click | 按快照编号点击元素，单击或双击 |
| browser_type | 向元素输入文本；支持 React 和 Vue 输入框，replace 会先清空字段 |
| browser_press | 发送一个按键：Enter、Tab、Escape、方向键或某个字符 |
| browser_scroll | 向上、向下、到顶部或到底部，作用于滚动页面的那个元素 |
| browser_text | 页面可见文本 |
| browser_html | 按编号取元素的 outerHTML |
| browser_eval | 在页面中执行 JavaScript |
| browser_screenshot | 视口的 PNG，长页面则按视口大小切片 |
| browser_history | 后退、前进、重新加载 |
| browser_cookies_import | 重启后恢复已保存的登录状态 |
| browser_cookies_export | 把某个站点的 cookie 存进本地保险库；这个工具需要调试端口 |
| browser_cookies_vaults | 列出已保存的保险库 |

元素编号来自最近一次 browser_snapshot。快照会把编号以 data-dsh-idx 属性的形式写到页面上，在下一次快照之前一直有效。

传输方式

插件有两半。宿主那一半注册工具。客户端那一半（plugin/lib/client.js）由应用自带的插件加载器载入 DSH 窗口，就在右侧边栏旁边。一次工具调用会变成队列里的一条命令，窗口通过 DSH 自带 web 服务器上的 2 条路由取走它，执行后再把结果回传。

在窗口里，客户端那一半使用应用已经暴露出来的东西：

* 侧边栏服务（sidebarRight.openTab、close、toggleExpanded）用来打开和关闭标签页；
* <webview> 元素自带的方法（executeJavaScript、sendInputEvent、insertText、loadURL、goBack）处理页面上的一切。这样发出的点击和按键会作为受信任事件到达。
browser_tabs 会告诉你这次调用走的是哪条路：via the app window 还是 via the debug port。

没有调试端口时截图

<webview> 元素有个 capturePage() 方法，在这个构建版本上，从窗口里调用它会让窗口的渲染进程崩溃。所以没有端口时，页面自己画自己。插件把 modern-screenshot（MIT，已内置在 plugin/lib/vendor/）加载进页面，它把 DOM 克隆进 SVG foreignObject，再画到 canvas 上。布局、文字和字体都来自浏览器本身，在 Wikipedia、GitHub 和 Hugging Face 上，我一眼看不出结果和像素截图有什么区别。

但这仍然是重新渲染，不是截图。Canvas、video、iframe，以及没有 CORS 的图片，都可能一片空白，工具的输出里会写 rendered in-page from the DOM。一个视口要花几秒。应用带调试端口运行时，browser_screenshot 改用像素截图。

调试端口

用 --remote-debugging-port=9222 启动应用，插件就能直接对 webview 说 CDP。这条路只为一件事必需，同时改进另一件事：

* browser_cookies_export 需要它。登录信息存在 HttpOnly cookie 里，页面脚本读不到。
* browser_screenshot 变成像素截图。

Playwright 和 Puppeteer 当不了这个 CDP 客户端。Electron 把侧边栏 webview 报告为 webview 类型的 target，这两个库只列 page 类型的 target，而它们找到的唯一 page 就是 harness UI：

$ node probes/probe.mjs # playwright-core, connectOverCDP
contexts: 1
ctx0 app-shell :: dsh-app://app/
RESULT: no webview page found

$ node probes/pp-test.mjs # puppeteer-core, connect()
puppeteer pages(): 1
- dsh-app://app/ | <the harness UI>
all targets:
webview :: https://example.com/
page :: dsh-app://app/
!! puppeteer cannot see the webview as a page

插件读 /json/list，只保留 type === 'webview' 的 target，然后连到那个 target 自己的 webSocketDebuggerUrl。两个探针都在 probes/ 里，想复现结果可以自己跑。

bundle 的 transport 设置决定走哪条路：auto（默认）优先用应用窗口，需要时用端口，window 和 cdp 则强制选一条。

命令行

cli/browser.mjs 是调试端口引擎的独立脚本，没有任何依赖。它要求应用带端口启动，并且 Browser 标签页已打开，写脚本或手动验证机制时都很好用。

node cli/browser.mjs tabs
node cli/browser.mjs snapshot
node cli/browser.mjs click 12
node cli/browser.mjs type 3 "hello" --replace
node cli/browser.mjs press Enter
node cli/browser.mjs scroll down 800
node cli/browser.mjs text --max 4000
node cli/browser.mjs eval "document.title"
node cli/browser.mjs screenshot out.png --full
node cli/browser.mjs navigate example.com
node cli/browser.mjs back | forward | reload
node cli/browser.mjs html 12
node plugin/selftest.mjs 用桩上下文加载插件代码，并针对运行中的应用跑一遍它的调试端口路径。

登录与 cookie 保险库

内置浏览器在你退出应用时会忘掉登录状态。桌面外壳给每个工作区分配一个会话分区，名字随机，且不带 persist: 前缀——在 Electron 里这意味着一个内存会话：

// DesktopBrowserGuests.acquire(owner, workspace)
partition = dsh-sidebar-browser-${randomUUID()}
this.configureSession(session.fromPartition(partition))

同一个会话会拒绝所有权限请求，阻止下载，并且只放行不指向 harness 自身的 http(s)、data 和 blob 请求。插件无法从外部改动其中任何一项。

cookie 保险库绕开了登录丢失的问题。保险库是 ~/.dsh/cookie-vault/ 下的一个文件，恢复它不需要调试端口：

browser_cookies_import { domain: "example.com" }

拿到文件有 2 种方式：

* 从 DSH 导出。带调试端口启动应用一次，登录，然后调用 browser_cookies_export {}。这是插件里唯一需要端口的步骤。
* 从你日常用的浏览器导出该站点的 cookie，格式为 Cookie-Editor JSON 或 Netscape cookies.txt，把文件保存为 ~/.dsh/cookie-vault/<site>.json。browser_cookies_import 也能读这些格式。

没有端口时，页面自己通过 document.cookie 设置 cookie。脚本无法设置 HttpOnly 属性，服务器也永远看不到这个属性，所以登录状态照样能恢复。在我的测试里，服务器收到了用这种方式恢复的 __Secure- 和 __Host- cookie。代价是，恢复后的 cookie 在该标签页里能被站点自己的脚本读到。端口打开时，导入设置的是真正的 HttpOnly cookie。

我在真实登录上通过调试端口测了完整往返。应用重启后，导入恢复了 6 个 cookie 中的 6 个，站点的会话端点返回已认证。保险库是快照，所以再次登录后，或者站点轮换 token 后，要重新导出。

保险库文件以 600 权限写入 700 目录。文件里是明文的活动会话 token，请像对待密码一样对待它们。.gitignore 已经排除了它们。

Electron webview 实测到的怪癖

| 行为 | 实际表现 |
| 对 <webview> 元素调用 capturePage() | 从应用窗口调用会让窗口的渲染进程崩溃（EXC_BREAKPOINT），应用卡死。插件从不调用它 |
| 对完全被遮挡的窗口调用 Page.captureScreenshot | 完全被遮挡的窗口不绘制，调用永远不返回。插件等 6 秒后回退到页内渲染 |
| 带 captureBeyondViewport 的 Page.captureScreenshot | 图像重复视口，而不是显示整页。DOM 里有 1 个 和 1 个信息框，图像里却有 3 份副本。full: true 改为滚动并分片截图 |
| Page.reload 走 CDP | 它可能把 CDP target 弄挂。走端口时，reload 是导航到当前 URL |
| 键盘快捷键 | 通过 CDP 发送 Cmd+T 不会打开标签页。标签页通过侧边栏服务打开 |
| 带 scroll-behavior: smooth 的页面 | 滚动调用在页面移动之前就返回了，所以工具强制瞬间跳转 |
| SPA 滚动 | 内部容器滚动时 window.scrollY 停在 0。工具会找到滚动的元素并报告它的位置 |
| 禁止 eval 的页面上的错误 | executeJavaScript 把抛出的错误报成 1 条笼统消息。在 CSP 允许 eval 的页面上插件能还原真实文本，在 GitHub 上不行 |
| 长截图 | DSH 里的图片读取器拒绝单边超过 8192 px 的图片，这也是长页面以切片形式返回的又一个原因 |

限制

* 工具作用于窗口中可见的 Browser 标签页。如果智能体在一个会话里干活，而你在看另一个，它会驱动你正在看的那个标签页。
* 属于其他主机、与页面不匹配的 cookie，没有调试端口就无法恢复。导入会按名称报告它。

安全

* 默认模式下插件不开任何端口。它往 DSH 已经为自己的窗口运行的 web 服务器上加 2 条路由，/dsh-sidebar-browser/poll 和 /dsh-sidebar-browser/reply。它们只接受 JSON POST 请求，网页跨源发这种请求必须走预检。我没有审计 DSH 自己是怎么保护那台服务器的。
* 调试端口如果你用的话，监听在回环地址上。它开着的时候，任何本地进程都能接入整个应用，包括 harness UI。需要时用那个 flag 启动应用，其余时间正常启动。
* 插件的宿主代码在进程内运行，在工作区沙箱之外。安装前先读 plugin/lib/index.js 和 plugin/lib/client.js。
* browser_eval 在页面里运行任意 JavaScript，cookie 工具会处理会话 token。只在你能接受智能体以你的身份行事的站点上使用它们。
* 插件不解包 app.asar，也不碰应用的代码签名。它在你机器上改两处东西：~/.dsh/profiles/desktop/package.json 里的一个 bundle 条目，以及如果你用了的话，~/.dsh/cookie-vault/。

卸载

在 Plugins 页面卸载 bundle，或者从 ~/.dsh/profiles/desktop/package.json 的 dependencies 和 dsh.profile.bundles 里删掉 dsh-sidebar-browser-cdp。如果你导出过 cookie，删掉 ~/.dsh/cookie-vault/。

目录结构

| 路径 | 是什么 |
| plugin/lib/index.js | 宿主那一半：工具、命令队列、调试端口客户端 |
| plugin/lib/client.js | 客户端那一半：在 DSH 窗口里运行，驱动 webview |
| plugin/lib/vendor/ | modern-screenshot 4.7.0 及其许可证 |
| cli/browser.mjs | 独立的裸 CDP 命令行 |
| probes/ | 上面引用的 Playwright 和 Puppeteer 探针 |

许可证

MIT 协议。本项目与 DeepSeek 无关联。我从一份已安装的副本中阅读了 DSH 内部实现，未做任何修改。