dsh-browser

中文 · English

为 DeepSeek Harness 生态打造的共享真实浏览器插件（装好即用，人机同页）

agent 驱动一个真实、可见、可随时人工接管的浏览器——人与 agent 操作的是同一个页面。

文档

这是什么

dsh-builtin-browser 给 DeepSeek Harness 提供浏览器能力:

• 真实页面,而非转播:页面由真实的浏览器承载 —— 桌面端就是官方侧栏里那一个,Web 端是插件拉起的窗口,也可以在设置里改用你本机的 Chrome / Edge。用户直接看到 agent 在做什么,随时可以上手接管;
• 人机同页(桌面端):agent 操作的页面与人看到的是同一个页面 —— 不再是一个你看不见的窗口;
• 装好即用:载体自动选择(桌面端侧重侧栏 → 否则自托管),纯 dsh web 不需要任何额外配置;
• 一插件即一套工具:安装后 agent 自动获得 34 个 browser_* 工具(打开、查看、无障碍树、等待、语义/坐标操作、滚动、回退、批量/单控件填表、按键、结构化提取、截图、下载、登录态管理……)。

一句话:安装插件 = 获得一个与用户共享、可被 agent 驱动的真实浏览器。

快速开始

插件要装进你要用的那一端的 profile 里。两端都装也可以,一份代码两个 profile 各一份。

Web 端(纯 dsh web)

# 从 npm 安装
dsh plugin --profile web add dsh-builtin-browser
# 或从源码目录安装(独立仓库,一插件一仓库)
dsh plugin --profile web add <本仓库路径>

桌面端(DSH Desktop)

# 1. 装进桌面端 profile
dsh plugin --profile desktop add dsh-builtin-browser

# 2. 桌面端特有的一步:让插件能驱动官方侧栏的页面
node <本仓库路径>/desktop-bridge/install.mjs

> 第 2 步不是可选项,而且每次都要重来一次:桌面端升级会替换 resources/app/,bridge 也随之消失;插件更新后同样需要重装。bridge 不在时插件自动退回"自己开一个独立窗口",功能不中断,只是失去"人机同页"。Web 端没有这一步。

更新(两端方式不同,详见更新方式)

安装后,agent 即可使用浏览器工具,例如:

完整清单见工具参考。

主要功能

共享真实浏览器
原生视图而非无头截屏。用户与 agent 操作同一个页面:用户能看到每一步,随时接管;agent 驱动的就是用户眼前那个窗口。
DOM 级驱动,框架友好
browser_snapshot 返回带编号的交互元素;browser_execute 在页面内执行 JS(受控输入用原生 setter + input/change 事件),React/Vue 页面也能可靠交互。语义定位优先 —— 不需要图像输入即可完整操作;设置成纯非视觉策略后,依赖截图的坐标点击会被明确拒绝并提示改用语义定位。
多标签会话
并行打开 URL,查看/切换/关闭/重置标签,每个会话的状态独立保持。桌面端下每个会话独占侧栏里自己的标签页,并可在自己的会话里继续开新标签,结束一个会话不会影响另一个。
多格式内容
以 html / markdown / txt / json 抓取页面,支持 CSS selector 限定、字符上限与超时控制。
任务级会话隔离
每个 DSH 任务(会话)拥有独立的浏览器会话(独立标签页与历史),并发任务互不抢页面、互不污染;同一任务内每次调用各开一个标签(cookie / 历史 / 登录态在同一会话内共享)。
登录态持久化
browser_auth 导出/恢复 cookie,重启后登录态不丢;自托管实例的 cookie 本身也落盘持久。
人机验证识别
自动检测 Cloudflare / reCAPTCHA / hCaptcha / Turnstile 等挑战(browser_challenge,快照也会标注),提示人工在共享窗口完成,不再盲目重试。
批量表单填充
browser_fill 一次填写多个字段:按选择器/名称/标签匹配,支持受控输入、下拉、单选/复选,可选提交;单个字段失败不影响其余字段。
操作历史与回放
browser_history 记录操作日志(打开/执行/点击/输入/填表/下载/登录),browser_replay 可按序号回放某一步。
带登录态下载
browser_download 在页面上下文内携带会话 cookie 拉取文件并落盘,登录后才能访问的内容也能直接下载。
安全限制
browser_restrict 限制允许的浏览器动作(白名单),防止 agent 误点、误导航;只读工具(snapshot / a11y / content / scrape / screenshot / get_value / wait / challenge / list_tabs / session / history / visited)加上「解除限制 / 复位会话」几个永远豁免,不受白名单影响。
截图即存即读
browser_screenshot 支持 savePath 直接落盘 PNG,交给视觉模型(modlens 等)做基于视觉的元素定位。
可查的浏览历史
browser_visited 读取持久化的访问记录(与 cookie 同址落盘,关闭浏览器、重启 DSH 后仍在),可按域名过滤并重新打开任意一条。它与 browser_history(会话内的操作日志)是两件事。
可视化鼠标
agent 操作时在页面内绘制虚拟光标、点击涟漪,并在指针旁用气泡标注当前动作 —— 光标出现即表示它已接管该标签页;DOM 级操作(填值/勾选/选择)同样有落点。不动真实系统鼠标,可在设置里关闭。
设置页里的「浏览器」栏
用哪个浏览器(侧栏浏览器 / 内置 Electron / 本机 Chrome / 本机 Edge / 自动)、历史是否保留、侧栏是否自动展开、会话结束时是否关闭浏览器、是否显示光标、视觉策略、是否允许读取凭据 —— 这些开关都是每次使用时现读,改完即时生效,无需重启。只有两个例外:browser.channel(用哪个浏览器)与 cookies.persist(是否保留 cookies)在插件挂载时读取一次,改完需要重新加载插件(重启 dsh / 刷新页面)才生效。栏里另有一组「Agent 能做什么」的动作开关 —— 执行页面脚本、下载文件到磁盘、写入登录状态 —— 它们与 browser_restrict 不是一回事:后者是模型自己的软护栏,模型随时可以解除;这三项写在设置文档里,没有任何工具能改它,模型只能被拒。
收尾明确
关掉承载页面 = 结束该会话(下次打开是干净的新会话)—— 桌面端是关掉侧栏里那个浏览器标签,Web 端是关掉窗口;浏览历史与登录状态不受影响。收起界面只是收起,浏览器继续运行。会话结束时是否自动释放,由设置项决定。

