feedgrab：给一个 URL，还你结构化内容

我见过太多叫”万能抓取器”的项目了，名字起得响亮，实际支持的平台掰着手指头数得完，碰到反爬直接趴窝。feedgrab 不一样——它确实做到了”给任意 URL，返回结构化 Markdown”，而且对 X/Twitter 做了六级兜底，这个深度在开源项目里很少见。

这篇文章把 feedgrab 拆开讲：能干什么、怎么装、怎么用、哪些地方有坑。

feedgrab 到底能抓什么？

覆盖 17 个以上平台，文章、视频、播客、推文、论坛帖子、知识库文档、付费墙内容都支持。抓完统一输出带 YAML front matter 的 Markdown，按平台分子目录存放。

按类型分：

• 文章类：微信公众号（搜狗搜索 + MP 后台 API 按账号批量 + 专辑批量）、知乎专栏、Medium、HackerNews、Reddit、微博、付费新闻网站（NYT/WSJ/FT/Economist/Bloomberg/SCMP 等 300+ 站，7 级付费墙绕过）
• 视频/音频：YouTube（InnerTube API，零依赖零 quota）、B 站（字幕 3 级兜底）、小宇宙（__NEXT_DATA__ SSR 提取 + Groq Whisper 转录）、喜马拉雅（Web Revision API + Whisper 转录）
• 社交平台：X/Twitter（六级兜底）、小红书（API + Pinia Store 注入 + 浏览器三级策略）、抖音（CDP 复用 Chrome + SSR RENDER_DATA 解析）
• 知识库/文档：飞书（Open API + CDP + Playwright + 知识库递归批量）、金山文档（ProseMirror DOM + 虚拟滚动）、FlowUs 息流（Notion 风格 block-tree 渲染）、有道云笔记
• 开发者平台：GitHub（REST API，中文 README 优先 + 子目录语言链接搜索 + 相对图片链接补全）、LinuxDo/IDCFlare（Discourse 论坛，JSON API → CDP → 浏览器 → Jina 四级降级）、Telegram（Telethon）
• 付费内容：知识星球（talk/question+answer/article/solution 五形态 topic 覆盖，短链 302 解析，评论三态控制）
• 任意网页：JSON-LD 前置探测 → Jina Reader 兜底

你平时读的东西，基本都能抓。

三种用法，按需选一层

feedgrab 分三个层级，单独用或组合都行。

层级	干什么	怎么装
Python CLI/库	基础内容抓取，统一数据结构	pip install 必装
Claude Code 技能	视频转录 + AI 内容分析	npx skills add iBigQiang/feedgrab
MCP 服务器	把阅读能力暴露给 MCP 协议客户端	克隆仓库后 python mcp_server.py

大多数人从 CLI 开始就够了。日常用 Claude Code 做内容分析的话，装上技能层会让视频转录变得顺滑——yt-dlp 拉字幕，拉不到就走 Groq Whisper 兜底，整个流程自动触发，不用手动切工具。MCP 服务器适合需要把”读网页”作为工具暴露给 AI Agent 的场景，暴露了 read_url、read_batch、list_inbox、detect_platform 四个工具。

Claude Code 技能层包含五个技能：/feedgrab 核心抓取、/feedgrab-batch 批量抓取、/feedgrab-setup 安装引导、/analyze 多维度结构化分析报告、video 自动触发的视频转录。安装后在 Claude Code 里直接发 URL，对应技能自动匹配触发。

X/Twitter 的六级兜底为什么值得单独讲

抓 X/Twitter 内容是 feedgrab 最硬核的部分。很多工具拿到一条推文链接，要么用 oEmbed 拿段纯文本，要么直接起浏览器渲染，数据完整度和速度都不理想。feedgrab 做了六级降级链：

层级	方式	要不要认证	能拿到什么
0	GraphQL API	要 Cookie	完整线程、图片、视频、引用推文、长文章、全部互动数据
0.3	FxTwitter API	不要	文本、图片、视频、互动数据（含 views/bookmarks）、Article 全文
0.5	Syndication API	不要	文本、图片、视频、部分互动数据（likes/replies）
1	oEmbed API	不要	单条推文纯文本
2	Jina Reader	不要	个人主页、非推文页面
3	Playwright	可选 session	最后兜底，需要登录的内容

有 Cookie 时走 Tier 0 GraphQL，数据最全。Cookie 过期了不会直接崩——先降级到 FxTwitter（第三方公共 API，无需认证，数据完整度接近 GraphQL，连续 3 次失败触发 circuit breaker 跳过），再降级到 Syndication（缺 retweets/bookmarks/views 三项，但正文和媒体都在）。到 oEmbed 那一层只剩纯文本了，至少不会返回空。

