• AI 技能
• 人工智能
• 深度研究
• 数据分析
• 媒体生成

本指南基于 SenseNova-Skills 开源仓库中的sn-search-social-en技能，完整讲解如何通过三个独立 Python 脚本检索 Reddit 帖子、Twitter/X 推文与 YouTube 视频，涵盖凭证配置、依赖安装、全部命令行参数、统一 JSON 输出协议，并结合仓库源码剖析各平台搜索的底层实现。读完本文，你将能把这些脚本直接接入 AI 办公助手或深度研究流水线，作为英文社交舆情与社区讨论的事实来源。

技能定位与适用场景

sn-search-social-en是 SenseNova-Skills 仓库中面向英文社交平台的搜索技能（中文社交平台对应技能见 sn-search-social-cn）。仓库 README_CN.md 将其定位为"Reddit / Twitter (X) / YouTube 三个英文社交平台搜索"，适用于以下典型场景：

• 收集产品早期用户在 Reddit 子版块中的真实讨论与反馈；
• 追踪 Twitter/X 上的行业大 V、KOL 与热点话题推文；
• 检索 YouTube 上与主题强相关的视频教程、发布与会议录像；
• 在 sn-deep-research 深度研究流程中，作为 research agent 按 source category 路由的社交来源之一（文档明确列出其覆盖范围为"Reddit、Twitter/X（TikHub）、YouTube"）。

整个技能由三组脚本加一个共享工具库构成，全部位于 scripts 目录下：

凭证配置：统一写入仓库根目录 .env

API key、token 与 cookie 统一建议写在仓库根目录.env（可参照仓库根目录的 .env.example），并由 runtime 或用户在执行前加载为同名环境变量。脚本本身只从环境变量或显式 CLI 参数读取凭证，不要把真实密钥写入 skill payload、报告、日志或提交。

.env.example中与英文社交平台相关的两个变量为：

# International social platforms TIKHUB_TOKEN= YOUTUBE_API_KEY=

加载方式可以是source .env、export $(cat .env)，或交由 runtime 注入。值得注意的是，凭证读取的优先级在源码中有明确定义：search_utils.py的get_key函数实现了CLI 参数优先于环境变量的取值逻辑（search_utils.py）：

def get_key(env_var: str, cli_arg: str | None = None) -> str | None: """读取 API key：CLI 参数 > 环境变量。""" if cli_arg: return cli_arg return os.environ.get(env_var)

也就是说，直接python3 scripts/twitter_search.py "AI agents" --token xxx会优先使用命令行传入的 token；未传时才回退读取TIKHUB_TOKEN环境变量。这为临时换号、多账号测试提供了便捷通道。

依赖安装

首次运行或脚本提示缺库时，使用本技能的依赖清单安装到当前 Python 环境：

python3 -m pip install -r skills/sn-search-social-en/requirements.txt

依赖非常轻量，仅一个包（见 requirements.txt）：

httpx>=0.27

所有脚本通过sys.path导入同目录下的 search_utils.py。该模块在import httpx失败时会抛出一条指向依赖清单的明确提示（而非晦涩的 ImportError），见 search_utils.py。不要在脚本内部自动安装依赖；若安装失败、网络不可用或包不可用，应停止使用对应脚本并改用网页搜索，同时说明缺少依赖。

reddit_search.py：Reddit 帖子和讨论搜索

Reddit 搜索无需任何 API 密钥，因为脚本直接调用 Reddit 公开 JSON API（见 reddit_search.py）。命令行接口：

python3 skills/sn-search-social-en/scripts/reddit_search.py <query> [选项]

python3 skills/sn-search-social-en/scripts/reddit_search.py "machine learning projects" --limit 5 python3 skills/sn-search-social-en/scripts/reddit_search.py "async python" --subreddit python --sort top --time month --limit 5

实现原理（结合源码）：

