2462268949-hue/apl-creative-set

角色

你在 AppLovin 帮投放负责人批量创建 creative set。API 封装、凭证复用本 skill 同目录的 scripts/creative_tuner.py（ct.set_account() / ct.APL_MGMT_KEY / ct.APL_ACCOUNT_ID / ct.APL_MGMT_URL）。所有工具脚本都在 scripts/，文件名 _cs_*.py。

安装 / 配置（首次必读）

1. 把整个 apl-creative-set/ 目录放进 ~/.claude/skills/（或 Windows %USERPROFILE%\.claude\skills\）。
2. scripts/ 里 cp config.example.json config.json，填入你自己的 AppLovin 凭证：
   • accounts.<账户ID>.report_key = AppLovin Report Key；.mgmt_key = Management API Key。
   • account_aliases 可给账户起别名（如 "myapp": "你的账户ID"），脚本里 ct.set_account("myapp") 就能用。
   • feishu 段可选，只有 creative_tuner.py 的调优日报会用；只建 creative set 不需要，留空即可。
3. config.json 含真实密钥，永远不要提交到 git / 分享出去（建议加进 .gitignore）。
4. 脚本里凡是 ct.set_account("YOUR_ACCOUNT")、顶部 CAMP="" / PA_IDS / VIDS / PREFIX / PP / SUFFIX 等大写常量都是 TODO 占位，按你本次目标改。

本 skill 由 Claude 读 SKILL.md 后驱动：你把目标（campaign、要建的视频、命名、CPP）告诉 Claude，Claude 按下面流程改脚本顶部常量并调用它们。

铁律

0. ★ 每次开工前必须逐条跟用户确认这三项（双端 iOS/安卓不一样，不能沿用上次）： ① set 命名规则；② 是否加 CPP 后缀；③ CPP product_page 填什么值。 即使和上次是同一条产品线也要问，不许默认套用。
1. 凭证安全：绝不输出/打印/回显 config.json 里任何 key/secret/token/open_id。脚本一律不 print 凭证。
2. 默认 PAUSED：新建的 set 一律 status:"PAUSED"，等用户确认无误后再开启（用户说「开启」才 →LIVE）。
3. 只做被要求的素材范围：用户常限定「只建某前缀」「只建近期上传的」等，严格按限定过滤，别多建。
4. 每步回读校验：create/挂载/CPP/开启后都要回读 creative_set/list 确认，不靠响应码。
5. 数字注明来源、精确到 2 位小数、有想法先问、写操作前先确认再执行。

★ API 关键机制（踩过坑，务必照做）

• 挂 campaign 一律以 add-to-campaigns 为准，别指望 create 自动挂牢。 POST /creative_set/create body 里 campaign 关联字段两种写法都见过（单数 campaign_id:"<内部id>" / 复数 campaign_ids:["<内部id>"]）， 但都不能保证挂上（复数常被静默忽略）。所以流程固定为：create 建好 → 立刻 add-to-campaigns 兜底挂载 → 回读 campaign_ids 校验。 create body（实操版）： {"account_id":AID,"type":"APP","name":..,"status":"PAUSED","campaign_ids":["<内部id>"],"product_page":"","languages":[],"countries":[],"assets":[{"id":".."},..]} → 返回 {"id":..,"version":"V2"}
• 补挂 campaign：POST /creative_set/add-to-campaigns，用复数整数数组： {"campaign_ids":[<内部id>],"creative_set_ids":[..]}（campaign≤20，set≤50/批）。最可靠。回读 campaign_ids 里含目标 camp 才算成功。
• 改 set（改名/CPP/开关/增删素材）：POST /creative_set/update {"id":..,"type":"APP","status":"LIVE|PAUSED","name":..,"product_page":..,"assets":[..]}
  • update 会生成新 version。传 assets 是整体覆盖（不是追加）：删=不传该 id，加=把 id 加进全量列表，漏传的会被删掉（务必保留视频+要留的试玩）。
  • 未传的字段（如 name/product_page/campaign 关联）实测保留不丢；稳妥起见开关/改素材时把 name+product_page+languages+countries 一并带上防丢。
  • update 传 campaign_ids 无效（返回200但不挂）——挂载只能用 add-to-campaigns。
• Custom Product Page：字段 product_page。
  • 默认商店页（Use default product page）= product_page:"" 空串（不带 CPP、名字不加后缀）。
  • 设 CPP 时填对应的 product_page 值（字符串 slug，不是 UUID）。没有列表端点；确认某名对应值靠扫全账户 set 统计 product_page vs 名字后缀（见 _cpp_map.py）。
• asset 类型字段两接口不同名（易踩）：
  • asset/list（media 库）里字段是 asset_type；
  • creative_set 的 assets[] 元素里字段是 type。
  • 值：视频 = VID_LONG_P / VID_SHORT_P（或 startswith("VID")）；试玩 = HOSTED_HTML。
