在你的 Symfony 应用中提供 AI-Ready Markdown 🔥

Source: Dev.to

引言

AI 代理并不像人类那样阅读你的网站。
它们会忽略 Tailwind 或任何 CSS 类、导航菜单以及 JavaScript。
它们需要的是干净、结构化的内容：

• 清晰的标题
• 最少的标记
• 没有展示噪声的内容

随着 ChatGPT、Claude、Perplexity 等工具以及自主爬虫越来越多地浏览网页，直接提供原始 HTML 变得低效。HTML 中包含布局噪声——页眉、页脚、脚本、样式、Cookie 横幅——这些会浪费 token 并降低语义清晰度。

解决方案： symfony‑markdown‑response‑bundle —— 一个轻量级 Symfony Bundle，能够在 仅在请求时 将你现有的 HTML 响应透明地转换为 Markdown。

• GitHub:
• Packagist:

无需重复路由，无需单独的 Markdown 控制器，也无需额外维护。

该 Bundle 的功能

symfony-markdown-response-bundle 拦截 Symfony 响应，并在合适的情况下：

1. 检测请求是否偏好 Markdown。
2. 清理 HTML 输出（去除布局噪声）。
3. 将清理后的 HTML 转换为 Markdown。
4. 返回 text/markdown 而非 text/html。

所有这些都是透明进行的；你的控制器保持不变。

转换后端

本地（默认）

• 使用 league/html-to-markdown。
• 转换在进程内完成，无需外部依赖。

Cloudflare

将转换任务交给 Cloudflare Workers AI 端点。

# config/packages/symfony_markdown_response.yaml
symfony_markdown_response:
    driver: cloudflare
    cloudflare_endpoint: 'https://your-worker.example.workers.dev/to-markdown'

• 需要 symfony/http-client。
• HTML 会被 POST 到你的 Worker 端点，返回的响应体即为 Markdown。

缓存

默认使用 PSR‑6 缓存池缓存已转换的 Markdown。

• 缓存键： 预处理后 HTML 的 xxh3 哈希
• 默认 TTL： 3600 秒

缓存解析顺序

1. cache_service（如果已配置）
2. cache.app
3. cache.system

禁用缓存

symfony_markdown_response:
    cache_enabled: false

使用示例

use Soleinjast\MarkdownResponseBundle\Attribute\ProvideMarkdownResponse;
use Symfony\Component\HttpFoundation\Response;
use Symfony\Component\Routing\Annotation\Route;

#[Route('/about')]
#[ProvideMarkdownResponse(enabled: true)]
public function about(): Response
{
    return $this->render('about.html.twig');
}

检测规则

当满足以下任意条件时，Bundle 会提供 Markdown：

• Accept: text/markdown 请求头
• URL 后缀为 .md（例如 /about.md）
• 已知的 AI 用户代理（如 GPTBot、ClaudeBot、ChatGPT-User）

普通浏览器流量仍然会收到 HTML。

安装

composer require soleinjast/symfony-markdown-response-bundle

然后在 Symfony 项目中启用该 Bundle（Symfony Flex 通常会自动完成），并在需要以 Markdown 形式暴露的路由上添加注解。

为什么重要

过去 20 多年我们一直为浏览器优化网页；现在我们也需要为读取和推理的机器进行优化。提供带有布局包装的完整 HTML 会增加 token 使用量并降低信号质量。Markdown：

• 保留标题和层级结构
• 保持段落完整
• 去除展示噪声
• 提升语义清晰度
• 大幅减轻体积

如果你的应用已经生成有意义的 HTML，就让机器以它们最懂的格式来消费它吧。symfony-markdown-response-bundle 正是弥合这一差距的桥梁——干净、透明且零重复。