agent-web-fetch

给 AI Agent 用的网页读取工具：先用最便宜的办法，被挡住了才升级；读不到时，明确告诉你为什么。

A web-reading toolkit for AI agents: cheapest first, escalate only when blocked, and always report why a page could not be read.

English · Python 库 · CLI (awf) · MCP Server (awf-mcp) · Agent Skill (skill/SKILL.md) · MIT

作者 Yomin Ma · GitHub @mrlong0129 · 姊妹项目：wechat-article-fetcher（专门读微信公众号文章） · 项目页

Quick start for agents

不用安装、不用配置，复制一行就能用（需要 uv；默认行为零配置）：

# 1) 直接读一个网页（不安装）
uvx --from git+https://github.com/mrlong0129/agent-web-fetch awf fetch <url>
uvx --from git+https://github.com/mrlong0129/agent-web-fetch awf fetch <url> --format json   # 结构化结果

# 2) Claude Code：一行注册 MCP server
claude mcp add agent-web-fetch -- uvx --from git+https://github.com/mrlong0129/agent-web-fetch awf-mcp

Cursor：写入 ~/.cursor/mcp.json（全局）或项目里的 .cursor/mcp.json：

{
  "mcpServers": {
    "agent-web-fetch": {
      "command": "uvx",
      "args": ["--from", "git+https://github.com/mrlong0129/agent-web-fetch", "awf-mcp"]
    }
  }
}

Agent Skill（不装包也能用，Agent 会照着手册用自己的工具读网页）：

# Claude Code
mkdir -p ~/.claude/skills/agent-web-fetch && curl -fsSL https://raw.githubusercontent.com/mrlong0129/agent-web-fetch/main/skill/SKILL.md -o ~/.claude/skills/agent-web-fetch/SKILL.md
# Cursor
mkdir -p ~/.cursor/skills/agent-web-fetch && curl -fsSL https://raw.githubusercontent.com/mrlong0129/agent-web-fetch/main/skill/SKILL.md -o ~/.cursor/skills/agent-web-fetch/SKILL.md

给编码 Agent 的完整说明见 AGENTS.md。

输出长什么样

awf fetch https://mp.weixin.qq.com/s/<article-id>

---
title: "示例标题"
url: "https://mp.weixin.qq.com/s/<article-id>"
author: "示例作者"
published: "2026-10-05T23:59:51+08:00"
site_name: "示例公众号"
extraction_method: "wechat:content_noencode"
---

# 示例标题

正文（Markdown）……

读不到时，退出码为 2，stderr 里写明原因，例如 blocked_reason: login_required，以及每一步尝试了什么。

Related MCP server: markfetch-mcp

为什么要做这个

大多数给大模型用的"网页抓取"工具，逻辑都只有一步：发一个请求，拿到 HTML，转成文本。成功了很好；失败了，Agent 拿到的要么是一个报错，要么是一段"请完成验证"的页面文字，然后它会一本正经地"总结"这段验证页。

真实的网络不是这样的。同一个链接，换一个"访问者"，拿到的可能完全是另一个页面：

• 微信公众号文章：从云服务器请求，经常返回"环境异常，完成验证后即可继续访问"；用手机微信的身份请求，同一个链接返回完整文章。

• 很多新闻站：正文由 JavaScript 渲染，HTML 里只有一个空壳，但页面里藏着给搜索引擎看的 JSON-LD，里面就是全文。

• Next.js / Nuxt 站点：<div id="__next"></div> 是空的，正文在 __NEXT_DATA__ 这段 JSON 里。

• YouTube：页面是重度 JS 应用，但视频标题和简介就在 ytInitialPlayerResponse 里。

• 有的页面压根不该读：需要登录、付费墙、验证码。这时候 Agent 最需要的不是"再试一次"，而是知道原因，好去问用户。

agent-web-fetch 把一个有经验的人读网页的思路，写成了一套 Agent 能直接调用的流程。

升级策略：先便宜，后昂贵

核心原则只有一句：一条路不通就换下一条，先用最便宜的办法，不行再上更重的；每一步都检查自己拿到的到底是不是正文。

 ┌──────────────────────────────────────────────────────────────────────┐
 │ 0. 站点适配器 API     GitHub README / X 公开嵌入接口        最便宜、最稳 │
 │ 1. 普通 HTTP 请求     一套真实、自洽的浏览器请求头                     │
 │ 2. 换身份重试         桌面 Chrome → 手机 Safari → Android / 微信内置浏览器│
 │                       + 同站 Referer、Accept-Language、礼貌退避重试    │
 │ 3. 每一步都做检测     Cloudflare？验证码？登录墙？付费墙？软 404？限流？ │
 │ 4. 多策略正文提取     trafilatura / readability / JSON-LD / JS 状态 /  │
 │                       og: 元数据 / 站点专用规则，挑最丰富的那个        │
 │    └ 正文太薄时        试 AMP 版本、RSS/Atom 订阅源                     │
 │ 5. 无头浏览器         Playwright（可选安装），真正把页面渲染出来   最贵 │
 └──────────────────────────────────────────────────────────────────────┘

