抖音账号订阅追踪

📝 简介

通过抖音号订阅竞对、同类和关注账号（最多 20 个），自动抓取最新作品。账号 ID 直接传入命令行参数，不依赖任何本地文件存储，自动化任务中硬编码所有已订阅的抖音号。

---

✨ 功能特性

功能模块	能力描述	核心价值
账号直传	通过 --accounts 参数直接传入抖音号，无需文件存储	简单透明，命令即文档
每日自动推送	自动化任务内置账号 ID，每天早上 9:00 自动执行	定时获取，无需手动操作
HTML 报告	fetch 时自动生成精美 HTML 报告文件，支持预览和分享	可视化浏览，一目了然
作品数据	收藏数、评论数、分享数、点赞数、发布时间	全维度数据，一目了然
按账号展示	终端表格按账号依次分组展示	清晰直观，便于对比
日期回溯	支持指定历史日期查询	追溯往期作品数据

---

🔑 鉴权

获取 API Key

请前往 红狐hub 获取API KEY

配置 API Key

方案1: 以OpenClaw为例，将REDFOX_API_KEY添加到~/.openclaw/openclaw.json中：

{ "env": { "REDFOX_API_KEY": "ak_xxxx..." } }

方案2: 终端配置

export REDFOX_API_KEY="ak_xxxx..."

---

⚙️ 使用方式

拉取作品（核心命令）

# 基础用法：直接传入抖音号列表
python3 "$SKILL_PATH/scripts/subscribe.py" fetch --accounts "YuZhouXiaoLi1220,Fish688688"

# 生成 HTML 报告（自动保存到 report/ 目录）
python3 "$SKILL_PATH/scripts/subscribe.py" fetch --accounts "YuZhouXiaoLi1220,Fish688688" --html

# 指定 HTML 报告输出路径
python3 "$SKILL_PATH/scripts/subscribe.py" fetch --accounts "YuZhouXiaoLi1220,Fish688688" --html --html-path ~/Desktop/report.html

# Markdown 格式输出（供 Agent 展示）
python3 "$SKILL_PATH/scripts/subscribe.py" fetch --accounts "YuZhouXiaoLi1220,Fish688688" --markdown

# 指定单日日期
python3 "$SKILL_PATH/scripts/subscribe.py" fetch --accounts "YuZhouXiaoLi1220,Fish688688" --html --date 2026-06-01

# 指定日期范围
python3 "$SKILL_PATH/scripts/subscribe.py" fetch --accounts "YuZhouXiaoLi1220,Fish688688" --html --date-start 2026-06-01 --date-end 2026-06-05

参数说明

命令	参数	说明
fetch	--accounts	抖音号列表（必填或核心参数），逗号分隔，如 "id1,id2,id3"
	--date	指定单日日期 YYYY-MM-DD
	--date-start	指定日期范围开始 YYYY-MM-DD
	--date-end	指定日期范围结束 YYYY-MM-DD
	--markdown	输出 Markdown 格式表格
	--html	生成 HTML 报告文件（保存到 report/ 目录）
	--html-path	自定义 HTML 报告输出路径
全局	--api-key	指定 API Key

依赖

依赖	安装命令
requests	pip3 install requests

---

🤖 每日自动推送

用户订阅账号后，Agent 会创建一个每日定时任务，每天早上 9:00 自动执行。任务命令中直接包含所有已订阅的抖音号 ID：

# 自动化任务中的实际命令（账号已内置）
python3 subscribe.py fetch --accounts "YuZhouXiaoLi1220,Fish688688" --html

工作原理

1. 用户发送抖音号 → Agent 将其写入自动化命令的 --accounts 参数
2. 每天 9:00 定时触发 → 命令自带账号 ID → 直接调 API 拉数据
3. 自动生成 HTML 报告 → 保存至 report/ 目录
4. 不依赖任何本地 JSON 文件

---

🔧 账号管理规则（Agent 必须遵守）

核心原则：所有订阅状态 = 自动化命令中的 --accounts 参数。无文件存储。

订阅新账号流程

当用户提供新的抖音号时，Agent 必须按以下步骤操作：

Step 1：查询现有自动化任务

使用 automation_update mode=list 获取所有「抖音订阅」相关的自动化任务，读取每个任务的 --accounts 参数中的账号列表。

Step 2：判断是否追加 / 新建

