# 广告素材竞争力系统 — 项目总览

最后更新：2026-03-31

---

## 系统目标

**为广告优化师源源不断提供有竞争力的广告素材。**

完整链路：抓取 → 入库 → 标注 → 分析 → Brief 生成 → （素材制作） → （投放验证） → 反馈闭环

---

## 系统全景

```
┌─────────────────────────────────────────────────────────────────────┐
│                        广告素材竞争力系统                            │
│                                                                     │
│  ① 素材抓取          ② 素材库           ③ 标注分析                  │
│  creative-library/    creative-library/   ad-creative-system/       │
│  scripts/             db/creatives.sqlite                           │
│                                                                     │
│  ④ Brief 生成        ⑤ 素材制作          ⑥ 投放验证                 │
│  ad-creative-system/  [未建设]            [未建设]                   │
│                                                                     │
│  ⑦ 反馈闭环                                                        │
│  [未建设]                                                           │
│                                                                     │
│  ─── 基础设施 ───                                                   │
│  gemini-proxy/        watchdog 系统       share 系统                │
│  LLM 适配层           后台任务监控        文件分享                   │
└─────────────────────────────────────────────────────────────────────┘
```

---

## ① 素材抓取 — `~/creative-library/`

**定位：从各广告平台抓取竞品素材，是整个系统的原料入口。**

### 已覆盖平台

| 平台 | 脚本 | 方式 | 已抓国家 | 当前库存 |
|------|------|------|----------|----------|
| TikTok Creative Center | `fetch-tiktok-cdp.js` | Playwright CDP 拦截 API | MX, CO, KE, NG | ~650 条 |
| Meta Ad Library | `fetch-meta.js` | Playwright CDP + DOM 提取 | MX, CO, IN, TZ, UG | ~420 条 |
| Google Ads Transparency | `fetch-google-all.sh` | 多步流程（搜索→提取→导入） | MX, CO, IN, TZ, UG | ~96 条 |

### 抓取脚本清单

| 脚本 | 用途 |
|------|------|
| `scripts/fetch-tiktok-cdp.js` | TikTok Top Ads 抓取（CDP 拦截 API 响应 + 视频下载） |
| `scripts/fetch-meta.js` | Meta Ad Library 抓取（DOM 提取 + 素材下载） |
| `scripts/fetch-google-step1-v2.js` | Google Ads Transparency 第一步：搜索广告主 |
| `scripts/fetch-google-step2.js` | Google Ads Transparency 第二步：提取素材 |
| `scripts/import-google.js` | Google 素材导入数据库 |
| `scripts/fetch-google-all.sh` | Google 全流程一键脚本 |
| `scripts/run-scraper.sh` | 统一后台抓取调度（Meta + TikTok 并行，自动启浏览器） |
| `scripts/start-scraper-browser.js` | 启动抓取用浏览器实例 |
| `scripts/start-scraper-chrome.sh` | 启动 Chrome 调试实例 |

### 辅助脚本

| 脚本 | 用途 |
|------|------|
| `scripts/score.js` | 统一评分（投放时长 40% + 平台指标 30% + 广告主规模 15% + 新鲜度 15%） |
| `scripts/dedup.js` | 感知哈希去重（图片 + 视频，跨平台匹配） |
| `scripts/video-phash.py` | 视频感知哈希计算 |
| `scripts/cross-platform-match.js` | 跨平台素材匹配 |
| `scripts/serve.js` | 本地素材浏览服务 |
| `scripts/probe-*.js` | 各平台 API / 抓取方案探测脚本（调研用） |

### 数据库

- 路径：`~/creative-library/db/creatives.sqlite`
- 主表：`creatives`（含平台字段、TikTok/Meta/Google 专属字段、评分、去重哈希）
- 辅表：`advertisers`（广告主信息）、`fetch_log`（抓取日志）
- 配置：`~/creative-library/db/config.json`（各平台国家、行业、关键词配置）

### 存储结构

```
~/creative-library/
├── raw/YYYY-MM/          # 原始素材文件（视频/图片）
├── thumbnails/           # 缩略图
├── db/creatives.sqlite   # 元数据库
├── db/config.json        # 抓取配置
├── exports/              # 导出文件
└── scripts/              # 所有抓取/评分/去重脚本
```

### 入口命令

```bash
# 全量抓取（Meta + TikTok 并行）
cd ~/creative-library && scripts/run-scraper.sh

# 只抓 TikTok
scripts/run-scraper.sh --tiktok-only

# 只抓 Meta
scripts/run-scraper.sh --meta-only

# 只抓某个国家
node scripts/fetch-tiktok-cdp.js --country=MX
node scripts/fetch-meta.js --country=IN

# Google 全流程
scripts/fetch-google-all.sh

# 评分（在入库时自动调用，也可单独跑）
node scripts/score.js

# 去重
node scripts/dedup.js --backfill
```