• ★ 单个 creative set 素材上限 = 11：assets 达 11 后再 update 加会被静默拒绝（返回不报错但没加上，只能靠回读发现）。加试玩前先查 len(assets)，满 11 的要先删 1 条腾位（替换），否则加不进。
• creative_set/list 与 asset/list 分页 size≤100/200，有的页返回裸 list（不是 {results:[]}），解析要 isinstance 兼容。asset/list 每页上限 100：翻页判定要用 len(res)<100 break（用 200 会第一页就误停，只拿到前 100 条 media）。

开工前先问清（除非用户已给）

1. 目标 campaign（名称/ID）→ 跨 config 里配置的账户定位，拿内部 id。
2. 素材范围：哪些视频？前缀过滤（如某产品线前缀）、上传时间界线（upload_time≥某日）、状态（通常 ACTIVE 且未被其他 set 用过）。
3. 固定试玩：要挂哪几条 HTML 试玩（用户会给确切文件名）。
4. 命名规则：默认 EN_视频类型(AI/3D/JJ…取素材名类型槽)_视频名_top试玩组PA；系列多视频进同一 set → EN_类型_基础名组_top试玩组PA（基础名=去掉尾部序号）。
5. 系列判定：同概念+尾号（迭代1/4）合成一组；易混的先问（如"基础款/进阶款"要不要拆）。
6. CPP：是否设 product_page、填什么、名字要不要加后缀。

标准流程（脚本流水线，均在 scripts/）

1. _apl_active_assets.py → 拉 ACTIVE 素材去重（_apl_active_assets.json）。
2. _cs_plan_scan.py → 找固定试玩 id + 候选视频（前缀+is_video+未被现有 set 占用+时间过滤）→ _cs_scan.json。先改顶部 PREFIX / CAMP / targets。
3. _cs_group.py → 候选按系列/单素材分组、生成名字 → _cs_build_plan.json。可用 _cs_plan_show.py 打印给用户确认。
4. _cs_build_all.py（幂等：按名查重跳过已建）→ 逐条 create(PAUSED, 带 campaign_id) + add-to-campaigns 兜底挂载 + 回读校验 → _cs_create_result.json。
5. （可选）_cpp_apply.py all → 设 product_page + 加名字后缀（先改顶部 PP / SUFFIX）。
6. 用户确认后 _cs_enable.py → status→LIVE（带 name+product_page 防丢）+ 回读。
7. 抽验：_cs_spotcheck.py <id..> 看素材构成（视频数+试玩数）。

轻量路径：少量指定视频直接建组（已知视频名，不走全量扫描）

适用：用户新上传几条视频、直接点名要建组。

1. _cs_find_new.py <关键词..> → 在 media 库按名找视频 完整名+id+状态+上传时间（只读）；核对是不是要的那条、状态 ACTIVE。
2. 改 _cs_en_new_create.py 顶部 VIDS=[(核心名,视频id),..] / PA_IDS(固定试玩) / CAMP；先按铁律 0 跟用户确认命名+CPP。 python _cs_en_new_create.py（dry-run 查重+列计划）→ go（建 PAUSED + 默认商店页 "" + 不设语言跟随 campaign + add-to-campaigns + 回读校验：挂载/assets 数/pp/status）。
3. 用户说开启 → _cs_en_new_enable.py（读 _cs_en_new_ids.json，显式带 name/product_page/languages/countries 防丢，status→LIVE + 回读）。

加 / 剔除 / 替换 set 里的试玩

按 set 名关键词批量增删某试玩（走 update 整包覆盖 assets，保全 name/product_page/languages/countries/status，执行后回读校验）：

• 加：_cs_add_pa.py <试玩id> <set名关键词> [enonly]（dry-run）→ 追加 go。enonly = 只对 EN_ 开头的组（排除小语种定向组）。幂等跳过已含；满 11 的组自动预警跳过（需先删 1 条腾位）。
• 删：_cs_rm_pa.py <试玩id>（dry-run）→ go。安全护栏：移除后该 set 仍须 ≥1 视频且 ≥1 试玩，否则标红跳过不改。
• 换 = 在全量 assets 列表里替换旧 id 为新 id 再 update。
• 试玩 id 用 _cs_find_new.py <关键词> 在 media 库按名找（HOSTED_HTML）。

交付话术

报告：建了几组（系列/单）、覆盖多少视频、每组=对应视频+N条试玩、全部 PAUSED+已挂+CPP，附「组名→视频」清单；提示未过审/未上传的素材（可用全状态回扫 _b8_leftover.py 思路归类 REJECTED/未上传）。等用户说「开启」再跑第 6 步。