twitter

Twitter / X（脚本模式）

以只读方式访问 twitterapi.io 端点。提供 13 个函数，涵盖推文、用户、关注者、回复、串文、引用推文、文章和趋势。

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

脚本用法

标准调用模式：

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"got {len(recent.get('tweets', []))} tweets")
EOF

从 URL 提取推文 ID：任何 x.com/{user}/status/{id} 或 twitter.com/{user}/status/{id} URL 的最后一个路径段就是推文 ID。请将其作为字符串传入（Python int 会导致较长 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 / 查找 cashtag 提及 → twitter_search_tweets("$SOL min_faves:50")。
• 查看热门话题 → twitter_get_trends。

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

twitterapi.io 按实际返回的条目数计费，而非按请求计费，也不受你设置的任何“max_results”影响。sc-proxy 费用 = 返回条目数 × 单位费用（推文 45 / 个人资料 54 / 关注者 45 积分；100k 积分 = $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 端点，我们的 skill 已通过 twitter_search_tweets() 提供该功能：

# Cheap polling pattern — bills only the tweets actually in the window.
# When NO new tweet exists, the call is billed as 1 item (not 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 defaults to 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。

其他成本优化方法

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

注意：twitterapi.io 还提供托管流/网络钩子产品。我们不会订阅该产品——不要使用 /oapi/x_user_stream/* 或 /oapi/tweet_filter/* 端点。对于任何账号监控需求，上述 advanced_search 轮询模式是这里唯一正确的做法。

错误处理

• 402 Credits is not enough → 上游代理额度已用尽；告知用户充值。不要重试。
• 429 → 请求频率受限；告知用户，不要自动重试。
• 404 user not found → 建议用户检查账号名拼写。

版本策略（硬性规则）

此 skill 采用脚本模式（delivery: script）。它不会注册运行时工具——Agent 必须 读取 SKILL.md，并通过 bash + python3 调用函数。旧版 tools.py / __init__.py 文件为向后兼容而保留，但不再是首选入口。

版本递增规则：

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