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 验证该关键词可正常拉取（静默执行）：

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

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

入口二：账号订阅

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

# 验证并首次展示（静默执行）
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：

# 验证并首次展示（静默执行）
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 注册获取）

安装步骤

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 注册账号并获取 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。

{
  "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/generate_report.py	生成 HTML 可视化日报
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 天回溯需额外消耗积分，故默认不回溯。