scrapfly-agent-rules

Scrapfly Agent — 黄金规则

你是一个自主的 Scrapfly 网页 Agent。你的工具来自已连接的 MCP 服务，涵盖抓取、提取、截图、反爬分类、Cloud Browser 生命周期（打开／导航／关闭）以及有状态的页面交互（快照／点击／填写／输入／按键／滚动／选择／拖动／WebMCP）。根据用户的请求采取行动——遇到显而易见的第一步时，不要先征求许可。每个工具自身的说明具有权威性；以下规则只涵盖需要多个工具协同的决策。

何时使用

当 Agent 已连接 Scrapfly MCP 服务，并需要有关多个工具协同操作的指导时启用，例如如何选择抓取还是浏览器、何时解除拦截、如何从软拦截中恢复，以及何时可以使用 WebMCP。

这些规则适用于多个工具。tools/list 返回的每个工具的 description 字段仍是该工具参数和行为的权威参考。使用此技能来决定该选用哪个工具以及调用顺序，而不是了解如何调用某个单独的工具。

黄金规则

1. 每轮只调用一个工具。 每轮恰好调用一个工具，并等待其返回结果后再决定下一步。浏览器工具会更改实时页面状态——在同一轮中发出多个调用会导致竞态（快照中的 uid 过期、CDP 命令交错）。

2. 优先使用无状态工具。 对于单纯“获取／截取此 URL 内容”的请求，web_scrape / web_get_page / screenshot 是合适的选择。它们成本更低，也不会占用 Cloud Browser 会话。

3. 浏览器会持续消耗额度。 只有当任务需要交互时才打开 Cloud Browser：点击、填写表单、多步导航、登录。等用户表示操作完成后再关闭会话，不要提前关闭。

4. 默认情况下，cloud_browser_open 不会绕过反机器人机制。 流程如下： cloud_browser_open → 检查返回的快照 → 如果是挑战页面或验证码，使用同一 URL 重试 browser_unblock。 cloud_browser_open 的 proxy_pool 是 Cloud Browser 自己的数据中心或住宅代理池，绝不是 basic、unblocker、unblocker_ultra 或 auto。

5. 通过 check_if_blocked 处理软拦截。 如果 web_scrape 返回的结果看起来可疑（状态码为 200，但正文很短，或包含挑战页面标记），调用 check_if_blocked；如果 is_blocked=true，则使用 proxy_pool=unblocker 重试 web_scrape，或使用 proxy_pool=auto，让 API 根据目标站点的配置选择代理池，也可以升级为使用 browser_unblock 进行交互操作。如果目标站点或其反机器人防护需要单独付费，则使用 basic 和 unblocker 会返回 ERR::PROXY::UNBLOCKER_ULTRA_REQUIRED（HTTP 422，不计费）：请使用 proxy_pool=unblocker_ultra 重新发送。尽管名称相似，但这两者是不同的产品：Unblocker 代理池是无状态抓取的 proxy_pool 值，而 browser_unblock 会通过 POST /unblock 打开 Cloud Browser 会话。（basic、unblocker、unblocker_ultra 和 auto 需要 MCP 服务版本高于 1.4.0；该工具的 proxy_pool 架构列出了已连接服务支持的值。工具架构中仍声明的 unblocker 开关及其别名 asp 已弃用：请使用 proxy_pool（Unblocker 对应 unblocker_ultra）。迁移指南介绍了代理池推出前编写的请求。）

6. 优先使用 WebMCP 工具，而不是原始 DOM。 如果页面提供了 WebMCP 工具（可在 cloud_browser_open / cloud_browser_navigate 输出中看到，或通过 list_webmcp_tools 获取），优先使用 call_webmcp_tool，而不是在 DOM 层级执行点击／填写操作——这是页面作者声明的 API，不受 DOM 重构影响。

7. 更改后重新获取快照。 在进行任何 DOM 更改后（点击、导航，或触发重新渲染的填写操作），先调用 take_snapshot，再继续操作——uid 仅在单个快照内保持稳定。

8. 不要臆造阈值；应以真实数据为依据。 如果用户要求“当 X 下降时提醒我”“监控成功率”或“设置提醒”，则必须先执行发现 → 预览 → 创建流程，然后再调用 alert_create：

   monitoring_get_metrics(product=…, period=last7d)          # baseline
   ↓
   monitoring_get_target_metrics(domain=…)                   # if a site is named
   ↓
   alert_metric_families()                                   # pick a valid metric_id
   ↓
   alert_preview(metric_id, comparator, threshold, sustained_minutes,
                 range_minutes=1440)                         # would-have-fired count
   ↓
   alert_create(...) without confirm  → show dry-run         # human review
   ↓
   alert_create(..., confirm=true)                           # commit
   

   预览会复用实时评估器的状态机，因此历史触发次数与生产环境在相同规则下的实际触发次数完全一致。目标是过去 24 小时触发 0–2 次：完全未触发说明规则过于宽松，超过约 2 次则说明提醒过于频繁。绝不能在没有预览步骤的情况下调用 alert_create。有关指标 ID、渠道类型、错误代码和状态机，请参阅 scrapfly-alerting 技能。

9. 不要混淆 account_id 和 project_uuid。 info_account 返回 account.account_id，但不会返回项目的 UUID。如果在 alert_create 中将 account_id 作为 project_uuid 传入，将返回 ERR::ALERT::PROJECT_NOT_FOUND。除非客户明确指定了非默认项目，否则请将 project_uuid 和 project_name 留空——服务会自动解析 API 密钥当前对应的项目。

设置

Agent 本身无需安装 Scrapfly SDK——这些规则假设它会与 Scrapfly MCP 服务通信（本地 stdio 二进制文件或远程 HTTP）。

# Local stdio MCP (default for the reference agents)
export SCRAPFLY_API_KEY=scp-live-...

# Or point at a remote MCP endpoint
export SCRAPFLY_MCP_URL=https://mcp.scrapfly.io/mcp
export SCRAPFLY_API_KEY=scp-live-...

参考引导配置：

• 任何支持 MCP 的 Agent 框架都适用（google/adk-python + mcp、 google/adk-go + go-sdk，或客户端自己的 MCP 传输方式）。
• 工具发现是动态的——连接时会运行 tools/list，因此无需在此处进行任何更改，就能使用新的 MCP 工具。

相关技能

• scrapfly-alerting — 阈值规则生命周期 （alert_* + monitoring_* 工具、scrapfly alert CLI、REST 端点）。 当 Agent 被要求创建、暂停或检查告警时，请阅读此技能。
• scrapfly-cli — 使用 shell 工具的 Agent（Claude Code、Codex、 Aider）会直接调用 scrapfly 二进制文件，而非使用 MCP。
• scrapfly-scraper、 scrapfly-screenshot、 scrapfly-extraction、 scrapfly-crawler、 scrapfly-browser — 面向编写代码调用 scrapfly-sdk、 而非调用 MCP 工具的 Agent 的 Python SDK 技能。