今日头条爆款查询

SKILL.md

---
name: toutiao-search
description: 今日头条爆款内容查询 — 输入关键词搜索今日头条最新作品（图文/视频），支持按阅读量/时间排序、限定时间范围，终端表格展示 + CSV 导出 + 交互式 HTML 报告。当用户需要搜索今日头条热门内容、追踪头条热点、分析爆款文章时使用。
---

# 今日头条爆款内容查询

输入关键词搜索今日头条最新作品（图文/视频），终端表格展示 + CSV 导出 + 交互式 HTML 报告。

> API 请求均携带 `今日头条爆款查询-RedSkill` 标识。需先配置 API Key，通过环境变量 REDFOX_API_KEY 或 --api-key 参数传入。
> 搜索范围：今日头条平台**最新发布的作品**，实时拉取，无缓存延迟。

---

## 使用场景

当你需要执行以下任务时，应优先使用本技能：

| 场景 | 示例 |
|------|------|
| **热点话题追踪** | 搜 "AI" 了解今日头条上最新的 AI 相关内容 |
| **爆款内容分析** | 搜 "大模型" 找出阅读量最高的爆款文章 |
| **竞品内容监控** | 搜品牌关键词，追踪竞品在今日头条的投放内容 |
| **选题灵感采集** | 搜 "新能源" 批量导出 CSV 做数据分析找选题 |
| **舆情快速了解** | 搜某事件关键词，快速了解头条平台讨论风向 |
| **视频内容挖掘** | 搜 "测评" 配合 --video-only 筛选视频类爆款 |

---

## 使用方法

```bash
# 基础搜索
python3 "$SKILL_PATH/scripts/search.py" "关键词"

# 主题扩展搜索（自动关联同义词/相关词，联合检索去重）
python3 "$SKILL_PATH/scripts/search.py" "美伊战争" --expand

# 手动追加多个关键词联合检索
python3 "$SKILL_PATH/scripts/search.py" "美伊战争" --also "美伊冲突,美国伊朗"

# 按阅读量排序（默认）
python3 "$SKILL_PATH/scripts/search.py" "AI" --sort views

# 限定最近 24 小时内发布的作品
python3 "$SKILL_PATH/scripts/search.py" "大模型" --hours 24

# 只查视频类作品（已修复详情缺失导致的误判，类型未确认的会被排除）
python3 "$SKILL_PATH/scripts/search.py" "测评" --video-only

# 多页翻页，获取更多结果
python3 "$SKILL_PATH/scripts/search.py" "新能源汽车" --pages 5

# 仅导出 CSV，不生成 HTML
python3 "$SKILL_PATH/scripts/search.py" "AI" --csv-only

# 不自动打开浏览器
python3 "$SKILL_PATH/scripts/search.py" "AI" --no-open
```

终端输出按**指定排序方式**（时间/阅读量）降序排列；结果较少或无结果时自动提示。

HTML 报告特性：深色主题 · 点击搜索按钮查询 · 作品卡片点击跳转原文 · 图文/视频标签区分 · 分页加载。

CSV / HTML 默认保存在 `~/Downloads/QoderToutiaoSearch/`。

---

## 返回结果展示规范

向用户展示搜索结果时，**必须**使用以下完整字段列表，不得省略：

| 序号 | 字段 | 说明 |
|------|------|------|
| # | 排名序号 | 从 1 开始 |
| 标题 | 作品标题 | 最多显示 30 字，超出截断 |
| 作者 | 作者昵称 | — |
| 阅读量 | viewCount | 用千/万简写（如 3.2k、12w） |
| 点赞数 | likeCount | 同上 |
| 评论数 | commentCount | 同上 |
| 转发数 | repostCount | 同上 |
| 发布时间 | publishTime | 格式：`YYYY-MM-DD HH:mm` |
| 类型 | workType | 图文 / 视频 |
| 链接 | workUrl | 可点击跳转原文 |

**表格示例：**

