# DSH Browser Control
简体中文 · English
Chrome 浏览器扩展 + DeepSeek Harness 插件，让 AI Agent 像人一样操控你的真实浏览器。
## 这是什么
不是无头浏览器，不是 Puppeteer——是你的**真实 Chrome**，带着你的登录态、你的 cookies。AI 通过 Chrome DevTools Protocol 驱动标签页，你可以在屏幕上看到每一步操作。
```
你对 AI 说一句话
↓
Agent 调用 browser_* 工具
↓
DSH 插件（WebSocket 桥）
↓
Chrome 扩展（CDP 驱动）
↓
你的真实浏览器执行操作
↓
结果返回给 Agent
```
## 和 MCP 浏览器方案的区别
市面上已经有 Playwright MCP、Puppeteer MCP、browser-use 等，它们的共同点：启动一个**自己下载的全新浏览器实例**。本项目走的是另一条路：
| | 本项目 | Playwright / Puppeteer MCP |
|---|---|---|
| 浏览器 | 你正在用的真实 Chrome | 自动下载的独立实例 |
| 登录态 / Cookies | ✅ 全部继承，无需重新登录 | ❌ 每次全新 profile |
| 过验证码 / 扫码登录 | 你的会话已经登录，基本不遇到 | 经常卡在登录墙 |
| 可见性 | 屏幕上实时可见，随时鼠标接管 | 无头运行或独立窗口 |
| 环境依赖 | 无需 Node / npx / Python | 需要 npx 或 uvx 运行时 |
| 接入方式 | 加载扩展 + 设置页开关 | 编辑 MCP 客户端 JSON 配置 |
| 磁盘占用 | 复用现有 Chrome，零新增 | 额外下载数百 MB 浏览器 |
| 集成深度 | dsh 原生插件（设置卡片 / 状态页 / 清理按钮） | 通用 MCP server |
一句话：**要 AI 用"你自己的"浏览器干活（已登录的 B 站、知乎、淘宝后台），用本项目；要做跨浏览器、跨应用的通用自动化测试，用 MCP。**
## 下载
| 文件 | 说明 |
|---|---|
| [DSH-Browser-Control-1.0.7.zip](https://github.com/caob23/dsh-browser-control/releases/download/v1.0.7/DSH-Browser-Control-1.0.7.zip) | Chrome 扩展（解压后加载） |
| [dsh-browser-control-plugin-v1.0.7.zip](https://github.com/caob23/dsh-browser-control/releases/download/v1.0.7/dsh-browser-control-plugin-v1.0.7.zip) | dsh 插件（离线兜底，在线装直接用方式 A/B） |
## 安装 Chrome 扩展（30 秒）
下载 zip → 解压到固定文件夹（别删）→ Chrome 打开 `chrome://extensions` → 开启「开发者模式」→ 点「加载已解压的扩展程序」→ 选解压后的文件夹。
工具栏出现鲸鱼图标 → 绿点呼吸 = 已连接。需要 Chrome 116+。
## 安装 dsh 插件
📦 本包是 bundle 包（package.json 中 `dsh.bundle.patch` 指向 `cordis.patch.yml`）。`dsh plugin` 安装成功后会自动把它加入 profile 的 `dsh.profile.bundles`，重启即加载。
前置：`dsh plugin` 转发给 pnpm，需要 pnpm 在 PATH 上；首次使用会自动初始化目标 profile。
### 方式 A：从 npm 安装（推荐）
```bash
# 通过 dsh plugin 从 npm registry 安装并自动注册到 profile
dsh plugin --profile web add @caob23/dsh-browser-control
```
如果自行管理 profile 的 node_modules，也可以在对应目录中直接使用 npm 安装：
```bash
npm install @caob23/dsh-browser-control
```
### 方式 B：从 GitHub 或本地目录安装
```bash
# 直接从 GitHub 安装
dsh plugin --profile web add "github:caob23/dsh-browser-control#v1.0.7"
# 本地目录调试（注意：必须显式 file: 前缀）
dsh plugin --profile web add "file:D:\path\to\dsh-browser-control"
```
重启 DSH 后生效。卸载：
```bash
dsh plugin --profile web remove @caob23/dsh-browser-control
```
> ⚠️ 本地目录请用 `file:` 前缀。裸路径 / 相对路径会被 pnpm 当作 `link:` 协议，
> 在 hoisted 布局下不会物化到 node_modules 顶层，导致启动时无法解析该包。
安装并重启后，桥接默认开启（v1.0.6+），不需要再去设置里手动启用。状态页 http://127.0.0.1:9777/ 可看到服务已监听。
> 想关掉默认开启：在 `~/.dsh/settings.yml` 的 `browser-bridge.config` 下写 `enabled: false` 即可。
### 方式 C：复制进 harness 源码树（旧方式，v1.0.2 及以前）
```bash
git clone https://github.com/caob23/dsh-browser-control.git
cd dsh-browser-control
git checkout v1.0.2 # 旧布局在 v1.0.2 tag
./install.sh /你的路径/deepseek-harness
```
脚本只负责把插件文件复制到位，**完成后仍需手动改三处配置**，改完重启 dsh 才会生效：
下载 [`dsh-browser-bridge-plugin-v1.0.2.zip`](https://github.com/caob23/dsh-browser-control/releases/download/v1.0.2/dsh-browser-bridge-plugin-v1.0.2.zip)，解压到 deepseek-harness 的 `packages/web/browser-bridge/`。
然后补充三处配置：
1. `packages/bundle/base/package.json` 的 dependencies 加：
```json
"@deepseek-ai/dsh-browser-bridge": "workspace:^"
```
2. `cordis.patch.yml` 的 plugins 列表加：
```yaml
- id: browser-bridge
name: '@deepseek-ai/dsh-browser-bridge'
config:
enabled: false
```
3. `tsconfig.host.json` 的 references 加：
```json
{ "path": "./packages/web/browser-bridge" }
```
重启 dsh → 设置页出现「DSH 浏览器控制」→ 开启即可。详细说明见 [dsh-config/README.md](dsh-config/README.md)。
## 使用
1. dsh 设置 → 插件 → DSH 浏览器控制 → 开启
2. Chrome 扩展自动连接（端口 9777，Token 默认 dsh-local）
3. 对话说自然语言，Agent 自动操控浏览器
访问 `http://127.0.0.1:9777/` 查看连接状态。
## 工具清单
| 工具 | 功能 |
|---|---|
| `browser_navigate` | 导航到 URL |
| `browser_read` | 读取页面文本/HTML |
| `browser_snapshot` | 页面快照 → ref 交互树 |
| `browser_click` | 点击元素（by ref / selector） |
| `browser_type` | 在输入框填入文本 |
| `browser_press` | 模拟键盘按键 |
| `browser_scroll` | 滚动页面 |
| `browser_tabs` | 标签页管理（列表/新建/关闭/切换） |
| `browser_evaluate` | 执行任意 JS |
| `browser_screenshot` | 截取页面截图 |
| `browser_console_log` | 抓取页面 console 日志（v1.0.7+） |
| `browser_network_log` | 抓取 HTTP 请求/响应（v1.0.7+） |
| `browser_pdf` | 当前页导出 PDF（v1.0.7+） |
| `browser_emulate` | 切设备视口（移动 / 桌面 / 自定义，v1.0.7+） |
| `browser_cleanup` | 清理临时文件 |
## 架构
```
Chrome 浏览器
└─ DSH Browser Control 扩展 (MV3)
└─ chrome.debugger (CDP)
└─ WebSocket ──────→ DSH 插件 (browser-bridge)
└─ browser_* 工具 → Agent
```
**关键设计：**
- 扩展主动外连桥（不需要 native messaging host）
- 默认关闭，设置页手动开启
- 持久 debugger 附着——控制期间横幅始终显示
- 仅监听 127.0.0.1，token 认证
## 已验证
| 场景 | 结果 |
|---|---|
| 百度搜索 → 提取结果标题 | ✅ |
| B 站搜索用户 → 发私信 | ✅ |
| B 站搜索 → 统计视频卡片 + 截图 | ✅ |
| 单元测试 29/29 | ✅ |
| 类型检查（host + client） | ✅ |
## 更新日志
见 [CHANGELOG.md](CHANGELOG.md)。
## 许可证 · License
本项目采用 **GNU Affero General Public License v3.0 (AGPL-3.0)**。
- **个人 / 学术 / 非商业用途**：完全免费，在遵守 AGPL-3.0 的前提下自由使用、修改、分发
- **企业 / 商业用途**：AGPL-3.0 要求通过网络使用本软件也构成"分发"，必须公开衍生代码。若企业在闭源产品中嵌入、基于本项目构建 SaaS 服务而不愿开源，需要联系作者获取**商业许可**（另行协商授权条款）
- **商业许可咨询**：[GitHub Issues](https://github.com/caob23/dsh-browser-control/issues) 或邮箱 **caob2333@outlook.com**
完整许可证文本见 [LICENSE](LICENSE) 文件（AGPL-3.0）。