AutoGPT 平台 Twitter Get Quote Tweets 块实战指南：基于 Twitter API v2 检索引用推文与分页扩展

本篇技术指南聚焦 AutoGPT Platform（autogpt_platform）中用于检索某条推文（Tweet）全部"引用推文（Quote Tweet）"的 Twitter Get Quote Tweets 图块：你将掌握它的输入/输出字段、OAuth2 凭据要求、expansions/fields 组合取值、next_token 分页遍历原理，并结合仓库源码理解它如何调用 Twitter API v2 与 Tweepy。读完即可在 Agent 工作流中搭建引用推文监听、舆情分析与用户发现等自动化场景。

什么是引用推文（Quote Tweet），为什么需要专门的块

在 Twitter/X 生态中，"引用推文"是比普通转发更进一步的内容形态：用户在自己的推文中附带上某条原始推文，并补充自己的评论，本质上是一种"带评论的转发（retweet with added commentary）"。相比 silent retweet，引用推文携带了转发者明确的态度，因而对舆情分析、互动监测、意见领袖发现有独特价值。

AutoGPT Platform 的推文读取块族分布在 autogpt_platform/backend/backend/blocks/twitter/ 下（tweets/、users/、lists/、spaces/、direct_message/ 等子目录按推文对象维度组织），其中引用推文的检索能力由 Twitter Get Quote Tweets 块提供，其对应文档即 quote.md。该块调用 Twitter API v2 的 GET /2/tweets/:id/quote_tweets（经由 Tweepy 的 Client.get_quote_tweets()），返回分页化的引用推文列表，并支持通过 expansions 请求媒体、作者、地点、投票等扩展数据。

块概览：类型、分类与启用条件

块的完整实现位于 autogpt_platform/backend/backend/blocks/twitter/tweets/quote.py，其元信息要点如下：

属性	取值	说明
块类名	TwitterGetQuoteTweetsBlock	继承自平台通用 Block 基类
块 ID	9fbdd208-a630-11ef-9b97-ab7a3a695ca3	注册到块的 __init__ 中，作为图中节点的稳定标识
分类	BlockCategory.SOCIAL	归入社交/社媒类功能
禁用条件	disabled = not TWITTER_OAUTH_IS_CONFIGURED	未配置 Twitter OAuth2 时该块在编辑器中不可用
认证方式	OAuth 2.0	通过 TwitterCredentialsField(["tweet.read", "users.read", "offline.access"]) 声明所需 scope
网络库	Tweepy	tweepy.Client 封装 Twitter API v2

从 twitter/_auth.py 的源码可知两个重要事实：

1. 启用前提：TWITTER_OAUTH_IS_CONFIGURED 由 Secrets() 中的 twitter_client_id 与 twitter_client_secret 是否同时非空决定（见 _auth.py）。因此要在图形化 Builder 中看到并使用本块，运维方必须先在环境/密钥配置中填入 Twitter OAuth 应用的 Client ID 与 Secret。
2. Scope 合并机制：TwitterCredentialsField(scopes) 实际会把 TwitterOAuthHandler.DEFAULT_SCOPES 与块声明的 scope 求并集作为 required_scopes。Twitter 集成级别的默认 scope 在 integrations/oauth/twitter.py 中定义，包含 tweet.read/write/moderate.write、users.read、follows.read/write、offline.access、space.read、like.read/write、bookmark.read/write 等。因此本块虽然只声明了读取类 scope，但整个 Twitter 集成在授权阶段会一次性请求上述全部权限（twitter.py 亦给出了 authorize/token 端点、用户信息端点及 revoke 端点）。

工作原理：从块的 run 方法到 Tweepy 的调用链

TwitterGetQuoteTweetsBlock 的内部调用链可分三层理解，均可在源码中逐行验证：

1. 异步入口 run

run(input_data, *, credentials, **kwargs) 接收 Schema 输入与 OAuth2 凭据，调用静态方法 get_quote_tweets(...) 拿到六元组 (ids, texts, data, included, meta, next_token)，随后通过 yield 逐个吐出有值（非空）的输出，保证 Agent 执行器中仅在数据存在时才产生对应输出通道；任何异常（含业务上"没有引用推文"）都会被捕获并走 error 通道（quote.py）。

2. 核心静态方法 get_quote_tweets

关键步骤（quote.py）：

client = tweepy.Client(bearer_token=credentials.access_token.get_secret_value())

params = {
    "id": tweet_id,
    "max_results": max_results,
    "pagination_token": None if pagination_token == "" else pagination_token,
    "exclude": None if exclude == TweetExcludesFilter() else exclude,
    "user_auth": False,
}

