x-fetcher

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

X Fetcher

抓取 X (Twitter) 帖子内容的命令行工具，支持普通推文和 X Article 长文章，自动保存为 Markdown 格式。

工程化来源: 本 Skill 基于 Jane-xiaoer/x-fetcher 项目。

A command-line tool for fetching X (Twitter) post content, supporting regular tweets and X Article long-form articles, and automatically saving as Markdown format.

Engineering Source: This Skill is based on the Jane-xiaoer/x-fetcher project.

功能

Features

抓取普通推文（文字、图片、视频链接）
抓取 X Article 长文章（完整正文，Markdown 格式）
获取互动数据（点赞、转发、浏览量、书签数）
自动保存为格式化的 Markdown 文件
可配置默认下载目录

Fetch regular tweets (text, images, video links)
Fetch X Article long-form articles (full content in Markdown format)
Get interaction data (likes, retweets, views, bookmark counts)
Automatically save as formatted Markdown files
Configurable default download directory

Script Directory

脚本位于

scripts/

子目录。

路径解析:

```
SKILL_DIR
```
= 此 SKILL.md 文件所在目录
脚本路径 =
```
${SKILL_DIR}/scripts/main.py
```

Scripts are located in the

scripts/

subdirectory.

Path Resolution:

```
SKILL_DIR
```
= Directory where this SKILL.md file is located
Script path =
```
${SKILL_DIR}/scripts/main.py
```

Preferences (EXTEND.md)

使用 Bash 检查 EXTEND.md 是否存在（优先级顺序）:

bash

undefined

Use Bash to check if EXTEND.md exists (priority order):

bash

undefined

首先检查项目级

Check project-level first

test -f .x-fetcher/EXTEND.md && echo "project"

然后检查用户级（跨平台：$HOME 适用于 macOS/Linux/WSL）

Then check user-level (cross-platform: $HOME works for macOS/Linux/WSL)

test -f "$HOME/.x-fetcher/EXTEND.md" && echo "user"


┌────────────────────────────────────┬───────────────────┐
│                路径                │     位置          │
├────────────────────────────────────┼───────────────────┤
│ .x-fetcher/EXTEND.md               │ 项目目录          │
├────────────────────────────────────┼───────────────────┤
│ $HOME/.x-fetcher/EXTEND.md         │ 用户主目录        │
└────────────────────────────────────┴───────────────────┘

┌───────────┬───────────────────────────────────────────────────────────────────────────┐
│  结果     │                                  动作                                     │
├───────────┼───────────────────────────────────────────────────────────────────────────┤
│ 已找到    │ 读取、解析、应用设置                                                       │
├───────────┼───────────────────────────────────────────────────────────────────────────┤
│ 未找到    │ **必须**运行首次设置（见下文）— **不要**静默创建默认值                       │
└───────────┴───────────────────────────────────────────────────────────────────────────┘

**EXTEND.md 支持**: 默认下载目录 | 媒体处理方式

test -f "$HOME/.x-fetcher/EXTEND.md" && echo "user"


┌────────────────────────────────────┬───────────────────┐
│                Path                │     Location      │
├────────────────────────────────────┼───────────────────┤
│ .x-fetcher/EXTEND.md               │ Project directory │
├────────────────────────────────────┼───────────────────┤
│ $HOME/.x-fetcher/EXTEND.md         │ User home directory │
└────────────────────────────────────┴───────────────────┘

┌───────────┬───────────────────────────────────────────────────────────────────────────┐
│  Result   │                                  Action                                    │
├───────────┼───────────────────────────────────────────────────────────────────────────┤
│ Found     │ Read, parse, and apply settings                                           │
├───────────┼───────────────────────────────────────────────────────────────────────────┤
│ Not found │ **Must** run initial setup (see below) — **Do not** silently create defaults │
└───────────┴───────────────────────────────────────────────────────────────────────────┘

