抖音数据规则

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

1. 赛道过滤规则

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

保留赛道（共 7 个）：

#	赛道	#	赛道
1	生活 vlog	5	情感
2	小剧场	6	颜值造型
3	亲子	7	旅行
4	美食

排除赛道（共 20 个）：

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

保留赛道 JSON：["生活 vlog", "小剧场", "亲子", "美食", "情感", "颜值造型", "旅行"]

排除赛道 JSON：["动物", "明星娱乐", "音乐", "游戏", "人文", "体育", "影视", "舞蹈才艺", "数码科技", "三农", "健康医学", "汽车", "个人才艺", "财富理财", "学习教育", "潮流风尚", "身体锻炼", "居家装修", "化妆美容", "二次元"]

获取数据后，在输出表格中剔除赛道属于排除列表的作品，并重新排列名次。赛道为空或 -（未分类）的作品保留。

赛道名体系更新于 2026-08-19（对齐红狐 API 27 赛道标准名；08-19 二次调整：剔除个人才艺/财富理财/学习教育/潮流风尚/身体锻炼/居家装修，保留 9 个；09-01 第三次调整：剔除化妆美容，保留 8 个；09-01 第四次调整：剔除二次元，保留 7 个）。

2. 数据归档规则

2.1 目录结构

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

数据类型	归档目录（①③用户/开发机）	归档目录（②dsh 环境）	说明
榜单数据（账号周榜/视频热榜/点赞榜/涨粉榜/日榜/月榜/七日飙升等）	`C:\Users\maidou\Desktop\MCNSkill项目\三方数据\红狐数据\抖音榜单\`	`D:\dshworkspace\抖音榜单\`	桌面顶层先分「业务账号/三方数据」：三方数据统一 `三方数据\{数据源}\`（当前=红狐数据）；文件命名 `{榜名}_{赛道}_{数据日期}.json` 不加数据源前缀；详见 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 「榜单数据落盘规范（白名单例外详则）」。本节为执行摘要：

查询前先 ls 本地 抖音榜单/ 对应文件 → 命中直接读本地（0 API 成本）；未命中才调 API 并立即落盘
缓存命中需在回复中注明「缓存命中·本地读取」
同榜名+赛道+数据日期全机器只允许一次 API 调用
缓存文件不入技能包 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 不同，禁止共用/预置）：

运行配置引导脚本（推荐，自动写入用户级环境变量）：
```
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
手动配置（等价做法）：Windows 用 [Environment]::SetEnvironmentVariable("REDFOX_API_KEY","<自己的key>","User")；macOS/Linux 把 export 追加到 shell 配置文件。
申请 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 并入时清理，不随包分发）。

7.1 KiB Raw Blame History Unescape Escape