dsh-browser-companion

一个面向个人的 DeepSeek Harness (DSH) 浏览器插件。

它给 Agent 一个专属、持久、可见的浏览器：

• 你可以实时看到 Agent 在真实浏览器窗口里做什么。
• 登录由你在弹窗中手动完成；密码和 OAuth 密钥不会经过 Agent。
• Cookies 和登录状态保存在同一个 profile 中，重启后依然保留。

功能特性

• ✅ 持久化浏览器 profile（cookies / localStorage / 登录状态）
• ✅ 可见窗口模式（默认 headless: false）
• ✅ 人机交互登录：browser_login 打开窗口，由你自己输入密码 / 完成 OAuth
• ✅ Agent 工具：open、snapshot、click、type、press、screenshot、see、select、check、upload、hover、scroll、tabs、status
• ✅ 安全护栏：browser_type 禁止填写密码框
• ✅ browser_see 使用本地视觉模型（OpenAI 兼容），让 Agent 理解图片 / 视觉布局
• ✅ 基于 agent-browser，底层浏览器自动化经过实战检验

开箱即用

插件默认零配置即可使用基础浏览功能：

• 默认使用 agent-browser 自带的 Chromium
• 默认使用 ~/.dsh/browser-profile 作为持久化 profile
• 基础工具全部可用：open、snapshot、click、type、tabs 等

可选设置可以在 DSH WebUI 插件设置中修改：

• executablePath：填真实 Chrome/Edge 路径，解决 Google 等登录拦截
• visionBaseUrl / visionModel：启用 browser_see 本地视觉模型
• profilePath：自定义浏览器 profile 位置

如果 browser_see 未配置，会返回友好提示，不会影响其他功能。

安装

1. 安装依赖

npm install -g agent-browser
agent-browser install   # 首次下载 Chromium

2. 安装插件

从 npm 或 GitHub 安装：

dsh plugin --profile web add dsh-browser-companion

pnpm 用户注意： 从 GitHub 安装时，pnpm 可能会阻止 agent-browser 的 build script。 在 profile 的 pnpm-workspace.yaml 中加入并重新运行：

allowBuilds:
  agent-browser: true

本地开发也可以直接加到 ~/.dsh/profiles/web/cordis.patch.yml：

- insert:
    - id: dsh-browser-companion
      name: 'file:///absolute/path/to/dsh-browser-companion/src/index.js'
      config:
        profilePath: '/home/your-name/.dsh/browser-profile'
        headless: false
        executablePath: '/path/to/your/chrome'
        browserArgs: '--disable-blink-features=AutomationControlled'
        defaultTimeout: 30000

完整示例配置见 examples/dsh-browser-companion.config.yml。

⚠️ 不要把真实路径、Token 或个人数据提交到 Git。请使用示例配置并在本地替换。

3. 重启 DSH

dsh web

Agent 工具

工具	说明
browser_open	打开网页（默认显示可见窗口）
browser_snapshot	获取带 @e1 引用的可访问性快照
browser_click	点击元素
browser_type	输入文字（禁止用于密码框）
browser_press	按键
browser_screenshot	截图保存到本地
browser_see	截图 + 本地视觉模型描述（仅在需要时使用）
browser_get_text	读取元素文本
browser_get_url / browser_get_title	获取 URL / 标题
browser_wait	等待时间 / 元素 / URL
browser_back / forward / reload	导航
browser_select	选择下拉框
browser_check / browser_uncheck	勾选 / 取消勾选
browser_upload	上传文件
browser_hover	鼠标悬停
browser_scroll	滚动页面
browser_tabs / browser_new_tab / browser_close_tab / browser_switch_tab	标签页管理
browser_status	浏览器状态
browser_login	打开可见登录窗口，由用户手动登录
browser_wait_login	等待登录完成（Cookie / URL）
browser_close	关闭浏览器（保留 profile）

典型登录流程

Agent: 我需要登录某个网站。
Agent 调用 browser_login("https://example.com/login")
→ 你看到弹窗，手动输入账号密码 / 完成 OAuth
→ 你告诉 Agent “登录好了”
→ Agent 继续用同一份 Cookie 操作

Agent 如何“看”页面

• 默认： browser_snapshot — 快速、免费的可访问性快照。
• 仅在需要时： browser_see — 截图 + 本地视觉模型，用于图片 / 视觉布局 / 复杂界面。

配置项

配置项	默认值	说明
profilePath	~/.dsh/browser-profile	持久化 profile 目录
headless	false	是否隐藏浏览器窗口
defaultTimeout	30000	单次操作超时（毫秒）
agentBrowserPath	自动检测	覆盖 agent-browser CLI 路径
executablePath	自动	Chrome/Edge 可执行文件路径（推荐用于 Google 登录）
browserArgs	--disable-blink-features=AutomationControlled	额外浏览器启动参数
visionBaseUrl	http://127.0.0.1:1234/v1	本地视觉模型地址
visionModel	your-vision-model	本地视觉模型名称

安全说明

• Agent 被明确禁止填写密码框。
• 密码和 OAuth 密钥由用户在可见浏览器窗口中手动输入。
• 未来版本可以增加加密 Cookie 存储和代理式凭据注入，提供更强保护。

开发

npm install
npm test

License

MIT