我在 NGINX（Rust 模块）中尝试了 Cloudflare 的 “Markdown for Agents” 想法 — 初步原型

Source: Dev.to

介绍

Cloudflare 最近推出了 Markdown for Agents：如果客户端发送 Accept: text/markdown，Cloudflare 可以抓取你的 HTML 并返回 Markdown 变体。
受此启发，我构建了一个可自行托管的 NGINX 动态模块，在自己的基础设施上实现类似功能。这是一个非常早期的原型，主要用于帮助大家尝试工作流并提供反馈。

仓库：

工作原理

• 不需要对应用进行任何改动；转换完全在反向代理层完成。
• 最佳使用场景： 文档、博客、新闻、知识库页面。
• 不适用场景： API、流式响应或需要身份验证的页面（除非你仔细处理缓存）。

Agent 和 LLM 工具通常会抓取完整的 HTML，并在导航栏、页脚、Cookie 横幅、布局标记、脚本以及噪声属性上浪费 token。Markdown 变体可以让下游解析更廉价、更可预测。

安装

# Install the module
curl -sSL https://raw.githubusercontent.com/cnkang/nginx-markdown-for-agents/main/tools/install.sh | sudo bash

# Test and reload NGINX
sudo nginx -t && sudo nginx -s reload

注意： 动态模块必须与您当前的 NGINX 补丁版本（nginx -v）完全匹配。如果没有可用的匹配构建，您可能需要自行编译该模块。

验证 Markdown 变体

# Request Markdown
curl -sD - -o /dev/null -H "Accept: text/markdown" http://localhost:8080/ | grep -iE 'content-type|vary'
# Expected output:
# content-type: text/markdown; charset=utf-8
# vary: Accept

验证 HTML 变体

curl -sD - -o /dev/null -H "Accept: text/html" http://localhost:8080/ | grep -i 'content-type'

示例请求

curl -s -H "Accept: text/markdown" http://localhost:8080/ | head -40

配置

先从小范围开始——先在单一路由上启用过滤器。

load_module modules/ngx_http_markdown_filter_module.so;

http {
    markdown_filter off;

    server {
        listen 8080;

        location /docs/ {
            markdown_filter on;

            # Recommended: avoid upstream compression for clean conversion
            proxy_set_header Accept-Encoding "";

            proxy_pass http://backend;
        }
    }
}

失效打开（推荐用于试用）

如果转换失败，将返回原始 HTML：

markdown_on_error pass;

限制工作量

markdown_max_size 10m;
markdown_timeout 5s;

指标端点（仅限本地主机）

location /markdown-metrics {
    markdown_metrics;
}

缓存注意事项

如果在 NGINX 或 CDN 上进行缓存，请确保通过 Accept 头区分变体：

proxy_cache_key "$scheme$request_method$host$request_uri$http_accept";

注意事项

• 会存在边缘情况（奇怪的 HTML、超大页面、异常编码）。
• 模块仅专注于 HTML → Markdown（不处理 PDF 或任意二进制文件）。
• 缓存需要谨慎处理（变体键 + 鉴权行为）。

如果你遇到页面损坏、页面极慢或缓存问题，请提交 issue，并提供以下信息：

• 示例 URL（或脱敏后的 HTML）
• nginx -v 的输出
• 上游是否开启了压缩
• 前置的任何缓存/CDN

参考资料

• Cloudflare 灵感 – 博客：
• Cloudflare 文档：
• 项目仓库：