https://docs.netlify.com

已完成 · 完成 2026-05-28 18:11 UTC · 运行 id 019e6fc8-6eac-74c2-acf7-e6c265133344

ID	标准	状态	得分
`A1`	主机根目录下的 llms.txt 符合 llmstxt.org 规范智能体（以及初次接触站点的人）需要一份单一、可预期的索引来定位文档所在位置。/llms.txt 正是 Anthropic 与 llmstxt.org 社区共同提出的约定：在主机根目录放置一个 Markdown 文件，给出文档地图。评分。 2 = 含 H1 + ≥1 个 H2 + ≥3 条链接，且全部可正常访问 · 1 = 任意带 H1 的文件（若链接无法访问，则从 2 降级）· 0 = 缺失或仅为 HTML 外壳。改进。在主机根目录发布 /llms.txt，包含一个 `# H1` 标题、若干 `## H2` 小节标题，以及至少三条指向具体文档页面的 Markdown 列表链接。规范详见 https://llmstxt.org 。证据。 https://docs.netlify.com/llms.txt /rubric#a1 · 文章	通过	5/5
`A2`	存在 llms-full.txt 或按小节拆分的 LLM 聚合文件 /llms-full.txt 是把文档全文汇总到一处的导出文件——大语言模型智能体更愿意直接读它，而非爬取 200 个 HTML 页面。按小节拆分的变体（如 /llms-api.txt 等）同样有效。评分。 3 = 主机根目录下存在 /llms-full.txt 且大于 1 KB · 2 = 通过 llms.txt 发现按小节拆分的聚合文件 · 0 = 两者皆无，或 /llms-full.txt 仅为 SPA 外壳。改进。在构建时生成 /llms-full.txt（mkdocs、docusaurus 均有相应插件），并以 text/plain 提供。文件应控制在 100 MB 以内，以便智能体无需流式传输即可获取。证据。 https://docs.netlify.com/llms-full.txt /rubric#a2 · 文章	缺失	0/3
`A3`	robots.txt 声明了 AI 爬虫策略与绝对路径的 Sitemap 每个 AI 爬虫（GPTBot、ClaudeBot、Google-Extended、PerplexityBot、CCBot）在抓取前都会先读取 /robots.txt。为各 UA 显式声明 Allow/Disallow，再加上一条绝对路径的 `Sitemap:` 指令，就能消除关于是否索引以及索引哪些内容的歧义。评分。 3 = 同时含显式 AI 爬虫 UA 指令与绝对路径的 Sitemap: 行 · 2 = 仅含 AI 爬虫指令 · 1 = 仅含绝对路径的 Sitemap · 0 = 两者皆无，或返回 404。改进。为每个主流 LLM 爬虫加上 `User-agent: GPTBot\nAllow: /`（或按策略改用 Disallow），并补一行 `Sitemap: https://example.com/sitemap.xml`。Cloudflare 的 `Content-Signal:` 指令同样计入。证据。 https://docs.netlify.com/robots.txt /rubric#a3 · 文章	缺失	0/3
`A4`	sitemap.xml 格式规范、使用绝对 URL、分类噪声低站点地图告诉爬虫该索引什么、内容多久变更一次。一个格式规范的 `<urlset>`，其中各页面均使用绝对路径的 `<loc>` URL，表明覆盖范围真实可信；而只有一个 URL 的占位文件（或 70% 以上都是 /tag/、/category/ 噪声的文件）则提供不了任何信号。评分。 3 = 格式规范 + ≥3 条不同路径 + 分类垃圾占比 <30% · 2 = 过于单薄（<3 条路径）或垃圾占比 30-70% · 1 = 仅格式规范 · 0 = 404 或解析错误。改进。在构建时生成 /sitemap.xml，将每个文档页面以绝对 URL 写入 `<loc>`，并排除 /tag/、/category/、/author/、/page= 等变体。再在 robots.txt 中用一行绝对路径的 `Sitemap:` 引用它。证据。 https://docs.netlify.com/sitemap.xml /rubric#a4 · 文章	通过	4/4
`A5`	首页发现标签：Markdown 备用版本 + OpenGraph 发现标签让智能体无需额外探测即可找到页面的 Markdown 版本，而 OpenGraph 则能把分享出去的文档链接在 Slack、Discord、Twitter 上渲染成富预览。两者都表明站点对机器消费者有所考量。评分。 2 = 含 `<link rel=alternate type=text/markdown>` + ≥3 个不同的 `og:` 属性 · 1 = 仅有 Markdown 备用版本，或仅有 OpenGraph · 0 = 两者皆无。改进。在 canonical 链接旁加上 `<link rel="alternate" type="text/markdown" href="/page.md">`，并确保首页设置了 `og:title`、`og:description`、`og:image`（至少 3 个属性）。证据。 https://docs.netlify.com /rubric#a5 · 文章	部分通过	1/3
`B1`	文档页面的 .md 配套版本返回干净的 Markdown 为读文档而浏览 200 个 HTML 页面，对人来说尚可接受；但对智能体而言，这是数量级的分词开销。为每个页面提供一个 Markdown 孪生版本，可让智能体只拉取正文内容。评分。 7 = 抽样的 3 个页面中 3 个都有可用的 .md 孪生版本 · 4 = 2/3 · 2 = 1/3 · 0 = 0/3。改进。在每个 HTML 页面旁提供 `{page}.md`（或 `{page}/index.md`），或者支持 `Accept: text/markdown` 内容协商并返回 `Content-Type: text/markdown`。mkdocs-material 与 docusaurus 均有相应插件。证据。 https://docs.netlify.com/api-and-cli-guides/api-guides/get-started-with-api/ /rubric#b1 · 文章	缺失	0/7
`B2`	首页与样本文档页含带有效 @type 的 JSON-LD JSON-LD 是兼容 schema.org 的方式，用来声明“本页面是一篇 Article”/“本产品是一个 SoftwareApplication”。搜索引擎、智能体和结构化数据提取器都依赖它。评分。 4 = 首页与某个样本文档页“同时”含可解析、带 `@type` 的 JSON-LD · 3 = 两者之一 · 0 = 都没有。改进。在每个文档页面嵌入 `<script type="application/ld+json">{"@context":"https://schema.org","@type":"TechArticle",...}</script>`。首页则适合用 `WebApplication` 类型。证据。 https://docs.netlify.com /rubric#b2 · 文章	缺失	0/5
`B3`	首页与样本页含绝对路径的 <link rel=canonical> canonical 链接能确定性地回答“这是 http 还是 https 版本？带不带末尾斜杠？带不带查询参数？”的问题。缺了它，智能体可能把同一份内容索引到多个 URL 之下。评分。 3 = 首页与某个样本页“同时”含绝对路径的 canonical · 2 = 仅首页有 · 1 = 存在但为相对路径 · 0 = 缺失。改进。在每个页面的 `<head>` 中加上 `<link rel="canonical" href="https://example.com/page">`。URL 必须包含协议和主机名（相对路径的 canonical 虽是合法 HTML，但对跨主机的智能体而言失去了意义）。证据。 https://docs.netlify.com /rubric#b3 · 文章	通过	3/3
`B4`	新鲜度：dateModified（JSON-LD）或 Last-Modified 头对于不声明最后更新时间的文档，智能体（和搜索引擎）会降低信任度。一个 2019 年的文档页面如果没有任何新鲜度信号，就和昨天才更新的页面没有区别。评分。 2 = 存在 JSON-LD 的 `dateModified` 或 HTTP `Last-Modified` 头 · 0 = 两者皆无。改进。要么在 JSON-LD 块中加入 `"dateModified": "2026-05-28"`，要么让 CDN/服务器发出 `Last-Modified` HTTP 头。大多数静态站点生成器在构建时套用模板即可免费做到这一点。证据。 https://docs.netlify.com /rubric#b4 · 文章	缺失	0/2
`B5`	机器可读的分类法（关键词、标签、类别）打了标签的文档可帮助智能体在不解析全文的情况下进行筛选（如“给我看与鉴权相关的页面”）。`<meta name="keywords">`、JSON-LD 的 `keywords`，或形如 `/tags/` 的 URL 都算数。评分。 2 = 至少存在一种分类法信号（meta keywords、JSON-LD keywords，或 /tags\|/categories\|/topics/ 风格的链接模式）· 0 = 都没有。改进。为每个页面加上 `<meta name="keywords" content="api,auth,oauth">`，或在 JSON-LD 中加入 `keywords` 数组，或将内容组织到 `/topics/`、`/tags/` 等 URL 前缀之下。证据。 https://docs.netlify.com /rubric#b5 · 文章	缺失	0/2
`B6`	用 <main> 或 <article> 包裹主体正文内容语义化的 HTML5 包裹元素让智能体（和屏幕阅读器）能剥离导航、页脚、侧边栏，只读文档正文。如果页面正文全是 `<div>`，就只能靠猜了。评分。 2 = `<main>` 内文本 >200 字符且 `<article>` 内文本 >100 字符 · 1 = 仅有 `<main>`，或仅有 `<article>` · 0 = 两者皆无。改进。用 `<main>` 包裹页面的主体正文（单个文档页面可用 `<article>`）。不要拿它们去包侧边栏或导航——这些标签是给真正的内容用的。证据。 https://docs.netlify.com /rubric#b6 · 文章	部分通过	2/3
`C1a`	在可发现的 URL 上提供 OpenAPI / Swagger / AsyncAPI 规范 OpenAPI 规范是 REST API 首要的机器可读契约。找到它的智能体无需读取任何 HTML，就能生成客户端、测试用例和准确的文档。评分。 8 = 在标准探测路径（/openapi.json、/swagger.yaml、/v1/openapi.json 等）上找到 · 5 = 仅通过 HTML 链接发现 · 0 = 什么都没找到。改进。在主机根目录（或文档路径之下——Phase 53 两处都会探测）发布 `/openapi.json` 或 `/openapi.yaml`。对于 OpenAPI 优先的项目，构建工具本就会产出它——把它暴露出来即可。证据。 https://docs.netlify.com /rubric#c1a · 文章	缺失	0/8
`C1b`	有效的 OpenAPI 3.x：含 info、≥1 条 path 及响应模式找到一份规范（C1a）只是成功了一半；规范还必须是有效的 3.x，并且描述了响应模式，智能体才能知道会拿到什么。一份只列出 path 却没有响应结构的规范，只是半份契约。评分。 7 = OpenAPI 3.x + 有效 info + path + ≥30% 的操作含响应内容模式 · 6 = 有 path 但模式很少 · 3 = 回退到 Swagger 2.0 · 0 = 解析错误。改进。如果还在用 Swagger 2.0，请升级到 OpenAPI 3.0 或 3.1。为每个操作加上 `responses: { '200': { content: { 'application/json': { schema: ... } } } }`——正是这些模式让规范对客户端有用。证据。 https://docs.netlify.com — C1a did not find a spec body /rubric#c1b · 文章	unknown	0/7
`C2`	可发现下载/fork 的 Postman 集合或 SDK OpenAPI 规范让智能体能生成客户端；而精心整理的 Postman 集合或预构建的 SDK 能让“人”在 30 秒内试用 API。两者都体现了对开发者体验的投入。评分。 4 = 含 Postman 集合链接且有 ≥1 个 SDK 仓库链接 · 3 = 含 Postman 或 ≥2 个 SDK 链接 · 2 = 1 个 SDK 链接 · 0 = 什么都没有。改进。发布一个指向 god.gw.postman.com/run-collection 的“Run in Postman”按钮，并在文档首页直接链接到至少一个来自 npm/PyPI/RubyGems 等的官方 SDK。证据。 https://www.npmjs.com/package/pg /rubric#c2 · 文章	部分通过	2/5
`C3`	端点页面展示方法、URL、类型、是否必填及示例一个只写着“调用 /users”的文档页面毫无用处——缺了方法、参数类型、必填字段，以及示例请求/响应。智能体（和人）需要这五样齐全才能发起一次可用的调用。评分。 5 = 抽样页面中多数被 ML 模型判定为 `complete` · 3 = 多数为 `partial`（或 2 个 complete + 1 个 absent）· 1 = 多数为 `absent` · 0 = 未找到候选页面。改进。在每个端点页面包含：HTTP 方法 + 路径、带类型和必填标记的参数表、一个 curl 示例，以及一个带状态码的 JSON 响应示例。Markdown 风格的参数表和 `<pre>` JSON 块能被清晰地分类识别。证据。 https://docs.netlify.com/build/data-and-storage/netlify-database/api/ — ml: majority=partial /rubric#c3 · 文章	部分通过	3/5
`D1`	代码示例同时包含 curl 与至少一种语言 SDK curl 示例普遍可被直接测试；SDK 示例则展示地道的用法。两者结合，既满足“能不能快速试一下？”的需求，也满足“我该如何集成？”的需求。评分。 4 = 至少 1 个页面同时含 curl 与语言 SDK 代码块 · 2 = 仅有 curl · 1 = 仅有 SDK · 0 = 两者皆无。改进。为每个端点加一个分页签的代码块，至少包含 curl 与你最常用的 SDK 语言（Python 或 JavaScript）。使用 `<code class="language-python">` 或 `language-bash`，让语法高亮器和我们的分类器都能识别。证据。 https://docs.netlify.com/api-and-cli-guides/api-guides/get-started-with-api/ /rubric#d1 · 文章	部分通过	2/4
`D2`	示例贴近真实（而非 foo/bar/example.com） `/users/{id}` 配上 `id = 1`、`email = [email protected]`，会迫使读者去想象真实数据长什么样。贴近真实的占位值（如 `[email protected]`、`org_2N5x...`）能降低使用阻力，也能避免直接从文档复制粘贴而出错。评分。 4 = ML 模型判定占位符密集的代码块 <20% · 3 = 20-40% · 2 = 40-60% · 1 = 60-80% · 0 = >80% 或没有代码块。改进。把 `foo`/`bar`/`example.com`/`your_api_key`/`<string>` 替换为看起来真实的值（如 Stripe 的 `pk_test_51N5...`、Twilio 的 `+14155552671`）。不要使用真实的客户数据——但要模仿其形态。证据。 https://docs.netlify.com/build/data-and-storage/netlify-database/api/ — ml: P(placeholder)>0.6 per block /rubric#d2 · 文章	部分通过	2/4
`D3`	错误目录：含 HTTP 状态码 + 原因说明当集成在凌晨 3 点出故障时，开发者需要在不提工单的情况下弄清 `403 - resource_not_owned` 到底意味着什么。一个专门的错误参考页面，决定了这是一次 5 分钟的修复还是半小时的调试。评分。 3 = 专门的错误页面（≥3 个状态码并附说明）· 1 = 错误码散落在各页面内联记录 · 0 = 没有。改进。发布 `/errors`（或 `/reference/errors`），列出你会返回的每个 HTTP 状态码 + 应用级错误码 + 每个错误一句话的成因说明。用表格效果不错，`<dl>` 定义列表也可以。证据。 https://docs.netlify.com/manage/monitoring/observability/reference/status-codes/ /rubric#d3 · 文章	通过	3/3
`D4`	同时记录了鉴权与限流鉴权是基本盘；而限流则关系到开发者能否判断自己的集成是否扛得住生产负载。两者都应放在从首页就能发现的顶级文档页面上。评分。 3 = 鉴权与限流都有记录 · 2 = 仅有鉴权 · 1 = 仅有限流 · 0 = 两者皆无。改进。增加 `/authentication`（bearer / API-key / OAuth 流程）和 `/rate-limits`（每分钟请求数、`X-RateLimit-Remaining` 等响应头、429 重试语义）页面。每个页面都需要至少 200 字符的说明——而不只是一段代码片段。证据。 https://docs.netlify.com/build/data-and-storage/netlify-database/api/ /rubric#d4 · 文章	通过	3/3
`D5`	提供术语表，或跨页面术语保持一致到底叫“工作区”、“团队”还是“组织”？选定一个术语并在所有文档中一以贯之，能避免一类“X 在这里是什么意思？”的支持工单。专门的术语表最理想；用法一致也可以接受。评分。 3 = 专门的 /glossary，含 ≥3 组结构化的术语/定义对 · 2 = 无术语表，但跨页面术语保持一致（主导写法占比 ≥80%）· 1 = 有术语表链接但内容稀少 · 0 = 两者皆无。改进。用 `<dl>` 发布 `/glossary`，以 `<dt>术语</dt><dd>定义</dd>` 成对呈现（或用定义不少于 50 字符的两列表格）。同一术语在所有页面中保持相同的大小写与拼写。证据。 https://docs.netlify.com — no glossary; 25/25 term groups consistent (0% inconsistent across 4 pages) /rubric#d5 · 文章	部分通过	2/3
`D6`	已废弃 / beta 端点以纯文本明确标注开发者把你 2022 年的代码示例粘到 2026 年的项目里，不应该到运行时才发现该端点已被废弃。在文档中显式标注 `deprecated`/`beta`/`sunset`，能省去迁移时的麻烦。评分。 2 = OpenAPI 规范中含 `deprecated`，或 ≥2 个样本页面在端点标题附近标注 · 1 = 出现 beta/experimental 等关键词但无废弃标记 · 0 = 没有。改进。在 OpenAPI 中为每个已废弃端点标注 `deprecated: true`，并在 HTML 文档中加一个可见的徽标或提示框（如 Mintlify 的 `<Warning>`、Docusaurus 的 admonition 语法等）。beta 端点同理——要在正文中可见，而不能只写在规范里。证据。 https://docs.netlify.com/deploy/deploy-types/branch-deploys/ /rubric#d6 · 文章	部分通过	1/3
`E1`	无需 JavaScript 即可在纯 HTML 中看到内容（门禁项）这是“门禁”准则。如果你的文档只有在 JavaScript 运行后才渲染（即单页应用外壳），那么抓取原始 HTML 的智能体将一无所获。网络爬虫、抓取器、curl 以及大多数 AI 抓取程序都不会执行 JS。评分。 6 = 在各 UA 模式下，首页或 2 个子页面中至少一个的正文文本 >500 字符 · 3 = 首页通过但子页面为 SPA · 0 = 处处都是 SPA 外壳，或命中 VK 陷阱（3 个以上 URL 返回完全相同的正文）。改进。在静态 URL 上提供预渲染的 HTML。如果你用 Next.js/Nuxt/SvelteKit，请为文档部分启用 SSG 或 SSR。单页应用外壳（React SPA、未做 SSR 的 Vue SPA）会无法通过这道门禁，并连带把许多其他准则一并清零。证据。 https://docs.netlify.com /rubric#e1 · 文章	通过	6/6
`E2`	稳定 URL：用 301 重定向保留旧路径当你重新组织文档时，旧链接不应返回 404——而应 301 跳转到新 URL。稳定的 URL 是来自博客、Stack Overflow 和书签的内部链接在你重构后仍能存活的关键。评分。 2 = 抽样的 2 个 URL 变体中 ≥1 个有稳定的 301/308 重定向 · 1 = canonical 别名模式（返回 200 并带 `<link rel=canonical>`）· 0 = 302（非永久）、404 或无重定向。改进。更改文档 URL 时，从旧路径加一个 301 重定向到新路径。静态站点生成器可通过 `_redirects`（Netlify）或 `vercel.json` 的 `redirects:`（Vercel）配置来处理。证据。 https://docs.netlify.com/api-and-cli-guides/api-guides/get-started-with-api /rubric#e2 · 文章	通过	2/2
`E3`	在 URL 路径、标题或 OpenAPI 规范中显式标注 API 版本 `/v1/users` 对 `/v2/users` 是一种既省事又能让智能体一目了然的 API 版本管理方式。仅存在于请求头（而不在路径或文档标题中）的版本元数据，对爬虫是不可见的。评分。 2 = 版本出现在文档自身的 URL 结构中（站点地图或 OpenAPI 规范 URL：`/v1/`、`/2024-01-15/`） · 1 = 版本出现在文档化的 API 端点 URL（curl/代码示例）、OpenAPI 的 `info.version` 或 `<h1>`/`<h2>`/页脚标题中 · 0 = 没有。改进。为 API 路径加上 `/v1/`、`/v2/` 前缀，并在 curl/代码示例中展示它们；或在 OpenAPI 规范中设置非空的 `info.version`。按日期版本化的 API（`/2024-01-15/users`）同样计入。证据。 https://docs.netlify.com /rubric#e3 · 文章	缺失	0/2
`E4`	抽查 5 条内部链接 → 全部返回 200 经过多年迭代后，失效的内部链接是文档最常见的故障模式。抽查 5 条链接能在不爬取每一条链接的前提下，揪出最严重的情况（首页上的链接直接返回 4xx/5xx）。评分。 2 = 抽样的同主机链接中 5/5 返回 200 · 1 = 4/5 · 0 = ≤3/5，或在首页找到的不同同主机链接不足 5 条。改进。在 CI 中运行链接检查工具（lychee、htmltest、linkinator）。对于首页上流量最大的链接，发布前先修掉所有 404。首页上有 5 条可用链接是最低要求。证据。 https://docs.netlify.com/ /rubric#e4 · 文章	通过	2/2
`E5`	使用条款：明确的 TOS / 许可证 / AI 策略没有明确的 TOS 或 AI 使用策略，每个 LLM 抓取器就只能猜测你的立场。增加一个内容充实的 `/terms` 或 `/license` 页面——尤其是带有 AI/ML 关键词的页面——能让策略变得机器可读。评分。 2 = 找到 TOS 页面且其正文含 AI/ML 策略关键词 · 1 = 找到 TOS（内容充实但无 AI 关键词，或链接存在但页面 404/内容稀少）· 0 = 没有 TOS 链接。改进。发布 `/terms`（或 `/legal`、`/license`），至少含 1000 字符的策略文本。就 AI 抓取、模型训练和自动化访问给出明确表述——即使你允许一切，把它说出来本身就是信号。证据。 https://docs.netlify.com /rubric#e5 · 文章	缺失	0/3

