---
title: "概念"
description: "理解性页面的指南——一个事物是什么、为什么这样设计、以及它的边界在哪里。无步骤、无操作说明。包含清单和搭建命令。"
---

> Documentation Index
> Fetch the complete documentation index at: https://nimbus-docs.cn/llms.txt
> Use this file to discover all available pages before exploring further.

# 概念

> **需求**
>
> 在学习中反思——读者已经能操作产品（或即将开始），想要获得心智模型：这个东西*是*什么、为什么这样设计、什么时候该用它。他们的问题是：*"X 到底是什么？"* 这是长期被忽视的类型——每项调查和 Diátaxis 本身都这么说——也是手写质量最能拉开差距的类型，因为参考和流程越来越被机器消费，而心智模型仍然是人类的层次。

<h2 id="when-to-use-it">何时使用</h2>

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

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

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

<h2 id="title--description">标题和描述</h2>

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

<h2 id="scaffold-this-page">搭建此页面</h2>

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

```sh
npx add content-concept
pnpm dlx add content-concept
yarn dlx add content-concept
bunx add content-concept
```

<h2 id="component-guidance">组件指导</h2>

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

<h2 id="ending">结尾</h2>

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

<h2 id="thresholds">阈值</h2>

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

<h2 id="links--freshness">链接和新鲜度</h2>

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

<h2 id="agent-notes">智能体备注</h2>

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

<h2 id="checklist">清单</h2>

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

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

Source: https://nimbus-docs.cn/writing/recipes/concept/index.mdx