教程

何时使用

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

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

它不是：

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

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

标题和描述

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

搭建此页面

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

npx @cloudflare/nimbus-docs add content-tutorial

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

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

bunx @cloudflare/nimbus-docs add content-tutorial

组件指导

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

结尾

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

阈值

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

链接和新鲜度

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

智能体备注

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

清单

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

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