人工智能AI Agent浏览器控制代码智能体【免费下载链接】CUAWrightA simple SWE style browserdesktop agent framework that achieves SOTA results on long horizon web tasks.项目地址https://gitcode.com/gh_mirrors/web/CUAWright点击查看免费下载本文基于cuawright-web技能中的 CLI 工具模式CLI tool mode命令 craft.md系统讲解如何把一次性的网页自动化任务搜索、筛选、表单填写、多步流程、数据抽取抽象为一个可反复调用的参数化final_script.py包括参数识别、# Parameters规划表、Google 风格 docstring 的可复用函数、argparseCLI 包装、导入安全import-safety与无参复现验证。读完本文你将掌握在 CUAWright 框架内从跑通一次到交付一个可持续复用的命令行工具的完整方法并能对照仓库源码理解其底层契约。一、两种模式的分工one-shot 与 CLI tool在cuawright-web技能总纲见 SKILL.md中Webwright 的浏览器自动化产出物都是final_script.py但根据使用意图分成两种模式默认一次性模式one-shot由普通提示词或/cuawright:run task触发见 run.md。final_script.py只针对用户给出的字面值完成任务跑完即止。CLI 工具模式CLI tool mode由/cuawright:craft task触发或当用户提出make it reusableparameterizeturn this into a CLII want to call this again with different X等意图时自动激活。此时final_script.py是一个可复用的参数化 CLI 工具同一个脚本可以在之后用不同的参数值重复运行完成同一类任务。完整契约见 cli_tool_mode.md。该契约源自仓库中 crafted_cli.yaml 的 Final-Script Shape (CLI Tool, MANDATORY) 章节并做了本地化改造原本依赖 OpenAI 的image_qa与self_reflection门控被替换为 Agent 自己对plan.md关键点Critical Points的逐一核对全程无需任何模型 API Key。二、一次性环境准备从 CUAWright 仓库根目录执行见 SKILL.md 的 Prerequisites 一节pip install -e . playwright install firefox本技能不需要任何 API Key浏览器为本地 Playwright Firefox视觉验证由 Agent 直接用Read读取 PNG 截图完成。浏览器引擎选择 Firefox 而非 Chromium 是有原因的部分站点如 cars.com 等 Akamai 防护站点在 Playwright Chromium 下会因 TLS/H2 指纹问题报ERR_HTTP2_PROTOCOL_ERROR而 Firefox 可以正常加载依据 playwright_patterns.md。不要额外pip/apt安装任何包playwright、httpx、pydantic等依赖已预装SKILL.md 的 Hard Rules。三、第一步识别参数划定可变与固定的边界craft的起点是 craft.md 的第 1 步提取用户可能变动的每一个需求点。可参数化的候选包括搜索关键词search terms地点locations如出发/到达机场、城市日期与时间dates筛选值filter values品牌、年份区间、价格区间、颜色等排序方式、数量、单位等一切用户下次可能换掉的输入而对站点而言真正固定的东西不是参数必须硬编码起始 URLstart URL站点名称选择器策略selector strategy以 crafted_cli.yaml 中的官方示例为例Search for a red Toyota Corolla from 2018 to 2023 on CarMax可参数化为Make、Model、min_year、max_year、color五个参数而 CarMax 的入口 URL 与页面选择策略保持硬编码。仓库中真实的飞行任务轨迹也印证了这一分工在 lax_ord/final_script.py 中Google Flights 的启动 URL 与get_by_role选择器全部写死而航线、日期等作为输入。四、第二步在 plan.md 中追加# Parameters参数表在写脚本之前先在plan.md中、在常规的# Critical Points清单之外增加# Parameters表格这是 CLI 模式的硬性要求cli_tool_mode.md# Task verbatim task description # Parameters | name | type | source phrase from task | default | allowed / format | |---------|------|-------------------------|-------------|-------------------------| | arg_a | str | ... | value | format / allowed set | | arg_b | int | ... | value | range or units | | arg_c | str | ... | value | format | # Critical Points - [ ] CP1: ... - [ ] CP2: ...参数表规则三条缺一不可# Parameters中每一行都必须同时成为a可复用函数的参数和bargparse的一个--flag且默认值使用表中列出的 default。真正固定于站点的项起始 URL、站点名、选择器策略不列入参数表保持硬编码。默认值必须精确复现原任务python final_script.py不带任何参数运行的结果必须与原任务完全一致。同时# Critical Points清单仍然保留它是对照截图/日志逐条验收的契约。每个 CP 必须能独立地从一张截图或一行日志得到验证。五、第三步final_script.py 的强制形状craft的核心产出物需要满足六项形状要求缺一不可。这里逐项展开。5.1 一个以任务领域命名的可复用函数函数名体现任务领域例如def search_domain(arg_a, arg_b, ...): ...如search_cars(Make, Model, min_year, max_year, color)def lookup_entity(query, filters): ...5.2 Google 风格 docstringdocstring 必须包含摘要、完整的Args:块和Returns:。每个Args:条目要说明参数名与类型、在任务领域中的含义、可接受的格式/单位/取值范围、默认值与# Parameters表保持一致def search_domain(arg_a: str, arg_b: int, arg_c: str) - dict: One-line summary of what this tool does on the target site. Args: arg_a: what it represents; format / allowed values. Default: value. arg_b: what it represents; range / units. Default: value. arg_c: what it represents; format. Default: value. Returns: dict with keys key1 (type), key2 (type), 5.3 argparse CLIflag 与函数参数一一对应在if __name__ __main__:下用argparse包装。每个函数参数都有对应的--argflagtype与 docstring 一致help直接取自 docstringdefault等于原任务的具体值if __name__ __main__: import argparse parser argparse.ArgumentParser( descriptionsearch_domain.__doc__.splitlines()[0]) parser.add_argument(--arg-a, destarg_a, typestr, defaultvalue, helpcopied from docstring) parser.add_argument(--arg-b, destarg_b, typeint, defaultvalue, helpcopied from docstring) parser.add_argument(--arg-c, destarg_c, typestr, defaultvalue, helpcopied from docstring) args parser.parse_args() result asyncio.run(_run(**vars(args))) print(result)注意dest将--arg-a映射回arg_a保证 CLI 参数名与函数签名严格对齐这正是 crafted_cli.yaml 中 Every function argument MUST have a matching--argflag 的实现方式。5.4 导入时零副作用side-effect-free at import time模块顶层不得启动浏览器、发起网络请求或写文件。可复用函数必须可以被另一个 Python 进程 import 而不触发任何运行——真正的执行只发生在if __name__ __main__:之下。这是为了支持后续的导入安全冒烟测试以及把该函数作为库被其他程序引用。5.5 动作日志的第一行必须是step 0 params: ...日志重置后写入的第一行必须列出全部解析后的参数格式为namevalue对例如step 0 params: arg_avalue arg_bvalue arg_cvalue这样任何验证环节包括外部 judge都能直接看到本次运行实际生效的输入。5.6 与默认模式相同的仪器化instrumentation仪器化要求与一次性模式完全一致playwright_patterns.md视口固定viewport{width: 1280, height: 1800}headless 本地 Firefoxplaywright.firefox.launch(headlessTrue)禁止page.screenshot(full_pageTrue)探索、调试、终跑截图一视同仁截图保存为final_runs/run_id/screenshots/final_execution_step_action.png最终数据final datum价格、代码、中选者、报价等追加写入final_script_log.txt末尾。5.7 一个真实的仪器化脚本参考仓库中 lax_ord/final_script.py 是 Google Flights最早直飞航班任务的完整执行脚本展示了核心仪器化模式RUNS WORKSPACE / final_runs RUNS.mkdir(exist_okTrue) existing [int(p.name.split(_)[-1]) for p in RUNS.glob(run_*) if p.name.split(_)[-1].isdigit()] run_id max(existing, default0) 1 RUN_DIR RUNS / frun_{run_id:03d}即每次干净执行都自动落到新的、递增的final_runs/run_id/文件夹互不覆盖随后LOG.write_text()重置日志next_step()写step n action: ...snap()以final_execution_step_action.png命名截图最后把答案写入agent_response.json并追加到日志。CLI 工具模式在其基础上把入口从写死的任务值换成argparse 解析的参数。六、第四步无参数复现原任务在全新的final_runs/run_id/目录中执行cd final_runs/run_id python final_script.py要求整条链路端到端成功并产出预期的截图与step 0 params: ...日志行。这一步验证默认值 原任务值的承诺确实成立。七、第五步导入安全冒烟测试import-safety smoke test从任意其他目录加载该模块确认不启动浏览器、不触发运行并能打印出可复用函数名cli_tool_mode.md 给出的标准命令python -c import importlib.util, pathlib; \ spec importlib.util.spec_from_file_location(fs, final_runs/run_id/final_script.py); \ m importlib.util.module_from_spec(spec); spec.loader.exec_module(m); \ print([n for n in dir(m) if not n.startswith(_)])该命令必须瞬间完成无浏览器启动并打印出可复用函数的名称证明模块可以安全地被其他代码引用。八、第六步自验证替代 self_reflectionCLI 模式的自验证在默认模式的逐条核对plan.md基础上详见 workflow.md增加了三项无参复现如上第 6 节python final_script.py在final_runs/run_id/内端到端成功。导入安全冒烟测试如上第 7 节。可选第二次运行用不同的参数值在final_runs/run_id_alt/中再跑一次用实际结果证明参数化生效仅当备选值在目标站点明确不可用时才可跳过。随后对plan.md中每个 CP在保存的截图与动作日志中找到对应证据并逐条勾选。证据必须不含歧义筛选 chip / 选中状态可见而不是藏在已关闭的抽屉里数值 / 日期精确匹配没有被放宽排序确实通过站点的控件应用而非由结果顺序推断提交 / 搜索 / 应用等必需动作被可见地执行最终数据清晰可读地展示。若任一 CP 失败定位具体问题错误的筛选值、缺失的控件、被遮挡的 chip、放宽的范围、缺失的确认、缺失的截图修复final_script.py保持 CLI 形状不变可复用函数 任务值默认值的 argparse flags在下一个final_runs/run_id1/中重跑并重新验证。空结果集在正确应用了筛选的前提下可接受。九、第七步展示--help并交付最后一步必须向用户展示python final_runs/run_id/final_script.py --help并同时报告**最终数据final datum**与--help输出让用户清楚知道以后如何用不同参数再次调用该工具。十、CLI 模式的完成门槛Completion Gate只有当以下全部为真时才能宣告任务完成cli_tool_mode.mdplan.md同时包含# Parametersname、type、source phrase、default、allowed/format与# Critical Points两份清单final_script.py定义恰好一个可复用函数Google 风格Args:docstring 覆盖每个参数# Parameters中每个条目与函数参数、argparse--flag一一对应且 flag 默认值等于原任务具体值脚本通过导入安全冒烟测试python final_script.py无参在final_runs/run_id/内复现了任务全部 CP 依据截图与动作日志验证通过final_script_log.txt中存在step 0 params: ...行用户已经看到最终数据与--help输出。任一条件不满足就不得宣告完成——应诊断、修复脚本保持 CLI 形状、在下一个run_id1/重跑并重新验证。这一修复-重跑-复验的闭环与 crafted_cli.yaml 中preserving the CLI shape — reusable function argparse flags with task-value defaults的强制要求一致。十一、底层支撑浏览器契约与表单交互要点CLI 工具模式与默认模式共享同一套浏览器契约base.yaml 中environment.browser_mode: local即为本地 Playwright 模式与 Browserbase 云会话模式二选一每次运行都是全新会话无持久浏览器状态脚本从起始 URL 开始重建全部状态交互式表单填充优先于深链 URL当任务需要参数化搜索地点、日期、筛选、查询词时应像真人一样驱动页面控件而不是把参数拼进 URL。深链的脆弱性在于站点会静默丢弃无法解析的参数、URL 解析随地区/A-B 桶/登录态变化、一个输入集下可用的深链无法证明另一输入集也能填充。正确姿势是用get_by_role/aria-label选择器避免脆弱的 CSS 类、输入后等待 suggestion listbox 再点选包含规范 token 的选项、成对字段日期范围、步进器组在同一个 modal 内打开后用 Tab 切换而不是逐一点击输入框避免被 modal 遮罩挡住、显式点击提交控件而非依赖自动提交最后重新读取表单状态逐条断言 CP1..CPn角色定位模式page.get_by_role(button, nameFilters).click()、page.get_by_role(checkbox, nameBMW).check()并对控件的父节点打印aria_snapshot()观察兄弟选项。十二、从 CLI 工具到技能库的延伸参数化的最终形态不止于单次任务的复用。仓库中 examples/README.md 展示了一条进阶路径三份从零求解的最早直飞航班轨迹SEA→JFK、SFO→BOS、LAX→ORD经过learn蒸馏为一份含5 个提升参数origin_city、origin_code、destination_city、destination_code、date的skill.py模板并在未见过的航线 SEA→DEN 上以约 10 步、约 40 秒、无需模型的方式独立运行成功meta.json中verified: true, grade: executable。这与craft共享参数化 默认值复现 可独立调用的思想但把复用单元从单个脚本升级为可检索、可路由的技能库。相关的test_learned_example.py、test_recommend.py等测试位于 tests/skill_factory 目录可作进一步参考。十三、常见踩坑清单综合 craft.md、cli_tool_mode.md 与 workflow.md 的硬规则CLI 工具模式最常出现的失败点把固定项也参数化起始 URL、站点名、选择器策略不应成为 flag否则 CLI 表面被无意义地膨胀函数参数、docstring、argparse flag 三者脱节任一参数在 docstring 或 CLI 中缺失即不满足完成门槛第 2、3 条顶层副作用模块 import 即启动浏览器或写文件冒烟测试将直接暴露日志缺step 0 params:验证环节无法确认实际生效参数默认值 ≠ 原任务值无参运行无法复现任务用搜索结果代替筛选控件站点提供专门控件时搜索框查询永远不能满足显式筛选/排序/样式/属性要求排名语言cheapest、best-selling、most reviewed、highest-rated、lowest、latest必须锚定在站点真实的排序/筛选控件上而不是自己重排结果数值/日期/数量/单位约束被放宽这些约束必须精确站点没有更精确的控件时才允许更宽泛的默认选中状态在抽屉/手风琴/弹窗/下拉关闭后被隐藏必须重新打开控件或先截取可见的 chip/摘要再认定状态已生效对声称的阻塞Access Denied、控件不可用过早放弃只有反复从真实站点 UI 取证后才允许停止。掌握上述要点后/cuawright:craft便能稳定地产出可复制、可运行、可复用、可被他人通过--help直接调用的 Webwright CLI 工具这正是 CUAWright 将浏览器自动化从一次性脚本升级为工程化资产的核心理念。赞分享人工智能AI Agent浏览器控制代码智能体【免费下载链接】CUAWrightA simple SWE style browserdesktop agent framework that achieves SOTA results on long horizon web tasks.项目地址https://gitcode.com/gh_mirrors/web/CUAWright点击查看免费下载相关推荐CUAWright CLI Tool Mode 实战指南用 /cuawright:craft 把一次性 Web 任务脚本改造成可复用、参数化的命令行工具CUAWright CLI Tool Mode 实战指南用 /cuawright:craft 把一次性 Web 任务脚本改造成可复用、参数化的命令行工具 这篇人工智能AI Agent浏览器控制代码智能体CUAWright 浏览器技能cuawright-web实战指南用单条 bash 命令驱动本地 Playwright 完成可验证的 Web 任务自动化CUAWright 浏览器技能cuawright web实战指南用单条 bash 命令驱动本地 Playwright 完成可验证的 Web 任务自动化 本人工智能AI Agent浏览器控制代码智能体CUAWright Webwright 一次性 Web 任务执行指南/cuawright:run 命令的 Playwright 代码即操作工作流CUAWright Webwright 一次性 Web 任务执行指南 /cuawright:run 命令的 Playwright 代码即操作工作流 CUAWr人工智能AI Agent浏览器控制代码智能体上一篇OpenPencil CLI 导出实战指南从终端生成 PNG、SVG、PDF、PPTX、HTML 与 JSX下一篇Shell变量作用域性能优化终极指南gh_mirrors/sh1/sh中的高效缓存策略 创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考