wehub/microsoft--webwright

Fork 0

Files

T

wehub-resource-sync 5edad4431d docs: make Chinese README the default

2026-07-13 10:18:32 +00:00

19 KiB

Raw Permalink Blame History

Note

本文档由 WeHub 基于上游 README 翻译整理，属于社区翻译，非官方中文文档。
English · 原始项目 · 上游 README
原作者、版权与许可证归属以原始项目及本仓库 LICENSE 文件为准。

Webwright

让你的编程模型成为一流的浏览器智能体（Browser Agent）

📝 Blog： Webwright: A Terminal Is All You Need For Web Agents
🌐 项目主页： microsoft.github.io/Webwright

Webwright 为 LLM 提供一个终端，使其能够启动多个浏览器会话来检查页面并完成 Web 任务。它仅在需要时捕获并检查页面截图/状态。它要求每个 Web 任务都必须在可重复运行的 Python 脚本中端到端完成——也就是说，你的 Web 智能体浏览历史就是单个代码文件。没有多智能体系统、没有图引擎、没有插件层、没有隐藏的编排——只有终端、浏览器和模型。

已有自己喜爱的智能体，想知道如何让 Claude Code、Codex、Hermes、OpenClaw 在浏览器任务中更强？可以考虑添加 Webwright 插件/技能！

📰 新闻

2026-05-11 — 支持 Task2UI 模式：Webwright 完成任务后将任务结果渲染为基于 HTML 的 Web 应用，便于查看和复用。
2026-05-06 — 新增 Codex 与 Claude Code 插件清单；可通过 /plugin install webwright@webwright 安装。已交付 OpenClaw 与 Hermes Agent 集成；同一 skills/webwright/ 文件夹现可在 Claude Code、Codex、OpenClaw 和 Hermes 中加载。
2026-05-04 — 首次公开发布：约 1.5k 行代码，支持 OpenAI / Anthropic / OpenRouter 后端与 Playwright 环境。

💡 动机：超越有状态浏览器中的逐步 Web 交互

当今大多数 Web 智能体将浏览器会话本身视为工作区：每一步模型接收当前页面状态并预测单个下一步操作——点击、输入、DOM 选择器或简短的工具调用。无论格式如何，智能体都被锁定在预定义交互循环内一次预测一个 Web 操作。当 LLM 较弱时，这种框架很有用；随着模型在编写和调试代码方面越来越强，同样的框架反而成为瓶颈。

Webwright 采取不同立场：将智能体与浏览器分离，把浏览器视为智能体在开发程序时可以启动、检查并丢弃的对象。持久化产物不是浏览器会话——而是本地工作区中的代码和日志。

🧱 与 Web 环境进行稳健、可复用的交互 — 编程智能体通过终端查询元素、等待条件，并处理懒加载或重新渲染等动态行为，而非脆弱的像素级操作。生成的脚本可重新运行、适配并在任务间共享，而不必从头摸索。
⚡ 高效组合复杂工作流 — 选择日期或填写表单等多步交互可变成紧凑程序。循环、函数和抽象让智能体在相似任务（如不同日期）间泛化，而无需重复预测相同的底层序列。更少交互轮次、更快执行、长程任务中更少错误累积。
🧪 工作区即状态，而非浏览器即状态 — 智能体可编写探索性脚本、启动全新浏览器会话，并自行决定何时捕获截图和检查失败，类似人类工程师迭代 RPA 脚本。
🪄 极简却出人意料地有效 — 这种精简配置在处理复杂且尤其长程的 Web 任务时表现良好（见性能）。

🌟 为什么选择 Webwright

大多数 Web 智能体框架将实际智能体循环埋在层层抽象之下。Webwright 采取相反立场：

🪶 设计上轻量 — 核心智能体循环在单个约 450 行的文件中，Playwright 环境约 570 行，CLI 约 150 行。
🧩 可插拔的模型后端 — OpenAI、Anthropic 和 OpenRouter，各约 150–200 行。
🔍 零隐藏框架 — 只有 httpx、pydantic、playwright 和 typer。
🔁 扁平的 prompt → observe → execute script 循环 — 端到端可读、易于调试、易于 fork。
🧪 运行产物优先 — 每次运行都将轨迹和截图写入磁盘以供检查。

