VicroCode 鬼斧神工 / SKILL 技能包
抖音获取多关键词热度趋势
抖音获取多关键词热度趋势
工具截图
工具说明
# 抖音获取多关键词热度趋势工具说明
## 一、工具简介
**工具名称：** 抖音获取多关键词热度趋势
**功能定位：** 批量查询多个抖音关键词在指定天数内的热度趋势，并生成中文 Markdown 报告和 PNG 趋势图。
该工具适合用于分析抖音平台上多个关键词、品牌词、话题词的热度变化情况，帮助用户进行内容选题、品牌监测、竞品对比和热点趋势观察。
---
## 二、适用场景
该工具适用于以下场景：
1. **多关键词热度查询**
- 查询多个关键词在抖音上的近期热度。
- 例如：查询“华为、苹果、鸿蒙”近 7 天热度趋势。
2. **品牌或产品热度对比**
- 对比不同品牌、产品、IP、明星、事件的热度变化。
- 例如：比较“比亚迪、特斯拉、小米汽车”的抖音热度。
3. **热点趋势分析**
- 观察多个话题在短期内的热度升降。
- 适合内容运营、短视频选题、市场分析等工作。
4. **生成可视化报告**
- 自动生成中文 Markdown 热度明细表。
- 自动生成关键词汇总表。
- 自动生成 PNG 多折线趋势图。
5. **单关键词趋势查看**
- 即使只输入一个关键词，也可以正常查询并生成趋势结果。
---
## 三、核心能力
工具执行后默认生成：
1. **Markdown 中文报告**
- 文件名：`douyin_trend.md`
- 内容包括：
- 热度明细表
- 关键词汇总表
- 查询错误表，如存在失败关键词
2. **PNG 趋势图**
- 文件名：`douyin_trend.png`
- 仅在识别到有效热度数据时生成。
- 支持多关键词折线对比。
3. **失败容错**
- 某个关键词查询失败时，不会中断全部任务。
- 成功关键词继续处理。
- 失败信息会写入 Markdown 报告。
---
## 四、输入要求
### 1. 关键词
支持输入一个或多个关键词。
可使用以下方式分隔：
- 英文逗号：`,`
- 中文逗号：`，`
- 分号：`;`
- 中文分号：`；`
- 换行
示例：
```text
华为，苹果，鸿蒙
```
或：
```text
华为
苹果
鸿蒙
```
### 2. 关键词规则
- 每个关键词长度必须为 **1—100 个字符**。
- 工具会自动去除首尾空格。
- 工具会自动去重，但保留原始输入顺序。
- 如果没有有效关键词，需要用户补充关键词。
### 3. 查询天数
- 查询天数必须是 **1—30 的整数**。
- 如果用户未指定，默认查询 **近 3 天**。
---
## 五、费用说明
该工具为付费工具。
根据当前 Skill 配置说明：
- 工具一次只接受 **一个关键词**。
- 多个关键词需要逐个调用。
- 查询 N 个关键词，通常需要调用 N 次。
- 单次调用价格以平台结算为准。
- Skill 文档中说明单次调用价格为 **10.00 金币**，并可能存在免费试用额度。
- 当前工具元信息中显示下载价格为 **1.00 金币**，实际扣费请以 VicroCode平台结算结果为准。
在执行查询前，应告知用户：
- 关键词数量
- 预计调用次数
- 可能产生的费用
例如：
```text
本次将查询 3 个关键词，预计调用 3 次。单次调用费用以平台结算为准，可能产生金币消耗。
```
---
## 六、使用限制
1. **一次 API 调用只查询一个关键词**
- 多关键词查询需要逐个调用接口。
2. **查询天数限制**
- 仅支持 1—30 天范围内的查询。
3. **不补造数据**
- 如果上游接口未返回有效日期或热度字段，工具不会估算或伪造数据。
4. **趋势图生成条件**
- 只有识别到有效热度数据点时才生成 PNG 趋势图。
- 如果没有有效数据，只生成 Markdown 报告并说明原因。
5. **默认不生成 Excel 或 CSV**
- 默认只生成 Markdown 和 PNG。
- 只有用户明确要求时，才额外生成 Excel、CSV 等格式。
6. **需要有效 API Key**
- 必须配置环境变量 `VICROCODE_API_KEY`。
- 不允许将真实令牌写入聊天、源码、脚本参数或报告文件。
7. **金币余额不足会失败**
- 如果返回 HTTP 402 或 `INSUFFICIENT_BALANCE`，说明余额不足。
- 用户需要充值后重试。
---
## 七、使用步骤
### 步骤 1：连接 VicroCode API
首次使用时，打开一键连接网址：
```text
https://www.vicoco.cn/user-center/my-skills?connect=skill-463b0b80
```
登录后，平台会自动：
1. 添加所需 API 工具。
2. 创建或复用调用令牌。
3. 授权该 Skill 使用对应工具。
---
### 步骤 2：配置 API Key
将平台生成的调用令牌保存为环境变量：
```text
VICROCODE_API_KEY
```
注意：
- 不要把 API Key 写入聊天记录。
- 不要写入 `SKILL.md`。
- 不要提交到 Git 仓库。
- 推荐放在项目根目录 `.env` 文件中。
- `.env` 应加入 `.gitignore`。
---
### 步骤 3：准备输入内容
向工具提供关键词和查询天数。
示例：
```text
查询华为、苹果、鸿蒙近 7 天的抖音热度趋势
```
如果未指定天数，默认查询近 3 天。
---
### 步骤 4：执行查询
工具会自动完成以下操作：
1. 校验关键词和查询天数。
2. 检查 `VICROCODE_API_KEY` 是否存在。
3. 按关键词逐个调用接口。
4. 解析上游返回数据。
5. 识别日期字段和热度字段。
6. 生成 Markdown 报告。
7. 生成 PNG 趋势图。
---
### 步骤 5：查看输出结果
默认输出文件包括：
```text
douyin_trend.md
douyin_trend.png
```
其中：
- `douyin_trend.md`：中文热度报告。
- `douyin_trend.png`：多关键词趋势图。
如果没有有效热度数据，则可能不会生成趋势图。
---
## 八、输出内容说明
### 1. 热度明细表
示例：
| 关键词 | 日期 | 热度 |
|---|---|---:|
| 华为 | 2026-08-20 | 12345 |
| 苹果 | 2026-08-20 | 9876 |
---
### 2. 关键词汇总表
示例：
| 关键词 | 查询状态 | 数据点数 | 最低热度 | 最高热度 | 平均热度 |
|---|---|---:|---:|---:|---:|
| 华为 | 成功 | 3 | 10000 | 15000 | 12333.33 |
| 苹果 | 成功 | 3 | 8000 | 12000 | 9800.00 |
---
### 3. 查询错误表
当部分关键词失败时，会增加错误表。
示例：
| 关键词 | 状态码 | 错误码 | 错误信息 |
|---|---:|---|---|
| 某关键词 | 402 | INSUFFICIENT_BALANCE | 金币不足，请充值 |
---
## 九、错误处理说明
### 1. 缺少 API Key
如果未配置 `VICROCODE_API_KEY`，工具会停止执行，并提示用户完成首次配置。
---
### 2. 金币不足
如果返回：
```text
HTTP 402
```
或错误码：
```text
INSUFFICIENT_BALANCE
```
表示金币余额不足。
可前往充值：
```text
https://www.vicoco.cn/user-recharge
```
---
### 3. 权限或令牌错误
如果返回 HTTP 401 或 403，通常表示：
- API Key 无效
- 工具未授权
- 调用令牌权限不足
需要检查 VicroCode 工具授权和调用令牌配置。
---
### 4. 单个关键词失败
如果多个关键词中某一个失败：
- 工具会继续查询其他关键词。
- 失败信息会写入 Markdown 报告。
- 不会隐藏失败关键词。
---
### 5. 没有有效数据
如果接口返回内容中无法识别有效日期和热度字段：
- 不会生成虚假数据。
- 不会生成趋势图。
- Markdown 报告会说明未识别到有效热度数据。
---
## 十、数据识别规则
工具会从上游返回的动态 `data` 结构中递归识别日期和热度字段。
### 日期字段识别顺序
依次识别：
```text
date
day
datetime
time
timestamp
stat_date
```
### 热度字段识别顺序
依次识别：
```text
heat
hot
hot_value
value
index
score
heat_value
```
### 数据处理规则
- 只接受可转换为有限数字的热度值。
- 重复的关键词、日期、热度组合只保留一次。
- 最大递归深度为 10。
- 无法识别的数据不会补造或估算。
---
## 十一、推荐使用示例
### 示例 1：查询多个品牌词
用户输入：
```text
查询华为、小米、苹果近 7 天抖音热度
```
工具行为：
- 查询关键词数：3
- 调用次数：3
- 查询天数：7
- 输出：
- `douyin_trend.md`
- `douyin_trend.png`
---
### 示例 2：查询单个关键词
用户输入：
```text
查询鸿蒙近 3 天抖音热度
```
工具行为：
- 查询关键词数：1
- 调用次数：1
- 查询天数：3
- 输出单关键词热度报告和趋势图。
---
### 示例 3：未指定天数
用户输入：
```text
查询华为、苹果、鸿蒙的抖音热度
```
工具行为：
- 默认查询近 3 天。
- 查询 3 个关键词。
- 调用 3 次接口。
---
## 十二、最终回复要求
工具执行完成后，面向用户的回复应包含：
1. 成功查询的关键词数量。
2. 失败关键词，如有。
3. 实际调用次数。
4. 费用提示。
5. Markdown 报告链接或路径。
6. 趋势图链接或路径，如已生成。
不应展示：
- Python 代码
- Shell 命令
- JSON 请求体
- 原始 API 响应
- API Key 或任何令牌信息
运行时收费披露
此 SKILL 包含运行时内置收费，使用前请核对收费声明。
[
{
"text": "## 工具与费用",
"file_path": "SKILL.md",
"line_number": 18
},
{
"text": "- 单次调用价格为 10.00 金币，当前提供 5 次免费试用；实际扣费和免费额度以平台结算结果为准。",
"file_path": "SKILL.md",
"line_number": 25
},
{
"text": "- 查询 N 个关键词通常需要调用 N 次。免费额度用完后，预计费用为 N × 10.00 金币。",
"file_path": "SKILL.md",
"line_number": 26
},
{
"text": "调用前先告知用户关键词数量、预计调用次数以及可能产生的费用。用户已明确提出查询时，直接执行，不要重复要求确认。",
"file_path": "SKILL.md",
"line_number": 29
},
{
"text": "最终面向用户的回复只展示或链接中文 Markdown 表格和趋势图，并用简短中文说明成功关键词、失败关键词、实际调用次数和费用提示。不要展示 Python、Shell、JSON、请求体或原始响应内容。",
"file_path": "SKILL.md",
"line_number": 87
},
{
"text": "- HTTP 402 或响应错误码 `INSUFFICIENT_BALANCE`：保留错误码和平台返回的充值网址，明确说明金币不足；若响应没有充值网址，提供 https://www.vicrocode.com/user-recharge 。",
"file_path": "SKILL.md",
"line_number": 102
},
{
"text": "5. 失败关键词、错误码和金币不足信息没有被隐藏。",
"file_path": "SKILL.md",
"line_number": 117
},
{
"text": "default_prompt: 请提取用户提供的抖音关键词和查询天数，先说明调用次数与费用，再逐词调用已绑定工具，生成中文 Markdown 热度明细表、汇总表和 PNG 趋势图；默认不要生成 Excel 或 CSV，不要补造无法识别的数据。",
"file_path": "agents/openai.yaml",
"line_number": 3
},
{
"text": "return {\"keyword\": keyword, \"success\": False, \"code\": \"INSUFFICIENT_BALANCE\", \"status\": \"金币不足，请充值：\" + RECHARGE_URL, \"body\": body}",
"file_path": "scripts/douyin_trend.py",
"line_number": 124
},
{
"text": "lines += [\"\", f\"实际调用次数：{len(results)}\", \"费用提示：单次调用价格为 10.00 金币，实际扣费以平台结算结果为准。\"]",
"file_path": "scripts/douyin_trend.py",
"line_number": 151
},
{
"text": "print(f\"将查询 {len(words)} 个关键词，共调用 {len(words)} 次；单次价格 10.00 金币。\")",
"file_path": "scripts/douyin_trend.py",
"line_number": 198
}
]