--- 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. # 操作指南 > **需求** > > 处于工作、正在行动 —— 读者已经知道自己想要什么，需要的是步骤，不是理论。他们的第一个问题：*“我怎么做 X？”* 这是任何文档站上数量最多的类型。 ## 适用场景 当**一个目标、一个结果，且读者足以独立按说明操作**时，使用操作指南。它不是： - **教程。** 教程通过构建东西来教学；作者全程扶着读者，不允许出错。操作指南服务的是正在任务中、能自己负责的读者。如果页面必须让一无所知的读者也能完成，请写教程。 - **参考。** 如果读者是在查一个值、一个选项或一个限制 —— 而不是在执行一串操作 —— 那就是参考。操作指南*链接*到参考；绝不内联完整的选项表。 - **概念。** 一旦你解释*为什么*产品这样工作超过一句，就删掉并链接到概念页。步骤中间的解释正是读者丢失位置的地方。 一页一个目标。“轮换签名密钥” 和 “吊销签名密钥” 是两个页面，不是一页分两半。注意那些把多个目标偷渡过关的伞形动词 —— “管理密钥” 和 “配置允许列表” 各自藏着创建、修改和删除。 ## 标题与描述 - **标题：陈述目标的祈使动词短语。** “轮换签名密钥。”“添加第二个端点。” 不要动名词（“轮换密钥”），不要裸名词（“密钥轮换”），不要 “如何” 前缀 —— 祈使动词短语本身就标记了类型。 - **描述公式：**“*动词+对象，加上收益或关键约束。*” —— 例如 “在不丢失投递的情况下轮换签名密钥。重叠窗口期内两个密钥都有效。” ## 脚手架生成本页 安装配方 —— 你的编码智能体会读取完整骨架和清单，并根据你的产品做调整： ```sh npx @cloudflare/nimbus-docs add content-how-to yarn nimbus-docs add content-how-to pnpm nimbus-docs add content-how-to bunx @cloudflare/nimbus-docs add content-how-to ``` ## 组件建议 - **编号步骤**是定义性结构 —— 用 Steps 组件或普通有序列表；两者在 `.md` 版本中必须读起来完全一致。如果页面没有步骤，先怀疑它是不是操作指南。 - **标签页 / 代码分组**在同一个规范页面*内部*承载变体维度（语言、平台、CLI 与控制台）。按变体复制整页是失败模式。对于可替代的*方法*，不要用标签页 —— 选推荐的一种，其余给链接。 - **提示框：** 破坏性步骤之前的警告（属于正常路径），以及正常路径的例外（“如果你在旧版套餐上，……”）。被例外提示框淹没的操作指南，说明正常路径选错了。 - **不适合：** 卡片（在 “下一步” 之前本页不做任何路由）、长篇概念插叙、完整选项表（链接到参考）。 ## 结尾 固定页脚，按顺序：**验证** → 若任务存在不可逆的收尾步骤，则放在这里 → **可选区块** → **下一步**，附 2–4 个精选链接。绝不要停在最后一个编号步骤 —— 在第 6 步就结束的页面会让读者不确定自己是否完成了。 ## 阈值 - **每个阶段 ≤ 约 10 步。** 单一目标的长流程用 `###` 划分阶段；*目标*增多的页面则拆分。检验标准是标题：如果需要 “和”，那就是两页。 - **背景介绍 ≤ 2 句。** 更长意味着概念内容渗了进来。 - **一个目标。** 伞形动词（“管理 X”）就是它其实是多个目标的信号。 ## 链接与时效 向外链接以提供深度：为什么看概念，取值看参考，接下来做什么看相邻操作指南。尽量减少步骤*内部*的链接；步骤中间的每个链接都是出口坡道。 功能变化时重新验证步骤，并用 frontmatter 中的 `lastVerified` 日期记录（需通过 `schemaFields` 声明，因为默认 schema 会拒绝未知键）。步骤已漂移的操作指南比没有页面更糟：错误步骤会误导，而缺失页面只是让人失望。 ## 智能体说明 - 每一步都必须脱离上下文也能执行：写明产品区域、完整命令、准确的设置项名称 —— 绝不要 “按上文配置”。 - 预期输出放在围栏代码块中，给出完整、真实的值 —— 不要用 `…` 截断凭据；智能体会按你展示的内容匹配。 - 标签页变体在 `.md` 版本中必须摊平成带标签的分节；绝不要让某一步的唯一副本只存在于生成的 Markdown 会丢弃的组件里。 - “验证” 区块同时也是智能体的验收检查 —— 写成可运行的内容，并明确写出失败分支。 ## 检查清单 建议性 —— 供作者自检或智能体最终检查，永不作为构建闸门： - [ ] 标题是祈使动词短语；一个目标，没有伞形动词 - [ ] 前置条件完整 —— 满足条件的读者无需离开页面即可完成 - [ ] 每一步：动词开头、一个动作、先给位置再给动作 - [ ] 正常路径不断裂 —— 变体维度放在标签页/选择器中，替代方法选定并链接，选项隔离在 “验证” 之后 - [ ] 警告先于破坏性步骤；“验证” 先于代价高昂且难以撤销的步骤 - [ ] 存在 “验证” —— 可运行且带失败分支，或一句自明的话 - [ ] 不可逆的收尾步骤（删除、切换、结束重叠）放在 “验证” 之后，单独成节 - [ ] 以 “下一步”（2–4 个链接）结束，而不是最后一个步骤 - [ ] 每个阶段 ≤ 约 10 步；背景 ≤ 2 句 - [ ] 没有位置引用（“如上所述”）；每个分节都自成一体 Source: https://nimbus.ndjp.net/style-guide/how-to/index.mdx