抖音作品实时搜索

SKILL.md

---
name: douyin-realtime-search
description: 抖音作品实时搜索工具。根据用户输入的关键词实时调用 Redfox 接口搜索抖音最新作品，支持按排序方式和发布时间筛选，返回实时数据（非缓存/历史数据）。当用户明确要求「实时」「最新」「现在」「当前」搜索抖音内容，或对已有数据时效性存疑时使用。触发词：抖音实时搜索、抖音最新作品、实时抖音热门、当前抖音数据、抖音实时查询。
---

# 抖音作品实时搜索

## 1. 简介

抖音作品实时搜索工具，根据用户输入的关键词实时调用 Redfox 接口搜索抖音最新作品，返回实时数据（非缓存/历史数据）。支持按排序方式（综合/最新发布/最多点赞）和发布时间（7天/30天/90天/不限）灵活筛选。当用户对数据时效性有严苛要求、需要获取当下最新的抖音内容时，本工具是最佳选择。

## 2. 功能特性

- 🔍 **实时接口调用** — 直接调用 Redfox 实时搜索接口，返回当下最新作品数据，非缓存/历史数据
- 📊 **多维度筛选** — 支持综合排序、最新发布、最多点赞三种排序方式，以及 7 天/30 天/90 天/不限四种时间范围
- 📋 **完整数据表格** — 以 Markdown 表格展示点赞数、评论数、分享数、收藏数、粉丝数等核心数据
- 🧠 **语义理解** — 优先提取用户描述中的细分方向词，智能匹配搜索意图
- 🔧 **筛选切换提示** — 每次结果后自动提示可用筛选条件，支持一键切换排序方式和时间范围
- 📩 **订阅推送** — 支持创建每日定时推送任务，每天 10:00 自动推送指定关键词的最新实时作品
- 📈 **智能数字格式化** — 万级以上数据自动转换（如 `1.2w`），标题链接可点击跳转

## 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 — 提取关键词与筛选参数**：从用户的自然语言描述中提取搜索关键词和筛选偏好。优先提取细分方向词（2~6 字），若用户意图模糊则主动询问。

**Step 2 — 调用实时搜索脚本**：

```bash
python3 ~/.agents/skills/douyin-realtime-search/scripts/search_douyin_realtime.py "<关键词>" [--sort 排序] [--time 时间]
```

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

---

### 高级使用

#### 筛选参数识别（用户未指定时使用默认值）

**排序方式**（`--sort`）：默认 `1`（综合排序）
- 用户提到"最新"、"最近发布" → `2`
- 用户提到"点赞"、"热门"、"爆款" → `3`
- 未提及排序 → `1`（默认）

**发布时间**（`--time`）：默认 `7`（最近7天）
- 用户提到"近一个月"、"30天" → `30`
- 用户提到"近三个月"、"90天" → `90`
- 用户提到"不限时间"、"全部" → `0`
- 未提及时间 → `7`（默认）

#### 参数速查表

| 参数     | 可选值                    | 含义                                    |
| -------- | ------------------------- | --------------------------------------- |
| keyword  | 任意字符串                | 搜索关键词，多个词用英文逗号连接         |
| `--sort` | `1` / `2` / `3`           | 综合排序 / 最新发布 / 最多点赞（默认1）  |
| `--time` | `7` / `30` / `90` / `0`   | 最近7天 / 30天 / 90天 / 不限（默认7）   |

#### 脚本返回字段说明

| 字段                 | 说明                           |
| -------------------- | ------------------------------ |
| `articles`           | 关键词匹配作品列表（按点赞降序） |
| `latestHotArticles`  | 近期热门推荐作品（兜底展示）    |
| `hotTopics`          | 相关热门话题标签               |
| `sort_type_label`    | 本次排序方式文字说明            |
| `publish_time_label` | 本次时间范围文字说明            |

每条作品字段：

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

---

#### 数据展示策略

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

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

> 📊 关键词「**XXX**」实时查询到 **N 条**作品（排序：{sort_type_label} | 时间范围：{publish_time_label}），以下是详细数据：

**A2. 渲染 Markdown 表格（全部展示）**

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

**数字格式化规则：**
- `< 10000`：原始数字（如 `320`）
- `≥ 10000`：`x.xw` 格式（如 `1.2w`）

**标题规则：** `[标题](work_url)`；超过 30 字截断并加 `...`

**A3. 筛选能力提示（紧接在表格之后，每次必须输出）**

> 🔧 **支持筛选，回复以下指令可切换条件重新搜索：**
> - **排序方式**：综合排序 / 最新发布 / 最多点赞（当前：{sort_type_label}）
> - **发布时间**：最近7天 / 最近30天 / 最近90天 / 不限（当前：{publish_time_label}）
>
> 示例：「按最新发布、最近30天重新搜索」

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

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

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

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

AI 必须生成**固定 10 个**扩展词，2~6 字，英文逗号分隔，不得少于 10 个。

**B2. 筛选能力提示（紧接在 B1 之后，每次必须输出，格式同 A3）**

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