• 全局搜索请求https://www.reddit.com/search.json；当传入--subreddit时，请求地址切换为https://www.reddit.com/r/{subreddit}/search.json，并追加restrict_sr=on参数将结果限定在指定子版块内（reddit_search.py）。
• limit会被钳制到最大 100（min(limit, 100)），避免单次请求过大；sort与t（time filter）直接透传给 Reddit API。
• 脚本自定义了有意义的User-Agent（Mozilla/5.0 (compatible; search-skill/1.0; ...)），并声明Accept: application/json——这是 Reddit 公开接口的基本礼仪要求，能显著降低被拒风险（reddit_search.py）。
• 每个结果条目会提取标题、通过 permalink 拼接的帖子 URL、被截断到 300 字符的正文摘要（_truncate(post.get("selftext", ""), 300)）、子版块名、得分score、评论数num_comments、作者、创建时间以及外部跳转链接url_overridden_by_dest（reddit_search.py）。

twitter_search.py：Twitter/X 推文搜索

Twitter/X 官方 API 门槛较高，因此该脚本通过TikHub 聚合 API获取推文数据（见 twitter_search.py）。命令行接口：

python3 skills/sn-search-social-en/scripts/twitter_search.py <query> [选项]

python3 skills/sn-search-social-en/scripts/twitter_search.py "AI agents" --limit 10 python3 skills/sn-search-social-en/scripts/twitter_search.py "LLM" --token your_tikhub_token --limit 5

实现原理（结合源码）：

• 请求目标是 TikHub 的 Twitter 搜索时间线接口，代码中定义为https://api.tikhub.io/api/v1/twitter/web/fetch_search_timeline（twitter_search.py），认证方式为Authorization: Bearer <token>。
• 若未提供 token，脚本会直接抛出带指引的ValueError：需要TIKHUB_TOKEN环境变量，并提示到 tikhub.io 注册获取（twitter_search.py）。
• 请求参数固定search_type: "Latest"（按最新推文排序），并设置了比默认更长的 30 秒超时（get_client(timeout=30, ...)），以应对 Twitter 数据接口较慢的响应（twitter_search.py）。
• 返回解析对 TikHub 的多层嵌套结构做了兼容处理（data.data可能是列表也可能是再套一层的 dict），兼容full_text与text两种正文字段、id_str与rest_id两种推文 ID 字段，最终拼出https://x.com/{screen_name}/status/{tweet_id}形式的推文链接；条目中还包含作者显示名、点赞数favorite_count、转推数retweet_count与创建时间（twitter_search.py）。

youtube_search.py：YouTube 视频搜索

YouTube 搜索使用官方YouTube Data API v3（见 youtube_search.py）。命令行接口：

python3 skills/sn-search-social-en/scripts/youtube_search.py <query> [选项]

python3 skills/sn-search-social-en/scripts/youtube_search.py "transformer explained" --limit 5 python3 skills/sn-search-social-en/scripts/youtube_search.py "python tutorial" --order viewCount --limit 10

实现原理（结合源码）：

• 请求目标是https://www.googleapis.com/youtube/v3/search，固定参数为part=snippet、type=video（只返回视频类型，过滤频道与播放列表）、maxResults=min(limit, 50)（API 单次上限 50 条）、order与key（youtube_search.py）。
• 缺少 API key 时抛出带指引的ValueError：需要YOUTUBE_API_KEY环境变量，提示到 Google Cloud Console 创建（youtube_search.py）。
• 每条结果提取视频标题、由videoId拼出的https://www.youtube.com/watch?v={video_id}播放链接、描述（作为摘要）、频道名channelTitle、发布时间与默认缩略图地址（youtube_search.py）。

统一 JSON 输出协议

三个脚本的成功与失败输出都遵循同一种标准 JSON 结构（见 SKILL.md 与 search_utils.py）：

{"success": true, "query": "...", "provider": "reddit|twitter|youtube", "items": [...], "error": null}

