抖音作品查询

SKILL.md

---
name: douyin-search
description: 抖音爆款作品查询工具。根据用户输入的关键词搜索抖音热门爆款作品，结果以表格展示。当用户想要查找抖音热门内容、搜索抖音爆款视频、查询抖音作品数据、了解某类内容在抖音的表现时使用。触发词包括：抖音爆款、抖音热门、抖音热榜、抖音作品查询、抖音搜索、爆款视频、热门视频。
---

# 抖音作品查询

## 1. 简介

抖音爆款作品查询工具，根据用户输入的关键词，一键搜索抖音热门爆款作品，结果以清晰的 Markdown 表格展示。专注服务于内容创作者、自媒体运营者和 MCN 机构，帮助用户快速发现抖音热门趋势、获取创作灵感、洞悉爆款规律。

## 2. 功能特性

- 🔍 **关键词精准搜索** — 输入任意关键词，即可搜索全平台抖音爆款作品，支持多关键词逗号分隔组合查询
- 📊 **多维数据表格** — 以 Markdown 表格直观展示点赞数、评论数、分享数、收藏数、粉丝数等核心数据
- 🧠 **语义理解与细分** — 智能理解用户意图，优先提取细分方向词而非泛化大类词，精准匹配搜索需求
- 🌐 **泛化词智能拓展** — 当用户输入泛化词时，自动推荐 10 个细分方向供选择，避免搜索结果过于宽泛
- 🔥 **热门推荐展示** — 搜索结果较少时自动展示近期热门推荐作品和热门话题，提供更多参考
- 📩 **订阅推送** — 支持创建每日定时推送任务，每天 10:00 自动推送指定关键词的最新爆款作品
- 📈 **数据可视化** — 数字智能格式化（万级显示），标题链接可点击跳转至抖音作品页

## 3. 一键安装

### 鉴权

#### 获取 API Key