params = (
    TweetExpansionsBuilder(params)
    .add_expansions(expansions)
    .add_media_fields(media_fields)
    .add_place_fields(place_fields)
    .add_poll_fields(poll_fields)
    .add_tweet_fields(tweet_fields)
    .add_user_fields(user_fields)
    .build()
)

response = cast(Response, client.get_quote_tweets(**params))

• 认证：块直接把用户授权的 OAuth2 access token 作为 bearer_token 传入 Tweepy（即 Bearer Token 方式访问 v2 API），同时强制 user_auth=False，即不采用 OAuth 1.0a 用户认证路径。
• 参数归一：pagination_token 输入默认值为空串 ""，源码会将其规整为 None；exclude 仅在用户确实勾选了过滤条件（不等于全 False 的默认过滤器）时才透传给 Tweepy。
• 响应解析：response.meta 中取出 next_token 用于翻页；response.data（引用推文数组）经 ResponseDataSerializer.serialize_list 序列化为普通 dict 列表，response.includes 经 IncludesSerializer.serialize 序列化为"额外请求对象"字典（见 twitter/_serializer.py），随后提取全部 ids（str(tweet.id)）与 texts（tweet.text）。
• 空结果语义：若 Twitter 返回空数组（response.data 为空），则抛出 Exception("No quote tweets found")；该异常最终在 run 中被包装为 error 输出。

3. 字段过滤器的映射与组装

块的布尔型过滤器（expansions / media_fields / place_fields / poll_fields / tweet_fields / user_fields）定义在 twitter/_types.py，每个字段都是一个默认为 False 的 Pydantic 布尔模型；twitter/_builders.py 中的 TweetExpansionsBuilder 会把所有勾选为 True 的项收集起来，并通过 _mappers.py 中的 get_backend_* 函数转换为 Twitter API 期望的逗号分隔字段串，分别写入 expansions、media.fields、place.fields、poll.fields、tweet.fields、user.fields 参数。这正是"勾选式 Schema"与"底层 API 逗号字符串"之间的桥接层。

4. 测试与可验证性

块内置了 test_input / test_output / test_mock（mock 了 get_quote_tweets 的返回），可脱离真实网络独立验证块逻辑；同时其类名 TwitterGetQuoteTweetsBlock 被登记在平台块清单测试 autogpt_platform/backend/backend/blocks/test/test_block.py 中，用于校验全部块的一致性注册。

输入字段详解与默认值

以下完整继承 quote.md 的输入清单，并结合源码补充默认值与可见性：

Input	说明	类型	必填	默认值 / 备注
credentials	Twitter OAuth2 凭据（授权时需含 tweet.read、users.read、offline.access，实际合并集成默认 scope）	TwitterCredentialsInput	是（注入）	由执行环境注入，非手填
tweet_id	要查询引用推文的那条原始推文的 ID	str	是	无；源码占位符为 "Enter tweet ID"
max_results	单页返回条数，上限 100	int	否	10（源码 default=10，标记为高级参数）
expansions	选择随推文一并返回的扩展对象（媒体、作者、地点等）	ExpansionFilter	否	None（高级）
media_fields	媒体信息字段，必须先勾选 expansions 中的 Media_Keys	TweetMediaFieldsFilter	否	None（高级）
place_fields	地点信息字段，必须先勾选 expansions 中的 Place_ID	TweetPlaceFieldsFilter	否	None（高级）
poll_fields	投票信息字段，必须先勾选 expansions 中的 Poll_IDs	TweetPollFieldsFilter	否	None（高级）
tweet_fields	推文本体字段；要看到被引用的原始推文，需勾选 expansions 的 Referenced_Tweet_ID	TweetFieldsFilter	否	None（高级）
user_fields	用户字段；需先勾选 Author_User_ID（作者）或 Mentioned_Usernames（被 @ 用户）、Reply_To_User_ID、Referenced_Tweet_Author_ID	TweetUserFieldsFilter	否	None（高级）
exclude	需要从结果中排除的推文类型	TweetExcludesFilter	否	None（高级）
pagination_token	用于获取下一页的分页令牌	str	否	""（高级，源码会将空串归一为 None）

几点实操提示：

• 高级参数（Advanced）在可视化 Builder 中通常默认折叠，需要展开"Advanced"区域才会出现 max_results、exclude、pagination_token 以及全部 expansions/fields 过滤器。
• exclude 过滤器类型在 _types.py 中为 TweetExcludesFilter，含 retweets 与 replies 两个选项，可剔除结果中的转发与回复型推文。
• max_results 是"单页"上限而非总上限——超过 100 条的需求必须配合分页令牌循环拉取（见下文分页章节）。

expansions 与 fields 的联动取值