第 0 层：能用官方/公开接口，就别解析 HTML

如果一个网站本来就提供了不需要登录的公开接口，那它永远比抓网页更快、更稳、更礼貌。

• GitHub：仓库地址直接走 api.github.com 拿 README 原文（Markdown），API 限额用完就退到 raw.githubusercontent.com。

• X / Twitter：单条推文走嵌入推文用的公开接口 cdn.syndication.twimg.com，不行再走官方 oEmbed。个人主页、时间线、搜索需要登录，工具会直接报告 login_required，不会去硬抓。

第 1 层：一次普通的请求，但要像个正常浏览器

很多工具默认的 User-Agent 是 python-requests/2.x，这本身就会被不少站点直接拒绝。我们发送的是一整套自洽的请求头：User-Agent、Accept、Accept-Language、sec-ch-ua 系列，彼此对得上，就像一个真的 Chrome。大部分公开页面在这一步就成功了，耗时几十到几百毫秒。

第 2 层：换一个"访问者"

被挡住时，最先要试的是换一个更合适的访问方式：

从第二次尝试开始，会带上同站的 Referer（就像用户从网站首页点进来）。遇到 429 / 503 会读取 Retry-After，按指数退避礼貌地重试，并且对同一个站点的请求之间保持最小间隔。同一次抓取的多个尝试共享 Cookie，就像同一个浏览器会话。

第 3 层：每一步都检查"我拿到的到底是什么"

这是和普通抓取工具最大的区别。每次拿到响应，都会先判断它是不是正文，如果不是，给出一个机器可读的原因 blocked_reason：

两条细节：

1. 关键词只在"页面很薄"时才算数。一篇讨论验证码的技术文章不会被误判成验证码页。

2. Cloudflare 会往很多正常页面里注入 challenge-platform 脚本，所以光有这个标记不算被挡，必须同时满足"挑战状态码"或"页面几乎没有内容"。

遇到验证码、登录墙、付费墙、404、已删除这类"换谁来都一样"的情况，梯子会立刻停下来，不浪费请求，也不去绕。

第 4 层：多策略提取，挑最丰富的，并记录谁赢了

拿到真正的页面之后，同时跑多种提取策略（它们都在本地运行，比再发一次网络请求便宜得多）：

按"文本长度 × 可信度权重"打分，选最高的。所有候选及其字数都写在 extraction_candidates 里，赢家写在 extraction_method 里，方便你调试，也方便 Agent 判断结果可不可靠。元数据（标题、作者、时间、站点名）则按字段合并：适配器 > JSON-LD > og 元数据 > trafilatura。

如果正文还是太薄，会尝试页面声明的 AMP 版本（<link rel="amphtml">），以及 RSS/Atom 订阅源里与当前链接匹配的那一条（订阅源本来就是给机器读的，又便宜又礼貌）。

第 5 层：真正打开一个浏览器

前面都不行、而且失败原因是"换个方式可能有用"的那一类时，才会启动 Playwright 无头浏览器，像普通访客一样把页面渲染出来，再走一遍检测和提取。它是可选依赖，没装就记录一条 skipped 然后跳过，不会报错。浏览器层不解验证码、不做交互式挑战；渲染后依然是验证码，就照实报告。

微信公众号：一个完整的例子

这个项目就是从读一篇公众号文章开始的。wechat 适配器把踩过的坑都写进去了：

1. 第一个尝试就用 iPhone 微信内置浏览器的 UA，Accept-Language: zh-CN。

2. 识别"环境异常 / 完成验证后即可继续访问"的验证页 → verification_wall；识别"该内容已被发布者删除""此内容因违规无法查看" → content_removed。

3. 长文：正文在 #js_content 里，图片地址在 data-src 里。

4. 短图文（item_show_type=10）：#js_content 是空的，全文在 content_noencode 这个 JS 变量里，og:title 里通常也有一份完整的。

5. 作者、公众号名、发布时间分别来自 author、nick_name、ori_create_time（没有时用 create_time），时间统一输出为带 +08:00 的 ISO 格式。

安装

# 从 GitHub 安装（发布到 PyPI 后可直接 pip install agent-web-fetch）
pip install "git+https://github.com/mrlong0129/agent-web-fetch"

