git:20260604.cdf46a5 to git:20260604.cf3fe8e

- description: 抖音爆款作品查询工具。根据用户输入的关键词搜索抖音热门爆款作品，结果以表格展示。当用户想要查找抖音热门内容、搜索抖音爆款视频、查询抖音作品数据、了解某类内容在抖音的表现时使用。触发词包括：抖音爆款、抖音热门、抖音热榜、抖音作品查询、抖音搜索、爆款视频、热门视频。

- ## 鉴权

-

- ### 获取 API Key

-

- 请前往 [红狐hub](https://redfox.hk/settings/api-keys?source=github) 获取API KEY

-

- ### 配置 API Key

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

- ```bash

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

- ```

- 方案2: 终端配置

- ```bash

- export REDFOX_API_KEY="ak_xxxx..."

- ```

- ## 工作流程

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

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

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

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

- - **有赛道关键词** → 继续提取和判断

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

- - **分析用户描述**：从用户自我介绍或需求描述中提取明确的细分领域词

- - 示例分析：

- - 用户输入："我是一个文艺类自媒体万粉抖音博主，平时会发小众电影审美积累、书评、乐评、港台文化等相关内容，帮我找电影领域热门话题"

- - 分析结果：用户提到的细分方向 = 小众电影、书评、乐评、港台文化

- - 将前文场景和"电影"相关，得到细分词 = 小众电影、港台电影、电影乐评

- - 搜索关键词：小众电影、港台电影、电影乐评

- - ❌ 错误做法：只提取泛化词「电影」去搜索

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

- - **细分词/垂直赛道**（含具体场景/属性修饰的词，如"职场穿搭"、"减脂餐"、"小个子穿搭"）→ 直接搜索，无需拓展询问

- - **泛化词/分类**（纯大类词，如"穿搭"、"美食"、"美妆"，无任何修饰）→ 执行拓展策略（Step 2）

- - **判断原则**：有修饰词（场景/人群/风格/意图）= 细分词，直接搜索；无修饰词 = 泛化词，需要拓展

- ### Step 2: 泛化词拓展策略

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

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

- - 拓展词生成原则：

- - **词的大小适中**：词语不要加组合，避免过细（如"中产穿搭"太细，查不到数据）

- - **必须覆盖不同场景**：趋势词、人群词、场景词、意图词各 2-3 个

- - 输出示例：

- ```

- 我识别到「中产」是较大的分类，已查询近期热门趋势，推荐以下细分方向：

- 老钱,轻奢,品质生活,松弛感,高级感穿搭,体面,法式穿搭,律师,医生,品质家居

- 回复「拓展」将同时搜索这 10 个词，回复「不拓展」将继续搜索「中产」

- ```

- **第二步：等待用户回复**

- - ❌ **禁止**：用户未回复时调用脚本

- - ✅ **正确**：只等待用户明确回复「拓展」或「不拓展」后再执行

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

- - 用户回复「拓展」 → 将 10 个细分词以英文逗号 `,` 连接为一个字符串（不加空格），**仅调用一次脚本**传入（如 `"老钱,轻奢,品质生活"`），禁止逐个词多次调用

- - 用户回复「不拓展」或「继续」 → 调用脚本搜索原关键词

- - 用户未回复或回复其他内容 → 识别对应意图

- ### Step 3: 调用搜索接口

- 在调用脚本前，需判断用户 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` = 范围结束日（今天）

- - 年份省略时默认取当前年份

- 根据时间解析结果，构建脚本调用命令：

-

- **无时间参数时**：

- ```

- **有时间参数时**：

- ```bash

- 仅传入非空的时间参数，空字符串的参数无需传入（脚本默认值为空字符串）。

-

- 脚本返回 JSON 对象，包含以下字段：

-

- | 字段 | 说明 |

- | ------------------ | ---------------- |

- | articles | 搜索匹配的作品列表（按点赞数降序） |

- | latestHotArticles | 近期热门推荐作品列表 |

- | hotTopics | 热门话题列表 |

-

- 每条作品（articles / latestHotArticles）包含字段：

- | 字段 | 说明 |

- | -------------- | -------- |

- | title | 作品标题 |

- | author | 作者名称 |

- | like_count | 点赞数 |

- | comment_count | 评论数 |

- | share_count | 分享数 |

- | collect_count | 收藏数 |

- | work_url | 作品链接 |

- | publish_time | 发布时间 |

- | follower_count | 粉丝数 |

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

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

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

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

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

- **⚠️ 总数校验规则**：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: 提示订阅

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

- ### 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 将自动查询最新数据并通知你。"