名称： twitter-search
描述： 高级 Twitter 搜索与社交媒体数据分析工具。使用 Twitter API 根据关键词获取推文，最多可处理 1000 条结果，并生成包含洞察与可执行建议的专业数据分析报告。适用于用户请求 Twitter/X 社交媒体搜索、社交媒体趋势分析、推文数据挖掘、社交聆听、意见领袖识别、推文主题情感分析，或任何涉及收集和分析 Twitter 数据以获取洞察的任务。

Twitter 搜索与分析

概述

使用高级搜索语法搜索 Twitter 关键词，获取最多 1000 条相关推文，并对数据进行分析，生成包含洞察、统计数据和可执行建议的专业报告。

前提条件

需要 API 密钥：用户必须从 https://twitterapi.io 配置其 Twitter API 密钥。

API 密钥可通过以下三种方式提供：
1. 环境变量（推荐）：在 ~/.bashrc 或 ~/.zshrc 中设置 TWITTER_API_KEY
bash echo 'export TWITTER_API_KEY="your_key_here"' >> ~/.bashrc source ~/.bashrc
2. 作为参数：使用包装脚本时附带 --api-key YOUR_KEY
3. 直接传递：作为 Python 脚本的第一个参数

快速开始

使用包装脚本（推荐）

包装脚本自动处理环境变量加载和依赖项检查：

# 基本搜索（使用 shell 配置中的 TWITTER_API_KEY）
./scripts/run_search.sh "AI"

# 使用自定义 API 密钥
./scripts/run_search.sh "AI" --api-key YOUR_KEY

# 带选项的搜索
./scripts/run_search.sh "\"Claude AI\"" --max-results 100 --format summary

# 高级查询
./scripts/run_search.sh "from:elonmusk since:2024-01-01" --query-type Latest

直接使用 Python 脚本

# 搜索关键词
scripts/twitter_search.py "$API_KEY" "AI"

# 搜索多个关键词
scripts/twitter_search.py "$API_KEY" "\"ChatGPT\" OR \"Claude AI\""

# 搜索特定用户的推文
scripts/twitter_search.py "$API_KEY" "from:elonmusk"

# 按日期范围搜索
scripts/twitter_search.py "$API_KEY" "Bitcoin since:2024-01-01"

高级查询

# 复杂查询：来自认证用户的英文 AI 推文
scripts/twitter_search.py "$API_KEY" "AI OR \"machine learning\" lang:en filter:verified"

# 具有最低互动量的近期加密货币推文
scripts/twitter_search.py "$API_KEY" "Bitcoin min_retweets:10 lang:en"

# 来自特定意见领袖的推文
scripts/twitter_search.py "$API_KEY" "from:elonmusk OR from:VitalikButerin since:2024-01-01"

输出格式

# 包含所有推文的完整 JSON
scripts/twitter_search.py "$API_KEY" "AI" --format json

# 包含统计数据的摘要（默认）
scripts/twitter_search.py "$API_KEY" "AI" --format summary

选项

• --max-results N：要获取的最大推文数（默认：1000）
• --query-type Latest|Top：排序方式（默认：Top，按相关性）
• --format json|summary：输出格式（默认：summary）

工作流程

1. 理解用户需求

明确分析目标：
- 要搜索什么主题/关键词？
- 偏好什么日期范围？
- 要包含/排除哪些特定用户？
- 语言偏好？
- 需要何种洞察（趋势、情感、意见领袖）？

2. 构建搜索查询

使用 Twitter 高级搜索 语法：

3. 获取数据

执行搜索脚本：

scripts/twitter_search.py "$API_KEY" "YOUR_QUERY" --max-results 1000 --query-type Top

重要提示：默认最多获取 1000 条推文。脚本会自动：
- 对所有可用结果进行分页处理
- 在 1000 条推文处停止（考虑 API 限制）
- 优雅地处理错误

4. 分析并生成报告

获取数据后，生成一份全面的专业报告，包含：

报告结构

1. 执行摘要（2-3 句话）

   • 搜索内容概述
   • 关键发现概览

2. 数据概览

   • 分析的推文总数
   • 数据日期范围
   • 使用的查询参数

