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 获取 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..."

依赖

无需安装第三方依赖，使用 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）：

   python3 scripts/subscribe.py top --query "用户原始问题" --top 20
   

3. 从输出尾部提取各账号 screen_name（脚本已从 profileUrl 的 x.com/<handle> 解析好，并输出逗号分隔列表）

4. 运行 fetch --first 验证每个账号是否可成功拉取：

   python3 scripts/subscribe.py fetch --accounts "handle1,handle2,..." --first --html
   

5. 将验证通过的账号批量写入每日 9:00 自动化任务（见「账号管理规则」），告诉用户结果

6. 立即执行一次展示结果（首次拉取各账号最新动态）

榜单输出尾部应提供订阅提示：是否订阅该榜单 Top 10/20/50，都不满意可直接订阅全部。

入口二：单独输入账号订阅

用户提供 @handle 或账号链接 → 提取 screen_name → 立即执行验证 → 追加到订阅名单：

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

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

入口三：关注列表探索

用户不知道订阅谁时（如「看看马斯克都在关注谁」）→ 调用 following 拉取关注列表（默认只拉 1 页、首次最多展示 20 个账号，含名称/粉丝数/简介）→ 用户从中挑选 → 走入口二入订阅：

# 默认：拉 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。

{
  "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/generate_report.py	生成 HTML 可视化日报
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 天）。