---

#### 订阅推送

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

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

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

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

**平台内置定时任务（优先）：**
- 任务名称：`抖音实时搜索订阅 - <关键词>`
- 执行频率：每天 10:00（cron：`0 10 * * *`）
- 执行内容：运行脚本并将结果按本指南中数据展示策略的格式展示推送到当前对话

**通用配置方案：**
```bash
# Linux/macOS crontab
0 10 * * * python3 ~/.agents/skills/douyin-realtime-search/scripts/search_douyin_realtime.py "<关键词>"
```

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

---

### 常用命令速查表

| 场景 | 命令 |
| ---- | ---- |
| 关键词搜索（默认排序和时间） | `python3 ~/.agents/skills/douyin-realtime-search/scripts/search_douyin_realtime.py "关键词"` |
| 按最新发布搜索 | `python3 ~/.agents/skills/douyin-realtime-search/scripts/search_douyin_realtime.py "关键词" --sort 2` |
| 按最多点赞搜索 | `python3 ~/.agents/skills/douyin-realtime-search/scripts/search_douyin_realtime.py "关键词" --sort 3` |
| 限定最近 30 天 | `python3 ~/.agents/skills/douyin-realtime-search/scripts/search_douyin_realtime.py "关键词" --time 30` |
| 不限时间范围 | `python3 ~/.agents/skills/douyin-realtime-search/scripts/search_douyin_realtime.py "关键词" --time 0` |
| 组合筛选 | `python3 ~/.agents/skills/douyin-realtime-search/scripts/search_douyin_realtime.py "关键词" --sort 3 --time 90` |

## 5. 使用场景

### 场景一：热点事件实时追踪

- **角色**：自媒体热点编辑
- **需求**：某热点事件爆发，需要立即获取抖音上相关的最新作品
- **使用方式**：输入事件关键词，选择"最新发布"排序 + "最近7天"，获取实时作品列表
- **预期收益**：第一时间掌握热点事件的抖音传播态势，快速产出追踪报道

### 场景二：竞品动态实时监控

- **角色**：品牌市场运营
- **需求**：需要实时了解竞品近期在抖音上的最新发布内容
- **使用方式**：搜索竞品品牌名，选择"最新发布"排序
- **预期收益**：通过实时数据洞察竞品的最新营销动作和内容策略变化

### 场景三：数据时效性验证

- **角色**：数据分析师
- **需求**：对已有数据的时效性存疑，需要确认当前抖音平台上某关键词的实际数据表现
- **使用方式**：使用本工具进行实时查询，排除缓存数据的干扰
- **预期收益**：获取当下实时数据，确保分析结论基于最新数据，避免被过期数据误导

### 场景四：每日热门趋势订阅

- **角色**：抖音创作者
- **需求**：希望每天上午自动获取特定领域的实时热门作品列表
- **使用方式**：搜索关键词后回复「确认订阅」，创建每天 10:00 的定时推送
- **预期收益**：无需手动重复搜索，每日自动获取领域最新实时数据，保持创作灵感的持续输入

## 6. 项目架构

### 目录结构

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

### 技术栈

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

### 核心模块说明

| 模块 | 路径 | 功能 |
| ---- | ---- | ---- |
| 实时搜索脚本 | `scripts/search_douyin_realtime.py` | 调用红狐实时搜索接口，支持排序方式和时间范围参数 |
| SKILL 定义 | `SKILL.md` | 定义 Skill 元数据、筛选参数规则、展示策略和订阅逻辑 |

### 资源索引

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

## 7. 常见问答

### 安装

**Q: 需要安装哪些依赖？**
A: 本工具使用 Python 3 标准库，无需额外安装第三方依赖。确保系统中已安装 Python 3.x 即可。

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

### 使用

**Q: 实时搜索和普通搜索有什么区别？**
A: 实时搜索直接调用红狐实时接口，返回当下最新数据；普通搜索（douyin-search）可能包含缓存/历史数据。当对时效性有严苛要求时请使用本工具。

**Q: `--sort` 参数三个值分别代表什么？**
A: `1` = 综合排序（默认），`2` = 最新发布，`3` = 最多点赞。可根据需求灵活切换。

**Q: `--time` 参数为 0 是什么意思？**
A: `0` 表示不限时间范围，会返回所有可用的历史数据。

### 故障排除

**Q: 返回结果为空怎么办？**
A: 尝试：(1) 使用更短/更宽泛的关键词；(2) 切换为"最多点赞"排序；(3) 扩大时间范围至 90 天或设为不限（`--time 0`）。

**Q: 脚本执行报错？**
A: 请检查：(1) REDFOX_API_KEY 环境变量是否正确配置；(2) Python 版本是否 ≥ 3.x；(3) 网络连接是否正常。

### 安全许可

**Q: 实时搜索是否会消耗更多 API 额度？**
A: 实时搜索和普通搜索的接口调用机制不同，请参考红狐平台的配额说明。建议合理控制调用频率。

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