xurl — 代理技能参考

xurl 是用于 X API 的命令行工具。它同时支持快捷命令（人类/代理友好的单行命令）和针对任何 v2 端点的原始 curl 风格访问。所有命令都向标准输出返回 JSON。

安装

Homebrew (macOS)

brew install --cask xdevplatform/tap/xurl

npm

npm install -g @xdevplatform/xurl

Shell 脚本

curl -fsSL https://raw.githubusercontent.com/xdevplatform/xurl/main/install.sh | bash

安装到 ~/.local/bin。如果它不在你的 PATH 中，脚本会告诉你需要添加什么。

Go

go install github.com/xdevplatform/xurl@latest

先决条件

此技能需要 xurl CLI 工具：https://github.com/xdevplatform/xurl。

在使用任何命令之前，你必须完成身份验证。运行 xurl auth status 进行检查。

密钥安全（强制）

• 切勿读取、打印、解析、总结、上传或将 ~/.xurl（或其副本）发送到 LLM 上下文。
• 切勿要求用户在聊天中粘贴凭据/令牌。
• 用户必须在其自己的机器上手动将所需密钥填入 ~/.xurl。
• 不要在代理/LLM 会话中推荐或执行带有内联密钥的认证命令。
• 警告在代理会话中使用 CLI 密钥选项可能会泄露凭据（提示/上下文、日志、shell 历史记录）。
• 切勿在代理/LLM 会话中使用 --verbose / -v；它可能暴露输出中的敏感标头/令牌。
• 绝对不能在代理命令中使用的敏感标志：--bearer-token、--consumer-key、--consumer-secret、--access-token、--token-secret、--client-id、--client-secret。
• 要验证是否至少有一个已注册凭据的应用，请运行：xurl auth status。

注册应用（推荐）

应用凭据注册必须由用户在代理/LLM 会话之外手动完成。
凭据注册后，通过以下方式认证：

xurl auth oauth2

对于多个预配置的应用，可在它们之间切换：

xurl auth default prod-app          # 设置默认应用
xurl auth default prod-app alice    # 设置默认应用 + 用户
xurl --app dev-app /2/users/me      # 单次请求覆盖

其他认证方法

带有内联密钥标志的示例被有意省略。如果需要 OAuth1 或仅应用认证，用户必须在代理/LLM 上下文之外手动运行这些命令。

令牌以 YAML 格式持久化到 ~/.xurl。每个应用都有自己隔离的令牌。不要通过代理/LLM 读取此文件。一旦认证成功，下面的每个命令都会自动附加正确的 Authorization 标头。

快速参考

帖子 ID 与 URL： 上面任何出现 POST_ID 的地方，你也可以粘贴完整的帖子 URL（例如 https://x.com/user/status/1234567890）——xurl 会自动提取 ID。

用户名： 开头的 @ 是可选的。@elonmusk 和 elonmusk 都有效。

命令详情

发帖

# 简单帖子
xurl post "Hello world!"

# 带媒体的帖子（先上传，后附加）
xurl media upload photo.jpg          # → 从响应中记下 media_id
xurl post "Check this out" --media-id MEDIA_ID

# 多个媒体
xurl post "Thread pics" --media-id 111 --media-id 222

# 回复帖子（通过 ID 或 URL）
xurl reply 1234567890 "Great point!"
xurl reply https://x.com/user/status/1234567890 "Agreed!"

# 带媒体的回复
xurl reply 1234567890 "Look at this" --media-id MEDIA_ID

# 引用帖子
xurl quote 1234567890 "Adding my thoughts"

# 删除自己的帖子
xurl delete 1234567890

读取

# 读取单个帖子（返回作者、文本、指标、实体）
xurl read 1234567890
xurl read https://x.com/user/status/1234567890

# 搜索最近的帖子（默认 10 条结果）
xurl search "golang"
xurl search "from:elonmusk" -n 20
xurl search "#buildinpublic lang:en" -n 15

用户信息

# 你自己的个人资料
xurl whoami

# 查找任何用户
xurl user elonmusk
xurl user @XDevelopers

时间线与提及

# 主页时间线（按时间倒序）
xurl timeline
xurl timeline -n 25

# 你的提及
xurl mentions
xurl mentions -n 20

互动

# 点赞 / 取消点赞
xurl like 1234567890
xurl unlike 1234567890

# 转发 / 取消转发
xurl repost 1234567890
xurl unrepost 1234567890

# 书签 / 移除
xurl bookmark 1234567890
xurl unbookmark 1234567890

# 列出你的书签 / 点赞
xurl bookmarks -n 20
xurl likes -n 20

社交图谱

# 关注 / 取消关注
xurl follow @XDevelopers
xurl unfollow @XDevelopers

# 列出你关注的人 / 你的粉丝
xurl following -n 50
xurl followers -n 50

# 列出其他用户的关注/粉丝
xurl following --of elonmusk -n 20
xurl followers --of elonmusk -n 20

# 屏蔽 / 取消屏蔽
xurl block @spammer
xurl unblock @spammer

