抖音作品查询

鉴权

获取 API Key

请前往 红狐hub 获取API KEY

配置 API Key

方案1: 以OpenClaw为例，将REDFOX_API_KEY添加到~/.openclaw/openclaw.json中，部分内容如下：

{ "env": { "REDFOX_API_KEY": "ak_xxxx..." } }

方案2: 终端配置

export REDFOX_API_KEY="ak_xxxx..."

工作流程

Step 1: 用户意图理解（查询脚本前）

⚠️ 核心规则：应该语义理解，优先提取用户描述中的细分方向词，而非泛化的大类词

1. 判断用户是否提到赛道关键词：

• 无赛道关键词（如"最近的热门作品有哪些"、"最近有什么热门内容"、"看看热门数据"）→ 直接调用脚本，关键词传空字符串 ""，查询全站热门
• 有赛道关键词 → 继续提取和判断

2. 提取精确搜索关键词（仅当用户提到赛道时执行）：

• 分析用户描述：从用户自我介绍或需求描述中提取明确的细分领域词
• 示例分析：
  • 用户输入："我是一个文艺类自媒体万粉抖音博主，平时会发小众电影审美积累、书评、乐评、港台文化等相关内容，帮我找电影领域热门话题"
  • 分析结果：用户提到的细分方向 = 小众电影、书评、乐评、港台文化
  • 将前文场景和"电影"相关，得到细分词 = 小众电影、港台电影、电影乐评
  • 搜索关键词：小众电影、港台电影、电影乐评
  • ❌ 错误做法：只提取泛化词「电影」去搜索

3. 关键词类型判断（仅当提取到关键词时执行）：

• 细分词/垂直赛道（含具体场景/属性修饰的词，如"职场穿搭"、"减脂餐"、"小个子穿搭"）→ 直接搜索，无需拓展询问
• 泛化词/分类（纯大类词，如"穿搭"、"美食"、"美妆"，无任何修饰）→ 执行拓展策略（Step 2）
• 判断原则：有修饰词（场景/人群/风格/意图）= 细分词，直接搜索；无修饰词 = 泛化词，需要拓展

Step 2: 泛化词拓展策略

泛化词处理流程（⚠️ 必须等待用户明确回复后再调用脚本！）：

第一步：生成细分词（禁止调用脚本搜索数据）

• 拓展词生成原则：
  • 词的大小适中：词语不要加组合，避免过细（如"中产穿搭"太细，查不到数据）
  • 必须覆盖不同场景：趋势词、人群词、场景词、意图词各 2-3 个
• 输出示例：

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

第二步：等待用户回复

• ❌ 禁止：用户未回复时调用脚本
• ✅ 正确：只等待用户明确回复「拓展」或「不拓展」后再执行

第三步：根据用户明确回复执行

• 用户回复「拓展」 → 将 10 个细分词以英文逗号 , 连接为一个字符串（不加空格），仅调用一次脚本传入（如 "老钱,轻奢,品质生活"），禁止逐个词多次调用
• 用户回复「不拓展」或「继续」 → 调用脚本搜索原关键词
• 用户未回复或回复其他内容 → 识别对应意图

Step 3: 调用搜索接口

3.1 时间解析规则

在调用脚本前，需判断用户 query 中是否包含时间信息，并解析为 startDate 和 endDate 参数：

• 默认值：startDate 和 endDate 均为空字符串 ""，表示不限定时间范围

• 需要解析时间的场景：用户 query 中包含明确的时间表达，例如：

  • 绝对日期：2025年6月1日、2025-06-01、6月1号 → 解析为 2025-06-01
  • 相对日期：昨天、前天、最近3天、最近一周、最近7天 → 根据当前日期计算
  • 日期范围：6月1日到6月3日、上周 → 分别解析为 startDate 和 endDate
  • 模糊时间：最近的、最新的 → 不解析为日期，保持默认空字符串，由接口返回最新数据

• 解析规则：

  • 仅解析绝对日期或明确相对日期，不解析模糊时间词
  • 日期格式统一为 YYYY-MM-DD
  • 若用户只提到单个日期（如6月1日），则 startDate = endDate = 该日期
  • 若用户提到时间范围（如最近7天），则 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 / latestHotArticles）包含字段：

Step 4: 判断搜索结果并展示

根据 articles 数量选择不同的展示策略：

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

A1. 告知用户数据查询范围

首先输出一句提示，告知用户本次查询的范围：

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

⚠️ 总数校验规则：N 必须直接取自脚本返回 JSON 中 articles 数组的长度（len(articles)），禁止人工计数或估算，确保总数准确无误。

A2. 展示作品表格（默认前 20 条）

将 articles 渲染为 Markdown 表格，默认展示前 20 条（按点赞数降序），格式如下：

