dsh-browser4

dsh plugin --profile web add dsh-browser4

🤖 Browser4


项目主页：github.com/platonai/Browser4 · 官网：browser4.io

---

[English](README.md) | 简体中文 | 中国镜像

<!-- TOC -->

目录

• [🤖 Browser4](#-browser4)
• [🌟 项目简介](#-项目简介)
• [✨ 核心能力](#-核心能力)
• [📦 安装](#-安装)
• [检查并安装 DeepSeek Harness（DSH）](#1-检查并安装-deepseek-harnessdsh)
• [安装 Browser4 插件（推荐）](#2-安装-browser4-插件推荐)
• [启动 DSH](#3-启动-dsh)
• [在 DSH 中使用 Browser4](#4-在-dsh-中使用-browser4)
• [安装 browser4-cli（可选）](#安装-browser4-cli可选)
• [免安装使用（可选）](#免安装使用可选)
• [快速开始](#快速开始)
• [🧭 工具选择指南](#-工具选择指南)
• [如何与页面交互](#如何与页面交互)
• [如何提取数据](#如何提取数据)
• [如何批量处理页面](#如何批量处理页面)
• [如何把 HTML 转成电子表格——零 Token](#如何把-html-转成电子表格零-token)
• [💡 面向人的 CLI 指南](#-面向人的-cli-指南)
• [快速上手](#快速上手)
• [心智模型](#心智模型)
• [全局选项](#全局选项)
• [命令列表前需要理解的概念](#命令列表前需要理解的概念)
• [完整命令参考](#完整命令参考)
• [超时环境变量](#超时环境变量)
• [状态持久化](#状态持久化)
• [🚀 从源码构建](#-从源码构建)
• [架构](#架构)
• [📦 模块概览](#-模块概览)
• [🧪 测试夹具服务器（MockSite）](#-测试夹具服务器mocksite)
• [🤝 支持与社区](#-支持与社区)
• [📜 文档](#-文档)
• [🔧 代理配置](#-代理配置---解锁网站访问)
• [许可证](#许可证)

<!-- /TOC -->

🌟 项目简介

💖 Browser4：一个快速、智能、可扩展、适用于多种场景的智能体浏览器 💖

🌟 简介

💖 Browser4 — 面向 AI Agent 的新一代智能浏览器引擎，连接网页、数据与自动化任务。 💖

✨ 核心能力

• 🤖 Agent Browser — 为 AI Agent 提供自主浏览、网页操作和自动化执行能力。
• 🧠 ML 智能提取 — 通过机器学习理解网页结构，无需消耗 LLM Token，即可从复杂页面提取结构化数据。
• ⚡ 高性能架构 — 协程安全设计，支持单机每天 10 万～20 万复杂网页访问。
• 🧬 智能数据管线 — 融合 LLM、ML、X-SQL 与选择器，实现复杂网页的数据提取、清洗与经验复用。
• 📦 企业级自动化平台 — 支持大规模网页访问、CDP 原生控制、批处理、有状态浏览、插件扩展等能力。

📦 安装

1. 检查并安装 DeepSeek Harness（DSH）

先检查本地是否已经安装 DSH：

dsh --version

如果命令能够正常输出版本号，说明 DSH 已就绪，可直接进入下一步。如果提示找不到命令，请根据操作系统安装。

macOS

安装 Node.js 20 或更高版本，然后安装 DSH：

brew install node
npm install -g @deepseek-ai/dsh

Windows

在 PowerShell 中安装 Node.js LTS：

winget install OpenJS.NodeJS.LTS

安装完成后重新打开 PowerShell，再安装 DSH：

npm install -g @deepseek-ai/dsh

安装后再次运行 dsh --version，确认 DSH 可以正常使用。

2. 安装 Browser4 插件（推荐）

用一条命令把 dsh-browser4 作为 DSH 插件 bundle 安装——从 npm registry 或直接从 GitHub：

dsh plugin --profile web add dsh-browser4                  # npm registry
dsh plugin --profile web add github:platonai/dsh-browser4  # GitHub

安装包时会执行包内的安装脚本（scripts/install-browser4.mjs），它只做两件事：

1. 按照 [browser4-cli SKILL 的安装流程](skills/browser4-cli/SKILL.md) 安装 browser4-cli（npm install -g browser4-cli → browser4-cli install；npm 不可用时回退到 SKILL.md 中的平台引导脚本）。

2. 用 browser4-cli skills unpack 把 SKILL 文件解压到 ~/.dsh/skills 和 ~/.agents/skills（尊重 $DSH_HOME / $DSH_AGENTS_HOME），让所有 DSH profile 与 preset 都能发现 browser4-cli、browser4-experience、browser4-plugin、scent-miner 四个技能。

此外，bundle 的 cordis.patch.yml 会注册 skill-provider 层，直接从已安装包的 skills/ 目录提供同样的技能。

解压到用户目录的是你本机 browser4-cli 二进制内嵌的版本。 browser4-cli skills unpack 读取的是 CLI 自身编译进去的技能文件，而不是本 npm 包里附带的那份。这是有意为之：智能体的使用说明永远与你机器上实际安装的 CLI 的命令集、选项和行为完全一致——无网络请求、无版本漂移；升级 browser4-cli 后只需再跑一次 browser4-cli skills unpack 即可刷新。

也支持更短的别名：dsh plugin --profile web add b4@github:platonai/dsh-browser4。

pnpm ≥ 10 默认拦截依赖构建脚本。 如果 add 因构建权限失败，把 pnpm 打印的包 key 原样复制到该 profile 的 pnpm-workspace.yaml（位于 $DSH_HOME/profiles/web/）并重新执行命令：

```yaml

allowBuilds:

dsh-browser4: true

```

从本地 checkout 安装（dsh plugin --profile web add ./dsh-browser4）只是链接包，不会执行生命周期脚本——请随后手动运行一次安装器：

node scripts/install-browser4.mjs

3. 启动 DSH

dsh web

4. 在 DSH 中使用 Browser4

启动 DSH 后，bundle 会自动加载 Skill Provider，模型可通过 skill({ name: "browser4-cli" }) 或 /browser4-cli 命令加载使用说明，无需任何额外配置。

之后只需用自然语言向智能体描述任务即可，智能体会通过 browser4-cli 命令（借助 Bash 工具）驱动浏览器完成操作，例如：

打开 https://browser4.io，找到安装指南，
并把整页截图保存到当前目录。

智能体在背后执行的典型流程：

browser4-cli open --headless https://browser4.io   # 打开会话（首次运行后端启动约需 10 秒）
browser4-cli snapshot -i --boxes                   # 检查页面并获取元素 ref
browser4-cli click e15                             # 使用 ref 进行交互
browser4-cli screenshot --full-page --filename page.png

安装 browser4-cli（可选）

插件安装器已经帮你装好了 browser4-cli，因此手动安装是可选的。仅当你想在 DSH 之外单独使用 browser4-cli，或者 AI 智能体在阅读 SKILL 后被要求自行安装时才需要。

通过 npm 全局安装 browser4-cli（需要 Node.js）：

npm install -g browser4-cli
browser4-cli install

或者用单条命令直接引导安装原生二进制：

Windows（PowerShell）：

irm https://browser4.oss-cn-beijing.aliyuncs.com/scripts/install-browser4-cli.ps1 | iex
browser4-cli install

Linux / macOS（bash）：

curl -fsSL https://browser4.oss-cn-beijing.aliyuncs.com/scripts/install-browser4-cli.sh | bash
browser4-cli install

免安装使用（可选）

不需要安装插件。启动 DSH 后，让智能体阅读 SKILL 并自行安装：

Read https://browser4.io/SKILL.md and install browser4-cli (if not installed), then run `browser4-cli skills unpack` into ~/.dsh/skills and ~/.agents/skills, for browser automation

智能体会按照 SKILL.md 的 Installation 章节安装 browser4-cli，并把同一套技能文件解压到 DSH 技能目录——效果与插件安装器一致。

快速开始

把下面这段说明粘贴给你喜欢的 AI 智能体（如 claude、codex、workbuddy 或 openclaw）并执行：

Read https://browser4.io/SKILL.md and install browser4-cli (if not installed) for browser automation to perform the following task:

1. go to amazon.com
2. search for pens to draw on whiteboards
3. compare the first 4 ones
4. write the result to a markdown file

🧭 工具选择指南

根据任务类型选择最合适的工具：

如何与页面交互

需要与页面交互？
├─ 需要打开或恢复浏览器会话？→ open [url] 或 goto <url>
├─ 想先看当前哪些元素可点击 / 可输入？→ snapshot -i --boxes
├─ 需要点击按钮、链接、复选框或菜单项？→ click <ref>
├─ 需要填写表单并替换已有文本？→ fill <ref> "<text>"
├─ 需要像真人一样继续输入，或者发送 Enter / Tab？→ type / press
├─ 需要从下拉框中选择值？→ select <ref> <value>
├─ 需要悬停、拖拽、滚动，或直接使用鼠标？→ hover / drag / scroll / mouse*
├─ 需要在下一步前等待页面稳定？
│  ├─ 等元素出现？→ wait <ref|selector>
│  ├─ 等文本出现？→ wait --text "..."
│  ├─ 等 URL 变化？→ wait --url "**/target"
│  └─ 等加载 / 网络请求完成？→ wait --load networkidle
├─ 需要确

…(truncated)