适用场景
故障排查内容生活在两个地方，本配方两者都覆盖：
-
内联，放在失败发生的页面上 —— 默认做法。在操作指南里用 “如果……怎么办” 提示框，或在功能页末尾用 FAQ 式折叠面板。内联形式保持相同的内部形状，只是压缩：
如果登录失败并报
Error: no workspace selected怎么办？ CLI 已通过认证，但还没指向任何工作区。运行hookline workspace use <name>后重试。 -
每个产品区域一个专门的故障排查页，当内联条目超过约 5 条，或同一失败跨越多个页面时使用。
它不是：
- 操作指南。 操作指南追求目标；故障排查从失败中恢复。“设置投递告警” 是操作指南，即使它涉及问题。
- 错误参考。 如果产品有稳定的错误码，完整的逐码目录属于参考材料（每个码一个条目、统一模板 —— 见参考配方）；故障排查页覆盖症状、多因问题和代码捕捉不到的叙述性问题（“它很慢 / 它不稳定”）。小型产品会把两者合并；说明哪个页面负责哪部分。
- 全局 FAQ。 有已知答案的问题，放到本应回答它的页面。故障排查页按失败组织，而不是按问题组织。
标题与描述
- 条目标题：逐字的症状，最好是精确的报错信息。 “Error: signature timestamp outside tolerance” 在任何地方都胜过 “签名问题”。长消息裁剪到最有辨识度的部分，约 70 个字符，用
...标记截断，并保留 “Error:” 或 “Warning:”。没有报错信息时，描述可观察到的现象：“投递成功但到达两次。” - 页面标题：“故障排查 区域” —— 例如 “故障排查：投递”。
- 描述公式：“区域内常见失败的修复，按症状组织。”
脚手架生成本页
安装配方 —— 你的编码智能体会读取完整骨架和清单，并根据你的产品做调整：
npx @cloudflare/nimbus-docs add content-troubleshooting
yarn nimbus-docs add content-troubleshooting
pnpm nimbus-docs add content-troubleshooting
bunx @cloudflare/nimbus-docs add content-troubleshooting组件建议
- 用围栏代码块放逐字的报错信息 —— 它是搜索、读者和检索的匹配目标。展示一个真实具体实例，包含变量值（
skew 512s > 300s展示了机制；稳定子串仍能匹配搜索）。绝不要改写报错；绝不要省略它有辨识度的部分。 - 加粗的 Cause/Fix/Verify（原因/修复/验证）标签（或固定的三小标题）—— 统一的内部顺序让慌乱的读者直接跳到 “修复”。
- 折叠面板适合内联形式（功能页末尾的 FAQ 式）；在专门页面上，条目保持展开 —— 藏起来的症状找不到，而页面存在的意义就是被扫读。
- 不适合： 卡片、营销语气，以及没有修复的安慰（“这通常无害” —— 那就说明何时有害）。
结尾
专门页面以 Still stuck?（仍然卡住？） 结尾 —— 升级路径，附一份 “先收集这些” 的清单。这是本类型的诚实条款：暗示自己完整的故障排查页，会把读者困在它恰好漏掉的那个失败上。
阈值
- 内联到约 5 条，然后建专门页面 —— 并在原内联位置留下链接。
- 最常见的失败排最前；数据丢失类失败插队。 排序就是分诊。
- 每个变通方案都说明其代价和永久替代方案。 把变通方案当作修复来写，是技术债被写进永久文档的方式。
链接与时效
每条 “原因” 链接到解释它的概念；每个多步 “修复” 链接到（或本身就是）一篇操作指南。
用支持请求和社区问题喂养本页。产品修复该失败后，删掉对应条目，否则读者会去寻找一个已经不存在的设置。对照某个版本检查页面时，盖上 lastVerified。
智能体说明
- 这是智能体按精确字符串匹配检索的类型 —— 围栏代码块中的逐字报错就是全部胜负手。展示真实具体的实例；稳定子串承载匹配。省略（ASCII
...）只允许出现在长消息的标题里，且绝不在有辨识度的部分上使用。 - 把 Cause → Fix 写成智能体可执行的陈述句；“检查你的配置” 不是修复，
hookline test-event --endpoint <id>才是。 - 让每个条目完全自成一体 —— 第 N 条会在没有第 N−1 条、也没有页面引言的情况下被检索。
检查清单
建议性 —— 供作者或智能体自检，永不作为构建闸门：
- 条目标题是逐字报错或可观察症状（长消息裁到有辨识度的子串，约 70 字符）
- 每个带报错的条目都在围栏代码块中展示它，作为一个具体实例；仅有症状的条目在第一行说明可观察行为
- 固定内部顺序：症状 → 原因 → 修复（→ 验证）；多因条目为每个原因配对确认方法和修复
- 变通方案已标注、已说明代价，并与永久修复配对
- 最常见的失败排最前；数据丢失类失败插队
- 专门页面以 Still stuck? + 先收集这些清单结尾
- 原因链接到概念；多步修复链接到操作指南
- 底层失败修复后删除对应条目；巡检时盖上
lastVerified