字段语义：

条目对象的最小公共字段为title、url、snippet，各平台再按需附加专属字段（如 Reddit 的subreddit/score/num_comments，Twitter 的favorite_count/retweet_count，YouTube 的channel/thumbnail）。make_item会自动剔除值为None、空字符串、空列表或空 dict 的字段，保证输出整洁（search_utils.py）。print_json以ensure_ascii=False、indent=2输出到 stdout，中文摘要不会被转义成\uXXXX（search_utils.py）。

这套统一协议意味着下游 Agent 只需按success → items的固定结构解析，无需区分平台差异，可直接把结果接入证据链、引用渲染或报告写作。

共享工具库 search_utils.py 源码解析

三个脚本的 CLI、HTTP 与输出逻辑均复用于同一个模块 search_utils.py，这里汇总其核心能力：

• CLI 脚手架：build_parser为所有脚本统一注入位置参数query与可选参数--limit/-n（默认 10），各平台脚本再通过add_argument追加专属参数（如--sort、--token、--order），保证参数风格一致（search_utils.py）。
• HTTP 客户端：get_client返回预配置的httpx.Client，默认超时 15 秒、默认浏览器 UA、自动跟随重定向，并允许通过headers覆盖（Reddit 脚本即借此传入自定义 User-Agent）（search_utils.py）。
• 通用入口：run_search封装了"解析参数 → 执行搜索 → 打印 JSON/出错退出"的标准流程，错误时以success=false输出并sys.exit(1)，方便上层脚本捕获（search_utils.py）。

从源码结构看，新增平台脚本只需实现一个search(query, limit, ...) -> list[dict]函数并复用上述工具即可获得统一的 CLI 与输出行为，这也是本技能便于扩展的设计要点。

错误处理与使用注意事项

• 三个脚本的main都将整个搜索过程包在try/except中，任何异常都会以标准 JSON 形式（success: false+ 错误信息）输出，而不是打印堆栈后崩溃；进程以退出码 1 结束，便于 Agent 感知失败（见 reddit_search.py 等）。
• 不要把真实密钥写入 skill payload、报告、日志或提交；.env应加入忽略列表。
• 若依赖安装失败、网络不可用或包不可用，停止使用对应脚本并改用网页搜索，并说明缺少依赖。
• Reddit 与 YouTube 走官方公开接口，稳定性较高；Twitter/X 经 TikHub 中转，接口形态可能随上游变化，返回解析已对多层级结构与字段名做了兼容处理，但使用时仍建议留意结果为空或字段缺失的情况。

在深度研究流水线中的集成方式

sn-search-social-en是 sn-deep-research 中 research agent 可调用的搜索技能之一：当研究维度涉及英文社交来源时，agent 会按 source category 路由到本技能，凭证同样从环境变量读取（推荐统一写在仓库根目录.env，复制 .env.example 后运行前加载）。这意味着你既可以在命令行手动调用三个脚本做单点检索，也可以让深度研究 Agent 自动调用它们来补齐 Reddit / Twitter(X) / YouTube 上的社区声音、KOL 观点与视频素材，并将统一 JSON 输出作为后续证据筛选与报告写作的输入。

快速上手三步走

1. 装依赖：python3 -m pip install -r skills/sn-search-social-en/requirements.txt；
2. 配凭证：在仓库根目录.env中填入TIKHUB_TOKEN（Twitter 必需）与YOUTUBE_API_KEY（YouTube 必需），Reddit 无需任何密钥，并在运行前加载为环境变量；
3. 跑搜索：按上文各脚本的参数表与示例执行，例如python3 skills/sn-search-social-en/scripts/youtube_search.py "transformer explained" --order viewCount --limit 10，解析 stdout 中的标准 JSON 即可获得结构化的英文社交平台搜索结果。

• AI 技能
• 人工智能
• 深度研究
• 数据分析
• 媒体生成