FxTwitter 这一层我一开始觉得多余，后来发现实际价值很大：Cookie 全部失效的情况下，用户不需要立刻重新登录，仍能拿到 80% 的数据。批量抓书签时某个账号被 429 限流，自动切到 FxTwitter 继续跑，比直接报错中断好太多了。

Tier 0 GraphQL 层的能力继承了宝玉的 baoyu-danger-x-to-markdown 技能，包括动态 queryId 解析（从 X 前端 JS bundle 中提取）、完整线程重建（作者自回复链）、多阶段分页（向上+向下+续页）、全部媒体提取、互动数据全量采集。在此基础上 feedgrab 又加了书签批量、用户推文批量、列表推文批量、浏览器搜索补充（突破 UserTweets 约 800 条限制，自动按月分片）、全局去重索引。

配置 Twitter Cookie 的四种方式

GraphQL 层需要 auth_token 和 ct0 两个 Cookie 值。优先级从高到低：

环境变量（最高优先级，设了就覆盖其他来源）——从浏览器 DevTools 手动复制，写入 .env：

X_AUTH_TOKEN=你的值
X_CT0=你的值

Playwright session——feedgrab login twitter 弹浏览器，登录完存到 sessions/twitter.json，这是最省事的方式。

Cookie 文件——手动创建 sessions/x.json，格式同上。

Chrome CDP 自动提取——Chrome 已登录状态下，CHROME_CDP_LOGIN=true feedgrab login twitter 秒提 Cookie，不用再开浏览器窗口。前提是 Chrome 开了 chrome://inspect/#remote-debugging。

多账号轮换防限流

批量抓推文时 GraphQL 容易触发 429。在 sessions/ 下放多个 Cookie 文件就能自动轮换：

sessions/
├── twitter.json    ← 主账号（feedgrab login twitter 自动生成）
├── x_2.json        ← 第二个账号（手动创建，格式同上）
├── x_3.json        ← 第三个

从浏览器 DevTools（F12 → Application → Cookies → https://x.com）复制 auth_token 和 ct0 填进去就行。Cookie 不绑定 IP 和设备，跨电脑用没问题。429 时自动切到下一个没被限流的账号，15 分钟冷却后自动恢复。

TwitterAPI.io 付费 API：服务器部署的替代方案

推文超过 800 条时，默认方案是自动起浏览器按月分片搜索补充。服务器没桌面环境的话这不现实。配了 TWITTERAPI_IO_KEY 后走付费 API 替代，$0.15/千条，无推文数量限制，有断点续传（发现阶段实时写缓存，中断后重跑不重复消耗额度）。

TWITTERAPI_IO_KEY=your_api_key
X_API_PROVIDER=api          # 全量走付费 API，无需 Cookie 和浏览器
X_API_SAVE_DIRECTLY=false   # false=GraphQL 补全媒体（推荐），true=直接保存快但无图片

还支持按点赞数/转发数/阅读量过滤（三项 OR 关系），在 .env 里设 X_API_MIN_LIKES、X_API_MIN_RETWEETS、X_API_MIN_VIEWS。

几个平台的具体抓取策略

不同平台的反爬强度和数据结构差异很大，feedgrab 对每个平台都做了针对性设计。

B 站字幕的三级兜底：先走 /x/player/v2 接口拿字幕，失败后走 /x/player/wbi/v2（需要 WBI 签名），都拿不到才降级到 Whisper 转录。和 YouTube 共享 Whisper 管线。

小红书四级策略：单篇抓取优先走 xhshow API（无需登录，完整元数据+评论），API 不可用时降级到 Pinia Store 注入（在浏览器里执行原生请求，不依赖第三方签名库，XHS_PINIA_ENABLED=true 默认开启），再降级到 Jina，最后 Playwright。关键词搜索（xhs-so）和作者主页批量同样走这个链路。

飞书的虚拟目录树：知识库批量抓取时，飞书的文档可能嵌套在多级目录下，还可能有懒加载的 Sheet。feedgrab 做了虚拟目录树抓取、懒加载 Sheet 预热、/sheet/block 合并、重复单元格错列处理。抓取链路是 Open API → CDP 直连 → Playwright PageMain → Jina。

