toutiao-search

今日头条爆款内容查询

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

需先配置 API Key，通过环境变量 REDFOX_API_KEY 或 --api-key 参数传入。 搜索范围：今日头条平台最新发布的作品，实时拉取，无缓存延迟。

---

使用场景

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

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

---

使用方法

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

# 按阅读量排序（默认按时间）
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	只返回视频类作品	—
--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

---

💳 积分不足充值（支付宝接管）

当脚本以退出码 3 结束、并在 stdout 打印 ===PAYMENT_REQUIRED_JSON_START=== 区块时，表示当前 API Key 积分不足（接口 code=3210，兼容 3201）。响应体 data 内含结构化支付信息：cashierUrl（支付宝收银台链接）、amount（订单金额，元）、goodsName（商品名称）、outTradeNo（订单号）。

脚本退出码说明：0 正常返回；1 参数/鉴权/接口错误；3 积分不足，需要充值（按下述流程处理）。

完整的前置检查、alipay-bot trigger-payment-signal → submit-payment → poll-payment-status 编排步骤、钱包绑定处理、支付接管规则与失败处理，统一见 references/alipay-recharge.md（通用流程，可被其他 skill 复用）。submit-payment 后由 Agent 用 poll-payment-status --out-shake-no <查询单号> 自动监听支付回调到账，无需用户再手动确认；到账（outcome=success）后自动用用户原始的查询参数重新运行 scripts/search.py 输出结果。

---

功能特点

• 双接口深度查询：searchWork 搜索列表 + workDetail 获取完整数据（阅读/点赞/评论/转发/分享）
• 时间过滤：限定最近 N 小时内的新鲜内容，拒绝过期缓存
• 灵活排序：按发布时间或阅读量降序排列
• 视频筛选：--video-only 只找视频类爆款
• 终端表格：标题、作者、阅读、点赞、评论、转发、发布时间、链接、类型
• CSV 导出：自动生成 UTF-8 BOM 编码的 CSV
• HTML 交互报告：深色主题，图文/视频标签区分，支持页内搜索
• 本地代理服务：避免浏览器跨域限制，支持页内实时搜索

---

依赖

pip3 install requests

---

常见问题

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

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

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

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

Q：额度用完怎么办？ A：前往 redfox.hk 注册获取 Token。

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