Webwright 浏览器编程代理
让编程模型用 Python 脚本完成并复现长流程网页任务。
README清楚说明浏览器、终端、本地工作区、截图、日志、轨迹以及模型后端之间的主要数据流，运行产物也便于事后检查；Credits、Citation、MIT版权声明和已验证的微软组织归属使来源归因充分。扣分在于：自由形式Playwright脚本具有广泛网页操作能力，未见域名或动作级最小权限控制；普通运行没有明确的提交、购买、发送或账户变更前确认机制，只有Skill Factory的assume_yes和草稿复核证据；API密钥仅说明通过环境变量提供，未展示脱敏、日志过滤、保存期限或秘密泄漏防护；依赖采用无上限的最低版本约束，未见锁文件、漏洞扫描或依赖更新策略；外部副作用、撤销和恢复语义未系统定义，保留脚本和产物只能提供有限审计与重跑能力。
README中的架构、命令、配置和产物描述总体一致，测试还专门约束README配置键与实现、配置优先级、恢复检测、CLI兼容和防覆盖行为，因此自洽性较强。依赖均为常见公开Python包并注明Python和Chromium前置条件，但版本未锁定且浏览器、网站和模型API均是运行时外部依赖。测试展示缺失模板值、无参数运行、无效规范、已有文件和部分失败路径的信息处理，不过提供的测试集中在Skill Factory，未证明核心浏览器循环的错误消息覆盖，因此未给满分。
资料明确覆盖独立CLI、Claude Code、Codex、OpenClaw和Hermes，并区分一次性脚本、可参数化工具、Task Showcase及Skill Factory，受众与场景说明很完整。边界方面明确说明没有多代理、图引擎、插件层或隐藏编排，也列出所需浏览器、模型后端及不同宿主的行为差异；但对登录、验证码、下载、支付、受限站点和危险写操作等能力边界说明不足。自然语言自动激活、显式命令和配置叠加均有说明，但自动触发描述较宽泛，缺少误触发或冲突处理规则。Python 3.10+、Playwright Chromium、三种模型后端及多宿主安装路径使环境适配证据充分。
README具有清晰的项目地图、快速开始、参数表、插件安装、使用方式、轨迹查看器和专题章节，信息架构与安装说明完整。包名、CLI入口、配置名和插件命令总体稳定，并有测试防止文档与实现漂移；但项目仍标为0.1.0，且多个宿主存在不同调用约定。示例丰富，也说明了report.json条件生成、插件重启、Hermes命令限制和结果可能变化等注意事项，但没有独立FAQ或系统化限制清单。MIT许可证文本完整。News提供带日期的变更摘要，但未见正式CHANGELOG、发布兼容政策或迁移指南。微软组织、版权与安全报告渠道使责任和升级路径部分明确，但未列维护者、支持承诺或响应时限。
每次运行输出可重跑的Python脚本、轨迹、截图和结构化报告，Skill Factory还提供参数化CLI入口及帮助文本，输出可用性证据充分。代码即动作、可复用技能和多宿主集成相较逐步浏览具有明确的潜在增量价值，但主要性能优势来自README中的项目自述，所给文件没有完整基准数据或核心端到端测试。成本收益有令牌统计、约40秒零令牌复用和减少步骤的说明，也诚实提示单次结果会变化；不过未给模型调用总成本、浏览器资源、安全审查成本或广泛场景下的权衡，因此只属中等支持。
性能数字注明基准名称、任务数、模型、步数预算和比较对象，并指向博客；代码结构、命令和Skill Factory行为可追溯到列出的路径和测试。不过源材料未包含博客内容、原始结果、评测脚本或完整核心实现，SOTA与准确率主张无法在本次静态材料中闭环验证。README与pyproject、许可证、工作流及测试在安装、命名、配置和部分Skill Factory行为上相互印证，但性能主张主要是单一项目来源。事实、架构观点和宣传性结论大多通过章节与措辞区分，并明确称个别结果可能变化；然而“verified”“SOTA”等强结论未在所给证据中逐项附带可核查材料，因而扣分。
- Webwright允许模型生成并执行自由形式Playwright代码；在真实账户、支付、发布、发送或删除场景中，应在外部增加域名白名单、动作限制和提交前人工确认。
- 不要把轨迹和截图当作安全边界：它们可能包含页面内容、账户信息或其他敏感数据，应限制访问、设置保留期限并验证日志脱敏。
- 依赖只有最低版本约束且未展示锁文件或漏洞扫描；部署前应固定并审计Python与浏览器依赖。
- README中的SOTA、准确率和零令牌复用数字未由本提示所含的原始评测材料独立验证。
- 本评估仅基于所给静态文件，未执行代理、浏览器、测试或基准。
这个 Agent 能做什么，适合哪些场景？
Webwright 是一个轻量级浏览器代理框架，让模型在终端中编写、运行和修复 Playwright Python 脚本，而不是逐次预测点击或坐标。其核心包括 `agents/default.py` 中的代理循环、Playwright 浏览器环境、OpenAI/Anthropic/OpenRouter 模型后端、Typer CLI，以及 `image_qa` 和 `self_reflection` 工具。浏览器会话可以随时重建，持久状态则保存在本地工作区的代码、日志、轨迹和截图中。每项任务最终收敛为可重新运行的 `final_script.py`；Task Showcase 配置还可生成 `task.json` 和结构化的 `report.json`。Skill Factory 能将成功脚本提炼为经过输入校验和独立回放验证的参数化技能，并在后续任务中直接运行或作为先验注入。它适合愿意提供 Python、Chromium、网络访问、文件系统和模型凭据，并重视可审查脚本而非托管式无代码体验的团队。
用户通过 python -m webwright.run.cli 提交任务、起始网址、配置文件和输出目录。agents/default.py 执行扁平的“提示→观察→执行脚本”循环：模型在终端工作区中生成 Python，浏览器环境启动一个或多个 Playwright/Chromium 会话，脚本查询元素、等待页面条件、填写表单或遍历多步流程，并在需要时保存页面状态和截图。失败时，代理检查日志或截图并修改代码，直到形成可重跑的最终脚本；普通运行写出 trajectory.json 等调试产物，叠加 task_showcase.yaml 后还会生成 task.json 与 report.json。webwright.skill_factory 的 recommend、route、learn、build 和 update 流程可复用、提炼和回归验证既有脚本。仓库还提供 Claude Code、Codex、OpenClaw 和 Hermes Agent 的插件或技能接入方式，以及用于比较 Webwright、Codex 和 GitHub Copilot 轨迹的浏览器查看器。
- 自动化工程师需要把跨多个页面的搜索、筛选、表单填写或信息收集任务沉淀为可重复运行的 Playwright Python 程序。
- 研究浏览器代理的团队希望在 Online-Mind2Web 或 Odysseys 一类长流程任务上试验代码即动作范式，并检查完整轨迹与截图。
- 使用 Claude Code 或 Codex 的开发者希望通过插件，让现有编码代理原生驱动浏览器任务，而不另建多代理编排层。
- 运营或数据团队需要定期执行商品、库存、职位、天气等网页任务，并通过 Task Showcase 将结构化结果渲染成简单仪表盘。
- 拥有重复网站任务的团队希望用 Skill Factory 把成功运行提炼为参数化 CLI 技能，后续在不调用模型的情况下独立执行。
- 框架作者需要一个约 1.5k 行、依赖较少且代理循环可直接阅读和修改的浏览器代理起点。
这个 Agent 有哪些优点和局限？
- 代码即动作：最终浏览历史是一份可重跑、可修改和可共享的 Python 脚本，而不是只能依赖存活浏览器会话的动作序列。
- 架构精简且可审查：核心代理循环约 450 行，浏览器环境约 570 行，CLI 约 150 行，并明确避免图引擎、插件层和隐藏编排。
- 支持 OpenAI、Anthropic 和 OpenRouter 后端；同一技能目录还明确接入 Claude Code、Codex、OpenClaw 和 Hermes Agent。
- 运行产物优先：轨迹、截图和日志写入磁盘，便于复盘失败、比较不同执行框架并调试长流程任务。
- Skill Factory 可把成功任务变为经过双重验证的参数化程序；来源给出的 WebArena 实验中，复用将留出集准确率从 55% 提升到 70%。
- 来源报告其在 100 步预算下于 Online-Mind2Web 达到 86.7%，并在 Odysseys 达到 60.1%，对长流程网页任务提供了具体基准证据。
- 自托管运行需要 Python 3.10+、Playwright、Chromium、网络和可写工作区；这些运行时与浏览器依赖会增加部署和维护成本。
- 独立框架模式需要所选模型后端的 API 密钥，并会产生相应模型调用成本；只有宿主插件模式声明无需宿主订阅之外的额外模型密钥或费用。
- 最终脚本依赖具体网站的页面结构和动态行为；虽然可等待条件并修复代码，网站改版仍可能使已有自动化失效。
- Task Showcase 的
report.json不是普通运行默认产物，必须显式叠加task_showcase.yaml，仪表盘还需要另行安装 Flask。 - 来源展示的是特定模型、任务集和步数预算下的结果，不能据此保证在任意网站、权限环境或业务流程中获得相同成功率。
- 框架刻意不提供多代理系统、图引擎或隐藏编排；需要复杂审批、分布式调度或企业级工作流治理的团队必须自行扩展。
如何安装或部署这个 Agent？
要求 Python 3.10+、可联网的运行环境、文件系统、Playwright Chromium，以及所选后端的 API 密钥。克隆仓库并在仓库根目录执行：
pip install -e .
playwright install chromium使用 OpenAI 配置时设置 OPENAI_API_KEY；使用 Anthropic 配置时设置 ANTHROPIC_API_KEY。框架也提供 OpenRouter 后端，但所给快速开始示例没有列出其凭据变量。Claude Code 可先执行 /plugin marketplace add microsoft/Webwright，再执行 /plugin install webwright@webwright 并重启会话。Codex CLI 可执行 codex plugin marketplace add microsoft/Webwright，随后进入 codex、打开 /plugins 安装 Webwright，并重启 Codex。
如何使用这个 Agent？
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-c 可叠加 src/webwright/config/ 中的配置，-t 是任务说明，--start-url 指定初始页面，--task-id 指定输出子目录，-o 指定输出根目录。若要生成可由 Task Showcase 渲染的结构化结果，额外叠加 -c task_showcase.yaml；随后可运行 python assets/task_showcase/app.py --tasks-dir outputs/default/<run>/task_showcase/tasks。在 Claude Code 中可使用 /webwright:run <任务> 生成一次性脚本，或 /webwright:craft <任务> 生成带 argparse 参数的可复用 CLI。Codex 新线程中可输入 @webwright <任务>。
这个 Agent 与同类方案有什么区别？
相较 Stagehand，Webwright 不以自然语言 act/extract 原语或混合式接口为中心，而让模型自由编写 Playwright Python。相较 Vercel 的 agent-browser，它不要求代理为每个微步骤调用 open、click 或 snapshot 子命令，而是组合成完整程序。相较 browser-use 的 DOM/AX 快照与索引化点击循环，Webwright 把本地代码、截图和日志视为状态，并允许浏览器会话被丢弃和重建。README 还给出了基准对照：在 Odysseys 上，GPT-5.4 Webwright 为 60.1%，高于所列视觉持久浏览器方案 Opus 4.6 的 44.5%和基础 GPT-5.4 坐标预测方案的 33.5%；这些数字仅对应来源注明的评测设置。
常见问题
必须使用 OpenAI 模型吗？
image_qa 和 self_reflection 默认使用同一模型，不要求额外的 OpenAI 密钥。每次运行都会生成结构化报告吗？
base.yaml 运行生成 trajectory.json 和调试产物，但不生成 report.json；必须叠加 task_showcase.yaml 才会写出可供仪表盘渲染的任务与报告文件。