x-research

用途

X/Twitter Research 是一套用于研究 X/Twitter 高表现内容的工作流：抓取被跟踪账号的推文，识别异常高表现（outlier）的推文，找出热门话题与内容模式，并可选地分析视频内容的结构与开场钩子。

主要能力

通过 Apify 的 Tweet Scraper V2 抓取指定账号在给定时间范围内的推文。
识别异常推文：输出中包含 total_posts（分析的推文数）、outlier_count（发现的异常推文数）、topics（热门标签、提及与关键词）、content_patterns（表现好的格式分析）、accounts（已分析账号列表）以及 outliers（带互动指标的异常推文数组）。
可选视频分析：当异常推文中包含视频内容时，可调用视频分析脚本，输出开场钩子、为什么有效以及可复制公式等信息。
生成结构化 Markdown 报告，涵盖摘要、表现最佳的推文、表现最佳的开场钩子、热门话题、内容模式表格、可执行的行动建议以及已分析账号列表。

使用方式

前置条件

APIFY_TOKEN 环境变量或写在 .env 中。
GEMINI_API_KEY 环境变量或写在 .env 中（用于视频分析）。
安装 apify-client 与 google-genai Python 包。
账号配置在 .claude/context/x-accounts.md。

验证配置：

python3 -c "
import os
try:
    from dotenv import load_dotenv
    load_dotenv()
except ImportError:
    pass
from apify_client import ApifyClient
assert os.environ.get('APIFY_TOKEN'), 'APIFY_TOKEN not set'
" && echo "Prerequisites OK"

工作流

RUN_FOLDER="x-research/$(date +%Y-%m-%d_%H%M%S)" && mkdir -p "$RUN_FOLDER" && echo "$RUN_FOLDER"

抓取推文：

python3 .claude/skills/x-research/scripts/fetch_tweets.py \
  --days 30 \
  --max-items 100 \
  --output {RUN_FOLDER}/raw.json

参数说明：

--days：回溯搜索的天数（默认 30）。
--max-items：每个账号最多抓取的推文数（默认 100）。
--handles：用指定 handle 覆盖账号文件。

API 限制：每个查询至少需要 50 条推文；两次运行之间需等待几分钟。

识别异常值：

python3 .claude/skills/x-research/scripts/analyze_posts.py \
  --input {RUN_FOLDER}/raw.json \
  --output {RUN_FOLDER}/outliers.json \
  --threshold 2.0

使用 AI 分析视频（可选）：

python3 .claude/skills/video-content-analyzer/scripts/analyze_videos.py \
  --input {RUN_FOLDER}/outliers.json \
  --output {RUN_FOLDER}/video-analysis.json \
  --platform x \
  --max-videos 5

注意：X/Twitter 以文本为主，视频分析为可选项，仅在异常推文包含视频时有用。

生成报告：读取 {RUN_FOLDER}/outliers.json（以及可选的 {RUN_FOLDER}/video-analysis.json），然后生成 {RUN_FOLDER}/report.md。

报告结构包含：摘要（分析推文总数、异常推文数、异常率）、表现最佳的推文（异常值，最多 15 条，含 URL、日期、互动数据、互动得分、互动率、粉丝数）、表现最佳的开场钩子（如有视频分析）、热门话题（热门标签、关键词、提及）、异常内容模式表格（是否含媒体、外部链接、线程格式、引用推文、提问、列表/编号格式、短/中/长文本等占比）、可执行的行动建议（4-6 条具体建议）以及已分析账号。

快速参考

完整流程：

RUN_FOLDER="x-research/$(date +%Y-%m-%d_%H%M%S)" && mkdir -p "$RUN_FOLDER" && \
python3 .claude/skills/x-research/scripts/fetch_tweets.py -o "$RUN_FOLDER/raw.json" && \
python3 .claude/skills/x-research/scripts/analyze_posts.py -i "$RUN_FOLDER/raw.json" -o "$RUN_FOLDER/outliers.json"

含视频分析（可选）：

python3 .claude/skills/video-content-analyzer/scripts/analyze_videos.py -i "$RUN_FOLDER/outliers.json" -o "$RUN_FOLDER/video-analysis.json" -p x

然后读取 JSON 文件并生成报告。

互动指标

互动得分（加权）：

收藏：4 倍（最高信号，被保存作参考）
回复：3 倍（主动对话）
转发：2 倍（放大传播）
引用：2 倍（带评论的互动）
点赞：1 倍（被动认可）

异常检测：互动率 > 平均值 +（阈值 × 标准差）的推文。

互动率：(得分 / 粉丝数) × 100。

输出位置

所有输出写入带时间戳的运行文件夹：

x-research/
└── {YYYY-MM-DD_HHMMSS}/
    ├── raw.json            # 来自 Apify 的原始推文数据
    ├── outliers.json       # 异常推文及其元数据与话题
    ├── video-analysis.json # AI 视频分析（可选）
    └── report.md           # 最终报告

适用场景与限制

适用于需要在 X/Twitter 上做内容研究、寻找表现突出的推文与内容模式、跟踪特定账号表现、以及从视频推文中提取开场钩子的场景。限制包括：需要 Apify 与 Gemini 的 API 凭据；接口有最低 50 条推文/查询、运行间隔需几分钟的限制；视频分析仅在异常推文含视频时才有用，X/Twitter 本身以文本为主，因此视频分析属于可选项。