媒体投放 AI 助手 (media-ads-skill)
配合 Claude Code 使用的广告投放工具包，支持 Meta 广告和小红书聚光平台。
用户快速上手指南：点击查看在线教程
架构概览
lib/ ← 核心业务逻辑（可复用层）
├── creator_*.py ← creator: Codex 11字段 → 视频脚本+图文文案
├── content_*.py ← content-creator: 竞品爬取+IG研究+视频分析
├── meta_*.py ← media-buyer: Meta 广告执行
├── xhs_*.py ← media-buyer: XHS 聚光执行
├── analysis_*.py ← data-analysis: 9个分析模块
├── notebooklm_client.py ← codex/consult 共用: NotebookLM API 客户端
├── scaffold_builder.py ← skill-gen: 纯函数模板生成（零 I/O）
└── ...
cli/ ← CLI 入口（参数解析 + 调用 lib）
├── creator.py ← creator CLI
├── codex.py ← codex CLI
├── consult.py ← consult CLI
├── data_analysis.py ← data-analysis CLI
├── media_buyer_meta.py ← media-buyer Meta CLI
├── media_buyer_xhs.py ← media-buyer XHS CLI
├── content_creator.py ← content-creator CLI
└── skill_gen.py ← skill-gen 脚手架 CLI
skills/ ← Claude Code Skill 定义
├── codex/ ← 策略生产
├── creator/ ← 创意执行
├── consult/ ← 投放咨询
├── media-buyer/ ← 广告执行（meta/ + xhs/）
├── content-creator/ ← 竞品研究
├── data-analysis/ ← 数据分析
├── token-setup/ ← Token 配置
└── skill-gen/ ← Skill 脚手架生成器
config/ ← 配置文件
├── notebooks.json ← NotebookLM notebook IDs
├── prohibited_words.json ← Meta 禁用词
└── framework_strategies.json ← 创意框架映射
tests/ ← 测试（只测 lib/，不测 scripts/）
output/codex/ ← Codex 阶段输出（.gitignored）
核心原则：业务逻辑写在 lib/，cli/ 只做参数解析 + 调用 lib 函数 + 格式化输出。
八板斧 Skills 总览
| Skill | 层级 | 功能 | 输入 | 输出 |
|---|
| content-creator | 研究层 | 竞品研究 + IG研究 + 市场分析 + 视频创意分析 | 关键词/行业 | 竞品报告+分析报告 |
| data-analysis | 分析层 | 数据分析 + 诊断（10模块） | 时间范围 + 北极星 | 报告 + 行动清单 |
| media-buyer | 执行层 | 广告执行（Meta + XHS，不写文案） | 行动清单/指令 | dry-run → 执行 |
| codex | 策略层 | 策略生产 11字段 | 17字段客户信息 | NotebookLM → Codex |
| creator | 创意层 | 创意执行（Codex 3-5变体 + 日常文案 + 脚本 + 批量生产） | Codex 11字段 或 产品名 | 视频脚本 + 图文文案 |
| consult | 咨询层 | Meta 投放咨询（12类场景） | 投放问题 | 知识库查询结果 |
| token-setup | 配置 | Token 获取引导 | — | 配置指导 |
| skill-gen | 扩展 | 生成新 skill 骨架 | 自然语言描述 | SKILL.md + scripts/ + lib/ + tests/ |
Skill 工作流
创意链路（新客上线）：
content-creator → codex → creator → media-buyer
（竞品研究） （策略） （创意） （CT 发布）
日常闭环（每周优化）：
data-analysis → media-buyer + consult
（诊断报告） （执行） （随时问策略）
安装
1. 从 Release 下载 zip
从 GitHub Release 下载 media-ads-skill-latest.zip，解压到 home 目录即可：
直接下载 media-ads-skill-latest.zip
unzip media-ads-skill-latest.zip -d ~
解压后会得到：
~/.claude/skills/{8 skills}/ # Claude Code
~/.agents/skills/{8 skills}/ # Codex 当前用户级 skills 路径
~/.codex/skills/{8 skills}/ # Codex 兼容路径
~/media-ads-skill/ # uv 管理的完整 CLI 工具项目
latest Release 只提供一个 zip：
media-ads-skill-latest.zip
Release 标题和说明中会写明日期版本，例如 media-ads-skill v2026.05.23.123。不要下载 GitHub 自动生成的 Source code zip。
2. 安装 uv
curl -LsSf https://astral.sh/uv/install.sh | sh
3. 确认 CLI 可用
cd ~/media-ads-skill
uv run media-buyer --help
uv run data-analysis --help
uv run content-creator --help
agent 使用本项目时也应先进入 ~/media-ads-skill，再通过 uv run <command> 调用 CLI：
cd ~/media-ads-skill
uv run media-buyer meta campaign list --account-id act_xxx
uv run data-analysis full-report --help
uv run consult --question "CTR 低怎么办？"
4. 配置环境变量
cp .env.example .env
# 编辑 .env 填入 META_ACCESS_TOKEN、META_ACCOUNT_ID 等所需配置
5. 从源码构建 release zip
cd ~/media-ads-skill
scripts/package-skills.sh --output dist/media-ads-skill-latest.zip
6. 自动化打包与发布 (GitHub Actions)
本项目已集成 GitHub Actions。每当你将代码推送到 main 分支时，系统会自动执行以下操作：
- 自动打包：生成
media-ads-skill-latest.zip。
- 自动发布：更新 GitHub 上的 Latest Release。
- 自动校验：确认 zip 内有 8 个 skill × 3 套路径，并排除
input/、output/、data/、tests/、.env 等本地产物。
- 自动更新文档：自动将
docs/ 和预览页面部署到 GitHub Pages。
- 激活方法：请前往仓库
Settings -> Pages，将 Source 改为 GitHub Actions。
开发指南
代码风格
- 不可变数据：Pydantic 模型使用
frozen=True
- 错误处理：显式处理每一层错误，不吞异常
- 文件组织：高内聚低耦合，200-400 行/文件，最多 800 行
测试
# 运行全部测试（962 tests）
uv run pytest tests/ -v
# 运行单个测试文件
uv run pytest tests/test_content_scraper.py -v
# E2E 测试
uv run pytest tests/e2e/ -v
# 覆盖率报告
uv run pytest tests/ --cov=lib --cov-report=term-missing -q
# 代码检查
uv run ruff check .
uv run ruff check . --fix
添加新 Skill
用 skill-gen 自动生成骨架，再迭代完善：
