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

# 抖音每日最具影响力账号

## 概述

提供抖音全品类/分品类账号每日/每周/每月的表现榜单查询。

**更新时间与回溯范围：**

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

**三大核心能力：**

- 📊 **排名查询** — 查日榜、周榜、月榜 TOP50
- 🎯 **领域查询** — 按品类筛选（美食、旅行、科技、游戏等）
- 📥 **报告下载** — 生成 HTML 可视化报告，支持导出 PDF/截图

---

## 目标用户与使用场景

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

---

## 触发词与意图识别

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

---

## 执行流程

### 第一步：查询数据（默认展示 TOP 20）

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

脚本会自动解析：

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

脚本输出包含：
1. Markdown 格式榜单表格（最多20条）
2. "更多操作"引导模块
3. "订阅服务"引导模块（根据用户选择的赛道动态展示）

### 第二步：生成 HTML 报告（立即执行）

```bash
python scripts/generate_report.py --data /path/to/data.json --limit 20  # 自动生成文件名
```

> **重要**：HTML 报告展示的数据条数必须与对话中展示的数量保持一致！
> - 对话默认展示 20 条 → HTML 报告也只展示 20 条
> - 用户要求查看全部 50 条 → 重新生成完整报告

使用 `deliver_attachments` 交付 HTML 文件。

### 用户查看全部数据时

```bash
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  # 自动生成完整文件名
```

使用 `deliver_attachments` 交付完整 HTML 文件。

---

## 输出模板

### Markdown 表格（对话输出）

```
📊 抖音{period_label} · {category_label}

数据日期：{date}
共 {total} 个账号上榜（展示 TOP {displayed} 条）

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

> **时间边界处理**（warning 插入榜单说明开头）：
> - 查询当日/未来日期：「非常抱歉🙏，我们最新的是昨日/上周/上月的数据，将为您提供最接近您需求的昨日/上周/上月热榜。」
> - 查询早于回溯日期：「非常抱歉🙏，目前榜单最多支持回溯「过去7天/过去3周/过去3月」，我将为您查询最接近您需求的时间范围~」
> - 正常查询：warning 为空，直接展示更新时间

📐 综合评分：根据总粉丝数、新增粉丝增量、新增点赞/分享/评论加权计算，满分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、财富理财、二次元、居家装修、学习教育、小剧场、数码科技、旅行、美食、化妆美容、动物、亲子、汽车、情感、三农、健康医学、潮流风尚、舞蹈才艺、颜值造型、人文、音乐、影视、身体锻炼、体育、明星娱乐、游戏

## 生成 HTML 报告
- 执行脚本生成 HTML 报告文件
  - 脚本调用示例：`python scripts/generate_report.py --data <fetch_rank输出> --limit 20  # 自动生成文件名`
  - 文件名格式：`{赛道}{周期}{YYYYMMDD}_{时间戳}.html（如 美食周榜20260511_时间戳.html）`（如 `20260511_美食.html`）

> ⚠️ **字段说明**：默认展示 TOP 20 条数据，最高互动 = 点赞 + 评论 + 分享

---

## 订阅服务

用户确认订阅后，使用 `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 示例：`查询抖音最新日榜（全品类），生成报告并推送给用户`

### 订阅赛道账号表现
- automation prompt 示例：`查询抖音最新日榜（美食赛道），生成报告并推送给用户`

---

## 常见问题

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

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

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

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

---

## 资源索引

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

---

## 注意事项

- ⚠️ **时间边界处理（必须严格遵守）**：
  - **查询当日及未来日期**：在输出开头回复「非常抱歉🙏，我们最新的是昨日/上周/上月的数据，将为您提供最接近您需求的昨日/上周/上月热榜。」然后继续展示最近一期数据
  - **查询时间早于回溯日期**：在输出开头回复「非常抱歉🙏，目前榜单最多支持回溯「过去7天/过去3周/过去3月」，我将为您查询最接近您需求的时间范围~」然后继续展示最接近的可查数据
- 严禁任何联网搜索
- ⚠️ **数据一致性**：对话展示多少条，HTML 报告就展示多少条，两者必须一致
- 日榜默认展示 TOP 20，完整 50 条通过报告或追问查看
- HTML 报告账号名均可点击跳转抖音主页
- 生成报告前确保 workspace 有写权限