| #   | 作品标题             | 作者   | 点赞数 | 评论数 | 分享数 | 收藏数 | 发布时间 |
| --- | -------------------- | ------ | ------ | ------ | ------ | ------ | -------- |
| 1   | [标题文字](作品链接) | 作者名 | 305.2w | 7.1w   | 51.0w  | 14.7w  | 06-02 19:55 |
| 2   | [标题文字](作品链接) | 作者名 | 158.3w | 3.2w   | 22.1w  | 8.5w   | 05-30 15:30 |

数字格式化规则：

• 小于 10000：直接展示原始数字（如 320）
• 大于等于 10000：使用 x.xw 格式（如 1.2w 代表 12000）

发布时间格式化规则：

• 将 publish_time（格式 YYYY-MM-DD HH:MM:SS）转换为 MM-DD HH:MM 格式展示（如 2026-06-02 19:55:03 → 06-02 19:55）
• 不管用户是否指定了时间范围查询，均展示发布时间列

标题链接规则：

• 作品标题使用 Markdown 链接格式 [标题](work_url)，点击可跳转到抖音作品页
• 如果标题过长（超过 30 字），截断并加 ...

A3. 查看全部数据（当结果超过 20 条时）

如果 articles 总条数 > 20，在表格下方输出提示后不等待，立刻继续输出 A4：

以上展示了前 20 条数据，还剩 N 条未展示。需要查看全部数据吗？回复「查看全部」即可。

当用户在后续对话中回复「查看全部」时：将第 21 条起的所有剩余数据，以相同表格格式续接展示，编号从 #21 开始连续递增，直到全部展示完毕。

articles ≤ 20 时：跳过本步骤，直接进入 A4。

A4. 展示热门推荐数据（latestHotArticles）

仅在 articles 总条数 ≤ 10 时执行本步骤。

如果 articles 总条数 ≤ 10 且 latestHotArticles 不为空，展示热门推荐作品表格（最多 10 条），标题为：

🔥 近期热门推荐作品

使用与 A2 相同的表格格式和数字格式化规则。若为空或 articles > 10 则跳过本模块，不输出任何内容。

A5. 展示热门话题（hotTopics）

仅在 articles 总条数 ≤ 10 时执行本步骤。

如果 articles 总条数 ≤ 10 且 hotTopics 不为空，以列表形式展示热门话题：

🏷️ 热门话题

• #话题1
• #话题2
• ...

若为空或 articles > 10 则跳过本模块，不输出任何内容。

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

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

B1. 抱歉提示 + 拓词推荐

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

AI 必须根据用户搜索的关键词生成 固定 10 个扩展搜索词，以英文逗号 , 分隔展示在一行括号内。

生成规则：

• 基于原始关键词进行语义扩展（如同义词、上下位词、相关场景词）
• 每个扩展词保持在 2-6 个汉字
• 优先推荐更细分或更宽泛的相关方向
• 必须生成恰好 10 个，不得少于 10 个

B2. 热门推荐数据（latestHotArticles）

如果 latestHotArticles 不为空，展示热门推荐作品：

💡 我们为您推荐了近期的其他热门作品供参考，或许对您有帮助：

随后以表格格式展示 latestHotArticles（最多 10 条），格式同情况 A 的表格。若为空则跳过本模块，不输出任何内容。

B3. 展示热门话题（hotTopics）

如果 hotTopics 不为空，以列表形式展示，格式同 A5。若为空则跳过本模块，不输出任何内容。

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

Step 5: 提示订阅

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

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

Step 6: 创建定时任务（用户在后续对话中回复「确认订阅」时执行）

优先使用当前平台内置的定时任务/自动化能力创建订阅，若无则提供通用配置方案：

1. 平台内置定时任务（优先） 如果当前平台提供定时任务或 cron 自动化功能：直接调用该功能创建订阅，配置如下：

• 任务名称：抖音爆款作品订阅 - <关键词>
• 执行频率：每天 10:00（北京时间，cron 表达式 0 10 * * *）
• 执行内容：运行 python3 <脚本路径>/search_douyin.py "<关键词>"（如有时间参数则附加 --start-date 和 --end-date），将结果按 SKILL.md 中 Step 4-5 的格式展示并推送到当前对话

2. 通用配置方案（平台无内置定时任务时） 向用户提供以下信息，由用户自行配置：

• 执行命令：python3 <脚本路径>/search_douyin.py "<关键词>"（如有时间参数则附加 --start-date 和 --end-date）
• Linux/macOS crontab：0 10 * * * python3 /path/to/search_douyin.py "<关键词>"（如有时间参数则附加 --start-date 和 --end-date）
• 其他平台：参照对应平台的定时任务文档配置上述命令

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