Browser Steel

优先使用Steel CLI。仅当工作流需要大量选择器的自定义逻辑，且难以通过原始CLI步骤表达时，才使用Python运行时。

此处CLI的含义

CLI指命令行界面。

在此技能中，特指Steel终端命令本身，例如：

bash
steel scrape https://example.com
steel browser start --session demo
steel browser open https://example.com --session demo
steel browser snapshot -i --session demo

包装脚本不会替代Steel CLI。它将CLI打包成更易于发布、对代理更友好的入口点：

bash
python3 {baseDir}/scripts/main.py scrape --url https://example.com
python3 {baseDir}/scripts/main.py start-session --session demo
python3 {baseDir}/scripts/main.py browser --session demo -- snapshot -i -c

因此关系如下：

• - Steel CLI = 底层浏览器命令系统
• scripts/main.py = 默认调用Steel CLI的包装器
• Python运行时 = 当CLI步骤不足时，用于自定义Playwright逻辑的回退路径

初始检查

1. 1. 在新环境中执行首个实际任务前，先运行诊断命令：

1. 2. 对于一次性提取或捕获，优先使用无状态命令。
2. 对于多步骤交互，优先使用命名会话。
3. 在同一工作流的每个步骤中保持相同的--session值。
4. 切勿将私有cookies、配置文件名称或本地路径硬编码到技能本身中。

运行时选择

• - auto：优先使用已安装的steel，否则回退到npx @steel-dev/cli
• cli：与auto相同，但若无可用CLI路径则报错
• node：通过npx @steel-dev/cli强制使用Node分发的CLI路径
• python：通过run-python-plan使用Steel SDK + Playwright

仅在运行时选择或环境解析相关时，阅读references/runtime-modes.md。
当需要权威的Steel CLI或Playwright-Python上游参考时，阅读references/official-docs.md。

首选命令

健康检查

bash
python3 {baseDir}/scripts/main.py doctor

无状态命令

bash
python3 {baseDir}/scripts/main.py scrape --url https://example.com --format markdown --json
python3 {baseDir}/scripts/main.py screenshot --url https://example.com --full-page --json
python3 {baseDir}/scripts/main.py pdf --url https://example.com --json

命名会话工作流

bash
python3 {baseDir}/scripts/main.py start-session --session demo --stealth --json
python3 {baseDir}/scripts/main.py browser --session demo -- open https://example.com
python3 {baseDir}/scripts/main.py browser --session demo -- snapshot -i -c
python3 {baseDir}/scripts/main.py browser --session demo -- fill @e2 hello
python3 {baseDir}/scripts/main.py browser --session demo -- click @e5
python3 {baseDir}/scripts/main.py browser --session demo -- wait --load-state networkidle
python3 {baseDir}/scripts/main.py stop-session --session demo --json

Python Playwright计划

bash
python3 {baseDir}/scripts/main.py run-python-plan \
--plan-file {baseDir}/references/example-plan.json \
--url https://example.com

仅在CLI路径不足时，阅读references/python-plan.md。

防护措施

• - 当任务为无状态时，从scrape、screenshot或pdf开始。
• 对于交互式工作流，遵循start-session -> browser commands -> stop-session的顺序。
• 在任何导航或有意义的DOM变更后，在使用另一个@eN引用前，先获取新的snapshot -i。
• 将机密信息保存在环境变量或显式的--env-file中，而非技能文件中。
• 仅通过--cookies-file或STEELBROWSERCOOKIES_FILE传递cookies。
• 仅对真正需要自定义Playwright逻辑的任务使用Python运行时。
• 将确认的改进记录在maintenance.log中。

参考资料

• - references/official-docs.md — 上游Steel CLI和Playwright-Python参考
• references/runtime-modes.md — 运行时选择、环境加载和隐私规则
• references/cli-workflows.md — 可靠的Steel CLI模式
• references/python-plan.md — JSON计划模式和受支持的操作
• references/troubleshooting.md — 安装/认证/运行时恢复