知识星球的五形态 topic：talk（普通帖子）、question+answer（问答）、article（长文章）、solution（解决方案），每种形态的数据结构不同，feedgrab 全部覆盖。短链 t.zsxq.com/<code> 自动 302 解析。评论支持三种模式：none（不抓）、all（全部）、author（仅作者本人）。

FlowUs 息流的 block-tree 渲染：公开分享链接零 Cookie 直接抓（走纯 HTTP /api/docs/{uuid}），付费/私有文档需要 next_auth+next_auth.sig 双 Cookie。渲染层面做了 8 类 block + 5 种 enhancer + 链接片段的 Notion 风格 block-tree 解析。图片本地化时 headless 浏览器渲染抓 cdn2.flowus.cn 签名 URL 后直拉。

付费墙七级绕过：JSON-LD 探测 → Googlebot/Bingbot UA → AMP 页面 → archive.today → Google Cache。不是每个站都能绕过，但 300+ 站点的覆盖面够用。

Discourse 论坛（LinuxDo/IDCFlare）：优先走 Discourse Topic JSON API，Cloudflare 严格校验时降级到 CDP 复用 Chrome 的 Cookie/会话，再降级到 Playwright 页面内 fetch，最后 Jina。回复模式可切：author（主贴+楼主自回）、all（完整楼层）、none（仅主贴）。

安装：从零到能用

# 基础安装
pip install git+https://github.com/iBigQiang/feedgrab.git

# 推荐：带隐身浏览器 + TLS 指纹（patchright + browserforge + curl_cffi）
pip install "feedgrab[stealth] @ git+https://github.com/iBigQiang/feedgrab.git"
patchright install chromium

[stealth] 额外依赖的反检测能力最强。如果需要 Twitter 搜索增强（x-so 命令的 x-client-transaction-id 签名）装 [twitter]，小红书 API 增强（xhs-so 的 xhshow 签名）装 [xhs]。嫌麻烦直接 [all] 全装。

装完跑一次引导：

feedgrab setup

五步：环境检查 → 配置文件生成 → UA 检测 → 平台登录 → 功能启用。每步可跳过，重复跑自动跳过已完成项。

视频/音频转录额外需要 yt-dlp 和 ffmpeg：

# macOS
brew install yt-dlp ffmpeg

# Linux
pip install yt-dlp
apt install ffmpeg

Whisper 转录需要 Groq API Key，免费申请：

export GROQ_API_KEY=your_key_here

CLI 日常用法

单条抓取：

feedgrab https://mp.weixin.qq.com/s/abc123

PowerShell 里 URL 含 & 会报错，用 feedgrab clip 从剪贴板读 URL 绕开。批量传多个 URL 也行：feedgrab https://url1.com https://url2.com。

几个典型的批量场景：

小红书搜索（无需登录，走 xhshow API）：

feedgrab xhs-so "AI Agent" --sort popular --type video --limit 50
feedgrab xhs-so "claude code,openclaw,养龙虾" --merge   # 多关键词合并一个表格
feedgrab xhs-so "claude code,openclaw"                     # 分别生成表格

Twitter 搜索（按互动量排序的汇总表格）：

feedgrab x-so openclaw                                        # 最近1天+中文+最新tab
feedgrab x-so "AI Agent" --days 7 --min-faves 50 --sort top   # 自定义参数
feedgrab x-so "梯子,VPN,v2ray,小火箭" --merge                  # 多关键词合并

YouTube 搜索和下载：

feedgrab ytb-so "AI Agent" --channel @AndrewNg --order viewCount
feedgrab ytb-dlv https://www.youtube.com/watch?v=xxx   # 下载视频 MP4
feedgrab ytb-dla https://www.youtube.com/watch?v=xxx   # 下载音频 MP3
feedgrab ytb-dlz https://www.youtube.com/watch?v=xxx   # 下载字幕 SRT

微信公众号按账号批量（需先 feedgrab login wechat）：

feedgrab mpweixin-id "饼干哥哥AGI"
MPWEIXIN_ID_SINCE=2025-01-01 feedgrab mpweixin-id "饼干哥哥AGI"

飞书知识库递归抓取：

feedgrab feishu-wiki https://xxx.feishu.cn/wiki/ABC123
FEISHU_DOWNLOAD_IMAGES=true feedgrab feishu-wiki https://xxx.feishu.cn/wiki/ABC123

媒体文件下载到本地：

X_DOWNLOAD_MEDIA=true feedgrab https://x.com/user/status/123
XHS_DOWNLOAD_MEDIA=true feedgrab https://www.xiaohongshu.com/explore/xxx
MPWEIXIN_DOWNLOAD_MEDIA=true feedgrab https://mp.weixin.qq.com/s/xxx

