douyin-top-account

name	douyin-top-account
description	抖音每日最具影响力账号榜单追踪分析工具；日榜每日17:30更新/回溯7天，周榜每周一17:30更新/回溯3周，月榜每月2号9点更新/回溯3月；当用户需要查询抖音账号排名、抖音日榜/周榜/月榜、抖音赛道TOP账号或下载榜单报告时使用
dependency	{}

抖音热门账号推荐

1. 简介

抖音每日最具影响力账号榜单追踪分析工具 -- 基于红狐数据 API，提供抖音全品类 / 分品类账号每日 / 每周 / 每月的表现榜单查询，支持排名查询、赛道筛选、HTML 可视化报告下载与定时订阅推送。

适用对象：新手内容创作者、品牌方 / 商务投放人员、MCN 机构 / 内容团队、行业分析师 / 咨询从业者。

---

2. 功能特性

核心功能：

• 排名查询 -- 查日榜、周榜、月榜 TOP50，支持全品类和分品类
• 赛道筛选 -- 按品类筛选（美食、旅行、科技、游戏等 27 个赛道）
• 报告下载 -- 生成 HTML 可视化报告，支持导出 PDF / 截图
• 定时订阅 -- 设置自动化定时推送，支持日 / 周 / 月频率

特色亮点：

• 日榜每日 17:30 更新 / 回溯 7 天，周榜每周一 17:30 更新 / 回溯 3 周，月榜每月 2 号 9 点更新 / 回溯 3 月
• 综合评分算法：根据总粉丝数、新增粉丝增量、新增点赞 / 分享 / 评论加权计算，满分 100
• 赛道模糊匹配：支持自然语言输入（如 "美妆" 自动映射到 "化妆美容"）
• 数据一致性保障：对话展示的数据条数与 HTML 报告严格一致

---

3. 一键安装

鉴权

获取 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..."

export REDFOX_API_KEY="ak_xxxx..."

依赖安装

无需安装第三方依赖，使用 Python 标准库即可运行。

---

4. 使用指南

基础使用

查询榜单数据（默认展示 TOP 20）：

python scripts/fetch_rank.py --query "用户原始问题" --limit 20 --output /path/to/data.json

脚本会自动解析：

• 时间：从用户文本识别日 / 周 / 月，未明确则默认日榜
• 日期：自动计算最新可用日期（日榜 17:30 更新，周榜周一 17:30 更新，月榜每月 2 号 9 点更新）
• 赛道：支持模糊匹配（如 "美妆" 映射为 "化妆美容"）

生成 HTML 报告：

python scripts/generate_report.py --data /path/to/data.json --limit 20

重要：HTML 报告展示的数据条数必须与对话中展示的数量保持一致。使用 deliver_attachments 交付 HTML 文件。

查看全部 50 条数据：

python scripts/fetch_rank.py --query "用户原始问题" --limit 50 --output /path/to/data_full.json
python scripts/generate_report.py --data /path/to/data_full.json --limit 50

高级使用

更新时间与回溯范围：

榜单类型	更新时间	回溯范围
日榜	每日17:30	过去7天
周榜	每周一17:30	过去3周
月榜	每月2号9点	过去3月

时间边界处理（必须严格遵守）：

• 查询当日及未来日期：回复「非常抱歉🙏，我们最新的是昨日/上周/上月的数据，将为您提供最接近您需求的昨日/上周/上月热榜。」
• 查询时间早于回溯日期：回复「非常抱歉🙏，目前榜单最多支持回溯「过去7天/过去3周/过去3月」，我将为您查询最接近您需求的时间范围~」

订阅服务：

用户确认订阅后，使用 automation_update 工具创建自动化任务：

• 日榜：FREQ=DAILY;BYHOUR=19;BYMINUTE=30
• 周榜：FREQ=WEEKLY;BYDAY=MO;BYHOUR=19;BYMINUTE=30
• 月榜：FREQ=MONTHLY;BYMONTHDAY=1;BYHOUR=16;BYMINUTE=0

automation prompt 示例：查询抖音最新日榜（全品类），生成报告并推送给用户

常用指令速查

用户意图	典型触发词	对应操作
排名查询	抖音日榜、周榜、月榜、TOP50、最夯账号、排行榜、最新推荐	调用脚本查询并格式化输出
领域查询	美食类/旅行类/游戏类/科技类...抖音排名	调用脚本并按赛道筛选
报告下载	下载报告、导出榜单、生成报告	运行 generate_report.py 生成 HTML

输出格式

Markdown 表格模板：

📊 抖音{period_label} · {category_label}
数据日期：{date}
共 {total} 个账号上榜（展示 TOP {displayed} 条）

💡 榜单说明：{warning}{period_update_time}，与实时数据存在差异

📐 综合评分：根据总粉丝数、新增粉丝增量、新增点赞/分享/评论加权计算，满分100

