概念

何时使用

当读者在其他页面中反复需要相同的解释时，就该写一个概念页面——这就是该模型值得拥有自己页面的信号。它不是：

• 操作指南。 硬性边界是无流程步骤、无配置演练。展示想法而非要求读者跟随的说明性代码是受欢迎的。测试边界代码片段的标准：移除它会丢失一个示例，那它是说明性的；移除它会丢失操作说明，那它是演练。
• 参考。 参考是完整且中立的；概念是有选择性且有立场的。概念页面应该表明立场——这是唯一适合“我们推荐”和设计理由的类型。
• 概览。 概览负责导航；概念负责解释。如果页面大部分是链接，那它就是一个戴着错误标题的概览。

每个页面一个概念。“投递和签名”应该是两个页面，中间有链接。

标题和描述

• 标题：简洁的名词短语，命名概念。 “投递保证。” “Webhook 签名。” 避免使用 “Overview”、“Introduction” 和 “How it works”，因为它们命名的是体裁而非主题，且与所有同名页面冲突。自检：一个好的概念标题在前面加上 “About” 后仍然自然可读（“About delivery guarantees” ✓）。
• 描述公式： “概念是什么以及它对读者的代码或选择意味着什么。”——例如 “Hookline 关于投递的保证——以及你的端点仍然必须自行处理的内容。”

搭建此页面

安装指南——你的编码智能体会读取完整的骨架和清单，并将其适配到你的产品：

npx @cloudflare/nimbus-docs add content-concept

yarn dlx @cloudflare/nimbus-docs add content-concept

pnpm dlx @cloudflare/nimbus-docs add content-concept

bunx @cloudflare/nimbus-docs add content-concept

组件指导

• 散文是主要组件。 短段落，每节一个想法——这是写作质量承载页面的类型。
• 图表和说明性代码/载荷在展示模型时适用；图表始终配有文字等效描述。
• 对比表格在确实存在非此即彼的情况下适用于边界部分。
• 不适用： Steps（明确禁止）、Tabs（概念不因平台而异——如果是，那是两个概念）、Cards。

结尾

边界 → 另请参阅。 以范围收尾是这种类型最大的特点。说明概念不是什么，紧挨着容易混淆的相邻概念，是让模型扎根的最廉价方式。

阈值

• 到第二段结束时建立浅层但正确的模型。 如果读者必须读完页面才能避免形成错误模型，说明开头顺序有问题。
• ≤ ~1,500 字作为实际限制。明确有序的、旨在从头到尾阅读的核心概念序列中的页面不受此限。独立概念超出上限时拆分为两个概念。
• 至少一句设计理由。 没有“为什么”的概念页面只是被拉长成页面的术语表条目。

链接和新鲜度

概念页面是枢纽：链接每一个应用该模型的操作指南和枚举它的参考——并从这些页面反向链接，这样模型只解释一次，处处引用。概念退化最慢，但当它们所支撑的设计发生变化时要重新阅读——一个不再匹配产品的“为什么”会主动误导。lastVerified 标记在此处可选；触发条件是设计变更，而非日历。

智能体备注

• 定义段落是智能体在被问及“X 保证什么”时检索和引用的内容——它们必须自成一体，脱离下方章节后仍然无歧义。
• 用可验证的术语陈述契约（“至少一次”、“按端点”、“无序”），而非安抚性术语（“可靠的”、“健壮的”）——智能体会将模糊形容词传播为错误代码。
• 边界同时充当智能体的否定知识——不要假设什么。写成扁平的声明性要点。

清单

建议性——供作者或智能体自查，不是构建门禁：

• 标题是名词短语；不是 “Overview” / “Introduction” / “How it works”；通过 “About X” 朗读测试
• 定义先行；到第二段建立正确的浅层模型
• 设计理由存在——产品权衡，或领域约束 + 产品立场
• 零流程步骤或配置演练；代码通过说明性测试
• 边界章节：它不是什么 + 易混淆的相邻概念
• 图表（如有）配有文字等效描述
• 以另请参阅结尾，链接依赖此模型的操作指南和参考
• 独立页面 ≤ ~1,500 字（课程序列页面豁免）；一个概念