# Markdown Proxy

> Fetch any URL as clean Markdown via bb-browser site (real browser login), proxy services (r.jina.ai / defuddle.md), or built-in scripts. Works with login-required pages like X/Twitter, WeChat 公众号, Feishu/Lark docs, Weibo, Zhihu, Bilibili, Xiaohongshu, Reddit, etc. Use this BEFORE agent-fetch, defuddle CLI, or WebFetch when the URL might need authentication or when you want the cleanest markdown output. Triggers on any URL the user shares, "fetch this", "read this link", "get content from". Supports 35+ platforms via bb-browser site adapters with real browser login state.

- Skill: `liangdabiao/markdown-proxy` (Agent Skill, multi-file: 7 files)
- Install (CLI): `npx skillmds@latest add liangdabiao/markdown-proxy`
- Raw SKILL.md: https://api.skillmd.com/api/skills/liangdabiao/markdown-proxy/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: AI & ML
- Author: liangdabiao (https://skillmd.com/u/liangdabiao)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/liangdabiao/markdown-proxy

---


# Markdown Proxy - URL to Markdown

将任意 URL 转为干净的 Markdown。支持需要登录的页面和专有平台。

## URL 路由规则（先判断再执行）

收到 URL 后，先判断类型，不同类型走不同通道：

| URL 特征 | 路由到 | 原因 |
|----------|--------|------|
| `twitter.com` / `x.com` | **bb-browser site**（`twitter/thread`、`twitter/user`、`twitter/search`） | 用真实浏览器登录态，内容最完整 |
| `reddit.com` | **bb-browser site**（`reddit/thread`、`reddit/posts`） | Reddit 需登录，bb-browser 直接用浏览器 |
| `weibo.com` / `weibo.cn` | **bb-browser site**（`weibo/post`、`weibo/user`、`weibo/hot`） | 微博需要登录态 |
| `zhihu.com` | **bb-browser site**（`zhihu/question`、`zhihu/hot`、`zhihu/search`） | 知乎需要登录态 |
| `bilibili.com` | **bb-browser site**（`bilibili/video`、`bilibili/search`） | B站需要登录态 |
| `xiaohongshu.com` | **bb-browser site**（`xiaohongshu/note`、`xiaohongshu/search`） | 小红书 Pinia store 方式，零逆向 |
| `github.com` | **bb-browser site**（`github/repo`、`github/issues`） | GitHub 登录态可用 |
| `mp.weixin.qq.com` | **Playwright MCP**（`browser_navigate` + `browser_snapshot`） | 公众号有反爬，用 MCP 浏览器抓取最可靠 |
| `feishu.cn` / `larksuite.com`（文档/知识库） | 内置 `scripts/fetch_feishu.py` | 需要飞书 API 认证 |
| `youtube.com` / `youtu.be` | **bb-browser site**（`youtube/video`、`youtube/transcript`）或 `yt-search-download` skill | YouTube 有多种方式 |
| 其他所有 URL | 代理服务级联（见下方） | |

**bb-browser site 支持的完整平台列表**（35+ 平台，95+ 命令）：

搜索引擎：`google/search`、`baidu/search`、`bing/search`、`duckduckgo/search`、`sogou/weixin`
社交媒体：`twitter/*`、`reddit/*`、`weibo/*`、`xiaohongshu/*`、`jike/*`、`hupu/hot`
视频：`youtube/*`、`bilibili/*`
技术开发：`github/*`、`stackoverflow/search`、`hackernews/*`、`npm/search`、`pypi/*`、`arxiv/search`、`csdn/search`、`cnblogs/search`、`devto/search`、`v2ex/*`
财经：`xueqiu/*`、`eastmoney/*`、`yahoo-finance/quote`
知识：`wikipedia/*`、`zhihu/*`
新闻：`bbc/news`、`reuters/search`、`toutiao/*`、`36kr/newsflash`
求职：`boss/*`、`linkedin/*`
娱乐：`douban/*`、`imdb/search`、`genius/search`、`qidian/search`
其他：`youdao/translate`、`ctrip/search`、`smzdm/search`、`gsmarena/search`、`producthunt/today`、`openlibrary/search`

运行 `bb-browser site list` 查看所有可用命令。

## 代理服务优先级

| 优先级 | 服务 | URL 模式 | 优势 |
|--------|------|----------|------|
| 1 | **r.jina.ai** | `https://r.jina.ai/{url}` | 免费、无需 API key，内容较完整 |
| 2 | **Firecrawl** | `https://api.firecrawl.dev/v2/scrape` 或 `firecrawl` CLI | JS 渲染、结构化提取、metadata 丰富，需 API key |
| 3 | **defuddle.md** | `https://defuddle.md/{url}` | 免费、输出干净，带 YAML frontmatter |
| 4 | `agent-fetch` | npx agent-fetch | 本地工具，无需网络代理 |
| 5 | `defuddle` CLI | defuddle parse | 本地 CLI，适合普通网页 |

## Workflow

### Step 0: URL 类型判断

```
# 1) bb-browser site 优先（支持 35+ 平台，使用真实浏览器登录态）
if URL matches a bb-browser supported platform:
    → Step C: bb-browser site 抓取
    → 如果 bb-browser 失败（未安装/未登录），继续下面的判断

# 2) 公众号
if URL contains "mp.weixin.qq.com":
    → Step A: 公众号抓取
    → 结束

# 3) 飞书文档
if URL contains "feishu.cn/docx/" or "feishu.cn/wiki/" or "feishu.cn/docs/" or "larksuite.com/docx/":
    → Step B: 飞书文档抓取
    → 结束

# 4) 通用代理
else:
    → 继续 Step 1
```

**bb-browser 平台 URL 匹配规则：**

| URL 特征 | bb-browser 命令 |
|----------|-----------------|
| `twitter.com/*/status/*` 或 `x.com/*/status/*` | `bb-browser site twitter/thread "URL"` |
| `twitter.com/<user>` 或 `x.com/<user>` | `bb-browser site twitter/user <user>` |
| `reddit.com/r/*/comments/*` | `bb-browser site reddit/thread "URL"` |
| `weibo.com/*/status/*` 或 `weibo.cn/*/status/*` | 从 URL 提取 post ID → `bb-browser site weibo/post <id>` |
| `weibo.com/u/*` | `bb-browser site weibo/user <uid>` |
| `zhihu.com/question/*` | 从 URL 提取 question ID → `bb-browser site zhihu/question <id>` |
| `bilibili.com/video/*` | 从 URL 提取 BV ID → `bb-browser site bilibili/video <bvid>` |
| `xiaohongshu.com/explore/*` 或 `xiaohongshu.com/discovery/item/*` | 从 URL 提取 note ID → `bb-browser site xiaohongshu/note <id>` |
| `github.com/<owner>/<repo>` | `bb-browser site github/repo <owner>/<repo>` |
| `github.com/<owner>/<repo>/issues/*` | `bb-browser site github/issues <owner>/<repo>` |
| `youtube.com/watch*` 或 `youtu.be/*` | 从 URL 提取 video ID → `bb-browser site youtube/video <id>` |
| 用户要求搜索/热榜等非 URL 场景 | 直接用对应 adapter（如 `bb-browser site zhihu/hot`） |

### Step C: bb-browser site 抓取（新增）

使用 bb-browser 的社区 site adapter，通过真实浏览器登录态获取结构化数据。

**前置检查：**

```bash
# 检查 bb-browser 是否已安装
bb-browser --version
# 如果未安装，跳过此步骤，回退到后续路由

# 更新 adapter（首次使用或定期）
bb-browser site update
```

**执行命令：**

```bash
# 通用格式
bb-browser site <platform/command> [args] --json

# Twitter
bb-browser site twitter/thread "https://x.com/user/status/123456" --json
bb-browser site twitter/user elonmusk --json
bb-browser site twitter/search "AI agent" --json

# Reddit
bb-browser site reddit/thread "https://reddit.com/r/programming/comments/..." --json

# 微博
bb-browser site weibo/post <post_id> --json
bb-browser site weibo/hot --json
bb-browser site weibo/user <uid> --json

# 知乎
bb-browser site zhihu/question <question_id> --json
bb-browser site zhihu/hot --json
bb-browser site zhihu/search "RAG" --json

# B站
bb-browser site bilibili/video BV1xx411c7 --json
bb-browser site bilibili/search "编程" --json

# 小红书
bb-browser site xiaohongshu/note <note_id> --json
bb-browser site xiaohongshu/search "穿搭" --json

# GitHub
bb-browser site github/repo epiral/bb-browser --json
bb-browser site github/issues epiral/bb-browser --json

# YouTube
bb-browser site youtube/video dQw4w9WgXcQ --json
bb-browser site youtube/transcript dQw4w9WgXcQ --json

# 搜索引擎
bb-browser site google/search "query" --json
bb-browser site baidu/search "query" --json

# 其他常用
bb-browser site hackernews/top 10 --json
bb-browser site stackoverflow/search "python async" --json
bb-browser site douban/movie <id> --json
bb-browser site xueqiu/stock 贵州茅台 --json
```

**用 `--jq` 内联过滤关键字段：**

```bash
bb-browser site twitter/search "AI" --jq '.[] | {text: .text, author: .author.userName, likes: .likeCount}'
bb-browser site xueqiu/hot-stock 5 --jq '.items[] | {name, changePercent}'
```

**JSON → Markdown 转换：**

bb-browser 返回结构化 JSON，需要转换为 Markdown：
1. 提取关键字段（title、author、content/text、date 等）
2. 组装为 Markdown 格式，包含 YAML frontmatter
3. 列表类数据用 Markdown 表格或列表展示
4. 长文本内容保留原始格式

**错误处理：**

```
如果 bb-browser 未安装（command not found）:
    → 提示用户: npm install -g bb-browser
    → 回退到后续路由步骤

如果返回 HTTP 401:
    → 提示用户: 请先在浏览器中登录 <platform>，然后重试
    → 回退到后续路由步骤

如果返回其他错误:
    → 回退到后续路由步骤（代理服务级联）
```

### Step A: 公众号文章抓取（Playwright MCP）

使用 Playwright MCP 工具直接在浏览器中打开页面并提取内容，无需本地安装 Playwright/Chromium。

**步骤：**

1. **导航到页面**：调用 `mcp__playwright__browser_navigate` 打开公众号 URL
2. **获取快照**：调用 `mcp__playwright__browser_snapshot` 获取页面的 accessibility tree
3. **提取内容**：从 snapshot 中提取标题（heading）、作者、日期、正文段落（paragraph）、图片（img src）、代码块（code）、引用（blockquote）、列表（list）等元素
4. **转为 Markdown**：将提取的结构化内容手动组装为 Markdown，包括：
   - YAML frontmatter（title, author, date, url, source）
   - 正文中的图片保留原始 URL（`![](img_url)`）
   - 代码块用 ` ``` ` 包裹
   - 引用用 `>` 标记
   - 列表用 `-` 标记
5. **关闭页面**：调用 `mcp__playwright__browser_close` 关闭标签页
6. **失败回退**：如果 MCP 不可用，回退到 `scripts/fetch_weixin.py` 或 Step 1-2 代理服务

**无额外依赖**，Playwright MCP 由 Claude Code 环境提供。

### Step B: 飞书文档抓取（内置）

```bash
python3 ~/.claude/skills/markdown-proxy/scripts/fetch_feishu.py "FEISHU_URL"
```

依赖：`requests`（标准库级别），环境变量 `FEISHU_APP_ID` + `FEISHU_APP_SECRET`
支持：docx 文档、doc 文档、wiki 知识库页面（自动解析实际文档 ID）
输出：YAML frontmatter（title, document_id, url）+ Markdown 正文
支持 `--json` 参数输出 JSON 格式。

### Step 1: 优先用 r.jina.ai

```bash
curl -sL "https://r.jina.ai/{original_url}" 2>/dev/null
```

如果返回非空且包含实际内容，使用此结果。

### Step 1.5: 如果 Jina 内容不够好，用 Firecrawl（需 API key）

Firecrawl 提供 JS 渲染、结构化提取和丰富的 metadata，适合 Jina 抓不到或内容不完整的情况。

**前置条件：** 环境变量 `FIRECRAWL_API_KEY`（免费 500 credits，无需信用卡）

**方式 A：API 调用（无需安装）**

```bash
curl -s -X POST "https://api.firecrawl.dev/v2/scrape" \
  -H "Authorization: Bearer $FIRECRAWL_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"url": "{original_url}"}' | jq -r '.data.markdown // .data.html'
```

**方式 B：Firecrawl CLI**

```bash
# 安装
npm install -g firecrawl

# 基础抓取（默认输出 Markdown）
firecrawl scrape "{original_url}"

# 只提取正文（去除导航、页脚、广告）
firecrawl scrape "{original_url}" --only-main-content

# 等待 JS 渲染（SPA 页面）
firecrawl scrape "{original_url}" --wait-for 3000

# 多格式输出 + 保存到文件
firecrawl scrape "{original_url}" --format markdown,links -o output.md

# 指定 HTML 标签提取
firecrawl scrape "{original_url}" --include-tags article,main
firecrawl scrape "{original_url}" --exclude-tags nav,aside,.ad
```

**Firecrawl API 返回结构：**

```json
{
  "success": true,
  "data": {
    "markdown": "...",
    "html": "...",
    "metadata": {
      "title": "...",
      "description": "...",
      "language": "...",
      "ogTitle": "...",
      "ogDescription": "...",
      "ogImage": "...",
      "sourceURL": "...",
      "statusCode": 200
    }
  }
}
```

提取 Markdown 时用 `jq -r '.data.markdown'`，提取标题用 `jq -r '.data.metadata.title'`。

### Step 2: 如果 Jina 和 Firecrawl 都失败，用 defuddle.md

```bash
curl -sL "https://defuddle.md/{original_url}" 2>/dev/null
```

### Step 3: 如果所有代理都失败，回退本地工具

```bash
# agent-fetch: https://github.com/teng-lin/agent-fetch
npx agent-fetch "{original_url}" --json
# 或
defuddle parse "{original_url}" -m -j
```

### Step 4: 展示内容（必做）

抓取成功后，**必须**按以下格式向用户展示：

```
**标题**: {title}
**作者**: {author}（如有）
**来源**: {source_type}（公众号 / 飞书文档 / 网页等）
**URL**: {original_url}

### 内容摘要
{前 3-5 句话的摘要}

### 正文
{完整 Markdown 内容，超长时截取前 200 行并注明"内容已截取，完整版已保存到 xxx"}
```

### Step 5: 保存文件（默认执行）

将抓取的 Markdown 内容保存到本地：

```
默认保存路径：~/Downloads/{title}.md
文件格式：YAML frontmatter（title, author, date, url, source）+ Markdown 正文
```

- 文件名用文章标题，去掉特殊字符
- 如果用户指定了其他保存路径，按用户要求
- 保存后告知用户文件路径
- 如果用户明确说"不用保存"或只是快速预览，可以跳过

## Examples

### X/Twitter 帖子
```bash
# 优先用 bb-browser（需要浏览器已登录 Twitter）
bb-browser site twitter/thread "https://x.com/username/status/1234567890" --json

# 回退：代理服务
curl -sL "https://r.jina.ai/https://x.com/username/status/1234567890"
```

### 微博热搜
```bash
bb-browser site weibo/hot --json
```

### 知乎热榜
```bash
bb-browser site zhihu/hot --json
```

### B站视频
```bash
bb-browser site bilibili/video BV1xx411c7 --json
bb-browser site bilibili/search "编程" --json
```

### 小红书笔记
```bash
bb-browser site xiaohongshu/note <note_id> --json
```

### GitHub 仓库
```bash
bb-browser site github/repo epiral/bb-browser --json
```

### 普通网页
```bash
curl -sL "https://r.jina.ai/https://example.com/article"
```

### 公众号文章
```
1. mcp__playwright__browser_navigate → "https://mp.weixin.qq.com/s/abc123"
2. mcp__playwright__browser_snapshot → 获取页面结构
3. 从 snapshot 提取标题、作者、日期、正文 → 组装 Markdown
4. mcp__playwright__browser_close
```

### 飞书文档
```bash
python3 ~/.claude/skills/markdown-proxy/scripts/fetch_feishu.py "https://xxx.feishu.cn/docx/xxxxxxxx"
```

### 飞书知识库
```bash
python3 ~/.claude/skills/markdown-proxy/scripts/fetch_feishu.py "https://xxx.feishu.cn/wiki/xxxxxxxx"
```

## Notes

- **bb-browser site**（优先）：支持 35+ 平台，使用真实浏览器登录态，结构化 JSON 输出。需 `npm install -g bb-browser` + Chrome 扩展。支持 `--json` 输出和 `--jq <expr>` 内联过滤。未安装时自动回退到代理服务
- **Firecrawl**：专业级网页抓取服务，支持 JS 渲染、结构化提取、丰富 metadata。免费 500 credits（无需信用卡），之后按量付费。支持自部署（AGPL-3.0）。环境变量 `FIRECRAWL_API_KEY`，或 CLI `npm install -g firecrawl`
- r.jina.ai 和 defuddle.md 均免费、无需 API key
- 公众号文章优先使用 Playwright MCP（`browser_navigate` + `browser_snapshot`），无需本地安装 Playwright/Chromium
- 如果 Playwright MCP 不可用，回退到 `scripts/fetch_weixin.py`（需 `pip install playwright beautifulsoup4 lxml` + `playwright install chromium`）
- 飞书文档使用内置 API 脚本（需环境变量 `FEISHU_APP_ID` + `FEISHU_APP_SECRET`）
- 飞书脚本自动将 blocks 转为 Markdown（标题、列表、代码块、引用、待办等）
- 对于超长内容，可用 `| head -n 200` 先预览
- bb-browser 也可用于搜索/热榜等非 URL 场景，如 `bb-browser site zhihu/hot`、`bb-browser site google/search "query"`
- bb-browser MCP 接入方式：`npx -y bb-browser --mcp`（可配置在 settings.json 中）