| 排名 | 账号名 | 综合评分 | 总粉丝数 | 新增粉丝 | 新增点赞 | 新增评论 | 新增分享 |
|:---:|--------|:-------:|:-------:|:-------:|:-------:|:-------:|:-------:|:-------:|
| 🥇 1 | [账号A](https://www.douyin.com/user/xxx) | 96 | 254.06w | 6919 | 24.64w | 6.68w | 13.39w |
| 🥈 2 | [账号B](https://www.douyin.com/user/xxx) | 89 | 113.55w | 1.91w | 7.90w | 4787 | 3.12w |
| 🥉 3 | [账号C](https://www.douyin.com/user/xxx) | 87 | 439.14w | 5859 | 16.51w | 993 | 687 |

输出完榜单后追加：

⚡ 更多操作
⏺️ 本次榜单完整共 50 条数据，是否需要查看剩余 30 条？

📬 订阅服务
1️⃣ 是否需要订阅每日/周/月的抖音账号最新排名？
2️⃣ 是否需要订阅具体赛道的账号表现？我们支持：个人才艺、生活vlog、财富理财、二次元、居家装修、学习教育、小剧场、数码科技、旅行、美食、化妆美容、动物、亲子、汽车、情感、三农、健康医学、潮流风尚、舞蹈才艺、颜值造型、人文、音乐、影视、身体锻炼、体育、明星娱乐、游戏

---

5. 使用场景

用户分层	核心痛点	使用方式
新手内容创作者 / 个体运营	不知道哪些账号做得好、无从借鉴、不知道自己水平在赛道内所处位置	查询 "美食类账号 TOP50"，获取对标参考
品牌方 / 商务投放人员	找达人效率低、数据维度单一、不了解账号历史表现	查询 "上周抖音美妆 TOP50"，获取投放候选
MCN 机构 / 内容团队	竞品账号情报获取难、无法快速掌握市场动态	查询 "最近一周游戏账号涨粉最快"，监控市场
行业分析师 / 咨询从业者	数据获取门槛高、缺乏可视化报告工具	生成 "3 月份抖音游戏类榜单分析报告"

预期收益：快速获取赛道动态、识别优质账号、降低投放决策成本、提升内容运营效率。

---

6. 项目架构

目录结构

douyin-top-account/
├── SKILL.md                          # 本文件
├── scripts/
│   ├── fetch_rank.py                 # 查询抖音榜单数据
│   └── generate_report.py            # 生成 HTML 可视化报告
└── references/
    ├── category_map.md               # 赛道映射表与匹配规则
    ├── update_rules.md               # 更新规则与日期计算逻辑
    ├── score_rules.md                # 评分算法说明
    └── api_docs.md                   # API 接口详细文档（技术参考）

技术栈

技术	用途
Python 标准库	数据查询与报告生成
红狐 API	抖音榜单数据来源
HTML / CSS	可视化报告渲染

核心模块说明

• fetch_rank.py：接收用户查询参数，调用红狐 API 获取榜单数据，自动解析时间、日期和赛道，输出 JSON 数据文件。
• generate_report.py：读取 fetch_rank 输出的 JSON 数据，生成带排名表格、统计卡片、排名算法的 HTML 可视化报告；账号名均可点击跳转抖音主页。

资源索引

文件	用途
scripts/fetch_rank.py	查询抖音榜单数据
scripts/generate_report.py	生成 HTML 可视化报告
references/category_map.md	赛道映射表与匹配规则
references/update_rules.md	更新规则与日期计算逻辑
references/score_rules.md	评分算法说明
references/api_docs.md	API 接口详细文档（技术参考）

---

7. 常见问答

安装

Q: 需要安装什么依赖？ A: 无需安装第三方依赖，使用 Python 标准库即可运行。

Q: 如何配置 API Key？ A: 请前往 红狐hub 获取 API KEY，然后通过环境变量 REDFOX_API_KEY 配置。

使用

Q: 日榜数据什么时候更新？ A: 每日 17:30 更新昨日数据。当前时间未到 17:30 时，脚本会自动取前天数据。

Q: 支持哪些赛道？ A: 支持 27 个赛道，完整列表见 references/category_map.md。

Q: 数据回溯范围？ A: 日榜可查过去 7 天，周榜可查过去 3 周，月榜可查过去 3 个月。

Q: 赛道识别失败怎么办？ A: 无法识别时，请列出完整赛道列表供用户选择。

Q: 默认展示多少条数据？ A: 日榜默认展示 TOP 20，完整 50 条通过报告或追问查看。

故障排除

Q: HTML 报告生成失败？ A: 确保 workspace 有写权限，且 JSON 数据文件路径正确。

Q: 数据不一致？ A: 对话展示多少条，HTML 报告就展示多少条，两者必须一致。如果用户要求查看全部 50 条，需要重新生成完整报告。

---