x-fetcher
X Fetcher
抓取 X (Twitter) 帖子内容的命令行工具，支持普通推文和 X Article 长文章，自动保存为 Markdown 格式。
工程化来源: 本 Skill 基于 Jane-xiaoer/x-fetcher 项目。
功能
- 抓取普通推文（文字、图片、视频链接）
- 抓取 X Article 长文章（完整正文，Markdown 格式）
- 获取互动数据（点赞、转发、浏览量、书签数）
- 自动保存为格式化的 Markdown 文件
- 可配置默认下载目录
Script Directory
脚本位于 scripts/ 子目录。
路径解析:
SKILL_DIR= 此 SKILL.md 文件所在目录- 脚本路径 =
${SKILL_DIR}/scripts/main.py
Preferences (EXTEND.md)
使用 Bash 检查 EXTEND.md 是否存在（优先级顺序）:
# 首先检查项目级
test -f .x-fetcher/EXTEND.md && echo "project"
# 然后检查用户级（跨平台：$HOME 适用于 macOS/Linux/WSL）
test -f "$HOME/.x-fetcher/EXTEND.md" && echo "user"
┌────────────────────────────────────┬───────────────────┐ │ 路径 │ 位置 │ ├────────────────────────────────────┼───────────────────┤ │ .x-fetcher/EXTEND.md │ 项目目录 │ ├────────────────────────────────────┼───────────────────┤ │ $HOME/.x-fetcher/EXTEND.md │ 用户主目录 │ └────────────────────────────────────┴───────────────────┘
┌───────────┬───────────────────────────────────────────────────────────────────────────┐ │ 结果 │ 动作 │ ├───────────┼───────────────────────────────────────────────────────────────────────────┤ │ 已找到 │ 读取、解析、应用设置 │ ├───────────┼───────────────────────────────────────────────────────────────────────────┤ │ 未找到 │ 必须运行首次设置（见下文）— 不要静默创建默认值 │ └───────────┴───────────────────────────────────────────────────────────────────────────┘
EXTEND.md 支持: 默认下载目录 | 媒体处理方式
首次设置（阻塞式）
关键: 当未找到 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]"，然后继续。
支持的配置键
| 键 | 默认值 | 可选值 | 描述 |
|---|---|---|---|
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）
使用
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
选项
| 选项 | 描述 |
|---|---|
<url> |
推文或文章 URL |
--output <path> |
输出路径（目录或文件） |
--download-media |
下载图片/视频资源到本地 imgs/ 和 videos/，并将 Markdown 链接重写为本地相对路径 |
--json |
JSON 输出（不保存 Markdown） |
--no-save |
不自动保存 Markdown 文件 |
支持的 URL
https://x.com/<user>/status/<id>https://twitter.com/<user>/status/<id>
输出
普通推文
# @username 的推文
> 作者: **Author Name** (@username)
> 发布时间: 2024-01-01 12:00:00
> 原文链接: https://x.com/user/status/123
---
推文内容...
## 媒体
---
## 互动数据
- ❤️ 点赞: 1,234
- 🔁 转发: 567
- 👀 浏览: 89,000
- 💬 回复: 123
X Article 长文章
# 文章标题
> 作者: **Author Name** (@username)
> 发布时间: 2024-01-01 12:00:00
> 修改时间: 2024-01-02 10:30:00
> 原文链接: https://x.com/user/status/123
---
完整文章内容（Markdown 格式）...
---
## 互动数据
- ❤️ 点赞: 206,351
- 🔁 转发: 28,631
- 👀 浏览: 115,555,283
- 🔖 书签: 571,495
文件结构: {output_dir}/{username}/{tweet-id}.md
工作原理
- 从 URL 提取 tweet ID
- 尝试 fxtwitter API（支持 Article）
- 备选 syndication API
- 解析并格式化输出
- 自动保存为 Markdown 文件
限制
- 依赖第三方 API（fxtwitter），可能因服务变更而失效
- 私密账号的内容无法抓取
- 部分媒体内容可能无法获取完整 URL
依赖
- Python 3.6+
- requests >= 2.25.0
首次使用时会自动检查依赖，如果未安装会提示安装命令。
Extension Support
通过 EXTEND.md 支持自定义配置。有关路径和支持的选项，请参阅 Preferences 部分。