q35888/dsh-plugin-browser

dsh-plugin-browser

给 DSH（DeepSeek Harness）装上 15 个浏览器工具:会话里的模型可以直接操作一个已登录的真实 Chrome——你在浏览器里登过什么(GitHub、内网、订阅站点),模型就能访问什么,不用重新输密码。

你: 帮我看看 github 今天有什么通知
模型: browser_navigate → browser_snapshot → 读到通知列表 → 汇报给你

工具(15 个)

| 工具 | 用途 |
|---|---|
| browser_session | 启动/切换会话(real 已登录 Chrome \| isolated 独立无痕) |
| browser_navigate | 打开 URL |
| browser_snapshot | 列出页面可交互元素,带 ref 编号(默认只列视口内,省 token) |
| browser_click / browser_type / browser_select_option / browser_hover | 点击/输入/选下拉/悬停,用 ref 精确定位 |
| browser_tabs | 标签页管理(列出/切换/关闭/新建) |
| browser_handle_dialog | 预设 JS 弹窗(alert/confirm)的处理策略 |
| browser_eval | 在页面执行 JS(等同 F12 控制台) |
| browser_storage / browser_console | 读 cookies/localStorage / 读控制台日志 |
| browser_wait_human | 遇到验证码/登录时在 DSH 界面弹卡片等你操作完确认(5 分钟超时) |
| browser_screenshot | 截图存文件 |
| browser_close | 关闭会话(real 模式只断连接,不关你的 Chrome) |

Chrome 没开?插件会自动拉起,不需要你手动启动。

安装

⚠️ 两种方式二选一,混用会产生重复插件行导致 DSH 启动失败。

方式 A:DSH Desktop 用户

1. 克隆并安装依赖
git clone https://github.com/q35888/dsh-plugin-browser.git \
~/.dsh/profiles/web/plugins/dsh-plugin-browser
cd ~/.dsh/profiles/web/plugins/dsh-plugin-browser && npm install --ignore-scripts
npx playwright install chromium   # 仅 isolated 模式需要(~95MB);只用 real 模式可跳过

2. 建立包名解析链接
ln -sfn ../web/plugins/dsh-plugin-browser ~/.dsh/profiles/node_modules/dsh-plugin-browser

3. 追加到机器级配置(对所有 profile 生效)
cat >> ~/.dsh/cordis.patch.yml /cordis.patch.yml 而不是机器级文件。

方式 B:dsh CLI 用户
bash
dsh plugin --profile web add github:q35888/dsh-plugin-browser
再把 "dsh-plugin-browser" 加进 ~/.dsh/profiles/web/package.json 的
dsh.profile.bundles 数组(包已自带 bundle patch)

配置(全部可选)

| 环境变量 | 默认值 | 说明 |
|---|---|---|
| AGENT_BROWSER_DIR | ~/.pi/agent | 根目录,下面几项默认从这里派生 |
| AGENT_BROWSER_CHROME_STARTER | /start-agent-chrome.sh | 自定义 Chrome 启动脚本(存在则优先用;适合要挂代理/特殊参数的场景) |
| AGENT_BROWSER_CDP_PROFILE | /chrome-cdp-profile | 已登录 Chrome 的用户数据目录——你的登录态存这里 |
| AGENT_BROWSER_ISOLATED_PROFILE | /bw-mcp-profile | isolated 模式的独立目录 |
| AGENT_BROWSER_CDP_PORT | 9222 | CDP 端口 |
| AGENT_BROWSER_ISOLATED_CHANNEL | 未设 | 设为 chrome 让 isolated 模式用系统 Chrome 而非 Playwright 自带 chromium。macOS 慎用:无头系统 Chrome 会被 macOS 认定为"正在运行的 Chrome",导致你点 Dock 图标打不开日常 Chrome |
| AGENT_BROWSER_NO_SANDBOX | 未设 | 设为 1 强制 Chrome 加 --no-sandbox(一般只在特殊环境需要) |

默认目录说明:默认值是为了和 agentic-browser-mcp(本插件的原型)的用户无缝共存——两者可以共享同一个已登录 Chrome。如果你没用过它、也不在乎共存,设置 AGENT_BROWSER_DIR 换成自己的目录即可,插件会自动创建。

想带登录态:首次用 real 模式时插件会拉起一个专用 Chrome 窗口(和你的日常浏览器完全独立),在里面手动登录一次你要的站点,登录态持久保存在 AGENT_BROWSER_CDP_PROFILE 目录,以后每次直接可用。

使用要点
- ref 是临时的：每次 snapshot 重新编号，页面变化后先重新 snapshot 再操作
- 验证码/二次验证：模型会调 browser_wait_human，DSH 界面弹出卡片，你去浏览器操作完点确认即可
- 多标签页：新开的标签页自动跟随；需要固定某个标签页用 browser_tabs 的 switch
- 隐私提示：browser_eval/browser_storage 能读取浏览器里的 cookies 和登录凭据——请只在你信任的会话中使用本插件

故障排查

- 模型说 Chrome 连接失败 —— 插件已内置自愈（窗口全被关掉但 Chrome 进程还活着的“僵尸”状态会自动恢复一个标签页）；持续失败就彻底退出 Chrome 再让模型重试
- 自己的 Chrome“点了打不开”（macOS） —— 旧版本的无头 isolated 会话用系统 Chrome 启动，会被 macOS 认定为“Chrome 正在运行”从而挡住你的日常 Chrome；已修复（isolated 默认用 Playwright 自带 chromium，与系统 Chrome 完全隔离）。若你设置了 AGENT_BROWSER_ISOLATED_CHANNEL=chrome 又用无头模式，此现象会复现
- 自动拉起失败（找不到 Chrome） —— 插件按常见安装位置 + PATH 查找；都找不到时写一个启动脚本并设 AGENT_BROWSER_CHROME_STARTER 指向它
- 截图在哪 —— /bw-shots/

已知限制

- 同一个 DSH 进程里的多个会话/子代理共享同一个浏览器标签页，并发使用时会互相干扰（单会话内已串行保护）
- isolated 模式下如果 DSH 意外退出，独立浏览器进程可能残留，手动关闭即可；real 模式不受影响
- 依赖 DSH 的 rc 期工具 API，DSH 大版本升级后若失效，删掉机器级配置里的两行即可完全回滚

License

MIT