dsh-browser-use

Native Chromium browser Agent tools for DeepSeek Harness

WebVoyager 109 tasks / 3 站点：成功率 88.1%（AllRecipes 88.6%、Apple 85.7%、Amazon 89.7%），平均 26.7 步、167.3s、$0.0968/任务。完整的 LLM-as-a-Judge、Trace、成本口径和恢复流程见评测指南。

浏览器命令失败的处理、点击检查和脚本异常说明见可靠性文档；原文引用的获取方式见证据文档。

中文 | English

---

🇨🇳 dsh-browser-use（中文）

给 DeepSeek Harness 装上真实浏览器：让 Agent 能够打开网页、理解页面、填写表单、管理标签页并完成多步骤任务。

我们将 dsh-browser-plugin 作为可独立安装的 DeepSeek Harness（DSH） Web profile 插件。它直接启动本机 Chrome 或 Chromium，通过 Puppeteer、Chrome DevTools Protocol（CDP）和增量 DOM 快照向 Agent 提供 16 个浏览器操作与 4 个任务证据工具。

本仓库只包含浏览器插件自身的源码，不包含 DeepSeek Harness 源码，也不要求用户克隆 Harness 仓库。

本版本通过 DSH 的原生扩展点，把浏览器运行时与上下文策略接入 Agent Harness。这里的 Host 是 DSH 的 Agent/Session 运行时；插件仍可独立打包安装，不需要复制或修改 DSH 源码。

它能做什么

任务	没装插件	装上插件
访问动态网站	只能依赖搜索或静态抓取	启动真实 Chromium 并操作页面
填写复杂表单	无法处理弹窗、下拉框和动态字段	通过 DOM 引用定位、输入和点击
多步资料调研	每一步都要人工复制页面内容	Agent 可在多个标签页之间持续探索
理解页面变化	反复读取整页，浪费上下文	优先返回 DOM 差异，必要时建立完整基线
查看图表和图片	只有文本信息	截取指定视觉元素并保存为 DSH attachment

核心特性

• 真实 Chromium — 使用本机 Chrome/Chromium，而不是 HTTP 抓取器或模拟页面。
• 增量 DOM — 首次返回完整快照，后续优先返回 +| / -| 差异，减少重复上下文。
• 稳定元素引用 — 可点击元素使用 [N]，可输入元素使用 <N>，视觉元素使用 [view:ID]。
• Session 隔离 — 每个 DSH Agent 独立拥有浏览器进程、标签页、CDP 会话和 DOM 缓存。
• 多标签页与滚动探索 — 支持创建、切换、关闭标签页，以及按屏或按页面位置探索长页面。
• DSH 原生生命周期 — 使用 Cordis、defineTool、approval、取消信号和 attachment 服务，不依赖兼容服务器。
• 显式浏览器路由 — 用户明确要求使用浏览器或 Chromium 时，模型从 browser_start 开始并持续使用 browser_*，不会用 web_search 或 web_fetch 替代。
• 安全默认值 — Chromium sandbox 默认开启；改变页面状态的操作默认需要 DSH approval。
• 有界输出 — 页面脚本结果过大时只向模型返回预览，并把完整结果写入指定目录或临时目录。
• 证据化任务记录 — 我们按页面访问归档 observation，用 sourceRef 登记结构化字段，并在完成时重查声明的字段覆盖。
• 操作后置条件 — 点击和输入可检查文本或 URL；实际执行、验证通过和整体任务完成始终是三个独立结论。
• 精确检查点恢复 — 我们用完整 stateId 恢复支持的表单、展开状态与滚动位置，并将不完整恢复明确标为 partial。
• 结构化与跨域诊断 — browser_execute_script 支持 JSON-LD、重复列表和有界结果；OOPIF 路由、CDP 录制/回放与统计接口用于可复现的 DOM 诊断。

快速开始

环境要求

• Node.js >=22.19
• Chrome 或 Chromium
• pnpm（DSH 的插件安装命令会调用它）

node --version
pnpm --version

如果尚未安装 pnpm：

npm install --global pnpm

安装当前本地版本

