Cloudflare Nimbus：让 AI Agent 和人类都能读懂你的文档

当你的文档只有你能看懂

想象一下这个场景：你的团队花了两周写的技术文档，发布到网上后，人类用户轻松浏览，AI 助手却完全"看不懂"——找不到关键信息、无法正确理解页面结构、给出的回答牛头不对马嘴。更糟糕的是，AI Agent 在处理你的代码问题时，读到的文档和实际行为不一致，导致它在帮你修 bug 时把事情越搞越糟。

这不是个别现象。随着 Claude Code、Cursor、Copilot 这类 AI 编程工具深入软件开发流程，文档的"AI 可读性"正在成为和人类可读性同等重要的问题。传统的文档工具（Docusaurus、GitBook）把注意力全放在人类体验上，AI Agent 能读，但读得很费劲——需要解析渲染后的 HTML、猜测页面层级、遗漏关键数据。

Cloudflare 的 Nimbus 正是冲着这个痛点来的。

一个让 Cloudflare 7000+ 页面"AI 化"的项目

Nimbus 最早是 Cloudflare 内部用来解决自己文档问题的工具。Cloudflare 的文档站有超过 8700 个页面，是公司对外技术支持的命脉——但随着 AI 编程工具普及，Cloudflare 的工程师们发现 Claude Code 等工具在处理 Cloudflare 相关的开发问题时频频出错，根本原因是文档的格式和内容组织方式对 AI Agent 不友好。

Cloudflare 的工程师做了一个实验：让 AI Agent 直接使用他们的文档，结果问题解决率远低于预期。经过分析，核心问题有三个：

1. 文档结构不透明：Agent 只能看到渲染后的 HTML，背后的 Markdown 结构和设计意图完全黑盒
2. 缺少机器可读的摘要：没有 sitemap.txt、llms.txt 这样的 AI 友好索引文件
3. 组件和代码示例混在一起：Agent 无法区分哪些是界面元素、哪些是可复用的代码

Nimbus 就是在这个背景下诞生的。它本质上是一个基于 Astro 7 的文档站点生成器，但和 Docusaurus、GitBook 不同，它从第一天起就把"AI Agent 能读懂"作为核心设计目标，而非后期补丁。

核心理念：你拥有每一个文件

Nimbus 最大的差异化主张是"你拥有每一个文件"（You own every file）。

传统文档工具的工作模式是：安装一个 npm 包，配置一下，运行时动态加载主题组件。你的源代码库里只有 Markdown 内容，样式和布局是"外面"的依赖——想改一个按钮的样式，你得和主题 API 较劲，或者直接 fork 一个你控制不了的东西。

Nimbus 做了相反的事：运行 npx @cloudflare/create-nimbus-docs@latest my-docs 后，项目里会有完整的 src/layouts/、src/components/、src/styles/——所有东西都是你的源代码，你直接改就行，npm 包只是"脚手架生成器"，生成完就走人。

这个设计对 AI Agent 特别友好：当 AI 需要修改文档站的结构或样式时，它看到的是一个完整的、可预测的文件树，而不是一个黑盒依赖。

AI 原生：让 Agent 读文档像浏览器一样好

这是 Nimbus 最值得关注的创新点。它默认生成以下 AI 友好的文件：

• /llms.txt：站点的纯文本摘要，供 AI 快速了解全站内容
• /llms-full.txt：完整版，包含所有页面的详细摘要
• JSON-LD 结构化数据：每个页面都带 schema.org 语义标记
• .md 替代版本：每个 MDX 页面同时生成纯 Markdown 版本
• 自动生成 sitemap 和 robots.txt
• 每页 OG 图片：社交分享和 AI 预览用

这些不是插件，而是开箱即用的默认行为。用 Nimbus 建站，AI Agent 读取文档的体验基本等同于用浏览器浏览。

技术架构：扎实的现代前端堆栈

Nimbus 的技术选型相当硬核：

层级	技术
框架	Astro 7（静态优先，岛屿架构）
样式	Tailwind CSS v4
Markdown 处理	Sätteri（Rust 编写，高性能）
可选交互层	React 19（用于需要 JS 交互的组件）
排版	Fontsource Inter + JetBrains Mono（可变字体）
图片处理	Resvg（SVG 转 PNG/Raster）
SSR 部署	Cloudflare Workers（可选适配器）

包结构也很有意思——采用 pnpm workspace monorepo 架构：

packages/
  create-nimbus-docs/   # npx 脚手架工具
  nimbus-docs/          # 核心 CLI 工具（add 命令等）
  nimbus-starter-source/ # 模板源码
apps/
  www/                  # Nimbus 自身文档站（nimbus-docs.com）

整个项目使用 TypeScript 全面类型化，ESLint + Prettier 统一代码风格。

上手体验：5 分钟建一个文档站

安装体验非常顺滑：

npx @cloudflare/create-nimbus-docs@latest my-docs
cd my-docs
pnpm install
pnpm dev

然后浏览器打开打印出的 URL，改 src/ 下的任何文件，热重载即时生效。

项目结构清晰：

src/
  layouts/     # 页面布局组件
  components/  # 可复用 UI 组件
  content/     # Markdown/MDX 文档内容
  styles/      # 全局样式和 Tailwind 主题

部署同样简单：pnpm build 输出纯静态 dist/，扔到 Cloudflare Pages、Vercel 或 Netlify 都能跑。如果选了 Cloudflare Workers 输出模式，还可以做服务端渲染。

局限与现实

需要坦诚的是，Nimbus 目前是 0.x 版本，官方明确说"公共 API 在小版本之间可能变化，还有粗糙边缘"。生产环境使用需要锁版本，并关注各包的 CHANGELOG。

此外，作为文档站点生成器，它不提供任何内容管理后台——文档更新靠改 Markdown 文件，适合工程团队，不太适合内容团队。

对于 AI Agent 的支持，虽然默认生成 llms.txt 等文件，但实际效果还取决于文档内容的质量和结构——好的文档生成器治不了差的文档内容。

行业意义：文档的"AI Ready"标准正在形成

Nimbus 代表了一个重要趋势：文档工具正在从"人类可读"向"人类+AI 双友好"进化。

随着 AI 编程工具渗透率提升，文档的读者不再只是人——AI Agent 会自动读取技术文档来理解 API、排查问题、生成代码。文档质量直接影响 AI 工具的使用效果。这意味着文档工具必须原生支持 AI 的读取和理解方式，而不只是优化人类的阅读体验。

Cloudflare 宣布他们用这套工具将 Astro 框架的积压 issue 减少了约 85%，虽然这个数字有多种解释，但足以说明AI 友好型文档对开发效率有真实影响。

如果你的团队重度使用 AI 编程工具，Nimbus 值得认真考虑——它代表了文档工具在 AI 时代的一种前沿方向。