kyo615/dsh-browser-control

dsh-browser-control

让 DeepSeek Harness 里的 AI 像 Codex 一样操控一个真实、可见的 Chrome 浏览器，并在对话 GUI 里实时看到每一步操作（自动截图 + 可点击元素的数字编号）。

底层基于微软官方开源项目 microsoft/playwright-mcp，通过 MCP（Model Context Protocol）stdio 连接。

本项目是 DeepSeek Harness 的动态 Cordis 插件（Host + Client 两部分）。它只调用 DSH / Cordis 的公开插件 API，不包含、不修改它们的源码。

✨ 特性

- 真实有头 Chrome：不是无头浏览器，你桌面上直接看到 AI 在操作（鼠标移动、输入、点击）
- 约 80 个 browser_ 工具注册给 AI：browser_navigate / browser_click / browser_type / browser_snapshot / browser_press_key / browser_mouse_click_xy / browser_tabs / browser_evaluate 等
- GUI 内嵌实时画面：每次 AI 动作后自动截图（live.png），经宿主 HTTP 路由 /dsh-browser/shot.png 实时刷新到对话面板，数字方框 = AI 可点击的元素编号
- 面板操作：网址栏跳转、刷新画面、重启浏览器、关闭浏览器
- 零硬编码路径：所有路径自动探测或可配置，clone 下来即可用

🏗 架构

┌──────────────────── DeepSeek Harness 进程 ────────────────────┐
│  Host（code.host）                                            │
│  ├─ 拉起 @playwright/mcp 子进程（真实有头 Chrome）             │
│  ├─ 最小 MCP stdio 客户端（换行分隔 JSON-RPC，手写实现）        │
│  ├─ 把 ~80 个 browser_ 工具注册为动态工具（harness.registerTool）│
│  └─ HTTP 路由 /dsh-browser/shot.png 提供实时截图               │
└──────┬─────────────────────────────┬──────────────────────────┘
│ MCP stdio（stdin/stdout）    │ HTTP（GUI 同源）
▼                             ▼
┌──────────────────┐        ┌──────────────────┐
│ @playwright/mcp  │        │ Client（code.client）│
│ （node 子进程）    │        │ 实时画面面板（轮询 rev）│
│   └─ 真实 Chrome │        └──────────────────┘
└──────────────────┘

📦 依赖与前提

- DeepSeek Harness（或兼容其动态 Cordis 插件机制的环境）
- Node.js ≥ 18
- 系统已安装 Google Chrome（或 Edge）
- 依赖包（在你打算放置 node_modules 的工作区里执行）：

npm install @playwright/mcp

🧩 方式一：作为正式插件安装（dsh plugin add）

本项目声明了标准的 dsh.bundle manifest（cordis.patch.yml + package.json 的 dsh 字段），可通过 DSH 的插件安装命令直接安装：

dsh plugin add
例如：
dsh plugin add https://github.com/kyo615/dsh-browser-control

安装后插件以 browser-control 作为实例 id 插入 Cordis 组合树，host 半加载 lib/index.js、client 半加载 lib/client.js。

前提同样需要：在对应工作区 npm install @playwright/mcp，且系统装有 Chrome。

🚀 方式二：动态插件（cordis_define / cordis_run）

动态插件是进程级的：DSH 重启后需重新定义与运行（依赖已在磁盘，无需重装）。

1. 在 DSH 对话中让 AI 执行（或手动调用）：
- cordis_define：
- plugin.kind: 'new'，idPrefix 例如 brws
- code.host = 本仓库 src/host.js 的完整内容
- code.client = 本仓库 src/client.js 的完整内容
- cordis_run(pluginId, packageId, 'run')
2. 在弹出的运行卡片上批准（Client 部分需要授权）。
3. Chrome 自动启动并打开起始页；对话中那张运行卡片变成实时画面面板。

⚙️ 配置

所有配置均有自动探测的默认值，无需手动配置即可运行：

| 配置项 | 默认值（自动探测顺序） | 说明 |
|--------|------------------------|------|
| workspace | 插件 config.workspace → 当前会话工作区（sandboxPolicy.workspaceRoot）→ 空 | 存放 node_modules/@playwright/mcp 的工作区 |
| cli | config.cli → /node_modules/@playwright/mcp/cli.js → 相对当前目录 → PATH 里的 playwright-mcp | MCP 服务入口 |
| startUrl | https://www.bing.com | 启动后自动打开的页面 |
| shotPath | .playwright-mcp/live.png | 实时截图文件（相对 workspace） |
| viewport | 1280x800 | 浏览器视口 |

代码按上述顺序解析，不硬编码任何本机路径。若运行时的插件配置支持 config 注入（apply(ctx, config) 的第二参），可用 workspace / cli / startUrl / shotPath / viewport 覆盖。

🎮 使用

- 直接对 AI 说："打开某网站 / 搜索某某 / 帮我操作网页"
- 或在面板的网址输入框输入网址跳转
- AI "看到"的是无障碍快照（带 [ref] 编号）；面板截图上的数字方框与之对应
- AI 可用 browser_status（带 start: true）在浏览器未运行时自行拉起来

📁 目录结构

dsh-browser-control/
├── LICENSE                 # MIT
├── THIRD_PARTY_NOTICES     # 第三方依赖声明（Apache-2.0 / MIT）
├── .gitignore              # 排除 node_modules / .playwright-mcp
├── cordis.patch.yml        # dsh.bundle manifest：dsh plugin add 安装入口
├── package.json            # 依赖声明 + dsh.bundle 字段（正式插件规范）
├── README.md               # 本文件
├── lib/
│   ├── index.js            # 宿主端入口（标准 Cordis 插件模块）
│   └── client.js           # 客户端入口（标准 Cordis 插件模块）
└── src/
├── host.js             # 宿主端源码（cordis_define 的 code.host 用）
└── client.js           # 客户端源码（cordis_define 的 code.client 用）

🤝 致谢 / 第三方

- microsoft/playwright-mcp · Apache-2.0 · © Microsoft
- Playwright · Apache-2.0 · © Microsoft
- DeepSeek Harness · MIT · © 2026 DeepSeek
- Cordis · MIT · © 2021-present Shigma

详见 THIRD_PARTY_NOTICES。

📄 许可证

MIT © 2026 kyo615

⚠️ 本插件允许 AI 操控浏览器执行真实操作，请自行负责使用场景的合规性（如网站条款、登录态、自动化访问限制等）。