**EXTEND.md Support**: Default download directory | Media handling method

首次设置（阻塞式）

Initial Setup (Blocking)

关键: 当未找到 EXTEND.md 时，在创建 EXTEND.md 之前，你必须使用
AskUserQuestion
询问用户的偏好。绝不要在未询问的情况下创建带有默认值的 EXTEND.md。这是一个阻塞式操作 — 在设置完成之前不要继续进行任何转换。

在一次调用中使用

AskUserQuestion

提出所有问题：

问题 1 — header: "下载目录", question: "推文保存的默认目录路径？"

"x-fetcher（推荐）" — 保存到 ./x-fetcher/{username}/{tweet-id}.md
（用户可以选择 "Other" 来输入自定义路径）

问题 2 — header: "保存位置", question: "偏好设置保存到？"

"用户（推荐）" — ~/.x-fetcher/（所有项目）
"项目" — .x-fetcher/（仅此项目）

用户回答后，在所选位置创建 EXTEND.md，确认 "偏好设置已保存到 [path]"，然后继续。

Key: When EXTEND.md is not found, you must use
AskUserQuestion
to ask the user for preferences before creating EXTEND.md. Never create EXTEND.md with default values without asking. This is a blocking operation — do not proceed with any conversion until setup is complete.

Use

AskUserQuestion

in one call to ask all questions:

Question 1 — header: "Download Directory", question: "Default directory path for saving tweets?"

"x-fetcher (Recommended)" — Save to ./x-fetcher/{username}/{tweet-id}.md
(User can select "Other" to enter a custom path)

Question 2 — header: "Save Location", question: "Where to save preferences?"

"User (Recommended)" — ~/.x-fetcher/ (all projects)
"Project" — .x-fetcher/ (this project only)

After the user answers, create EXTEND.md at the selected location, confirm "Preferences saved to [path]", then proceed.

支持的配置键

Supported Configuration Keys

键	默认值	可选值	描述
`default_output_dir`	空	路径或空	默认输出目录（空 = `./x-fetcher/` ）
`auto_save`	`true`	`true` / `false`	自动保存 Markdown 文件
`download_media`	`ask`	`ask` / `true` / `false`	是否下载媒体文件到本地（ `ask` = 每次询问， `true` = 总是下载， `false` = 从不下载）

值优先级:

CLI 参数
EXTEND.md
Skill 默认值

媒体下载说明:

当
```
download_media
```
设置为
```
true
```
时，图片会保存到
```
imgs/
```
目录，视频保存到
```
videos/
```
目录
Markdown 文件中的媒体链接会自动更新为本地相对路径
支持的媒体格式：图片（jpg, png, gif, webp），视频（mp4, mov, webm）

Key	Default Value	Optional Values	Description
`default_output_dir`	Empty	Path or empty	Default output directory (empty = `./x-fetcher/` )
`auto_save`	`true`	`true` / `false`	Automatically save Markdown files
`download_media`	`ask`	`ask` / `true` / `false`	Whether to download media files locally ( `ask` = ask every time, `true` = always download, `false` = never download)

Value Priority:

CLI parameters
EXTEND.md
Skill default values

Media Download Notes:

When
```
download_media
```
is set to
```
true
```
, images are saved to the
```
imgs/
```
directory, videos to the
```
videos/
```
directory
Media links in Markdown files are automatically updated to local relative paths
Supported media formats: Images (jpg, png, gif, webp), Videos (mp4, mov, webm)

使用

Usage

bash

python3 ${SKILL_DIR}/scripts/main.py <url>
python3 ${SKILL_DIR}/scripts/main.py <url> --output /path/to/save
python3 ${SKILL_DIR}/scripts/main.py <url> --download-media
python3 ${SKILL_DIR}/scripts/main.py <url> --json

bash