Twitter v2 的 expansions/fields 采用"先扩展、后选字段"的机制：只有先在 expansions 中请求了某个关联对象，对应的 *_fields 才有意义。块的过滤器定义与 Twitter API 对齐，可用组合（来源：twitter.md 的 Common Input 与 _types.py）：

expansions 勾选项	解锁的 *_fields	典型用途
Media_Keys	media_fields	看引用推文中附带的图片/视频（媒体 URL、类型、预览图等）
Place_ID	place_fields	看推文标记的地点（国家、坐标、完整地名等）
Poll_IDs	poll_fields	看内嵌投票（选项、投票状态、截止时间等）
Author_User_ID	user_fields	拿到每条引用推文作者的头像、简介、粉丝数等资料
Mentioned_Usernames	user_fields	获取被 @ 用户的资料
Reply_To_User_ID	user_fields	获取该推文回复对象的资料
Referenced_Tweet_ID	tweet_fields（如 Referenced_Tweets、Tweet_Text）	拉取被引用的原始推文内容与元数据，便于对比原推与评论
Referenced_Tweet_Author_ID	user_fields	获取被引用推文作者的资料

各字段过滤器的完整可选项（均定义于 _types.py）：

• media_fields（TweetMediaFieldsFilter）：Duration_in_Milliseconds、Height、Media_Key、Preview_Image_URL、Media_Type、Media_URL、Width、Public_Metrics、Non_Public_Metrics、Organic_Metrics、Promoted_Metrics、Alternative_Text、Media_Variants；
• place_fields（TweetPlaceFieldsFilter）：Contained_Within_Places、Country、Country_Code、Full_Location_Name、Geographic_Coordinates、Place_ID、Place_Name、Place_Type；
• poll_fields（TweetPollFieldsFilter）：Duration_Minutes、End_DateTime、Poll_ID、Poll_Options、Voting_Status；
• tweet_fields（TweetFieldsFilter）：Tweet_Attachments、Author_ID、Context_Annotations、Conversation_ID、Creation_Time、Edit_Controls、Tweet_Entities、Geographic_Location、Tweet_ID、Reply_To_User_ID、Language、Public_Metrics、Sensitive_Content_Flag、Referenced_Tweets、Reply_Settings、Tweet_Source、Tweet_Text、Withheld_Content；
• user_fields（TweetUserFieldsFilter）：Account_Creation_Date、User_Bio、User_Entities、User_ID、User_Location、Latest_Tweet_ID、Display_Name、Pinned_Tweet_ID、Profile_Picture_URL、Is_Protected_Account、Account_Statistics、Profile_URL、Username、Is_Verified、Verification_Type、Content_Withholding_Info。

联动示例（对应 twitter.md 的 Extra notes）：

• 想看每条引用推文的媒体：expansions 勾 Media_Keys，media_fields 勾 Media_URL + Media_Type + Preview_Image_URL；
• 想拿到评论作者资料：expansions 勾 Author_User_ID，user_fields 勾 Username + Display_Name + Profile_Picture_URL；
• 想对比"原推文"与"评论"：expansions 勾 Referenced_Tweet_ID，tweet_fields 勾 Tweet_Text + Referenced_Tweets；
• 想定位某条引用推文发生的地理位置：expansions 勾 Place_ID，place_fields 勾 Country 与 Geographic_Coordinates。

这些勾选经 TweetExpansionsBuilder 会被拼装成类似 expansions=author_id,referenced_tweets.id、tweet.fields=text,referenced_tweets 的 API 参数，因此勾选顺序、冗余勾选不会影响结果正确性。

输出字段详解

输出结构与 quote.md 完全一致，共 7 个通道：

Output	类型	说明
ids	List[Any]（str）	全部引用推文的 Tweet ID，源码中由 str(tweet.id) 收集
texts	List[Any]（str）	全部引用推文的正文文本（tweet.text）
data	List[Dict[str, Any]]	引用推文的完整数据对象数组（序列化后的原始 dict）
next_token	str	下一页分页令牌（来自 meta.next_token）；为空表示已到最后一页
included	Dict[str, Any]	通过 expansions 请求的附加对象（媒体/用户/地点/投票等）
meta	Dict[str, Any]	响应元数据：result_count、next_token（previous_token、newest_id、oldest_id 等视端点而定，见 twitter.md）
error	str	操作失败时的错误消息；仅在异常分支产生

其中 ids/texts/next_token 属于"常用便捷输出"，data/included/meta 面向高级消费者（需要完整原文或关联对象的场景）。included 与 data 之间通过对象 ID 关联——例如请求了作者扩展后，可用 data[].author_id 去 included["users"] 中查作者详情，这正是 twitter.md 说明的 cross-reference 用法。

