Tianyu209/dsh-browser-companion

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