---

## ② 素材库 — `~/creative-library/db/`

**定位：所有抓取到的素材的统一存储和索引。**

是 ① 的产出，也是 ③ 的输入。

当前库存统计（截至 2026-03-31）：

| 平台 | 国家 | 数量 |
|------|------|------|
| tiktok | MX | 409 |
| tiktok | CO | 232 |
| meta | MX | 105 |
| meta | CO | 94 |
| meta | TZ | 95 |
| meta | IN | 76 |
| meta | UG | 48 |
| google | MX | 96 |
| 其他 | — | ~11 |
| **合计** | | **~1,166** |

---

## ③ 标注分析 — `~/.openclaw/workspace/ad-creative-system/`

**定位：对抓取到的素材做结构化标注、因子分析、模式总结。**

### 三个独立工作流

1. **标注（Labeling）** — 输入素材 → 输出结构化因子标签
2. **分析（Analysis）** — 输入标签 → 输出因子分析报告
3. **Brief 生成（Briefing）** — 输入分析 → 输出创意 brief

### 当前版本

- 标注体系：**V3**（已定版，Russell 确认为默认版本）
- 聚焦：TikTok × MX
- 已验证：290 条素材重标 + 50 样本稳定性测试

### 核心脚本

| 脚本 | 用途 |
|------|------|
| `run_labeling_workflow.py` | 标注工作流 |
| `run_analysis_workflow.py` | 分析工作流 |
| `run_brief_workflow.py` | Brief 生成工作流 |
| `run_pipeline.py` | 一键串联 |
| `enrich_multimodal.py` | 多模态增强（抽帧 + OCR + vision） |
| `tag_creatives.py` | LLM 标注 |
| `validate_labels.py` | 标签校验 |
| `analyze_factors.py` | 因子分析 |
| `generate_briefs.py` | Brief 生成 |
| `llm_adapter.py` / `provider_bridge.py` | LLM 适配层（支持 gemini / openai / anthropic） |
| `labeling_rules.py` | 标注规则定义 |
| `usage_logger.py` | Token / 成本记录 |

### 设计要点

- 支持 provider：`mock / gemini / openai / anthropic`
- 标注温度 `0.0`，强调稳定性
- OCR 保留 `raw / clean`
- 视频：抽 5 帧 → 选 3 帧高信息量
- `risk_level` 由 `risk_tags` 派生
- 支持 low-confidence 二次重标

### 入口命令

```bash
cd ~/.openclaw/workspace/ad-creative-system

# 标注
python3 scripts/run_labeling_workflow.py

# 分析
python3 scripts/run_analysis_workflow.py

# Brief
python3 scripts/run_brief_workflow.py

# 一键全流程
python3 scripts/run_pipeline.py
```

---

## ④ Brief 生成

已包含在 ③ 中，当前由 `generate_briefs.py` 实现。

输入：分析报告 / 指定因子组合
输出：创意 brief JSON

---

## ⑤ 素材制作 — 🚧 未建设

**这是当前系统最大的缺口之一。**

Brief 生成之后，目前没有自动化或半自动化的素材制作环节。
优化师拿到 brief 后，仍需手动找设计师 / 剪辑师制作。

### 未来可能方向
- AI 视频生成（Runway / Pika / Kling 等）
- AI 图片生成（Gemini / DALL-E / Midjourney）
- 模板化视频拼接（FFmpeg + 素材模板）
- 文案自动生成（已有 LLM 基础）
- 与设计工具集成（Canva API / Figma API）

---

## ⑥ 投放验证 — 🚧 未建设

**Brief / 素材做出来之后，缺少闭环验证。**

当前没有：
- 新素材投放后的效果追踪
- 素材 A/B test 结果回收
- "哪些 brief 产出的素材效果好"的反馈

### 未来可能方向
- 对接广告平台 API（Google Ads / Meta / TikTok）获取素材级效果数据
- 素材 ID ↔ brief ID 关联
- 效果数据回写到素材库
- 自动标记"高效素材"和"低效素材"

---

## ⑦ 反馈闭环 — 🚧 未建设

**把投放验证的结果反哺回标注和分析环节。**

当前没有：
- "效果好的素材有什么共同因子"的自动发现
- 标注体系的数据驱动迭代
- Brief 策略的效果验证

### 未来可能方向
- 效果数据 + 标签数据联合分析
- 自动发现高 ROI 因子组合
- 标注体系版本迭代的 A/B 验证
- Brief 推荐算法（基于历史效果）

---

## 基础设施

### Gemini Proxy — `~/.openclaw/workspace/gemini-proxy/`

Cloudflare Worker 中转代理，解决 Gemini API 区域限制。