标准

状态

得分

A1

主机根目录下的 llms.txt 符合 llmstxt.org 规范

智能体（以及初次接触站点的人）需要一份单一、可预期的索引来定位文档所在位置。/llms.txt 正是 Anthropic 与 llmstxt.org 社区共同提出的约定：在主机根目录放置一个 Markdown 文件，给出文档地图。

评分。 2 = 含 H1 + ≥1 个 H2 + ≥3 条链接，且全部可正常访问 · 1 = 任意带 H1 的文件（若链接无法访问，则从 2 降级）· 0 = 缺失或仅为 HTML 外壳。

改进。 在主机根目录发布 /llms.txt，包含一个 `# H1` 标题、若干 `## H2` 小节标题，以及至少三条指向具体文档页面的 Markdown 列表链接。规范详见 https://llmstxt.org 。

证据。 https://docs.netlify.com/llms.txt

/rubric#a1 · 文章

通过

5/5

A2

存在 llms-full.txt 或按小节拆分的 LLM 聚合文件

/llms-full.txt 是把文档全文汇总到一处的导出文件——大语言模型智能体更愿意直接读它，而非爬取 200 个 HTML 页面。按小节拆分的变体（如 /llms-api.txt 等）同样有效。

评分。 3 = 主机根目录下存在 /llms-full.txt 且大于 1 KB · 2 = 通过 llms.txt 发现按小节拆分的聚合文件 · 0 = 两者皆无，或 /llms-full.txt 仅为 SPA 外壳。

