dengpeihua/dsh-browser-use

dsh-browser — DeepSeek Harness 的原生浏览器代理

dsh-browser-use

面向 DeepSeek Harness 的原生 Chromium 浏览器代理工具

在 WebVoyager 126 个任务 / 3 个站点上取得 92.9 % 的成功率，平均 15.3 步 / 任务，耗时 149 秒 / 任务，成本约 $ 0.031 / 任务。成本为 Agent 标价等价估算，Judge 费用另计；评测方法和历史归档见评测指南。

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

= 22.19">

🇨🇳 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 个归档回读工具。

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

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

它能做什么

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

核心特性

- 真实 Chromium — 使用本机 Chrome/Chromium，而不是 HTTP 抓取器或模拟页面。
- 增量 DOM — 首次返回完整快照，后续优先返回 +| / -| 差异，减少重复上下文。
- 稳定元素引用 — 可点击元素使用 [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

安装当前本地版本
该包目前尚未发布到 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 | 向  元素输入内容 |
| browser_reveal_offscreen | 展示已知的离屏元素 |
| browser_scroll_next_screen | 滚动到下一段未探索内容 |
| browser_scroll_to_page | 跳到指定页面位置 |
| browser_execute_script | 在页面上下文执行 JavaScript |
| browser_view_elements | 截取 [view:ID] 视觉元素 |
| browser_wait | 可取消地等待指定秒数 |
| 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       # 注册 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、取消和输出限额，并保持以下能力边界：

| 能力 | 使用方式与边界 |
|---|---|
| 显式观察 | 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|verify 录制和回放受控 CDP 输入；录制可能含页面数据，只保存在本地受控目录。 |

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

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

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 reference

正式评测条件固定为 --headed --timeout 600000 --judge reference：显示浏览器窗口、每题最多运行 600 秒，并逐字加载固定上游版本 opencode-browser 的 judge-prompt.md。每次评分提供对应任务和 Agent 结果，要求返回单项 JSON 数组；error/timeout 只要最终答案有效也允许 PASS。它们也是评测器的默认值，但命令中仍显式写出，便于复核 manifest 和复现实验。reference 不提交浏览器文本证据或截图；旧的严格证据评分仍可显式选择 --judge evidence，但不属于上游同口径。--reasoning-effort high 显式固定 Agent 和默认 Judge 的推理档位，并写入 manifest 和运行指纹。真实试跑和全量评测都会消耗 Agent、Judge 的 API 额度；npm run eval:smoke 则使用真实浏览器和确定性模型替身，不调用收费 API，也不产生正式评测成绩。

3. 顺序运行全部 126 题
powershell
npm run eval -- --out output/evals/webvoyager-126-concurrency1 --reasoning-effort high --concurrency 1 --headed --timeout 600000 --judge reference

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

当前本地评测汇总覆盖 126/126 题，全部已评分，117/126 通过，成功率 92.9%。平均每题调用浏览器工具 15.3 次，Agent 耗时 149 秒，Agent 成本按标价估算约 $0.031；Judge 成本另计。评分模式为 reference，成功率分母包含失败和超时任务。此处的成本是估算值，不是实际账单。

启动时会用小请求检查模型服务，默认准入超时为 60000 ms，可通过 --preflight-timeout 调整。Agent 运行中的临时限流、服务端错误、超时和传输错误会按有界指数退避自动重试；preflight 和独立 Judge 请求均为单次调用。Judge API、截断或格式异常记录为未评分，不能算作任务 FAIL；可在服务恢复后用 --judge-only 补评。额度耗尽与认证失败不会重试。若出现 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. 中断后继续
powershell
普通中断续跑
npm run eval -- --out output/evals/webvoyager-126-concurrency1 --reasoning-effort high --concurrency 1 --headed --timeout 600000 --judge reference --resume

完全更换评分规则：先清除旧 Judge 内容，再重新评分全部已保存 Agent 结果；不重跑浏览器
npm run eval:reset-judge -- --out output/evals/webvoyager-126-concurrency1
npm run eval:reset-judge -- --out output/evals/webvoyager-126-concurrency1 --execute
npm run eval -- --out output/evals/webvoyager-126-concurrency1 --reasoning-effort high --judge-only --judge reference
续跑需保持原输出目录、选题、配置及代码指纹完全一致。修改 --concurrency、--preflight-timeout、模型、Judge、评测脚本或构建产物后不能续跑原目录，必须指定新的 --out。已有结果（包括失败和超时）会跳过，不会自动重跑或重新评分；要重新评分时使用 --judge-only 生成单独的 judged-reference.json。发现已有 trace.ndjson 但没有 result.json 的中断题时，评测器会直接拒绝继续，避免静默重试。需要重新执行这些题时，使用新的输出目录。不要删除仍需续跑的记录。

5. 只补旧运行缺失的任务
powershell
只读核对：验证旧任务轨迹并列出精确差集，不加载凭据或启动浏览器
npm run eval:backfill -- --out output/evals/OLD_RUN --data assets/benchmark/webvoyager-126.json

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

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

6. 查看结果与保留代码

全量命令的结果位于命令指定的 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/ 及依赖清单。更多参数、评分口径和参考结果差异见评测指南。

开发与验证
powershell
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 目录）：
powershell
$env:DSH_TEST_SESSION_MODULE = (uri.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.
我们将 dsh-browser-plugin 构建为一个独立的 DeepSeek Harness (DSH) 插件，用于 Web 配置文件。它启动本地 Chrome 或 Chromium 实例，并通过 Puppeteer、Chrome DevTools Protocol (CDP) 和增量 DOM 快照暴露 16 项浏览器操作以及一个归档召回工具。

我们当前的本地 WebVoyager 结果覆盖了三个站点上的全部 126 个任务。所有任务均使用 reference 评判器进行评判，其中 117 个通过：成功率为 92.9%，每个任务平均 15.3 次浏览器工具调用和 149 秒。按标价估算，Agent 成本约为每个任务 $0.031；评判器成本另计。

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

它能实现什么

| 任务 | 没有插件 | 有插件 |
|---|---|---|
| 访问动态站点 | 仅限于搜索或静态抓取 | 操作真实的 Chromium 页面 |
| 填写复杂表单 | 无法可靠处理动态控件 | 定位、填写并点击 DOM 引用 |
| 进行多步研究 | 每一步都手动复制内容 | 跨标签页继续探索 |
| 理解页面变化 | 反复重读整个页面 | 优先使用 DOM 差异，并在需要时建立完整基线 |
| 检查图表和图像 | 仅文本信息 | 将视觉元素捕获为 DSH 附件 |

核心功能

- 真实 Chromium —— 控制本地 Chrome/Chromium，而不是模拟页面或仅执行 HTTP 抓取。
- 增量 DOM —— 返回完整的初始快照，然后优先使用 +| / -| 差异以减少重复上下文。
- 稳定的元素引用 —— 可点击元素使用 [N]，输入框使用 ，视觉元素使用 [view:ID]。
- 会话隔离 —— 每个 DSH Agent 拥有独立的浏览器进程、标签页集合、CDP 会话和 DOM 缓存。
- 标签页与长页面探索 —— 创建、切换和关闭标签页；逐屏探索内容或跳转到页面位置。
- 原生 DSH 生命周期 —— 使用 Cordis、defineTool、审批、取消信号和附件，无需兼容服务器。
- 显式浏览器路由 —— 当用户明确请求浏览器或 Chromium 时，模型从 browser_start 开始，并保持在 browser_* 上，而不是替换为 web_search 或 web_fetch。
- 安全默认值 —— 启用 Chromium 沙箱，并且改变状态的操作默认请求 DSH 审批。
- 有界输出 —— 过大的脚本结果返回预览，而完整值写入配置的或临时目录。
- 同一步骤文本保留 —— 每个 DOM 快照都告诉 Agent 在更改页面之前，将重要答案、值和导航线索写入同一个助手输出中，而无需额外的旧式事实摘要调用。
- 按需归档召回 — 观测结果按访问归档；browser_recall 在需要时检索较早的页面，无需逐页注册，也没有完成覆盖率门槛。
- 后置条件感知操作 — 点击和输入可以验证文本或 URL 结果；执行、已检查的后置条件和整个任务完成仍是彼此独立的断言。
- 精确检查点恢复 — 我们通过完整的 stateId 恢复受支持的表单、详情和滚动状态，并将不完整的恢复报告为 partial。
- 结构化与跨框架诊断 — 脚本辅助工具覆盖 JSON-LD 和重复记录，而 OOPIF 路由加上 CDP tape/statistics 支持可复现的 DOM 诊断。

快速开始

环境要求

- Node.js >=22.19
- Chrome 或 Chromium
- pnpm（由 DSH 插件安装命令使用）
powershell
node --version
pnpm --version

如果缺少 pnpm，请安装它：
powershell
npm install --global pnpm

安装当前本地构建

该包尚未发布到 npm。获取此仓库的源代码，构建标准 npm tarball，并将其添加到 DSH web 配置文件：
powershell
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

导出的配置应包含 id: dsh-browser 和 name: dsh-browser-plugin。

npm 发布之后
powershell
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 可能会下载已发布的 DSH CLI 及其依赖项；插件安装会下载此插件及其依赖项。这两种方式都不会下载 DeepSeek Harness 源代码检出。

快速配置（可选）

默认值开箱即用。在本地打包之前，你可以编辑此仓库的 cordis.patch.yml。安装之后，将下面的条目合并到 $DSH_HOME/profiles/web/cordis.patch.yml 中现有的 YAML 列表（DSH_HOME 默认为 ~/.dsh）；不要覆盖无关的配置文件条目。此用户层会覆盖 bundle 默认值。

DSH 配置文件补丁会替换匹配条目的整个 config，因此必须重新声明所有需要保留的字段：
yaml
- 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。

使用示例

安装后，用自然语言描述任务：

信息提取

打开 Hugging Face 热门模型页面，收集前三个模型名称、组织、参数数量和下载量，并附上来源页面。

表单填写

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

多步骤研究

调查某篇论文的官方代码仓库、依赖项、维护状态和常见复现问题，然后评估其复现难度。

对于登录、购买、发布、删除或最终提交操作，请保持审批启用，并明确说明任务边界。

增量 DOM 的工作原理

许多浏览器 Agent 在每次操作后都会重新发送整个页面。此插件为每个标签页保留一条 DOM 快照链：
text
首次观察   → mode:full         完整 DOM
页面小幅变化   → mode:incremental  新增 +| 和移除 -|
大幅变化/检查点 → mode:full     新的完整基线
页面无变化      → mode:nochange     简短状态消息

处理流水线：
text
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 使用精确的带版本检查点 ID（例如 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 | 向一个  元素输入内容 |
| browser_reveal_offscreen | 显示一个已知的屏幕外元素 |
| browser_scroll_next_screen | 以重叠方式前进视口的 80% 以加载内容 |
| browser_scroll_to_page | 跳转到页面位置 |
| browser_execute_script | 在页面上下文中运行 JavaScript |
| browser_view_elements | 捕获 [view:ID] 视觉元素 |
| browser_wait | 等待有限秒数，支持取消 |
| browser_recall | 按需读取历史事实或已归档的浏览器观察记录 |

架构
text
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

仓库布局：
text
dsh-browser/
├─ src/
│  ├─ index.ts              # Cordis entry and lifecycle
│  ├─ plugin-tools.ts       # Registers 16 browser tools; one archive recall tool is separate
│  ├─ 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/ 是唯一事实来源。lib/ 由 npm run build 生成；请勿直接编辑 lib/。

上下文准备通过 Session.snapshotEvents() 读取当前宿主日志，并使用固定版本 DSH 0.1.2-alpha.2 宿主上的 events getter。更改源码链接安装后，请重新构建插件并重启 pnpm dsh web 以加载更新后的 lib/。

将 DSH_TEST_SESSION_MODULE 设置为另一个宿主 Session 模块的文件 URL，以针对其运行 test/browser-context.test.mjs。对于源码检出，请在 DSH 根目录下使用其 TypeScript 加载器运行（假定插件位于同级的 dsh-browser 目录中）：
powershell
$env:DSH_TEST_SESSION_MODULE = (uri.Path).AbsoluteUri
node --import tsx/esm --test ../dsh-browser/test/browser-context.test.mjs
Remove-Item Env:DSH_TEST_SESSION_MODULE
开发与验证
powershell
npm install
npm test
npm run test:smoke
npm run test:host
npm run verify:package
npm run verify:installed

| 命令 | 产生的证据 |
|---|---|
| npm test | 构建、包结构、工具注册、错误契约、审批和配置测试 |
| 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 | 在临时消费者项目中安装 tarball 并导入插件 |

有关贡献工作流，请参阅 CONTRIBUTING.md；有关安全边界和漏洞报告，请参阅 SECURITY.md。

浏览器、证据和诊断契约

我们保留动态列表覆盖、操作后置条件、精确检查点恢复、归档观察和 Host 上下文管理。该包公开 17 个工具：16 个浏览器操作和 browser_recall。

工作记忆流程是 观察 → 在同一条助手消息中写入重要发现 → 继续浏览 → 仅在需要时召回归档观察。文本笔记不是经过验证的 sourceRef 证据。精确的检查点 ID 可恢复受支持的本地字段和滚动；不可用状态返回 error，而不完整恢复返回 partial。

browser_observe 在不重新加载的情况下创建当前完整基线，并带有可选的 Markdown 操作引用。脚本辅助工具包括 __data、__records、__skeleton 和无浏览器的 guide: true。子框架 CDP 路由、框架作用域引用、URL 变更通知和有界脚本证据扩展了相同的执行契约。

我们可选的 dom:regression 捕获/验证工作流以及单独的 /diagnostics 导出提供无 socket 的 DOM 回归和 CDP 统计信息。录制内容包含本地页面数据，并非通用 Agent 评估。请参阅可靠性与验证和证据状态模型。

许可证

本项目在 MIT License 下发布。