该包目前尚未发布到 npm，以下步骤假定你已经通过当前私下交付渠道取得源码。先生成标准 npm tarball，再安装到 DSH 的 web profile：

Set-Location path\to\dsh-browser
npm install
$package = npm pack --silent

npx @deepseek-ai/dsh@0.1.2-alpha.2 plugin --profile web add ".\$package"
npx @deepseek-ai/dsh@0.1.2-alpha.2 --profile web --dump-config
npx @deepseek-ai/dsh@0.1.2-alpha.2 web

--dump-config 中应出现 id: dsh-browser 和 name: dsh-browser-plugin。

发布到 npm 后

npx @deepseek-ai/dsh@0.1.2-alpha.2 plugin --profile web add dsh-browser-plugin
npx @deepseek-ai/dsh@0.1.2-alpha.2 web

首次使用 npx 时可能会下载 npm 发布的 DSH CLI 及其依赖；插件安装会下载本插件及其依赖。两条路径都不会下载 DeepSeek Harness 源码 checkout。

快速配置（可选）

默认配置可以直接使用。在本地打包前，可以修改本仓库的 cordis.patch.yml。安装完成后，把下面的条目合并进 $DSH_HOME/profiles/web/cordis.patch.yml（DSH_HOME 默认是 ~/.dsh）已有的 YAML 列表；不要覆盖文件中的其他 profile 条目。该层会覆盖 bundle 默认值。

DSH 的 profile patch 会替换目标条目的整个 config，因此覆盖时要重述需要保留的字段：

- id: dsh-browser
  config:
    headless: true
    noSandbox: false
    approvalMode: mutating
    viewportWidth: 1280
    viewportHeight: 900
    toolTimeoutMs: 120000
    maxWaitSeconds: 300
    maxContextDeltas: 8
    scriptMaxLines: 100
    scriptMaxBytes: 8192

修改后重启 DSH，并用 npx @deepseek-ai/dsh@0.1.2-alpha.2 --profile web --dump-config 检查最终配置。

需求	配置项	默认值	常用改法
后台无界面运行	headless	false	改为 true
指定浏览器程序	chromePath	自动探测	填入 Chrome/Chromium 绝对路径
调整操作审批	approvalMode	mutating	off、mutating 或 always
调整浏览器窗口	viewportWidth / viewportHeight	1280 / 900	改为所需正整数
限制单次工具时长	toolTimeoutMs	120000	填写正整数毫秒数
限制等待时长	maxWaitSeconds	300	填写正整数秒数
限制 DOM 增量链长	maxContextDeltas	8	正整数；达到后生成完整检查点
限制脚本可见输出	scriptMaxLines / scriptMaxBytes	100 / 8192	改为所需正整数
保存完整脚本结果	outputDir	系统临时目录	填入目标目录绝对路径

只有受控容器确有兼容性需要时才应设置 noSandbox: true。

使用示例

安装后，直接在 DSH 中使用自然语言描述任务：

信息提取

打开 Hugging Face 热门模型页面，整理排名前三的模型名称、机构、参数规模和下载量，并给出来源页面。

表单填写

打开联系表单，填写我提供的字段，检查必填项和格式校验，但不要最终提交。

多步骤调研

调查一篇论文的官方代码仓库、依赖、最近维护状态和常见复现问题，最后判断复现难度。

涉及登录、购买、发布、删除或最终提交等高风险动作时，应明确限制任务边界并保留 approval。

增量 DOM 如何工作

普通浏览器 Agent 经常在每次操作后把整个页面重新发送给模型。这个插件会保留同一标签页的 DOM 快照链：

首次观察       → mode:full         完整 DOM
少量页面变化   → mode:incremental  新增 +| 与移除 -|
大量变化/检查点 → mode:full         建立新的完整基线
没有变化       → mode:nochange     简短状态提示

处理链路如下：

CDP Snapshot
  → DOM Tree
  → 可见性与可交互性检测
  → 剪枝、内联合并和视觉元素标记
  → 结构化文本渲染
  → 与上一快照计算差异
  → 返回给 Agent

