tiktok-subscribe v1.0.0A

Immutable. This exact content never changes and is served at /api/v1/blob/52cad315daecef4b.

---
name: tiktok-subscribe
description: TikTok 监控订阅推送工具 — 订阅关键词、指定账号与话题，每日早上 9:00 自动拉取昨日时间窗内新内容（关键词新爆款视频 / 账号新作品 / 话题新作品），按订阅项分组生成 HTML 日报推送，无需手动操作。支持三类订阅项批量管理（总上限 100 项）、按日期过滤翻页、互动数据（播放/点赞/评论/分享）展示与 AI 总结。当用户需要订阅 TikTok 关键词、追踪指定账号新作品、监控话题热度变化、获取 TikTok 昨日内容日报时使用。触发词：TikTok订阅、TikTok监控、TikTok日报、TikTok关键词订阅、TikTok账号订阅、TikTok话题订阅、TikTok订阅推送、监控订阅推送。
version: 1.0.0
---

# TikTok 监控订阅推送

## 1. 简介

订阅 TikTok 关键词、指定账号与话题，**每日早上 9:00 自动拉取「昨日 9:00 ~ 今日 9:00」这一近 24 小时时间窗内的新内容**，按订阅项分组生成 HTML 日报推送，无需手动逐个刷动态。三类订阅项：

| 订阅项 | 追踪内容 | 数据来源 |
|--------|---------|---------|
| 关键词订阅 | 关键词新增爆款视频（按点赞热度拉取最近一天） | 关键词视频搜索 |
| 账号订阅 | 指定账号的新作品与互动数据 | 用户主页作品 |
| 话题订阅 | 指定话题的新作品与热度变化 | 话题作品列表 |

**适用对象**：出海品牌 / 投放人员（盯关键词热度与竞品动作）、MCN / 商务经纪（批量盯多个达人账号与话题）、内容创作者 / 研究者（追踪选题热度与爆款规律）。

---

## 2. 功能特性

| 功能模块 | 能力描述 |
|---------|---------|
| 三入口订阅 | 关键词 / 账号（secUserId）/ 话题（话题 ID）三类订阅项，一次命令可混合订阅 |
| 每日自动推送 | 自动化任务内置全部订阅项，每天 9:00 自动拉取昨日新内容 |
| 时间窗口过滤 | 按「昨日 9:00 ~ 今日 9:00」时间窗口过滤并智能翻页（关键词 / 话题支持翻页） |
| HTML 日报 | TikTok 平台风格（黑底 logo + TikTok 红/青配色），按订阅项分组展示作品表格，支持导出 PDF / 高清图片 |
| 互动数据 | 播放 / 点赞 / 评论 / 分享 / 发布时间，全部订阅项按播放数降序展示 |
| AI 语义总结 | AI 读作品内容，归纳「今日主题」（分析作品在说什么，按实际条数）+ 每个订阅项的「主题/观点」 |
| 无更新折叠 | 昨日无更新 / 近 7 天无更新订阅项自动折叠提示 |

---

## 3. 订阅方式（三个入口）

> **静默执行原则**：所有中间步骤（fetch 验证、automation_update）均不得向用户输出过程性提示，仅展示最终结果。

用户表达订阅意向但方式不明确时，先输出引导：

```
📬 订阅 TikTok 内容日报，三类订阅任选：
1️⃣ 关键词订阅 — 说「订阅关键词 nvidia 每日新视频」
2️⃣ 账号订阅 — 提供账号 secUserId 或 TikTok App 分享链接，如「订阅这个账号」
3️⃣ 话题订阅 — 提供话题 ID（ch_id），说「订阅话题 2525872 每日新作品」
已订阅后每天 9:00 自动推送昨日新内容日报，最多可订阅 100 个订阅项（三类合计）。
```

### 入口一：关键词订阅

用户说「订阅关键词 xxx」→ Agent 验证该关键词可正常拉取（静默执行）：

```bash
python3 scripts/subscribe.py fetch --keywords "nvidia" --first --html
```

验证通过后追加到自动化任务的 `--keywords` 参数（见「账号管理规则」）。

### 入口二：账号订阅

用户提供 secUserId 或分享链接 → Agent 提取 secUserId → 验证 → 追加到 `--accounts`：

```bash
# 验证并首次展示（静默执行）
python3 scripts/subscribe.py fetch --accounts "MS4wLjAB..." --first --html
```

**secUserId 获取方式**（MS4w 开头的完整长串）：

