dsh-plugin-browser

English | 中文

给 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 <<'EOF'
- insert:
    - id: dsh-plugin-browser
      name: dsh-plugin-browser
EOF

# 4. 重启 DSH Desktop

只想给某个 profile 用:把第 3 步的行写进 ~/.dsh/profiles/<名称>/cordis.patch.yml 而不是机器级文件。

方式 B:dsh CLI 用户

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