用途：借助随附的 Bash/Python 辅助脚本，对 TikTok Creative Center 的 Top Ads 进行调研。需要 Bash 与 Python 3.9+（仅标准库），无需 TikTok Business token 或 SDK。
主要能力：支持按关键词、1 至 5 个 --start-url，或两者同时发起查询；可叠加国家、行业、目标、广告语言、周期、排序等筛选。URL 必须为 ads.tiktok.com 上 /business/creativecenter/topads/ 或 /business/creativecenter/inspiration/topads/ 下的 HTTPS 地址。仅用国家等筛选不足以发起请求。
使用方式：推荐用 run 一次性创建、等待并获取完整 JSON 数组；也可用 create、status、wait、result 分阶段执行。示例： bash {baseDir}/scripts/tiktok_top_ads_search.sh run --keyword 'shoes' --country US --order-by ctr --max-items 10 bash {baseDir}/scripts/tiktok_top_ads_search.sh create --client-task-id caller-stable-id --keyword 'skincare' --industry 14 --objective 15 --ad-format 1 bash {baseDir}/scripts/tiktok_top_ads_search.sh status --task-id TASK_UUID bash {baseDir}/scripts/tiktok_top_ads_search.sh wait --task-id TASK_UUID --timeout 1800 bash {baseDir}/scripts/tiktok_top_ads_search.sh result --task-id TASK_UUID --output ./out/top-ads.json create --wait 等价于 run。重复 --country、--industry、--objective、--ad-language 可传数组。
限制与注意：创建任务会计费，服务器先估算积分并异步结算实际用量；需记录打印的 client_task_id 与返回的 task_id。创建结果不确定时，只能用相同选项与相同 client ID 重试，切勿自动创建替代任务；相同 ID 改参数会返回 HTTP 409。等待 READY 且 result_available=true，按 next_poll_after_ms 轮询，为 0 则停止自动轮询；遇 FAILED、REVIEW_REQUIRED 或 RESULT_EXPIRED 应停止。保留保存的 JSON 字节，除非要求原始 JSON 否则应做摘要；id 保持字符串。指标与媒体为可选，不得推断缺失值，也不要把媒体 URL 当作永久归档资源。认证用 FREVANA_TOKEN 或一次性 --token Bearer，切勿打印凭据；默认 base URL 为 https://ai-factory.frevana.com，可用 FREVANA_API_BASE_URL 或 --api-base-url 覆盖，不跟随重定向。Windows 需用 Git Bash 或 WSL 并具备 Python 3。