douyin-search

抖音作品查询

📝 简介

根据关键词搜索抖音热门爆款作品，支持按日期范围筛选，返回点赞、评论、分享、收藏、发布时间等互动数据，结果以结构化表格展示。

✨ 功能特性

功能模块	能力描述	核心价值
爆款搜索	关键词搜索抖音爆款作品	精准发现高热度内容
日期筛选	支持按日期范围筛选	定位特定时间段的热门内容
智能拓展	泛化词自动拓展为 10 个细分词	避免泛化词搜索结果偏差
可点击链接	作品标题以超链接格式输出	一键跳转查看原作品
订阅推送	支持关键词每日推送	定时获取最新爆款动态

🔑 鉴权

• 获取 API Key：前往 红狐hub
• 配置方式1：写入 ~/.openclaw/openclaw.json → { "env": { "REDFOX_API_KEY": "ak_xxxx..." } }
• 配置方式2：终端执行 export REDFOX_API_KEY="ak_xxxx..."

⚙️ 工作流程

Step 1: 🔍 用户意图理解

⚠️ 核心规则：优先提取细分方向词，而非泛化的大类词

用户输入	处理方式
无赛道关键词（"最近热门作品"）	关键词传空字符串 ""，查询全站热门
有细分词（"职场穿搭"、"减脂餐"）	直接搜索，无需拓展
有泛化词（"穿搭"、"美食"）	执行拓展策略（Step 2）

细分词判断原则：有场景/人群/风格/意图修饰 → 细分词；纯大类无修饰 → 泛化词。

提取精确关键词：从用户描述中提取细分领域词，而非泛化词。例：用户说“帮我找电影领域热门话题”且自称“小众电影、港台文化” → 搜索“小众电影、港台电影、电影乐评”，❌ 而非只搜“电影”。

过滤触发钩子词：用户输入中的「热门文章」「热门作品」「爆款」「热门内容」「查询」「搜索」等词是调用 Skill 的触发钩子，不属于搜索关键词，必须剥离。例：用户说“查询AI热门文章” → 关键词为「AI」，❌ 而非「AI热门文章」。

Step 2: 🔄 泛化词拓展策略

⚠️ 必须等待用户明确回复后再调用脚本！

步骤	操作
1. 生成细分词	生成10个适中大小的细分词（趋势词、人群词、场景词、意图词各2-3个），禁止调用脚本
2. 等待用户回复	用户未回复时禁止调用脚本
3. 执行	回复「拓展」→ 10词以英文逗号连接，仅调用一次脚本；回复「不拓展」→ 搜索原关键词

输出示例：

我识别到「中产」是较大的分类，推荐以下细分方向：
老钱,轻奢,品质生活,松弛感,高级感穿搭,体面,法式穿搭,律师,医生,品质家居
回复「拓展」将同时搜索这10个词，回复「不拓展」将继续搜索「中产」

Step 3: 📡 调用 API 接口

3.1 时间解析规则

用户输入	解析方式	示例
绝对日期	解析为 YYYY-MM-DD	6月1号 → 2026-06-01
相对日期	基于当前日期计算	最近7天 → start=7天前, end=今天
日期范围	分别解析为 startDate/endDate	5月30日到6月2日
模糊时间	不解析，保持默认空字符串	最近的、最新的

• startDate/endDate 默认空字符串，表示不限定时间
• 单日期 → startDate = endDate；年份省略取当前年份

3.2 执行脚本

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

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

仅传入非空的时间参数。脚本返回 JSON：

字段	说明
articles	搜索匹配的作品列表（按点赞数降序）
total	总记录数
pageNum	当前页码
pageSize	每页大小

每条作品字段：title、author、like_count、comment_count、share_count、collect_count、work_url、publish_time

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

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

脚本退出码说明：0 正常返回（含"暂无数据"）；1 参数/鉴权/接口错误；3 积分不足，需要充值 —— 按 references/alipay-recharge.md 唤起支付宝充值，到账后自动用原始参数重跑脚本。

完整的前置检查、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_douyin.py 输出结果。

Step 4: 📊 结果展示

⚠️ 总数校验：展示的 N 必须取自 articles 数组长度，禁止人工计数。

情况 A：articles > 0

A1. 输出查询范围：

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

A2. 展示前 20 条表格：

| # | 作品标题 | 作者 | 点赞数 | 评论数 | 分享数 | 收藏数 | 发布时间 |
|---|---------|------|--------|--------|--------|--------|----------|
| 1 | [标题](work_url) | 作者名 | 305.2w | 7.1w | 51.0w | 14.7w | 06-02 19:55 |

格式化规则：

• 数字 < 10000 直接展示；≥ 10000 用 x.xw 格式
• publish_time 转为 MM-DD HH:MM；无论是否指定时间范围均展示
• 标题超 30 字截断加 ...，使用 [标题](work_url) 链接格式

A3. articles > 20 时提示：

以上展示了前 20 条数据，还剩 N 条未展示。回复「查看全部」展开剩余数据。

⚠️ A1~A3 同一轮输出连续完成，A3 后紧跟 Step 5。

情况 B：articles = 0

B1. 抱歉提示 + 10个扩展词（以英文逗号分隔）：

😔 抱歉，未找到与「XXX」相关的内容，可尝试（扩展词1,扩展词2,...,扩展词10）

扩展词规则：基于原关键词语义扩展，每词2-6字，固定10个。

⚠️ B1 后紧跟 Step 5。

Step 5: 📩 提示订阅

展示完毕后末尾附上：

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

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

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

• 任务名称：抖音爆款作品订阅 - <关键词>
• 执行频率：每天 10:00（cron 0 10 * * *）
• 执行命令：python3 <脚本路径>/search_douyin.py "<关键词>"（有时间参数则附加 --start-date/--end-date）
• 通用 crontab：0 10 * * * python3 /path/to/search_douyin.py "<关键词>"

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