x-top-account git:20260923.2869aa4A

Immutable. This exact content is served forever at /api/v1/blob/0881c3fc6b33918a.

---
name: x-top-account
description: X(Twitter)每日最具影响力账号榜单追踪分析工具；每日早上9:00更新前一天榜单，最多回溯7天；支持性别（男/女/全部）与32个行业分类筛选、分页翻页、HTML可视化报告导出与定时订阅推送；当用户需要查询X/Twitter账号排名、热门账号榜、分行业/分性别榜单、下载榜单报告或订阅推送时使用。触发词：X榜单、Twitter榜单、推特账号排名、X热门账号、Twitter影响力榜、推特大V排行。
dependency: {}
---

# X (Twitter) 热门账号榜

## 1. 简介

X (Twitter) 每日最具影响力账号榜单追踪分析工具 -- 基于红狐数据 API，提供 X 平台全行业 / 分行业 / 分性别的每日影响力账号榜单查询，支持排名查询、筛选过滤、分页翻页、HTML 可视化报告下载与定时订阅推送。

**适用对象**：出海内容创作者、品牌方 / 海外投放人员、MCN 机构 / 跨境运营团队、行业分析师 / 咨询从业者。

---

## 2. 功能特性

**核心功能**：

- 排名查询 -- 查每日 TOP 账号榜（每页 20 条，共 10 页 200 条）
- 筛选过滤 -- 按性别与 32 个行业分类精准筛选，支持自然语言模糊匹配
- 分页翻页 -- 支持指定页码查询，对话内逐页浏览
- 报告下载 -- 生成 X 平台风格 HTML 报告，支持一键导出 PDF / 高清图片
- 定时订阅 -- 设置每日定时推送，支持按性别 / 行业组合订阅

**特色亮点**：

- 每日早上 9:00 更新前一天榜单，最多回溯 7 天
- 影响力评分：结合粉丝数、互动量、曝光数等加权综合评估，满分 100
- 行业模糊匹配：支持自然语言输入（如 "宠物" 自动映射到 "萌宠动物"）
- 多维数据：国家/地区、主行业、日涨幅、X 粉丝数、其他平台粉丝数、专题标签一览无余

---

## 3. 一键安装

### 鉴权

#### 获取 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: 终端配置：export REDFOX_API_KEY="ak_xxxx..."

```bash
export REDFOX_API_KEY="ak_xxxx..."
```

### 依赖安装

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

---

## 4. 使用指南

### 基础使用

**查询榜单数据（默认第 1 页 20 条）并生成 HTML 报告**：

```bash
python scripts/fetch_rank.py --query "用户原始问题" --html
```

脚本会自动解析：
- **日期**：未明确则取最新可用日期（每日 9:00 更新，9 点后为昨日，9 点前为前日）
- **性别**：识别 男/女（如 "女博主" → female），未明确则 all
- **行业**：模糊匹配 32 个行业（如 "宠物" → "萌宠动物"），接口 category 传行业中文名，未明确则 all；skill 内部不暴露英文分类值
- **页码**：识别 "第2页" 等表达，未明确则第 1 页

**翻页查询**：

```bash
python scripts/fetch_rank.py --query "用户原始问题" --page 2 --html
```

**显式指定筛选条件**（优先级高于 --query 解析结果）：

```bash
python scripts/fetch_rank.py --date 2026-09-20 --gender female --category "萌宠动物" --html
```

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

### 高级使用

**更新时间与回溯范围（必须输出给用户）**：

- 榜单每日早上 **9:00** 更新**前一天**数据
- 最多回溯**过去 7 天**

**时间边界处理（必须严格遵守）**：
- 查询当日及未来日期：回复「非常抱歉🙏，我们最新的是昨日的数据，将为您提供最接近您需求的昨日热榜。」
- 查询时间早于回溯日期：回复「非常抱歉🙏，目前榜单最多支持回溯「过去7天」，我将为您查询最接近您需求的时间范围~」
- 目标日期接口返回空数据：脚本自动回退到最近可用日期并输出 `[WARN]` 提示，需转述给用户

**订阅服务**：

用户确认订阅后，使用 `automation_update` 工具创建自动化任务：
- 每日订阅：`FREQ=DAILY;BYHOUR=9;BYMINUTE=30`（数据 9:00 更新后推送）

