twitter

Twitter / X（脚本模式）

对twitterapi.io端点的只读访问。13个函数涵盖推文、用户、关注者、回复、线程、引用、文章和趋势。

所有请求通过sc-proxy经由core.http_client.proxied_get发送。TWITTER_API_KEY环境变量在服务端自动注入，代理机器上无需本地密钥。

脚本使用

标准调用模式：

python3 - <<'EOF'
import sys, json
sys.path.insert(0, "/data/workspace/skills/twitter")
from exports import twitter_user_info, twitter_user_tweets

profile = twitter_user_info(username="vitalikbuterin")
print(json.dumps(profile, indent=2))

recent = twitter_user_tweets(username="vitalikbuterin")
print(f"获取到 {len(recent.get('tweets', []))} 条推文")
EOF

从URL提取推文ID：任何x.com/{user}/status/{id}或twitter.com/{user}/status/{id} URL的最后一段路径就是推文ID。将其作为字符串传递（Python整数在长ID上会丢失精度）。

函数参考（签名）

所有13个函数位于exports.py中。返回的是来自twitterapi.io的直接字典——每个端点的键不同，编写脚本前请先检查一次。

推文端点

函数	描述
twitter_search_tweets(query, cursor=None)	高级搜索。操作符：from:user、to:user、#tag、$cashtag、lang:en、has:media、has:links、is:reply、min_faves:N、since:YYYY-MM-DD、until:YYYY-MM-DD。
twitter_get_tweets(tweet_ids)	按ID获取一条或多条推文。tweet_ids = 字符串列表（也接受逗号分隔的字符串）。
twitter_tweet_replies(tweet_id, cursor=None)	推文的回复。
twitter_tweet_retweeters(tweet_id, cursor=None)	转发的用户。
twitter_tweet_thread_context(tweet_id)	完整线程上下文（父推文+直接回复）。
twitter_tweet_quote(tweet_id, cursor=None)	引用推文。
twitter_get_article(tweet_id)	长文X文章正文。
twitter_get_trends(woeid=None, country=None, category=None, limit=None)	热门话题；所有过滤器可选。

用户端点

函数	描述
twitter_user_info(username)	个人资料：简介、关注/粉丝数、推文数、认证状态。
twitter_user_tweets(username, cursor=None)	用户的最新推文。
twitter_user_followers(username, cursor=None)	粉丝列表。
twitter_user_followings(username, cursor=None)	关注的账号。
twitter_search_users(query, cursor=None)	按名称/关键词搜索用户。

username是不带@的句柄（例如"elonmusk"，而不是"@elonmusk"）。
分页：当响应包含next_cursor时，在下一次调用中将其作为cursor传回。

何时使用此技能

• 任何x.com/...或twitter.com/... URL → 从这里开始，不要使用web_fetch（Twitter会屏蔽爬虫）。
• 单条推文详情 → twitter_get_tweets([tweet_id])。
• "@user最近发了什么？" → twitter_user_tweets。
• KOL发现/股票代码提及 → twitter_search_tweets("$SOL min_faves:50")。
• 热门话题 → twitter_get_trends。

计费与成本控制（批量/定时使用前请阅读）

twitterapi.io按实际返回的项目数计费，而不是按请求次数，也不按你要求的任何"max_results"。sc-proxy收费 = 返回项目数 × 单价（推文45 / 个人资料54 / 关注者45积分；10万积分=1美元；上游3倍）。每次请求最少1个项目。

last_tweets / user_tweets陷阱： 上游/twitter/user/last_tweets端点没有页面大小参数——它总是每页最多返回20条推文。没有max_results / pageSize控制杆，twitter_user_tweets()也不接受此类参数。所以"我只需要5条"仍然会获取并计费约20条。在客户端对结果切片并不能省钱——代理端已根据上游响应计费。

⭐ 轮询"账号X的新推文" → 使用搜索，而不是last_tweets

这是最大、最常见的浪费。twitter_user_tweets()（上游last_tweets）没有页面大小参数，每次调用总是计费一整页约20条推文，即使没有新内容发布。官方twitterapi.io指南推荐使用advanced_search端点，我们的技能已将其暴露为twitter_search_tweets()：

# 廉价轮询模式——仅对窗口内的实际推文计费。
# 当没有新推文时，调用计费为1个项目（而不是20个）。
import time
since = int(last_check_unix)
until = int(time.time())
q = f"from:{handle} include:nativeretweets since_time:{since} until_time:{until}"
res = twitter_search_tweets(q)   # queryType默认为Latest

官方定价（上游；我们的代理计费3倍）：

• 找到推文 → 每条返回推文$0.00015
• 未找到推文 → 整个调用$0.00015（对比last_tweets的约20倍）

在我们的计费中，每次调用的成本差异明显：

• last_tweets → 每次调用约$0.009（每次20条推文）
• advanced_search空窗口 → 每次调用约$0.00045（1个项目）——便宜约20倍

频率与月成本（单个账号，上游）：每小时$0.11 · 每30分钟$0.22 · 每15分钟$0.43 · 每5分钟$1.30 · 每1分钟$6.48。

其他成本控制手段

• 使用get_tweets([ids]) 当ID已知时——只为这些确切的推文付费，而不是一个20条推文的页面。
• 关注者/关注按返回的个人资料计费（默认页面200 → 计费200）。仅按需分页。对于仅需ID的图谱工作，使用批量关注者ID端点（轻量级）。
• 收紧搜索查询（min_faves、since_time/until_time、lang），以减少所需页面数。

注意：twitterapi.io也销售托管流/webhook产品。我们未订阅——不要使用/oapi/x_user_stream/*或/oapi/tweet_filter/*端点。对于任何账号监控需求，上述advanced_search轮询模式是正确且唯一的方法。

错误处理

• 402 Credits is not enough → 上游代理积分耗尽；告知用户充值。不要重试。
• 429 → 频率限制；告知用户，不要自动重试。
• 404 user not found → 建议检查句柄拼写。

版本策略（硬性规定）

此技能为脚本模式（delivery: script）。它不注册运行时工具——代理必须read_file SKILL.md并通过bash + python3调用函数。遗留的tools.py / __init__.py文件保留用于向后兼容，但不再是首选入口点。

版本号规则：

• 任何签名变更、环境变量变更或sc-proxy合约变更 → MAJOR
• 新增函数、响应模式澄清 → MINOR
• 错误修复或仅文档变更 → PATCH