改进。 在构建时生成 /llms-full.txt（mkdocs、docusaurus 均有相应插件），并以 text/plain 提供。文件应控制在 100 MB 以内，以便智能体无需流式传输即可获取。

证据。 https://docs.netlify.com/llms-full.txt

/rubric#a2 · 文章

缺失

0/3

A3

robots.txt 声明了 AI 爬虫策略与绝对路径的 Sitemap

每个 AI 爬虫（GPTBot、ClaudeBot、Google-Extended、PerplexityBot、CCBot）在抓取前都会先读取 /robots.txt。为各 UA 显式声明 Allow/Disallow，再加上一条绝对路径的 `Sitemap:` 指令，就能消除关于是否索引以及索引哪些内容的歧义。

评分。 3 = 同时含显式 AI 爬虫 UA 指令与绝对路径的 Sitemap: 行 · 2 = 仅含 AI 爬虫指令 · 1 = 仅含绝对路径的 Sitemap · 0 = 两者皆无，或返回 404。

改进。 为每个主流 LLM 爬虫加上 `User-agent: GPTBot\nAllow: /`（或按策略改用 Disallow），并补一行 `Sitemap: https://example.com/sitemap.xml`。Cloudflare 的 `Content-Signal:` 指令同样计入。

证据。 https://docs.netlify.com/robots.txt

