尧图网站建设 
openai-agents-python 沙箱技能实战用 Playwright SKILL.md 驱动浏览器截图闭环视觉调试网站克隆【免费下载链接】openai-agents-pythonA lightweight, powerful framework for multi-agent workflows项目地址: https://gitcode.com/GitHub_Trending/op/openai-agents-python本篇文章围绕 examples/sandbox/tutorials/vision_website_clone/skills/playwright/SKILL.md 展开讲解在 openai-agents-python 的沙箱Sandbox环境中如何把 Playwright 封装成一个可被 Agent 按需加载lazy-load的 Skill用真实浏览器为静态站点截图并配合view_image工具形成截图 → 查看 → 修订的视觉调试闭环。读完本文你将掌握 SKILL.md 的 frontmatter 规范与命令编写要点、Skills(lazy_from...)懒加载机制的原理以及如何复现一个完整的视觉 UI 克隆示例。一、SKILL.md 是什么Agent 沙箱中的技能入口文件在 openai-agents-python 的沙箱体系中Skill技能是一组本地指令以SKILL.md文件为核心载体。从 src/agents/sandbox/capabilities/skills.py 的注释可以看到官方定义A skill is a set of local instructions to follow that is stored in aSKILL.mdfile.一个 Skill 目录的典型结构如下scripts/、references/、assets/均为可选skills/ └── playwright/ ├── SKILL.md # 技能入口frontmatter 使用说明 ├── scripts/ # 可选可执行脚本优先运行而非手敲 ├── references/ # 可选按需加载的参考资料 └── assets/ # 可选模板与静态资源每个SKILL.md头部都有一段YAML frontmatter至少包含name和description两个字段它们是 Agent 发现并决定是否使用该技能的依据。本示例的 frontmatter 如下--- name: playwright description: Use when the task requires capturing or automating a real browser from the terminal. ---name技能的唯一名称也是load_skill(playwright)调用时使用的标识。description触发规则的核心——从 skills.py 的Trigger rules可以看出当任务描述与该技能 description 明显匹配时Agent 必须使用该技能。本示例中description明确指出需要从终端捕获或自动化真实浏览器时使用与为克隆站点截图做视觉修订的任务天然匹配。二、逐行拆解 Playwright SKILL.md 的核心命令该 SKILL.md 的正文是一段可以直接在沙箱终端中执行的 Shell 脚本。它被刻意设计为直接捕获静态站点并在开头强调了一条关键约束Use Playwright to capture the static site directly. Do not start a server for this example.也就是说本示例是纯文件模式不启动 FastAPI、不暴露端口、不起本地浏览器服务器——克隆产物是静态 HTML/CSS用file://协议直接加载即可截图。完整命令如下mkdir -p output/screenshots output/playwright/.tmp export TMPDIR$PWD/output/playwright/.tmp export TEMP$TMPDIR export TMP$TMPDIR npx --yes --package playwright1.50.0 playwright install chromium npx --yes --package playwright1.50.0 playwright screenshot \ --browserchromium \ --viewport-size2048,1152 \ file://$PWD/output/site/index.html \ output/screenshots/draft-1.png逐条解读创建目录与隔离临时文件mkdir -p output/screenshots output/playwright/.tmp一次性创建截图输出目录output/screenshots/和 Playwright 运行时临时目录output/playwright/.tmp。-p保证目录已存在时不报错幂等可重入。重定向临时目录环境变量export TMPDIR$PWD/output/playwright/.tmp export TEMP$TMPDIR export TMP$TMPDIR把TMPDIR/TEMP/TMP三个变量统一指向沙箱工作区内的相对路径。这样做有两个好处一是把 Playwright 及 Chromium 的临时文件收拢到工作区内便于清理与审查二是避免依赖系统默认/tmp在沙箱中的权限或容量不确定性。安装 Chromium 浏览器npx --yes --package playwright1.50.0 playwright install chromium使用npx --yes --package playwright1.50.0的方式临时拉取指定版本的 Playwright CLI不写入项目依赖然后安装 Chromium。--yes跳过交互确认保证在无人值守的沙箱中可自动执行。版本号1.50.0被显式固定确保每次运行行为一致。对静态站点执行浏览器截图npx --yes --package playwright1.50.0 playwright screenshot \ --browserchromium \ --viewport-size2048,1152 \ file://$PWD/output/site/index.html \ output/screenshots/draft-1.png参数说明参数含义本示例取值--browser指定浏览器内核chromium--viewport-size视口宽高像素决定截图尺寸2048,1152与参考截图 reference-site.png2048x1152完全一致URL 参数要截图的页面地址file://$PWD/output/site/index.html直接加载沙箱中克隆出的静态首页输出路径截图落盘位置output/screenshots/draft-1.png第二遍修订时只需把输出文件名改为output/screenshots/draft-2.png——这正是 SKILL.md 最后一句Change the final path tooutput/screenshots/draft-2.pngfor the second pass的含义它把至少修订两轮的调试约定直接写进了技能说明让 Agent 在第二次截图时知道该用新文件名避免覆盖第一版证据。三、Skill 如何被 Agent 发现并加载lazy_from 懒加载机制该 SKILL.md 位于沙箱示例的skills/目录下但它不会在沙箱启动时就被全部灌入工作区而是通过 main.py 中配置的Skills能力以懒加载方式按需取用Skills( lazy_fromLocalDirLazySkillSource( # 这是 SDK 进程读取的主机路径 sourceLocalDir(srcSKILLS_SOURCE_DIR), ), skills_pathskills, ),从 src/agents/sandbox/capabilities/skills.py 可以看到Skills能力支持三种来源且只能三选一配置多个会抛SkillsConfigError来源字段行为skills: list[Skill]显式内联声明技能from_: BaseEntry把整个目录作为技能根目录挂载lazy_from: LazySkillSource只索引元数据文件按需加载本项目推荐的大目录默认方案关键设计点LocalDirLazySkillSource读取的是 SDK 进程所在宿主机的文件系统如 docs/sandbox/guide.md 所强调必须传原主机侧技能目录而不是只存在于沙箱镜像或工作区内的路径。skills_path是工作区内的相对目标路径load_skill被调用时才把技能文件 staged 到该位置。Skills.process_manifest()对 lazy 模式会预占整个skills_path命名空间若与现有 manifest 条目重叠会直接报错skills.py避免路径冲突。懒加载的完整调用链Agent 侧触发加载的工具是load_skill它只在lazy_from配置时才会注册skills.py。调用链如下运行时Skills.instructions()会先渲染一份可用技能索引name description 文件路径并明确告知模型懒加载模式下调用load_skill之前不要直接读SKILL.mdskills.py。模型调用load_skill(playwright)后LocalDirLazySkillSource.load_skill()会先检查工作区里是否已存在skills/playwright/SKILL.md——存在则返回already_loaded否则把宿主目录中的技能目录连同文件元数据权限、属组一起复制进沙箱工作区返回loadedskills.py。之后模型才能打开skills/playwright/SKILL.md按其中的命令执行截图。在 main.py 内置的AGENTS.md工作流里这一步被写成了必须执行的硬性要求Before taking screenshots, callload_skill(playwright)and readskills/playwright/SKILL.md.四、视觉调试闭环view_image Playwright 截图的循环该示例的核心价值不在于一次截图成功而在于形成一条可验证的视觉调试循环visual-debug loop。README 明确列出四个必需步骤README.md调用view_image(reference/reference-site.png)查看参考截图先写output/visual-notes.md记录布局与排版要点写出output/site/index.html与output/site/styles.css截图draft-1.png→ 用view_image查看 → 修订 → 再截draft-2.png不产出截图不允许结束。其中view_image工具的实现位于 src/agents/sandbox/capabilities/tools/view_image.py它从沙箱工作区读取图片并返回结构化的图像输出。其底层行为值得注意格式嗅探通过文件头魔数识别 PNG/JPEG/GIF/WebP/BMP/TIFF并通过内容嗅探 SVGview_image.py不依赖扩展名。大小限制超过10MB的图片会被拒绝并提示压缩_MAX_IMAGE_BYTES 10 * 1024 * 1024所以大截图需控制尺寸——本示例 2048x1152 的视口设定也隐含了这一点。路径策略支持工作区路径与显式授权的沙箱路径路径不合法或文件不存在时返回可读的错误字符串而不是直接抛异常中断流程。整个循环的本质是克隆结果不是写完就算数而是必须经过真实浏览器的像素级检验。Agent 写出的 HTML/CSS 是否与参考截图一致、有无错位与缺失通过 Playwright 截图 view_image回看即可发现然后带着反馈进入下一轮修订。main.py运行结束后会把沙箱内的站点与评审产物拷贝回宿主目录便于人工最终核对。五、端到端运行示例从仓库根目录运行 Unix-local 版本README.mduv run python examples/sandbox/tutorials/vision_website_clone/main.py若要改用 Docker 运行同一 manifest先构建共享教程镜像再追加--docker参数docker build -t sandbox-tutorials:latest -f examples/sandbox/tutorials/Dockerfile . uv run python examples/sandbox/tutorials/vision_website_clone/main.py --docker脚本入口支持以下参数main.py参数默认值说明--modelgpt-5.4-mini使用的模型名称--question内置克隆指令发送给 Agent 的用户提示词--docker关闭改用 Docker 沙箱运行--imagesandbox-tutorials:latest--docker时的镜像名--output-dir示例下output/可用环境变量EXAMPLES_ARTIFACTS_DIR覆盖拷贝产物目录运行结束后期望的产物包括README.mdoutput/index.html、output/styles.css—— 克隆出的静态站点output/screenshots/draft-1.png、output/screenshots/draft-2.png—— 两轮视觉修订截图output/visual-notes.md—— Agent 的布局/排版观察笔记其中main.py的copy_site_output_dir会递归遍历沙箱output/site/目录并写回宿主output/copy_review_artifacts则逐个拷贝评审产物文件不存在时如修订轮次不足会静默跳过随后脚本校验index.html与styles.css必须存在否则抛错——这正是必须有产物的契约式兜底main.py。六、相关文件索引如果你想深入这套机制以下文件值得继续阅读技能定义本体examples/sandbox/tutorials/vision_website_clone/skills/playwright/SKILL.md示例说明与产物契约examples/sandbox/tutorials/vision_website_clone/README.md示例主程序manifest、能力装配、产物回拷examples/sandbox/tutorials/vision_website_clone/main.pySkills 能力与懒加载实现src/agents/sandbox/capabilities/skills.pyview_image工具实现src/agents/sandbox/capabilities/tools/view_image.py沙箱能力使用指南含 lazy_from 选型建议docs/sandbox/guide.md参考截图视觉克隆的输入examples/sandbox/tutorials/vision_website_clone/reference-site.png小结playwright这份 SKILL.md 虽然只有二十余行却是沙箱技能 真实浏览器 视觉反馈三者协同的浓缩范例frontmatter 让 Agent 能在正确场景下发现它file:// 固定视口的截图命令让纯静态产物可被像素级验证而Skills(lazy_from...)懒加载机制与load_skill调用链保证了技能文件按需进入工作区、不浪费上下文。这套写页面 → 截图 → 看图 → 修订的循环正是 Agent 自主完成视觉质量闭环的通用模板可以迁移到任何需要浏览器渲染验证的沙箱任务中。【免费下载链接】openai-agents-pythonA lightweight, powerful framework for multi-agent workflows项目地址: https://gitcode.com/GitHub_Trending/op/openai-agents-python创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 openai-agents-python 沙箱技能实战：用 Playwright SKILL.md 驱动浏览器截图，闭环视觉调试网站克隆
openai-agents-python 沙箱技能实战用 Playwright SKILL.md 驱动浏览器截图闭环视觉调试网站克隆【免费下载链接】openai-agents-pythonA lightweight, powerful framework for multi-agent workflows项目地址: https://gitcode.com/GitHub_Trending/op/openai-agents-python本篇文章围绕 examples/sandbox/tutorials/vision_website_clone/skills/playwright/SKILL.md 展开讲解在 openai-agents-python 的沙箱Sandbox环境中如何把 Playwright 封装成一个可被 Agent 按需加载lazy-load的 Skill用真实浏览器为静态站点截图并配合view_image工具形成截图 → 查看 → 修订的视觉调试闭环。读完本文你将掌握 SKILL.md 的 frontmatter 规范与命令编写要点、Skills(lazy_from...)懒加载机制的原理以及如何复现一个完整的视觉 UI 克隆示例。一、SKILL.md 是什么Agent 沙箱中的技能入口文件在 openai-agents-python 的沙箱体系中Skill技能是一组本地指令以SKILL.md文件为核心载体。从 src/agents/sandbox/capabilities/skills.py 的注释可以看到官方定义A skill is a set of local instructions to follow that is stored in aSKILL.mdfile.一个 Skill 目录的典型结构如下scripts/、references/、assets/均为可选skills/ └── playwright/ ├── SKILL.md # 技能入口frontmatter 使用说明 ├── scripts/ # 可选可执行脚本优先运行而非手敲 ├── references/ # 可选按需加载的参考资料 └── assets/ # 可选模板与静态资源每个SKILL.md头部都有一段YAML frontmatter至少包含name和description两个字段它们是 Agent 发现并决定是否使用该技能的依据。本示例的 frontmatter 如下--- name: playwright description: Use when the task requires capturing or automating a real browser from the terminal. ---name技能的唯一名称也是load_skill(playwright)调用时使用的标识。description触发规则的核心——从 skills.py 的Trigger rules可以看出当任务描述与该技能 description 明显匹配时Agent 必须使用该技能。本示例中description明确指出需要从终端捕获或自动化真实浏览器时使用与为克隆站点截图做视觉修订的任务天然匹配。二、逐行拆解 Playwright SKILL.md 的核心命令该 SKILL.md 的正文是一段可以直接在沙箱终端中执行的 Shell 脚本。它被刻意设计为直接捕获静态站点并在开头强调了一条关键约束Use Playwright to capture the static site directly. Do not start a server for this example.也就是说本示例是纯文件模式不启动 FastAPI、不暴露端口、不起本地浏览器服务器——克隆产物是静态 HTML/CSS用file://协议直接加载即可截图。完整命令如下mkdir -p output/screenshots output/playwright/.tmp export TMPDIR$PWD/output/playwright/.tmp export TEMP$TMPDIR export TMP$TMPDIR npx --yes --package playwright1.50.0 playwright install chromium npx --yes --package playwright1.50.0 playwright screenshot \ --browserchromium \ --viewport-size2048,1152 \ file://$PWD/output/site/index.html \ output/screenshots/draft-1.png逐条解读创建目录与隔离临时文件mkdir -p output/screenshots output/playwright/.tmp一次性创建截图输出目录output/screenshots/和 Playwright 运行时临时目录output/playwright/.tmp。-p保证目录已存在时不报错幂等可重入。重定向临时目录环境变量export TMPDIR$PWD/output/playwright/.tmp export TEMP$TMPDIR export TMP$TMPDIR把TMPDIR/TEMP/TMP三个变量统一指向沙箱工作区内的相对路径。这样做有两个好处一是把 Playwright 及 Chromium 的临时文件收拢到工作区内便于清理与审查二是避免依赖系统默认/tmp在沙箱中的权限或容量不确定性。安装 Chromium 浏览器npx --yes --package playwright1.50.0 playwright install chromium使用npx --yes --package playwright1.50.0的方式临时拉取指定版本的 Playwright CLI不写入项目依赖然后安装 Chromium。--yes跳过交互确认保证在无人值守的沙箱中可自动执行。版本号1.50.0被显式固定确保每次运行行为一致。对静态站点执行浏览器截图npx --yes --package playwright1.50.0 playwright screenshot \ --browserchromium \ --viewport-size2048,1152 \ file://$PWD/output/site/index.html \ output/screenshots/draft-1.png参数说明参数含义本示例取值--browser指定浏览器内核chromium--viewport-size视口宽高像素决定截图尺寸2048,1152与参考截图 reference-site.png2048x1152完全一致URL 参数要截图的页面地址file://$PWD/output/site/index.html直接加载沙箱中克隆出的静态首页输出路径截图落盘位置output/screenshots/draft-1.png第二遍修订时只需把输出文件名改为output/screenshots/draft-2.png——这正是 SKILL.md 最后一句Change the final path tooutput/screenshots/draft-2.pngfor the second pass的含义它把至少修订两轮的调试约定直接写进了技能说明让 Agent 在第二次截图时知道该用新文件名避免覆盖第一版证据。三、Skill 如何被 Agent 发现并加载lazy_from 懒加载机制该 SKILL.md 位于沙箱示例的skills/目录下但它不会在沙箱启动时就被全部灌入工作区而是通过 main.py 中配置的Skills能力以懒加载方式按需取用Skills( lazy_fromLocalDirLazySkillSource( # 这是 SDK 进程读取的主机路径 sourceLocalDir(srcSKILLS_SOURCE_DIR), ), skills_pathskills, ),从 src/agents/sandbox/capabilities/skills.py 可以看到Skills能力支持三种来源且只能三选一配置多个会抛SkillsConfigError来源字段行为skills: list[Skill]显式内联声明技能from_: BaseEntry把整个目录作为技能根目录挂载lazy_from: LazySkillSource只索引元数据文件按需加载本项目推荐的大目录默认方案关键设计点LocalDirLazySkillSource读取的是 SDK 进程所在宿主机的文件系统如 docs/sandbox/guide.md 所强调必须传原主机侧技能目录而不是只存在于沙箱镜像或工作区内的路径。skills_path是工作区内的相对目标路径load_skill被调用时才把技能文件 staged 到该位置。Skills.process_manifest()对 lazy 模式会预占整个skills_path命名空间若与现有 manifest 条目重叠会直接报错skills.py避免路径冲突。懒加载的完整调用链Agent 侧触发加载的工具是load_skill它只在lazy_from配置时才会注册skills.py。调用链如下运行时Skills.instructions()会先渲染一份可用技能索引name description 文件路径并明确告知模型懒加载模式下调用load_skill之前不要直接读SKILL.mdskills.py。模型调用load_skill(playwright)后LocalDirLazySkillSource.load_skill()会先检查工作区里是否已存在skills/playwright/SKILL.md——存在则返回already_loaded否则把宿主目录中的技能目录连同文件元数据权限、属组一起复制进沙箱工作区返回loadedskills.py。之后模型才能打开skills/playwright/SKILL.md按其中的命令执行截图。在 main.py 内置的AGENTS.md工作流里这一步被写成了必须执行的硬性要求Before taking screenshots, callload_skill(playwright)and readskills/playwright/SKILL.md.四、视觉调试闭环view_image Playwright 截图的循环该示例的核心价值不在于一次截图成功而在于形成一条可验证的视觉调试循环visual-debug loop。README 明确列出四个必需步骤README.md调用view_image(reference/reference-site.png)查看参考截图先写output/visual-notes.md记录布局与排版要点写出output/site/index.html与output/site/styles.css截图draft-1.png→ 用view_image查看 → 修订 → 再截draft-2.png不产出截图不允许结束。其中view_image工具的实现位于 src/agents/sandbox/capabilities/tools/view_image.py它从沙箱工作区读取图片并返回结构化的图像输出。其底层行为值得注意格式嗅探通过文件头魔数识别 PNG/JPEG/GIF/WebP/BMP/TIFF并通过内容嗅探 SVGview_image.py不依赖扩展名。大小限制超过10MB的图片会被拒绝并提示压缩_MAX_IMAGE_BYTES 10 * 1024 * 1024所以大截图需控制尺寸——本示例 2048x1152 的视口设定也隐含了这一点。路径策略支持工作区路径与显式授权的沙箱路径路径不合法或文件不存在时返回可读的错误字符串而不是直接抛异常中断流程。整个循环的本质是克隆结果不是写完就算数而是必须经过真实浏览器的像素级检验。Agent 写出的 HTML/CSS 是否与参考截图一致、有无错位与缺失通过 Playwright 截图 view_image回看即可发现然后带着反馈进入下一轮修订。main.py运行结束后会把沙箱内的站点与评审产物拷贝回宿主目录便于人工最终核对。五、端到端运行示例从仓库根目录运行 Unix-local 版本README.mduv run python examples/sandbox/tutorials/vision_website_clone/main.py若要改用 Docker 运行同一 manifest先构建共享教程镜像再追加--docker参数docker build -t sandbox-tutorials:latest -f examples/sandbox/tutorials/Dockerfile . uv run python examples/sandbox/tutorials/vision_website_clone/main.py --docker脚本入口支持以下参数main.py参数默认值说明--modelgpt-5.4-mini使用的模型名称--question内置克隆指令发送给 Agent 的用户提示词--docker关闭改用 Docker 沙箱运行--imagesandbox-tutorials:latest--docker时的镜像名--output-dir示例下output/可用环境变量EXAMPLES_ARTIFACTS_DIR覆盖拷贝产物目录运行结束后期望的产物包括README.mdoutput/index.html、output/styles.css—— 克隆出的静态站点output/screenshots/draft-1.png、output/screenshots/draft-2.png—— 两轮视觉修订截图output/visual-notes.md—— Agent 的布局/排版观察笔记其中main.py的copy_site_output_dir会递归遍历沙箱output/site/目录并写回宿主output/copy_review_artifacts则逐个拷贝评审产物文件不存在时如修订轮次不足会静默跳过随后脚本校验index.html与styles.css必须存在否则抛错——这正是必须有产物的契约式兜底main.py。六、相关文件索引如果你想深入这套机制以下文件值得继续阅读技能定义本体examples/sandbox/tutorials/vision_website_clone/skills/playwright/SKILL.md示例说明与产物契约examples/sandbox/tutorials/vision_website_clone/README.md示例主程序manifest、能力装配、产物回拷examples/sandbox/tutorials/vision_website_clone/main.pySkills 能力与懒加载实现src/agents/sandbox/capabilities/skills.pyview_image工具实现src/agents/sandbox/capabilities/tools/view_image.py沙箱能力使用指南含 lazy_from 选型建议docs/sandbox/guide.md参考截图视觉克隆的输入examples/sandbox/tutorials/vision_website_clone/reference-site.png小结playwright这份 SKILL.md 虽然只有二十余行却是沙箱技能 真实浏览器 视觉反馈三者协同的浓缩范例frontmatter 让 Agent 能在正确场景下发现它file:// 固定视口的截图命令让纯静态产物可被像素级验证而Skills(lazy_from...)懒加载机制与load_skill调用链保证了技能文件按需进入工作区、不浪费上下文。这套写页面 → 截图 → 看图 → 修订的循环正是 Agent 自主完成视觉质量闭环的通用模板可以迁移到任何需要浏览器渲染验证的沙箱任务中。【免费下载链接】openai-agents-pythonA lightweight, powerful framework for multi-agent workflows项目地址: https://gitcode.com/GitHub_Trending/op/openai-agents-python创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考