# 抖音数据规则

> 本文件定义所有 douyin-* 技能获取数据时必须遵守的规则。
> 最后更新：2026-08-08

---

## 1. 赛道过滤规则

所有抖音榜单/数据获取时，按以下配置过滤赛道。

**保留赛道**（共 5 个）：

| # | 赛道 | | # | 赛道 |
|---|------|-|---|------|
| 1 | 生活 vlog | | 4 | 美食 |
| 2 | 小剧场 | | 5 | 旅行 |
| 3 | 亲子 | | | |

**排除赛道**（共 21 个）：

| # | 赛道 | | # | 赛道 |
|---|------|-|---|------|
| 1 | 动物 | | 12 | 汽车 |
| 2 | 明星娱乐 | | 13 | 个人才艺 |
| 3 | 音乐 | | 14 | 财富理财 |
| 4 | 游戏 | | 15 | 学习教育 |
| 5 | 人文 | | 16 | 潮流风尚 |
| 6 | 体育 | | 17 | 身体锻炼 |
| 7 | 影视 | | 18 | 居家装修 |
| 8 | 舞蹈才艺 | | 19 | 化妆美容 |
| 9 | 数码科技 | | 20 | 二次元 |
| 10 | 三农 | | 21 | 颜值造型 |
| 11 | 健康医学 | | 22 | 情感 |

> 保留赛道 JSON：`["生活 vlog", "小剧场", "亲子", "美食", "旅行"]`
>
> 排除赛道 JSON：`["动物", "明星娱乐", "音乐", "游戏", "人文", "体育", "影视", "舞蹈才艺", "数码科技", "三农", "健康医学", "汽车", "个人才艺", "财富理财", "学习教育", "潮流风尚", "身体锻炼", "居家装修", "化妆美容", "二次元", "颜值造型", "情感"]`
>
> 获取数据后，在输出表格中剔除赛道属于排除列表的作品，并重新排列名次。
> 赛道为空或 `-`（未分类）的作品保留。
>
> 赛道名体系更新于 2026-08-19（对齐红狐 API 27 赛道标准名；08-19 二次调整：剔除个人才艺/财富理财/学习教育/潮流风尚/身体锻炼/居家装修，保留 9 个；09-01 三次调整：剔除化妆美容，保留 8 个；09-01 四次调整：剔除二次元，保留 7 个；09-03 五次调整：剔除颜值造型，保留 6 个；09-03 六次调整：剔除情感，保留 5 个）。

---

## 2. 数据归档规则

### 2.1 目录结构

数据按类型分三个文件夹存放；**榜单数据**因属「同日期固定快照」+ API 按调用计费，**采用业务数据目录落盘 + 查询先查本地缓存命中免 API**（09-03 定稿规范）：

