何时使用
故障排除内容存在于两个地方，本指南覆盖两者：
-
内联在故障发生的页面上——默认做法。在操作指南中使用“What if…“提示框，或在功能页面末尾使用 FAQ 折叠面板。内联形式保持相同的内部结构，但更紧凑：
如果登录失败并显示
Error: no workspace selected怎么办？ CLI 已认证但未指向工作区。运行hookline workspace use <name>然后重试。 -
每个产品区域的独立故障排除页面，当内联条目超过约 5 个或同一故障跨多个页面时。
它不是：
- 操作指南。 操作指南追求目标；故障排除从故障中恢复。“设置投递警报”是操作指南，即使它涉及问题。
- 错误参考。 如果产品有稳定的错误代码，完整的按代码目录是参考材料（每个代码一个条目，统一模板——见参考指南）；故障排除页面覆盖症状、多原因问题，以及代码无法捕获的“它很慢/它不稳定”的叙述性情况。小型产品合并两者；说明哪个页面负责什么。
- 全局 FAQ。 有已知答案的问题放在应该回答它们的页面上。故障排除页面按故障组织，而非按问题。
标题和描述
- 条目标题：原始症状——理想情况下是确切的错误信息。 “Error: signature timestamp outside tolerance” 在搜索、检索和侧边栏扫视中都优于 “Signature problems”。较长的信息：保留有区分度的子串，截断到约 70 个字符，用 ASCII
...标记截断位置。信息类型（“Error:”、“Warning:”）保留在标题中。没有错误信息的症状型条目使用可观察的表述：“Deliveries succeed but arrive twice。” - 页面标题： “Troubleshooting 区域”——例如 “Troubleshooting delivery。”
- 描述公式： “区域常见故障的修复，按症状排列。”
搭建此页面
安装指南——你的编码智能体会读取完整的骨架和清单，并将其适配到你的产品：
npx @cloudflare/nimbus-docs add content-troubleshootingyarn dlx @cloudflare/nimbus-docs add content-troubleshootingpnpm dlx @cloudflare/nimbus-docs add content-troubleshootingbunx @cloudflare/nimbus-docs add content-troubleshooting组件指导
- 围栏块用于原始信息——搜索、读者和检索的匹配目标。展示一个具体的现实实例，包含变量值（
skew 512s > 300s展示了机制；稳定的子串仍然匹配搜索）。永远不要意译错误；永远不要省略有区分度的部分。 - 加粗的 Cause/Fix/Verify 标签（或固定的子标题三联体）——统一的内部顺序让慌张的读者能直接跳到 Fix。
- 折叠面板适合内联形式（功能页面末尾的 FAQ 风格）；在独立页面上，条目保持展开——隐藏的症状不可查找，页面的存在就是为了被扫读。
- 不适用： Cards、营销语气、以及没有修复的安慰（“这通常是无害的”——那就说明什么时候不是）。
结尾
独立页面以 Still stuck? 结尾——升级路径，附带一个先收集这些信息的列表。这是类型的诚实条款：一个暗示完整性的故障排除页面会让读者困在它遗漏的那个故障上。
阈值
- 内联到约 5 个条目，然后独立页面——在内联处留下链接。
- 最常见的故障排在前面；数据丢失故障插队。 排序就是分诊。
- 每个临时方案说明其成本和永久替代方案。 以修复面目出现的临时方案是技术债务被记录为永久性的方式。
链接和新鲜度
每个 Cause 链接到解释机制的概念；每个多步骤 Fix 链接到（或本身就是）操作指南。从支持请求和社区问题中获取此页面的内容——这是唯一一种积压自动生成的类型——当产品修复了底层故障时清除条目：修复已不存在问题的修复方案会让读者去寻找一个已经消失的设置。在对照当前发布版本清扫时盖上页面的 lastVerified 日期。
智能体备注
- 这是智能体通过精确字符串匹配检索的类型——围栏块中的原始错误信息就是全部。展示一个具体的现实实例；稳定的子串承载匹配。省略（ASCII
...）仅属于长信息的标题中，且永远不在有区分度的部分。 - 将 Cause → Fix 结构化为智能体可以执行的声明；“检查你的配置”不是修复，
hookline test-event --endpoint <id>才是。 - 保持每个条目完全自成一体——条目 N 会在没有条目 N-1 和页面介绍的情况下被检索。
清单
建议性——供作者或智能体自查，不是构建门禁：
- 条目标题是原始信息或可观察的症状（长的截断到有区分度的子串，约 70 个字符）
- 每个有信息的条目在围栏块中展示一个具体实例；仅症状的条目在第一行说明可观察的行为
- 固定内部顺序：症状 → 原因 → 修复（→ 验证）；多原因条目将每个原因与其确认和修复配对
- 临时方案已标注、已说明成本、并与永久修复配对
- 最常见的故障排在前面；数据丢失故障插队
- 独立页面以 Still stuck? + 先收集这些信息列表结尾
- 原因链接到概念；多步骤修复链接到操作指南
- 当底层故障已修复时清除条目；清扫时盖上
lastVerified