如何為 AI 代理提供 Markdown 服務：讓你的文件更適合 AI

介紹

如果您最近曾造訪開發者 Twitter，您可能已經看過 Bun 關於直接向 Claude Code 等 AI 編碼助手提供 Markdown 的推文。

{% 嵌入 https://x.com/bunjavascript/status/1971934734940098971 %}

Mintlify和Fumadocs都已經在其文件平台中立即實現了該功能，而我剛剛為Lingo.dev親自實現了該功能。

{% 嵌入 https://x.com/mintlify/status/1972315377599447390 %}

這就是為什麼它很重要以及如何自己實現它。

問題：HTML 膨脹

AI 代理可以抓取網頁內容來幫助開發者。大多數情況下，這些內容會以 HTML 格式傳回。但 HTML 中包含一些標記，它們會消耗 token 而不會加入任何有意義的訊息，從而降低效能。

解決方案：內容協商

優雅的解決方案是內容協商。這是一種標準的 HTTP 機制，客戶端使用Accept標頭告訴伺服器它們想要什麼格式。

當 AI 代理程式使用Accept: text/markdown或Accept: text/plain請求您的文件時，您的伺服器可以使用 Markdown 而不是 HTML 來回應。

這意味著：

相同資訊使用更少的令牌
更容易解析和理解
上下文視窗中可容納更多文件

實施指南

確切的實作細節取決於您的程式語言和框架，但整體方法是相同的。

讓我們透過 Express.js 來看範例。

1. 偵測Accept頭

當請求到達時，檢查Accept標頭是否包含text/markdown或text/plain ：

app.get("/docs/*", (req, res) => {
  const acceptHeader = req.headers.accept || "";

  if (acceptHeader.includes("text/markdown")) {
    // Serve Markdown
  } else if (acceptHeader.includes("text/plain")) {
    // Serve plain text
  } else {
    // Serve HTML (default behavior)
  }
});

2. 提供原始 Markdown

載入並返回所請求頁面的原始 Markdown 內容：

if (acceptHeader.includes("text/markdown")) {
  const markdownContent = await loadMarkdownForPage(req.path);
  res.setHeader("Content-Type", "text/markdown; charset=utf-8");
  res.send(markdownContent);
  return;
}

3. 恢復現有行為

對於所有其他請求（瀏覽器、爬蟲等），請繼續使用現有的 HTML 渲染：

res.render("docs", { content: processedContent });

4. 測試你的實現

使用curl驗證您的實作是否正常運作：

# Request Markdown
curl -H 'Accept: text/markdown' https://lingo.dev/en/cli

# Request plain text
curl -H 'Accept: text/plain' https://lingo.dev/en/cli

# Request HTML (default)
curl -H 'Accept: text/html' https://lingo.dev/en/cli

對於 Markdown 請求，您應該看到：