---
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.

# 教程

> **需求**
>
> 在学习中行动——边做边学。读者是新手，想要能力而非仅仅一个结果；教师承担**全部**责任（Diátaxis 最难的规则）。他们的问题是：*"教我用这个构建真实的东西。"*

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

当能力需要*组装*产品的各个部分时编写教程——一个平台或 API 的价值只有在多个功能协同工作时才显现。**在开始之前了解成本：** 这是构建和维护最昂贵的类型，因为教程必须对每个读者、每次都有效，在一台冷机器上。两个后果：

- **最少且最新鲜的胜出。** 一个经过测试的教程胜过五个过时的；一个坏掉的教程不仅任务失败，还会让新手相信*产品*坏了。
- **你可能根本不需要。** 一个好的快速入门加操作指南通常覆盖类应用产品和单关注点工具。

它不是：

- **快速入门。** 快速入门在几分钟内证明产品能用；教程通过一个有意义的项目在一小时内建立能力。不同的承诺，不同的预算——不要把快速入门拉长为课程。
- **操作指南。** 操作指南服务于有能力自行推进的读者；教程的读者还什么都不懂，当出错时**是教程的错，永远不是读者的错**。如果你发现自己假定能力，你写的其实是操作指南。
- **概念课程。** 教程通过做来教，而非解释。超过一两句的解释都删掉并链接；Diátaxis："教学的第一条规则是不要试图教"——提供体验。

一条路径，零替代方案。教程从不提供选项（"你也可以……"）——作者已经选好了。当不同技术栈确实需要不同叙述时，按技术栈各出一个教程——就像按技术栈出的快速入门一样，当*整个故事*不同时，兄弟页面优于变体标签页。（这是对操作指南"永不兄弟页面"规则的授权例外，该规则仅适用于只有代码块变化的页面。）

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

- **标题：** "Build \<成果\>"——按成果命名："Build an order-notification service。" 不是 "Learn Hookline"，不是 "Tutorial 1"。
- **描述公式：** "*你将构建什么*，以及*之后你能做什么*。*时间估计*。"——例如 "构建一个在订单发货时邮件通知客户的服务。之后你将了解 Hookline 完整的发送-投递-验证循环。大约 30 分钟。"

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

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

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

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

- **带编号的部分和预期输出块**是脊柱——每个部分之后的输出是信心机器；永远不要跳过。
- **错误恢复作为普通散文**在读者实际绊倒的地方——这里属于正常路径内容，不是异常提示框，因为在教程中预判的错误不是异常。一个预判三个可能错误的教程比假装它们不会发生的教程教得更多。
- **不适用：** 任何类型的标签页和选项（作者已选；按技术栈意味着按页面）、Cards、冗长的概念旁白（链接出去）、隐藏步骤的折叠面板。

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

固定页脚，按顺序：**清理**（即使没有可删除的内容也要写一行）→ **你构建了什么**（回顾）→ **后续步骤**。回顾之所以值得存在，是因为读者是在获取技能，而非完成任务：命名他们现在知道的东西是教学的一部分。

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

- **≤ ~7 个部分**，**15–60 分钟**，提前诚实说明并附具体难度指标（约代码行数、涉及的服务）。
- **每次出现的解释 ≤ 2 句**——然后链接。
- **零决策、零替代、零未解释的魔术**——如果一个步骤"因为某些原因"有效，要么一行展示原因，要么链接。
- **每次都有效。** 不是通常有效。每次都有效——这是类型的决定性契约，也是它昂贵的原因。分阶段故障——教师注入故障然后保证恢复——不违反契约。

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

部分中间几乎没有链接（出口打断叙事）；概念和生产链接在后续步骤中。这种类型退化速度仅次于快速入门，且破坏更严重：**在开始前固定每个版本**，在每次涉及该路径的发布时在冷环境上端到端重跑整个教程，并盖上 `lastVerified`。如果你承担不起这个维护，少发布一个教程。

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

- 智能体端到端执行教程；每个部分的"You should see"块是它们的验收检查——每个部分一个，逐字，运行时变化字段用占位符（`<n>ms`）。
- 固定版本对智能体加倍重要：它们无法判断演练是否已从 `latest` 漂移；它们会强制演练使用已安装的版本。
- 完整上下文的部分标题（"4. 强制重新投递并观察去重吸收它"，永远不是"故意弄坏它"）——部分会被单独检索。
- 分阶段故障部分是高价值的智能体内容：它在一个可检索的块中同时记录了故障特征*和*恢复方法。

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

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

- [ ] 标题是 "Build \<成果\>"；在部分 1 之前展示目的地
- [ ] 学习目标（3–5 个）、时间估计、以及具体的难度指标提前说明
- [ ] 版本在开始前固定；模拟部分已命名
- [ ] 每个部分以可见的、逐字的结果结束；标题自成一体
- [ ] 错误恢复散文在可能绊倒的地方；不责怪读者
- [ ] 零选项或替代方案；每次解释 ≤ 2 句然后链接
- [ ] ≤ ~7 个部分；诚实的 15–60 分钟范围
- [ ] 以清理（最少一行）→ 你构建了什么 → 后续步骤结尾
- [ ] 在冷环境上端到端重跑过本次发布；已盖上 `lastVerified`

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