--- title: "概念" description: "解释产品的心智模型：它是什么、为什么这样设计、何时该用它。" --- > Documentation Index > Fetch the complete documentation index at: https://nimbus.ndjp.net/llms.txt > Use this file to discover all available pages before exploring further. # 概念 > **需求** > > 处于学习、正在思考 —— 读者已经能操作产品，或即将开始操作，想要的是心智模型：这个东西*是什么*、为什么这样设计、什么时候该用它。他们的第一个问题：*“X 到底是什么？”* > > 这是最被忽视的类型，也是手写质量最重要的类型：参考和流程越来越多由机器阅读，而心智模型仍属于人类层。 ## 适用场景 当读者在其他页面中间反复需要同一种解释时，就该写概念页 —— 这是模型值得拥有独立归宿的信号。它不是： - **操作指南。** 硬边界是**没有过程步骤、没有配置演练**。示意性代码是欢迎的，只要它展示想法，而不是要求读者跟着做。判断边界片段的测试：删掉它如果失去的是一个例子，它就是示意性的；删掉它如果失去的是操作说明，它就是演练。 - **参考。** 参考完整且中立；概念有选择、有观点。概念页应当表明立场 —— 这是唯一适合出现 “我们推荐” 和设计理由的类型。 - **概览。** 概览做路由；概念做解释。如果页面大部分是链接，那就是一个戴错标题的概览。 一页一个概念。“投递与签名” 是两个页面，中间加一个链接。 ## 标题与描述 - **标题：命名该概念的简洁名词短语。** “投递保证。”“Webhook 签名。” 避免 “概览”“介绍”“工作原理”，因为它们命名的是体裁而不是主题，并会与所有同名页面冲突。自检：好的概念标题前面加上 “关于” 仍然自然（“关于投递保证” ✓）。 - **描述公式：**“*概念是什么*，以及*它对读者代码或选择意味着什么*。” —— 例如 “Hookline 对投递保证了什么 —— 以及你的端点仍须自行处理什么。” ## 脚手架生成本页 安装配方 —— 你的编码智能体会读取完整骨架和清单，并根据你的产品做调整： ```sh npx @cloudflare/nimbus-docs add content-concept yarn nimbus-docs add content-concept pnpm nimbus-docs add content-concept bunx @cloudflare/nimbus-docs add content-concept ``` ## 组件建议 - **散文是主要组件。** 短段落，每节一个想法 —— 这是写作质量支撑页面的类型。 - **示意图和示意性代码/载荷**在能展示模型时适用；示意图始终要配文字等价物。 - **对比表**在 “边界” 部分有真正的二选一时适用。 - **不适合：** Steps（本类型的定义性禁令）、Tabs（概念不会因平台而异 —— 若真如此，那是两个概念）、卡片。 ## 结尾 **边界 → 另见。** 以范围收尾是最能定义本类型的做法。在易混淆的邻居旁边说明这个概念*不是什么*，是让模型扎根的最便宜方式。 ## 阈值 - **到第二段结束时给出一个浅显但正确的模型。** 如果读者必须读完整页才能避免*错误*模型，说明开头顺序错了。 - **≤ 约 1,500 词**作为实用上限。明确要求从头读到尾的核心概念序列页面不受此限。*独立*概念超出上限时拆成两个概念。 - **至少一句设计理由。** 没有 “为什么” 的概念页，只是被拉长成一页的术语条目。 ## 链接与时效 概念页是枢纽：链接每一个应用该模型的操作指南和列出该模型的参考页，并从那些页面*反向*链接回来，让模型只解释一次。 概念腐化最慢，但设计变化时要重读；不再与产品匹配的 “为什么” 会误导。此处 `lastVerified` 是可选的，因为触发条件是设计变化，而不是日历。 ## 智能体说明 - 定义段落是智能体在被问到 “X 保证什么” 时检索并引用的内容 —— 它们必须自成一体、单独看也无歧义，不依赖下面的分节。 - 用可核对的措辞陈述契约（“至少一次”“按端点”“不保证顺序”），而不是安抚性形容词（“可靠”“健壮”）—— 智能体会把模糊形容词传播成错误代码。 - 边界同时也是智能体的负向知识 —— *不要*假设什么。把它们写成平铺的陈述性要点。 ## 检查清单 建议性 —— 供作者或智能体自检，永不作为构建闸门： - [ ] 标题是名词短语；不是 “概览” / “介绍” / “工作原理”；通过 “关于 X” 朗读测试 - [ ] 定义先行；到第二段给出正确的浅层模型 - [ ] 存在设计理由 —— 产品取舍，或领域约束 + 产品立场 - [ ] 零过程步骤或配置演练；代码通过示意性测试 - [ ] 有 “边界” 分节：它不是什么 + 易混淆的邻居 - [ ] 示意图（若有）配有文字等价物 - [ ] 以 “另见” 结尾，链接依赖该模型的操作指南和参考 - [ ] 独立页面 ≤ 约 1,500 词（课程序列页面除外）；一个概念 Source: https://nimbus.ndjp.net/style-guide/concept/index.mdx