/rubric#a3 · 文章

缺失

0/3

A4

sitemap.xml 格式规范、使用绝对 URL、分类噪声低

站点地图告诉爬虫该索引什么、内容多久变更一次。一个格式规范的 `<urlset>`，其中各页面均使用绝对路径的 `<loc>` URL，表明覆盖范围真实可信；而只有一个 URL 的占位文件（或 70% 以上都是 /tag/、/category/ 噪声的文件）则提供不了任何信号。

评分。 3 = 格式规范 + ≥3 条不同路径 + 分类垃圾占比 <30% · 2 = 过于单薄（<3 条路径）或垃圾占比 30-70% · 1 = 仅格式规范 · 0 = 404 或解析错误。

改进。 在构建时生成 /sitemap.xml，将每个文档页面以绝对 URL 写入 `<loc>`，并排除 /tag/、/category/、/author/、/page= 等变体。再在 robots.txt 中用一行绝对路径的 `Sitemap:` 引用它。

证据。 https://docs.netlify.com/sitemap.xml

/rubric#a4 · 文章

通过

4/4

A5

首页发现标签：Markdown 备用版本 + OpenGraph

发现标签让智能体无需额外探测即可找到页面的 Markdown 版本，而 OpenGraph 则能把分享出去的文档链接在 Slack、Discord、Twitter 上渲染成富预览。两者都表明站点对机器消费者有所考量。

