tiktok-search

Files (3)

• SKILL.md
• search.mjs · scripts/
• search-fields.md

SKILL.md (first lines)

## 执行

**前置：** chrome-devtools 守护进程已启动。

```bash
node ~/Developer/tiktok-web-skills/skills/tiktok-search/scripts/search.mjs "<keyword>"
```

脚本自动：

1. 导航到 `https://www.tiktok.com/search?q={keyword}&t={timestamp}`
2. 轮询 `list_network_requests` 直到出现 `/api/search/general/full/` 响应
3. 等请求 status 转 200 后，用 `get_network_request --responseFilePath` 拿 body（Brotli 已自动解压）
4. 按 `--profile` 投影字段 → 输出文本或 JSON

### 可选 flag

| flag | 默认 | 说明 |
|------|------|------|
| `--profile summary\|detail\|trace` | `summary` | 视图模板 |
| `--fields a,b,c` | — | 自定义字段（dot path，覆盖 profile） |
| `--json` | false | 输出 JSON 而非文本 |
| `--limit N` | 20 | 最多返回 N 条 |

### PROFILES 视图

| profile | 用途 | 字段 |
|---------|------|------|
| `summary` | 拿 ID 列表（80% 场景） | `item.id` |
| `detail` | 用户视图：描述 / 作者 / 互动数据 / 封面 / 时长 | `item.id` / `item.desc` / `item.createTime` / `item.author.{nickname,uniqueId,verified}` / `item.stats.{digg,comment,share,play,collect}Count` / `item.video.{duration,cover}` |
| `trace` | 链式调用：拿 `secUid` 喂给后续 skill（text 输出带 `video=` 前缀区分作者 ID） | `item.id` / `item.author.{uniqueId,secUid,nickname}` |

### 按需取字段（推荐用法）

需要 PROFILES 没覆盖的字段（视频直链 / 音乐 URL / 作者签名等），用 `--fields` + `--json`：

```bash
# 纯视频 ID 列表（默认 summary profile）
node search.mjs "<keyword>"

# 自定义字段投影（路径从 search-fields.md 查，dot path 语法以 item. 开头）
node search.mjs "<keyword>" --fields <item-field-path-1>,<item-field-path-2>,<item-field-path-3> --json
```

完整字段路径见 [`search-fields.md`](search-fields.md)（按需加载，agent 需要时读取）。

## 反例（不要这么做）

| 错 | 为什么 |
|---|---|
| `JSON.parse(stdout)` 不加 `--json` | 默认 text 输出是 `1. {...}` 行格式；agent 解析会爆 |
| `--limit 1000` 期望拿更多 | 脚本只取首屏（与 `has_more` 无关），API 单页就 20 条左右 |
| 想"翻页"搜更多 → 用 cursor | 脚本**未实现**翻页；要更多结果只能换关键词 |
| 一次传多个关键词 `"foo bar baz"` | 整串当 1 个 keyword 拼 URL；想搜多关键词跑多次 |
| 短时间重复跑同 keyword | 触发 TikTok 限流 → `data=[]` 或 `status_code!=0`；间隔 30s+ |
| 把脚本当登录态校验 | 搜索不强制登录，未登录也能跑；结果少先去 `tiktok-ensure-login` |

## 已知陷阱

1. **Brotli 解压** — response header 是 `content-encoding: br`，**chrome-devtools 已经自动处理**，body 是明文 JSON。不要再手动 zlib 解压（douyin search.mjs 的 `decodeChunkedBody` 不适用）
2. **大 body（240KB+）** — 必须走 `responseFilePath` + `readFileSync`，不能依赖 inline（`detail.networkRequest.responseBody` 字段是空的）
3. **status 必须先于 body** — `listReqs` 里请求 `status=pending` 时 `getReq` 拿不到 body；脚本里有 `waitForRequestDone` 轮询直到 status=200
4. **翻页未实现** — 脚本只取首屏（与 douyin 一致）；后续可扩展 cursor 翻页
5. **空结果（`data=[]`）** — 可能关键词无结果 / verify_check 反爬；建议到 Chrome 手动确认后重跑
6. **Web ID 反爬参数** — URL 里的 `X-Dynosaur` / `X-Bogus` / `X-Gnarly` / `msToken` / `verifyFp` 必须由浏览器自动注入；脚本不构造这些，依赖 chrome-devtools 的 nav 触发真实请求
7. **不要传 `--search` 给 chrome-devtools** — CLI 不支持 URL 关键词过滤，脚本内部用 `requests.filter(r => r.url.includes('/api/search/general/full/'))` 处理
8. **未登录也能搜** — TikTok 搜索结果对未登录用户也开放，但个性化推荐少；脚本不强制 `ensure-login`
9. **不要用 `--profile full`** — 已移除该 profile。需要冷门字段走 `--fields a,b,c --json`，避免一次性 240KB 输出爆 token

## 字段路径

完整字段路径见 [`search-fields.md`](search-fields.md)，agent 按需加载。

## MCP 兜底

如果中间层脚本失败（守护进程未启动 / API 路径变化 / 等待超时），手动走 `lib.mjs` 的 wrapper 拿数据：

1. `nav('https://www.tiktok.com/search?q={keyword}&t={ts}')`
2. 轮询 `listReqs({pageSize: 500})`，用 `reqs.filter(r => r.url.includes('/api/search/general/full/'))` 找到请求
3. 等 `status !== 'pending'`，再 `getReq(reqid, {responseFilePath: '/tmp/resp.json'})`
4. `readFileSync` + `JSON.parse`，字段路径查 [`search-fields.md`](search-fields.md)

From 271642183/tiktok-web-skills, MIT.

More from 271642183/tiktok-web-skills