条件	操作
现有账号数 + 新账号数 ≤ 20	追加到现有自动化任务的 --accounts 参数（去重后用逗号拼接）
现有账号数 + 新账号数 ＞ 20	创建新的自动化任务，将超出部分放入新任务的 --accounts
用户明确要求取消某账号	从对应自动化任务的 --accounts 中移除该 ID

Step 3：更新/创建自动化任务

• 追加场景：调用 automation_update mode=update，修改现有任务的 prompt 字段中的 --accounts 值
• 新建场景：调用 automation_update mode=create，新建一个独立的每日定时任务（同样 9:00 执行），名称可加序号如「抖音订阅作品日报 #2」

Step 4：立即拉取一次

无论追加还是新建，都必须立即执行一次 fetch（带 --html）展示最新结果给用户。

多任务示例

假设已有 18 个账号，用户又提供了 5 个新账号：

现有任务 #1: --accounts "id1,id2,...,id18" (18个)
新增 5 个: id19,id20,id21,id22,id23

→ 任务 #1 更新为: --accounts "id1,...,id18,id19,id20" (20个 ✅)
→ 新建任务 #2: --accounts "id21,id22,id23" (3个 ✅)

每个独立任务都会在每天 9:00 各自执行，各自生成 HTML 报告。

取消订阅

从对应任务的 --accounts 中移除该 ID 即可。如果移除后某个任务剩余 0 个账号，则删除该自动化任务。

---

📋 交互规范

订阅流程

静默执行原则：所有中间步骤（fetch 验证、add 订阅、automation_update）均不得向用户输出任何过程性提示（如「正在验证账号」「账号验证通过」「自动订阅中」等）。仅向用户展示最终结果。

1. 用户发送抖音号 → Agent 静默执行 fetch --accounts "抖音号" --html --markdown 验证账号
2. 判断账号状态（规则 1）：
   • 接口返回正常数据：
     • 静默执行 add 订阅（见下一步）
   • 近 30 天无数据，自动回溯半年后仍无数据：
     • 告知用户：「抱歉您订阅的“xxx”账号近半年都未发布过作品，如果需要数据核查可联系工作人员邮箱 redfoxdata@proton.me 处理」
     • 询问用户：「是否订阅明日推送？」
     • 用户回答「订阅」→ 静默执行 add 订阅
     • 用户未确认 → 不订阅
3. 静默查询现有自动化任务的 --accounts 列表，判断追加 or 新建：
   • 现有账号数 + 新账号数 ≤ 20 → 追加到现有任务的 --accounts
   • 现有账号数 + 新账号数 ＞ 20 → 新建一个自动化任务放溢出部分
4. 静默更新/创建自动化任务
5. 若 fetch 返回了作品数据：
   • 自动打开 HTML 报告预览（preview_url）
   • 对话中展示 Markdown 作品表格
   • 提示：「如需查看特定时间段的作品，可以告诉我，如“查一下 2026-06-01 到 2026-06-05 的作品”」
6. 若 fetch 无作品数据（账号存在但时段内无更新）：仅告知用户无更新，不生成 HTML 报告
7. 输出顺序：先按账号名升序分组，同账号内按分享数降序排列
8. 若某个账号在指定时间范围内无更新作品，直接告知用户：「账号名：该时间段内无更新作品」

重要：仅当 fetch 返回实际作品数据时，才需要三输出——Markdown 表格 + HTML 报告预览 + HTML 报告文件。无作品数据时不生成 HTML 报告。

对话输出格式（订阅/拉取时必须遵循）

Agent 执行 fetch 后，必须在对话回复中按以下格式输出数据（不是只依赖脚本终端输出）：

格式一：账号概览表

## 📊 订阅报告

| 项目 | 值 |
|------|-----|
| 新订阅 | `新账号名`（粉丝量） |
| 当前总账号 | N 个 |
| 本次拉取作品 | N 条 |
| 自动化任务 | 已更新 ✅ 每天 9:00 自动执行 |

### 账号概览

| 账号 | 粉丝量 | 领域 | 代表作数据 |
|------|--------|------|-----------|
| AccountA | xxx | 领域 | 🏆 代表作：收藏x / 点赞x / 分享x |

格式二：每个账号的详细作品表（Markdown）

### ▸ AccountName（粉丝: xxx）

| 作品标题 | 收藏数 | 评论数 | 分享数 | 点赞数 | 发布时间 |
|---------|--------|--------|--------|--------|---------|
| 标题1 | 10.8w | 2.8k | 10.3w | 19.3w | 06-08 |

要求：