评分。 2 = 含 `<link rel=alternate type=text/markdown>` + ≥3 个不同的 `og:` 属性 · 1 = 仅有 Markdown 备用版本，或仅有 OpenGraph · 0 = 两者皆无。

改进。 在 canonical 链接旁加上 `<link rel="alternate" type="text/markdown" href="/page.md">`，并确保首页设置了 `og:title`、`og:description`、`og:image`（至少 3 个属性）。

证据。 https://docs.netlify.com

/rubric#a5 · 文章

部分通过

1/3

B1

文档页面的 .md 配套版本返回干净的 Markdown

为读文档而浏览 200 个 HTML 页面，对人来说尚可接受；但对智能体而言，这是数量级的分词开销。为每个页面提供一个 Markdown 孪生版本，可让智能体只拉取正文内容。

评分。 7 = 抽样的 3 个页面中 3 个都有可用的 .md 孪生版本 · 4 = 2/3 · 2 = 1/3 · 0 = 0/3。

改进。 在每个 HTML 页面旁提供 `{page}.md`（或 `{page}/index.md`），或者支持 `Accept: text/markdown` 内容协商并返回 `Content-Type: text/markdown`。mkdocs-material 与 docusaurus 均有相应插件。

证据。 https://docs.netlify.com/api-and-cli-guides/api-guides/get-started-with-api/

/rubric#b1 · 文章

缺失

0/7

B2

首页与样本文档页含带有效 @type 的 JSON-LD