automation prompt 示例：`查询X(Twitter)最新热门账号榜（行业：全部行业，性别：全部），生成报告并推送给用户`

**订阅询问时必须罗列全部筛选项**（见「输出格式」订阅服务模板）：
- 性别：全部(all) / 男(male) / 女(female)
- 行业分类：32 个行业中文名全量罗列，完整枚举见 [references/category_map.md](references/category_map.md)

### 常用指令速查

| 用户意图 | 典型触发词 | 对应操作 |
| -------- | ---------- | -------- |
| 排名查询 | X榜单、Twitter日榜、推特热门账号、影响力排行 | 调用脚本查询并格式化输出 |
| 筛选查询 | 宠物类/科技类/女博主...Twitter排名 | 调用脚本并按行业/性别筛选 |
| 翻页 | 第2页、下一页、继续看 | 加 --page 参数重新查询 |
| 报告下载 | 下载报告、导出榜单、生成报告 | 运行脚本加 --html 生成并交付 |

### 输出格式

**Markdown 表格模板**：

```
📈 X (Twitter) 热门账号榜 · {category_label} · {gender_label}
数据日期：{rankDate}（第 {pageNum}/{pages} 页）
共 {total} 个账号上榜（本页展示 20 条）

💡 榜单说明：每日早上 9:00 更新前一天榜单，与实时数据存在差异
📐 影响力评分：结合粉丝数、互动量、曝光数等加权综合评估，满分 100

| 排名 | 账号名 | 账号简介 | 国家/地区 | 主行业 | 影响力评分 | 日涨幅 | X粉丝数 | 其他平台粉丝数 | 专题标签 |
|:---:|--------|--------|:---:|--------|:---:|:---:|:---:|--------|--------|
| 🥇 1 | [Elon Musk](profile_url)<br>*Tech Entrepreneur and CEO* | biography 简介（前 60 字） | 美国 | Tech & Software | 99/100 | +1.25% | 2.2亿+ | — | 账号标签 |
| 🥈 2 | [MrBeast](profile_url)<br>*Creator & Philanthropist* | biography 简介（前 60 字） | 美国 | Entertainment & Culture | 97/100 | +0.88% | 3,100w+ | YouTube 4亿+ | — |
| 🥉 3 | [iJustine](profile_url)<br>*Tech Vlogger* | biography 简介（前 60 字） | 美国 | Tech & Software | 93/100 | +0.69% | 180w+ | YouTube 7,100w+ / TikTok 1,600w+ | Women in Tech / STEM |
```

**字段展示规则**：
- 账号名：Markdown 链接 `[fullName](profileUrl)` + `<br>` + 头衔（`title`，斜体），头衔不换列、不省略；1-3 名加 🥇🥈🥉
- 账号简介：仅 `biography`（过长时截取前 60 字），头衔不放入本列
- 影响力评分：xScore 四舍五入取整，格式 `99/100`
- X粉丝数：≥1亿 显示 `x.x亿+`，≥1万 显示 `x,xxxw+`
- 其他平台粉丝数：逐条展示 `otherNetworks[].network` 平台名 + `followersFmt`（如 `YouTube 400w+`；字段名是 `network`，不是 `platform`），多个平台用 ` / ` 连接，无则 `—`
- 专题标签：取专题话题 topics，无则取公益标签 cause，均无则 `—`
- 完整性：表格 10 列全部输出，不得为压缩列宽省略任何字段或整列；HTML 报告与对话表格版式保持一致（头衔在账号名下方，简介列仅 biography）

输出完榜单后追加：

```
总结榜单构成
{AI 对榜单数据做一些分析：头部集中度、行业分布、国家分布、涨粉亮点等}

⚡ 更多操作
• 点击下方下载 HTML 报告文件，可在浏览器中打开查看，支持一键导出 PDF / 高清图片
• 本次榜单完整共 {total} 条数据，是否需要继续查看第 {pageNum+1} 页？

📬 订阅服务
1️⃣ 是否需要订阅每日 X(Twitter) 账号最新排名，订阅后定时推送给您（每日早上 9:00 更新前一天榜单）。
2️⃣ 支持您按照以下筛选项订阅：
   • 性别：全部 / 男 / 女
   • 行业分类：全部行业、商业创业、汽车出行、设计创意、航空领域、电商零售、教育培训、工程运营、娱乐文化、环境能源、家庭育儿、时尚美妆、金融投资、美食饮品、游戏电竞、健康医疗、牧场马术、宗教信仰、科学学术、体育健身、科技软件、旅行户外、视觉艺术、健康生活、居家手工、人力职场、公益平权、法律法务、市场营销、音乐领域、萌宠动物、政治新闻
```

