Markdown Fetch

核心用法

markdown-fetch 是一个针对 AI Agent 优化的网页抓取工具，核心原理是利用 Cloudflare 的 Markdown for Agents 功能：通过在 HTTP 请求头中声明 Accept: text/markdown, text/html，让支持该特性的网站直接返回 Markdown 格式而非 HTML，从而大幅减少 Token 消耗（官方宣称约 80%）。

使用方式

1. 集成到现有项目：替换原有的 fetch 调用，使用封装好的 optimizedFetch 函数
2. 自动降级处理：优先请求 Markdown，若服务端不支持则自动回退到 HTML 解析
3. Token 监控：可选读取响应头 x-markdown-tokens，量化节省效果

显著优点

• Token 效率：Markdown 比 HTML 精简约 80%，直接降低 LLM API 成本
• 简化解析：无需复杂的 HTML→Markdown 转换，减少解析错误
• 透明兼容：服务端不支持时自动回退，无破坏性变更
• 低侵入性：仅需修改请求头，不改业务逻辑

潜在局限

• 服务端依赖：仅 Cloudflare 托管站点支持，覆盖率有限（2024-2025 逐步推广中）
• 内容完整性：部分动态渲染内容（JS 执行后）可能丢失
• 格式一致性：不同站点的 Markdown 生成质量参差不齐
• 生态早期：工具链成熟度待验证，生产环境需充分测试

适合人群

• 开发 AI Agent/RAG 系统的工程师
• 高频抓取网页并喂给 LLM 的场景（如搜索增强、知识库构建）
• 关注 Token 成本优化的团队

常规风险

• 可用性风险：Cloudflare 功能迭代可能导致行为变更
• 安全风险：需确保抓取目标合规，避免违反 robots.txt 或服务条款
• 数据一致性：Markdown 简化可能导致结构化信息丢失（如表格、嵌套列表）

核心用法

markdown-fetch 是一个轻量级的网页内容获取优化工具，专为 Cloudflare 的 Markdown for Agents 功能设计。当目标网站托管于 Cloudflare 并启用该功能时，通过设置特定的 HTTP Header（Accept: text/markdown, text/html），服务器会直接返回 Markdown 格式的内容，而非传统的 HTML。

核心 API 为 optimizedFetch(url, options)，返回包含 markdown 或 html 字段的结果对象，同时提供 tokensSaved 指标量化节省效果。

显著优点

极致的性能优化：官方宣称可降低约 80% 的 Token 消耗，对于频繁进行网页内容处理的 AI Agent 场景，成本效益显著。

零依赖安全架构：完全不依赖第三方 npm 包，仅使用 Node.js 原生 fetch API，彻底规避供应链攻击风险。

优雅的降级机制：当目标服务器不支持 Markdown 响应时，自动回退至 HTML 解析，保证功能可用性。

极简的集成成本：单一函数接口，仅需替换现有 fetch 调用并添加 Header，即可无缝接入现有工作流。

潜在缺点与局限性

服务商锁定效应：功能完全依赖 Cloudflare 的专有实现，仅对 Cloudflare 托管且开启该特性的站点有效，通用性受限。

URL 验证缺失：当前版本未对输入 URL 进行有效性校验，可能传递非法协议（如 file://）或恶意构造的地址。

错误处理薄弱：缺乏详细的错误分类、超时控制和重试机制，生产环境稳定性需额外封装。

功能单一性：仅为请求层包装，不包含 HTML 到 Markdown 的转换能力，非 Cloudflare 站点无优化效果。

适合人群

• 使用 Cloudflare 托管服务的内容平台开发者
• 需要大规模网页抓取并关注 Token 成本的 AI Agent 构建者
• 追求零依赖、供应链安全优先的技术团队

常规风险

| 风险类型 | 等级 | 说明 |

|---------|------|------|

| SSRF（服务器端请求伪造） | 低 | 未限制 URL 协议和地址范围，需调用方自行管控 |

| 依赖风险 | 无 | 零第三方依赖 |

| 数据泄露 | 无 | 无敏感数据收集或外发 |

| 超时/DoS | 低 | 无请求超时设置，可能因慢响应导致资源占用 |

建议生产使用前添加 URL 白名单/黑名单、请求超时、以及速率限制等防护措施。