JSON-LD 是兼容 schema.org 的方式，用来声明“本页面是一篇 Article”/“本产品是一个 SoftwareApplication”。搜索引擎、智能体和结构化数据提取器都依赖它。

评分。 4 = 首页与某个样本文档页“同时”含可解析、带 `@type` 的 JSON-LD · 3 = 两者之一 · 0 = 都没有。

改进。 在每个文档页面嵌入 `<script type="application/ld+json">{"@context":"https://schema.org","@type":"TechArticle",...}</script>`。首页则适合用 `WebApplication` 类型。

证据。 https://docs.netlify.com

/rubric#b2 · 文章

缺失

0/5

B3

首页与样本页含绝对路径的 <link rel=canonical>

canonical 链接能确定性地回答“这是 http 还是 https 版本？带不带末尾斜杠？带不带查询参数？”的问题。缺了它，智能体可能把同一份内容索引到多个 URL 之下。

评分。 3 = 首页与某个样本页“同时”含绝对路径的 canonical · 2 = 仅首页有 · 1 = 存在但为相对路径 · 0 = 缺失。

改进。 在每个页面的 `<head>` 中加上 `<link rel="canonical" href="https://example.com/page">`。URL 必须包含协议和主机名（相对路径的 canonical 虽是合法 HTML，但对跨主机的智能体而言失去了意义）。

证据。 https://docs.netlify.com

/rubric#b3 · 文章

通过

3/3

B4

新鲜度：dateModified（JSON-LD）或 Last-Modified 头

对于不声明最后更新时间的文档，智能体（和搜索引擎）会降低信任度。一个 2019 年的文档页面如果没有任何新鲜度信号，就和昨天才更新的页面没有区别。

评分。 2 = 存在 JSON-LD 的 `dateModified` 或 HTTP `Last-Modified` 头 · 0 = 两者皆无。

改进。 要么在 JSON-LD 块中加入 `"dateModified": "2026-05-28"`，要么让 CDN/服务器发出 `Last-Modified` HTTP 头。大多数静态站点生成器在构建时套用模板即可免费做到这一点。

证据。 https://docs.netlify.com

/rubric#b4 · 文章

缺失

0/2

B5

机器可读的分类法（关键词、标签、类别）

打了标签的文档可帮助智能体在不解析全文的情况下进行筛选（如“给我看与鉴权相关的页面”）。`<meta name="keywords">`、JSON-LD 的 `keywords`，或形如 `/tags/` 的 URL 都算数。

评分。 2 = 至少存在一种分类法信号（meta keywords、JSON-LD keywords，或 /tags|/categories|/topics/ 风格的链接模式）· 0 = 都没有。

改进。 为每个页面加上 `<meta name="keywords" content="api,auth,oauth">`，或在 JSON-LD 中加入 `keywords` 数组，或将内容组织到 `/topics/`、`/tags/` 等 URL 前缀之下。

证据。 https://docs.netlify.com

/rubric#b5 · 文章

缺失

0/2

B6

用 <main> 或 <article> 包裹主体正文内容

语义化的 HTML5 包裹元素让智能体（和屏幕阅读器）能剥离导航、页脚、侧边栏，只读文档正文。如果页面正文全是 `<div>`，就只能靠猜了。

评分。 2 = `<main>` 内文本 >200 字符且 `<article>` 内文本 >100 字符 · 1 = 仅有 `<main>`，或仅有 `<article>` · 0 = 两者皆无。

改进。 用 `<main>` 包裹页面的主体正文（单个文档页面可用 `<article>`）。不要拿它们去包侧边栏或导航——这些标签是给真正的内容用的。

证据。 https://docs.netlify.com

/rubric#b6 · 文章

部分通过

2/3

C1a

在可发现的 URL 上提供 OpenAPI / Swagger / AsyncAPI 规范

OpenAPI 规范是 REST API 首要的机器可读契约。找到它的智能体无需读取任何 HTML，就能生成客户端、测试用例和准确的文档。

评分。 8 = 在标准探测路径（/openapi.json、/swagger.yaml、/v1/openapi.json 等）上找到 · 5 = 仅通过 HTML 链接发现 · 0 = 什么都没找到。

改进。 在主机根目录（或文档路径之下——Phase 53 两处都会探测）发布 `/openapi.json` 或 `/openapi.yaml`。对于 OpenAPI 优先的项目，构建工具本就会产出它——把它暴露出来即可。

证据。 https://docs.netlify.com

/rubric#c1a · 文章

缺失

0/8

C1b

有效的 OpenAPI 3.x：含 info、≥1 条 path 及响应模式

找到一份规范（C1a）只是成功了一半；规范还必须是有效的 3.x，并且描述了响应模式，智能体才能知道会拿到什么。一份只列出 path 却没有响应结构的规范，只是半份契约。

评分。 7 = OpenAPI 3.x + 有效 info + path + ≥30% 的操作含响应内容模式 · 6 = 有 path 但模式很少 · 3 = 回退到 Swagger 2.0 · 0 = 解析错误。

改进。 如果还在用 Swagger 2.0，请升级到 OpenAPI 3.0 或 3.1。为每个操作加上 `responses: { '200': { content: { 'application/json': { schema: ... } } } }`——正是这些模式让规范对客户端有用。

证据。 https://docs.netlify.com — C1a did not find a spec body

/rubric#c1b · 文章

unknown

0/7

C2

可发现下载/fork 的 Postman 集合或 SDK

OpenAPI 规范让智能体能生成客户端；而精心整理的 Postman 集合或预构建的 SDK 能让“人”在 30 秒内试用 API。两者都体现了对开发者体验的投入。

