<!-- Source: https://deepseek-browser-use.io.nexus/33 -->

# DeepSeek Harness 原生浏览器插件：安装、配置与使用

首次开发 Harness 插件，建议先读 [插件开发入门](<https://deepseek-browser-use.io.nexus/29>) → [基础功能](<https://deepseek-browser-use.io.nexus/30>) → [核心功能](<https://deepseek-browser-use.io.nexus/31>) → [构建与安装](<https://deepseek-browser-use.io.nexus/32>)，再用本篇查配置与日常用法。

本章使用 `@litongjava/dsh-plugin-deepseek-browser-use`，让 DeepSeek Harness 直接调用结构化浏览器工具。插件位于 `deepseek-browser-use/plugins/deepseek-browser-use`。浏览器能力仍由现有 Java HTTP 服务提供，插件在 Harness 后端进程中用 TypeScript 发送请求，不启动 Python 或 `dsb` 子进程；只有开启后端自动管理时，才会派生 `powershell.exe` 执行随包脚本（见 [35](<https://deepseek-browser-use.io.nexus/35>)）。

## 1. 运行结构

```text
用户任务
  → Harness 模型选择 dsb_* 工具
  → 插件校验参数、绑定会话、排队
  → POST /playwright/command
  → Java 服务操作真实浏览器
  → JSON 页面状态 / 执行结果 / 图片附件
  → 模型观察结果并决定下一步
```

这里的“原生”指工具直接注册到 Harness 的 ToolRuntime。模型可以看到工具名、参数类型和说明；PTC 模式也能通过 `tools.dsb_*` 调用。现有 CLI 和 Python 客户端仍可独立使用。

第一版以独立命名空间注册工具，没有占用 Harness 的独占 `browserUse` provider 槽。已安装的 Playwright MCP 等工具不被替换。任务中指定使用 `dsb_*`，避免混用不同浏览器后端和页面索引。

## 2. 环境与版本

| 组件 | 要求 |
| --- | --- |
| 插件运行环境 | Node.js >= 22.19 |
| Harness 适配基线 | `0.2.0-rc.2` |
| Cordis 验证版本 | `4.0.4` |
| Java 浏览器服务 | 见 [安装、启动与健康检查](<https://deepseek-browser-use.io.nexus/02>) |
| 默认服务地址 | `http://127.0.0.1:10049` |

Harness 的开发预览 API 会变化，因此插件将 Harness peerDependencies 固定在已验证的版本。安装器会逐个校验 peerDependencies 中 `@deepseek-ai/dsh` 与 `@deepseek-ai/dsh-*` 的范围是否满足宿主运行时版本，不满足会直接以 `incompatible-version` 拒绝安装。遇到依赖不匹配时应适配和重新验证，不能只删除版本限制并认为兼容。

服务地址由 **Harness 后端主机** 发起访问。浏览器 Web UI 在另一台电脑上打开时，其 localhost 与 Harness 主机的 localhost 不是同一地址。0.2.0 已增加 Windows 后端自动安装、更新、编译和启动，详见 [后端自动管理](<https://deepseek-browser-use.io.nexus/35>)。

## 3. 构建可安装包

在 PowerShell 中执行：

```powershell
cd deepseek-browser-use\plugins\deepseek-browser-use
npm ci --ignore-scripts --legacy-peer-deps
npm test
npm pack
```

`npm test` 先编译 TypeScript，再运行 Node 测试。`npm pack` 的 `prepack` 会重新构建，压缩包包括 `dist/`、本地化信息、README、`cordis.patch.yml` 和 `scripts/backend.ps1`（后端自动管理必需），可通过 `npm pack --dry-run` 检查清单。

开发目录使用 `--legacy-peer-deps` 是为了只安装独立测试需要的依赖；完整 Harness 自己提供宿主服务。不要用该选项掩盖宿主版本不兼容。

## 4. 在 Harness 安装

0.2.0 默认 bundle 开启本机后端自动启动，已有健康服务会直接复用。使用远程或手工管理的服务时，先设置 `backendAutoStart:false` 并自行启动服务。

在目标 Harness 的 GUI 侧边栏 **Plugins（插件）** 页点 Install 并填入该目录，或在目标 Harness 会话中请智能体使用自身的 `plugin_manager`，参数为：

```json
{
  "action": "install_bundle",
  "target": "deepseek-browser-use/plugins/deepseek-browser-use"
}
```

这是一条 **Harness 工具调用**，不是 PowerShell 命令。此目录必须是 Harness 主机上的**绝对路径**（上面为通用起见省略了本机盘符前缀），且已完成构建。

会话内安装需要两个前提：智能体处于 **Creator mode**（才会拿到 `plugin_manager` 工具），权限为 **Full access**（`danger-full-access`，审批策略为 `never`）。截图与逐层回读方法见 [构建并安装到 DeepSeek Harness](<https://deepseek-browser-use.io.nexus/32>)。

安装器读取 `package.json` 中的 `dsh.bundle.patch`，应用下列默认配置：

```yaml
- insert:
    - id: litongjava-browser-use
      name: '@litongjava/dsh-plugin-deepseek-browser-use'
      config:
        baseUrl: http://127.0.0.1:10049
        browser: chrome
        headless: false
        timeoutMs: 60000
        maxTextChars: 24000
        maxResponseBytes: 16777216
        backendAutoStart: true
        backendAutoUpdate: true
        backendInstallDependencies: true
        backendRepository: gitee
```

回读插件管理器的安装与激活结果，然后调用 `dsb_health`、`dsb_start` 和 `dsb_state`。保存 bundle 配置不等于运行时已经激活。如果返回 `restart-required`，按提示重启目标 Harness；替换已安装包的 JavaScript 代码时尤其需要注意。

插件没有 npm install 生命周期脚本。依赖检查、源码构建和启动由激活后的后台操作完成，用 `dsb_backend` 的 `status` 查看进度；已有服务不会因为插件加载而重启。浏览器本身仍需按服务文档准备。

## 5. 配置项

| 字段 | 默认值 | 作用 |
| --- | --- | --- |
| `baseUrl` | `http://127.0.0.1:10049` | 服务根地址；允许代理路径前缀，不允许 URL 内嵌账号密码、查询串或 fragment。使用路径前缀、HTTPS 或远程主机时必须同时设 `backendAutoStart:false`，否则托管校验会在激活时报错 |
| `browser` | `chrome` | `auto`、`chrome`、`chromium`、`edge`、`firefox` |
| `headless` | `false` | 有头模式便于人工扫码和处理验证码 |
| `timeoutMs` | `60000` | 单次 HTTP 请求超时，毫秒 |
| `maxTextChars` | `24000` | 普通文本展示上限，规范 JSON 返回值不被截断 |
| `maxResponseBytes` | `16777216` | 单次响应体最多 16 MiB |
| `maxUploadBytes` | `8388608` | Harness 主机文件最多 8 MiB，base64 编码后传输体积会增加 |

后端管理另有 `backendAutoStart`、`backendAutoUpdate`、`backendInstallDependencies`、`backendRepoDir`、`backendRepository`、`backendStartupTimeoutMs` 六项，默认值与详细行为见 [35](<https://deepseek-browser-use.io.nexus/35>)。

首次安装前可编辑插件的 patch。安装后通过 Harness 的配置入口或用户覆盖层修改；Loader 替换配置对象时，应保留仍需要的字段。

需要不同登录账号互不干扰时，应启动不同浏览器服务并使用不同 profile。托管模式的 profile 固定在 `<backendRepoDir>/.dsb-backend/profile`，与端口无关，只改端口会共用同一份 profile，要隔离必须使用不同的 `backendRepoDir`。任务 ID 和页签归属不隔离共享 profile 的 Cookie。

## 6. 工具与调用示例

| 工具 | 主要参数 | 用途 |
| --- | --- | --- |
| `dsb_health` | 无 | 检查 HTTP 服务，不创建浏览器任务 |
| `dsb_backend` | `action` | 后端部署、状态、更新与空闲重启 |
| `dsb_methods` | `filter?` | 列出插件已适配的通用任务命令 |
| `dsb_start` / `dsb_close` | 无 | 创建/复用、关闭当前会话任务 |
| `dsb_navigate` | `url` | 打开网页，自动按需启动任务 |
| `dsb_state` | `viewportExpansion?`、`maxElements?`、`includeElements?`、`includeFrames?` | 读取页面文本和状态 |
| `dsb_click` | `index` 或 `selector`，以及可选 `mode` | 点击目标 |
| `dsb_input` | `index` 或 `selector`、`text`、`mode?` | 填写目标 |
| `dsb_evaluate` | `body`、`frame?` | 执行页面脚本 |
| `dsb_command` | `method`、`params?` | 使用通用任务命令 |
| `dsb_batch` | `commands`、`stopOnError?` | 提交顺序执行的异步批次 |
| `dsb_job` | `jobId`、`cancel?` | 查询或取消本会话批次 |
| `dsb_upload` | `localPath`、`index` 或 `selector` | 上传本机文件到页面 input |
| `dsb_screenshot` | `fullPage?`、`selector?`、`view?` | 返回截图地址或图片附件 |

选择器定位额外支持 `frame` 与 `nth`，其中 `nth` 从 0 开始。使用索引时不传 frame/nth，因为服务端已经记录索引所属 frame。`dsb_click` 还支持单次 `timeoutMs`。

给模型的提示词可以直接写：

```text
使用 dsb_ 开头的原生浏览器工具完成任务。
先用 dsb_state 读取页面，页面变化后重新取索引。
点击提交后回读结果，不要在超时后直接重复提交。
任务：打开 https://example.com，返回页面标题和正文。
```

PTC 示例：

```javascript
await tools.dsb_navigate({ url: "https://example.com" });
const state = await tools.dsb_state({});
console.log(state);
```

普通页面数据优先读取 DOM 文本。需要 JS 时，脚本放在 `body`，例如：

```json
{
  "body": "return document.title;"
}
```

通用命令名与 Java 命令表一致。例如 `dsb_command`：

```json
{
  "method": "get_element_text",
  "params": { "selector": "h1" }
}
```

参数含义见 [命令清单](<https://deepseek-browser-use.io.nexus/13>) 和后续源码章节。`dsb_methods` 返回本插件的显式适配集合，不是在线获取的完整服务能力；新服务新增命令需要同步插件命令快照。

## 7. 批次与文件

`dsb_batch` 的模型参数使用 `method/params`：

```json
{
  "commands": [
    { "method": "get_title" },
    { "method": "get_url" }
  ],
  "stopOnError": true
}
```

插件转换为服务端单键命令格式，设置 `async:true`，返回 `jobId`。用 `dsb_job` 反复查询，读到 `done/failed/cancelled` 后才允许下一项普通操作。不要把依赖页面变化后索引的点击盲目放进同一批次。

查询接口外层 `ok:true` 只表示成功查到作业；作业执行结果还要看 `data.status`、`data.ok` 和内部结果。失败的部分结果不会被插件吞掉。

文件上传：

```json
{
  "localPath": "D:/work/report.pdf",
  "selector": "input[type=file]"
}
```

`localPath` 指向 Harness 后端机器。插件读取文件，将 `filename/contentBase64` 发给服务；因此远程浏览器服务不需要访问 Harness 主机的磁盘路径。大量或超限文件可继续使用现有上传客户端，第一版原生工具没有实现流式大文件上传。

## 8. 截图、错误和恢复

默认 `dsb_screenshot` 仅返回落盘路径/相对 URL；它不会将图片像素交给模型。`view:true` 会先验证当前模型支持 image，再把截图存入 Harness 附件服务，返回持久图片引用。没有附件服务、模型路由无法验证或模型不支持图片时，会明确失败，可改用默认截图或 DOM 文本。

服务业务错误原样保留 `ok:false`。网络错误、参数错误和会话错误由 Harness 标为工具错误。HTTP 超时、取消或断开不能证明页面操作没有发生；插件不会自动重发命令。

异步提交的响应丢失时可能已经开始执行，却拿不到 `jobId`。插件冻结这个会话的后续浏览器操作，并在错误中报告 task ID。管理员在服务端用 `list_jobs` 找 `browserId` 对应作业，查询或取消后等待结束，再关闭该任务。之后新建 Harness 会话；不要重放原批次。

第一版不暴露 `shutdown`、全局清理、跨会话作业操作、嵌套批次和配方运行。Java 服务、Cookie 与页面脚本仍属于可信本地自动化能力，插件没有新增多租户认证隔离。

调用由 Harness 记录，服务端 trace 继续生效。插件不会额外生成 Python 客户端的 `logs/agent` 留档，也没有复刻其脱敏逻辑；需要脱敏时使用宿主和服务端部署策略。

下一篇：[原生插件源码、生命周期与测试](<https://deepseek-browser-use.io.nexus/34>)。