# DeepSeek Browser Use

> 面向 AI 智能体的有状态浏览器服务：HTTP API、dsb 命令行、人机协作、站点技能与 DeepSeek Harness 插件

## 检索入口

- [机器可读目录](https://deepseek-browser-use.io.nexus/ai/index.json): 页面标题、章节、摘要、原文地址、内容哈希和占位状态。
- [分段语料](https://deepseek-browser-use.io.nexus/ai/chunks.jsonl): 每行一个 JSON 对象，按正文标题分段，保留代码块。
- [完整正文](https://deepseek-browser-use.io.nexus/llms-full.txt): 所有页面原文。优先按章节或单页获取。
- [站点地图](https://deepseek-browser-use.io.nexus/sitemap.xml): HTML 页面入口。

回答时引用 url 字段；结合版本与验证范围，placeholder 表示短内容候选，不应当作完整实现。

## overview

- [本章完整正文](https://deepseek-browser-use.io.nexus/ai/chapters/overview.txt)
- [deepseek-browser-use：概念与学习路线](https://deepseek-browser-use.io.nexus/ai/pages/01.md): deepseek-browser-use 是供智能体调用的浏览器服务。它用真实浏览器加载网页，通过 HTTP 接收命令，返回页面文本、元素索引、截图和动作结果。DeepSeek 或其他模型负责理解目标与选择动作；服务负责执行，模型调用并不内置在每条浏览器命令里。 项目源码： GitHub 、 Gitee 。 先理解四个
- [安装、启动与健康检查](https://deepseek-browser-use.io.nexus/ai/pages/02.md): 本章目标是让 deepseek-browser-use 服务正常响应健康检查。浏览器任务在下一章创建。 环境准备 当前源码需要 Java 21 或以上环境。源码运行还需要 Maven；使用 dsb 客户端不需要 Python 或其他运行时 —— 它是一个静态二进制（源码在仓库 dsb/ ， go build 一下即可，
- [客户端：dsb 命令行与结构化留档](https://deepseek-browser-use.io.nexus/ai/pages/03_client.md): dsb 是 Go 实现的命令行客户端，负责参数解析、HTTP 调用、退出码和 UTF-8 留档。浏览器操作由服务端执行。安装、多目标和后端管理见 客户端安装与管理 ，可靠采集见 上下文与证据 。本章提供当前可执行入口，不依赖已经移除的 Python 客户端。 1. 常用命令 1001 为数字示例 ID，使用前确认没有被
- [第一个任务：打开页面、读取结果与关闭](https://deepseek-browser-use.io.nexus/ai/pages/03.md): 本章使用项目自带 dsb 客户端完成一个只读任务。先按 上一章 启动服务，再在仓库根目录运行命令。 1. 创建任务 1001 是教学 ID，执行前应确认没有同名任务。实际项目可省略 ID，由服务生成；读取返回的 data.id ，后续请求始终使用这个值。Java 侧需要生成业务 ID 时使用 nexus.io.tio.
- [统一命令接口与人机协作](https://deepseek-browser-use.io.nexus/ai/pages/04.md): 本章介绍 deepseek-browser-use 的统一接口。完成 第一个任务 后，再了解请求、响应和错误处理。所有浏览器控制命令使用 POST /playwright/command ；执行过程见 公共执行链 。 项目源码： deepseek-browser-use 。智能体使用说明位于 .agents/skill
- [浏览器、profile 与登录态](https://deepseek-browser-use.io.nexus/ai/pages/05.md): 本文说明当前工程「用哪个浏览器、用哪份 profile、登录态存在哪」，以及换浏览器带来的实际后果。前文 04 讲的是请求与响应的形状，本文讲的是浏览器本身。 toc 一、一个浏览器，多个任务 浏览器是 全进程共享 的：一个浏览器进程、一份 profile，任务之间靠 页签 隔离。 | 行为 | 说明 | | --- 
- [窗口尺寸与页面视口](https://deepseek-browser-use.io.nexus/ai/pages/06.md): 本文说明浏览器窗口开多大、页面按多大排版、截出来的图是什么尺寸。「窗口尺寸」和「页面视口」在早期实现里是同一个值，现在分开管理 —— 混在一起会得到一个页面比窗口还大的怪状态。 toc 一、两件事必须分开看 | | 由什么决定 | 默认行为 | | --- | --- | --- | | 窗口尺寸 | 屏幕的可用工作区
- [接入智能体：观察、执行与验证](https://deepseek-browser-use.io.nexus/ai/pages/07.md): 掌握手动调用后，再让模型选择动作。deepseek-browser-use 不要求特定模型，只要上层智能体能够发送 HTTP 请求并读取回执，就可以接入。 服务与智能体各自负责什么 | 组件 | 职责 | | --- | --- | | 模型 | 理解用户目标，读取页面信息，提出下一步动作 | | 调用程序 | 校验动
- [表单与多层弹窗排障：防止重复提交](https://deepseek-browser-use.io.nexus/ai/pages/08.md): 本文对应浏览器工程的当前源码，说明表单定位、点击降级、对象释放异常和人工验证的处理方式。升级源码后需要重新构建并重启服务；旧进程不会自动获得这些行为。 支付产品申请等业务可参考 支付宝接入指南 。本章只讲浏览器操作，不重复支付接口实现。示例中的任务 ID、企业名称和域名均为占位信息。 1. 可见不等于能收到点击 背景表
- [调用追踪、页面留档与文件上传](https://deepseek-browser-use.io.nexus/ai/pages/09.md): 本文说明服务在自己的工作目录里留下了什么、放在哪、以及客户端-服务器模式下怎么把文件送到服务端。这些产物是排障与事后复盘的唯一凭据，同时也是需要定期清理的磁盘占用。 toc 一、每一次调用都有留档 每一次调用（含批量里的每一步）的请求与响应都会落到 /logs/trace/ / 下，例如 logs/trace/2026
- [站点配方、技能与异步作业](https://deepseek-browser-use.io.nexus/ai/pages/10.md): 本文讲三件与「让智能体少踩坑」有关的事：把站点经验固化成可执行序列的 配方 、给人读也给智能体读的 技能文档 ，以及长批次用的 异步作业 。 toc 一、站点配方（recipes） 把「某个站点上必须这么点」的经验固化成服务端的 JSON 命令序列。每个配方一个 .json 文件， 文件名（不含扩展名）就是配方名 。 
- [Windows OCR：本地图片与页面文字识别](https://deepseek-browser-use.io.nexus/ai/pages/11.md): ocr image 识别图片上的文字。默认走后端 Windows 的 Windows.Media.Ocr ， 也可以配置成调用一条外部文档 OCR 命令 （见第 6 节）。它适用于扫描件、公告图片和页面中没有 DOM 文本的区域。它不是二维码解码器，也不等于文档结构化提取；图片中的表格、印章、手写字和模糊字符需要另外核
- [配置项与运维自省](https://deepseek-browser-use.io.nexus/ai/pages/12.md): 本文列出当前工程的全部运行时配置项与只读查询端点，用于部署、排障和「现在到底是哪个配置在生效」这类问题。 toc 一、配置从哪里读 配置项统一通过 EnvUtils.get 读取， 优先级从高到低 ： 1. EnvUtils 通道（系统属性、环境变量、 app.properties 等，具体来源以框架的加载顺序为准）；
- [命令清单](https://deepseek-browser-use.io.nexus/ai/pages/13.md): 本文按功能分组列出当前工程的 注册方法 ，用于快速定位「这件事该用哪个方法」。这是方法名与用途索引，不是每条命令的完整参数手册。参数以源码 CommandTable 的注册及服务实现为准，使用说明位于 .agents/skills/deepseek-browser-use/SKILL.md 及其 references/
- [源码教程：从 HTTP 请求到命令执行](https://deepseek-browser-use.io.nexus/ai/pages/14.md): 本系列以当前 deepseek-browser-use 工程为准，按功能解释全部 122 个注册命令，以及额外的 commands 批量入口。先阅读本章理解公共执行链，再按章节进入具体实现。文中的源码路径均相对于浏览器项目根目录；示例中的 ID、域名及资料均为占位信息。 1. 建立源码地图 | 文件或类 | 职责 | 
- [DOM 原理：前端如何生成可交互快照](https://deepseek-browser-use.io.nexus/ai/pages/15.md): 本章解释当前源码如何把网页 DOM 转成模型可读的结构化文本。先掌握 页面状态命令 ，再看实现。 源码入口 文件位于 playwright-server/src/main/resources/dom/dom tree/ ： | 文件 | 用途 | | --- | --- | | index.js | DOM 遍历、可见
- [DOM 原理：Java 模型与跨 Frame 索引](https://deepseek-browser-use.io.nexus/ai/pages/16.md): 前端脚本返回节点映射后，Java 负责恢复树形结构、生成可读文本，并保存索引与 Frame 的对应关系。 当前模型 源码位于 playwright-server/src/main/java/nexus/io/ai/browser/dom/model/ ： | 类型 | 职责 | | --- | --- | | DOMB
- [正文提取与上层结构化处理](https://deepseek-browser-use.io.nexus/ai/pages/17.md): 正文提取有两条命令，分工按 页面上有没有表格 来分： - extract structured data 读取页面正文纯文本，并可附带链接列表。命令名称中的 structured 不表示服务会自动调用大模型生成业务 JSON。 - extract markdown 把页面（或页面上某个元素）转成 Markdown， 表
- [源码教程：生命周期、导航与页签](https://deepseek-browser-use.io.nexus/ai/pages/18.md): 本章从 PlaywrightService.start 、 BrowserInstance 和页签操作方法入手。共享浏览器策略详见 浏览器与登录态 。 1. 启动不是每个任务都创建一个浏览器 start 先解析 browser、headless、profile 等配置，再复用或创建共享浏览器，将任务 ID 与 Brow
- [源码教程：DOM、页面状态与元素读取](https://deepseek-browser-use.io.nexus/ai/pages/19.md): 浏览器服务把 DOM 变为可供模型阅读的文本，同时保存索引与元素、frame 的对应关系。索引是一次快照的定位线索，不是网站自己的元素 ID。 highlight 默认 false，关闭绘制仍分配索引。每次读取前清除旧高亮及其监听器； screenshot 默认关闭，显式 true 才请求本次截图。CLI 分别为 st
- [源码教程：点击、输入、键盘与鼠标](https://deepseek-browser-use.io.nexus/ai/pages/20.md): 本章解释定位如何转为动作。核心辅助方法是 resolveIndex 、 resolveActionTarget 、 clickWithMode 和输入执行逻辑；遮挡与重复提交的排障步骤见 第 08 篇 。 1. 索引、CSS 与语义定位 | 命令 | 定位和执行方式 | | --- | --- | | click el
- [源码教程：等待条件与 JavaScript 执行](https://deepseek-browser-use.io.nexus/ai/pages/21.md): 异步页面不能只靠固定 sleep。等待命令分别判断元素、URL、网络、DOM 或数量条件；条件成立说明观测到了某种状态，不自动证明业务完成。 1. 原生等待与自定义等待 | 命令 | 实现思路与适用范围 | | --- | --- | | wait | 按 seconds 等待；没有业务条件，适合明确要求的短暂间隔 |
- [源码教程：文件上传、截图、PDF 与 OCR](https://deepseek-browser-use.io.nexus/ai/pages/22.md): 这一组命令连接浏览器对象与服务端文件系统。路径属于服务端，不能把客户端路径直接当成服务器可以打开的文件。文件传输协议见 第 12 篇 ，OCR 使用方式见 第 16 篇 。 1. upload file 的两个入口分支 注册层先检查 contentBase64 或 url：存在时调用 uploadFileInline 
- [源码教程：Cookie、存储与页面设置](https://deepseek-browser-use.io.nexus/ai/pages/23.md): 这一组命令最容易混淆作用域。任务的 Page 可以独立，但 BrowserContext 可能共享；修改上下文会影响多个任务。不能把所有 set 开头的命令都当作当前页设置。 1. Cookie 是 Context 级数据 | 命令 | 实现 | | --- | --- | | get cookies | 调用 con
- [源码教程：网络记录、请求拦截与控制台](https://deepseek-browser-use.io.nexus/ai/pages/24.md): 网络功能用于解释“点击后发生了什么”。核心状态位于 BrowserInstance ，通过页面事件监听记录请求、响应和失败，再由查询命令过滤和返回。 1. 从事件到请求记录 任务认领 Page 时安装监听器，为请求生成 requestId，保存 URL、方法、类型、时间及必要的正文摘要。响应和失败事件继续更新同一记录，
- [源码教程：原生对话框、DOM 弹窗与人机协作](https://deepseek-browser-use.io.nexus/ai/pages/25.md): 这三类能力的实现对象不同：原生对话框由浏览器事件提供，DOM 弹窗是普通网页节点，人工请求是服务端维护的协作状态。它们不能共用“找到一个确定按钮就点”的逻辑。 1. 原生对话框记录 页面出现 alert、confirm 或 prompt 时，监听器保存最近一次对话框信息并按配置处理。读取命令返回的是记录，不保证对话框现
- [源码教程：批量、配方、后台作业与维护](https://deepseek-browser-use.io.nexus/ai/pages/26.md): 这些能力不增加新的浏览器原语，而是组合和管理已有命令。重点是避免 HTTP 超时被误认为执行失败，以及区分“取消后续步骤”和“撤销已执行操作”。 1. commands 批量入口 commands 是 ActionService.execute 特殊处理的入口，不包含在 122 个注册方法之中。同步批次逐项解析单命令对
- [源码教程：Chrome 走 CDP 与 CDP 客户端](https://deepseek-browser-use.io.nexus/ai/pages/27.md): 本机 Google Chrome 一律通过 CDP（Chrome DevTools Protocol） 驱动：服务自己拉进程、开远程调试端口、用协议接上。为此工程里多了一个独立的协议客户端，包名 nexus.io.chromium.cdp ，它不依赖工程内其它包，可以整包拿走单独用。 前文 05 讲的是「用哪个浏览器、
- [请求响应关联与线程约束](https://deepseek-browser-use.io.nexus/ai/pages/28.md): 同一个 URL 可以连续或并发请求多次。 get requests 给出的每个 requestId 必须对应那次请求的状态和正文， get response body 与 wait for response 也必须沿用这个 ID。只比 URL 或选择最近一条未完成请求，无法证明响应归属。 精确关联与有序采集 服务按请求
- [DeepSeek Harness 插件开发入门：从入口到第一个工具](https://deepseek-browser-use.io.nexus/ai/pages/29.md): 如果你会写 Java 或 JavaScript，但还不知道 Harness 插件从哪里开始，本系列按四个步骤带你理解并修改 @litongjava/dsh-plugin-deepseek-browser-use ：建立插件入口、接入基础浏览器命令、处理会话和异步作业、安装到宿主。 本篇的目标是先看懂一个工具如何被 Ha
- [开发 dsh-plugin-deepseek-browser-use：HTTP 客户端与基础工具](https://deepseek-browser-use.io.nexus/ai/pages/30.md): 上一篇完成了工具注册和派发。这一篇接入 Java 浏览器服务，让模型能够导航、观察、点击和输入。代码取自插件 0.2.0；完整文件会明确标注，其余片段都在现有工程中阅读或修改，不需要逐块拼接。 1. 先定义调用链和最小验收任务 本篇要完成的任务是：打开一个页面，读取新的 DOM 状态，取得标题，最后关闭本会话的浏览器任
- [开发 dsh-plugin-deepseek-browser-use：会话、作业、文件与图片](https://deepseek-browser-use.io.nexus/ai/pages/31.md): 上一篇已经把工具请求送到了 Java 服务。真实使用还有几个问题：两个会话会不会操作同一个任务？同一会话同时发两个命令怎么办？HTTP 已返回，但异步批次还没结束怎么办？本篇结合插件 0.2.0 的实际实现，逐步补齐这些核心能力。 1. 为什么不能只保存一个全局 taskId 假设 A 会话打开订单页面，B 会话打开搜
- [把 dsh-plugin-deepseek-browser-use 构建并安装到 DeepSeek Harness](https://deepseek-browser-use.io.nexus/ai/pages/32.md): 前三篇已经说明插件入口、HTTP、工具和会话管理。这一篇把源码变成可安装的插件，并确认目标 Harness 真正用上了它。操作以当前插件 0.2.0、Harness 0.2.0-rc.2 为基线。 下面的命令是给读者在自己的开发机和目标 Harness 中执行的安装步骤；文档中的调用样例不表示你的宿主已经安装成功。 1
- [DeepSeek Harness 原生浏览器插件：安装、配置与使用](https://deepseek-browser-use.io.nexus/ai/pages/33.md): 首次开发 Harness 插件，建议先读 插件开发入门 → 基础功能 → 核心功能 → 构建与安装 ，再用本篇查配置与日常用法。 本章使用 @litongjava/dsh-plugin-deepseek-browser-use ，让 DeepSeek Harness 直接调用结构化浏览器工具。插件位于 deepseek
- [DeepSeek Harness 原生浏览器插件：源码、生命周期与测试](https://deepseek-browser-use.io.nexus/ai/pages/34.md): 插件源码目录是 deepseek-browser-use/plugins/deepseek-browser-use 。它保留 Java 服务现有协议，只在 Harness 和 HTTP 之间增加适配层。安装步骤见 上一章 。 1. 文件分工 2. 插件装载与工具注册 index.ts 导出 name 、 inject 
- [后端自动管理：安装 Java 与 Git、更新源码、编译和启动](https://deepseek-browser-use.io.nexus/ai/pages/35.md): 原生插件 0.2.0 增加 dsb backend 。启用后，Windows 用户不必先手工起 Java 服务：插件检查依赖、克隆源码、执行 Maven 构建，再以隐藏窗口方式启动长驻后端。浏览器动作仍直接走 HTTP。 1. 默认部署位置与来源 Windows 存在 D 盘时，默认源码目录为： 没有 D 盘时使用当前
- [页面正在导航与主 Frame 缺失：PAGE_NAVIGATING](https://deepseek-browser-use.io.nexus/ai/pages/36.md): 只读命令突然报 Cannot invoke "com.microsoft.playwright.Frame.childFrames()" because "frame" is null ，或者在构建快照时抛 Index 0 out of bounds for length 0 —— 这两种异常看起来毫不相干，实际是同一
- [dsb 客户端：Go 版本、多目标与后端服务管理](https://deepseek-browser-use.io.nexus/ai/pages/37.md): 03-1 介绍当前命令行参数、结构化输出与留档。本章介绍 Go 实现的单文件二进制 dsb 的安装、多目标与服务管理；源码在仓库 dsb/ 目录。 这一章讲三件事：为什么换、怎么装、以及新版本多出来的两块能力 —— 连别的主机/多个端口 与 自己管后端服务 。 1. 为什么换成 Go 原来的 Python 客户端只有一
- [可靠的数据采集：上下文校验、UTF-8 留档与证据口径](https://deepseek-browser-use.io.nexus/ai/pages/38.md): 浏览器自动化把可见页面、接口响应与调用留档连接起来。将动作执行、输出处理和业务结论分开记录，可以减少重复操作，并让分析结果可以追溯。本章只介绍通用采集能力，不包含具体应用的业务报告。 1. 使用明确的客户端入口 methods 是 CLI 子命令；协议方法使用 dsb run list methods 。任务 ID 使
- [浏览器 profile：列表、克隆与选择](https://deepseek-browser-use.io.nexus/ai/pages/39.md): 本文说明如何发现服务端的 Chrome profile、离线克隆为独立命名 profile，以及在启动时选择它。共享浏览器与登录态基础见 05 ，客户端安装见 37 。 toc 一、先分清目录与名称 - userDataDir ：用户数据根目录，里面通常有 Local State 和多个子 profile。 - pro
- [命令可靠性：诊断、业务断言与稳定定位](https://deepseek-browser-use.io.nexus/ai/pages/40.md): 超时和取消 | 参数 | 单位和范围 | 作用 | | --- | --- | --- | | 等待方法的 timeoutMs | 毫秒，大于 0、不超过 900000 | wait for 的目标条件等待时间 | | 等待方法的 timeoutSeconds | 秒，大于 0、不超过 900 | 兼容原有写法；同时传
- [deepseek-browser-use：从入门到源码](https://deepseek-browser-use.io.nexus/ai/pages/guide.md): 本章对应当前 deepseek-browser-use 工程，所有浏览器控制操作通过 POST /playwright/command 。新读者从 01 开始；已经接入的读者可直接查 13 的命令清单。文中源码路径相对于浏览器项目根目录。 第一阶段：从零运行一个任务 按顺序阅读，完成环境准备、第一次调用并理解统一协议。
- [DeepSeek Browser Use](https://deepseek-browser-use.io.nexus/ai/pages/index.md):