x-twitter

使用经过身份验证的用户自己的开发者凭据（OAuth 1.0a，按使用量付费）的 X（Twitter）API v2 skill。所有命令都通过单一入口运行：node <base_directory>/x.ts <command> [flags]，Node.js 22.18 或更高版本可直接运行，无需安装或构建。每个命令都有自己的文档文件，其中包含标志和行为的完整参考。

[!OUTPUT] 每个命令都会打印一个 JSON 对象：X 的响应（将 includes 合并到 data 中），以及我们的提示，格式为 { data, meta?, errors?, hints? }。meta 和 errors 与 X 返回的内容完全一致：meta.next_token 是 --next-token 的值，errors 说明缺少内容的原因，包括与有效数据并列的部分错误。hints 是 CLI 返回的字符串数组。只有当 X 未返回任何内容时，才会省略 data。字段名称沿用 X 的名称。

[!POSTS] 每个返回帖子（get、search、thread、replies、quotes、mentions、timeline、bookmarks、reposts-of-me、me --pinned-tweet）的命令，都会像 x.com 一样以统一格式展示帖子：使用 author（id、name、username）代替 author_id；text 是人类可读的完整文本，包括长帖，并展开 t.co 链接，同时移除指向帖子自身媒体和被引用帖子的链接；media 包含 X 所描述的附加照片和视频（type、url、preview_image_url、duration_ms、variants、alt_text）；referenced_tweets 会完整嵌入被引用和转发的帖子，而被回复的帖子仍保持为 { type: "replied_to", id }，被回复用户则位于 in_reply_to_user 中。article 包含 X Article 的 title 和完整的 plain_text。对于 X 未返回的被引用帖子，会保留为 { type, id }，并由 errors 说明原因。不会请求嵌入帖子所引用的帖子：这些帖子会保留为 { type, id }，且不会产生错误；被引用帖子的链接仍会从嵌入帖子的文本中移除，使用 get <id> 可读取这些帖子。

[!COMMANDS]

核心： a) me — 经过身份验证的用户自己的账户数据（个人资料、指标、验证信息）。@docs/me.md。 b) search — 按查询条件搜索帖子。重要：默认只搜索最近 7 天；使用 --all 搜索完整存档。不要使用带有 conversation_id: 的 search 来读取帖子串或回复——应改用 thread 或 replies。@docs/search.md。 c) get — 按 ID 检索一个或多个帖子；data 始终是数组。@docs/get.md。 d) post — 创建推文、回复或引用推文。@docs/post.md。 e) delete — 删除经过身份验证的用户拥有的帖子。@docs/delete.md。 f) thread — 获取包含某帖的对话作者的帖子串：首帖以及该作者对首帖或帖子串中其他帖子的回复，按时间从早到晚排列。不包含其他人的回复，以及该作者在这些回复下的回复。对于超过 7 天的帖子串，使用 --all。@docs/thread.md。 g) replies — 获取对某帖的直接回复，按时间从近到远排列，每次一页。重要：默认只搜索最近 7 天，因此对于更早的帖子，返回的回复会不完整且不显示警告；请使用 --all。@docs/replies.md。 h) transcript — 获取帖子视频的字幕，由 X 生成；X 未为某视频发布字幕时，该视频没有字幕。@docs/transcript.md。

互动： i) like — 按推文 ID 点赞。@docs/like.md。 j) unlike — 取消对帖子的点赞。@docs/like.md。 k) repost — 转发（retweet）帖子。@docs/repost.md。 l) unrepost — 取消转发。@docs/repost.md。

社交： m) user — 按用户名或 ID 查找用户。@docs/user.md。 n) follow — 按用户名或 ID 关注用户。@docs/follow.md。 o) unfollow — 取消关注用户。@docs/follow.md。 p) followers — 列出某用户的关注者。@docs/followers.md。 q) following — 列出某用户关注的账户。@docs/followers.md。 动态： r) timeline — 你的主页时间线（按时间倒序排列，不是算法推荐的 “For you” 信息流）。结果中经过身份验证的账号自己的帖子占比很高，且无法还原 Web 客户端的 “Following” 标签页。使用 --exclude replies,retweets 可提高内容相关性。@docs/timeline.md。 s) mentions — 提及你的帖子。@docs/mentions.md。

书签： t) bookmarks — 列出你的书签。无法添加或移除书签：X 仅接受 OAuth 2.0 用户上下文来执行此类写入操作，而目前没有受支持的凭据可提供该上下文。@docs/bookmark.md。

内容管理： u) mute — 将用户设为静音。@docs/mute.md。 v) unmute — 取消将用户设为静音。@docs/mute.md。 w) muted — 列出已设为静音的账号。@docs/mute.md。 x) blocked — 列出已屏蔽的账号。@docs/blocked.md。 y) hide-reply — 隐藏对你帖子的回复。@docs/hide-reply.md。

分析： z) likers — 点赞某帖子的用户。@docs/likers.md。 aa) reposters — 转发某帖子的用户。@docs/reposters.md。 ab) quotes — 某帖子的引用推文。@docs/quotes.md。 ac) count — 统计一段时间内符合查询条件的帖子数量。@docs/count.md。 ad) reposts-of-me — 其他人转发过的你自己的帖子；此命令不包含转发者，使用 reposters <id> 可列出转发者。@docs/reposts-of-me.md。

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

社群： ag) search-communities — 按关键词（名称、描述）搜索社群。返回元数据：名称、描述、成员数、加入政策。@docs/search-communities.md。 ah) community — 按 ID 查找社群。@docs/community.md。

新闻： ai) search-news — 按查询条件搜索热门新闻。返回标题、摘要、类别、关键词和相关帖子。@docs/search-news.md。 aj) news — 按 ID 查找新闻。@docs/news.md。

账号： ak) usage — 本周期已读取的帖子数，以及项目上限。这是读取配额，而不是余额：它无法告知你是否还有资金，并且即使额度耗尽，也会正常运行。@docs/usage.md。

[!CREDENTIALS] 必须提供四个 OAuth 1.0a 变量：X_API_KEY、X_API_SECRET、X_ACCESS_TOKEN、X_ACCESS_TOKEN_SECRET。这些变量会按以下顺序从第一个提供它们的来源读取：a) 当前工作目录中的 .env.local，b) 当前工作目录中的 .env，c) 技能目录（<base_directory>）中的 .env.local，d) 技能目录中的 .env，e) 环境变量。<base_directory>/.env.example 列出了所有变量。请从 X Developer Console（Apps > Keys and tokens）获取这些变量。另有一个有条件必需的变量：X_API_BEARER_TOKEN（OAuth 2.0 App-Only Bearer Token），需从 X Developer Console（Apps > Keys and tokens > Bearer Token）生成。三个命令使用此令牌而非 OAuth 1.0a 进行身份验证，并且在发送任何请求前，如果缺少此令牌就会失败：count（始终需要，不仅在使用 --all 时需要）、trending（默认的全球分支；--personalized 仅接受用户上下文，因此不需要此令牌）和 usage。这些命令的端点（帖子计数、用量、按地点查询趋势）属于 App-Only。所有其他命令，包括全量存档搜索（search --all、thread --all、replies --all），均在 OAuth 1.0a 用户上下文中运行，因而可以返回 connection_status 和 receives_your_dm 等用户上下文字段。