SuperAPI AI 工具集
合作ENAI 行业资讯收藏
Skill 广场schedule-ads

schedule-ads

营销与增长

查看项目

更新于 10-15 10:08

技能介绍

用途

schedule-ads 用于通过声明式配置文件管理 AdManage.ai 上的付费广告。它根据 ${var} 选择流程：为空或未设置时运行 schedule 分支（把广告投放到已有广告组）；设为 create 时运行 create 分支（创建 Meta 广告系列与广告组）。两条分支都由配置驱动、默认 PAUSED，并通过 ./secretcurl 在运行中调用 AdManage API（使用 {ADMANAGE_API_KEY} 占位符避免密钥出现在命令行），且受失败关闭式花费护栏保护。

主要能力

schedule 分支（默认）

读取 skills/schedule-ads/config.yaml，挑选匹配今天的排期条目，并通过 AdManage.ai（POST /v1/launch）在运行中投放这些广告。

安全默认值（按优先级）：

  • 默认 PAUSED：每个投放请求都把实体设为 PAUSED，需操作员在 AdManage 面板手动恢复后才开始花费；config 中 launchPaused: false 是显式退出选项。
  • 每日花费上限：投放前检查 GET /v1/spend/daily，若花费 ≥ config 中的 dailySpendCap，则跳过所有投放并发出警告；若花费无法核实（响应格式错误或为空），则失败关闭——跳过并通知，不投放。这是熔断器，不是预算执行器，平台预算仍然适用。
  • dry-run 模式：若环境变量 DRY_RUN=true 或 config 中 dryRun: true，则构建载荷写入 .pending-admanage/dryrun/，通知将要投放的内容，不调用 API 即退出。
  • 仅配置：不凭空生成广告系列、创意或定向；若今天没有排期，则干净退出，不调用 API。
  • 单一事实来源：所有广告/广告系列/定向都在 config.yaml 中，分支不会即时生成新创意。

排期匹配规则：when.everyDay: true 始终匹配；when.dayOfWeek 按 UTC 星期匹配；when.date 按精确日期匹配；when.dates 按日期列表匹配；when.cron 为高级选项。

载荷构建：为每个匹配条目构造 POST /v1/launch 请求体，包含 ads 数组，字段有 adName、adAccountId、workspaceId、title、description、cta、link、page、insta、adSets、media、status。字符串字段支持模板替换：{date} 替换为今天 ISO 日期，{dateHuman} 替换为如 "April 21, 2026" 的格式。除非 defaults.launchPaused 显式为 false，否则强制 status: PAUSED。

预检校验：media[].url 必须是绝对 https:// URL；adSets[].value 必须是非空字符串；Meta 条目（adAccountId 以 act_ 开头）必须设置 page 和 insta；title 和 description 必须非空。无效条目被丢弃并记录原因，继续处理其余条目。

投放执行：先检查 ADMANAGE_API_KEY 是否设置（用 ${VAR:+x} 形式），未设置则通知并停止；再执行每日花费熔断检查（取今天载荷中最严格的 dailySpendCap，花费无法核实或非数字则失败关闭）；然后逐批调用 POST /v1/launch，轮询 GET /v1/batch-status/{id} 至终态，记录每批结果。最后写入 output/.chains/schedule-ads.md 供下游链式消费者读取，并通过 ./notify 发送简洁通知。若今天无匹配则完全不通知。

create 分支（${var}=create）

读取 skills/schedule-ads/config.create.yaml，判断哪些广告系列/广告组尚不存在，并通过 AdManage.ai（/v1/manage/create-*）在运行中创建——先创建广告系列，再创建引用返回的 campaign ID 的广告组，并把新 ID 写回 .admanage-state/campaigns.json。此分支为按需手动调用。

仅提供两类实体：Meta 广告系列（名称、目标、预算、竞价策略、推广对象）和 Meta 广告组（名称、预算、优化目标、定向（地域/年龄/平台）、目的地）。其他平台及高级 Meta 字段属于 v2+。

安全默认值：默认 PAUSED（每个广告系列和广告组都以 status: PAUSED 创建）；幂等（在 .admanage-state/campaigns.json 中跟踪已创建实体，同名跳过，运行两次不产生重复）；dry-run 模式（写入 .pending-admanage/dryrun-create/，通知，不调用 API）；仅配置（无配置文件则静默退出，不凭空创建）。

执行顺序：先创建所有广告系列（POST /v1/manage/create-campaign），维护 config 名称到 campaignId 的映射；再创建广告组（POST /v1/manage/create-adset），替换父级真实 campaign ID；每步把新 ID 写回状态文件。若 ADMANAGE_API_KEY 未设置或创建调用失败，记录失败并继续其余部分，不盲目重试、不虚构 ID；父广告系列创建失败的广告组会被跳过。

使用方式

  • schedule 分支：配置 skills/schedule-ads/config.yaml（参考同目录 config.example.yaml），运行技能即可按排期投放。
  • create 分支：配置 skills/schedule-ads/config.create.yaml（参考 config.create.example.yaml），以 ${var}=create 调用以创建广告系列与广告组，再把返回的 ID 填入 config.yaml 供 schedule 分支使用。
  • 认证：ADMANAGE_API_KEY 通过技能的 requires: 在运行中注入，始终写作 {ADMANAGE_API_KEY} 占位符，绝不使用裸 $ADMANAGE_API_KEY。
  • 可用命令：./secretcurl、jq、date、echo、mkdir、grep、python3 及 Write 工具。

适用场景

  • 按日/星期/指定日期/日期列表/cron 排期，把配置好的广告投放到已有广告组。
  • 在正式投放前用 dry-run 预演载荷。
  • 按需批量创建 Meta 广告系列与广告组，并保持幂等。

限制

  • schedule 分支不创建广告系列或广告组，只投放到已存在的广告组；不上传创意（媒体 URL 必须已托管在可访问位置）；不生成文案（标题/描述来自配置）；不管理预算、竞价或定向；v1 不支持 Google Ads、Axon、Taboola。
  • create 分支仅支持 Meta 广告系列与广告组，其他平台及高级 Meta 字段属于 v2+。
  • 两条分支都会产生真实广告花费，属于不可逆的出站副作用，因此作为各分支的最终动作，且仅在护栏通过后执行。
  • 若 ADMANAGE_API_KEY 未设置或调用失败，跳过并通知，不盲目重试，没有延迟后处理回退。
  • 具体收费、价格、平台覆盖范围等更多细节暂未提供。