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