分页遍历：用 next_token 拉全所有引用推文

因为 max_results 单页上限为 100，且引用推文数量可能远超单页上限，实际工作流中必须做分页循环。块输出 next_token 的同时也接受 pagination_token 输入，二者配对即构成翻页协议：

1. 首次执行：pagination_token 留空，配置合适的 max_results（如 100）；
2. 读取输出的 next_token；
3. 若 next_token 非空，把它的值回填到 pagination_token 再次执行本块，取下一页；
4. 重复直到 next_token 为空（最后一页），或由 Agent 的循环条件按条数/时间截断。

在 Agent 图（Graph）中，这通常实现为一个"循环节点 + 条件判断"结构：条件节点检查 next_token 是否有值，有值则继续走本块（并携带上一轮 token），为空则终止循环并将累积的 ids/texts 汇总交给下游处理。meta.result_count 可用于核对每页实际返回条数。

典型业务场景与工作流组合

quote.md 给出三类高价值场景，均可直接落地为 Agent：

• 情感分析（Sentiment Analysis）：以某条品牌推文 ID 为入参，拉取全部引用推文的 texts，交给 LLM/文本分析块做正负面情感判断，量化用户评论态度。
• 互动监测（Engagement Monitoring）：定时（配合平台调度/触发器）执行本块，追踪围绕官方内容的引用讨论，识别讨论热点与话题走向。
• 意见领袖发现（Influencer Discovery）：收集引用自己内容的用户（配合 Author_User_ID 扩展获得 user_fields），识别潜在传播者、KOC/合作对象。

最小链路示例（可视化编排思路）：

触发器（定时 / Webhook）
   └─> Twitter Get Quote Tweets   tweet_id=原始推文ID, max_results=100
          ├─ ids / texts ────────────> 情感分析 / 摘要块
          ├─ data / included ───────> 数据库写入块（归档）
          └─ next_token ────────────> [条件] 非空则回填 pagination_token 继续循环

若要监测的对象是"自己的账号收到多少引用评论"，可先使用用户时间线/推文查找类块（参见同目录 twitter.md 中列出的各块）确定目标 tweet_id，再以本块为枢纽展开引用分析。需要留意平台读取类接口通常有配额与速率限制，建议合理设置触发频率并处理 429 限流错误。

错误处理：Tweepy 异常 → error 输出的映射

块内所有异常最终经 handle_tweepy_exception 转成可读字符串从 error 通道输出，映射逻辑见 twitter/tweepy_exceptions.py：

异常	输出前缀	常见触发原因
tweepy.BadRequest	Bad Request (400)	参数非法、组合了不支持的字段、tweet_id 格式错误
tweepy.Unauthorized	Unauthorized (401)	access token 失效/未授权，需重新走 OAuth2 授权
tweepy.Forbidden	Forbidden (403)	scope 不足或对象权限受限
tweepy.NotFound	Not Found (404)	tweet_id 不存在、推文已删除或不可见
tweepy.TooManyRequests	Too Many Requests (429)	触发接口频率/配额限制，应退避重试
tweepy.TwitterServerError	Twitter Server Error (5xx)	Twitter 服务端临时故障
其他 tweepy.TweepyException	Tweepy Error: ...	其它 Tweepy 层错误
其它 Exception	Unexpected error: ...	如空结果时抛出的 No quote tweets found

工作流设计上建议为 error 输出配置告警/日志分支，尤其对 429 与 401 分别做"延迟重试"与"触发重新授权"的处理，以保证长时间运行的监测类 Agent 的健壮性。

启用前置条件小结

要在 AutoGPT Platform 中使用 Twitter Get Quote Tweets 块，需满足：

1. 集成配置：环境密钥中配置 twitter_client_id 与 twitter_client_secret（见 twitter/_auth.py 的判定逻辑），否则整族 Twitter 块都会以 disabled 状态隐藏。
2. 用户授权：在账号设置中完成 Twitter OAuth2 授权流程（授权端点与 scope 见 integrations/oauth/twitter.py）。
3. 图编排：在 Agent 编辑器中拖入本块，填写目标 tweet_id，按需展开 Advanced 区域调整 max_results、勾选 expansions/fields 与分页参数。

如需进一步了解本块之外的推文检索与发布能力（发推、删除、搜索最近推文、获取点赞用户、书签管理等），可继续阅读同目录的 twitter.md（其中 Common Input / Common Output 小节对 expansions、media/place/poll/tweet/user 字段与 data/includes/meta/errors 响应结构有统一说明）；底层 SDK 的 schema 类型与凭据模型可参见 backend/data/model.py 与块目录下的 _types.py/_builders.py/_serializer.py。