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

首次开发 Harness 插件，建议先读 插件开发入门 → 基础功能 → 核心功能 → 构建与安装，再用本篇查配置与日常用法。

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

1. 运行结构

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

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

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

2. 环境与版本

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

服务地址由 Harness 后端主机 发起访问。浏览器 Web UI 在另一台电脑上打开时，其 localhost 与 Harness 主机的 localhost 不是同一地址。0.2.0 已增加 Windows 后端自动安装、更新、编译和启动，详见 后端自动管理。

3. 构建可安装包

在 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，参数为：

{
  "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。

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

- 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. 配置项

后端管理另有 backendAutoStart、backendAutoUpdate、backendInstallDependencies、backendRepoDir、backendRepository、backendStartupTimeoutMs 六项，默认值与详细行为见 35。

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

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

6. 工具与调用示例

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

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

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

PTC 示例：

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

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

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

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

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

参数含义见 命令清单 和后续源码章节。dsb_methods 返回本插件的显式适配集合，不是在线获取的完整服务能力；新服务新增命令需要同步插件命令快照。

7. 批次与文件

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

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

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

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

文件上传：

{
  "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 留档，也没有复刻其脱敏逻辑；需要脱敏时使用宿主和服务端部署策略。

下一篇：原生插件源码、生命周期与测试。