browser_restore_state 优先回到仍有效的浏览器历史条目，失败时访问原 URL，再逐项恢复并验证受支持状态。它使用完整版本号（如 tab0-dom3.2）恢复检查点 URL、原生表单值、勾选/下拉选项、details 展开状态，以及主页面和局部容器的滚动位置。恢复后逐项核对；不完整时返回 partial。密码、文件选择、iframe、任意弹窗与 SPA 内存不在恢复范围内。

工具清单

工具	作用
browser_start	启动浏览器并打开 URL
browser_observe	不刷新页面，重新观察完整状态；支持 HTML 或 Markdown
browser_goto	导航当前标签页
browser_refresh	刷新当前页面
browser_restore_state	按精确 stateId 恢复可支持的页面状态，并报告未恢复项
browser_new_tab	新建标签页
browser_switch_tab	切换活动标签页
browser_close_tab	关闭一个或多个标签页
browser_click	点击 [N] 元素
browser_input	向 <N> 元素输入内容
browser_reveal_offscreen	展示已知的离屏元素
browser_scroll_next_screen	滚动到下一段未探索内容
browser_scroll_to_page	跳到指定页面位置
browser_execute_script	在页面上下文执行 JavaScript
browser_view_elements	截取 [view:ID] 视觉元素
browser_wait	可取消地等待指定秒数
browser_define_task	声明本轮任务字段与最低记录数
browser_record_facts	登记 sourceRef 任务记录；兼容旧事实格式
browser_check_coverage	检查字段覆盖；完成阶段自动重查
browser_recall	搜索当前/历史事实，或回读已归档的页面观察

架构

DSH Agent Session
  → Cordis 加载 dsh-browser-plugin
  → @deepseek-ai/dsh-tools defineTool
  → DSH approval / cancellation / timeout
  → browser operation
  → Session-scoped BrowserManager
  → Puppeteer + Chromium + CDP + DOM Service
  → canonical tool output / DSH attachments / observation metadata
  → agent/pre-step: browser context retention
  → Session surface → next model request

项目结构：

dsh-browser/
├─ src/
│  ├─ index.ts              # Cordis 插件入口与生命周期
│  ├─ plugin-tools.ts       # 浏览器注册器，配合记忆工具共 20 个
│  ├─ tool-schemas.ts       # 参数与输出 schema
│  ├─ config.ts             # 配置 schema 与校验
│  └─ browser/
│     ├─ manager.ts         # 浏览器与标签页生命周期
│     ├─ operations/        # 导航、交互、观察、滚动等操作
│     ├─ cdp/               # CDP 封装
│     └─ dom/               # DOM 构建、渲染、差异与视觉映射
├─ test/                    # node:test 测试
├─ scripts/                 # 真实浏览器和安装验证脚本
├─ cordis.patch.yml         # DSH bundle patch
└─ package.json             # npm 与 DSH bundle 清单

src/ 是源码事实来源，lib/ 是 npm run build 生成的发布产物，不要直接编辑 lib/。

上下文策略优先通过 Session.snapshotEvents() 读取当前宿主日志；对依赖锁定的 DSH 0.1.2-alpha.2 使用其 events getter。源码链接安装修改后需重新构建插件并重启 pnpm dsh web，使进程加载新的 lib/。

浏览器能力与诊断

我们对 20 个工具统一复用 approval、取消和输出限额，并保持以下能力边界：

