dsh-browser-ops

Readme

# dsh-browser-ops

**Browser Ops for DeepSeek Harness** — 让 DSH 的 agent 直接操作真实浏览器、录制手动操作流程并按参数自动重放造测试数据。

English: a [DeepSeek Harness](https://github.com/deepseek-ai/deepseek-harness) plugin that drives a **real browser** (managed Chrome with an isolated persistent profile, or your daily Chrome over CDP), lets the agent snapshot/read/click/fill/query pages, records your manual operations into reusable **flows with variable slots**, and replays them to create test data on demand. Ships 27 `browser_*` tools + a Settings panel.

> 非官方插件，非 DSH 官方出品；按 MIT 许可使用。

---

## ✨ Features

- **Agent 直接操作浏览器**：`browser_launch / browser_open / browser_snapshot / browser_click / browser_fill / browser_select / browser_read_text / browser_read_table / browser_eval / browser_screenshot / browser_diagnostics …` —— 让它"打开系统查订单、填表提交、排查页面 console/网络报错"都行。
- **录制操作流程**：`browser_record_start` 后你在浏览器窗口手动点一遍 → `browser_record_stop` 保存为 JSON 流程（存于数据目录 `flows/`）。
- **变量槽 + 自动重放造数据**：用 `browser_flow_edit`（或设置页面板）把输入步骤标为变量 → `browser_run_flow` 填参数重放并校验（可带 `verifyText`，如校验"创建成功"）。
- **Web GUI 面板**：DSH 设置 →「浏览器操作」页签：启动/连接浏览器、●录制/■停止、流程列表、变量编辑、参数一键重放。
- **两种浏览器模式**：

| 模式 | 说明 | 适用 |
|---|---|---|
| `managed`（默认） | 插件启动**独立 Chrome**（专用档案目录，登录态持久，不触碰日常浏览器数据） | 造测试数据；**推荐** |
| `connect` | 附加**你日常在用的 Chrome**（先跑 `scripts/connect-chrome-mac.command` 带调试端口重启，再 `browser_launch {mode:'connect'}`） | 必须用日常会话/登录态时 |

## 🚀 Install

需要 DSH Desktop / DeepSeek Harness（node ≥ 20）。

```bash
# 方式一：npm（推荐）
dsh plugin --profile dsh-desktop add dsh-browser-ops

# 方式二：GitHub
dsh plugin --profile dsh-desktop add git+https://github.com/<you>/dsh-browser-ops.git

# 方式三：本地开发（link 到源码目录，改动重启即生效）
dsh plugin --profile dsh-desktop add link:/path/to/dsh-browser-ops
```

装完**重启 DSH Desktop**，新会话即可使用 `browser_*` 工具；或打开 **设置 → 浏览器操作** 查看面板。

## 🧭 Typical usage

```
启动浏览器，打开测试系统 https://test.example.com（需要登录就先在弹窗里登录一次）。
开始录制流程"创建订单"：browser_record_start → [你手动操作] → browser_record_stop
把第 3 步(客户名称)设为变量：browser_flow_edit
执行 browser_run_flow《创建订单》，params {"客户名称":"张三"}，verifyText "创建成功"。
```

## ⚙️ Configuration

| 环境变量 | 作用 |
|---|---|
| `DSH_BROWSER_OPS_DATA` | 数据根目录（浏览器档案 / flows / 截图）。默认 `~/.dsh/data/browser-ops` |
| `DSH_BROWSER_CHROME` | 指定 Chrome/Edge/Chromium 可执行文件路径（默认自动探测 macOS 常见路径） |

## 📁 Data layout

```
~/.dsh/data/browser-ops/
├── chrome-profiles/managed   # managed 模式浏览器档案（登录态持久）
├── flows/                    # 录制的流程 JSON + index.json
└── screenshots/              # browser_screenshot 输出
```

## 🧪 Development

```bash
# 端到端冒烟（真实 Chrome：录制→变量→重放→校验），无需 DSH：
ELECTRON_RUN_AS_NODE=1 "<DSH Desktop>" smoke/smoke.mjs
# 重新构建 Web 客户端面板（需要 esbuild，见 scripts/build-client.mjs 说明）
ELECTRON_RUN_AS_NODE=1 "<DSH Desktop>" scripts/build-client.mjs
```

目录：`lib/core/*` 为框架无关引擎（bridge/record/replay/locator/snapshot…），`lib/tools.js` 注册 `browser_*`，`lib/http.js` 提供面板 JSON 接口，`lib/client-src/` 是面板源码。

## 📝 Known limitations (v1)

- 录制覆盖：点击、文本输入（合并）、原生下拉、checkbox/radio、回车、SPA/整页跳转等待。**不含**文件上传、拖拽、iframe 内、跨标签序列。
- 定位"语义优先"（label/placeholder/text/testid/id → 兜底结构路径）；页面结构大变时建议重新录制。
- `connect` 模式当前仅提供 macOS 一键脚本；managed 模式的 Chrome 自动探测以 macOS 为主，其他平台可用 `DSH_BROWSER_CHROME` 指定。
- 无官方"UP主/作者"类排行等三方数据接口——纯浏览器自动化，数据来自你打开的真实页面。

## 📄 License

MIT © 2026 lirui