当你的 AI Agent 需要吃网页：PageToMD 把任意 URL 变成干净的知识饲料
问题：AI Agent 要读网页，但 HTML 是垃圾食品
每天你的 AI 编码助手都要吞下大量网页——文档站、技术博客、GitHub README、API 参考手册。但你传入的东西其实很脏：导航栏、广告脚本、跟踪像素、零宽字符、混乱的标题层级、未标准化的 Unicode。
直接喂原始 HTML 给 LLM，你浪费了至少 30-50% 的 context window 在无用 chrome 上。更糟的是，curl | html2md 管道在每个项目里都要重新写一遍，robots.txt 没处理，mojibake 乱码随缘，输出没有元数据追踪，你甚至不知道这段 Markdown 是从哪个 URL 爬来的。
PageToMD 就是来解决这个问题的：一个命令，把任意 URL 变成干净、带元数据、LLM 可直接消化的 Markdown。
安装：三条命令中的任意一条
PageToMD 是纯 Python CLI 工具，发布在 PyPI 上。推荐用 pipx 安装（隔离环境、全局可用）：
pipx install pagetomd pip install pagetomd uv tool install pagetomd
如果你不需要 JavaScript 渲染（大多数静态文档页不需要），就这么简单。如果目标页面是 SPA（React、Vue、Next.js），额外装 Playwright：
pipx inject pagetomd playwright && playwright install chromium
最常用的场景：一条命令，输出到 stdout
pagetomd https://example.com/blog/post pagetomd https://example.com/blog/post -o - | llm "三句话总结本文"
-o - 是关键参数：所有日志走 stderr，stdout 只有纯净的 Markdown，可以直接管道。输出的 Markdown 带有完整 YAML 头——url、title、author、date、description、site_name、language，方便溯源。
进阶场景一：爬取整个文档站
pagetomd "https://docs.example.com/guide/" \ --crawl --crawl-depth 2 \ --fetcher auto \ -o ./docs-output/
这个命令会从种子 URL 开始 BFS 遍历所有同子树链接，每个页面写一个 .md 文件，目录结构镜像 URL 层级：
| URL | 输出文件 |
|---|---|
docs.example.com/guide/ | docs-output/index.md |
docs.example.com/guide/intro | docs-output/intro.md |
docs.example.com/guide/concepts/alerts | docs-output/concepts/alerts.md |
配合 --fetcher auto，静态页面用 httpx 秒级获取，遇到 SPA 自动降级到 Playwright 渲染。--overwrite 可以覆盖已有文件，默认跳过。
进阶场景二：SPA 页面的自动降级
很多现代文档站（Next.js、Docusaurus）是 JS 渲染的——直接 HTTP GET 只能拿到 空壳。PageToMD 的 --fetcher auto 模式会智能检测：
- 先用
httpx抓取 - 如果 body 文本 < 200 字符且页面含 SPA 标记（
data-reactroot、__next等），自动切换到 Playwright - 如果 Playwright 不可用，标记为”空页面”而非硬失败
pagetomd https://my-spa-app.com/docs --fetcher auto -o -
进阶场景三：批量喂给 RAG
while read -r url; do pagetomd "$url" -o "./corpus/$(date +%s).md" done < urls.txt pagetomd https://example.com --no-fetched-at -o post.md
--no-fetched-at 在需要字节级稳定输出时特别有用——每次运行相同 URL 得到相同的 Markdown，适合 RAG 管道的哈希比对和增量更新。
输出质量：不止是去掉 HTML 标签
PageToMD 的管线分为五层：
URL → Fetcher → Extractor → Converter → Postprocess → Writer
(httpx/ (BS4 + (markdownify (NFC, heading (atomic file +
playwright) trafilatura) + GFM tables) hierarchy) YAML head)
关键的质量保证：
- NFC 标准化：所有 Unicode 被规范化为 NFC 形式，消除零宽字符和同形异码字
- 单调标题层级：不会出现 H1 → H3 → H2 这种跳跃
- 绝对路径 URL：所有相对链接被转成绝对路径，不会因为目录结构变化而断开
- YAML 溯源：每次输出都附完整元数据——原始 URL、最终 URL（含重定向链）、标题、作者、日期、描述、站点名、语言
- 稳定退出码：
0成功、2网络失败、3提取失败、4写入失败、5缺依赖、64参数错误、130用户中断。每个退出码都可被 shell 脚本精确捕获
安全设计
PageToMD 是一个公共 URL 专用工具。它默认拒绝抓取私有 IP、loopback、link-local、multicast、保留地址和云 metadata 地址——并且没有 flag 可以绕过这个限制。输出文件的安全敏感度等同于你抓取的 URL。
什么时候该用它，什么时候不该
| 场景 | 推荐工具 |
|---|---|
| 快速把一篇博客转成 Markdown 喂给 LLM | ✅ PageToMD pagetomd URL -o - |
| 整个文档站离线同步到 RAG 知识库 | ✅ PageToMD --crawl 模式 |
| 需要精确 HTML→Markdown 转换（如 Pandoc 支持的特定格式） | ❌ 用 Pandoc |
| 已有完整的网页抓取/清洗基础设施 | ❌ 不需要额外工具 |
总结
PageToMD 不是最全能的网页转 Markdown 工具（它不做格式间互转，不生成 PDF），但它是最适合 AI Agent 场景的。一个命令、无配置、带溯源、可脚本化——对于每天要用 AI 工具读十几个网页的开发者来说，这是一个直接提升 context 效率的实用工具。
注意：PageToMD 使用 Business Source License 1.1（源码可用，非商业免费，2030 年转为 MIT），不是传统意义上的"开源"软件。但如果只是在个人项目中用它给 LLM 喂数据，协议完全够用。