douyin-search

---
name: douyin-search
description: 抖音爆款作品查询工具。根据关键词搜索抖音热门爆款作品，支持按日期范围筛选，结果以结构化表格展示。当用户查找抖音热门内容、搜索抖音爆款视频、查询抖音作品数据时使用。触发词：抖音爆款、抖音热门、抖音热榜、抖音作品查询、抖音搜索、爆款视频、热门视频。
---

# 抖音作品查询

## 📝 简介

根据关键词搜索抖音热门爆款作品，支持按日期范围筛选，返回点赞、评论、分享、收藏、发布时间等互动数据，结果以结构化表格展示。

## ✨ 功能特性

| 功能模块 | 能力描述 | 核心价值 |
|---------|---------|---------|
| 爆款搜索 | 关键词搜索抖音爆款作品 | 精准发现高热度内容 |
| 日期筛选 | 支持按日期范围筛选 | 定位特定时间段的热门内容 |
| 智能拓展 | 泛化词自动拓展为 10 个细分词 | 避免泛化词搜索结果偏差 |
| 热门推荐 | 无结果时推荐热门作品和话题 | 兜底保障不空手而归 |
| 可点击链接 | 作品标题以超链接格式输出 | 一键跳转查看原作品 |
| 订阅推送 | 支持关键词每日推送 | 定时获取最新爆款动态 |

## 🔑 鉴权

- 获取 API Key：前往 [红狐hub](https://redfox.hk/settings/api-keys?source=github)
- 配置方式1：写入 `~/.openclaw/openclaw.json` → `{ "env": { "REDFOX_API_KEY": "ak_xxxx..." } }`
- 配置方式2：终端执行 `export REDFOX_API_KEY="ak_xxxx..."`

## ⚙️ 工作流程

### Step 1: 🔍 用户意图理解

**⚠️ 核心规则：优先提取细分方向词，而非泛化的大类词**

| 用户输入 | 处理方式 |
|---------|--------|
| 无赛道关键词（"最近热门作品"） | 关键词传空字符串 `""`，查询全站热门 |
| 有细分词（"职场穿搭"、"减脂餐"） | 直接搜索，无需拓展 |
| 有泛化词（"穿搭"、"美食"） | 执行拓展策略（Step 2） |

细分词判断原则：有场景/人群/风格/意图修饰 → 细分词；纯大类无修饰 → 泛化词。

**提取精确关键词**：从用户描述中提取细分领域词，而非泛化词。例：用户说"帮我找电影领域热门话题"且自称"小众电影、港台文化" → 搜索"小众电影、港台电影、电影乐评"，❌ 而非只搜"电影"。

### Step 2: 🔄 泛化词拓展策略

**⚠️ 必须等待用户明确回复后再调用脚本！**

| 步骤 | 操作 |
|------|------|
| 1. 生成细分词 | 生成10个适中大小的细分词（趋势词、人群词、场景词、意图词各2-3个），禁止调用脚本 |
| 2. 等待用户回复 | 用户未回复时禁止调用脚本 |
| 3. 执行 | 回复「拓展」→ 10词以英文逗号连接，仅调用一次脚本；回复「不拓展」→ 搜索原关键词 |

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

### Step 3: 📡 调用 API 接口

**3.1 时间解析规则**

| 用户输入 | 解析方式 | 示例 |
|---------|---------|------|
| 绝对日期 | 解析为 `YYYY-MM-DD` | `6月1号` → `2026-06-01` |
| 相对日期 | 基于当前日期计算 | `最近7天` → start=7天前, end=今天 |
| 日期范围 | 分别解析为 startDate/endDate | `5月30日到6月2日` |
| 模糊时间 | **不解析**，保持默认空字符串 | `最近的`、`最新的` |

- `startDate`/`endDate` 默认空字符串，表示不限定时间
- 单日期 → startDate = endDate；年份省略取当前年份

**3.2 执行脚本**

```bash
# 无时间参数
python3 ~/.qoderwork/skills/douyin-search/scripts/search_douyin.py "<关键词>"

# 有时间参数
python3 ~/.qoderwork/skills/douyin-search/scripts/search_douyin.py "<关键词>" --start-date <startDate> --end-date <endDate>
```

仅传入非空的时间参数。脚本返回 JSON：

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

每条作品字段：`title`、`author`、`like_count`、`comment_count`、`share_count`、`collect_count`、`work_url`、`publish_time`、`follower_count`

### Step 4: 📊 结果展示

**⚠️ 总数校验**：展示的 N 必须取自 `articles` 数组长度，禁止人工计数。

#### 情况 A：articles > 0

**A1.** 输出查询范围：

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

**A2.** 展示前 20 条表格：

```markdown
| # | 作品标题 | 作者 | 点赞数 | 评论数 | 分享数 | 收藏数 | 发布时间 |
|---|---------|------|--------|--------|--------|--------|----------|
| 1 | [标题](work_url) | 作者名 | 305.2w | 7.1w | 51.0w | 14.7w | 06-02 19:55 |
```

格式化规则：
- 数字 < 10000 直接展示；≥ 10000 用 `x.xw` 格式
- `publish_time` 转为 `MM-DD HH:MM`；无论是否指定时间范围均展示
- 标题超 30 字截断加 `...`，使用 `[标题](work_url)` 链接格式

**A3.** articles > 20 时提示：

> 以上展示了前 20 条数据，还剩 **N 条**未展示。回复「查看全部」展开剩余数据。

**A4-A5.** 仅 articles ≤ 10 时执行：
- `latestHotArticles` 非空 → 展示「🔥 近期热门推荐作品」表格（最多10条）
- `hotTopics` 非空 → 展示「🏷️ 热门话题」列表
- 为空则跳过，不输出

**⚠️ A1~A5 同一轮输出连续完成，A5 后紧跟 Step 5。**

#### 情况 B：articles = 0

**B1.** 抱歉提示 + 10个扩展词（以英文逗号分隔）：

> 😔 抱歉，未找到与「**XXX**」相关的内容，可尝试（扩展词1,扩展词2,...,扩展词10）

扩展词规则：基于原关键词语义扩展，每词2-6字，固定10个。

**B2-B3.** 展示 `latestHotArticles`（💡 推荐提示）和 `hotTopics`，为空则跳过。

**⚠️ B1~B3 同一轮输出连续完成，B3 后紧跟 Step 5。**

### Step 5: 📩 提示订阅

展示完毕后末尾附上：

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

### Step 6: ⏰ 创建定时任务（用户回复「确认订阅」时执行）

优先使用平台内置定时任务，若无则提供通用方案：

- 任务名称：`抖音爆款作品订阅 - <关键词>`
- 执行频率：每天 10:00（cron `0 10 * * *`）
- 执行命令：`python3 <脚本路径>/search_douyin.py "<关键词>"`（有时间参数则附加 `--start-date`/`--end-date`）
- 通用 crontab：`0 10 * * * python3 /path/to/search_douyin.py "<关键词>"`

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