1. 手机 TikTok App 进入目标账号主页 → 点右上角「分享」→「复制链接」，分享链接中带有 `sec_uid=MS4w...` 参数，把完整分享链接提供给本技能即可
2. 或按 F12 打开浏览器开发者工具 → Console 粘贴执行：`JSON.parse(document.getElementById('__UNIVERSAL_DATA_FOR_REHYDRATION__').textContent).__DEFAULT_SCOPE__['webapp.user-detail'].userInfo.user.secUid`

### 入口三：话题订阅

用户提供话题 ID（ch_id，纯数字）→ 验证 → 追加到 `--topics`：

```bash
# 验证并首次展示（静默执行）
python3 scripts/subscribe.py fetch --topics "2525872" --first --html
```

**话题 ID 获取方式**：用户只给话题名 / 话题链接时，先用「TikTok热门搜索」技能搜索话题获取话题 ID（`topicId` 字段），或从 TikTok 话题链接中的 `ch_id` 参数提取，再交给本技能订阅。

---

## 4. 数据规则

### 时间窗口

- **每日更新模式**（自动化任务默认）：拉取「昨日 9:00 ~ 今日 9:00」这一近 24 小时窗口（本地时区）内的作品
- **首次订阅模式**（`--first`）：直接拉取第一页最新内容，不按时间窗口过滤
- 接口不支持按时间排序，Skill 内部逐条比对发布时间过滤；关键词 / 话题支持翻页（`--max-pages` 可调，默认 3 页）

### 订阅项状态判定

| 状态 | 判定条件 | 报告处理 |
|------|---------|---------|
| `updated` | 命中时间窗内作品 | 正常展示作品表格 |
| `no_update_yesterday` | 无昨日作品（关键词订阅项不做 7 天回溯，避免额外积分消耗） | 折叠提示「昨日无更新」 |
| `no_update_7d` | 账号 / 话题最新作品早于 7 天前 / 无作品 | 折叠提示「近 7 天无更新」 |
| `error` | 接口请求失败 | 折叠提示失败原因 |

---

## 5. 一键安装

### 前置条件

