蝉妈妈数据采集 (chanmama-data-collector)

批量采集蝉妈妈平台抖音话题热点视频数据的 AI Agent Skill。

适用于任何支持浏览器自动化的 AI Agent 框架（如 OpenClaw、Claude Code、Cursor、AutoGPT 等），也可作为独立参考文档手动执行。

功能

• 📊 基础数据：排名、标题、博主、粉丝数、点赞/评论/转发/互动量、播放量、时长、发布时间
• 👥 观众画像：性别分布、年龄分布（18-23/24-30/31-40/41-50/>50）
• 📝 AI提文案：自动提取视频口播文案（通过蝉妈妈AI功能）
• 🎬 视频下载：批量下载无水印抖音视频
• 📁 Excel输出：所有数据合并为一份结构化Excel表格

前提条件

• 浏览器已登录蝉妈妈运营版账号
• 能在浏览器中执行 JavaScript（通过 Agent 浏览器插件、Playwright、Puppeteer 等）
• Python 3 + pandas + xlsxwriter（用于生成Excel）

使用方式

作为 AI Agent Skill

OpenClaw：将本目录放到 ~/.openclaw/plugin-skills/ 或在配置中注册路径。

其他 Agent 框架：将 SKILL.md 作为 system prompt 或工具说明注入，Agent 会按流程自动执行。

通用触发词：

获取蝉妈妈的标题是"夏季穿搭"的数据
抓蝉妈妈话题"ootd穿搭"的视频数据
下载蝉妈妈话题"母亲节"前100个视频

作为参考文档手动使用

即使不用 AI Agent，references/api-guide.md 也是完整的蝉妈妈 API 逆向文档，包含：

• 所有 API 端点和请求格式
• 浏览器 Console 可直接粘贴执行的代码
• AI提文案的完整异步流程
• 抖音无水印视频下载方法

采集流程

1. 确认登录 — 检查蝉妈妈登录状态，获取话题 subject_id
2. 视频列表 — API 获取话题下热点视频（默认100条，~5秒）
3. 观众画像 — 批量获取性别/年龄分布（~2分钟/100个）
4. AI提文案 — 调用蝉妈妈AI提取口播文案（~30-60秒/个，可选）
5. 视频下载 — 浏览器提取抖音视频URL并下载（~3-5秒/个，可选）
6. 生成Excel — 合并所有数据输出 xlsx

目录结构

chanmama-data-collector/
├── README.md             # 项目说明
├── SKILL.md              # Agent skill 指令（精简版流程）
├── references/
│   ├── api-guide.md      # API端点、请求格式、完整代码示例
│   └── lessons.md        # 经验教训、踩坑记录、注意事项
└── scripts/
    └── gen_excel.py      # Excel生成脚本（可独立运行）

脚本独立使用

scripts/gen_excel.py 可脱离 Agent 独立运行：

python3 scripts/gen_excel.py \
  --videos /tmp/videos.json \
  --personas /tmp/personas.json \
  --copywriting /tmp/copywriting.json \
  --output "蝉妈妈_话题名_完整数据.xlsx"

已知限制

限制	说明
观众画像额度	运营版每日100次，用完需等次日重置
AI提文案	纯AI特效/图文/BGM类视频无口播内容，返回空属正常
视频下载	必须通过浏览器（抖音有JS加密，无纯API方案）
登录	过期需手动在浏览器重新登录（无法自动化）
浏览器超时	单次evaluate约20秒超时，观众画像需分批≤25个

API额度

API	消耗	限制
视频列表 (/v1/subject/relationAwemes)	无	无限制
观众画像 (/v1/aweme/personas)	每日详情页额度	运营版100次/天
AI提文案/爆点拆解	AI积分	独立额度

额度每日0点重置。

贡献

欢迎提 Issue 和 PR。如果蝉妈妈更新了 API 或页面结构导致采集失败，请在 Issue 中说明具体报错信息。

License

MIT