评分。 4 = 含 Postman 集合链接且有 ≥1 个 SDK 仓库链接 · 3 = 含 Postman 或 ≥2 个 SDK 链接 · 2 = 1 个 SDK 链接 · 0 = 什么都没有。

改进。 发布一个指向 god.gw.postman.com/run-collection 的“Run in Postman”按钮，并在文档首页直接链接到至少一个来自 npm/PyPI/RubyGems 等的官方 SDK。

证据。 https://www.npmjs.com/package/pg

/rubric#c2 · 文章

部分通过

2/5

C3

端点页面展示方法、URL、类型、是否必填及示例

一个只写着“调用 /users”的文档页面毫无用处——缺了方法、参数类型、必填字段，以及示例请求/响应。智能体（和人）需要这五样齐全才能发起一次可用的调用。

评分。 5 = 抽样页面中多数被 ML 模型判定为 `complete` · 3 = 多数为 `partial`（或 2 个 complete + 1 个 absent）· 1 = 多数为 `absent` · 0 = 未找到候选页面。

改进。 在每个端点页面包含：HTTP 方法 + 路径、带类型和必填标记的参数表、一个 curl 示例，以及一个带状态码的 JSON 响应示例。Markdown 风格的参数表和 `<pre>` JSON 块能被清晰地分类识别。

证据。 https://docs.netlify.com/build/data-and-storage/netlify-database/api/ — ml: majority=partial

/rubric#c3 · 文章

部分通过

3/5

D1

代码示例同时包含 curl 与至少一种语言 SDK

curl 示例普遍可被直接测试；SDK 示例则展示地道的用法。两者结合，既满足“能不能快速试一下？”的需求，也满足“我该如何集成？”的需求。

评分。 4 = 至少 1 个页面同时含 curl 与语言 SDK 代码块 · 2 = 仅有 curl · 1 = 仅有 SDK · 0 = 两者皆无。

改进。 为每个端点加一个分页签的代码块，至少包含 curl 与你最常用的 SDK 语言（Python 或 JavaScript）。使用 `<code class="language-python">` 或 `language-bash`，让语法高亮器和我们的分类器都能识别。

证据。 https://docs.netlify.com/api-and-cli-guides/api-guides/get-started-with-api/

/rubric#d1 · 文章

部分通过

2/4

D2

示例贴近真实（而非 foo/bar/example.com）

`/users/{id}` 配上 `id = 1`、`email = [email protected]`，会迫使读者去想象真实数据长什么样。贴近真实的占位值（如 `[email protected]`、`org_2N5x...`）能降低使用阻力，也能避免直接从文档复制粘贴而出错。

评分。 4 = ML 模型判定占位符密集的代码块 <20% · 3 = 20-40% · 2 = 40-60% · 1 = 60-80% · 0 = >80% 或没有代码块。

改进。 把 `foo`/`bar`/`example.com`/`your_api_key`/`<string>` 替换为看起来真实的值（如 Stripe 的 `pk_test_51N5...`、Twilio 的 `+14155552671`）。不要使用真实的客户数据——但要模仿其形态。

证据。 https://docs.netlify.com/build/data-and-storage/netlify-database/api/ — ml: P(placeholder)>0.6 per block

/rubric#d2 · 文章

部分通过

2/4

D3

错误目录：含 HTTP 状态码 + 原因说明

当集成在凌晨 3 点出故障时，开发者需要在不提工单的情况下弄清 `403 - resource_not_owned` 到底意味着什么。一个专门的错误参考页面，决定了这是一次 5 分钟的修复还是半小时的调试。

评分。 3 = 专门的错误页面（≥3 个状态码并附说明）· 1 = 错误码散落在各页面内联记录 · 0 = 没有。

改进。 发布 `/errors`（或 `/reference/errors`），列出你会返回的每个 HTTP 状态码 + 应用级错误码 + 每个错误一句话的成因说明。用表格效果不错，`<dl>` 定义列表也可以。

证据。 https://docs.netlify.com/manage/monitoring/observability/reference/status-codes/

/rubric#d3 · 文章

通过

3/3

D4

同时记录了鉴权与限流

鉴权是基本盘；而限流则关系到开发者能否判断自己的集成是否扛得住生产负载。两者都应放在从首页就能发现的顶级文档页面上。

评分。 3 = 鉴权与限流都有记录 · 2 = 仅有鉴权 · 1 = 仅有限流 · 0 = 两者皆无。

改进。 增加 `/authentication`（bearer / API-key / OAuth 流程）和 `/rate-limits`（每分钟请求数、`X-RateLimit-Remaining` 等响应头、429 重试语义）页面。每个页面都需要至少 200 字符的说明——而不只是一段代码片段。

证据。 https://docs.netlify.com/build/data-and-storage/netlify-database/api/

/rubric#d4 · 文章

通过

3/3

D5

提供术语表，或跨页面术语保持一致

到底叫“工作区”、“团队”还是“组织”？选定一个术语并在所有文档中一以贯之，能避免一类“X 在这里是什么意思？”的支持工单。专门的术语表最理想；用法一致也可以接受。

评分。 3 = 专门的 /glossary，含 ≥3 组结构化的术语/定义对 · 2 = 无术语表，但跨页面术语保持一致（主导写法占比 ≥80%）· 1 = 有术语表链接但内容稀少 · 0 = 两者皆无。

改进。 用 `<dl>` 发布 `/glossary`，以 `<dt>术语</dt><dd>定义</dd>` 成对呈现（或用定义不少于 50 字符的两列表格）。同一术语在所有页面中保持相同的大小写与拼写。

