SuperAPI AI 工具集
合作ENAI 行业资讯收藏
Skill 广场playwright-stealth-job

playwright-stealth-job

测试与质量

查看项目

更新于 10-16 07:49

技能介绍

用途

playwright-stealth-job 用于把一次受监督的浏览会话转化为一个可长期重放的 Python 作业文件。它适合会重复发生的浏览任务，例如每月拉取发票、每周导出数据、周期性检查。也用于重放、列出或修复已有作业。

它不适用于一次性的“去看一下这个页面”——那属于 playwright-stealth，直接驱动比录制更便宜。它也不用于创建或调整身份（playwright-stealth-identity）或安装工具链（playwright-stealth-setup）。

录制是一种权衡：它把稳定的每次运行模型成本，换成突发的损坏修复成本，后者会在供应商发布改版的当天早上出现。对稳定站点上的高频作业值得，对易变站点上的季度作业不值得。

主要能力

  • 将浏览任务录制为可提交的 Python 作业，代码可审查、不含密钥。
  • 在固定身份上重放作业，运行时不调用模型。
  • 重放前自动运行 linter（基于 AST 的允许列表，对应内部规则，不是风格检查）。
  • 运行后生成清单（manifest）、结果和失败包，存放在 gitignore 的 .stealth/ 目录下。
  • 支持 --list（列出作业及其上次运行）、--seed <n>（精确复现过去某次运行的时序）、--keep-trace、--self-test。
  • 失败时提供 DIAGNOSE 命令，可离线运行 pagestate.py 生成诊断标签。

使用方式

  1. 脚手架：身份必须已存在并已登录。
python3 "${CLAUDE_SKILL_DIR}/scripts/job.py" --identity acme-portal --job invoices --new
  1. 真实驱动一次：打开身份并亲自执行任务，阅读实际页面，尽量深链接，记录每个操作的 role 或 label。
import os, sys
sys.path.insert(0, os.path.join(os.environ["CLAUDE_SKILL_DIR"], "..", "playwright-stealth", "scripts"))
from launch import open_identity
with open_identity("acme-portal") as ctx:
    page = ctx.new_page(); page.goto("https://vendor.example/invoices")

不要跳过这一步凭猜测写选择器，否则作业会在首次真实运行时失败，而那时模型调用已经付费。

  1. 把步骤写入 run()。使用 role 和 label 定位器；它们既是持久的 API，也是拟人化的。设置 START_URL 以深链接跳过菜单，设置 LOGGED_IN_WHEN 为仅在登录后存在的内容，并至少添加一个 h.expect(...) 结果断言。

  2. lint 后运行：

python3 "${CLAUDE_SKILL_DIR}/scripts/job.py" --identity acme-portal --job invoices --lint
python3 "${CLAUDE_SKILL_DIR}/scripts/job.py" --identity acme-portal --job invoices --run

报告运行目录和 seed。后续运行只需这条命令。

  1. 失败时：给页面打标签，然后只修复一个步骤。失败的运行会打印 DIAGNOSE 命令；它离线运行且始终安全：
python3 "${CLAUDE_SKILL_DIR}/scripts/pagestate.py" --run <run-dir> --offline

离线签名（HTTP 状态、几个明确的标题、可见的挑战 iframe）能捕获明显情况。其余情况，去掉 --offline 会把失败页面的脱敏标题和文本发送给 TypeSafe Jev 获得一个类型化标签——需先询问用户；环境中有密钥不等于授权。无论哪种方式，diagnosis.json 都包含一个标签和首先要检查的事项：疑似会话失效、同意覆盖层、机器人挑战或封锁（不要凭猜测重跑）、站点错误，或无墙内容。这只是分诊提示，不是结论——在改动任何东西前，先在 failure.png 和 failure.html 中确认。只改损坏的部分，然后重跑验证。

适用场景

  • 每月发票拉取、每周导出、周期性检查等重复浏览任务。
  • 重放、列出或修复已有作业。
  • 在稳定站点上运行高频作业。

限制与注意事项

  • 仅限授权使用。录制的作业无人值守运行，风险更高。只自动化你拥有或获授权测试的资产；遵守服务条款和 robots.txt。优先只读作业。完整政策见 references/secrets-and-artefacts.md。
  • 会话过期是主要失败模式，而非选择器漂移。LOGGED_IN_WHEN 不是可选项，它把会话过期变成干净的早期错误，而不是在登录墙上困惑点击。
  • Locator API 已完全拟人化——CloakBrowser 对 Locator 类的 click、fill、type、hover、check、press、press_sequentially、select_option、drag_to、clear 和 scroll_into_view_if_needed 打了补丁。page.get_by_role(...).click() 既持久又像人。page.query_selector() 返回 ElementHandle，绕过所有补丁——linter 会拒绝它。
  • 绝不做运行时自愈。“最接近匹配”回退会把响亮的失败变成在活跃认证账户上的静默错误点击。修复应作为可审查的 diff；绝不在运行中替换选择器。
  • 固定重放是跨运行指纹。humanize 在一次运行内变化，不在运行之间变化。h.pause() 从运行 seed 抖动，seed 被记录——所以生产运行不同，而 --seed <n> 可精确复现任何过去运行用于调试。不要在同一墙钟秒调度重放。
  • 密钥是引用，绝不是值。h.secret("NAME") 在运行时读取 STEALTH_SECRET_NAME，未设置时快速失败并指出变量名。更好的是根本不脚本化登录——profile 已持有会话。
  • 运行产物含密钥。截图、trace 和 result.json 捕获账户数据和 POST 值。它们位于 gitignore 的 .stealth/ 下并被修剪；成功的 trace 被删除，失败的永不删除。
  • 改变状态的步骤重放危险。盲目重放的失败模式是执行两次。优先只读作业；对任何提交、支付或删除的操作断言恰好一次。
  • 绝不要为了让作业通过而编辑 linter。每条规则都对应一个已记录的迹象。
  • pagestate.py 是唯一会调用模型的东西，且仅在去掉 --offline 时。重放从不调用它，所以“循环中无模型”字面成立。该调用发送失败页面的脱敏标题、最多 2,000 字符的可见文本（URL、邮箱和数字串被掩码）、密码字段数量和可见 iframe 源——绝不发送页面 URL、cookie、字段值或密钥——并在 429/529 时重试一次。页面文本仍可能影响标签（测试中一个隐藏的“你已登录”注释使概率移动了 13%），这就是它只是建议性的原因：标签是查看的理由，绝不是行动的理由。

完成标准

  • 真实 --run 返回 RESULT: ok，并报告运行目录和 seed。
  • 作业文件可安全提交：无凭据、cookie、令牌或提取的数据。
  • 它声明 LOGGED_IN_WHEN 和至少一个结果断言。
  • 你告诉用户它在哪个身份上运行，以及大致维护成本。

参考

  • references/authoring.md — 编译而非录制、选择器持久性排名、断言、内部规则表、带标签到首查表的修复工作流、运行间差异，以及何时根本不应录制作业。
  • references/secrets-and-artefacts.md — 提交/gitignore 划分、密钥机制、为什么作业不应登录、运行产物、什么离开机器及何时、保留策略，以及从 git 获得的可追溯性。