# 可选：无头浏览器层
pip install "agent-web-fetch[browser] @ git+https://github.com/mrlong0129/agent-web-fetch"
playwright install chromium     # 或者系统里已有 Google Chrome 也可以，会自动尝试

# 不想装？用 uvx 直接跑
uvx --from git+https://github.com/mrlong0129/agent-web-fetch awf fetch https://example.com

需要 Python 3.10+。

使用

CLI

awf fetch <url>                       # 默认输出 Markdown（带 front matter）
awf fetch <url> --format json         # 完整结构化结果
awf fetch <url> --format text         # 纯文本
awf fetch <url> --browser             # 直接用无头浏览器
awf fetch <url> --no-browser          # 永远不用浏览器
awf fetch <url> --adapter none        # 关闭站点适配器（auto | none | wechat | github | x）
awf fetch <url> --profile wechat_ios  # 指定身份（可重复，按顺序尝试）
awf fetch <url> --robots strict       # robots.txt 不允许就不抓（批量/爬取场景请用这个）
awf extract page.html --url <原链接>   # 对本地 HTML 做检测 + 提取，不联网
awf adapters                          # 列出适配器
awf reasons                           # 列出所有 blocked_reason

退出码：0 成功，2 被挡或没有内容（原因打印在 stderr），1 其他错误。

JSON 输出字段：url、final_url、status、ok、title、author、published、site_name、description、lang、content_markdown、content_text、links、images、extraction_method、extraction_candidates、adapter、feeds、amp_url、fetch_attempts（每一步的 strategy、result、status、blocked_reason、detail、耗时、字节数、提取字数）、blocked_reason、blocked_detail、robots、warnings。

Python

from agent_web_fetch import fetch, extract_from_html

r = fetch("https://yomin.love/projects/claude-gemini-bridge/")
if r.ok:
    print(r.title, r.extraction_method, len(r.content_text))
else:
    print(r.blocked_reason, r.blocked_detail)   # 告诉用户原因，不要去绕

r = extract_from_html(html, url="https://example.com/post")  # 已经有 HTML 时

MCP Server（Claude Code / Cursor / 其他 Agent）

提供两个工具：

• fetch_page(url, format="markdown"|"text"|"both", use_browser="auto"|"never"|"always", adapter="auto", max_chars=40000)

• extract_from_html(html, url=None, format=..., adapter="auto", max_chars=40000)

Claude Code

claude mcp add agent-web-fetch -- uvx --from git+https://github.com/mrlong0129/agent-web-fetch awf-mcp
# 已经 pip install 过的话：
claude mcp add agent-web-fetch -- awf-mcp

或者在项目根目录的 .mcp.json 里：

{
  "mcpServers": {
    "agent-web-fetch": {
      "command": "uvx",
      "args": ["--from", "git+https://github.com/mrlong0129/agent-web-fetch", "awf-mcp"]
    }
  }
}

Cursor：把同样的 JSON 写进 ~/.cursor/mcp.json（全局）或项目里的 .cursor/mcp.json。

Agent Skill（不装也能用）

skill/SKILL.md 是一份写给 Agent 的操作手册，用大白话讲清楚这套升级策略：先试什么、看到什么信号说明被挡了、什么时候该停下来问用户。把它放进 Claude Code 的 ~/.claude/skills/agent-web-fetch/SKILL.md（或任何支持 skill 的 Agent），即使没有安装这个包，Agent 也能用自己的 curl / 浏览器工具照着做；装了包的话，它会优先调用 awf。

和普通抓取工具比

它不是爬虫框架，不做大规模抓取、不管理代理池，也不打算和专门的反爬对抗工具竞争。它解决的是 Agent 日常最常见的需求：用户丢过来一个链接，读懂它；读不了，说清楚为什么。

局限

• 只读公开内容。需要登录、付费、或者只对粉丝可见的内容读不到，这是设计如此。

• 检测是启发式的，可能有误判，所以每一步都记录了原因细节（blocked_detail）方便核查。

• 站点会变：微信、X 的公开接口随时可能调整，适配器需要维护。

• 从数据中心 IP 访问时，部分站点（例如路透社的 DataDome、知乎、B 站风控）无论换什么身份都会拒绝，工具会照实报告 captcha / forbidden。

• GitHub 未登录 API 每个 IP 每小时 60 次；设置环境变量 GITHUB_TOKEN 可以提高，但不是必需。

• 无头浏览器层慢（通常 10–20 秒），而且需要额外安装。

负责任地使用

• 只读公开内容。 这个工具遇到登录墙、付费墙、验证码时会报告，而不是绕过。永远不要用它去绕过访问控制。

