x-subscribe · git:20260924.e7021f9 · 2026-09-24 · sha256 89e354bc08bb3741
x-subscribe git:20260924.e7021f9A
Immutable. This exact content is served forever at /api/v1/blob/89e354bc08bb3741.
---
name: x-subscribe
description: X(Twitter)订阅账号推文工具 — 订阅 Twitter 名人账号（来源：榜单推荐 / 用户指定 @handle / 关注列表探索），每日早上 9:00 自动拉取订阅账号昨日最新推文，按账号分组生成 HTML 日报推送，无需手动操作。支持最多 100 个账号批量订阅、按日期过滤翻页、互动数据（浏览/点赞/转发/回复）展示与 AI 总结。当用户需要订阅 Twitter/X 账号、追踪名人推文动态、监控 KOL 发声、获取 X 账号昨日发帖日报时使用。触发词：X订阅、Twitter订阅、订阅推特账号、订阅推文、X名人日报、Twitter账号追踪、关注列表探索、订阅KOL、推特动态订阅、X日报。
dependency: {}
---
# X (Twitter) 订阅账号推文
## 1. 简介
订阅 X(Twitter) 名人账号，**每日早上 9:00 自动拉取订阅账号昨日 9:00 至今日 9:00（近 24 小时）发布的推文**，按账号分组生成精美 HTML 日报推送，无需手动逐个刷动态。订阅来源支持三种入口：榜单推荐、用户指定账号、关注列表探索。
> **榜单推荐**是本 Skill 内置的批量订阅来源：固定查询**昨日**的 X 热门账号榜，支持性别（全部/男/女）与 32 个行业分类筛选，用户可一键订阅榜单 Top N 账号后进入每日推文追踪。
**适用对象**：出海品牌 / 投放人员（评估 KOL 合作窗口）、MCN / 商务经纪（批量盯几十个名人账号动态）、内容创作者 / 研究者（追踪头部账号发帖节奏与爆款）。
---
## 2. 功能特性
| 功能模块 | 能力描述 |
|---------|---------|
| 三入口订阅 | 榜单批量订阅 / 指定 @handle 订阅 / 关注列表探索后订阅 |
| 每日自动推送 | 自动化任务内置账号 handle，每天 9:00 自动拉取昨日推文 |
| 时间窗口过滤 | 接口不支持按时间排序，Skill 内部按「昨日 9:00 ~ 今日 9:00」时间窗口过滤并智能 cursor 翻页 |
| HTML 日报 | X 平台风格（白底 + X 蓝），按账号分组展示推文时间线，支持导出 PDF / 高清图片 |
| 互动数据 | 浏览 / 点赞 / 转发 / 回复 / 发布时间，转推与引用标识 |
| AI 语义总结 | AI 读推文内容，归纳「今日主题」（分析推文在说什么，按实际条数）+ 每个账号的「今日主题/观点」 |
| 无更新折叠 | 昨日无更新 / 近 7 天无更新账号自动折叠提示 |
---
## 3. 鉴权
### 获取 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..."
```
### 依赖
无需安装第三方依赖，使用 Python 标准库即可运行。
---
## 4. 订阅方式（三个入口）
> **静默执行原则**：所有中间步骤（fetch 验证、榜单查询、automation_update）均不得向用户输出过程性提示，仅展示最终结果。
用户表达订阅意向但方式不明确时，先输出引导：
```
📬 订阅 Twitter 名人作品日报，三种方式任选：
1️⃣ 榜单订阅 — 说「订阅XX分类热门榜单 Top 10/20/50」
2️⃣ 指定账号 — 直接发我 @handle 或账号链接，如「订阅 @elonmusk」
3️⃣ 关注探索 — 不知道订阅谁？从 TA 的关注列表里挑，说「看看elonmusk关注了谁」
已订阅后每天 9:00 自动推送昨日发帖日报，最多可订阅 100 个账号。
```
### 入口一：从热门账号榜批量订阅（推荐主路径）
1. 用户查看某分类榜单（如「商业创业日榜」），或直接说「订阅科技榜前 30 个」
2. Agent 运行 `top` 子命令查询**昨日**榜单（解析 N，N ≤ 100）：
```bash
python3 scripts/subscribe.py top --query "用户原始问题" --top 20
```
3. 从输出尾部提取各账号 `screen_name`（脚本已从 `profileUrl` 的 `x.com/<handle>` 解析好，并输出逗号分隔列表）
4. 运行 `fetch --first` 验证每个账号是否可成功拉取：
```bash
python3 scripts/subscribe.py fetch --accounts "handle1,handle2,..." --first --html
```
5. 将验证通过的账号批量写入每日 9:00 自动化任务（见「账号管理规则」），告诉用户结果
6. 立即执行一次展示结果（首次拉取各账号最新动态）
> 榜单输出尾部应提供订阅提示：是否订阅该榜单 Top 10/20/50，都不满意可直接订阅全部。
### 入口二：单独输入账号订阅
用户提供 `@handle` 或账号链接 → 提取 `screen_name` → 立即执行验证 → 追加到订阅名单：
```bash
# 验证并首次展示（静默执行）
python3 scripts/subscribe.py fetch --accounts "elonmusk" --first --html
```
验证通过后追加到自动化任务的 `--accounts` 参数（见「账号管理规则」）。
### 入口三：关注列表探索
用户不知道订阅谁时（如「看看马斯克都在关注谁」）→ 调用 `following` 拉取关注列表（**默认只拉 1 页、首次最多展示 20 个**账号，含名称/粉丝数/简介）→ 用户从中挑选 → 走入口二入订阅：
```bash
# 默认：拉 1 页，最多展示前 20 个
python3 scripts/subscribe.py following --account "elonmusk"
# 用户想「查看更多」：展示本页已获取的全部账号（不发起新请求）
python3 scripts/subscribe.py following --account "elonmusk" --all
# 用户想「继续翻页」：用上次输出的 nextCursor 拉下一页
python3 scripts/subscribe.py following --account "elonmusk" --cursor "<nextCursor>"
```
> 展示策略：首次仅呈现前 20 个；当本页还有未展示账号时提示「查看更多」（加 `--all` 展示全部），当 `moreUsers=true` 时提示「继续翻页」（加 `--cursor`）。
---
## 5. 拉取作品 API 处理（核心规则）
接口**不支持按时间排序**，时间线按倒序返回。Skill 内部按场景区分处理：
### 首次订阅查看（`--first`）
直接拉取第 1 页推文，每账号默认展示 20 条，**不按时间窗口过滤**。
### 后续每日更新订阅作品（默认模式）
> 时间窗口：每日早上 9:00 运行时，拉取「昨日 9:00 ~ 今日 9:00」这一近 24 小时窗口内的推文（接口不支持按时间排序，需逐条比对）。
1. 拉第 1 页推文
2. 逐个查看推文发布时间（`createdAt` 为 UTC，转换为**本地时区**），仅保留落在窗口「昨日 9:00 ~ 今日 9:00」内的推文
3. 若本页存在命中推文**且**没有早于窗口起点（昨日 9:00）的推文 → 继续 cursor 翻页
4. 当页已包含早于窗口起点的推文 → **结束翻页**，只保留窗口内的推文
5. 安全上限：每账号最多翻 5 页（`--max-pages` 可调），或 `nextCursor` 为空时停止
> cursor 是服务端状态标识，不可自行构造，必须严格使用上一页返回的 `nextCursor`。
### 账号状态判定
| 状态 | 判定条件 | 报告处理 |
|------|---------|---------|
| `updated` | 命中昨日推文 | 正常展示推文表格 |
| `no_update_yesterday` | 无昨日推文，但近 7 天有推文 | 折叠提示「昨日无更新」 |
| `no_update_7d` | 最新推文早于 7 天前 / 无推文 | 折叠提示「近 7 天无更新」 |
| `error` | 接口请求失败 | 折叠提示失败原因 |
---
## 6. 使用指南
### 命令速查
| 用户意图 | 命令 |
|---------|------|
| 拉取订阅账号昨日推文（每日更新） | `fetch --accounts "h1,h2" --html` |
| 首次订阅验证 / 查看最新动态 | `fetch --accounts "h1,h2" --first --html` |
| 指定历史日期 | `fetch --accounts "h1" --date 2026-09-20 --html` |
| 探索某账号关注列表（默认1页/最多20个） | `following --account "elonmusk"` |
| 查询昨日榜单推荐（批量订阅来源） | `top --query "科技软件榜前20" --top 20` |
### fetch 参数
| 参数 | 说明 |
|------|------|
| `--accounts` | **必填**，账号列表，逗号分隔（@handle 或 x.com 链接均可） |
| `--date` | 时间窗口结束日 `YYYY-MM-DD`（默认：最近一个 9:00 边界往前 24 小时） |
| `--first` | 首次订阅模式：拉第一页全部推文，不按日期过滤 |
| `--max-pages` | 每日更新模式每账号最多翻页数（默认 5） |
| `--markdown` | 输出 Markdown 格式表格（供 Agent 转述） |
| `--html` | 生成 HTML 日报（自动打开浏览器） |
| `--output` | 自定义 JSON 输出路径 |
### following / top 参数
- `following`：`--account`（必填）、`--pages`（默认 1）、`--limit`（首次最多展示数，默认 20）、`--all`（展示已获取全部）、`--cursor`（翻页游标）
- `top`：`--query`（自动解析行业/性别）、`--category`、`--gender`、`--top`（默认 20，最多 100）、`--date`（默认昨日）
> 全局参数 `--api-key` 需置于子命令**之前**（如 `subscribe.py --api-key ak_xxx fetch ...`），默认读环境变量 `REDFOX_API_KEY`。
### 账号名纠错（Agent 必须遵守）
若某账号获取失败（`status=error`），请提示用户确认账号名是否正确——handle 可从 X 主页链接获取，例如 `https://twitter.com/elonmusk` 中的 `elonmusk`、`https://x.com/naval` 中的 `naval`。脚本在失败时也会打印该提示。
---
## 7. 账号管理规则（Agent 必须遵守）
> **核心原则：所有订阅状态 = 自动化命令中的 `--accounts` 参数。无本地文件存储。**
### 上限
- **单个自动化任务最多 50 个账号**
- **总订阅上限 100 个账号**
### 订阅新账号流程
1. **查询现有自动化任务**：使用 `automation_update mode=list` 获取所有「X订阅」相关任务，读取每个任务 `--accounts` 中的账号列表
2. **判断追加 / 新建**：
| 条件 | 操作 |
|------|------|
| 现有账号数 + 新账号数 ≤ 50 | 追加到现有任务的 `--accounts`（去重后逗号拼接） |
| 现有账号数 + 新账号数 ＞ 50 且总数 ≤ 100 | 新建自动化任务，溢出部分放入新任务 |
| 总数将 ＞ 100 | 告知用户已达上限，请取消部分账号后再订阅 |
| 用户要求取消某账号 | 从对应任务 `--accounts` 移除该 handle |
3. **更新/创建自动化任务**：
- 追加：`automation_update mode=update` 修改现有任务 `prompt` 中的 `--accounts`
- 新建：`automation_update mode=create`，每日 9:00 执行（`FREQ=DAILY;BYHOUR=9;BYMINUTE=0`），名称加序号如「X订阅推文日报 #2」
- automation prompt 示例：`拉取X(Twitter)订阅账号昨日推文并生成HTML日报推送给用户：python3 scripts/subscribe.py fetch --accounts "h1,h2,..." --html`
4. **立即拉取一次**：无论追加还是新建，都必须立即执行一次 `fetch --first --html` 展示最新结果
### 取消订阅
从对应任务的 `--accounts` 移除该 handle。若移除后某任务剩余 0 个账号，则删除该自动化任务。
---
## 8. 输出格式
### 订阅结果总览（订阅/拉取时必须输出）
```
📊 订阅结果
| 项目 | 值 |
|------|-----|
| 本次订阅 | 20 个（科技软件榜 Top 20，2 个已订阅跳过） |
| 当前总订阅 | 45 / 100 个 |
| 自动化任务 | 已更新 ✅ 每日 9:00 自动执行 |
| 首次拉取 | 以下展示各账号最新动态 |
```
### 每账号推文详情表（Markdown）
```
▸ Elon Musk（粉丝: 2.4亿）
| 推文摘要 | 浏览 | 点赞 | 转发 | 回复 | 发布时间 |
|---------|------|------|------|------|---------|
| Starship Flight 12 launch tomorrow... | 8,900w | 120w | 21w | 3.4w | 09-19 08:30 |
```
要求：
- 每个账号一个子标题 + 一个完整 Markdown 表格，每账号默认展示 20 条
- 推文摘要使用 `text` 原文（过长截取前 60 字），渲染为可点击超链接 `[摘要](tweetUrl)`
- 转推加 🔁 前缀，引用推文加 💬 前缀
- 数值列使用可读格式（8,900w / 120w / 3.4w）
- 发布时间截取到 `MM-DD HH:mm`（本地时区）
- 昨日无更新 / 近 7 天无更新账号折叠提示，如：「以下 12 个账号近 7 天无更新，已折叠」
### 总结统计（必须附加在所有表格之后）
由 **AI 读取推文内容**生成语义总结，不接 LLM 端点、不做词频统计。写入与数据文件同目录的 `x_subscribe_ai_summary.json`，`generate_report.py` 渲染时自动合并到 HTML。
```json
{
"overall": [
{"title": "主题/事件名", "summary": "这段在讲什么（1-2 句）", "accounts": ["elonmusk"], "tweetCount": 11}
],
"accounts": [
{"screenName": "elonmusk", "theme": "该账号今日主要聊了什么主题", "viewpoint": "该账号表达的观点/立场"}
]
}
```
要求：
- `overall` 是「今日主题总结」：分析推文到底在说什么（事件/主题），**不是简单高频词**；有几条归纳几条，不强制凑 5 条，禁止虚构
- `accounts` 是单账号总结：每个有更新账号一条，说明「主要主题」和「观点/立场」
- 主题数按实际内容归纳，没有 5 个就少写；不硬凑
### 输出完整性清单
每次订阅/拉取，对话中必须包含：
- [ ] 订阅结果总览表
- [ ] 每个有更新账号的 Markdown 推文详情表
- [ ] 无更新账号折叠提示（如有）
- [ ] 总结统计分析（AI 语义总结：今日主题 + 单账号主题/观点）
- [ ] **仅当有推文数据时**：HTML 日报已生成说明（附文件路径）+ 自动打开预览
- HTML 日报的「报告说明」会解释 🔁 转发与 💬 引用的区别，并说明纯转发的点赞/回复为何常为空或 0（转发不是独立推文，互动数据归属原推文）
---
## 9. 项目架构
```
x-subscribe/
├── SKILL.md # 本文件
├── scripts/
│ ├── subscribe.py # 统一入口：fetch / following / top 子命令
│ └── generate_report.py # 生成 X 风格 HTML 日报（导出 PDF/图片）
├── assets/
│ └── category_config.json # 榜单更新规则 + 性别/行业枚举与关键词映射
├── output/ # JSON 数据与 HTML 日报输出目录（运行时自动创建）
└── references/
└── api_docs.md # 3 个接口详细文档（技术参考）
```
### 核心模块说明
- **subscribe.py**：
- `fetch` — 拉取订阅账号推文，支持首次模式（拉第一页）与每日模式（按昨日过滤 + cursor 智能翻页），输出 JSON + Markdown，`--html` 时调用报告生成
- `following` — 拉取账号关注列表，cursor 翻页，用于订阅前探索
- `top` — 查询昨日热门账号榜（内置榜单数据源），从 profileUrl 解析 screen_name，输出可直接用于 `fetch --accounts` 的 handle 列表
- **generate_report.py**：读取 fetch 输出的 JSON 生成 X 平台风格（纯白底 + X 蓝）HTML 日报，按账号分组展示推文时间线（含头像、认证标识、封面图、互动数据），无更新账号折叠，内置一键下载 PDF / 高清图片按钮（html2canvas + jsPDF 直接生成文件下载，非浏览器打印），生成后自动打开浏览器。文件名格式 `X订阅日报_{日期}.html`（首次模式为 `X订阅首次拉取_{日期}.html`）。
### 资源索引
| 文件 | 用途 |
| ---- | ---- |
| [scripts/subscribe.py](scripts/subscribe.py) | 拉取推文 / 关注列表 / 榜单推荐 |
| [scripts/generate_report.py](scripts/generate_report.py) | 生成 HTML 可视化日报 |
| [references/api_docs.md](references/api_docs.md) | 3 个接口详细文档（技术参考） |
---
## 10. 常见问答
**Q: 需要安装什么依赖？**
A: 无需第三方依赖，Python 标准库即可运行。
**Q: 最多订阅多少个账号？**
A: 总上限 100 个；单个自动化任务最多 50 个，超出自动新建任务。
**Q: 每日报告什么时候推送？拉取哪段时间的数据？**
A: 每天早上 9:00 自动执行，拉取「昨日 9:00 ~ 今日 9:00」这一近 24 小时窗口内（本地时区）发布的推文。
**Q: 接口不支持按时间排序，怎么保证只拉时间窗口内的推文？**
A: Skill 内部按 cursor 翻页并逐条比对发布时间：命中窗口且无早于窗口起点（昨日 9:00）的推文则继续翻页，出现更早推文即停止，只保留窗口内推文（详见第 5 节）。
**Q: 推文时间是什么时区？**
A: 接口返回 UTC 时间，Skill 统一转换为**本地时区**展示与过滤。
**Q: 某账号昨日没发推怎么办？**
A: 报告中折叠提示「昨日无更新」；若近 7 天都无更新则提示「近 7 天无更新」。
**Q: 如何取消订阅？**
A: 告诉 Agent 要取消的账号，Agent 从对应自动化任务的 `--accounts` 中移除该 handle。
**Q: 榜单推荐的数据日期？**
A: `top` 子命令固定查询昨日榜单（每日 9:00 更新前一天数据，最多回溯 7 天）。