为什么选它

• 装好即用,零配置:不需要桌面外壳、不需要额外启动步骤;纯 dsh web 环境自托管拉起 Electron 窗口,browser_* 工具照常可用。
• 人机协同,互不干扰:用户能看到并接管 agent 的每一个动作;任务级会话隔离让多个并行任务各自拥有独立的标签页与历史。
• 面向真实世界的自动化:人机验证识别、登录态持久化、批量填表、带登录态下载、操作回放、动作限制——把"真实浏览器"变成可靠的 agent 能力。
• 可测试、可替换的架构:provider 与 Electron 通过 ElectronBrowserViewHost 接缝解耦,同一套工具层未来可对接无头转播 provider,无需改动模型侧。

工具参考

> 「守卫」列:打 ✅ 的动作受 browser_restrict 白名单约束;「– 豁免」的工具无论白名单怎么写都不拦截;「–」表示只观察、本来就不做动作,因此没有可拦的东西。豁免集合来自 READ_ONLY_TOOLS(src/tool-browser/index.ts):snapshot / a11y / content / scrape / screenshot / get_value / wait / challenge / list_tabs / session / history / visited,外加 restrict(白名单本身必须能解除,否则一旦限制到空就再也出不来)、reset_session、reset(从崩死状态恢复)。browser_close_tab 不在豁免集合里,与 open/click/switch_tab 一样可被限制;browser_auth 同样不在(它的 restore 会向任意域写 cookie,是动作而非观察)。

等待页面就绪

• browser_open/导航已有界等待新文档解析完成(readyState + 文档指纹,不把同 URL 重载或 A→B→A 重定向误判成旧文档),但仍不等异步内容:慢站点或依赖 XHR 渲染的页面,请在 browser_snapshot 之前先 browser_wait——传 url(你打开的地址)与可选的 selector,等它返回 ready: true 再拍照,否则拍到的是旧页面或白屏/空元素列表。
• 页面里看不到的内容先想 iframe / Shadow DOM:快照与无障碍树会穿透同源 iframe 与 shadow root 并标注 (iframe),坐标始终是顶层文档坐标,可直接用 browser_click;DOM 选择器则是 frame 作用域的,需用 browser_execute 经 iframe.contentDocument 访问。

语义定位(target)与无障碍树

• browser_a11y 是理解页面的首选:它返回每个交互节点的语义角色(button/textbox/checkbox…)、可访问名称、当前值与状态(checked/expanded/required…),比编号快照更能说明“这是什么、能做什么”。默认 150 个节点(maxNodes 10-5000,要更多请显式传),不再默认带坐标(需要像素落点时传 coords: true);states 只省略字面量 enabled(unchecked、collapsed 等仍会打印)—— 没有 states= 就是 enabled。每个节点的 name 就是 browser_click/browser_type 按 text 定位时匹配的东西。
• browser_click/browser_type 支持 target 定位:{by: css|text|xpath, value, index?}——text 按元素自身可见文本匹配(精确优先、退化包含、最深元素优先);点击会把元素滚动到视口中央再点;输入会先聚焦该元素。
• 单控件操作用 browser_set_value/browser_check/browser_select/browser_clear/browser_get_value,批量用 browser_fill,列表页结构化抓取用 browser_scrape。