- Python 3.8+（仅使用标准库，无需安装额外依赖）
- 红狐数据 API Key（前往 [红狐 hub](https://redfox.hk/settings/api-keys?source=github) 注册获取）

### 安装步骤

1. 将技能文件夹放入你的 Skills 目录
2. 配置环境变量 `REDFOX_API_KEY`（配置细节详见 `references/core_workflow.md` Step 0）
3. 无需安装额外依赖，直接使用

---

## 6. 工作流程

> 核心执行流程（订阅项解析、脚本调用、时间窗过滤、表格渲染规则、AI 总结、空结果与错误处理等）详见 `references/core_workflow.md`，Agent 执行时必须遵循该文件中的所有规则。

---

## 7. 使用指南

### 🔑 鉴权

首次使用需配置环境变量 `REDFOX_API_KEY`：前往 [红狐 hub](https://redfox.hk/settings/api-keys?source=github) 注册账号并获取 API Key，终端与 OpenClaw 的配置方式详见 `references/core_workflow.md` Step 0。

### 命令速查

| 用户意图 | 命令 |
|---------|------|
| 拉取订阅项昨日新内容（每日更新） | `fetch --keywords "k1,k2" --accounts "s1,s2" --topics "t1,t2" --html` |
| 首次订阅验证 / 查看最新动态 | `fetch --keywords "k1" --first --html` |
| 指定历史日期 | `fetch --keywords "k1" --date 2026-10-12 --html` |
| 单类订阅项 | `fetch --accounts "MS4wLjAB..." --markdown` |

### fetch 参数

| 参数 | 说明 |
|------|------|
| `--keywords` | 订阅关键词列表，逗号分隔 |
| `--accounts` | 订阅账号列表，逗号分隔（secUserId 或带 `sec_uid=` 参数的分享链接） |
| `--topics` | 订阅话题 ID 列表，逗号分隔（ch_id 数字） |
| `--date` | 时间窗结束日 `YYYY-MM-DD`（默认：今日 9:00 边界往前 24 小时） |
| `--first` | 首次订阅模式：拉第一页最新内容，不按时间窗过滤 |
| `--count` | 每订阅项条数（1~50，默认 20） |
| `--max-pages` | 每日更新模式关键词 / 话题每项最多翻页数（1~10，默认 3） |
| `--region` | 关键词视频搜索地区（默认 US） |
| `--markdown` | 输出 Markdown 格式表格（供 Agent 转述） |
| `--html` | 生成 HTML 日报（自动打开浏览器） |
| `--save-json` | 结果落盘为 JSON（供 HTML 日报使用） |

> 全局参数 `--api-key` 需置于子命令之后（如 `subscribe.py fetch --api-key ak_xxx ...`），默认读环境变量 `REDFOX_API_KEY`。

---

## 8. 账号管理规则（Agent 必须遵守）

> **核心原则：所有订阅状态 = 自动化命令中的 `--keywords` / `--accounts` / `--topics` 参数。无本地文件存储。**

### 上限

- **单个自动化任务最多 50 个订阅项**（三类合计）
- **总订阅上限 100 个订阅项**（三类合计）

### 订阅新订阅项流程

1. **查询现有自动化任务**：使用 `automation_update mode=list` 获取所有「TikTok订阅」相关任务，读取每个任务 `--keywords` / `--accounts` / `--topics` 中的订阅列表
2. **判断追加 / 新建**：

   | 条件 | 操作 |
   |------|------|
   | 现有订阅项 + 新订阅项 ≤ 50 | 追加到现有任务的对应参数（去重后拼接） |
   | 现有订阅项 + 新订阅项 ＞ 50 且总数 ≤ 100 | 新建自动化任务，溢出部分放入新任务 |
   | 总数将 ＞ 100 | 告知用户已达上限，请取消部分订阅项后再订阅 |
   | 用户要求取消某订阅项 | 从对应任务参数中移除该项 |

3. **更新/创建自动化任务**：
   - 追加：`automation_update mode=update` 修改现有任务 `prompt` 中的订阅参数
   - 新建：`automation_update mode=create`，每日 9:00 执行（`FREQ=DAILY;BYHOUR=9;BYMINUTE=0`），名称加序号如「TikTok订阅监控日报 #2」
   - automation prompt 示例：`拉取TikTok订阅监控昨日新内容并生成HTML日报推送给用户：python3 scripts/subscribe.py fetch --keywords "nvidia" --accounts "MS4wLjAB..." --topics "2525872" --html`
4. **立即拉取一次**：无论追加还是新建，都必须立即执行一次 `fetch --first --html` 展示最新结果

### 取消订阅

从对应任务的参数中移除该项即可。若移除后某任务剩余 0 个订阅项，则删除该自动化任务。

---

## 9. 输出格式

### 订阅结果总览（订阅/拉取时必须输出）

```
📊 订阅结果
| 项目 | 值 |
|------|-----|
| 本次订阅 | 关键词 2 个、账号 1 个、话题 1 个（1 个已订阅跳过） |
| 当前总订阅 | 5 / 100 项 |
| 自动化任务 | 已更新 ✅ 每日 9:00 自动执行 |
| 首次拉取 | 以下展示各订阅项最新动态 |
```

### 每订阅项作品详情表（Markdown）

```
### ▸ 关键词「nvidia」 昨日新内容（5 条）

| # | 作者 | 作品摘要 | 播放 | 点赞 | 评论 | 分享 | 发布时间 |
|---:|---|---|---:|---:|---:|---:|---|
| 1 | Raina / `rainaships` | [party ended immediately #Tech...](作品链接) | 85,207 | 18,254 | 315 | 1,251 | 10-12 11:50 |
```

要求：

- 每个订阅项一个子标题 + 一个完整 Markdown 表格；账号订阅项表格无「作者」列
- 作品摘要使用 `content` 原文（过长截取前 60 字），渲染为可点击超链接 `[摘要](作品链接)`
- 数值使用可读格式（千分位，如 85,207）
- 发布时间截取到 `MM-DD HH:mm`（本地时区）
- 所有订阅项按播放数降序排列
- 昨日无更新 / 近 7 天无更新订阅项折叠提示，如：「以下 2 个订阅项昨日无更新，已折叠」

### 总结统计（必须附加在所有表格之后）

由 **AI 读取作品内容**生成语义总结，不接 LLM 端点、不做词频统计。写入与数据文件同目录的 `tiktok_subscribe_ai_summary.json`，`generate_report.py` 渲染时自动合并到 HTML。

```json
{
  "overall": [
    {"title": "主题/事件名", "summary": "这段在讲什么（1-2 句）", "items": ["nvidia"], "workCount": 8}
  ],
  "items": [
    {"key": "nvidia", "kind": "keyword", "theme": "该订阅项今日主要聊了什么主题", "viewpoint": "该订阅项内容表达的观点/立场"}
  ]
}
```

要求：

- `overall` 是「今日主题总结」：分析作品到底在说什么（事件/主题），**不是简单高频词**；有几条归纳几条，不强制凑数，禁止虚构
- `items` 是单订阅项总结：每个有更新订阅项一条，说明「主要主题」和「观点/立场」
- 主题数按实际内容归纳，没有就少写，不硬凑

### 输出完整性清单

每次订阅/拉取，对话中必须包含：

- [ ] 订阅结果总览表
- [ ] 每个有更新订阅项的 Markdown 作品详情表
- [ ] 无更新订阅项折叠提示（如有）
- [ ] 总结统计分析（AI 语义总结：今日主题 + 单订阅项主题/观点）
- [ ] **仅当有作品数据时**：HTML 日报已生成说明（附文件路径）+ 自动打开预览

---

## 10. 注意事项

1. **数据真实性**：所有数值均来自数据服务返回，如实展示，严禁估算或编造
2. **输入准确**：账号订阅需要 secUserId（MS4w 开头）或带 `sec_uid=` 参数的分享链接；话题订阅需要话题 ID（ch_id 数字）；输入无效时如实提示并附获取方式，不猜测替换
3. **积分保护**：每次成功查询可能消耗积分；关键词 / 话题每翻一页各消耗 1 次调用；账号订阅项一次返回近期全部作品、无额外翻页；HTML 日报与 AI 总结为本地离线生成，不消耗积分；未经用户明确指定，不主动翻页或批量查询
4. **鉴权**：首次使用需配置环境变量 `REDFOX_API_KEY`，API Key 获取与配置详见 `references/core_workflow.md`
5. **链接完整性**：输出中的链接保持完整可点击，不使用被终端截断的 URL
6. **分析为推测**：AI 总结基于公开数据撰写，须明确标注为推测，不虚构

---

## 11. 项目架构

```
tiktok-subscribe/
├── SKILL.md                          # 本文件
├── scripts/
│   ├── subscribe.py                  # 统一入口：fetch 子命令（关键词 / 账号 / 话题三类订阅项）
│   └── generate_report.py            # 生成 TikTok 风格 HTML 日报（导出 PDF/图片）
├── output/                           # JSON 数据与 HTML 日报输出目录（运行时自动创建）
└── references/
    └── core_workflow.md              # 3 个接口详细文档与完整执行规则（技术参考）
```

### 核心模块说明

- **subscribe.py**：
  - `fetch` — 拉取订阅项作品，支持首次模式（拉第一页）与每日模式（按昨日时间窗过滤 + 翻页），三类订阅项混合传入一次拉取，输出 JSON + Markdown，`--html` 时调用报告生成
- **generate_report.py**：读取 fetch 输出的 JSON 与本地 AI 总结 JSON 生成 TikTok 平台风格 HTML 日报，按订阅项分组展示作品表格（含作者、互动数据、作品链接），无更新订阅项折叠，内置一键下载 PDF / 高清图片按钮（html2canvas 导出图片、浏览器打印导出 PDF），生成后自动打开浏览器。文件名格式 `TikTok订阅日报_{日期}.html`（首次模式为 `TikTok订阅首次拉取_{日期}.html`）

### 资源索引

| 文件 | 用途 |
| ---- | ---- |
| [scripts/subscribe.py](scripts/subscribe.py) | 拉取订阅项作品 / 时间窗过滤 / 翻页 |
| [scripts/generate_report.py](scripts/generate_report.py) | 生成 HTML 可视化日报 |
| [references/core_workflow.md](references/core_workflow.md) | 3 个接口详细文档（技术参考） |

---

## 12. 常见问答

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

**Q: 最多订阅多少个订阅项？**
A: 总上限 100 个（关键词 + 账号 + 话题合计）；单个自动化任务最多 50 个，超出自动新建任务。

**Q: 每日报告什么时候推送？拉取哪段时间的数据？**
A: 每天早上 9:00 自动执行，拉取「昨日 9:00 ~ 今日 9:00」这一近 24 小时窗口内（本地时区）发布的作品。

**Q: 接口不支持按时间排序，怎么保证只拉时间窗内的作品？**
A: Skill 内部翻页并逐条比对发布时间：命中窗口且本页无早于窗口起点的作品则继续翻页，出现更早作品即停止，只保留窗口内作品（详见第 4 节）。

**Q: 作品时间是什么时区？**
A: 接口返回秒级时间戳，Skill 统一转换为**本地时区**展示与过滤。

**Q: 某订阅项昨日没有新内容怎么办？**
A: 报告中折叠提示「昨日无更新」；账号 / 话题类若近 7 天都无更新则提示「近 7 天无更新」。

**Q: 如何取消订阅？**
A: 告诉 Agent 要取消的订阅项，Agent 从对应自动化任务的参数中移除该项。

**Q: 关键词订阅为什么不做 7 天回溯？**
A: 关键词视频搜索按「最近一天」直接拉取，若昨日无新增即可判定无更新；做 7 天回溯需额外消耗积分，故默认不回溯。