前言¶

做内容选题或竞品观察时，往往需要先在今日头条上按关键词翻作品、看阅读量和发布时间。手工在 App 或网页里搜、抄标题、再整理成表，步骤多，也不方便和 AI 工作流衔接。下面介绍 SkillHub 上的 今日头条爆款查询（@redfox-data/toutiao-search，v1.0.1）：用关键词检索头条最新图文/视频，支持排序与时间过滤，并在终端表格、CSV 与交互式 HTML 报告里呈现结果。

这是什么¶

今日头条爆款查询 是红狐数据发布的企业类 Skill（分类 content-creation），坐标 @redfox-data/toutiao-search。它面向「搜头条热门作品、追热点、看爆款指标」这类任务：输入关键词，从今日头条最新发布的作品中拉取数据（官方说明为实时拉取、无缓存延迟），再按你的选项排序、过滤并导出。

SkillHub 页面标注 requires_api_key=true：调用红狐数据 API 前需配置个人 API Key。API 请求会携带 今日头条爆款查询-RedSkill 标识。

核心功能¶

以下能力均来自该 Skill 的 SKILL.md 与 SkillHub 简介，安装后由 scripts/search.py 执行。

1. 关键词搜索：必填位置参数 keyword，检索头条图文与视频作品。
2. 排序：--sort views（阅读量，默认）或 --sort time（发布时间），结果按所选维度降序。
3. 时间范围：--hours N 限定最近 N 小时内发布（0 表示不限）。
4. 翻页：--pages 控制翻页次数（默认 3 页，每页约 10 条）。
5. 主题扩展：--expand 自动关联同义词/相关词联合检索；--also "词1,词2" 手动追加关键词，结果去重。
6. 视频筛选：--video-only 只保留确认为视频的作品。
7. 输出形态：终端表格；UTF-8 BOM 的 CSV；深色主题 HTML 报告（可页内搜索、卡片跳转原文）。默认输出目录为 ~/Downloads/QoderToutiaoSearch/。
8. 数据字段：标题、作者、阅读量、点赞、评论、转发、发布时间、类型（图文/视频）、原文链接等；搜索列表与 workDetail 详情补全配合使用。

依赖：pip3 install requests。

安装与启用¶

1. 安装 SkillHub CLI（若尚未安装）¶

先检查是否已有 CLI：

command -v skillhub && skillhub --version

未安装时可执行官方安装脚本（完整安装或仅 CLI）：

curl -fsSL https://skillhub-1388575217.cos.ap-guangzhou.myqcloud.com/install/install.sh | bash

curl -fsSL https://skillhub-1388575217.cos.ap-guangzhou.myqcloud.com/install/install.sh | bash -s -- --cli-only

说明见 SkillHub 安装文档。

2. 安装本 Skill¶

安装时必须用 --dir 指向当前 Agent 的 skills 目录，否则默认落在 ./skills/ 且可能不被识别。SkillHub 文档给出的常见路径示例：

• Cursor：~/.cursor/skills/
• Claude Code：~/.claude/skills/
• Codex：~/.codex/skills/ 或项目下的 .agents/skills/

安装命令示例（将 <skills 目录> 换成你的实际路径）：

skillhub install @redfox-data/toutiao-search --dir <skills 目录>

SkillHub 技能页也支持让 AI 按上述安装文档安装 @redfox-data/toutiao-search。

3. 配置 API Key¶

任选一种方式（密钥需自行在红狐数据平台申请）：

export REDFOX_API_KEY=ak_你的密钥

python3 scripts/search.py "关键词" --api-key ak_你的密钥

echo '{"api_key":"ak_你的密钥"}' > ~/.qoder/apis/redfox.json

注册与 Key 管理：redfox.hk 设置页。

典型用法¶

安装后，在 Skill 目录下将 SKILL_PATH 设为该 Skill 的根路径，再调用 scripts/search.py。

基础搜索（终端表格 + 默认 CSV/HTML）：

python3 "$SKILL_PATH/scripts/search.py" "关键词"

按阅读量排序、限定最近 24 小时：

python3 "$SKILL_PATH/scripts/search.py" "大模型" --sort views --hours 24

主题扩展与多词联合检索：

python3 "$SKILL_PATH/scripts/search.py" "美伊战争" --expand
python3 "$SKILL_PATH/scripts/search.py" "美伊战争" --also "美伊冲突,美国伊朗"

只查视频、多页、仅 CSV、不自动打开浏览器：

python3 "$SKILL_PATH/scripts/search.py" "测评" --video-only
python3 "$SKILL_PATH/scripts/search.py" "新能源汽车" --pages 5
python3 "$SKILL_PATH/scripts/search.py" "AI" --csv-only
python3 "$SKILL_PATH/scripts/search.py" "AI" --no-open

常用参数摘要：--output-dir 自定义输出目录；--port 指定 HTML 本地服务端口（默认 8767）。

在 Cursor 等环境中，也可直接用自然语言描述需求（例如「搜头条 AI 相关、按阅读量排序、导出 CSV」），由 Agent 按 Skill 说明调用上述脚本。

适用场景与注意¶

适合谁

• 需要在头条侧快速看某关键词下的新作与互动数据的内容、运营、分析人员。
• 希望把检索结果落到 CSV/HTML，便于二次统计或汇报的团队。

Skill 文档列出的典型任务包括：热点追踪、爆款分析、竞品关键词监控、选题采集、舆情速览、视频类内容筛选等；具体仍以你配置的关键词与 API 返回为准。

限制与注意

• 必须配置有效的 REDFOX_API_KEY（或等价配置），并关注平台额度；额度问题需到红狐数据控制台处理。
• 默认约 3 页、每页约 10 条，更多结果需增大 --pages；官方 FAQ 说明搜索范围目前覆盖近 1 年作品，并优先近期内容。
• 列表检索后会进行详情补全，等待时间属正常现象。
• SkillHub 统计（以抓取资料为准）：评分 100000，下载 1788；页面展示安装数为 0，以 SkillHub 实时数据为准。
• 使用第三方 API 与头条数据时，请遵守平台服务条款与合规要求。

结尾¶

今日头条爆款查询 把「关键词 → 头条作品列表 → 阅读/互动指标 → 表格与导出」收成一条可在 Agent 里复用的路径，适合追热点和做内容分析前的数据拉取。官方 Skill 包地址：https://api.skillhub.cn/redfox-data/toutiao-search；SkillHub 介绍页：https://www.skillhub.cn/skills/redfox-data/toutiao-search。