---

## 5. 使用场景

| 用户分层 | 核心痛点 | 使用方式 |
| -------- | -------- | -------- |
| 出海内容创作者 | 不知道同赛道头部账号是谁、无从对标 | 查询 "科技类 Twitter 榜单"，获取对标参考 |
| 品牌方 / 海外投放 | 找海外达人效率低、不了解账号跨平台影响力 | 查询 "美妆类女博主榜单"，评估投放候选 |
| MCN / 跨境运营团队 | 竞品账号情报获取难 | 查询 "宠物榜第2页"，逐页监控市场 |
| 行业分析师 | 数据维度单一、缺乏可视化报告 | 生成 "金融投资行业榜单 HTML 报告" |

**预期收益**：快速掌握 X 平台头部账号格局、识别高增长账号、降低海外投放决策成本。

---

## 6. 项目架构

### 目录结构

```
x-top-account/
├── SKILL.md                          # 本文件
├── scripts/
│   ├── fetch_rank.py                 # 查询榜单数据（解析/翻页/容错回退）
│   └── generate_report.py            # 生成 X 风格 HTML 报告（导出 PDF/图片）
├── assets/
│   └── category_config.json          # 更新规则 + 性别/行业枚举与关键词映射
├── output/                           # HTML 报告输出目录（运行时自动创建）
└── references/
    ├── category_map.md               # 行业映射表与匹配规则
    └── api_docs.md                   # API 接口详细文档（技术参考）
```

### 核心模块说明

- **fetch_rank.py**：接收用户查询参数，调用红狐 API 获取榜单数据，自动解析日期、性别、行业与页码，目标日期无数据时自动回退最近可用日期，输出 JSON 数据文件；加 `--html` 自动调用报告生成。
- **generate_report.py**：读取 JSON 数据生成 X 平台风格（纯白底 + X 蓝）HTML 报告，报告标题格式 `X(Twitter)·{行业}·热门{性别}账号榜`（行业/性别为 all 时省略对应字段），默认保存到 skill 目录下 `output/`（自动创建），文件名格式 `X账号榜_{性别}_{分类}_{日期}.html`（性别/分类为 all 时展示为全部性别/全部分类，如 `X账号榜_全部性别_全部分类_2026-09-21.html`）。列版式与对话表格一致：账号名列展示头像 + 账号名（可点击跳转 X 主页）+ 头衔（账号名下方，超长省略号、悬停显示全文），账号简介列仅 biography（悬停显示全文），其他平台粉丝数带平台名且可点击跳转对应主页；内置导出 PDF / 高清图片按钮，生成后自动打开浏览器。

### 资源索引

| 文件 | 用途 |
| ---- | ---- |
| [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/api_docs.md](references/api_docs.md) | API 接口详细文档（技术参考） |

---

## 7. 常见问答

### 安装

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

**Q: 如何配置 API Key？**
A: 请前往 [红狐hub](https://redfox.hk/settings/api-keys?source=github) 获取 API KEY，然后通过环境变量 `REDFOX_API_KEY` 配置。

### 使用

**Q: 榜单数据什么时候更新？**
A: 每日早上 9:00 更新前一天榜单。当前时间未到 9:00 时，脚本会自动取前天数据。

**Q: 支持哪些筛选？**
A: 性别 3 项（全部/男/女）+ 行业 32 类，完整列表见 [references/category_map.md](references/category_map.md)。

**Q: 数据回溯范围？**
A: 最多回溯过去 7 天；目标日期无数据时自动回退最近可用日期并提示。

**Q: 行业识别失败怎么办？**
A: 无法识别时降级为全部行业，并列出完整行业列表供用户选择。

**Q: 每页多少条？如何翻页？**
A: 每页固定 20 条，共 10 页 200 条；对话中询问用户是否查看下一页，使用 `--page N` 翻页。

### 故障排除

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

**Q: 数据不一致？**
A: 对话展示多少条（每页 20 条），HTML 报告就展示多少条，两者必须一致。翻页后需重新生成对应页报告。