> [!NOTE]
> 本文档由 WeHub 基于上游 README 翻译整理，属于社区翻译，非官方中文文档。
> [English](./README.en.md) · [原始项目](https://github.com/browser-use/browser-harness) · [上游 README](https://github.com/browser-use/browser-harness/blob/HEAD/README.md)
> 原作者、版权与许可证归属以原始项目及本仓库 LICENSE 文件为准。
# Browser Harness ♞
通过轻量、可编辑的 CDP（Chrome DevTools Protocol）harness，将 LLM 直接连接到真实浏览器。适用于需要**完全自主**的浏览器任务。
一条 WebSocket 直连 Chrome，中间无额外层。代理在运行过程中补写缺失部分，harness 在每次运行后自我改进。
在 [Browser Use Cloud](https://cloud.browser-use.com/v4?utm_campaign=browser-harness-use-in-cloud&utm_source=github) 试用 browser-harness，或将设置提示词粘贴到你的编程 agent 中。
```
● agent: wants to upload a file
│
● agent-workspace/agent_helpers.py → helper missing
│
● agent writes it agent_helpers.py
│ + custom helper
✓ file uploaded
```
**你将再也不想亲手操作浏览器了。**
## 设置提示词
粘贴到 Claude Code 或 Codex 中：
```text
Install or upgrade browser-harness to the latest stable version with uv using Python 3.12, register the skill from `browser-harness skill`, and connect it to my browser. Follow https://github.com/browser-use/browser-harness/blob/main/install.md if setup or connection fails.
```
代理会打开 `chrome://inspect/#remote-debugging`。勾选复选框，以便代理连接到你的浏览器：
当出现每次附加时的弹出窗口时点击 Allow（Chrome 144+）：
查看 [agent-workspace/domain-skills/](agent-workspace/domain-skills/) 获取示例任务。
## 免费的 Browser Use Cloud 浏览器
隐身模式、子 agent 或无头部署。
**Browser Use Cloud 免费层：3 个并发浏览器、代理、captcha 破解等。无需信用卡。**
- 在 [cloud.browser-use.com/new-api-key](https://cloud.browser-use.com/new-api-key) 获取密钥
- 或让 agent 通过 [docs.browser-use.com/llms.txt](https://docs.browser-use.com/llms.txt) 自行注册（包含设置流程与挑战上下文）。
## 架构（4 个核心文件约 1k 行）
- `install.md` — 首次安装与浏览器引导
- `SKILL.md` — 日常使用
- `src/browser_harness/` — 受保护的核心包
- `${XDG_CONFIG_HOME:-~/.config}/browser-harness/agent-workspace/agent_helpers.py` — 由 agent 编辑的辅助代码
- `${XDG_CONFIG_HOME:-~/.config}/browser-harness/agent-workspace/domain-skills/` — 由 agent 编辑的可复用站点专属技能
普通的 `browser-harness` 辅助调用会附加到正在运行的 Chrome/Chromium CDP 端点。如需隔离式自动化，请自行使用 `--remote-debugging-port` 启动 Chrome 并传入 `BU_CDP_URL`，或使用 Browser Use 云浏览器。
## 开发
从 checkout 出发，使用 `./browser-harness` 运行当前工作树，无需激活 virtualenv 或依赖全局安装的命令：
```bash
./browser-harness <<'PY'
print(page_info())
PY
```
面向 agent 的常规文档应继续使用 `browser-harness`；`./browser-harness` 启动器仅用于本地仓库测试。
## 贡献
欢迎 PR 与改进。最佳帮助方式：在 [agent-workspace/domain-skills/](agent-workspace/domain-skills/) 下**贡献新的 domain skill**，针对你常用的站点或任务（LinkedIn 外联、Amazon 下单、报销等）。每个 skill 会教会 agent 选择器、流程与边界情况，否则它需要重新摸索。
- **Skill 由 harness 编写，而非由你手写。** 只需用 agent 运行你的任务——当它弄清某些非显而易见之事，会自行归档 skill（见 [SKILL.md](SKILL.md)）。请勿手写 skill 文件；agent 生成的才反映浏览器中真正有效的做法。
- 将生成的 `domain-skills//` 文件夹复制到本仓库的 `agent-workspace/domain-skills/` 示例中并开启 PR——小而聚焦最佳。
- Bug 修复、文档微调与辅助代码改进同样欢迎。
- 浏览现有 skill（`github/`、`linkedin/`、`amazon/`、...）了解其形态。
若不确定从哪入手，请开 issue，我们会指引你有用之处。
## Domain skills（领域技能）
设置 `BH_DOMAIN_SKILLS=1` 以启用来自 agent workspace 的 domain skill。本仓库的 [agent-workspace/domain-skills/](agent-workspace/domain-skills/) 目录包含可通过 PR 贡献的示例。
---
[The Bitter Lesson of Agent Harnesses](https://browser-use.com/posts/bitter-lesson-agent-harnesses) · [Web Agents That Actually Learn](https://browser-use.com/posts/web-agents-that-actually-learn)