操作纪律(定位/点击/填表)

• 先语义、后坐标:browser_a11y 给角色与可访问名称,browser_snapshot 给引用与坐标;两者都带选择器(见下一节),有选择器就优先用它 —— 它不会被滚动和布局变化作废。
• browser_click 的 target(css/text)本身就是语义定位,能用就别自己算坐标:滚进视野、中心点击、iframe 偏移、像素比都由它处理。
• 优先用 DOM 语义而非坐标:表单提交优先 form.requestSubmit();点击优先 element.click();坐标点击是最后手段。
• 选中正确的元素:页面常有隐藏副本(如移动端按钮),用 browser_execute 过滤可见元素(getBoundingClientRect() 宽高 > 0、getComputedStyle 非 display:none),再取坐标。
• 取坐标后立即点击:中间不要插入其他操作(填表、滚动会移动元素,旧坐标立即失效)。
• 点击前验证命中:document.elementFromPoint(x, y) 确认该坐标确实是目标元素(按钮/链接),再执行真实点击。
• DPR 注意:CDP 输入使用 CSS 像素;高 DPI 屏上若点击落空,用 elementFromPoint 校准,不要盲试坐标。
• 同一动作连败两次就换策略:换选择器、换语义定位、或重新快照 —— 不要第三次用同样的坐标。

视觉策略:先确认你在哪一种

设置里的 vision.strategy 决定坐标点击是否可行,而它只影响坐标一件事:

nonVisual 下用坐标点击会被明确拒绝,报 BROWSER_NON_VISUAL_COORDINATES,错误信息里直接给出改法:传语义 target,例如 target { by: "text", value: "Sign in" },它从 DOM 定位并点击元素中心。这不是故障,是配置 —— 不要重试同一次坐标点击。

两种策略下,DOM 查询、无障碍树、文本提取、结构化抓取的能力完全一致 —— 也就是说不需要图像输入也能完整操作页面。下面这节的"不该用截图"因此是给所有模型的默认建议,不是因为谁看不了图。

什么时候不该用截图

工具输出占用的是调用方的上下文,而截图是最贵的一种:

• 能用文本就用文本。 browser_snapshot / browser_a11y / browser_content 给出同一页面的文本表示;没有图像输入能力的模型看截图什么也得不到,只是白花。截图留给布局、图表、设计核对这类必须看像素的事。
• 降采样后结果里会返回 width/height(实际像素尺寸)。用 maxWidth/maxHeight 控制成本时,靠这两个数字确认它生效了,而不是自己解码 data URL。

人的三个开关,模型绕不过

设置页里的执行页面脚本、下载到磁盘、写入登录态由操作者控制,任何 browser_* 工具都改不了。关掉时报的错误码是明确的,看到它不要重试、不要绕路 —— 那是人的决定,直接说明"需要他在设置里打开":

BROWSER_EXECUTE_DISABLED(执行脚本)、BROWSER_DOWNLOAD_DISABLED(下载)、BROWSER_AUTH_WRITE_DISABLED(写入登录态)、BROWSER_AUTH_DISABLED(读 cookie)。

别和这两种混淆:BROWSER_DOWNLOAD_BLOCKED / BROWSER_SCREENSHOT_BLOCKED 是保存路径被沙箱拒绝(换路径,不是找开关);BROWSER_DOWNLOAD_UNSUPPORTED 是该载体没这个能力。

browser_restrict 不同 —— 那是模型自己设的临时白名单,可设可解除,但不该用来绕过上面三个门。

输出尺寸与截断

工具输出占用的是调用方的上下文,因此几处返回都有明确上限,并且截断时一定说出来:

