# Tiktok Research

> 通过怪奇信息查询和分析TikTok视频、达人、评论和品类机会研究。用户提到TikTok或海外版抖音 数据分析、市场调研、选品、找品、爆品、趋势、市场容量、竞争结构等数据形成经营判断时使用，依据TikTok真实返回的数据形成分析结论。当用户任务需要的数据有TikTok视频、抓博主作品、看TikTok评论、做市场调研分析、做竞品/对标账号监控、短视频选题调研、评论舆情分析、热点追踪、爆款挖掘时使用。触发词：TikTok搜索、TikTok评论、TikTok作品、博主作品、市场调研、对标账号、TikTok竞品分析、TikTok数据分析、短视频运营、TikTok舆情监控、热点追踪、爆款挖掘、tiktok search、tiktok work、douyin comments。

- Skill: `why20261/tiktok-research` (Agent Skill, multi-file: 4 files)
- Install (CLI): `npx skillmds@latest add why20261/tiktok-research`
- Raw SKILL.md: https://api.skillmd.com/api/skills/why20261/tiktok-research/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Research & Search
- License: MIT
- Author: why20261 (https://skillmd.com/u/why20261)
- Updated: 2026-09-22
- Page: https://skillmd.com/skills/why20261/tiktok-research

---


# 🚀 TikTok数据分析与市场调研

## 1. 能力概览

> 💡**一句话价值**：一个口语化指令拿到TikTok公开的视频/作者/评论数据，直接输出结构化JSON——做数据分析、市场调研、爆款选题、对标账号监控、评论舆情分析、热点追踪，不用再手动刷TikTok。

| 能力       | 入口脚本                        | 必填参数                 | 返回                                                |
| ---------- | ------------------------------- | ------------------------ | --------------------------------------------------- |
| 关键词搜索 | `scripts/tiktok/search-cli.js`  | `--keyword`              | 作品列表：作者、点赞/评论/分享/收藏、标签、播放地址 |
| 博主作品   | `scripts/tiktok/post-cli.js`    | `--url`（主页或用户名）  | 该博主公开作品列表（支持最新 / 最热排序）           |
| 视频评论   | `scripts/tiktok/comment-cli.js` | `--url`（视频链接或 ID） | 评论正文、评论者、点赞数、回复数                    |

> **前置条件**：必须在**技能根目录**执行，且环境变量 `GUAIKEI_API_TOKEN` 已配置。未配置时所有命令返回退出码 `3`、`error_code=AUTH_REQUIRED`——此时**直接提示用户配置 Token，不要重试、不要换参数**。

---

## 2. 何时调用 / 何时不调用

### 2.1 应该调用

- 用户要查 **TikTok** 的公开内容（视频 / 图文 / 作者 / 评论 / 趋势）。
- 用户要做**爆款选题调研、竞品账号监控、红人筛选、评论舆情分析、内容风格拆解**。
- 用户已给出 TikTok 关键词、视频链接、博主主页链接，希望拿到结构化数据。
- 用户拿到数据后还要继续做总结、对比、排序、聚类、出报告 / 表格。

### 2.2 不应调用

- 用户只要文案 / 标题 / 脚本，没有要查 TikTok 数据。
- 平台不是 TikTok，而是其他平台的（抖音、小红书、B 站、微博、公众号）→ 路由到对应技能。**本技能只处理 TikTok。**
- 要求登录态、私密、隐藏数据 → 不支持。
- 既有关键词又有可识别链接且目标不明 → **先追问，不要猜**。

### 2.3 能力边界（明确不做）

发布 / 点赞 / 评论 / 关注 / 私信等**写操作**一律不支持；不登录任何账号；不采集手机号、位置、私信等隐私字段；不替用户做营销决策——职责是把数据拿回来，分析交给上层。

---

## 3. 调用路由（先判断，再执行）

| 用户意图                                           | 脚本          | 判定关键词                                    |
| -------------------------------------------------- | ------------- | --------------------------------------------- |
| 搜关键词、找某类内容、找爆款                       | `search-cli`  | 搜索 / 找 / 关键词 / 爆款 / 最火              |
| 看某博主 / 达人 / 网红的作品、主页、账号、近期发布 | `post-cli`    | 作品 / 主页 / 账号 / 博主 / 达人 / 网红 / KOL |
| 看某条视频的评论、留言                             | `comment-cli` | 评论 / 留言 / 评论区的观点                    |

### 3.1 消歧义规则（必须遵守）

1. **单独出现"视频"二字，不要默认归 `post-cli`**。
   - 有"关键词"且无"评论" → `search-cli`（用户想搜这类视频）。
   - 明确"这个视频的评论 / 留言" → `comment-cli`。
   - 只有出现"作品 / 主页 / 账号 / 博主 / 达人" → `post-cli`。
2. **评论优先级高于作品**：若给的链接是 `/video/<id>` 且问的是评论 → `comment-cli`；若问的是"这个人的作品" → `post-cli`（用 `@username`）。
3. 用户给了 `/video/<id>` 链接却要"作品列表" → 先确认是要该作者的作品还是该视频的评论。

### 3.2 参数推断规则

| 用户说法                      | 参数                       |
| ----------------------------- | -------------------------- |
| 相关度 / 默认                 | `--sort 0`（搜索）         |
| 最火 / 点赞最多 / 爆款 / 最热 | `--sort 1`（搜索）         |
| 最近发的 / 按时间倒序         | `--sort 0`（作品）         |
| 最热的作品                    | `--sort 1`（作品）         |
| 一天 / 24 小时                | `--time 1`                 |
| 一周 / 7 天                   | `--time 7`                 |
| 一个月 / 三个月 / 半年        | `--time 30` / `90` / `180` |
| N 条 / 前 N 条 / 要 N 个      | `--limit N`                |

默认值：`sort=0`、`time=0`、`limit=10`。

> ⚠️ **搜索的 `--sort` 与作品的 `--sort` 不要混用**：前者是"相关度 / 最多点赞"，后者是"最新 / 最热"。

**任何参数被非法值回退，都会出现在输出 JSON 的 `warnings` 数组里，必须回显给用户，不要当成原样生效。**

---

## 4. 执行方式

> 完整参数说明见 [references/options.md](references/options.md)；字段级 Schema 见 `assets/` 下的 6 个 JSON Schema（draft-07）。

```bash
# 关键词搜索
node scripts/tiktok/search-cli.js --keyword "AI" --sort 1 --limit 20
node scripts/tiktok/search-cli.js --keyword "AI model" --time 7 --limit 20

# 博主作品
node scripts/tiktok/post-cli.js --url "https://www.tiktok.com/@username" --limit 30
node scripts/tiktok/post-cli.js --url "https://www.tiktok.com/@username" --sort 1 --limit 30

# 视频评论
node scripts/tiktok/comment-cli.js --url "https://www.tiktok.com/@username/video/1234567890123456789" --limit 40
```

**可用的输入形态**

- 博主：`https://www.tiktok.com/@username`、带参数链接 `https://www.tiktok.com/@username?lang=en`、或直接 `author_sec_uid`
- 视频：`https://www.tiktok.com/@username/video/<id>`、短链、或直接作品 `<id>`

**执行纪律**

- 只把 **stdout** 当机器可读输出（纯 JSON）；banner / 进度 / 错误日志都在 **stderr**，不要混在一起解析。
- 单次 `--limit` 建议 **≤ 1000**。
- 不要因为一次空结果就自动放宽条件重试：**先把空结果告诉用户**，由用户决定是否换关键词 / 放宽 `--time`。

---

## 5. 输出契约（AI 解析必读）

所有入口输出**同一个信封**，成功与失败结构一致：

```json
{
  "status": "success | empty | error",
  "error_code": "OK | NO_MATCH | AUTH_REQUIRED | INVALID_KEYWORD | ...",
  "message": "人类可读说明",
  "timestamp": "2026-09-16 21:00:00",
  "request": {
    "command": "search",
    "keyword": "AI",
    "sort": 1,
    "time": 0,
    "limit": 20
  },
  "metadata": {
    "skill_version": "1.0.0",
    "skill_name": "tiktok-creator-videos",
    "runtime_version": "22.22.2",
    "execution_time": 8421
  },
  "results": [],
  "warnings": ["数量 99999 无效，已回退为 10"]
}
```

### 5.1 `status` 语义

| status    | 含义                       | `results` | 该怎么做                                   |
| --------- | -------------------------- | --------- | ------------------------------------------ |
| `success` | 拿到数据                   | 非空数组  | 直接分析                                   |
| `empty`   | **请求成功，但确实没数据** | `null`    | 视为有效结果，告知用户没搜到，不要当成失败 |
| `error`   | 请求失败                   | `null`    | 按 `error_code` 处理，不要编造数据         |

### 5.2 退出码

| 退出码 | 含义                                          | Agent 行为                                           |
| ------ | --------------------------------------------- | ---------------------------------------------------- |
| `0`    | 成功（`success` 或 `empty`）                  | 继续分析                                             |
| `1`    | 运行错误（网络 / 超时 / 接口异常 / 参数非法） | 展示 `message`，询问用户是否换参数重试               |
| `3`    | `AUTH_REQUIRED`：Token 缺失或格式错误         | **立即停止**，提示配置 `GUAIKEI_API_TOKEN`，禁止重试 |

### 5.3 错误码处理

| error_code        | 处理方式                                                 |
| ----------------- | -------------------------------------------------------- |
| `AUTH_REQUIRED`   | 停止并提示配置 Token。禁止重试、禁止改参数绕行           |
| `INVALID_KEYWORD` | 提示关键词需 2–100 字符、不能含 `< > " ' &` 与 http 链接 |
| `NO_MATCH`        | 有效空结果，建议换关键词或放宽 `--time`                  |
| `NETWORK_ERROR`   | 已内置重试；仍失败则提示检查网络，最多手动重试 1 次      |
| `TIMEOUT_ERROR`   | 已内置重试；仍失败则建议降低 `--limit` 后重试            |
| 其它（服务端码）  | 原样展示 `error_code` + `message`，不要自行猜测含义      |

### 5.4 `warnings` 必须回显

当传入参数不合法被自动回退时（如 `--sort 9`、`--limit 99999`），`warnings` 数组会说明"哪个参数被改成了什么"。**必须原样转告用户**，不能假装参数按原值生效了。

### 5.5 禁止行为

- ❌ 不编造、不补全、不凭记忆填充任何数据。
- ❌ 收到 `AUTH_REQUIRED` 后不重试、不换脚本、不改参数。
- ❌ 不把 `empty` 当成"用户要的内容不存在"以外的结论（不等于接口坏了）。
- ❌ 不在用户未同意时自动放宽搜索条件。

---

## 6. 结果消费建议（提升最终交付质量）

拿到 `results` 后，按用户原始目标组织输出，而不是原样吐 JSON：

- **选题调研** → 按 `digg_count` 降序取 Top N，归纳标题句式 / 标签 / 时长分布规律
- **竞品监控** → 按 `create_time` 排发布节奏，统计更新频率与爆款占比
- **评论洞察** → 按 `digg_count` 取高赞评论做观点聚类，输出正负向占比
- **红人筛选** → 交叉 `author_nickname` / 平均互动 / 发布频次，给出候选清单
- **需要留档** → 每次运行会自动写入日志文件，路径在 stderr 的"已保存到 …"一行

---

## 7. 安全与合规（Trust）

- **只读**：不登录 TikTok 账号，不执行发布 / 点赞 / 评论 / 关注 / 私信等任何写操作，无风控封号风险。
- **最小权限**：仅请求业务所需的一个环境变量 `GUAIKEI_API_TOKEN`；不读取本地其他文件、不写技能目录以外路径（日志写入系统临时目录）。
- **凭据保护**：Token 只从环境变量读取，不写入 stdout、不写进日志、不出现在错误信息里。
- **数据外发范围（务必知悉）**：调用时会向 `https://www.guaikei.com` 发送：你的 **API Token**、**查询关键词**或**目标 URL/ID**，以及技能名与 Node 版本。除此之外不采集任何本地信息。
- **数据合规**：仅获取 TikTok 公开可见数据（昵称、公开作品、公开评论）。不含手机号、位置、私信等隐私字段。数据仅限个人 / 团队内部分析；对外发布或商用前请自行确认授权，并对用户昵称等做脱敏处理。
- **无第三方依赖**：仅使用 Node.js 内置模块（`https` / `fs` / `path` / `os` / `querystring`），无 npm 依赖、无远程脚本加载、无 `eval` / `child_process`。

---

## 8. 常见问题

| 现象                            | 原因与处理                                                                   |
| ------------------------------- | ---------------------------------------------------------------------------- |
| 退出码 3 / AUTH_REQUIRED        | Token 未配置或格式不对（需 16–256 位字母数字下划线连字符）                   |
| 搜索结果为空                    | 换更通用的关键词，或 `--time 0` 放开时间窗；`empty` 是正常结果不是错误       |
| 结果条数少于 `--limit`          | 服务端无可返回更多，或单次上限被截断；降到 ≤ 1000 分批取                     |
| 一直超时                        | 减小 `--limit` 后重试；脚本已内置指数退避重试                                |
| 想看"最热作品"却按时间倒序      | `post-cli` 要用 `--sort 1`                                                   |
| 参数没生效 / 结果与预期排序不同 | 检查输出里的 `warnings`，参数不合法时会被静默回退为默认值                    |
| 日志文件在哪                    | 见 stderr 中"已保存到 …"那一行（系统临时目录 `tiktok-guaikei/logs/<日期>/`） |

## 9. 环境与支持

- 环境：Node.js ≥ 16.14.0，Windows / macOS / Linux 全平台；必需 `GUAIKEI_API_TOKEN`。
- 官网：[TikTok数据分析与市场调研技能](https://www.guaikei.com)（自助开通 Token、查阅用量与接口说明）。
- 支持：微信 `13395823479`（备注：TikTok 技能）。
- 变更记录：[references/changelog.md](references/changelog.md)