• robots.txt：工具每次都会检查 robots.txt，并在结果的 robots 和 warnings 字段里写明。默认模式 warn 面向"用户亲手给了一个链接、读一次"的场景（和浏览器打开链接性质相同）；做批量抓取、爬虫、定时任务时，请使用 --robots strict。

• 控制频率：内置了同站请求间隔和退避重试。不要用它高频轮询任何网站。

• 遵守服务条款和版权：读到的内容版权归原作者。引用请注明出处，不要整篇转载或用于违反网站条款的用途。

• 身份切换的边界：切换 User-Agent 是为了拿到"为这类客户端设计的那个版本"（比如为手机微信设计的公众号页面），而不是伪装成搜索引擎爬虫或冒充特定用户。本工具不会冒充 Googlebot 等爬虫。

English

By Yomin Ma (@mrlong0129). Sibling project: wechat-article-fetcher, a focused reader for WeChat Official Account articles. See Quick start for agents for zero-install one-liners and AGENTS.md.

Why

Most "fetch" tools for LLMs make one request and either return an error or hand the agent a verification page that it then confidently "summarises". On the real web the same URL can return a full article, a bot check, or an empty JavaScript shell depending on who is asking. agent-web-fetch encodes how an experienced human reads the web: try the cheapest thing first, escalate only when blocked, check at every step whether you actually got the content, and when you can't, say exactly why.

The escalation ladder

1. Site adapter APIs – public, login-free endpoints (GitHub README API / raw, X syndication + oEmbed).

2. Plain HTTP – one request with a coherent, realistic browser header set.

3. Client rotation – desktop Chrome → mobile Safari → Android Chrome (WeChat in-app UA for WeChat), same-origin Referer, Accept-Language, polite pacing, Retry-After-aware exponential backoff, cookies shared across rungs.

4. Detection after every rung – cloudflare_challenge, captcha, verification_wall, login_required, paywall, rate_limited, forbidden, not_found, soft_404, content_removed, js_required, robots_disallowed. Keyword heuristics only fire on thin pages, so articles about captchas are not misflagged. Non-retryable verdicts (CAPTCHA, login, paywall, 404, removed) stop the ladder immediately.

5. Multi-strategy extraction – trafilatura, readability-lxml, JSON-LD articleBody, embedded JS state (__NEXT_DATA__, __NUXT__, window.__INITIAL_STATE__, __APOLLO_STATE__, ytInitialPlayerResponse…), og:/twitter: meta, and adapter rules compete; the richest (length × trust weight) wins and is recorded in extraction_method, with all candidates in extraction_candidates. Thin pages also try the AMP version and a matching RSS/Atom entry.

6. Headless browser – optional Playwright extra, used only when cheaper rungs failed for a retryable reason; skipped gracefully if not installed. It never solves CAPTCHAs.

Install

pip install "git+https://github.com/mrlong0129/agent-web-fetch"
pip install "agent-web-fetch[browser] @ git+https://github.com/mrlong0129/agent-web-fetch" && playwright install chromium

Use

awf fetch <url> [--format md|json|text] [--browser|--no-browser] [--adapter auto|none|wechat|github|x] [--robots warn|strict|ignore]
awf extract page.html --url <original-url>
awf-mcp            # MCP server on stdio: tools fetch_page, extract_from_html

Claude Code: claude mcp add agent-web-fetch -- uvx --from git+https://github.com/mrlong0129/agent-web-fetch awf-mcp. Cursor: put the JSON above in ~/.cursor/mcp.json. The agent skill lives in skill/SKILL.md and works even without the package.

Limitations and responsible use

Public content only. The tool reports logins, paywalls and CAPTCHAs; it never bypasses them. It checks robots.txt on every fetch and surfaces the result; the default warn mode is meant for one-off, user-initiated reads of a link (like opening it in a browser) — use --robots strict for crawls, batch jobs and schedules. Built-in per-host pacing and backoff; don't use it to hammer sites. Respect each site's terms and the authors' copyright. Profile rotation picks the client a page was built for (e.g. WeChat's in-app browser); it does not impersonate search-engine crawlers or specific users. Detection is heuristic, adapters can break when sites change, and some sites block datacenter IPs regardless of client.

Development

python -m venv .venv && . .venv/bin/activate
pip install -e ".[dev,browser]"
pytest            # offline tests (fixtures in tests/fixtures)
pytest -m live    # live smoke tests (network)

Adding a site adapter: subclass agent_web_fetch.adapters.base.Adapter, override matches, and any of profiles, api_fetch, classify, candidates; register it in adapters/__init__.py. Please only add adapters you have verified against the live site, using public, login-free endpoints.

License

MIT © 2026 Yomin Ma