douyin-subscribe

---
name: douyin-subscribe
description: 抖音账号订阅追踪 — 通过抖音号订阅账号（最多20个），Agent 每日 9:00 自动拉取并生成 HTML 报告。账号 ID 直接内置于自动化命令中，无需文件存储。支持多抖音号批量订阅，自动生成精美 HTML 作品报告，终端/Markdown 表格按账号依次展示作品标题、收藏、评论、分享、点赞、发布时间等数据。当用户订阅抖音账号、追踪抖音作品更新、监控抖音竞品账号时使用。触发词：抖音订阅、抖音账号订阅、抖音订阅追踪、抖音作品订阅、抖音账号监控、抖音作品追踪、抖音每日推送、抖音日报。
---

# 抖音账号订阅追踪

## 📝 简介

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

---

## ✨ 功能特性

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

---

## 🔑 鉴权

### 获取 API Key

请前往 [红狐hub](https://redfox.hk/settings/api-keys?source=github) 获取API KEY

### 配置 API Key

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

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

方案2: 终端配置

```bash
export REDFOX_API_KEY="ak_xxxx..."
```

---

## ⚙️ 使用方式

### 拉取作品（核心命令）

```bash
# 基础用法：直接传入抖音号列表
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**：

```bash
# 自动化任务中的实际命令（账号已内置）
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. **判断账号状态**：
   - **接口返回 `type=1`（未收录）**：
     - 直接告知用户「当前暂未找到该账号信息，可能是数据覆盖范围有限所致」
     - **询问用户**：「我们将尽快更新数据，通常10分钟内可查，特殊情况下需1天。是否订阅明日推送？」
     - 用户回答「订阅」→ **静默执行** add 订阅
     - 用户未确认 → 不订阅
   - **接口返回正常数据 / 无作品但账号存在**：
     - **静默执行** 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 后，**必须在对话回复中按以下格式输出数据**（不是只依赖脚本终端输出）：

#### 格式一：账号概览表

```markdown
## 📊 订阅报告

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

### 账号概览

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

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

```markdown
### ▸ AccountName（粉丝: xxx）

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

要求：
- 每个账号一个子标题 + 一个完整 Markdown 表格
- 标题列使用 `title` 字段值，超长标题截断为前30字+`...`
- 数值列使用 `format_number` 后的可读格式（如 10.8w、2.3k）
- 发布时间截取到 `MM-DD HH:mm`
- 按**分享数降序**排列

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

```markdown
### 对上述作品的总结

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

#### 输出完整性清单

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

- [ ] 账号概览表（含总览信息）
- [ ] 每个账号一个 Markdown 作品详情表
- [ ] 无更新账号提示（如有）
- [ ] 未收录账号提示 + 询问是否订阅明日推送（如有）
- [ ] 总结统计分析
- [ ] **仅当有作品数据时**：自动打开 HTML 报告预览（preview_url）+ HTML 报告文件已生成说明（附文件路径）

### 抖音号要求

接口仅支持通过抖音号（`accountId`）查询，订阅时**必须提供抖音号**。支持 `unique_id`、`short_id`、`uid` 任一格式。

**重要：** 若用户只输入账号名称（如"李佳琦""老高與小茉"）而未提供抖音号，必须提示：
> "抖音账号名称存在多个重名情况，请提供准确的**抖音号**以便精准订阅。"

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

![获取抖音号示例](https://lyy.redfox.hk/page/ljq.png)

### 数据规则

- **每个自动化任务最多 20 个账号**（超限时 Agent 自动创建新任务，详见「账号管理规则」）
- **默认查前一天数据（T-1）**：用户未指定日期时，fetch 默认查询昨日作品；若昨日无数据则**自动回溯近 7 天**（T-7 至 T-1）；若仍无数据则直接告知用户
- **用户指定日期不回溯**：若用户明确指定了日期或日期范围，查不到数据时直接告知用户，不自动回溯
- **支持日期范围查询**：用户可指定起止日期（`--date-start YYYY-MM-DD --date-end YYYY-MM-DD`）拉取历史作品
- 每账号最多返回 **10 条**作品
- 排序方式：账号名升序 → 同账号内**分享数降序**
- **无数据提示**：若某个账号在指定时间范围内无更新作品，脚本会输出「**账号名**：该时间段内无更新作品」，Agent 需将此信息原样转达给用户
- **未收录账号提示**：若接口返回 `type=1` 表示账号未被数据库收录，脚本会输出引导信息：「当前暂未找到该账号信息，可能是数据覆盖范围有限所致。我们将尽快更新数据，通常10分钟内可查，特殊情况下需1天，您可订阅明日推送。」Agent 需原样转达
- 接口不支持多账号同时查询，脚本自动拆分后逐账号调用并整合数据

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

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

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

作品标题使用 `title` 字段，链接使用 `workUrl` 字段。Markdown 输出中标题自动渲染为可点击超链接：`[标题](workUrl)`。

### 总结统计

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

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