python3 ${SKILL_DIR}/scripts/main.py <url>
python3 ${SKILL_DIR}/scripts/main.py <url> --output /path/to/save
python3 ${SKILL_DIR}/scripts/main.py <url> --download-media
python3 ${SKILL_DIR}/scripts/main.py <url> --json

选项

Options

选项	描述
`<url>`	推文或文章 URL
`--output <path>`	输出路径（目录或文件）
`--download-media`	下载图片/视频资源到本地 `imgs/` 和 `videos/` ，并将 Markdown 链接重写为本地相对路径
`--json`	JSON 输出（不保存 Markdown）
`--no-save`	不自动保存 Markdown 文件

Option	Description
`<url>`	Tweet or article URL
`--output <path>`	Output path (directory or file)
`--download-media`	Download image/video resources to local `imgs/` and `videos/` directories, and rewrite Markdown links to local relative paths
`--json`	Output in JSON format (do not save Markdown)
`--no-save`	Do not automatically save Markdown files

支持的 URL

Supported URLs

```
https://x.com/<user>/status/<id>
```
```
https://twitter.com/<user>/status/<id>
```

```
https://x.com/<user>/status/<id>
```
```
https://twitter.com/<user>/status/<id>
```

输出

Output

普通推文

Regular Tweet

markdown

undefined

markdown

undefined

@username 的推文

Tweet from @username

作者: Author Name (@username) 发布时间: 2024-01-01 12:00:00 原文链接: https://x.com/user/status/123

推文内容...

Author: Author Name (@username) Published: 2024-01-01 12:00:00 Original Link: https://x.com/user/status/123

Tweet content...

媒体

Media

互动数据

Interaction Data

❤️ 点赞: 1,234
🔁 转发: 567
👀 浏览: 89,000
💬 回复: 123

undefined

❤️ Likes: 1,234
🔁 Retweets: 567
👀 Views: 89,000
💬 Replies: 123

undefined

X Article 长文章

X Article Long-form Article

markdown

undefined

markdown

undefined

文章标题

Article Title

作者: Author Name (@username) 发布时间: 2024-01-01 12:00:00 修改时间: 2024-01-02 10:30:00 原文链接: https://x.com/user/status/123

完整文章内容（Markdown 格式）...

Author: Author Name (@username) Published: 2024-01-01 12:00:00 Updated: 2024-01-02 10:30:00 Original Link: https://x.com/user/status/123

Full article content (Markdown format)...

互动数据

Interaction Data

❤️ 点赞: 206,351
🔁 转发: 28,631
👀 浏览: 115,555,283
🔖 书签: 571,495


**文件结构**: `{output_dir}/{username}/{tweet-id}.md`

❤️ Likes: 206,351
🔁 Retweets: 28,631
👀 Views: 115,555,283
🔖 Bookmarks: 571,495


**File Structure**: `{output_dir}/{username}/{tweet-id}.md`

工作原理

How It Works

从 URL 提取 tweet ID
尝试 fxtwitter API（支持 Article）
备选 syndication API
解析并格式化输出
自动保存为 Markdown 文件

Extract tweet ID from URL
Try fxtwitter API (supports Articles)
Fallback to syndication API
Parse and format output
Automatically save as Markdown file

限制

Limitations

依赖第三方 API（fxtwitter），可能因服务变更而失效
私密账号的内容无法抓取
部分媒体内容可能无法获取完整 URL

Depends on third-party APIs (fxtwitter), which may fail due to service changes
Cannot fetch content from private accounts
Some media content may not have complete URLs available

依赖

Dependencies

Python 3.6+
requests >= 2.25.0

首次使用时会自动检查依赖，如果未安装会提示安装命令。

Python 3.6+
requests >= 2.25.0

Dependencies are automatically checked on first use, and installation commands will be prompted if not installed.

Extension Support

通过 EXTEND.md 支持自定义配置。有关路径和支持的选项，请参阅 Preferences 部分。

Custom configurations are supported via EXTEND.md. See the Preferences section for paths and supported options.