```
| # | 标题 | 作者 | 阅读 | 点赞 | 评论 | 转发 | 发布时间 | 类型 |
|---|------|------|------|------|------|------|----------|------|
| 1 | 某某爆款文章标题... | 某某作者 | 3.2k | 412 | 89 | 56 | 2026-06-28 14:30 | 图文 |
```

---

## 参数说明

| 参数 | 说明 | 默认值 |
|------|------|--------|
| `keyword` | 搜索关键词（必填，位置参数） | — |
| `--sort` | 排序方式：`views` / `time` | `views` |
| `--hours` | 限定最近 N 小时内发布的作品（0=不限） | `0` |
| `--pages` | 翻页次数（每页约 10 条） | `3` |
| `--video-only` | 只返回确认的视频类作品（类型未确认的会被排除并提示） | — |
| `--expand` | 主题扩展模式：自动关联同义词/相关词联合检索 | — |
| `--also` | 手动追加搜索关键词，逗号分隔 | — |
| `--output-dir` | 输出目录 | `~/Downloads/QoderToutiaoSearch` |
| `--api-key` | 指定 API Key | — |
| `--no-open` | 不自动打开浏览器 | — |
| `--csv-only` | 仅生成 CSV，不生成 HTML | — |
| `--port` | HTML 本地服务端口 | `8767` |

---

## API Key 配置

任选一种方式配置个人 Key：

| 方式 | 命令 |
|------|------|
| 环境变量（推荐） | `export REDFOX_API_KEY=ak_你的密钥` |
| 命令行参数 | `--api-key ak_你的密钥` |
| 配置文件 | `echo '{"api_key":"ak_你的密钥"}' > ~/.qoder/apis/redfox.json` |

注册地址：[redfox.hk](https://redfox.hk/settings/api-keys?source=redskill)

---

## 功能特点

- **双接口深度查询**：`searchWork` 搜索列表 + `workDetail` 获取完整数据（阅读/点赞/评论/转发/分享）
- **主题扩展搜索**：`--expand` 自动关联同义词，`--also` 手动追加多词，联合检索自动去重
- **时间过滤**：限定最近 N 小时内的新鲜内容，拒绝过期缓存
- **灵活排序**：按发布时间或阅读量降序排列
- **视频筛选**：`--video-only` 只保留确认的视频；详情未获取的作品标记为「未知」，不误判为图文
- **检索透明**：终端显示各关键词贡献条数、类型分布统计（图文/视频/未确认）
- **终端表格**：标题、作者、阅读、点赞、评论、转发、发布时间、链接、类型
- **CSV 导出**：自动生成 UTF-8 BOM 编码的 CSV
- **HTML 交互报告**：深色主题，图文/视频标签区分，支持页内搜索
- **本地代理服务**：避免浏览器跨域限制，支持页内实时搜索

---

## 依赖

```bash
pip3 install requests
```

---

## 常见问题

**Q：能搜到每条爆款吗？**
A：能保证每次的关键词都有作品。

**Q：搜索范围覆盖多久之前的作品？**
A：目前提供近 1 年的作品，优先会覆盖近期发布的内容。

**Q：为什么搜索后还要等待详情查询？**
A：搜索接口只返回基础信息，同时提供单作品补全阅读量、点赞、转发等完整指标，让数据更完整。

**Q：搜索后如何保存数据？**
A：可以让 AI 为你导出 Excel，也可以让 AI 导出 HTML。

**Q：额度用完怎么办？**
A：前往 [redfox.hk](https://redfox.hk/settings/api-keys?source=redskill) 注册获取 Token。

**Q：最多能获取多少条？**
A：每页约 10 条，默认翻 3 页（约 30 条）。可通过 `--pages` 参数调整。

**Q：搜「美伊战争」结果很少怎么办？**
A：使用 `--expand` 开启主题扩展搜索，自动关联「美伊冲突」「美国伊朗」等相关词联合检索，结果更完整。也可用 `--also "词1,词2"` 手动指定相关词。