如果你想要一个极简、易于调试的浏览器智能体起点，而不是又一个重量级平台，这就是它。

🆚 Webwright 与其他浏览器智能体仓库的区别

架构层面的差异：

	Stagehand (Browserbase)	agent-browser (Vercel)	browser-use	Webwright
范式	混合：代码 + 自然语言原语（`act` / `extract` / `agent`）	供其他智能体（Claude Code、Codex 等）调用的 CLI 工具	基于 DOM/AX 快照的自主 LLM 智能体循环	带终端的编程智能体；浏览器只是其启动的环境
动作空间	Playwright 代码，或自然语言 → LLM 翻译的 Playwright	离散子命令（`open`、`click @e2`、`snapshot`、`eval`）	由 LLM 选择的索引化点击/输入操作	自由形式 Python（自行编写 Playwright 脚本）
何为「状态」？	浏览器会话	浏览器会话（由守护进程在多次 CLI 调用间保持）	浏览器会话	本地工作区——代码、截图、日志。浏览器可丢弃。
循环形态	命令式；`agent()` 在需要时执行多步	每个微步骤一次 CLI 调用	observe → predict next action → execute → repeat	编写代码 → 执行 → 检查截图 → 修复（code-as-action）

🎥 演示

https://github.com/user-attachments/assets/4ed94cd5-11be-4daa-b2d7-1260a803baca

📊 性能

在两个真实网站基准测试上以 100 步预算达到一流水平——详见博客文章。

🏆 Online-Mind2Web（300 项任务）： 使用 GPT-5.4 达到 86.7% — AutoEval 类别中开源框架最高。Claude Opus 4.7 达到 84.7%，在困难子集上更强（80.5% vs. GPT-5.4 在 N=100 时的 76.6%）。
🚀 Odysseys（200 项长程任务）： 使用 GPT-5.4（平均 76.1 步）达到 60.1% — 较先前 SOTA（Opus 4.6 为 44.5%，采用基于视觉的方法与持久化浏览器）+15.6 个百分点，较基础 GPT-5.4（33.5%，采用 xy 坐标预测与持久化浏览器）+26.6 个百分点。
🧠 Code-as-action 优于坐标预测： Webwright 在所有难度子集上均大幅优于复现的 GPT-5.4 截图+xy 坐标基线。
🧰 小模型 + 可复用工具： 生成的脚本可打包为参数化 CLI 工具 — 即便 Qwen-3.5-9B 在 Online-Mind2Web 站点上、有 5+ 个可用工具时也能很好地完成任务。

🗺️ 项目地图

webwright/
├── pyproject.toml           # package: webwright
├── src/webwright/
│   ├── run/cli.py           # CLI entrypoint (`webwright`)
│   ├── agents/default.py    # core agent loop
│   ├── environments/        # Playwright browser workspace
│   ├── tools/               # image_qa, self_reflection
│   ├── models/              # openai_model, anthropic_model, base
│   ├── config/              # base.yaml, model_openai.yaml, model_claude.yaml
│   └── utils/
├── assets/
│   └── task_showcase/       # tiny Flask dashboard for repeatable runs
│       ├── app.py
│       ├── templates/       # dashboard.html, task.html
│       └── tasks/<short_id>/ # task.json + report.json per task
├── tests/
└── outputs/                 # run artifacts (trajectories, screenshots)

📰 任务展示（可重复运行，仪表板形式）

位于 assets/task_showcase/ 下的小型 Flask 应用将针对可重复 odyssey 任务（优惠、库存、列表、招聘板、天气等）的 Webwright 运行结果汇总到单一仪表板中。每个任务仅包含两个文件 — task.json（元数据）和 report.json（精心整理的结构化输出：来源 + 表格、列表、摘要等结果区块）— 模板以通用方式渲染它们，因此添加新任务只需在 assets/task_showcase/tasks/ 中放入一个新文件夹即可。

pip install flask
python assets/task_showcase/app.py    # http://127.0.0.1:5005

若要在运行时让 Webwright 生成可供渲染器使用的任务文件夹，请叠加 Task Showcase 覆盖层：

