---
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？"* 这是任何文档站点上数量最多的类型。

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

当存在**一个目标、一个结果、且读者有能力遵循指示**时使用操作指南。它不是：

- **教程。** 教程通过构建来教学；作者全程引导，不允许出错。操作指南服务于正在工作中自行推进的读者。如果页面必须对什么都不懂的读者有效，写教程。
- **参考。** 如果读者在查找一个值、一个选项或一个限制——而非执行一系列操作——那是参考。操作指南*链接*到参考；从不内联完整的选项表。
- **概念。** 当你开始用超过一句话解释*为什么*产品这样运作时，删掉并链接到概念页面。步骤中间的解释是读者迷失位置的地方。

每个页面一个目标。"轮换签名密钥"和"撤销签名密钥"是两个页面，而非一个页面的两半。注意那些将多个目标偷渡过此测试的伞状动词——"管理密钥"和"配置白名单"各自隐藏了创建、修改和删除。

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

- **标题：陈述目标的祈使动词短语。** "轮换签名密钥。" "添加第二个端点。" 不用动名词（"Rotating secrets"），不用裸名词（"Secret rotation"），不要加 "How to" 前缀——祈使动词短语本身就是类型的信号。
- **描述公式：** "*动词 + 对象，附带收益或关键约束。*"——例如 "轮换签名密钥而不丢失投递。两个密钥在重叠窗口期内都保持有效。"

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

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

```sh
npx add content-how-to
pnpm dlx add content-how-to
yarn dlx add content-how-to
bunx add content-how-to
```

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

- **带编号的步骤**是定义性结构——作为 Steps 组件或普通有序列表；两者在 `.md` 版本中必须读起来相同。如果一个页面没有步骤，质疑它是否是操作指南。
- **Tabs / 代码组**在一个规范页面*内*承载变体维度（语言、平台、CLI vs 控制台）。按变体复制页面是失败模式。对于替代*方法*，不要用标签页——选择推荐的那个并链接其余的。
- **提示框：** 在破坏性步骤之前发出警告（正常路径的一部分），以及正常路径的例外（"如果你使用的是旧版计划……"）。一个被例外提示淹没的操作指南说明正常路径选错了。
- **不适用：** Cards（此页面在 Next steps 之前不导航到任何地方）、冗长的概念旁白、完整选项表（链接到参考）。

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

固定页脚，按顺序：**验证** → 不可逆的收尾步骤（如果任务有的话）→ **可选块** → **后续步骤** 包含 2–4 个精选链接。永远不要在最后一个编号步骤结束——停在步骤 6 的页面会让读者不确定自己是否完成了。

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

- **每个阶段 ≤ ~10 个步骤。** 较长的单目标流程用 `###` 划分阶段；*目标*成倍增长的页面需要拆分。测试标准是标题：如果需要"和"，那是两个页面。
- **上下文介绍 ≤ 2 句。** 更长意味着概念内容渗入了。
- **一个目标。** 伞状动词（"管理 X"）是多个目标的标志。

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

向外链接以获取深度：概念解释为什么，参考提供数值，相邻操作指南告诉你下一步。最小化步骤*内*的链接——步骤中的每个链接都是一个出口匝道。每当功能变更时，对照实际产品重新验证步骤，并记录结果（frontmatter 中的 `lastVerified` 日期或等效方式），使过时状态可见而非事后发现——一个步骤已漂移的操作指南比没有页面更糟，因为错误的步骤会主动误导，而缺失的页面只是令人失望。

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

- 每个步骤必须脱离周围页面也能独立执行：命名产品区域、完整命令、确切设置标签——永远不要写"如上所述配置"。
- 将预期输出放在围栏块中，使用完整、真实的值——不要用 `…` 截断凭据；智能体会匹配你展示的内容。
- 标签页变体在 `.md` 版本中必须展平为带标签的章节；永远不要让步骤的唯一副本活在会丢弃内容的组件内。
- 验证章节同时充当智能体的验收检查——写成可执行的内容，并明确失败分支。

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

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

- [ ] 标题是祈使动词短语；一个目标，无伞状动词
- [ ] 前置条件完整——满足条件的读者无需离开页面即可完成
- [ ] 每个步骤：动词开头、一个动作、位置在动作之前
- [ ] 正常路径不断裂——变体维度在标签页/选择器中，替代方法已选择并链接，选项在验证之后隔离
- [ ] 警告在破坏性步骤之前；验证在高撤销成本步骤之前
- [ ] 验证存在——可执行且有失败分支，或一句不言自明的话
- [ ] 不可逆收尾步骤（删除、切换、结束重叠）在验证之后，独立章节中
- [ ] 以后续步骤（2–4 个链接）结尾，而非最后一步
- [ ] 每个阶段 ≤ ~10 个步骤；上下文 ≤ 2 句
- [ ] 无位置引用（"如上所述"）；每个章节自成一体

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