适用场景
当能力需要通过组装产品的各个部件才能建立时 —— 一个平台或 API，其价值只有在多个功能协同时才显现 —— 就该写教程。动手之前先认清成本： 这是搭建和维护成本最高的类型，因为教程必须在冷机器上、对每个读者、每次都成功。两个后果：
- 少而新者胜。 一篇经过测试的教程胜过五篇过期的；坏掉的教程不仅让任务失败，还会让新用户认定产品坏了。
- 你可能根本不需要教程。 一个好的快速开始加上若干操作指南，通常已能覆盖应用型产品和单一关注点的工具。
它不是：
- 快速开始。 快速开始在几分钟内证明产品能用；教程在一小时内通过一个有意义的项目建立能力。承诺不同，预算不同 —— 不要把快速开始拉长成课程。
- 操作指南。 操作指南服务的是能自己负责的熟练读者；教程的读者还什么都不懂，出问题时错在教程，永远不在读者。如果你发现自己假设读者已经具备能力，那你写的是操作指南。
- 概念课程。 教程靠做来教，不靠讲。任何超过一两句的解释都删掉并链接出去；Diátaxis 说：“教学的第一条规则是不要试图教” —— 提供体验，而不是讲解。
一条路径，零替代方案。教程从不提供选项（“你也可以……”）；作者已经选好了。
当技术栈确实需要不同的叙述时，每个技术栈各写一篇教程。当整个故事不同时，同级页面胜过变体标签页 —— 这也是操作指南的 “禁止同级页面” 规则在这里不适用的原因。
标题与描述
- 标题：“Build <the thing>”（构建……） —— 按成果命名：“Build an order-notification service”。不要 “Learn Hookline”，不要 “Tutorial 1”。
- 描述公式：“你将构建什么，以及之后你能做什么。时间估计。” —— 例如 “构建一个在订单发货时给客户发邮件的服务。完成后你将掌握 Hookline 的发送—投递—验证完整闭环。约 30 分钟。”
脚手架生成本页
安装配方 —— 你的编码智能体会读取完整骨架和清单，并根据你的产品做调整：
npx @cloudflare/nimbus-docs add content-tutorial
yarn nimbus-docs add content-tutorial
pnpm nimbus-docs add content-tutorial
bunx @cloudflare/nimbus-docs add content-tutorial组件建议
- 带预期输出块的编号部分是骨架 —— 每部分之后的输出是信心机器；永远不要省略。
- 把错误恢复写成普通散文，放在读者真正会绊倒的地方，在这里属于正常路径内容 —— 不用例外提示框，因为在教程里可预期错误不是例外。一篇预判了三种常见错误的教程，比假装它们不会发生的教程教得更多。
- 不适合： 任何形式的标签页和选项（作者已选；按技术栈区分意味着按页面区分）、卡片、长篇概念插叙（链接出去）、藏起步骤的折叠面板。
结尾
固定页脚，按顺序：清理（即使没有可删的内容也写一行）→ 你构建了什么（回顾）→ 下一步。回顾之所以值得占位，是因为读者是在获得能力，而不是在完成任务：点明他们现在会了什么，是教学的一部分。
阈值
- ≤ 约 7 部分，15–60 分钟，开头如实说明，并给出具体难度代理指标（约多少行代码、涉及哪些服务）。
- 每处解释 ≤ 2 句 —— 然后给链接。
- 零决策、零替代、零未解释的魔法 —— 如果某一步 “因为某些原因” 就能工作，要么用一行说明原因，要么链接出去。
- 它每次都成功。 不是通常。是每次 —— 这是本类型的定义性契约，也是它昂贵的原因。阶段性故障 —— 作者故意注入错误并保证其恢复 —— 不违反契约。
链接与时效
部分之间几乎不要放链接（出口会打断叙述）；概念与生产环境相关链接放在下一步。本类型腐化速度仅次于快速开始，而且坏得更狠：在 “开始之前” 固定每个版本，在每个触及该路径的版本上用冷环境重跑整篇教程，并盖上 lastVerified。如果承担不起这种维护，就少发一篇教程。
智能体说明
- 智能体会端到端执行教程；每部分的 “你应该看到” 区块是它们的验收检查 —— 每部分一个，逐字保留，会变化的字段用占位符（
<n>ms）。 - 固定版本对智能体加倍重要：它们无法判断演练是否已偏离
latest；它们会把演练强行套到已安装的版本上。 - 部分标题要带完整上下文（“4. 强制重投并观察去重将其吸收”，而不是 “故意弄坏它”）—— 部分会被单独检索。
- 阶段性故障部分是高价值的智能体内容：它在一个可检索块中同时记录了故障特征和恢复方法。
检查清单
建议性 —— 供作者或智能体自检，永不作为构建闸门：
- 标题为 “Build <成果>”；第 1 部分之前就展示目的地
- 开头给出学习目标（3–5 条）、时间估计和具体难度代理指标
- 在 “开始之前” 固定版本；点名了哪些部分是模拟的
- 每部分都以可见、逐字的结果结束；标题自带上下文
- 在易出错处给出错误恢复说明；不责怪读者
- 零选项、零替代；解释 ≤ 2 句，然后给链接
- ≤ 约 7 部分；诚实的 15–60 分钟范围
- 结尾为 清理（至少一行）→ 你构建了什么 → 下一步
- 本版本已在冷环境端到端重跑；已盖上
lastVerified