- 透传请求到 `generativelanguage.googleapis.com`
- 可选鉴权（`X-Auth-Token`）
- CORS 支持
- 部署：`wrangler deploy`

### Watchdog 系统 — `~/.openclaw/workspace/scripts/watchdog_*.py`

后台任务监控框架。

| 脚本 | 用途 |
|------|------|
| `watchdog_launch.py` | 启动任务 + 同步拉起 watchdog |
| `watchdog_monitor.py` | 持续轮询日志/输出/进度 |
| `watchdog_register.py` | 注册 watchdog 状态 |
| `watchdog_refresh.py` | 刷新状态 |
| `watchdog_report.py` | 输出结构化报告 |
| `watchdog_state.py` | 查看状态 |

### 批次调度脚本

| 脚本 | 用途 |
|------|------|
| `start_creative_round.py` | 从 creative-library 抽样 → 标注 → 分析（带 watchdog） |
| `start_labeling_from_samples.py` | 从现成 JSON → 标注 → 分析（带 watchdog） |
| `export_recent_creatives.py` | 导出最近抓取的素材为标注输入 |

### 文件分享

| 组件 | 用途 |
|------|------|
| `share_server.py` | 本机 HTTP 静态文件服务（端口 18080） |
| `publish-share` | 按 profile 发布文件并返回链接 |
| `ai.openclaw.share-server.plist` | LaunchAgent 配置 |

### 已安装技能（`skills/`）

- `agent-browser` — 浏览器自动化
- `find-skills` — 搜索可用 skills
- `gemini-draw` — Gemini 图像生成/编辑
- `mem0` — 语义记忆层
- `openclaw-tavily-search` — Tavily 搜索
- `self-improving-agent` — 自我改进/learnings

### 调研资料库（`.firecrawl/`）

已积累的调研主题：
- TikTok Creative Center / API / internal API
- Meta Ad Library / GraphQL / 抓取方案
- Google Ads Transparency
- 创意评分 / 创意测试框架
- Cloudflare region / Gemini placement
- Adzviser 产品调研

---

## 系统成熟度总览

| 环节 | 状态 | 说明 |
|------|------|------|
| ① 素材抓取 | ✅ 可用 | TikTok / Meta / Google 三平台，5 国覆盖 |
| ② 素材库 | ✅ 可用 | SQLite + 评分 + 去重，~1166 条 |
| ③ 标注分析 | ✅ 可用 | V3 标注体系已定版，290 条验证 |
| ④ Brief 生成 | ✅ 可用 | 基于分析结果生成 |
| ⑤ 素材制作 | 🚧 未建设 | 优化师仍需手动制作 |
| ⑥ 投放验证 | 🚧 未建设 | 无效果数据回收 |
| ⑦ 反馈闭环 | 🚧 未建设 | 无数据驱动迭代 |
| 基础设施 | ✅ 可用 | LLM 代理 / watchdog / 分享 / 调度 |

---

## 当前系统缺什么（框架级缺口）

### 缺口 1：素材制作环节（⑤）
Brief 到成品素材之间是断裂的。优化师拿到 brief 后全靠人工。
这是"源源不断提供素材"最直接的瓶颈。

### 缺口 2：投放效果回收（⑥）
不知道产出的素材投放效果如何，无法判断系统产出质量。
没有效果数据，分析和 brief 就是"盲飞"。

### 缺口 3：反馈闭环（⑦）
没有"效果好的素材 → 共同因子 → 优化标注/分析/brief"的自动循环。
系统无法自我进化。

### 缺口 4：抓取自动化调度
`run-scraper.sh` 存在但没有接入定时任务。
目前靠手动触发，不是"源源不断"。

### 缺口 5：素材库前端 / 查询界面
优化师没有一个可以浏览、搜索、筛选素材的界面。
当前只能通过 SQLite 查询或脚本导出。

### 缺口 6：竞品监控与趋势追踪
只有"抓一批"的能力，没有"持续监控竞品动态"的能力。
比如：某竞品新上了什么素材、某类素材最近在涨、某个 hook 类型开始流行。

### 缺口 7：多国家标注体系适配
V3 在 MX 验证过，其他国家（IN/CO/TZ/UG）还没有做适配验证。
语言、文化、金融术语差异可能影响标注质量。

---

## 建议优先级（如果要推进）

1. **抓取定时化** — 最小成本，最大收益，让"源源不断"先跑起来
2. **素材库查询界面** — 让优化师能自己看素材，不依赖技术
3. **素材制作辅助** — 哪怕先做模板化/半自动，也比纯手工强
4. **投放效果回收** — 需要对接广告平台 API，工程量较大但价值极高
5. **反馈闭环** — 在有效果数据之后才有意义
6. **多国家适配** — 按业务优先级逐国验证
7. **竞品监控** — 在抓取定时化之后自然延伸