# 静音 / 取消静音
xurl mute @annoying
xurl unmute @annoying

私信

# 发送私信
xurl dm @someuser "Hey, saw your post!"

# 列出最近的私信事件
xurl dms
xurl dms -n 25

媒体上传

# 上传文件（自动检测图像/视频的类型）
xurl media upload photo.jpg
xurl media upload video.mp4

# 显式指定类型和类别
xurl media upload --media-type image/jpeg --category tweet_image photo.jpg

# 检查处理状态（视频需要服务器端处理）
xurl media status MEDIA_ID
xurl media status --wait MEDIA_ID    # 轮询直至完成

# 完整工作流程：上传后发帖
xurl media upload meme.png           # 响应包含媒体 ID
xurl post "lol" --media-id MEDIA_ID

全局标志

这些标志适用于每个命令：

原始 API 访问

快捷命令涵盖了最常见的操作。对于其他任何操作，使用 xurl 的原始 curl 风格模式——它适用于任何 X API v2 端点：

# GET 请求（默认）
xurl /2/users/me

# 带 JSON 主体的 POST
xurl -X POST /2/tweets -d '{"text":"Hello world!"}'

# PUT, PATCH, DELETE
xurl -X DELETE /2/tweets/1234567890

# 自定义标头
xurl -H "Content-Type: application/json" /2/some/endpoint

# 强制流式模式
xurl -s /2/tweets/search/stream

# 完整 URL 也有效
xurl https://api.x.com/2/users/me

流式传输

流式端点会被自动检测。已知的流式端点包括：

• /2/tweets/search/stream
• /2/tweets/sample/stream
• /2/tweets/sample10/stream

你可以使用 -s 强制在任何端点上进行流式传输：

xurl -s /2/some/endpoint

输出格式

所有命令都向标准输出返回 JSON，并带有语法高亮的美化打印。输出结构匹配 X API v2 响应格式。典型的响应如下：

{
  "data": {
    "id": "1234567890",
    "text": "Hello world!"
  }
}

错误也以 JSON 形式返回：

{
  "errors": [
    {
      "message": "Not authorized",
      "code": 403
    }
  ]
}

常见工作流程

发带图片的帖子

# 1. 上传图片
xurl media upload photo.jpg
# 2. 从响应中复制 media_id，然后发帖
xurl post "Check out this photo!" --media-id MEDIA_ID

回复对话

# 1. 读取帖子以了解上下文
xurl read https://x.com/user/status/1234567890
# 2. 回复
xurl reply 1234567890 "Here are my thoughts..."

搜索并互动

# 1. 搜索相关帖子
xurl search "topic of interest" -n 10
# 2. 点赞一个有趣的帖子
xurl like POST_ID_FROM_RESULTS
# 3. 回复它
xurl reply POST_ID_FROM_RESULTS "Great point!"

检查你的活动

# 查看你是谁
xurl whoami
# 检查你的提及
xurl mentions -n 20
# 检查你的时间线
xurl timeline -n 20

设置多个应用

# 应用凭据必须在代理/LLM 上下文之外手动配置。
# 在每个预配置的应用上认证用户
xurl auth default prod
xurl auth oauth2                       # 在 prod 应用上认证

xurl auth default staging
xurl auth oauth2                       # 在 staging 应用上认证

# 在它们之间切换
xurl auth default prod alice           # prod 应用，alice 用户
xurl --app staging /2/users/me         # 对 staging 的单次请求

错误处理

• 任何错误时退出代码非零。
• API 错误以 JSON 形式打印到标准输出（因此你仍然可以解析它们）。
• 认证错误建议重新运行 xurl auth oauth2 或检查你的令牌。
• 如果某个命令需要你的用户 ID（如点赞、转发、书签、关注等），xurl 会自动通过 /2/users/me 获取。如果失败，你会看到认证错误。

注意事项

• 速率限制： X API 对每个端点强制执行速率限制。如果收到 429 错误，请等待后重试。写入端点（发帖、回复、点赞、转发）的限制比读取端点更严格。
• 作用域： OAuth 2.0 令牌在请求时具有广泛的作用域。如果在特定操作上收到 403，你的令牌可能缺少所需的作用域——重新运行 xurl auth oauth2 以获取新令牌。
• 令牌刷新： OAuth 2.0 令牌过期时会自动刷新。无需手动干预。
• 多个应用： 每个应用都有自己的隔离凭据和令牌。在代理/LLM 上下文之外手动配置凭据，然后使用 xurl auth default 或 --app 进行切换。
• 多个账户： 你可以为每个应用认证多个 OAuth 2.0 账户，并使用 --username / -u 在它们之间切换，或使用 xurl auth default APP USER 设置默认账户。
• 默认用户： 当未提供 -u 标志时，xurl 使用活动应用的默认用户（通过 xurl auth default 设置）。如果未设置默认用户，则使用第一个可用的令牌。
• 令牌存储： ~/.xurl 是 YAML 格式。每个应用存储自己的凭据和令牌。切勿读取或将此文件发送到 LLM 上下文。