Twitter 还支持自定义媒体文件名（X_MEDIA_FILENAME_PATTERN），支持 {date} {screen_name} {tweet_id} {num} {ext} 等占位符。

一键诊断和清理：

feedgrab doctor        # 全平台检查 Cookie、依赖、queryId、网络
feedgrab doctor x      # Twitter 专项
feedgrab reset bookmarks/OpenClaw   # 重置某目录（删 .md + 清去重索引）
feedgrab clean-index --yes          # 清理批量记录和缓存，保留去重索引

输出长什么样

每条内容一个独立 Markdown 文件，按平台分目录：

output/
├── X/                  # 推文、书签、搜索结果
│   ├── status/         #   单篇
│   ├── status_xxx/     #   用户推文（按 display_name）
│   ├── bookmarks/      #   书签
│   └── search/         #   搜索结果（.md + .csv）
├── XHS/                # 小红书
├── mpweixin/           # 微信公众号
├── YouTube/            # YouTube
├── GitHub/             # GitHub 仓库
├── Bilibili/           # B 站
└── ...

文件名带作者、日期、标题。Twitter 的 front matter：

---
title: "OpenClaw新手完整学习路径"
source: "https://x.com/AI_Jasonyu/status/123"
author:
  - "@AI_Jasonyu"
author_name: "鱼总聊AI"
published: 2026-02-25
created: 2026-02-26
cover_image: "https://pbs.twimg.com/media/xxx.jpg"
likes: 1075
retweets: 315
replies: 41
bookmarks: 2180
views: 426321
tags:
  - "clippings"
  - "twitter"
---

小红书多 collects（收藏数）、location、item_id。GitHub 多 stars、forks、language、license、repo_created、readme_file。不同平台的 front matter 字段按其数据结构定制，不是机械套同一个模板。

设了 OBSIDIAN_VAULT 环境变量，内容直接写到 Obsidian 笔记库对应的平台子目录。

当 Python 库用

不想走 CLI，在代码里直接调：

import asyncio
from feedgrab.reader import UniversalReader

async def main():
    reader = UniversalReader()
    content = await reader.read("https://mp.weixin.qq.com/s/abc123")
    print(content.title)
    print(content.content[:200])

asyncio.run(main())

新项目建议用 FetchService，返回结构化 FetchResult，content 是 UnifiedContent，artifacts 记录生成的 Markdown 路径：

import asyncio
from feedgrab.service import FetchService

async def main():
    service = FetchService()
    result = await service.fetch_url("https://github.com/iBigQiang/feedgrab")
    print(result.content.title)
    for artifact in result.artifacts:
        print(artifact.kind, artifact.path)

asyncio.run(main())

CLI 命令、MCP 服务器都走同一层 service。批量抓取时单个 URL 失败不会吞掉整批结果——这个设计在跑大批量时很关键，不用因为一条链接挂了就重跑全部。代理配置（FEEDGRAB_PROXY_*）也在 service 设置层统一暴露。

几个容易忽略的细节

代理配置：FEEDGRAB_PROXY_ENABLED=true 加 FEEDGRAB_PROXY_URL=http://127.0.0.1:7890 开启全局代理。FEEDGRAB_NO_PROXY 默认排除 127.0.0.1,localhost，防止本地 CDP 和内部服务被代理拦截。这个默认值很合理，很多人配了代理后发现 CDP 连不上，就是没注意这条。

UA 检测：首次部署跑 feedgrab detect-ua，自动检测本机 Chrome UA 写入 .env。很多平台反爬第一道就是 UA，用真实 Chrome UA 比手动编一个靠谱得多。

Twitter 被作者隐藏的回复：X_FETCH_MODERATED_REPLIES=true 可以抓取 ModeratedTimeline 里的隐藏回复，但仅作者本人 Cookie 可见。

转推者/点赞者列表：feedgrab x-retweeters https://x.com/.../status/... 输出 MD + CSV，按粉丝数倒序排列。也支持直接传 tweet_id。点赞者列表注意作者可能隐藏了点赞信息。

Twitter 人物搜索：feedgrab x-so "AI Agent" --people 走 SearchTimeline 的 product=People，按粉丝倒序。

知识星球和 FlowUs 的登录：推荐 CHROME_CDP_LOGIN=true feedgrab login zsxq（或 flowus），直接从已运行的 Chrome 提取 Cookie，比弹 Playwright 浏览器手动扫码方便得多。

