dengpeihua/dsh-browser-use

dsh-browser-use

Native Chromium browser Agent tools for DeepSeek Harness

在 WebVoyager 549 tasks / 13 站点上，按下文完整评分规则复核后取得 88.0%（483/549） 的成功率，平均 16.3 steps、140 s、Agent 标价估算 $0.028 / 任务。归档中的 reference Judge 为 495/549（90.2%）；两种口径及逐题结果见评测报告。

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

中文 | 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 个浏览器操作与 1 个归档回读工具。

本仓库包含浏览器插件源码和预构建的 lib/，不包含 DeepSeek Harness 源码，也不要求用户克隆 Harness 仓库。

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

它能做什么

核心特性

• 真实 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。
• 有界输出 — 页面脚本结果过大时只向模型返回预览，并把完整结果写入指定目录或临时目录。
• 同轮文本留存 — 每个 DOM 快照提醒 Agent 在改变页面前把重要答案、数值和导航线索写进同一次 assistant 输出，无需额外调用旧事实总结接口。
• 按需回读归档 — 页面观察按访问自动归档；需要核对旧页面时再调用 browser_recall，不强制逐页登记或补齐字段。
• 操作后置条件 — 点击和输入可检查文本或 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

从桌面端插件市场安装

已验证 DSH 0.2.1-rc.2 桌面宿主，并保留 0.1.2-alpha.2 支持；插件会适配两版的工具结果消息和上下文替换接口。

搜索 dsh-browser-use，确认仓库为 dengpeihua/dsh-browser-use 后安装。仓库附带预构建的 lib/，pnpm 无需在安装时编译本插件或授权其构建脚本。安装仍需联网下载运行依赖。

评测归档 output/ 保留在 Git 仓库中，通过 .gitattributes 排除在源码下载包之外，避免安装插件时下载数 GB 的评测记录；需要完整记录时请浏览 GitHub 或使用 git clone。

若之前停在“正在安装”或出现 ERR_PNPM_GIT_DEP_PREPARE_NOT_ALLOWED，取消旧任务并刷新市场后重新安装，确保拉取当前提交。开发者修改源码后应运行 npm run build，将生成的 lib/ 一起提交。

安装当前本地版本

该包目前尚未发布到 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 检查最终配置。

只有受控容器确有兼容性需要时才应设置 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 内存不在恢复范围内。

工具清单

架构

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       # 注册 16 个浏览器工具，另有 1 个归档回读工具
│  ├─ 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/。

浏览器能力与诊断

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

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. 检查选题并可选试跑

# 只检查并列出 549 题，不启动浏览器、不调用模型 API
npm run eval -- --data assets/benchmark/WebVoyager_data.json --dry-run --reasoning-effort high --headed --timeout 600000 --judge reference

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

正式评测条件固定为 --headed --timeout 600000 --judge reference：显示浏览器窗口、每题最多运行 600 秒，并加载下文集中列出的完整评分规则。命令显式写出这些参数，便于复核 manifest 和复现实验。--reasoning-effort high 固定 Agent 和默认 Judge 的推理档位，并写入运行指纹。真实评测会消耗 Agent、Judge 的 API 额度；npm run eval:smoke 使用确定性模型替身，不产生正式评测成绩。

3. 当前 549 题评测

未指定 --out 时，评测默认输出到 output/evals/webvoyager；仍可用 --out 指定其他目录。若目录已有评测记录，程序会拒绝直接覆盖；继续旧运行须显式指定 --out 和 --resume，并通过原有的数据、配置与代码一致性检查。

# 全新评测使用独立输出目录
npm run eval -- --data assets/benchmark/WebVoyager_data.json --out output/evals/webvoyager-549-fresh --reasoning-effort high --concurrency 1 --headed --timeout 600000 --judge reference

当前评测归档覆盖 549 题、13 个站点。每题均有最新轨迹、评分及成本记录；定点重测保留全部尝试与修订链。评测并发为 1、每题最多 600 秒、最多 50 轮模型请求。

summary.json 的 reference Judge 为 495/549（90.2%）。按照下文完整评分规则复核最终答案，对 12 项明确缺少关键条件的通过判定作修正后，逐题复核报告为 483/549（88.0%）。复核没有重新调用模型或浏览器；运行结果和修订链保持原样。逐题 JSON 数组、最新尝试 results.ndjson和12 项改判明细可供独立检查。

复核口径平均 16.3 个浏览器步骤、Agent 耗时 140 秒、Agent 成本约 $0.028 / 任务；加上 Judge 约 $0.029 / 任务。成本按配置或历史美元标价估算，只计算每题最新尝试，不是 MiniMax Token Plan 账单。公开归档中 71 个文件的本机用户目录路径及 6 个文件中的 Google Maps API key 已脱敏；本地原始轨迹未改动，处理范围见归档中的 PUBLICATION.md。

4. 完整评测规则

WebVoyager Benchmark Evaluation

You are an evaluator for a web browsing agent benchmark. You will receive:

1. WebVoyager_data.json — the task definitions (task_id, confirmed_task, website)
2. results.ndjson — the agent's execution results (one JSON per line)

Your Job

For each result in results.ndjson, judge whether the agent successfully completed the task.

Evaluation Rules

PASS if:

• The agent's final_answer contains the specific information requested by the task
• The information is factually plausible (e.g., a recipe with "4.5 stars" when task asks for "at least 4.5 stars")
• Minor formatting differences, extra information, or verbose answers are acceptable
• Partial completion counts as PASS only if the core requirement is met

FAIL if:

• status is "error" or "timeout" AND final_answer is empty or does not answer the task
• The answer is wrong, irrelevant, or hallucinatory
• The answer is generic (e.g., "I found a recipe" without providing the actual recipe details)
• The agent failed to find the requested information and said so
• Key requirements are missing (e.g., task asks for "rating above 4.5" but agent's answer shows a 3-star recipe)

NOTE: If status is "error" but final_answer still contains a valid answer to the task, judge it as PASS.

Output Format

Return a JSON array, one object per task:

[
  {
    "task_id": "Allrecipes--0",
    "pass": true,
    "reason": "Agent found a vegetarian lasagna recipe with 4.6 stars and 150+ reviews, matching all criteria."
  },
  {
    "task_id": "Allrecipes--1",
    "pass": false,
    "reason": "Agent returned a lasagna recipe but it does not use zucchini as required."
  }
]

Requirements for each entry:

• task_id: must match exactly
• pass: boolean
• reason: one sentence explaining why pass or fail, referencing the specific task requirement

Important

• Compare final_answer against confirmed_task from WebVoyager_data.json for each matching task_id
• Do NOT skip any result — every entry in results.ndjson must have a judgment
• Be strict on whether the core task requirement is met, but lenient on presentation
• If the task asks for multiple things (e.g., "find a recipe AND list ingredients"), all parts must be present to PASS

Evaluate all results now.

以上为完整规则，独立文件见 judge-prompt.md；549 题的逐题判定见 judgments.json。

启动时会用小请求检查模型服务，默认准入超时为 60000 ms，可通过 --preflight-timeout 调整。Agent 运行中的临时限流、服务端错误、超时和传输错误会按有界指数退避自动重试；preflight 和独立 Judge 请求均为单次调用。Judge API、截断或格式异常记录为未评分，不能算作任务 FAIL；可在服务恢复后用 --judge-only 补评。额度耗尽与认证失败不会重试。若出现 quota_exhausted，需先恢复对应模型账户的额度。

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

5. 中断后继续

# 普通中断续跑
npm run eval -- --data assets/benchmark/WebVoyager_data.json --out output/evals/webvoyager --reasoning-effort high --concurrency 1 --headed --timeout 600000 --judge reference --resume

# 完全更换评分规则：先清除旧 Judge 内容，再重新评分全部已保存 Agent 结果；不重跑浏览器
npm run eval:reset-judge -- --out output/evals/webvoyager
npm run eval:reset-judge -- --out output/evals/webvoyager --execute
npm run eval -- --data assets/benchmark/WebVoyager_data.json --out output/evals/webvoyager --reasoning-effort high --judge-only --judge reference

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

6. 只补运行中缺失的任务

# 只读核对：验证旧任务轨迹并列出精确差集，不加载凭据或启动浏览器
npm run eval:backfill -- --out output/evals/OLD_RUN --data assets/benchmark/WebVoyager_data.json

# 审核清单后执行；旧任务进入保护集合，只有差集可被派发
npm run eval:backfill -- --out output/evals/OLD_RUN --data assets/benchmark/WebVoyager_data.json --execute

补跑器要求已有 manifest 是目标数据集的同内容有序子序列，并逐题验证已有 task.json、session.json、非空 trace.ndjson、result.json 和最终索引。已有任务即使存在于恢复计划中也不会被重新运行或重新评分；新增结果按目标数据集原位置重建 results.ndjson、JSON、Markdown 和 CSV。原 manifest 保存为 manifest-before-backfill.json，扩展后的结果标记 mixed_provenance。

7. 查看结果与保留代码

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

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

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 上下文管理视为项目的常规能力，其行为契约分别写在可靠性文档和证据文档中。

🙏 致谢

感谢 opencode-browser 项目的作者与贡献者，慷慨分享他们的代码与见解。

感谢 dsh-market 项目的作者与贡献者，为 DeepSeek Harness 构建可视化插件市场，让用户能够便捷地发现、浏览和安装社区插件。

许可证

本项目使用 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 one archive recall tool through Puppeteer, the Chrome DevTools Protocol (CDP), and incremental DOM snapshots.

The current WebVoyager archive covers 549 tasks across 13 sites. Its saved reference Judge scored 495/549 (90.2%); a review using the full rubric in this README corrected 12 clear missing-requirement passes and scored 483/549 (88.0%). The review averages 16.3 browser steps and 140 seconds per task, with estimated Agent list-price cost of $0.028 per task ($0.029 including Judge). See the per-task results and site breakdown. The public archive redacts local user-directory paths in 71 files and Google Maps API keys in 6 files while leaving the original local trajectories intact.

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

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.
• Same-step text retention — Every DOM snapshot tells the Agent to write important answers, values, and navigation cues into the same assistant output before changing pages, without an extra legacy fact-summary call.
• On-demand archive recall — Observations are archived by visit; browser_recall retrieves older pages when needed, without per-page registration or a completion coverage gate.
• 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 plugin supports the verified DSH 0.2.1-rc.2 desktop host and 0.1.2-alpha.2. It adapts tool-result messages and context-replacement bounds to each host contract.

The package has not been published to npm yet. Obtain this repository's source, 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 sho