Paperclip

安装 TwexAPI Paperclip 插件，在 Paperclip AI Agent中实现推文搜索、资料查询、时间线与热门推文。

TwexAPI Paperclip 插件为 Paperclip AI Agent增加六个只读 Twitter/X 工具。它包装已文档化的 TwexAPI REST 路由，提供类型化工具 schema、密钥认证与可预测的 JSON 结果。

当 Paperclip AI Agent需要推文搜索、资料查询、用户搜索、时间线读取或全球热门推文且无需手写原始 HTTP 时，使用该插件。

工具

AI Agent任务	Paperclip 工具	TwexAPI 路由
搜索推文	`twexapi.search_tweets`	`POST /twitter/advanced_search/page`
读取单条推文	`twexapi.lookup_tweet`	`POST /v2/tweet/detail`
搜索用户	`twexapi.search_users`	`GET /twitter/search-user/{keyword}/{target_count}`
读取资料	`twexapi.get_user`	`GET /twitter/{screen_name}/about`
读取资料推文	`twexapi.get_user_tweets`	`POST /twitter/{screen_name}/timeline/page`
读取热门推文	`twexapi.get_trends`	`GET /twitter/global-trending/tweets`

本插件不导出粉丝或发布帖子。粉丝与发布请用 REST API、CLI 或 MCP Server。

前置条件

Node.js 18 或更新版本
Paperclip CLI（paperclipai）
来自 dashboard 的 TwexAPI API 密钥
用于 API 密钥的 Paperclip 密钥引用

安装

paperclipai plugin install @twexapi-dev/paperclip-plugin-x-api-scraper

需要可重复安装时固定当前发布版本：

paperclipai plugin install @twexapi-dev/paperclip-plugin-x-api-scraper --version 0.1.2

npm：@twexapi-dev/paperclip-plugin-x-api-scraper

源码：twexapi-dev/paperclip-plugin-x-api-scraper

配置

在 TwexAPI dashboard 创建 API 密钥，存入 Paperclip 密钥并在插件配置中引用。

设置	用途
`apiBaseUrl`	TwexAPI REST 端点。默认 `https://api.twexapi.io`。
`apiKeySecretRef`	TwexAPI API 密钥的 Paperclip 密钥引用。
`defaultTimelineCount`	默认时间线页数，1 至 100。
`defaultUserSearchCount`	默认用户搜索数量，1 至 100。
`defaultTrendCount`	默认趋势数量，1 至 100。

Paperclip 在调用时解析 API 密钥并发送 Authorization: Bearer。

示例插件配置形状：

{
  "apiBaseUrl": "https://api.twexapi.io",
  "apiKeySecretRef": "twexapi/api-key",
  "defaultTimelineCount": 20,
  "defaultUserSearchCount": 10,
  "defaultTrendCount": 20
}

切勿将 API 密钥提交到纳入源码控制的插件配置文件。

示例AI Agent任务

搜索推文

让AI Agent搜索某话题的近期帖子。插件通过 twexapi.search_tweets 调用 POST /twitter/advanced_search/page。

建议 prompt：

Search X for recent posts about "AI agents lang:en -filter:retweets".
Return tweet IDs, author usernames, text, and created_at for the top 10 results.

读取资料与时间线

Look up @openai, then read the latest timeline page.
Return username, user_id, follower count, and the 5 most recent tweet IDs.

读取全球热门推文

Get trending tweets for United States, topic Sports, content NFL.
Summarize the top themes and list 5 representative tweet IDs.

Handoff 清单

Paperclip AI Agent将结果交给下游系统时，保留稳定标识符。

数据类型	存储
推文	`tweet_id`、`text`、`author_username`、`created_at`、搜索查询
资料	`user_id`、`username`、`name`、粉丝数
趋势	国家、主题、内容标签、推文行
分页	`next_cursor`、`has_more`、原始请求参数

同一工作流中混合 Paperclip 工具与基于 MCP 的AI Agent 时，见 Agent MCP Handoff。

错误处理

状态	操作
`400`	修正工具输入。切勿原样重试。
`401`	检查 Paperclip 密钥引用与 API 密钥值。
`403`	检查账号访问与额度。
`429`	重试前退避。
`5xx`	有界退避重试。

本地开发

git clone https://github.com/twexapi-dev/paperclip-plugin-x-api-scraper.git
cd paperclip-plugin-x-api-scraper
pnpm install
pnpm check

pnpm check 运行类型检查、测试与构建。