能力	使用方式与边界
显式观察	browser_observe({format: "html"}) 不导航、不刷新，建立完整 DOM 基线；markdown 使用完整 AX 语义树并保留操作引用。
结构化数据	__data、__find、__records 和 __skeleton 帮助读取 JSON-LD、Microdata 和已加载的重复列表；页面数据仍需按任务要求验证。
跨域 iframe	CDP 请求路由到节点所属子会话，元素引用按 frame 隔离；主页成功不自动证明子框架可操作。
页面变化提醒	Host 在 URL 与最近观察不一致时要求重新观察；相同 URL 内的人工修改仍需显式观察。
离线回归	`npm run dom:regression -- capture

dsh-browser-plugin/diagnostics 导出 captureDomTape、replayDomTape、CDPTape 和 CDPStats。这些接口用于 DOM 文本、元素编号和管线性能诊断，不等同于线上任务成功率。

运行 WebVoyager 评测

在本仓库根目录打开 PowerShell，要求 Node.js >=22.19 和本机 Chrome/Chromium。脚本直接启动真实 DSH AgentLoop 和浏览器，无需先启动 DSH Web 界面。Agent 自动操作网页，独立的 LLM Judge 请求负责评分。

1. 安装依赖并构建

# 首次使用或依赖变化后安装
npm install
# 首次评测及修改源码后重新构建
npm run build

默认读取现有 DSH 配置（DSH_HOME 默认是 ~/.dsh）：从 settings.yaml 获取当前 Agent provider/model/reasoningEffort，通过环境变量或 .credentials.yaml 的凭据引用获取 API Key。MiniMax 默认沿用 DSH 的 Anthropic-compatible 路径；high 按当前 DSH 映射为 thinking.enabled 和 16384-token 思考预算，完整 thinking 块随工具调用历史回放。默认 Agent 和 Judge 共用模型、推理档位及凭据，也可用 EVAL_* 环境变量分别覆盖，密钥不会写入仓库。

2. 检查选题并可选试跑

# 只检查并列出选题，不启动浏览器、不调用模型 API
npm run eval -- --dry-run --reasoning-effort high --headed --timeout 600000 --judge evidence

# Allrecipes、Apple、Amazon 各一题，显示浏览器窗口方便观察
npm run eval -- --out output/evals/pilot-run1 --ids "Allrecipes--0,Apple--0,Amazon--0" --reasoning-effort high --concurrency 3 --headed --timeout 600000 --judge evidence

正式评测条件固定为 --headed --timeout 600000 --judge evidence：显示浏览器窗口、每题最多运行 600 秒，并使用浏览器文本证据评分。它们也是评测器的默认值，但命令中仍显式写出，便于复核 manifest 和复现实验。--reasoning-effort high 显式固定 Agent 和默认 Judge 的推理档位，并写入 manifest 和运行指纹。真实试跑和全量评测都会消耗 Agent、Judge 的 API 额度；npm run eval:smoke 则使用真实浏览器和确定性模型替身，不调用收费 API，也不产生正式评测成绩。

3. 顺序运行全部 109 题

npm run eval -- --out output/evals/webvoyager-109-20260916-concurrency1 --reasoning-effort high --concurrency 1 --headed --timeout 600000 --judge evidence

数据集包含 Allrecipes 35 题、Apple 35 题、Amazon 39 题。我们的完整运行使用可见浏览器、evidence 评分、每题 600 秒上限、50 轮模型请求和 --concurrency 1。并发会影响限流频率和延迟，对照运行必须保持一致；每次全新评测使用独立输出目录。

WebVoyager 109 tasks / 3 站点：成功率 88.1%（AllRecipes 88.6%、Apple 85.7%、Amazon 89.7%），平均 26.7 步、167.3s、$0.0968/任务。这里的成本是 Agent 标价等价估算；加上 Judge 后平均为 $0.1047/任务。

启动时会用小请求检查模型服务，默认准入超时为 60000 ms，可通过 --preflight-timeout 调整。Agent 运行中的临时限流、服务端错误、超时和传输错误会按有界指数退避自动重试；preflight 和独立 Judge 请求则是单次调用，失败后停止派发或留下未完成评分。额度耗尽与认证失败不会重试。若出现 quota_exhausted，需先恢复对应模型账户的额度。缺失或未评分任务不能作为完整评测成绩发布。

halted / 现象	含义	处理方式
provider_rate_limit	preflight/Judge 首次遇到 HTTP 429，或 Agent 的有界重试仍未恢复	等待限流窗口恢复并使用 --concurrency 1；零题 preflight 失败且配置未变时可 --resume，要重做已有失败题或取得干净成绩则换新目录
provider_connection	preflight/Judge 单次调用，或 Agent 重试后仍遇到超时、传输错误、HTTP 5xx	preflight 查控制台和 preflight.ndjson；Agent 查 TASK_ID/result.json、trace.ndjson、host-log.ndjson；Judge 查 results.ndjson 的 judge_result。慢模型可在新输出目录设置 --preflight-timeout 120000
quota_exhausted	账户额度、余额或 Token Plan 用量已耗尽	恢复额度后再运行；此类永久错误不会自动重试
provider_authentication	API Key 无效、缺失权限或服务返回 HTTP 401/403	检查 DSH provider、apiKeyEnv 和 .credentials.yaml 引用，不要把密钥写入仓库
provider_preflight_failed	未归入上述类型的准入错误	读取 output/evals/RUN_NAME/preflight.ndjson 中的 error，不要把零题运行当作 benchmark 成绩

Allrecipes 返回 People Inc access issue 页面时属于目标网站访问限制，不是模型 provider 故障；降低模型并发或延长 preflight 超时不会绕过该限制。

4. 中断后继续

npm run eval -- --out output/evals/webvoyager-109-20260916-concurrency1 --reasoning-effort high --concurrency 1 --headed --timeout 600000 --judge evidence --resume

# Agent 结果已保存、仅 Judge 失败时重新评分，不重新运行浏览器
npm run eval -- --out output/evals/webvoyager-109-20260916-concurrency1 --reasoning-effort high --judge-only --judge evidence

续跑需保持原输出目录、选题、配置及代码指纹完全一致。修改 --concurrency、--preflight-timeout、模型、Judge、评测脚本或构建产物后不能续跑原目录，必须指定新的 --out。已有结果（包括失败和超时）会跳过，不会自动重跑或重新评分；仅 Judge 失败时使用 --judge-only 生成单独的 judged-evidence.json。发现已有 trace.ndjson 但没有 result.json 的中断题时，评测器会直接拒绝继续，避免静默重试。需要重新执行这些题时，使用新的输出目录。不要删除仍需续跑的记录。

5. 查看结果与保留代码

全量命令的结果位于命令指定的 output/evals/RUN_NAME/：

文件	内容
report.md	总体及分站点成功率、平均步数、耗时、成本估算
summary.json	结构化统计和评分完整性标记
manifest.json	选题、模型、API 协议、推理档位、参数及代码指纹
results.ndjson	逐题执行与评分结果
TASK_ID/trace.ndjson	模型请求、响应和工具执行记录
TASK_ID/result.json、TASK_ID/final.png	Agent 原始结果和最终截图（如有）

completed 只代表 Agent 执行结束，judge_result.pass 才代表 Judge 判定通过。当前只对 MiniMax-M3 提供公开单价估算，GLM 等其他模型会显示 unpriced_calls，total_cost_usd: null 不代表实际费用为 0；估算也不是 Token Plan 实际账单。

output/ 中的旧评测记录可在不再需要回看、续跑或重新评分时删除，不影响新评测。请保留正式代码 scripts/eval/、插件源码 src/、数据集 assets/benchmark/ 及依赖清单。更多参数、评分口径和参考结果差异见评测指南。

开发与验证

npm install
npm test
npm run test:smoke
npm run test:host
npm run verify:package
npm run verify:installed

命令	验证内容
npm test	构建、包结构、工具注册、错误契约、approval 和配置测试
npm run test:smoke	真实 Chromium：DOM、脚本、截图、附件、清理，以及动态/虚拟列表、操作验证和状态恢复
npm run test:host	真实 Cordis/DSH Agent Loop + Chromium，验证下一轮消息、基线恢复、截图裁剪、回放与会话隔离；模型决策使用确定性适配器
npm run verify:package	确认 npm 包是独立 DSH bundle 且不包含 Harness checkout
npm run verify:installed	在临时 npm 消费者项目中安装 tarball 并导入插件

test/browser-context.test.mjs 可通过 DSH_TEST_SESSION_MODULE 指定另一宿主 Session 模块的文件 URL，以复用全部上下文测试。检查 DSH 源码版本时，从其仓库根目录执行（假设插件位于相邻的 dsh-browser 目录）：

$env:DSH_TEST_SESSION_MODULE = ([uri](Resolve-Path packages/core/session/src/index.ts).Path).AbsoluteUri
node --import tsx/esm --test ../dsh-browser/test/browser-context.test.mjs
Remove-Item Env:DSH_TEST_SESSION_MODULE

贡献流程见 CONTRIBUTING.md，安全边界和漏洞报告方式见 SECURITY.md。我们将动态列表、动作后置条件、检查点恢复、证据记录和 Host 上下文管理视为项目的常规能力，其行为契约分别写在可靠性文档和证据文档中。

许可证

本项目使用 MIT License。

---

🇬🇧 dsh-browser-use (English)

Give DeepSeek Harness a real browser so an Agent can open pages, understand interfaces, fill forms, manage tabs, and complete multi-step tasks.

We build dsh-browser-plugin as a standalone DeepSeek Harness (DSH) plugin for the Web profile. It launches a local Chrome or Chromium instance and exposes 16 browser operations plus four task/evidence tools through Puppeteer, the Chrome DevTools Protocol (CDP), and incremental DOM snapshots.

Our completed WebVoyager run covers 109 tasks across three sites: 88.1% overall success (AllRecipes 88.6%, Apple 85.7%, Amazon 89.7%), with 26.7 average tool calls, 167.3 seconds, and an estimated $0.0968 Agent cost per task.

This repository contains only the browser plugin's own source. It neither contains DeepSeek Harness source nor requires users to clone the Harness repository.

What it enables

Task	Without the plugin	With the plugin
Visit dynamic sites	Limited to search or static fetch	Operate a real Chromium page
Fill complex forms	Cannot reliably handle dynamic controls	Locate, fill, and click DOM references
Conduct multi-step research	Manually copy content at every step	Continue exploration across tabs
Understand page changes	Re-read the full page repeatedly	Prefer DOM diffs and establish a full baseline when needed
Inspect charts and images	Text-only information	Capture visual elements as DSH attachments

Core features

• Real Chromium — Controls local Chrome/Chromium instead of simulating a page or performing an HTTP-only fetch.
• Incremental DOM — Returns a full initial snapshot, then prefers +| / -| diffs to reduce repeated context.
• Stable element references — Clickable elements use [N], inputs use <N>, and visual elements use [view:ID].
• Session isolation — Each DSH Agent owns an independent browser process, tab set, CDP session, and DOM cache.
• Tabs and long-page exploration — Create, switch, and close tabs; explore content screen by screen or jump to a page position.
• Native DSH lifecycle — Uses Cordis, defineTool, approval, cancellation signals, and attachments without a compatibility server.
• Explicit browser routing — When the user explicitly requests a browser or Chromium, the model starts with browser_start and stays on browser_* instead of substituting web_search or web_fetch.
• Secure defaults — Chromium sandboxing is enabled, and state-changing operations request DSH approval by default.
• Bounded output — Oversized script results return a preview while the full value is written to a configured or temporary directory.
• Evidence-backed records — We archive observations by visit, register structured fields through sourceRef, and recheck declared coverage at completion.
• Postcondition-aware actions — Click and input can verify text or URL outcomes; execution, checked postconditions, and whole-task completion remain separate claims.
• Exact checkpoint restoration — We restore supported form, details, and scroll state by full stateId, reporting incomplete restoration as partial.
• Structured and cross-frame diagnostics — Script helpers cover JSON-LD and repeated records, while OOPIF routing plus CDP tape/statistics support reproducible DOM diagnostics.

Quick start

Requirements

• Node.js >=22.19
• Chrome or Chromium
• pnpm (used by the DSH plugin installation command)

node --version
pnpm --version

Install pnpm if it is missing:

npm install --global pnpm

Install the current local build

The package has not been published to npm yet, so these steps assume you already obtained the source through the current private distribution channel. Build a standard npm tarball and add it to the DSH web profile:

Set-Location path\to\dsh-browser
npm install
$package = npm pack --silent

npx @deepseek-ai/dsh@0.1.2-alpha.2 plugin --profile web add ".\$package"
npx @deepseek-ai/dsh@0.1.2-alpha.2 --profile web --dump-config
npx @deepseek-ai/dsh@0.1.2-alpha.2 web

The dumped config should contain id: dsh-browser and name: dsh-browser-plugin.

After npm publication

npx @deepseek-ai/dsh@0.1.2-alpha.2 plugin --profile web add dsh-browser-plugin
npx @deepseek-ai/dsh@0.1.2-alpha.2 web

On first use, npx may download the published DSH CLI and its dependencies; plugin installation downloads this plugin and its dependencies. Neither path downloads a DeepSeek Harness source checkout.

Quick configuration (optional)

The defaults work out of the box. Before packing locally, you can edit this repository's cordis.patch.yml. After installation, merge the entry below into the existing YAML list in $DSH_HOME/profiles/web/cordis.patch.yml (DSH_HOME defaults to ~/.dsh); do not overwrite unrelated profile entries. This user layer overrides the bundle defaults.

A DSH profile patch replaces the matched entry's entire config, so restate every field that must be retained:

- id: dsh-browser
  config:
    headless: true
    noSandbox: false
    approvalMode: mutating
    viewportWidth: 1280
    viewportHeight: 900
    toolTimeoutMs: 120000
    maxWaitSeconds: 300
    maxContextDeltas: 8
    scriptMaxLines: 100
    scriptMaxBytes: 8192

Restart DSH after editing, then inspect the effective config with npx @deepseek-ai/dsh@0.1.2-alpha.2 --profile web --dump-config.

Need	Setting	Default	Common change
Run without a visible window	headless	false	Set to true
Select a browser executable	chromePath	Auto-detect	Set an absolute Chrome/Chromium path
Change approval behavior	approvalMode	mutating	off, mutating, or always
Resize the viewport	viewportWidth / viewportHeight	1280 / 900	Set positive integers
Limit one tool call	toolTimeoutMs	120000	Set positive milliseconds
Limit explicit waits	maxWaitSeconds	300	Set positive seconds
Bound DOM delta chains	maxContextDeltas	8	Positive integer; then produce a full checkpoint
Bound visible script output	scriptMaxLines / scriptMaxBytes	100 / 8192	Set positive integers
Store complete script results	outputDir	System temp directory	Set an absolute directory path

Set noSandbox: true only when a controlled container has a demonstrated compatibility requirement.

Usage examples

After installation, describe the task in natural language:

Information extraction

Open the Hugging Face trending models page, collect the top three model names, organizations, parameter counts, and download counts, and include the source page.

Form filling

Open the contact form, fill the fields I provide, and check required-field and format validation, but do not submit it.

Multi-step research

Investigate a paper's official code repository, dependencies, maintenance status, and common reproduction issues, then rate its reproduction difficulty.

For login, purchase, publish, delete, or final-submit operations, keep approval enabled and state the task boundary explicitly.

How incremental DOM works

Many browser Agents resend the entire page after every action. This plugin retains a DOM snapshot chain for each tab:

First observation   → mode:full         complete DOM
Small page change   → mode:incremental  added +| and removed -|
Large change/checkpoint → mode:full     new complete baseline
No page change      → mode:nochange     short status message

Processing pipeline:

CDP Snapshot
  → DOM Tree
  → visibility and interactivity detection
  → pruning, inline merging, and visual-element mapping
  → structured-text rendering
  → diff against the previous snapshot
  → Agent output

browser_restore_state uses the exact versioned checkpoint ID (for example tab0-dom3.2) to restore its URL, native form values, checked/selected options, details state, and window/nested scroll positions. It verifies the result and returns partial when incomplete. Passwords, file selections, iframe state, arbitrary dialogs and SPA memory are not restored.

Tool reference

Tool	Purpose
browser_start	Launch the browser and open a URL
browser_observe	Observe a full current state without reloading, as HTML or Markdown
browser_goto	Navigate the active tab
browser_refresh	Reload the active page
browser_restore_state	Restore supported page state using the exact checkpoint stateId; report omissions
browser_new_tab	Create a tab
browser_switch_tab	Change the active tab
browser_close_tab	Close one or more tabs
browser_click	Click a [N] element
browser_input	Enter content into a <N> element
browser_reveal_offscreen	Reveal a known off-screen element
browser_scroll_next_screen	Advance 80% of the viewport with overlap for loaded content
browser_scroll_to_page	Jump to a page position
browser_execute_script	Run JavaScript in the page context
browser_view_elements	Capture [view:ID] visual elements
browser_wait	Wait for a bounded number of seconds with cancellation support
browser_define_task	Declare required fields and minimum records for this turn
browser_record_facts	Register sourceRef task records; support legacy facts
browser_check_coverage	Check field coverage and report missing evidence
browser_recall	Search current/historical facts or read archived browser observations

Architecture

DSH Agent Session
  → Cordis loads dsh-browser-plugin
  → @deepseek-ai/dsh-tools defineTool
  → DSH approval / cancellation / timeout
  → browser operation
  → Session-scoped BrowserManager
  → Puppeteer + Chromium + CDP + DOM Service
  → canonical tool output / DSH attachments / observation metadata
  → agent/pre-step: browser context retention
  → Session surface → next model request

Repository layout:

dsh-browser/
├─ src/
│  ├─ index.ts              # Cordis entry and lifecycle
│  ├─ plugin-tools.ts       # Browser registrations; 20 tools with memory tools
│  ├─ tool-schemas.ts       # parameter and output schemas
│  ├─ config.ts             # config schema and validation
│  └─ browser/
│     ├─ manager.ts         # browser and tab lifecycle
│     ├─ operations/        # navigation, interaction, observation, and scrolling
│     ├─ cdp/               # CDP wrappers
│     └─ dom/               # DOM building, rendering, diffing, and visual mapping
├─ test/                    # node:test suite
├─ scripts/                 # real-browser and installation verification
├─ cordis.patch.yml         # DSH bundle patch
└─ package.json             # npm and DSH bundle manifest

src/ is the source of truth. lib/ is generated by npm run build; do not edit lib/ directly.

Context preparation reads current host logs through Session.snapshotEvents() and uses the events getter on the pinned DSH 0.1.2-alpha.2 host. After changing a source-linked installation, rebuild the plugin and restart pnpm dsh web to load the updated lib/.

Set DSH_TEST_SESSION_MODULE to another host Session module's file URL to run test/browser-context.test.mjs against it. For a source checkout, run from the DSH root with its TypeScript loader (the plugin is assumed to be in the sibling dsh-browser directory):

$env:DSH_TEST_SESSION_MODULE = ([uri](Resolve-Path packages/core/session/src/index.ts).Path).AbsoluteUri
node --import tsx/esm --test ../dsh-browser/test/browser-context.test.mjs
Remove-Item Env:DSH_TEST_SESSION_MODULE

Development and verification

npm install
npm test
npm run test:smoke
npm run test:host
npm run verify:package
npm run verify:installed

Command	Evidence produced
npm test	Build, package shape, tool registration, error contract, approval, and config tests
npm run test:smoke	Real Chromium DOM, images, cleanup, dynamic/virtual lists, postconditions and checkpoint restoration
npm run test:host	Published Cordis/DSH Agent Loop + Chromium; real model-request inputs, baseline recovery, images, replay and isolation with deterministic decisions
npm run verify:package	Confirms the npm package is a standalone DSH bundle with no Harness checkout
npm run verify:installed	Installs the tarball in a temporary consumer project and imports the plugin

See CONTRIBUTING.md for the contribution workflow and SECURITY.md for security boundaries and vulnerability reporting.

Browser, evidence, and diagnostic contract

We treat dynamic-list coverage, action postconditions, exact checkpoint restoration, evidence records, and Host context management as normal product capabilities rather than dated additions. The package exposes 20 tools: 16 browser operations and four task/evidence tools.

The evidence flow is archive → visit-level Evidence Bundles → sourceRef records → continue browsing → check declared field coverage at completion → recall or browse to fill gaps. Coverage is revision-specific and does not prove exhaustive search or arbitrary answer prose. Exact checkpoint IDs restore supported native fields and scrolling; unavailable state returns error, while incomplete restoration returns partial.

browser_observe creates a current full baseline without reloading, with optional Markdown action references. Script helpers include __data, __records, __skeleton, and browser-free guide: true. Child-frame CDP routing, frame-scoped references, URL-change notices, and bounded script evidence extend the same execution contract.

Our opt-in dom:regression capture/verify workflow and the separate /diagnostics export provide socket-free DOM regression and CDP statistics. Recordings contain local page data and are not general Agent evaluation. See reliability and verification and the evidence state model.

License

This project is released under the MIT License.