3. 关键指标

   • 总互动量（点赞、转发、回复、引用、浏览量）
   • 每条推文的平均互动量
   • 语言分布
   • 回复与原创推文比例

4. 热门内容分析

   • 转发最多的推文（附带指向原推文的 URL 链接）
   • 点赞最多的推文（附带指向原推文的 URL 链接）
   • 热门话题标签及其频率
   • 提及最多的用户
   • 精选推文示例（附带完整的 URL 引用）

5. 意见领袖分析

   • 按粉丝数排名的顶级用户
   • 最活跃的用户
   • 认证用户百分比

6. 趋势洞察（基于数据模式）

   • 新兴主题
   • 情感指标
   • 时间模式
   • 对话驱动因素

7. 关键要点

   • 3-5 个核心洞察要点
   • 基于数据的结论

8. 可执行建议

   • 具体、可实施的建议
   • 基于数据发现
   • 按影响优先级排序

分析指南

• 数据驱动：每个主张都应引用实际指标
• 提供背景：解释指标为何重要
• 识别模式：在整个数据集中寻找趋势
• 保持客观：陈述事实，避免猜测
• 具体明确：建议应具体且可操作
• 考虑外部背景：在相关时使用网络搜索获取背景信息

5. 输出格式

以清晰的 Markdown 格式呈现报告，包括：
- 每个部分的标题
- 结构化数据的表格
- 列表的要点符号
- 关键指标使用粗体
- 推文示例使用代码块
- 所有引用的推文使用 可点击的 URL（格式：[@username](https://x.com/username/status/tweet_id)）

推文 URL 格式

始终包含指向推文的可点击链接：

| 作者 | 推文 | URL |
|------|------|-----|
| @user | 推文内容摘要 | [查看](https://x.com/user/status/123456) |

或内联格式：

- **@username**: 推文摘要 - [查看推文](https://x.com/username/status/123456)

按用例分类的查询示例

趋势分析

"AI" OR "artificial intelligence" lang:en min_retweets:50

竞争对手监控

from:competitor1 OR from:competitor2 since:2024-01-01

产品发布跟踪

#ProductName OR "Product Name" lang:en filter:verified

危机监控

#BrandName OR "Brand Name" lang:en --query-type Latest

意见领袖发现

#Topic lang:en min_retweets:100 min_faves:500

情感分析

"brand name" OR #BrandName lang:en --max-results 1000

资源

scripts/run_search.sh（包装脚本）

便捷的包装脚本，处理环境变量加载和依赖项检查：
- 自动从 ~/.bashrc 或 ~/.zshrc 加载 TWITTER_API_KEY
- 检查 Python 可用性并安装缺失的依赖项
- 提供用户友好的错误信息
- 支持 Python 脚本的所有命令行选项

用法：

./scripts/run_search.sh <query> [options]

选项：
- --api-key KEY：覆盖环境变量中的 API 密钥
- --max-results N：要获取的最大推文数（默认：1000）
- --query-type Latest|Top：排序方式（默认：Top）
- --format json|summary：输出格式（默认：json）

scripts/twitter_search.py

可执行的 Python 脚本，功能包括：
- 从 Twitter API 获取推文
- 自动处理分页
- 提取关键推文指标
- 计算聚合统计数据
- 输出结构化的 JSON 数据

用法：

scripts/twitter_search.py <api_key> <query> [options]

references/twitter_api.md

全面的 API 文档，包括：
- 完整的参数参考
- 查询语法指南
- 响应结构详情
- 分页说明
- 分析最佳实践
- 错误处理指南

阅读时机：构建复杂查询或理解数据结构时。

优化分析技巧

1. 使用 Top 查询类型进行趋势分析（结果更相关）
2. 设置日期过滤器以获得及时的洞察
3. 按语言过滤以进行准确的文本分析
4. 包含最低互动量以过滤噪音
5. 结合网络搜索以验证趋势
6. 超越指标——分析内容主题
7. 跟踪话题标签以识别子对话
8. 结合粉丝数与互动量来识别意见领袖

错误处理

如果脚本失败：
- 检查 API 密钥有效性
- 验证查询语法
- 确保网络连接
- 检查速率限制（如果适用）
- 查看错误信息以了解具体问题