• 每个账号一个子标题 + 一个完整 Markdown 表格
• 标题列使用 API 返回的 content 字段完整原文（脚本内部映射为 title），不截断
• 数值列使用 format_number 后的可读格式（如 10.8w、2.3k）
• 发布时间截取到 MM-DD HH:mm
• 按分享数降序排列

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

### 对上述作品的总结

> 1. **突出的账号表现**：...
> 2. **高频事件 TOP5**：...

输出完整性清单

每次订阅/拉取，对话中必须包含以下全部内容：

• 账号概览表（含总览信息）
• 每个账号一个 Markdown 作品详情表
• 无更新账号提示（如有）
• 总结统计分析
• 规则 2 适用：已订阅账号昨日无数据时，结尾附加邮箱核查提示
• 规则 3 适用：被频率限制拒绝的账号提示
• 仅当有作品数据时：自动打开 HTML 报告预览（preview_url）+ HTML 报告文件已生成说明（附文件路径）

抖音号要求

接口通过 uniqueName（抖音展示ID）查询，脚本将用户提供的抖音号统一按 uniqueName 传入，userId 和 shortId 固定为空字符串。订阅时必须提供抖音号。

重要： 若用户只输入账号名称（如"李佳琦""老高與小茉"）而未提供抖音号，必须提示：

"抖音账号名称存在多个重名情况，请提供准确的抖音号以便精准订阅。"

并附上获取抖音号的示例图供用户参考：

数据规则

• 每个自动化任务最多 20 个账号（超限时 Agent 自动创建新任务，详见「账号管理规则」）
• 规则 1：未订阅账号（首次验证查询）：
  • 默认查询近 30 天数据
  • 若近 30 天无数据，自动回溯近半年（180 天）
  • 若近半年仍无数据，告知用户：「抱歉您订阅的“xxx”账号近半年都未发布过作品，如果需要数据核查可联系工作人员邮箱 redfoxdata@proton.me 处理」
• 规则 2：已订阅账号（日常拉取）：
  • 默认查前一天数据（T-1）
  • 若昨日无数据，告知用户：「昨日该账号暂未发布作品」
  • 结尾固定提示：「如果需要数据核查可联系工作人员邮箱 redfoxdata@proton.me 处理」
• 规则 3：失败阈值保护：
  • 同一抖音号在 6 小时内累计 3 次 API 调用失败后，后续请求将被拒绝
  • 拒绝时提示：「当前账号订阅已超过失败阈值，请联系客服邮箱 redfoxdata@proton.me 处理」
  • 距上次失败超过 6 小时 / 同一账号查询成功，计数归零，恢复正常调用
• 用户指定日期不回溯：若用户明确指定了日期或日期范围，查不到数据时直接告知用户，不自动回溯
• 支持日期范围查询：用户可指定起止日期（--date-start YYYY-MM-DD --date-end YYYY-MM-DD）拉取历史作品
• 每账号最多返回 10 条作品
• 排序方式：账号名升序 → 同账号内分享数降序
• 无数据提示：若某个账号在指定时间范围内无更新作品，脚本会输出「账号名：该时间段内无更新作品」，Agent 需将此信息原样转达给用户
• 接口不支持多账号同时查询，脚本自动拆分后逐账号调用并整合数据

输出表格结构（脚本终端格式，仅供参考）

脚本终端输出原始格式如下，但 Agent 对话中必须使用「对话输出格式」中的 Markdown 表格重新排版：

▸ Fish688688（粉丝: 249w+）
──────────────────────────────────────────────────────────────
  作品标题                          收藏数  评论数  分享数  点赞数  发布时间
──────────────────────────────────────────────────────────────
  今晚图省事...                    10.8w   2.8k   10.3w  19.3w  05-21 21:40

作品标题使用 API content 字段（脚本内部映射为 title），链接使用 opusUrl 字段（脚本内部映射为 workUrl）。Markdown 输出中标题自动渲染为可点击超链接：[标题](workUrl)。

注意：当前广域库 API 不返回 followerCount（粉丝数），账号概览中粉丝量显示为 -。

总结统计

表格展示完毕后，必须严格按以下格式附加总结：

对上述作品的总结：

1. 突出的账号表现：指出数据最亮眼的账号及其代表作品
2. 高频事件 TOP5：提炼所有作品中提到次数最多的 5 个事件/话题，并归纳每个事件对应的不同观点（不足 5 个可提炼的，按实际数量呈现，禁止虚构）