meta-ads-search

Meta 广告搜索

通过本地 Frevana 守护进程和 Chrome 扩展会话搜索 Meta 广告资料库。

用途

此技能用于通过 Chrome 扩展支持的 Frevana MCP 工具 frevana_meta_ads_search，按关键词或广告主文本查找 Meta/Facebook 广告。

输入：

• keyword（必填）——用于在 Meta 广告资料库中搜索的关键词、广告主或品牌文本
• country（可选）——ALL 或 ISO 3166-1 alpha-2 国家代码，例如 US、CN 或 GB；默认为 ALL
• active_status（可选）——active、inactive 或 all；默认为 active
• date_from（可选）——包含在内的开始日期，格式为 YYYY-MM-DD
• date_to（可选）——包含在内的结束日期，格式为 YYYY-MM-DD
• maxResults（可选）——要返回的广告数量上限，默认为 20，最大为 500
• timeout（可选）——超时时间，单位为毫秒

输出：

• 包含结构化 Meta 广告记录的原始 Frevana JSON 文本

除非用户要求原始输出，否则请总结结果。

此技能所需内容

• 用户提供的 keyword
• 随附的 scripts/setup.sh 封装脚本，该脚本会下载并运行最新的官方 Frevana 设置脚本
• 设置完成后运行的 Frevana 本地守护进程，默认端口为 12306
• 通过 Frevana Chrome 扩展连接的 Chrome
• 已连接的 Chrome 会话可访问 Meta 广告资料库
• curl
• bash
• python3

这是一项 Chrome 扩展技能。它使用本地守护进程和 Chrome 扩展会话。

执行顺序

按以下流程操作：

1. 确认用户已提供 keyword 或等效的广告主／品牌文本。
2. 优先使用脚本，不要临时直接运行 frevana call 命令。
3. 将 country 默认为 ALL、active_status 默认为 active、maxResults 默认为 20。不要臆造可选的日期范围或超时值。
4. 每次调用 Frevana 工具前，都让脚本运行随附的 scripts/setup.sh。
5. 如果设置提示 Chrome 未连接，请停止操作，并告知用户打开 Chrome、连接 Frevana 扩展后重试。
6. 仅在设置成功后运行 Meta 广告搜索。
7. 如果结果看起来是登录／身份验证内容，或者 Meta 广告资料库不可用，请告知用户可能需要使用可用的 Chrome 会话并重试。
8. 返回简洁的广告摘要；如果用户有要求，则返回原始 JSON。
9. 在有用时，将输出保存到文件。

命令

基本关键词搜索

bash <skill-path>/scripts/search_meta_ads.sh \
  --keyword "nike"

--query、--q 和 --text 可用作 --keyword 的别名。 如果没有其他选项，此命令会搜索所有国家／地区的活跃广告，并最多返回 20 条广告。

按国家／地区和活跃状态筛选

bash <skill-path>/scripts/search_meta_ads.sh \
  --keyword "nike" \
  --country US \
  --active-status active

--active_status 可用作 --active-status 的别名。

限定日期范围和结果数量

bash <skill-path>/scripts/search_meta_ads.sh \
  --keyword "nike" \
  --date-from 2026-01-01 \
  --date-to 2026-06-22 \
  --max-results 50

--date_from、--date_to 和 --maxResults 可用作别名。

将输出保存到文件

bash <skill-path>/scripts/search_meta_ads.sh \
  --keyword "nike" \
  --output ./out/meta-ads-search-result.json

固定工具调用格式

脚本调用：

frevana call frevana_meta_ads_search '<json_args>'

JSON 参数始终包含默认国家／地区、活跃状态和结果数量上限；未提供的其他可选字段会被省略：

{
  "keyword": "nike",
  "country": "ALL",
  "active_status": "active",
  "maxResults": 20
}

用户指定国家／地区和结果数量上限时，这些值会覆盖默认值：

{
  "keyword": "nike",
  "country": "US",
  "active_status": "active",
  "date_from": "2026-01-01",
  "date_to": "2026-06-22",
  "maxResults": 50,
  "timeout": 120000
}

不要向 frevana_meta_ads_search 传入不受支持的字段。

输出

• 成功：脚本会将 Frevana 工具结果打印到标准输出
• 使用 --output：相同结果也会写入指定的文件路径
• 失败：脚本会将 Frevana 错误或预检失败信息打印到标准错误，并以非零状态码退出

注意事项

• 必须提供 --keyword、--query、--q 或 --text。
• --country 默认为 ALL；设置两字母大写国家代码可将结果限制在一个国家。
• --active-status 默认为 active；仅在用户明确要求时使用 inactive 或 all。
• --date-from 和 --date-to 必须使用 YYYY-MM-DD 格式。
• --max-results 默认为 20，且必须是 1 到 500 之间的整数。
• 提供 --timeout 时，必须是正整数。
• 每次搜索前，脚本都会运行随附的 scripts/setup.sh，与原始 Frevana 技能的流程一致。
• scripts/setup.sh 会从 https://raw.githubusercontent.com/FinpeakInc/frevana-cli-releases/refs/heads/main/skills/frevana/scripts/setup.sh 下载并执行最新的官方安装脚本。
• 如果缺少 frevana，官方安装脚本会先安装 Frevana 二进制文件，然后再启动／检查守护进程。

示例提示词

中文

• “查一下 Meta Ads Library 里 nike 的广告”
• “搜索 Facebook 广告库里关于 openai 的广告，美国区，只看 active”
• “查 meta ads，关键词 shopify，限制 2026-01-01 到 2026-06-22，保存原始 JSON”

英文

• “搜索 Meta Ads Library 中的 nike 广告”
• “查找美国地区关于 openai 的活跃 Meta 广告”
• “搜索 2026-01-01 到 2026-06-22 期间关于 shopify 的 Meta 广告，并保存原始 JSON”