xfetch

xfetch

使用用户自己的登录 Cookie，而非付费开发者 API，从 X (Twitter) 获取公开数据，包括个人资料、推文、帖子串、搜索结果和关注者。此技能提供了一个独立的 CLI：scripts/xfetch.py。它会直接调用 X 的 GraphQL API，并输出 Agent 可解析的结构化数据。

保持正常运行的方式（关键架构）： X 抓取最棘手之处在于 X 会不断更改网站：每隔几周就会轮换 GraphQL 查询 ID、在 GET 和 POST 之间迁移端点，并调整响应 JSON 的结构。此 CLI 将这些问题拆开处理，因此某一处出问题时，不会导致所有功能都不可用：

• 它会复用 twikit 包附带的当前查询 ID 和功能标志（通过 pip install -U twikit 保持最新），因此你不必手动维护变化最快的值。
• 它会自行发送 HTTP 请求并解析 JSON，从而避开 twikit 中最容易随时出问题的两处：(1) 从主页抓取的反机器人事务 ID——此 CLI 会发送无害的占位符 x-client-transaction-id，X 接受它用于读取端点；(2) 响应模型层——此 CLI 会自行解析原始 JSON。如果端点返回 404，它还会自动在 GET 和 POST 之间回退，因此即使 X 迁移了端点，功能仍可正常使用。

总之：如果某条命令突然对所有人报错，首先仍应运行 pip install -U twikit（刷新查询 ID）。如果这没有帮助，说明 X 更改了响应结构——请检查 scripts/xfetch.py 中的解析器。

面向 Agent 的约定

scripts/xfetch.py 专为循环调用而设计，行为可预测。请依靠以下三个渠道，而不是抓取说明文字：

• stdout 仅包含数据载荷（默认为 JSON）。可将其重定向或通过管道传输——不会向其中写入其他内容。
• stderr 包含面向用户的状态信息（✓ Saved…）和错误。读取它以诊断问题；解析数据时请忽略它。
• 退出代码 是判断结果的依据：0 = 成功，1 = 错误，2 = 未通过身份验证，3 = 请求受限（stderr 会包含 rate_limit_reset=<epoch>），64 = 用法错误（标志或参数有误——请修正命令，而不是重新进行身份验证）。请根据退出代码分支判断，而不是依据 stderr 文本。

设置（每个环境仅需一次）

1. 确认 Python 并安装 twikit（使用虚拟环境最为妥当，这样不会影响系统包）：

   python3 -m pip install -r scripts/requirements.txt   # installs twikit>=2.3.3
   

2. 验证 CLI 是否能加载：

   python3 scripts/xfetch.py --version    # -> xfetch-skill 0.3
   

调用每条命令时，使用此技能自带的脚本，以 python3 scripts/xfetch.py <command> … 的形式执行。

请先完成身份验证——这是最常见的故障原因

每条数据命令都需要用户的 X Cookie（auth_token + ct0）。没有它们，命令会向 stderr 输出 Not authenticated.，并以 2 退出。身份验证采用委托方式：由用户设置一次，CLI 将会话保存到 ~/.config/xfetch/cookies.json，之后你只需复用即可——凭据生命周期不由你管理，你只需确认凭据存在。

始终先运行此命令，并根据退出码采取相应操作：

python3 scripts/xfetch.py auth check

如果尚未完成身份验证，请按以下优先顺序让用户提供凭据：

• 从已登录的浏览器提取（最方便——直接从浏览器存储中读取 x.com Cookie，无需复制粘贴）：

  python3 scripts/xfetch.py auth extract --browser chrome
  # supported: chrome, chromium, firefox, safari, edge, brave, arc, opera, vivaldi, librewolf
  

  需要 browser_cookie3（位于 requirements.txt 中）。在 macOS 上，这可能会提示访问 Keychain——这是操作系统提供 Cookie 解密密钥，属于正常情况。

• 导入 Cookie 文件（适用于没有读取器的浏览器，例如 ChatGPT Atlas、Orion 或任何 Chromium 分支浏览器）：使用“Get cookies.txt”浏览器扩展导出 Cookie（Netscape cookies.txt 和 JSON 格式均可），然后让 CLI 使用该文件——它会为你提取 auth_token + ct0：

  python3 scripts/xfetch.py auth import --file ~/Downloads/x.com_cookies.txt
  

• 粘贴 Cookie 令牌（适用于任何浏览器）：打开 DevTools → Application → Cookies → https://x.com，复制 auth_token 和 ct0 的值，然后：

  python3 scripts/xfetch.py auth set --auth-token <token> --ct0 <token>
  

• 环境变量（适用于 CI／一次性使用，不会将任何内容保存到磁盘）：

  XFETCH_AUTH_TOKEN=<token> XFETCH_CT0=<token> python3 scripts/xfetch.py user @handle
  

• 用户名／密码登录（twikit 会执行真实登录；可能触发验证码或 2FA——对于基于 TOTP 的 2FA，请传入 --totp）：

  python3 scripts/xfetch.py auth login --username <user> --password <pass>
  