请前往 [红狐hub](https://redfox.hk/settings/api-keys?source=clawhub) 获取API KEY

#### 配置 API Key

方案1: 以OpenClaw为例，将REDFOX_API_KEY添加到~/.openclaw/openclaw.json中：

```bash
{ "env": { "REDFOX_API_KEY": "ak_xxxx..." } }
```

方案2: 终端配置

```bash
export REDFOX_API_KEY="ak_xxxx..."
```

### 依赖安装

本 Skill 使用 Python 3 标准库，无需额外安装第三方依赖。确保系统中已安装 Python 3.x 即可。

### 环境变量配置

| 环境变量 | 说明 | 是否必填 | 获取方式 |
| -------- | ---- | -------- | -------- |
| `REDFOX_API_KEY` | 红狐数据 API Key | 是 | [红狐hub](https://redfox.hk/settings/api-keys?source=clawhub) |

## 4. 使用指南

### 基础使用（3 步完成查询）

**Step 1 — 提取关键词**：从用户的自然语言描述中提取搜索关键词。优先提取细分方向词（如"小众电影""港台电影"），而非泛化大类词（如仅提取"电影"）。

**Step 2 — 调用脚本**：在终端执行以下命令查询数据：

```bash
python3 ~/.qoderwork/skills/douyin-search/scripts/search_douyin.py "<关键词>"
```

- 无赛道关键词时传空字符串 `""`，查询全站热门
- 多个关键词用英文逗号 `,` 连接为一个字符串（不加空格），仅调用一次脚本

**Step 3 — 查看结果**：脚本返回 JSON，根据返回数据量自动选择合适的展示策略（详见下方"数据展示策略"）。

---

### 高级使用

#### 泛化词拓展策略

当用户输入的关键词为**泛化词**（纯大类词，如"穿搭""美食""美妆"，无任何修饰词）时，系统会启动拓展策略：

**判断原则**：有修饰词（场景/人群/风格/意图）= 细分词，直接搜索；无修饰词 = 泛化词，需要拓展。

**泛化词处理流程（⚠️ 必须等待用户明确回复后再调用脚本！）**：

**第一步：生成细分词**（禁止调用脚本搜索数据）

拓展词生成原则：
- **词的大小适中**：词语不要加组合，避免过细（如"中产穿搭"太细，查不到数据）
- **必须覆盖不同场景**：趋势词、人群词、场景词、意图词各 2-3 个

输出示例：
```
我识别到「中产」是较大的分类，已查询近期热门趋势，推荐以下细分方向：
老钱,轻奢,品质生活,松弛感,高级感穿搭,体面,法式穿搭,律师,医生,品质家居
回复「拓展」将同时搜索这 10 个词，回复「不拓展」将继续搜索「中产」
```

**第二步：等待用户回复**
- ❌ **禁止**：用户未回复时调用脚本
- ✅ **正确**：只等待用户明确回复「拓展」或「不拓展」后再执行

**第三步：根据用户明确回复执行**
- 用户回复「拓展」 → 将 10 个细分词以英文逗号 `,` 连接为一个字符串（不加空格），**仅调用一次脚本**传入，禁止逐个词多次调用
- 用户回复「不拓展」或「继续」 → 调用脚本搜索原关键词
- 用户未回复或回复其他内容 → 识别对应意图

---

#### 数据展示策略

##### 数据字段说明

| 字段               | 说明             |
| ------------------ | ---------------- |
| articles           | 搜索匹配的作品列表（按点赞数降序） |
| latestHotArticles  | 近期热门推荐作品列表 |
| hotTopics          | 热门话题列表       |

每条作品（articles / latestHotArticles）包含字段：

| 字段           | 说明     |
| -------------- | -------- |
| title          | 作品标题 |
| author         | 作者名称 |
| like_count     | 点赞数   |
| comment_count  | 评论数   |
| share_count    | 分享数   |
| collect_count  | 收藏数   |
| work_url       | 作品链接 |
| publish_time   | 发布时间 |
| follower_count | 粉丝数   |

##### 情况 A：articles 数量 > 0（有匹配结果）

**A1. 告知用户数据查询范围**

首先输出一句提示，告知用户本次查询的范围：

> 📊 关键词「**XXX**」共匹配到 **N 条**抖音爆款作品，以下是详细数据：

**A2. 展示作品表格（默认前 20 条）**

将 `articles` 渲染为 Markdown 表格，默认展示前 **20 条**（按点赞数降序），格式如下：

```markdown
| #   | 作品标题             | 作者   | 点赞数 | 评论数 | 分享数 | 收藏数 |
| --- | -------------------- | ------ | ------ | ------ | ------ | ------ |
| 1   | [标题文字](作品链接) | 作者名 | 305.2w | 7.1w   | 51.0w  | 14.7w  |
| 2   | [标题文字](作品链接) | 作者名 | 158.3w | 3.2w   | 22.1w  | 8.5w   |
```

**数字格式化规则：**

- 小于 10000：直接展示原始数字（如 `320`）
- 大于等于 10000：使用 `x.xw` 格式（如 `1.2w` 代表 12000）

**标题链接规则：**

- 作品标题使用 Markdown 链接格式 `[标题](work_url)`，点击可跳转到抖音作品页
- 如果标题过长（超过 30 字），截断并加 `...`

**A3. 查看全部数据（当结果超过 20 条时）**

如果 `articles` 总条数 > 20，在表格下方输出提示后**不等待，立刻继续**输出 A4：

> 以上展示了前 20 条数据，还剩 **N 条**未展示。需要查看全部数据吗？回复「查看全部」即可。

**当用户在后续对话中回复「查看全部」时**：将第 21 条起的所有剩余数据，以相同表格格式续接展示，编号从 #21 开始连续递增，直到全部展示完毕。

**articles ≤ 20 时**：跳过本步骤，直接进入 A4。

**A4. 展示热门推荐数据（latestHotArticles）**

**仅在 `articles` 总条数 ≤ 10 时执行本步骤。**

如果 `articles` 总条数 ≤ 10 且 `latestHotArticles` 不为空，展示热门推荐作品表格（最多 10 条），标题为：

> 🔥 **近期热门推荐作品**

使用与 A2 相同的表格格式和数字格式化规则。**若为空或 articles > 10 则跳过本模块，不输出任何内容。**

**A5. 展示热门话题（hotTopics）**

**仅在 `articles` 总条数 ≤ 10 时执行本步骤。**

如果 `articles` 总条数 ≤ 10 且 `hotTopics` 不为空，以列表形式展示热门话题：

> 🏷️ **热门话题**
>
> - #话题1
> - #话题2
> - ...

**若为空或 articles > 10 则跳过本模块，不输出任何内容。**

**⚠️ A1~A5 必须在同一轮输出中连续完成，输出 A5 后紧跟订阅提示，不得中断。**

##### 情况 B：articles 数量 = 0（无匹配结果）

**B1. 抱歉提示 + 拓词推荐**

> 😔 抱歉，未找到与「**XXX**」直接相关的内容，你可以尝试用更短或更宽泛的关键词重试（扩展词1,扩展词2,扩展词3,扩展词4,扩展词5,扩展词6,扩展词7,扩展词8,扩展词9,扩展词10）

AI 必须根据用户搜索的关键词生成 **固定 10 个**扩展搜索词，以英文逗号 `,` 分隔展示在一行括号内。

生成规则：
- 基于原始关键词进行语义扩展（如同义词、上下位词、相关场景词）
- 每个扩展词保持在 2-6 个汉字
- 优先推荐更细分或更宽泛的相关方向
- **必须生成恰好 10 个，不得少于 10 个**

**B2. 热门推荐数据（latestHotArticles）**

如果 `latestHotArticles` 不为空，展示热门推荐作品：

> 💡 我们为您推荐了近期的其他热门作品供参考，或许对您有帮助：

随后以表格格式展示 `latestHotArticles`（最多 10 条），格式同情况 A 的表格。**若为空则跳过本模块，不输出任何内容。**

**B3. 展示热门话题（hotTopics）**

如果 `hotTopics` 不为空，以列表形式展示，格式同 A5。**若为空则跳过本模块，不输出任何内容。**

**⚠️ B1~B3 必须在同一轮输出中连续完成，输出 B3 后紧跟订阅提示，不得中断。**

---

#### 订阅推送

全部内容展示完毕后，**不等待、立刻结束输出**，仅在末尾附上订阅提示：

> 📩 是否订阅「**XXX**」的每日推送？订阅后每天 10:00 自动推送最新爆款作品。回复「确认订阅」即可创建定时任务。

##### 创建定时任务（用户在后续对话中回复「确认订阅」时执行）

优先使用当前平台内置的定时任务/自动化能力创建订阅，若无则提供通用配置方案：

**1. 平台内置定时任务**（优先）

如果当前平台提供定时任务或 cron 自动化功能：直接调用该功能创建订阅，配置如下：
- 任务名称：`抖音爆款作品订阅 - <关键词>`
- 执行频率：每天 10:00（北京时间，cron 表达式 `0 10 * * *`）
- 执行内容：运行 `python3 <脚本路径>/search_douyin.py "<关键词>"`，将结果按本指南中数据展示策略的格式展示并推送到当前对话

**2. 通用配置方案**（平台无内置定时任务时）

向用户提供以下信息，由用户自行配置：
- 执行命令：`python3 <脚本路径>/search_douyin.py "<关键词>"`
- **Linux/macOS crontab**：`0 10 * * * python3 /path/to/search_douyin.py "<关键词>"`
- **其他平台**：参照对应平台的定时任务文档配置上述命令

创建成功后告知用户："已成功订阅关键词「<关键词>」的爆款作品推送，每天 10:00 将自动查询最新数据并通知你。"

---

### 常用命令速查表

| 场景 | 命令 |
| ---- | ---- |
| 关键词搜索 | `python3 ~/.qoderwork/skills/douyin-search/scripts/search_douyin.py "关键词"` |
| 全站热门 | `python3 ~/.qoderwork/skills/douyin-search/scripts/search_douyin.py ""` |
| 多关键词搜索 | `python3 ~/.qoderwork/skills/douyin-search/scripts/search_douyin.py "词1,词2,词3"` |
| 订阅创建 | 回复「确认订阅」后在对话中创建每日推送 |

## 5. 使用场景

### 场景一：内容创作者寻找选题灵感

- **角色**：抖音内容创作者
- **需求**：想了解近期"职场穿搭"领域有哪些爆款作品，寻找选题灵感
- **使用方式**：直接输入细分关键词「职场穿搭」，系统返回点赞数最高的作品列表
- **预期收益**：快速获得同赛道的爆款作品数据，了解热门选题方向和内容特征

### 场景二：MCN 机构监控赛道趋势

- **角色**：MCN 机构内容运营
- **需求**：需要实时了解"美妆"赛道整体趋势，但"美妆"范围太广
- **使用方式**：输入泛化词「美妆」后，系统推荐 10 个细分方向（如"口红试色""底妆测评"等），回复「拓展」批量搜索所有细分方向
- **预期收益**：一次性覆盖多个细分领域，全面掌握赛道热度分布

### 场景三：品牌方竞品分析

- **角色**：品牌市场人员
- **需求**：分析竞品在抖音的爆款内容策略
- **使用方式**：搜索竞品品牌名或相关品类关键词，查看高点赞作品的标题套路、互动数据
- **预期收益**：通过数据对比了解竞品内容打法，为自身品牌内容策略提供参考

### 场景四：自媒体博主每日热点追踪

- **角色**：抖音自媒体博主
- **需求**：每天上午自动获取特定领域的爆款作品列表
- **使用方式**：搜索关键词后回复「确认订阅」，创建每天 10:00 的定时推送
- **预期收益**：无需手动重复搜索，每日自动获取最新爆款数据，保持对赛道热点的持续追踪

## 6. 项目架构

### 目录结构

```
douyin-search/
├── SKILL.md                          # Skill 定义与使用文档（本文件）
├── scripts/
│   └── search_douyin.py              # 核心搜索脚本，调用红狐 API 获取数据
└── references/
    └── (数据格式参考文档)
```

### 技术栈

| 组件 | 技术 | 说明 |
| ---- | ---- | ---- |
| 运行环境 | Python 3.x | 标准库，无第三方依赖 |
| 数据接口 | 红狐 API (Redfox) | 通过 REDFOX_API_KEY 鉴权 |
| 输出格式 | JSON (stdout) | 脚本通过标准输出返回结构化 JSON 数据 |
| 展示格式 | Markdown 表格 | AI 代理将 JSON 渲染为表格展示 |

### 核心模块说明

| 模块 | 路径 | 功能 |
| ---- | ---- | ---- |
| 搜索脚本 | `scripts/search_douyin.py` | 调用红狐接口搜索抖音作品，返回 articles、latestHotArticles、hotTopics 三部分数据 |
| SKILL 定义 | `SKILL.md` | 定义 Skill 的元数据、工作流程、展示策略和订阅逻辑 |

### 资源索引

- **核心脚本**：`scripts/search_douyin.py` — 调用红狐 API 获取抖音爆款作品数据
- **参考文档**：`references/` 目录 — 包含数据字段格式说明（按需读取）

## 7. 常见问答

### 安装

**Q: 需要安装哪些依赖？**
A: 本工具使用 Python 3 标准库（urllib、json、os、sys、argparse），无需安装任何第三方依赖。只需确保系统已安装 Python 3.x。

**Q: 如何获取 API Key？**
A: 请访问 [红狐hub](https://redfox.hk/settings/api-keys?source=clawhub) 注册并获取 API Key，然后按本文"一键安装"章节配置环境变量。

### 使用

**Q: 泛化词和细分词有什么区别？**
A: 泛化词是纯大类词（如"穿搭""美食"），无任何修饰；细分词含有具体场景/人群/风格等修饰（如"小个子穿搭""减脂餐"）。泛化词会触发拓展策略，细分词直接搜索。

**Q: 为什么我的搜索没有返回结果？**
A: 可能关键词过于细分或小众。系统会自动提示 10 个扩展搜索词，建议尝试更短或更宽泛的关键词重试。

**Q: 如何查看超过 20 条的完整结果？**
A: 当搜索结果超过 20 条时，系统会在表格下方提示剩余条数，回复「查看全部」即可展示所有数据。

### 故障排除

**Q: 脚本执行报错怎么办？**
A: 常见原因包括：(1) 未配置 REDFOX_API_KEY 环境变量；(2) API Key 已过期；(3) 网络问题导致接口调用失败。请逐一排查。

**Q: 返回的数据为空或与预期不符？**
A: 尝试使用更短的关键词，或者使用全站热门模式（传空字符串关键词）查看是否有数据。如果全站热门也没有数据，可能是接口临时故障。

### 安全许可

**Q: API Key 如何安全存储？**
A: 推荐使用方案 1（配置到 openclaw.json 的 env 字段中），避免在终端历史中泄露。请勿将 API Key 直接硬编码在脚本中或上传到公开仓库。

**Q: 数据使用有什么限制？**
A: 数据来源于红狐 API，请遵守红狐平台的使用条款。本工具仅供个人学习和内容创作参考使用。