🤖 让 AI 帮你采集 TikTok 数据

如果上面的"一句话"你的 AI 不理解，也可以直接复制完整 Skill 文本粘贴给它。

---
name: tiktok-scraper
description: 🎁 永久免费 · 注册即享 1000万条额度 · 1 个并发窗口。零安装 skill：打开浏览器 URL，扩展 + 登录态自动完成。TikTok 视频搜索、达人发现、标签采集、达人资料、用户视频导出 CSV。适用于 Claude Code、Codex、Cursor、Windsurf、ChatGPT（任何 AI 客户端）。无需 Python 包、无需凭证、无需无头浏览器。
---

# TikTok Scraper

> 🎁 永久免费 · 注册即享 1000万条额度 · 免费用户 1 个并发窗口（会员支持更多并行窗口）

## 这是什么？

一个让**任何 AI 助手**（Claude Code、Codex、Cursor、Windsurf、ChatGPT…）采集 TikTok 数据的 skill——视频搜索、达人发现、标签采集、达人资料、指定用户视频——并返回 CSV。无需安装 Python 包、配置无头浏览器或管理凭证。AI 编排：生成 taskId → 在用户浏览器打开 URL → 轮询 → 下载结果。

**为什么用浏览器 + 扩展？** 采集在用户的真实 TikTok 会话中执行（已登录，装有 MonsterGet 扩展），这是账号防封的核心保障。

**首次使用（约 2 分钟）：** ① 在 monsterget.com 注册免费账号并安装扩展 ② 在浏览器登录 TikTok。之后可重复使用。

## 架构

```
AI ──1. GET /api/agent/generate-task-id ──▶ {"taskId":"<uuid>"}
AI ──2. 打开浏览器页面 {pagePath}?auto=1&agentTaskId={taskId}&{param}=...&count=N
     页面 + 扩展自动在 TikTok 中执行采集
AI ──3. GET /api/agent/delivery/task/{taskId}/status 轮询
AI ──4. GET /api/agent/delivery/task/{taskId}/data 下载 CSV
```

## 五种采集类型

> ⚠️ **此表可能滞后。** 新增爬虫不会自动同步。执行前先获取最新列表：
> ```bash
> curl -s https://monsterget.com/api/agent/scrapers
> ```
> 以返回的 `type` + `page` + `param` 为准。

| 类型     | 页面路径              | 参数       | 默认 | 最大 |
|---------|----------------------|-----------|------|------|
| 视频搜索 | /tiktok-search-video  | query     | 50   | 300  |
| 达人搜索 | /tiktok-search-user   | query     | 30   | 300  |
| 标签搜索 | /tiktok-tag           | query     | 30   | 300  |
| 用户视频 | /tiktok-user-videos   | username  | 50   | 300  |
| 达人资料 | /tiktok-profile       | username  | 1    | 1    |

username 接受 @name 或完整主页 URL（服务器自动标准化）。

## ⚡ 自动化规则（AI 必读）

**打开浏览器即自动执行，无需等待用户确认。** 以下是关键规则：

1. **Open + poll 一步完成。** 执行浏览器打开命令后立即开始轮询。不要在两者之间询问用户。
2. **不要等用户确认。** 页面打开后自动运行——你已持有 taskId，页面会用这个 taskId 创建任务。
3. **轮询已经检测完成。** 当状态为 `ready` 或 `failed` 时轮询自动结束。
4. **批量采集无需中断。** 多个采集可以连续运行：打开 → 轮询 → 下载 → 下一个。
5. **已完成的任务释放并发槽位。** 只有 `pending`/`processing` 状态的任务才占配额。

## 执行流程

### Step 0 — 首次使用（第一次用时才需要）

如果用户第一次使用，先引导完成：
1. 打开 https://monsterget.com 注册并登录
2. 打开 https://monsterget.com/install 安装浏览器扩展
3. 在浏览器登录 https://www.tiktok.com

完成后做一次测试采集验证。

### Step 1 — 生成 taskId（零鉴权）

```bash
TASK_ID=$(curl -s https://monsterget.com/api/agent/generate-task-id | sed -n 's/.*"taskId":"\([^"]*\)".*/\1/p')
```

### Step 2 — 打开浏览器页面（fire-and-forget）

⚠️ **URL 必须用双引号包裹**，否则 & 会被 shell 截断参数。

Windows Edge: `start msedge "https://monsterget.com/tiktok-search-video?auto=1&agentTaskId=$TASK_ID&query=mike&count=10"`
Windows Chrome: `start chrome "URL"`
Mac: `open "URL"`
Linux: `xdg-open "URL"`

### Step 3 — 轮询状态（每 5 秒，最多 60 次）

```bash
curl -s https://monsterget.com/api/agent/delivery/task/$TASK_ID/status
```

| status | 含义 |
|--------|------|
| processing | 仍在采集，继续轮询 |
| ready | 数据就绪，马上下载 |
| downloaded | 已被取走 |

### Step 4 — 下载 CSV（一次性，24 小时有效）

```bash
curl -OJ https://monsterget.com/api/agent/delivery/task/$TASK_ID/data
```

### 批量达人资料

一次采集多个达人资料：
```bash
start msedge "https://monsterget.com/tiktok-profile?auto=1&agentTaskId=$TASK_ID&usernames=mike,jenifer,tiktok&count=3"
```

CSV 包含每个达人的聚合统计数据。

### 多次采集连续运行（批量模式）

当用户要求采集多个数据时，连续执行，不要在每个任务之间停止：

1. TASK_ID = generate-task-id
2. 打开页面 1（fire-and-forget）
3. 轮询直到 ready
4. 下载 CSV 1
5. TASK_ID = generate-task-id
6. 打开页面 2 ← 不要等用户
7. 轮询 → 下载
... 重复 ...

## 错误处理

| 症状 | 原因 | 处理 |
|------|------|------|
| curl 连接失败 | 平台不可达 | 确认 monsterget.com 可访问 |
| status 404 delivery_not_found | taskId 错误，或上一任务还在跑（429 拦截、页面自动重试超时） | 若确认有任务在跑则等其 ready/failed；确认无任务才重新生成 taskId |
| status 409 not_ready | 数据未就绪 | 继续轮询 |
| status 410 already_downloaded | 已下载过 | 重新采集 |
| status 429 too_many_concurrent | 上一任务还在跑（pending/processing） | 页面会自动重试，无需处理；任务完成即释放槽位 |
| status 402 insufficient_credits | 额度用完 | 注册送 1000万条，几乎用不完 |
| 页面显示"扩展未就绪" | 扩展未安装 | 引导安装扩展，刷新页面 |
| 页面显示"请先登录" | 未登录平台 | 引导登录，刷新页面 |
| 浏览器打不开 | AI 在沙箱中 | 用户需要在本地 AI 终端（Claude Code CLI 等）中使用 |

## 约束

- 必须使用安装了扩展 + 已登录的浏览器
- 免费用户 1 并发窗口（日常足够）；会员最多 10 个并行窗口
- 页面必须保持打开直到采集完成，否则无法上报数据
- CSV 下载后 24h 过期，只能下载一次
- AI 不要手动 POST /api/agent/scrape——页面会自动用你的 taskId 创建任务

聊天型 AI 可能无法直接执行采集操作（无法打开你的本地浏览器），但把链接发给它让它指导你操作还是可以的：