douyin-search git:20260604.cdf46a5A

Immutable. This exact content is served forever at /api/v1/blob/348fb330d96257ea.

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

# 抖音作品查询

## 鉴权

### 获取 API Key

请前往 [红狐hub](https://redfox.hk/settings/api-keys?source=github) 获取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..."
```

## 工作流程

### Step 1: 用户意图理解（查询脚本前）

**⚠️ 核心规则：应该语义理解，优先提取用户描述中的细分方向词，而非泛化的大类词**

**1. 判断用户是否提到赛道关键词**：
- **无赛道关键词**（如"最近的热门作品有哪些"、"最近有什么热门内容"、"看看热门数据"）→ 直接调用脚本，关键词传空字符串 `""`，查询全站热门
- **有赛道关键词** → 继续提取和判断

**2. 提取精确搜索关键词**（仅当用户提到赛道时执行）：
- **分析用户描述**：从用户自我介绍或需求描述中提取明确的细分领域词
- 示例分析：
  - 用户输入："我是一个文艺类自媒体万粉抖音博主，平时会发小众电影审美积累、书评、乐评、港台文化等相关内容，帮我找电影领域热门话题"
  - 分析结果：用户提到的细分方向 = 小众电影、书评、乐评、港台文化
  - 将前文场景和"电影"相关，得到细分词 = 小众电影、港台电影、电影乐评
  - 搜索关键词：小众电影、港台电影、电影乐评
  - ❌ 错误做法：只提取泛化词「电影」去搜索

**3. 关键词类型判断**（仅当提取到关键词时执行）：
- **细分词/垂直赛道**（含具体场景/属性修饰的词，如"职场穿搭"、"减脂餐"、"小个子穿搭"）→ 直接搜索，无需拓展询问
- **泛化词/分类**（纯大类词，如"穿搭"、"美食"、"美妆"，无任何修饰）→ 执行拓展策略（Step 2）
- **判断原则**：有修饰词（场景/人群/风格/意图）= 细分词，直接搜索；无修饰词 = 泛化词，需要拓展

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

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

**第一步：生成细分词**（禁止调用脚本搜索数据）
- 拓展词生成原则：
  - **词的大小适中**：词语不要加组合，避免过细（如"中产穿搭"太细，查不到数据）
  - **必须覆盖不同场景**：趋势词、人群词、场景词、意图词各 2-3 个
- 输出示例：
  ```
  我识别到「中产」是较大的分类，已查询近期热门趋势，推荐以下细分方向：
  老钱,轻奢,品质生活,松弛感,高级感穿搭,体面,法式穿搭,律师,医生,品质家居
  回复「拓展」将同时搜索这 10 个词，回复「不拓展」将继续搜索「中产」
  ```

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

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

### Step 3: 调用搜索接口

**3.1 时间解析规则**

在调用脚本前，需判断用户 query 中是否包含时间信息，并解析为 `startDate` 和 `endDate` 参数：

- **默认值**：`startDate` 和 `endDate` 均为空字符串 `""`，表示不限定时间范围
- **需要解析时间的场景**：用户 query 中包含明确的时间表达，例如：
  - 绝对日期：`2025年6月1日`、`2025-06-01`、`6月1号` → 解析为 `2025-06-01`
  - 相对日期：`昨天`、`前天`、`最近3天`、`最近一周`、`最近7天` → 根据当前日期计算
  - 日期范围：`6月1日到6月3日`、`上周` → 分别解析为 startDate 和 endDate
  - 模糊时间：`最近的`、`最新的` → **不解析为日期**，保持默认空字符串，由接口返回最新数据

- **解析规则**：
  - 仅解析绝对日期或明确相对日期，不解析模糊时间词
  - 日期格式统一为 `YYYY-MM-DD`
  - 若用户只提到单个日期（如`6月1日`），则 `startDate` = `endDate` = 该日期
  - 若用户提到时间范围（如`最近7天`），则 `startDate` = 范围起始日，`endDate` = 范围结束日（今天）
  - 年份省略时默认取当前年份

**3.2 执行脚本**

根据时间解析结果，构建脚本调用命令：

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

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

仅传入非空的时间参数，空字符串的参数无需传入（脚本默认值为空字符串）。

脚本返回 JSON 对象，包含以下字段：

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

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

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

### Step 4: 判断搜索结果并展示

根据 `articles` 数量选择不同的展示策略：

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

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

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

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

**⚠️ 总数校验规则**：N 必须直接取自脚本返回 JSON 中 `articles` 数组的长度（`len(articles)`），禁止人工计数或估算，确保总数准确无误。

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

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

```markdown
| #   | 作品标题             | 作者   | 点赞数 | 评论数 | 分享数 | 收藏数 | 发布时间 |
| --- | -------------------- | ------ | ------ | ------ | ------ | ------ | -------- |
| 1   | [标题文字](作品链接) | 作者名 | 305.2w | 7.1w   | 51.0w  | 14.7w  | 06-02 19:55 |
| 2   | [标题文字](作品链接) | 作者名 | 158.3w | 3.2w   | 22.1w  | 8.5w   | 05-30 15:30 |
```

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

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

**发布时间格式化规则：**

- 将 `publish_time`（格式 `YYYY-MM-DD HH:MM:SS`）转换为 `MM-DD HH:MM` 格式展示（如 `2026-06-02 19:55:03` → `06-02 19:55`）
- 不管用户是否指定了时间范围查询，均展示发布时间列

**标题链接规则：**

- 作品标题使用 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 后紧跟 Step 5 订阅提示，不得中断。**

#### 情况 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 后紧跟 Step 5 订阅提示，不得中断。**

### Step 5: 提示订阅

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

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

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

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

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

**2. 通用配置方案**（平台无内置定时任务时）
向用户提供以下信息，由用户自行配置：
- 执行命令：`python3 <脚本路径>/search_douyin.py "<关键词>"`（如有时间参数则附加 `--start-date` 和 `--end-date`）
- **Linux/macOS crontab**：`0 10 * * * python3 /path/to/search_douyin.py "<关键词>"`（如有时间参数则附加 `--start-date` 和 `--end-date`）
- **其他平台**：参照对应平台的定时任务文档配置上述命令

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