x-twitter-api

使用经过身份验证用户自己的开发者凭据（OAuth 1.0a，按使用付费）的 X（Twitter）API v2 技能。所有命令都通过单一入口运行：node x.js <command> [flags]。每条命令都有自己的文档文件，其中包含完整的标志和行为参考。

[!SETUP] 首次使用前，检查 ./node_modules 是否存在。如果不存在，则运行 npm install。然后检查 ./dist/x.js 是否存在。如果不存在，则运行 npm run build。绝不要切换到技能目录；使用相对路径或 --prefix 指定目标目录，无需更改当前工作目录。

[!COMMANDS]

核心： a) me — 经过身份验证用户自己的账户数据（个人资料、指标、验证状态）。@docs/me.md。 b) search — 按查询搜索帖子（最近 7 天或完整档案）。@docs/search.md。 c) get — 按 ID 获取一个或多个帖子。@docs/get.md。 d) post — 创建推文、回复或引用推文。@docs/post.md。 e) delete — 删除经过身份验证用户发布的帖子。@docs/delete.md。

互动： f) like — 点赞指定推文 ID 的帖子。@docs/like.md。 g) unlike — 取消点赞帖子。@docs/like.md。 h) repost — 转发帖子（转推）。@docs/repost.md。 i) unrepost — 取消转发。@docs/repost.md。

社交： j) user — 按用户名或 ID 查找用户。@docs/user.md。 k) follow — 按用户名或 ID 关注用户。@docs/follow.md。 l) unfollow — 取消关注用户。@docs/follow.md。 m) followers — 列出某用户的粉丝。@docs/followers.md。 n) following — 列出某用户关注的账户。@docs/followers.md。

信息流： o) timeline — 你的主页时间线（按时间倒序）。@docs/timeline.md。 p) mentions — 提及你的帖子。@docs/mentions.md。

书签： q) bookmark — 为帖子添加书签。@docs/bookmark.md。 r) unbookmark — 移除书签。@docs/bookmark.md。 s) bookmarks — 列出你的书签。@docs/bookmark.md。

管理： t) mute — 屏蔽用户。@docs/mute.md。 u) unmute — 取消屏蔽用户。@docs/mute.md。 v) muted — 列出已屏蔽的账户。@docs/mute.md。 w) blocked — 列出已封锁的账户。@docs/blocked.md。 x) hide-reply — 隐藏对你帖子的回复。@docs/hide-reply.md。

分析： y) likers — 点赞帖子的用户。@docs/likers.md。 z) reposters — 转发帖子的用户。@docs/reposters.md。 aa) quotes — 某帖子的引用推文。@docs/quotes.md。 ab) count — 按时间统计符合查询条件的帖子数量。@docs/count.md。 ac) reposts-of-me — 其他用户转发你的帖子。@docs/reposts-of-me.md。

发现： ad) search-users — 按查询搜索用户。@docs/search-users.md。 ae) trending — 热门话题（全球或个性化）。@docs/trending.md。

[!PARAMETERS]

核心：

• me：无参数
• search：query:string，[max_results?:number, since?:date, until?:date]
• get：id:string | ids:string[]
• post：text:string，[reply_to?:string, quote_id?:string]
• delete：id:string

互动：

• like：id:string
• unlike：id:string
• repost：id:string
• unrepost：id:string

社交：

• user：user:string，[expansions?:string, tweet_fields?:string, user_fields?:string]
• follow：user:string
• unfollow：user:string
• followers：[user?:string, max_results?:number, pagination_token?:string]
• following：[user?:string, max_results?:number, pagination_token?:string]

信息流：

• timeline：[max_results?:number, pagination_token?:string]
• mentions：[max_results?:number, pagination_token?:string]

书签：

• bookmark：id:string
• unbookmark：id:string
• bookmarks：[max_results?:number, pagination_token?:string]

管理：

• mute：user:string
• unmute：user:string
• muted：[max_results?:number, pagination_token?:string]
• blocked：[max_results?:number, pagination_token?:string]
• hide-reply：id:string 分析：
• likers：id:string，[max_results?:number, pagination_token?:string]
• reposters：id:string，[max_results?:number, pagination_token?:string]
• quotes：id:string，[max_results?:number, pagination_token?:string]
• count：query:string，[granularity?:string, start_time?:date, end_time?:date]
• reposts-of-me：[max_results?:number, pagination_token?:string]

发现：

• search-users：query:string，[max_results?:number]
• trending：[woeid?:number]

[!OUTPUT]

所有命令均返回具有标准结构的 JSON：

{
  "success": boolean,
  "data": object | array | string,
  "error": string | null
}

示例：

• 单个对象：{"success": true, "data": {...}, "error": null}
• 数组响应：{"success": true, "data": [...], "error": null}
• 错误响应：{"success": false, "data": null, "error": "Error description"}

[!ERRORS]

标准错误代码：

• 400 - 错误请求：参数无效或请求格式错误
• 401 - 未授权：凭据无效或已过期
• 403 - 禁止访问：访问被拒绝或权限不足
• 404 - 未找到：资源不存在
• 429 - 请求过多：超出速率限制
• 500 - 内部服务器错误：X API 服务错误
• 502 - 网关错误：X API 不可用
• 503 - 服务不可用：X API 过载

错误处理：

• 速率限制错误包含 retry-after 标头
• 身份验证错误需要刷新凭据
• 验证错误会指出具体字段问题

[!RATE-LIMITS]

X API v2 速率限制（OAuth 1.0a）：

• 用户身份验证：每 15 分钟 50 次请求
• 应用身份验证：每 15 分钟 450 次请求（所有用户共享）
• POST 请求（推文、点赞等）：每 3 小时 300 次请求

最佳实践：

• 对 429 错误实施指数退避
• 尽可能缓存时间线和搜索结果
• 在支持的情况下批量发送请求

[!CREDENTIALS]

必须提供 4 个 OAuth 1.0a 变量：X_API_KEY、X_API_SECRET、X_ACCESS_TOKEN、X_ACCESS_TOKEN_SECRET。系统会从第一个提供这些变量的来源中读取：

a) 当前工作目录中的 .env.local b) 当前工作目录中的 .env c) 插件目录中的 .env.local d) 插件目录中的 .env f) 环境变量

可从 X Developer Console（Apps > Keys and tokens）获取这些变量。

安全说明：

• 切勿将凭据提交到版本控制系统
• 本地开发时使用 .env 文件
• 凭据泄露时请轮换凭据