python -m webwright.run.cli \
    -c base.yaml -c model_openai.yaml -c task_showcase.yaml \
    -t "<repeatable web task>" \
    --task-id my_repeatable_task \
    -o outputs/default

注意： 仅当包含 -c task_showcase.yaml 时才会生成 report.json。普通的 base.yaml 运行会产生 trajectory.json 和调试产物，但不会生成 report.json。

运行会在输出工作区内写入 task_showcase/tasks/<short_id>/task.json 和 report.json。直接渲染这些生成的文件，无需将它们复制回仓库：

python assets/task_showcase/app.py \
    --tasks-dir outputs/default/<run>/task_showcase/tasks

🚀 快速开始

前置条件

Python 3.10+
通过 Playwright 安装的 Chromium
所选后端（OpenAI、Anthropic 或 OpenRouter）的 API 密钥

安装

pip install -e .
playwright install chromium

运行

为已配置的后端导出凭据（例如，OPENAI_API_KEY 配合 model_openai.yaml，或 ANTHROPIC_API_KEY 配合 model_claude.yaml）。默认情况下， image_qa 和 self_reflection 工具使用同一已配置模型，因此使用 Anthropic 运行无需 OpenAI 密钥。然后：

python -m webwright.run.cli \
    -c base.yaml -c model_openai.yaml \
    -t "Search for flights from SEA to JFK on 2026-08-15 to 2026-08-20" \
    --start-url https://www.google.com/flights \
    --task-id demo_openai \
    -o outputs/default

🚩 标志

Flag	说明
`-c`	来自 `src/webwright/config/` 的配置文件（可叠加）。
`-t`	任务指令。
`--start-url`	初始页面。
`--task-id`	输出子文件夹名称。
`-o`	输出目录。

🔌 作为插件使用

Webwright 为 Claude Code (.claude-plugin/plugin.json) 和 OpenAI Codex (.codex-plugin/plugin.json) 均提供了插件清单，共享技能位于 skills/webwright/，斜杠命令位于 skills/webwright/commands/。宿主智能体以原生方式驱动 Webwright 循环 — 除宿主订阅费用外，无需额外的 LLM API 密钥或成本。原生支持读取 PNG 截图的宿主会跳过 image_qa / self_reflection 工具。

通用运行时依赖（任选一种安装路径后安装一次即可）：

pip install -e .
playwright install chromium

Claude Code

安装

通过 Claude Code 内置的市场安装：

# 1. Add this repo as a Claude Code plugin marketplace
/plugin marketplace add microsoft/Webwright

# 2. Install the plugin from that marketplace
/plugin install webwright@webwright

更倾向于使用本地检出？将市场命令指向克隆的仓库即可：

/plugin marketplace add /absolute/path/to/Webwright
/plugin install webwright@webwright

使用

安装后启动新的 Claude Code 会话 — 插件在会话开始时加载，重启前不会出现。

你可以用自然语言向 Claude Code 提问（技能会根据其描述自动激活），或使用其中一个斜杠命令：

/webwright:run search Google Flights for flights from SEA to JFK on 2026-08-15 to 2026-08-20
/webwright:craft search a ticket on Google Flights from LAX to SFO depart June 7 return June 14

/webwright:run（或任意普通提示）会为字面任务值生成一次性 final_script.py。
/webwright:craft 会生成可复用的 CLI 工具：final_script.py 变成一个参数化函数，带有 Google 风格的 Args: docstring 和 argparse 包装器，其标志默认为具体任务值，因此你可以稍后使用不同参数重新运行 — 例如 python final_script.py --origin JFK --destination LAX --depart-date 2026-07-01。

在两种模式下，Claude Code 都会使用 plan.md 搭建工作区，在 final_runs/run_<id>/ 下运行插桩的 Playwright 脚本，并针对保存的截图对每个关键点进行可视化自检。

OpenAI Codex

安装

Codex 可读取 Claude 风格的市场，因此同一仓库可作为 Codex 插件市场使用。在 Codex CLI 中：

# 1. Add this repo as a Codex plugin marketplace
codex plugin marketplace add microsoft/Webwright