证据。 https://docs.netlify.com — no glossary; 25/25 term groups consistent (0% inconsistent across 4 pages)

/rubric#d5 · 文章

部分通过

2/3

D6

已废弃 / beta 端点以纯文本明确标注

开发者把你 2022 年的代码示例粘到 2026 年的项目里，不应该到运行时才发现该端点已被废弃。在文档中显式标注 `deprecated`/`beta`/`sunset`，能省去迁移时的麻烦。

评分。 2 = OpenAPI 规范中含 `deprecated`，或 ≥2 个样本页面在端点标题附近标注 · 1 = 出现 beta/experimental 等关键词但无废弃标记 · 0 = 没有。

改进。 在 OpenAPI 中为每个已废弃端点标注 `deprecated: true`，并在 HTML 文档中加一个可见的徽标或提示框（如 Mintlify 的 `<Warning>`、Docusaurus 的 admonition 语法等）。beta 端点同理——要在正文中可见，而不能只写在规范里。

证据。 https://docs.netlify.com/deploy/deploy-types/branch-deploys/

/rubric#d6 · 文章

部分通过

1/3

E1

无需 JavaScript 即可在纯 HTML 中看到内容（门禁项）

这是“门禁”准则。如果你的文档只有在 JavaScript 运行后才渲染（即单页应用外壳），那么抓取原始 HTML 的智能体将一无所获。网络爬虫、抓取器、curl 以及大多数 AI 抓取程序都不会执行 JS。

评分。 6 = 在各 UA 模式下，首页或 2 个子页面中至少一个的正文文本 >500 字符 · 3 = 首页通过但子页面为 SPA · 0 = 处处都是 SPA 外壳，或命中 VK 陷阱（3 个以上 URL 返回完全相同的正文）。

改进。 在静态 URL 上提供预渲染的 HTML。如果你用 Next.js/Nuxt/SvelteKit，请为文档部分启用 SSG 或 SSR。单页应用外壳（React SPA、未做 SSR 的 Vue SPA）会无法通过这道门禁，并连带把许多其他准则一并清零。

证据。 https://docs.netlify.com

/rubric#e1 · 文章

通过

6/6

E2

稳定 URL：用 301 重定向保留旧路径

当你重新组织文档时，旧链接不应返回 404——而应 301 跳转到新 URL。稳定的 URL 是来自博客、Stack Overflow 和书签的内部链接在你重构后仍能存活的关键。

评分。 2 = 抽样的 2 个 URL 变体中 ≥1 个有稳定的 301/308 重定向 · 1 = canonical 别名模式（返回 200 并带 `<link rel=canonical>`）· 0 = 302（非永久）、404 或无重定向。

改进。 更改文档 URL 时，从旧路径加一个 301 重定向到新路径。静态站点生成器可通过 `_redirects`（Netlify）或 `vercel.json` 的 `redirects:`（Vercel）配置来处理。

证据。 https://docs.netlify.com/api-and-cli-guides/api-guides/get-started-with-api

/rubric#e2 · 文章

通过

2/2

E3

在 URL 路径、标题或 OpenAPI 规范中显式标注 API 版本

`/v1/users` 对 `/v2/users` 是一种既省事又能让智能体一目了然的 API 版本管理方式。仅存在于请求头（而不在路径或文档标题中）的版本元数据，对爬虫是不可见的。

评分。 2 = 版本出现在文档自身的 URL 结构中（站点地图或 OpenAPI 规范 URL：`/v1/`、`/2024-01-15/`） · 1 = 版本出现在文档化的 API 端点 URL（curl/代码示例）、OpenAPI 的 `info.version` 或 `<h1>`/`<h2>`/页脚标题中 · 0 = 没有。

改进。 为 API 路径加上 `/v1/`、`/v2/` 前缀，并在 curl/代码示例中展示它们；或在 OpenAPI 规范中设置非空的 `info.version`。按日期版本化的 API（`/2024-01-15/users`）同样计入。

证据。 https://docs.netlify.com

/rubric#e3 · 文章

缺失

0/2

E4

抽查 5 条内部链接 → 全部返回 200

经过多年迭代后，失效的内部链接是文档最常见的故障模式。抽查 5 条链接能在不爬取每一条链接的前提下，揪出最严重的情况（首页上的链接直接返回 4xx/5xx）。

评分。 2 = 抽样的同主机链接中 5/5 返回 200 · 1 = 4/5 · 0 = ≤3/5，或在首页找到的不同同主机链接不足 5 条。

改进。 在 CI 中运行链接检查工具（lychee、htmltest、linkinator）。对于首页上流量最大的链接，发布前先修掉所有 404。首页上有 5 条可用链接是最低要求。

证据。 https://docs.netlify.com/

/rubric#e4 · 文章

通过

2/2

E5

使用条款：明确的 TOS / 许可证 / AI 策略

没有明确的 TOS 或 AI 使用策略，每个 LLM 抓取器就只能猜测你的立场。增加一个内容充实的 `/terms` 或 `/license` 页面——尤其是带有 AI/ML 关键词的页面——能让策略变得机器可读。

评分。 2 = 找到 TOS 页面且其正文含 AI/ML 策略关键词 · 1 = 找到 TOS（内容充实但无 AI 关键词，或链接存在但页面 404/内容稀少）· 0 = 没有 TOS 链接。

改进。 发布 `/terms`（或 `/legal`、`/license`），至少含 1000 字符的策略文本。就 AI 抓取、模型训练和自动化访问给出明确表述——即使你允许一切，把它说出来本身就是信号。

证据。 https://docs.netlify.com

/rubric#e5 · 文章

缺失

0/3

https://docs.netlify.com

分类

30 项标准