• 快照与无障碍树带引用选择器:元素有 id 或 name 时,每行末尾附 {#id} / {[name=x]},可直接作为 browser_click/browser_type 的 target {by: "css", value: "#id"} —— 不用对着可访问名称猜文本;没有 id/name 的元素不带这一段(选择器推导不出来,工具不会编一个)。
• browser_content 按格式设上限(默认值):html 50 000 字符、json 50 000 字符、txt 20 000 字符、markdown 20 000 字符;单次调用用 maxChars 覆盖。被截断时结果末尾提示用什么手段收窄;selector 可先把范围限到一个区域。
• browser_content 的 json 返回的是元素标记:{"html": "<元素 outerHTML>", "tag": "标签名"},不是空对象(DOM 节点自身没有可枚举属性,JSON.stringify 一个 DOM 元素只会得到 {})。
• browser_execute 的返回值上限 50 000 字符,超出即在结果里写明"截断于 50 000 / 实际 N 字符",并提示改用更小的返回值。
• browser_scrape 的结果是紧凑 JSON(不缩进),前面带条目数 —— 缩进对模型没有信息量,却占实测输出的一成以上。
• browser_history 默认只展示最近 20 条操作、不重复回显参数(参数就是你刚发出去的东西),首行先给总条数,免得把尾部当成全部;确实要看参数时传 verbose: true。
• browser_visited 的时间戳精确到分钟,同一会话的标记只在切换时打印一次并取 8 位前缀,不是每行一份完整会话 id。

配置

插件通过 cordis.patch.yml 挂载四行:一个惰性的根行(只用来声明包名:宿主的客户端插件扫描按精确包名读该行的 dsh.client,以子路径命名的行会被整行跳过,少了这行设置栏不会出现)+ 三个功能行(browser / browser-electron / tool-browser)。各行配置:

工作原理

agent (browser_* 工具)
→ ctx.browser (seam, dsh-builtin-browser/browser)
→ dsh-builtin-browser/browser-electron (provider)
→ ElectronBrowserViewHost  ← 同一个接缝,三种载体各实现一份
① 桌面端侧栏      经 bridge → 外壳主进程 → webContents.debugger (CDP)
② 本机 Chrome/Edge 经 WebSocket → CDP
③ 自托管 Electron  经本机 TCP JSON-RPC → 子进程 → CDP

• seam 层(browser 行)提供 ctx.browser 服务:provider 注册、会话生命周期、错误码,与具体实现解耦;
• provider 层(browser-electron 行)只认 ElectronBrowserViewHost 这一个接缝(创建/销毁/显示/sendCommand),因此换载体不需要动工具、历史、光标与收尾逻辑;
• 工具层(tool-browser 行)提供模型侧的 34 个 browser_* 工具,按调用方任务(DSH 会话)维护独立的浏览器会话。

自托管模式:没有桌面外壳时,插件自己拉起一个 Electron 子进程(host-main.js),通过本机 TCP JSON-RPC 驱动。RPC 带随机 token 认证,token 经 stdin + 环境变量双通道传递——Windows 上 Electron 是 GUI 子系统进程、收不到 piped stdin,环境变量兜底保证握手稳定。子进程崩溃会自动重启;优先使用随插件安装的 electron 包(打包应用如 DSH Desktop.exe 不会被误当作可复用二进制,避免 spawn 秒退);截图优先走 Electron 原生 capturePage(CDP 截图在多视图下会挂起);Electron 的定位顺序见下(33.x 有合成器缺陷,建议 ≥ 40;44+ 的 electron 包不再随安装自动下载二进制,首次使用若缺失会按报错提示先 npx install-electron,需联网)。

自托管浏览器就是一台真正的浏览器(Web 端、或没有桌面外壳时的形态):每个任务(DSH 会话)拥有独立的浏览器窗口,窗口自带完整工具栏——地址栏、后退/前进/刷新按钮、标签条(新建/切换/关闭标签)。人可以直接像用 Chrome 一样使用它:在地址栏输入网址(自动补 https://)、点标签切换页面、开新标签;键盘焦点跟随点击——点地址栏即可输入、点页面即可操作(Windows 焦点路由,修复了点击不转移焦点导致地址栏无法输入的问题)。agent 与人的操作都汇入同一个会话模型(同一套标签、历史与导航),窗口标题实时显示当前任务标识与页面标题/URL,窗口缩放时视图自动跟随。任务结束后窗口随会话自动关闭。

Electron 定位顺序:① ELECTRON_PATH(显式覆盖,用户显式意图最优先)→ ② 随插件安装的 electron 包(纯文件系统探测,不触发 44+ 懒下载;覆盖 node_modules 与 pnpm store 两种布局)→ ③ DSH 安装锚点与 pnpm 虚拟仓库中版本最新者 → ④ 当前进程为裸 Electron 时复用宿主二进制(开发模式)→ ⑤ 进程祖先树中的裸 Electron 宿主(Windows 走 PowerShell CIM,仅最后手段)。打包应用(如 DSH Desktop.exe)一律不复用——它们不能按脚本参数拉起,误用会导致 spawn 秒退(issue #6);找不到时工具会报清晰的错误提示(含 npx install-electron 指引)。

与桌面外壳的分工

插件会自动选载体,也可以在设置里指定(共四种,见下):

① 桌面端:驱动官方侧栏的页面(人机同页)

DSH Desktop 是两层结构:Electron 外壳 + 一个 --expose-internals 的 Node 模式宿主(插件就跑在宿主里,没有 Electron API)。0.2 移除了 electronViewHost,宿主与外壳之间也没有任何承载视图的通道,所以插件借道一条小桥:外壳主进程里跑一个 loopback + token 的 bridge,把侧栏浏览器的 guest(就是你在界面上看到的那个页面)的 CDP 交给插件。

结果是:agent 操作的页面就是人看的页面,插件不再 spawn 自己的 Electron,也不再出现第二个窗口。

页面落在哪个会话,由发起的会话决定,与屏幕上显示谁无关。 外壳为每个会话各挂一个侧栏,而插件的渲染侧半边按会话 id 打开那一会话自己的面板(DSH 的 openTabIn),不读"当前显示的是谁"——所以"在 A 里让 agent 开页面、随后切到 B"不会把页面开到 B 去,结构上也没有通往别人侧栏的路径。

> 一条来自外壳的行为:外壳只渲染当前显示会话的侧栏。因此当发起会话不是屏幕上那个时,面板会被建立(它的标签确实进了那个会话),但页面要等该会话被显示时才附着上来。表现是:切走后在 A 里再让 agent 开页面,会得到一句"面板已放置,页面只能在被显示时附着",而 A 的侧栏此后一直是它自己的样子——那是提示,不是串扰。

安装这条桥(改的是已安装的桌面端,所以做成可重放):

node desktop-bridge/install.mjs            # 幂等;首次会备份 main.js.before-bridge
node desktop-bridge/install.mjs --revert   # 回滚

> 桌面端升级后要重跑一次 install.mjs —— 升级会替换 resources/app/,bridge 随之消失。bridge 不在时插件自动退回自托管,功能不会中断,只是会多出一个独立窗口。

> ⚠️ 沙箱边界的变化(请明示知悉)
>
> 官方侧栏浏览器的前提是:侧栏里的页面不被外部读取 —— 它有独立的 partition,且宿主拒绝跨站内容访问。让 Agent 驱动该 guest,等于有意打破这个前提:
>
> - Agent 能读到你在侧栏访问的任何页面的内容(这正是"人机同页"的意义);
> - Agent 能读到该 partition 中的 Cookie / 登录态,browser_auth 可将其导出(由设置项控制);
> - 反过来,你在侧栏里的操作与 Agent 的操作作用于同一个页面,可能互相影响(Agent 不会主动覆盖你的输入,但导航会改变双方看到的内容)。
>
> 这是"人机同页"的必然代价。我们认为值得(它把"Agent 在一个你看不见的窗口里操作"变成"你能看着它操作并随时接手"),但你有权知道它存在 —— 因此也提供了开关:「凭据访问」关闭后 browser_auth 的导出会被拒绝(BROWSER_AUTH_DISABLED)—— 它只管读;写入登录态(restore)另有「允许写入登录状态」开关,报 BROWSER_AUTH_WRITE_DISABLED,两者独立;「视觉策略」设为纯非视觉后,任何依赖截图定位的坐标点击都会被拒绝。不想接受这个边界变化时,把 desktop profile 里的插件移除即可回到"独立窗口"的旧形态。

② 用你自己的浏览器(Chrome / Edge)

设置里可以把载体改成本机已安装的 Chrome 或 Edge(browser.channel:bundled / auto / chrome / edge)。做法与 Codex Browser Use 一致:以 --remote-debugging-port=0 启动,读浏览器自己写下的 DevToolsActivePort 得到端口,再全程走 CDP(用 Node 22 内置的 WebSocket,不新增依赖)。

你自己的数据不会被碰:插件用的是独立 profile($DSH_HOME/dsh-builtin-browser-host/-profile),不会打开、占用或修改你日常的窗口、书签与登录状态;插件退出也不会关掉你的浏览器。

浏览器死了之后会自己回来:这个载体会观察子进程的退出并清掉已失效的会话映射(不只是缓存里的连接),所以重启后的浏览器是可用的,而不是"活着但每条命令都报 Session not found"。重新拉起前会先 kill 旧进程并最多等 3 秒它真正退出(Windows 上 kill 是异步的,不等就会把新进程交给旧实例、然后被误报成"路径不是可运行的浏览器"),并删掉上一轮写下的 DevToolsActivePort、只认本次启动之后写入的那份(否则会连到别的 Chromium 或 node --inspect 上,发布一个自己既不属于、也杀不掉的客户端)。反过来,页面慢不等于浏览器死了:命令超时只把连接标记为"存疑",下一次调用先用 Browser.getVersion 探一次再决定是否丢弃;只有socket 已关闭才直接重启 —— 因此一次慢页面不会让插件杀掉你正在用的浏览器窗口、连你打开的标签和填到一半的表单一起丢掉。

登录态怎么办:

• cookies.persist 开(默认)→ 上面那个固定 profile 会保留,重启 DSH 后仍是登录状态;browser_auth 也照常可导出/恢复该 profile 的 Cookie。
• cookies.persist 关 → 每次用临时 profile,释放浏览器时整个目录被删除,不留登录痕迹。进程被强杀时释放路径跑不到,所以下一次启动会先清扫上一轮残留的临时 profile —— 只清"属主进程已不在 且 一小时没有写入"的那些,免得删掉仍在运行的孤儿浏览器正在用的目录。
• 代价要说清:独立 profile 看不到你日常浏览器里已登录的站点 —— 在插件打开的窗口里登录一次即可,之后登录态就存在它自己的 profile 里。

③ 有 electronViewHost 的宿主(旧版桌面外壳):直接使用外壳提供的视图。

④ 没有外壳(纯 dsh web):自托管 —— spawn 插件自带的 Electron 窗口,功能照常。

> 可见视图与列布局始终属于宿主外壳;插件只负责 seam、provider 与工具。各形态下工具集、浏览历史、设置栏、可视化鼠标、收尾语义完全一致,差别只在页面由谁承载。
>
> 优先级:设置里显式选择的本机浏览器 > 桌面端侧栏 > 自托管。载体缺失时分两种处理:自动 的语义就是"哪个都行",找不到 Chrome/Edge 时记一条警告并继续用内置;明确选了某个浏览器而它没装时不再只写日志 —— 插件改挂一个只会解释原因的载体,每次命令都向调用方报出找不到的是哪个浏览器、查过哪些名字与位置,以及三条出路,不会让你对着一条关于 Electron 的错误去猜真正的原因。

环境要求

• DeepSeek Harness(dsh),已安装对应 profile(web / desktop 等)
• Electron 运行时(随插件自动安装,建议 ≥ 40;44+ 的二进制不随安装自动下载,缺失时按报错提示先 npx install-electron,需网络)—— 只有自托管载体需要它:
• ELECTRON_PATH 可显式指定其他二进制(最优先);
• 桌面端:默认走官方侧栏,不需要 Electron;退回自托管时使用随包 electron。打包宿主 exe(DSH Desktop.exe)不复用 —— 打包应用无法按脚本参数拉起,误用会秒退(issue #6);开发模式的裸 Electron 宿主仍可复用;
• 改用本机 Chrome / Edge 时也不需要 Electron;
• 纯 dsh web 自托管:直接使用随插件安装的 electron 包

验证过的版本

> 插件声明 electron >= 30。核心链路在 Windows 上完整实测;系统浏览器的查找已适配 Linux 与 macOS(先查 PATH,再查各平台的惯例安装位置,均可用 DSH_BROWSER_CHROME_PATH / DSH_BROWSER_EDGE_PATH 覆盖),但这两个平台上的端到端链路尚未实测,暂不承诺。

> 宿主兼容性可以随时复验:node scripts/verify-host-compat.mjs 会用某个 profile 里真实安装的
> @deepseek-ai/* 包组装一个宿主,加载本插件的编译产物、经宿主自己的 defineTool 注册工具、再用一个
> 假 provider 真调两个工具(browser_session / browser_a11y)。它回答的是"DSH 升级有没有把我们弄坏",
> 不需要启动浏览器。默认读 $DSH_HOME/profiles 下的 profile,可用 DSH_PROFILE / DSH_HOME 指定。
>
> 关于预发布版本的 semver 语义:范围 >=0.1.1-rc.2 <0.3.0 在 semver 默认语义下不匹配任何带
> 预发布标签的版本(如 0.2.1-alpha.1)—— 这是规范行为,预发布只被"同一 major.minor.patch 元组"的
> 比较器允许。DSH 判定插件兼容性时用的是 includePrerelease: true
> (packages/boot/app-boot/src/plugin-compatibility.ts),因此这些预发布宿主实际都在范围内;
> 若某个外部工具用默认语义得出"不兼容",那是它的语义与 DSH 不同,不是这里的声明写错了。

更新方式(两端不同)

插件在两种宿主里各有一份安装,更新路径也不同 —— 更新其中一端不会连带更新另一端。

桌面端(DSH Desktop)
- 插件是桌面端 profile 里的依赖(profile 目录通常是 $DSH_HOME/profiles/desktop)。更新它 = 把该 profile 里的依赖更新到新版本,然后重启 DSH Desktop,客户端设置栏与工具才会换成新代码。
- 桌面端还多一步,而 Web 端没有:让插件驱动侧栏的那条 bridge 装在桌面端自己的安装目录里(resources/app/),插件更新不会带上它。桌面端升级会替换该目录、bridge 随之消失,所以请重跑一次:

node desktop-bridge/install.mjs            # 幂等;已装则只刷新模块
node desktop-bridge/install.mjs --revert   # 回滚

bridge 不在时插件自动退回自托管(多出一个独立窗口),功能不中断。
- 浏览器内核默认由桌面端自带的 Electron 提供,插件不会再下载一份 Electron;也可以在设置里改用它自己装的 Chrome / Edge。
- 选了某个浏览器但它没装时会怎样:内置 用自己的 Electron;自动 挑一个已装的、都没有就安静地退回内置;明确选了 Chrome / Edge 而它不在时则直接报错说明找不到它(报错里写明查了哪些名字与位置,并给出三条出路:装上它 / 用 DSH_BROWSER_CHROME_PATH、DSH_BROWSER_EDGE_PATH 指定路径 / 把载体改回 内置 或 自动)—— 不会让你对着一条关于 Electron 的错误去猜真正的原因。
- 升级桌面端本身不会带上插件,按上面的方法单独更新它。

Web 端(dsh web)
- 插件是 web profile 里的依赖($DSH_HOME/profiles/web),更新后重启 dsh web 生效。
- Web 端没有侧栏、也没有 bridge:共享浏览器由插件自托管拉起。首次安装可能需要 Electron 二进制;若包管理器的构建白名单拦下了它(pnpm v10+ 会拦 electron 的 postinstall),执行一次 npx install-electron 补上即可。
- 同样可以在设置里改用本机 Chrome / Edge —— 这是两端行为一致的选项。
- 更新方式与你首次安装它时一致(按 npm 包名 dsh-builtin-browser、按 GitHub 仓库 wqty123/dsh-browser,或本地目录)。

两端一致的体验
- 工具集(34 个 browser_*)、设置页里的「浏览器」栏、浏览历史与 cookie 的持久化行为完全相同;差别只在页面由谁承载(桌面端=官方侧栏,Web 端=插件自托管窗口,或你在设置里指定的本机浏览器)。
- 升级不会丢数据:浏览历史与设置都在 $DSH_HOME/dsh-builtin-browser-host/(history.jsonl、settings.json),登录状态在同一 profile 目录里 —— 包括使用本机浏览器时的 -profile。
- 升级后如果历史记录不符合预期,先去「设置 → 浏览器」确认这些开关:历史默认开、侧栏自动展开默认开、会话结束时自动关闭浏览器默认关、载体默认内置。

已知限制

• JPEG 截图在自托管与本机 Chrome / Edge 上可用;桌面端侧栏走外壳的 webContents.debugger,其 Electron 的 CDP JPEG 编码会挂起,因此该载体下请求 JPEG 会返回 PNG。降采样(maxWidth/maxHeight)三种载体都支持(经 CDP clip.scale,或用自托管的原生 capturePage)。
• 自托管截图优先走 Electron 原生 capturePage(CDP captureScreenshot 在多视图下会挂起);截图前自动把目标标签置顶。
• fullPage 截图在部分主机的软件合成下不稳定 —— 请求 fullPage 时原生 capturePage 路径被整体跳过(capturePage 没有捕获滚动区以外内容的能力),因此三种载体都走 CDP 的 captureBeyondViewport,fullPage 的不稳定性与载体无关,任何载体都可能碰到;只有视口截图才优先走原生的 capturePage。
• 人机验证(CAPTCHA)无法自动解决:快照会标注检测到的挑战,此时应请用户在共享窗口中人工完成,而不是反复重试。
• 无痕模式(privateMode)未实现:它需要 Electron 的 session 分区能力,属于宿主层,本插件不承诺。
• 设置文档存在但读不懂(JSON 损坏、写到一半、权限读不到)时,四个门控开关(credentials.allowRead 与三个动作开关)一律按关处理,其余设置取默认值 —— "读不透操作者的意图"不等于"操作者什么都允许"。文件不存在(首次运行)仍按默认值。单个门控字段类型不对("false" 字符串、null、数字)同样按关;门控所在的小节整个写成非对象(如 actions: false、null、一个字符串)也按关 —— 而不是把里面的每个开关当成"缺席"、各取放行的默认值。
• browser_download 在页面上下文内 fetch(带登录态),受同源/CORS 约束;仅允许 HTTP(S) 目标;savePath 必须为绝对路径且位于 downloadDir 内(默认系统下载目录,自动识别 Downloads/下载/下載 与 XDG_DOWNLOAD_DIR,可用 downloadDir 覆盖),不覆盖已存在文件;browser_screenshot 的 savePath 走同一准入门;单文件上限 256MB(流式限流,按 Content-Length 提前拒绝),文件由浏览器子进程直接落盘(临时文件 + 原子改名)。准入还会解析路径的真实归属:downloadDir 里的符号链接无法把写入带出目录,悬空链接同样被拒(它读作"名字已被占用",而不是"路径空闲")。
• 自托管浏览器的 cookie 在磁盘上以明文存储(Electron 默认行为);需要加密落盘的部署应在宿主层接入系统钥匙串 / DPAPI。
• browser_restrict 是防误操作的软护栏,不是安全边界:模型可以自行解除白名单。要一个模型拿工具改不掉的限制,用设置页「Agent 能做什么」的三个动作开关(它们写在设置文档里,browser_* 工具没有一个会写它),或部署级的 tool-browser 配置 allowedActions(见 cordis.patch.yml 的注释)。这条边界要说准:设置走的是本机 HTTP 端点,写入要求带同源 Origin(裸 HTTP 客户端因此写不进去),但同源页面仍然可以写 —— 这是"插件暴露了一个 HTTP 端点"的固有代价,它不是凭据系统,面板上的说明也是这么写的。
• 页面弹窗(window.open / target=_blank)不再覆盖当前视图:HTTP(S) 弹窗会在同一会话窗口新开一个标签页并计入历史,原页面与 opener 上下文保留;非 HTTP(S) 弹窗(空 URL 弹窗承接、mailto:、自定义协议)仍放行原生窗口,交给系统处理——这类弹窗不纳入会话模型。
• browser_auth 的 cookie 往返不保留 hostOnly/sameSite 字段(host-only cookie 恢复后变成 domain cookie)。三种载体都可用:自托管走原生会话,侧栏与本机浏览器走 CDP 的 Network.getCookies / Storage.setCookies。flush 只导出当前页所属站点的 cookie,不是整台机器的共享 cookie 罐 —— 导出范围按本会话所在页面的 URL 收敛;页面上没有可用的 URL(未知范围)时直接拒绝,而不是扩大范围去读全部域(自托管侧栏载体报"无法确定 cookie 范围",CDP 载体报 BROWSER_AUTH_SCOPE_UNKNOWN);browser_restrict 的白名单也管着 browser_auth,因为 restore 是向任意域写 cookie 的动作。
• 自托管浏览器子进程崩溃(或宿主 DSH 重启)后会自动重启;崩溃前已打开的会话在下一次调用时自动重建——仅页面状态丢失,无需手动 browser_reset_session。browser_reset_session 仍可用于主动重置。新视图创建前会先有界加载 about:blank(3 秒上限,保证视图一存在就有可响应的渲染进程),宿主侧命令另有 20s 有界超时;子进程 stderr 与退出码/信号落到 $DSH_HOME/logs/dsh-builtin-browser-host.log,写之前若该文件已超过 2 MiB,则丢弃旧内容、只写入一行带时间戳的轮转记录(形如 log rotated: previous content exceeded 2097152 bytes and was discarded)—— 旧内容就此消失,不留副本,但那一行证明"曾发生过轮转",纯 dsh web 自托管可据此自助排查崩溃循环。
• electron 随插件安装;但 Electron 44+ 不再随安装下载二进制(约 100MB,需网络)——插件探测是纯文件系统、不触发其懒下载,二进制缺失时首次使用会报错并提示先 npx install-electron;也可预装 ELECTRON_PATH 指定的二进制。
• 本插件不提供任何浏览器界面(地址栏、标签条、侧栏面板都不是插件画的):桌面端的浏览器界面是外壳自带的官方侧栏,我们只是借它的页面来驱动;自托管载体下画窗口的是插件拉起的那个 Electron 子进程,那是载体本身而非插件 UI。别把"侧栏"或"浏览器列"当成插件能力。
• 侧栏载体不上报"用户操作"事件:人在那个页面里点击是外壳自己的事件,而 bridge 没有用于回报它的操作。因此依赖该事件的功能(如自定义的接管提示)在桌面端侧栏下不会触发;换到自托管载体则可以。
• 本机 Chrome / Edge 载体使用插件自己的 profile:插件用它自己的用户数据目录启动浏览器($DSH_HOME/dsh-builtin-browser-host/-profile),所以你日常浏览器里的书签、扩展与登录态不会自动继承 —— 这是刻意的,避免插件操作与你的个人会话混在一起;登录态是否跨重启保留由 cookies.persist 决定。

开发

# 类型检查 + 构建(lib/)
npm run build

> 运行测试: npm test(= tsc -p tsconfig.json + node --test "tests/*.test.mjs",假 host 测试,无需 Electron)。

代码结构:

更新记录

> 按轮次记录的开发与修复历程(完整明细见 CHANGELOG.md)。0.1.16 起随版本发布(tag v0.1.16)。