| 数据类型 | 归档目录（①③用户/开发机） | 归档目录（②dsh 环境） | 说明 |
|---|---|---|---|
| **榜单数据**（账号周榜/视频热榜/点赞榜/涨粉榜/日榜/月榜/七日飙升等） | `C:\Users\maidou\Desktop\MCNSkill项目\三方数据\红狐数据\抖音榜单\` | `D:\dshworkspace\抖音榜单\` | 桌面顶层先分「业务账号/三方数据」：三方数据统一 `三方数据\{数据源}\`（当前=红狐数据）；文件命名 `{榜名}_{赛道}_{数据日期}.json` 不加数据源前缀；详见 [SKILL.md 榜单数据落盘规范](../../SKILL.md) |
| **信息源数据**（AI信息源、短剧信息源等） | `RedFox数据\信息源数据\YYYY-MM\` | 同（沙箱内） | 按月分文件夹 |
| **作品数据**（单作品爬取、账号诊断等） | `RedFox数据\作品数据\YYYY-MM-DD\` | 同 | 按日分文件夹 |

### 2.2 日期命名规则

> 以下示例归档目录 = 表 2.1 对应环境的目录内（①③ = `三方数据\红狐数据\抖音榜单\`；② dsh = `D:\dshworkspace\抖音榜单\`）。

- 归档文件夹日期按 **数据实际日期** 命名，**不是获取日期**。
- 例：8月8日获取8月7日的日榜 → 存入 `抖音榜单\抖音视频热榜_美食_2026-08-07.json`
- 例：8月8日获取8天前的七日飙升榜 → 存入 `抖音榜单\抖音七日飙升榜_美食_2026-08-01.json`
- 例：8月8日获取账号周榜（period=week, 08-01 至 08-07）→ 存入 `抖音榜单\抖音周榜_亲子_2026-08-07.json`（采用周结束日期命名；与 dsh 工作台 RANKING_DIR 既有读取兼容）
- 例：8月8日获取AI信息源（数据日期8月7日）→ 存入 `RedFox数据\信息源数据\2026-08\抖音AI信息源_2026-08-07.json`
- 例：8月8日爬取某作品详情（作品发布于8月5日）→ 存入 `RedFox数据\作品数据\2026-08-05\作品详情_xxx.json`

### 2.3 格式

- 统一以 **JSON 格式**（`.json`）归档，保留 API 返回的完整结构化字段，便于后续入库与查询。
- 输出展示时可在对话中以表格形式呈现，但落盘文件必须为 `.json`。

### 2.4 榜单查询幂等铁律（防重复花 API 钱，09-03 定稿）

> 详见主 SKILL.md 「榜单数据落盘规范（白名单例外详则）」。本节为执行摘要：

1. **查询前先 `ls`** 本地 `抖音榜单/` 对应文件 → 命中直接读本地（**0 API 成本**）；未命中才调 API 并立即落盘
2. 缓存命中需在回复中注明「缓存命中·本地读取」
3. **同榜名+赛道+数据日期**全机器只允许一次 API 调用
4. 缓存文件不入技能包 git（新增 `.gitignore` 忽略缓存产物）

> **最后更新**：2026-09-03（榜单数据落盘规范定稿：业务数据目录+查询先查本地缓存命中免 API）

---

## 3. API Key 安全规则

- 红狐Hub API Key 仅通过环境变量 `REDFOX_API_KEY` 读取（`os.getenv("REDFOX_API_KEY")`）。
- **禁止**硬编码到代码中。
- **禁止**从系统文件读取。
- **未配置 Key 时**：脚本报错退出，提示「获取地址 + 运行 `python scripts/setup_redfox_key.py` 交互式输入」；引导用户输入**自己的** Key，不要代填、不要硬编码。
- 一键配置（推荐）：`python scripts/setup_redfox_key.py`（交互式输入，自动写入用户级环境变量）；`--check` 检查配置状态。
- 临时设置（仅当前终端有效）：`REDFOX_API_KEY=xxx python script.py`

### 3.1 部署到新电脑：让用户输入自己的 key

技能分发/部署到其他用户电脑时，**必须由用户配置自己的 key**（每个账号的 key 不同，禁止共用/预置）：

1. **运行配置引导脚本**（推荐，自动写入用户级环境变量）：

   ```bash
   python scripts/setup_redfox_key.py   # 交互式输入自己的 key
   python scripts/setup_redfox_key.py --key ak_xxx   # 部署脚本/CI 直传
   python scripts/setup_redfox_key.py --check        # 检查是否已配置
   ```

   - Windows：自动写入用户级环境变量（HKCU\Environment）并广播刷新，新开终端即可生效
   - macOS/Linux：打印 `export REDFOX_API_KEY=...` 指引，由用户追加到 `~/.zshrc` 或 `~/.bashrc`

2. **手动配置**（等价做法）：Windows 用 `[Environment]::SetEnvironmentVariable("REDFOX_API_KEY","<自己的key>","User")`；macOS/Linux 把 export 追加到 shell 配置文件。

3. **申请 key**：https://redfox.hk/settings/api-keys

> 脚本不包含任何真实 key，可随仓库分发；key 仅写入当前系统用户环境，不落入技能目录/仓库文件。

---

## 4. 技能存放路径

- 11 个子技能统一存放在 `subskills/` 目录下（随 mcn-data-insight 技能包分发）。
- 技能包根目录结构：`SKILL.md`（技能索引）+ `references/`（统一规则）+ `scripts/`（共享工具）+ `subskills/`（子技能）。
- 共享工具以技能包根目录为工作目录执行，例如 `python scripts/setup_redfox_key.py`。
- 运行数据统一输出到 `RedFox数据/`（相对技能包根目录，不存在则创建）。
- 技能包不含 `.workbuddy/`（原项目历史工作日志已随 2026-09-03 并入时清理，不随包分发）。