金山文档的 CDP 降级：默认走 CDP 模式复用 Chrome 登录态，Chrome 没运行时自动降级到 Launch 模式。也可以 KDOCS_CDP_ENABLED=false 强制 Launch。

FORCE_REFETCH：设为 true 时跳过去重索引，强制重新抓取并覆盖已有文件。调试或内容更新后重抓时有用。

实用操作清单

• [ ] pip install "feedgrab[all] @ git+https://github.com/iBigQiang/feedgrab.git" 全量安装
• [ ] patchright install chromium 装隐身浏览器
• [ ] feedgrab setup 跑引导流程
• [ ] feedgrab detect-ua 检测并写入 Chrome UA
• [ ] 按需执行 feedgrab login twitter / feedgrab login xhs 等
• [ ] feedgrab https://某个URL 测试单条抓取
• [ ] 按需在 .env 中配置开关和参数
• [ ] 如需 Whisper 转录，配置 GROQ_API_KEY
• [ ] 如需 Obsidian 集成，配置 OBSIDIAN_VAULT
• [ ] 如需代理，配置 FEEDGRAB_PROXY_ENABLED 和 FEEDGRAB_PROXY_URL

一页速览

feedgrab 是一个开源万能内容抓取器，输入任意 URL，输出带 YAML front matter 的结构化 Markdown。核心亮点：X/Twitter 六级兜底（GraphQL → FxTwitter → Syndication → oEmbed → Jina → Playwright），小红书三级策略（API → Pinia → 浏览器），付费墙七级绕过。支持 CLI、Python 库、Claude Code 技能、MCP 服务器四种使用方式。批量抓取有全局去重索引、断点续传、多 Cookie 轮换防限流。输出兼容 Obsidian，可直接写入笔记库。项目在 runes_leo 的 x-reader 和宝玉的 baoyu-danger-x-to-markdown 基础上融合升级，MIT 协议。

FAQ

feedgrab 和 Jina Reader 有什么区别？

Jina Reader 是 feedgrab 的兜底层之一。feedgrab 在 Jina 之上做了平台检测、专用 API 调用、多级降级、批量抓取、去重索引、媒体下载、结构化输出。Jina 只负责”把网页转 Markdown”这一步。

不配置 Twitter Cookie 能用吗？

能用，自动降级到 FxTwitter 或 Syndication，拿到正文和媒体，但拿不到 likes/views/bookmarks 等互动数据，书签批量、用户推文批量等功能也用不了。

批量抓推文被 429 限流怎么办？

配多个账号的 Cookie 文件（x_2.json、x_3.json）自动轮换，或用 TwitterAPI.io 付费 API（TWITTERAPI_IO_KEY），完全不依赖 Cookie 和浏览器。

小红书抓取需要登录吗？

单篇和 xhs-so 搜索不需要，走 xhshow API。作者主页批量需要 feedgrab login xhs 登录一次。API 不可用时自动降级到 Pinia Store 注入，再降级到 Jina。

输出能直接导入 Obsidian 吗？

设 OBSIDIAN_VAULT 指向 Obsidian 笔记库路径，内容直接写入对应平台子目录，YAML front matter 兼容 Obsidian 属性面板。

服务器上没有桌面环境能用吗？

能用。大部分平台走 API 层不需要浏览器。需要浏览器的场景（如 Twitter 搜索补充）可配 TwitterAPI.io 付费 API 替代，或设 X_API_PROVIDER=api 全量走付费 API。

Whisper 转录收费吗？

Groq Whisper API 有免费额度，从 Groq 控制台申请 Key 即可。yt-dlp 字幕提取不依赖任何付费服务。

feedgrab doctor 能查什么？

检查 Cookie 是否有效、依赖是否齐全、Twitter queryId 能否正常解析、网络连通性。支持全平台检查和单平台专项（feedgrab doctor x、feedgrab doctor xhs 等）。

feedgrab reset 和 feedgrab clean-index 有什么区别？

reset 针对特定子目录，扫描 .md 文件的 YAML front matter 提取 item_id，从去重索引移除后删除文件。clean-index 清理索引目录中除全局去重索引（item_id_url.json）以外的批量记录和 API 断点缓存，释放磁盘空间。

GitHub 仓库抓取需要 Token 吗？

无 Token 60 次/小时，有 Token 5000 次/小时。设 GITHUB_TOKEN 即可。抓取时会自动检测中文 README（优先根目录，再搜子目录的语言链接），补全相对图片链接。

图片来源：Unsplash