# 2. Open the plugin browser and install Webwright
codex
/plugins

更倾向于使用本地检出？

codex plugin marketplace add /absolute/path/to/Webwright

然后重启 Codex，以加载新的市场和插件。

使用

在新的 Codex 线程中，可以用自然语言提问（技能会根据其描述自动激活），或使用 @webwright 显式调用内置技能：

@webwright search Google Flights for flights from SEA to JFK on 2026-08-15 to 2026-08-20

Codex 会使用 plan.md 搭建工作区，在 final_runs/run_<id>/ 下运行插桩的 Playwright 脚本，并针对保存的截图对每个关键点进行可视化自检。

若要在不卸载的情况下关闭插件，请将其在 ~/.codex/config.toml 中的条目设为 enabled = false 并重启 Codex。

🦞 OpenClaw

安装

直接从本地检出安装（路径、压缩包、npm spec、git 仓库或 clawhub: spec 均可）：

openclaw plugins install /absolute/path/to/Webwright
openclaw gateway restart   # reload so the plugin and skill are picked up

验证：

openclaw plugins list | grep webwright
openclaw skills  list | grep webwright   # should show "✓ ready"

使用

webwright 技能现可在任意 OpenClaw 智能体界面（CLI、Telegram 等）上使用 — 可通过自然语言向智能体提问，或通过 skills/webwright/commands/ 下附带的斜杠命令调用，例如 /webwright run <task>。

卸载：openclaw plugins uninstall webwright。

Hermes Agent

安装

Hermes Agent 是一款 skills-compatible client,，因此同一 skills/webwright/ 文件夹可作为 Hermes 技能加载。请将其符号链接到你的 Hermes 用户技能目录：

mkdir -p ~/.hermes/skills
ln -sfn /absolute/path/to/Webwright/skills/webwright ~/.hermes/skills/webwright

无需 Hermes 专用 manifest；仅加载 SKILL.md。

用法

启动 Hermes（hermes），用自然语言让它驱动一项 Web 任务——技能会根据其描述自动激活。你也可以通过 /webwright 显式调用。

注意：skills/webwright/commands/ 下提供的命名子命令（/webwright:run、/webwright:craft）属于 Claude Code / Codex 约定，在 Hermes 中不起作用；技能本身仍可端到端运行。

📃 轨迹对比与查看器

你可以使用 Webwright harness 及其 Codex / GitHub Copilot 技能变体运行相同任务，并比较不同 harness 之间的 token 用量与轨迹。轨迹查看器支持 Codex、GitHub Copilot 和 Webwright harness 的轨迹。

使用方法

cd assets/compare_trajectory/
python3 -m http.server

在浏览器中打开该网页，上传 Webwright 的 raw_responses.jsonl，并附加 trajectory.json 以查看。随后在另一侧上传你的 Codex 或 GitHub Copilot 轨迹。

获取 Codex 轨迹：

ls ~/.codex/sessions/2026/MONTH/DAY/SESSION_ID.jsonl

获取 GitHub Copilot 轨迹：

/export file session
-> session.md is the uploadable trace

快速对比

"查找 2005–2015 年间制造、售价 25,000 至 50,000 美元、里程不超过 50,000 英里的最便宜二手 8 缸 BMW。"

Tokens	Webwright Harness（本地浏览器模式）	Codex Webwright Skill
输入	420,433	3,271,143
输出	3,593	20,040
推理	0	4,410
缓存	217,216	3,081,3440
总计	424,026	3,291,183

单次运行及结果可能有所不同。

致谢

SWE-agent/mini-swe-agent — 极简 agent 循环的设计灵感。
Playwright — 浏览器自动化。

引用

若你在研究中使用 Webwright 或在其基础上进行开发，请引用本仓库：

@misc{webwright2026,
  title        = {Webwright: A terminal is all you need for web agents},
  author       = {Lu, Yadong and Xu, Lingrui and Huang, Chao and Awadallah, Ahmed},
  year         = {2026},
  howpublished = {\url{https://github.com/microsoft/Webwright}},
  note         = {GitHub repository}
}

19 KiB Raw Permalink Blame History Unescape Escape