切勿编造或猜测 Cookie 值。优先使用 auth set／环境变量，而非 login，以免密码经过命令行。如果缺少身份验证信息且无法获取，请停止并询问用户——没有身份验证信息就无法继续。这些操作会读取真实账户，因此该账户的登录会话是一种共享且受速率限制的资源：请勿频繁请求。

为使用者选择输出格式

默认的 json 格式会美化输出，便于人类阅读单条结果。对于需要由你或管道解析的内容，请使用 --format 明确选择格式：

格式	标志	适用场景
JSON（美化）	（默认）	检查单个对象或少量结果
JSONL	--format jsonl	大量／多页结果——每行一条记录，可追加，适合流式处理
CSV	--format csv	电子表格或快速表格分析（嵌套字段会以 JSON 编码写入单元格）
SQLite	--format sqlite --db out.db	构建可查询的数据集；行会写入 tweets／users 表，摘要会输出到 stderr

添加 --plain 可输出紧凑的单行 JSON。可以通过重定向 stdout 保存到文件，例如 … --format jsonl > tweets.jsonl。

命令

# Profile (by @handle or numeric id)
python3 scripts/xfetch.py user @elonmusk

# A user's tweets (--replies for replies, --media for media-only)
python3 scripts/xfetch.py tweets @elonmusk -n 50
python3 scripts/xfetch.py tweets @elonmusk --replies --all --format jsonl > timeline.jsonl

# A user's liked tweets
python3 scripts/xfetch.py likes @handle -n 40

# Single tweet, and a tweet with its replies (thread)
python3 scripts/xfetch.py tweet https://x.com/user/status/1234567890
python3 scripts/xfetch.py thread 1234567890

# Search (--type top|latest|media)
python3 scripts/xfetch.py search "AI agents" -n 100 --type latest
python3 scripts/xfetch.py search "from:openai since:2024-01-01" --all --format csv > openai.csv

# Followers / following, paginated into a SQLite dataset
python3 scripts/xfetch.py followers @handle --all --format sqlite --db network.db
python3 scripts/xfetch.py following @handle -n 100

# Your own timelines (uses the logged-in account)
python3 scripts/xfetch.py home              # "For You"
python3 scripts/xfetch.py home --following  # chronological
python3 scripts/xfetch.py bookmarks -n 50

search 支持 X 的高级运算符（from:、to:、since:、until:、filter:、min_faves: 等）——将它们放在带引号的查询中传入。如需查看完整的标志参考以及每条命令返回的确切字段，请阅读 references/commands.md。

此 CLI 为保持精简，不提供私信、列表和趋势命令，但 twikit 支持这些功能（get_dm_history、get_list_tweets、get_trends）——如果用户需要，可按照 scripts/xfetch.py 中的现有模式添加命令。

分页和速率限制

列表命令（tweets、search、followers、following、likes、home、bookmarks）共用以下标志——默认只获取一页，如需更多页面，请启用相应选项：

-n 40            # results per page
--all            # every page until exhausted
--max-pages 10   # cap the pages
--cursor <c>     # start from a specific pagination cursor
--delay 1.5      # seconds between pages (default 1.0 — keep it >0 for --all)

如果还有更多页面，或者获取过程中途被中断或受到速率限制，CLI 会将 next_cursor=<value> 输出到 stderr。捕获该值并通过 --cursor 传回，即可从中断处准确继续获取，而不是从头重新获取。

X 会对每个账户实施速率限制（每个端点每 15 分钟大约可请求几百次），此工具使用的是用户的真实账户。批量获取时，请设置合理的 --delay；如果只需要样本，请优先使用 --max-pages 而不是 --all；并请记住，过于激进的抓取可能导致账户受到限流或被标记。进行更大规模的操作时，可通过代理路由：--proxy http://user:pass@host:port。

出错时的处理方法

检查退出代码，然后阅读 stderr，以判断错误类型：

• 退出代码 2 / Not authenticated → 按照上文运行身份验证流程。
• 退出代码 64 / 用法错误 → 命令行本身有误（标志未知或值无效）。修正调用方式——不要重新运行身份验证。
• 退出代码 3 / 受到速率限制 → stderr 中会包含 rate_limit_reset=<epoch>；请等到该时间，增大 --delay，然后从 stderr 输出的 next_cursor= 值处继续。
• 退出代码 1，且出现突然影响所有人的 GraphQL / 解析错误 → X 可能更改了其网站。升级 twikit（pip install -U twikit）并重试。
• 获取过程中途出现超时 / 网络错误 → 从 stderr 中的 next_cursor= 行继续，而不是从头重新获取。
• 结果为空 → 该账户可能是私密账户（你只能查看已登录账户可见的内容）、已被暂停，或者账号名有误。

使用范围与负责任使用提示

此工具会读取公开数据，以及已登录账户能够查看的内容（其主页时间线、书签和点赞）。它不会发布内容、点赞、关注或修改任何内容——这是一个只读工具。由于它使用的是用户自己的会话，用户有责任遵守 X 的服务条款和速率限制。请将其用于正当用途——例如研究、个人归档，以及监控用户有权查看的账户——不要用于骚扰、大规模监控或规避屏蔽。会话 Cookie 存储在 ~/.config/xfetch/ 下；使用 auth clear 清除。