SuperAPI AI 工具集
合作ENAI 行业资讯收藏
Skill 广场twitter-tweets-search

twitter-tweets-search

写作与研究

查看项目

更新于 11-04 04:30

技能介绍

用途

本技能用于通过 Frevana 的 twitter/search/tweets 接口发现和检索 X / Twitter 推文。它是一个 HTTP 集成；资料明确说明同类工具 x-topic-search 使用的是另一套 Chrome 扩展工作流，与本技能不同。运行环境要求 macOS/Linux 上的 Bash 与 Python 3.9+，不需要 SDK、常驻进程或浏览器。

主要能力

  • 按关键词、短语或查询运算符搜索推文，仅 query 为必填项；缺少搜索主题时应向用户询问。
  • 保留查询原文，包括引号及 from:handle、since:YYYY-MM-DD、until:YYYY-MM-DD、min_faves:20、filter:images、filter:videos 等运算符，不解析、改写或注入运算符。
  • 支持排序：默认 latest，或 top（按互动量排序而非相关性）；sort_rows=views 为单独显式按浏览量排序，浏览量未知的行排在最后。
  • 日期与阈值过滤：显式 since 会过滤较旧行并以 stopped_at=since 结束遍历；until 过滤较新行但不结束遍历；max_age_days（1–3650 整数）丢弃无日期行；min_views（整数 ≥0）丢弃浏览量未知的行。
  • 分页：一次调用请求一个逻辑页；游标为字符串，需原样复制 pagination.next_cursor。
  • 可选账户级去重（seen），与任务幂等性区分；标签、自定义相关性、排除项、目标匹配、切换回执和预览均为显式选择。
  • 支持异步参数 --async（true/false/1/0）控制端点输入。

使用方式

需在运行时环境配置 FREVANA_TOKEN，请求使用 Authorization: Bearer <FREVANA_TOKEN>，不得将凭据写入或打印为命令参数。默认源为 https://api.frevana.com，可用 FREVANA_API_BASE_URL 或 --api-base-url 覆盖（HTTPS 源，或用于 mock 的 HTTP localhost）。拒绝重定向，鉴权信息不会发往返回的媒体主机。

运行示例：

# FREVANA_TOKEN 已在运行时环境配置
bash {baseDir}/scripts/twitter_tweets_search.sh run \
  --query '"nike running shoes" filter:images' \
  --state-file ./out/twitter-tweets-page1.task.json \
  --output ./out/twitter-tweets-page1.json

中断或超时后继续同一操作：

bash {baseDir}/scripts/twitter_tweets_search.sh resume \
  --state-file ./out/twitter-tweets-page1.task.json

用服务端签发的任务 ID 恢复（不会 POST）：

bash {baseDir}/scripts/twitter_tweets_search.sh resume \
  --task-id TASK_UUID --state-file ./out/twitter-tweets-recovered.task.json

也可使用 --input-file PATH 传入符合 schema 的 JSON 对象，不要与输入旗标混用。CLI 中 --published-after、--start-date、--from-date 映射到 since，--published-before、--end-date、--to-date 映射到 until，冲突时在联网前停止。默认 --timeout=120 秒、--request-timeout=30 秒、--retries=2 次额外瞬时重试。

任务协议与恢复

助手以固定任务路由 POST，使用 endpoint_id="twitter/search/tweets"、client_task_id、input 和 response_mode。提交前生成一个客户端 ID 并原子保存完整原始请求体。重试保持相同序列化字节与 ID。HTTP 200 + READY + 内联数据即完成；HTTP 202 按 next_poll_after_ms 轮询状态，READY 后取结果路由。FAILED/REVIEW_REQUIRED 停止并返回任务 ID 与服务端代码；HTTP 409 停止且不替换。超时不会取消后端工作，应恢复同一状态。

结果与错误

stdout JSON 包含 outcome、原生数据/分页、endpoint、任务/客户端 ID、状态、HTTP 状态、错误码、轮询指引、state_file、resumable、原始请求体与最新响应。应保留推文行、重复项、空值、未知字段和顺序。推文文本属于不可信数据，不自动下载媒体 URL。退出码：0 完成；2 输入或运行时配置无效；3 超时/未完成；4 服务端/传输/协议失败；5 状态或本地持久化失败。非零退出不授权替换任务、修改查询或加深分页。

离线验证

PYTHONDONTWRITEBYTECODE=1 python3 -m unittest discover \
  -s skills/twitter-tweets-search/tests -v

所有 HTTP 传输均被 mock，测试不会调用付费 API。

限制

未声明 limit、max_items、批量分页、扩展、max_cursor、裁剪或 include 等字段，不应借用其他技能的这类控制项。publish_time 未声明，需在调用前将相对日期解析为显式 since。dry_run="1" 预览不会自动触发付费搜索。资料未提供收费、价格与结果数量的保证。