参考

何时使用

当内容是关于一个接口的事实枚举时（文件格式、命令、一组类型或限制），编写参考。它不是：

• 操作指南。 参考描述；从不指导。如果条目开始出现“要这样做，首先……“的句子，提取为操作指南并链接。
• 概念。 参考是中立且完整的；观点和理由在概念页面上。顶部一句带概念链接的引导语是全部的散文配额——条目内链接到概念和操作指南是预期的（见链接和新鲜度）。
• 垃圾场。 “杂项”参考页面是事实变得不可查找的地方。每个参考页面覆盖一个可命名的接口；其结构映射产品的结构，使读者可以并行导航两者。

这种类型的两条法则是完整性（缺失条目破坏参考，就像缺失的词破坏词典）和一致性（每个条目以相同顺序回答相同的问题）。

标题和描述

• 标题：接口的名称，按读者搜索时的形式。 “hookline.config.js” · “CLI commands” · “Event types” · “Limits。” 当裸名词有歧义时可以添加 “reference”（“Retry policy reference”）。
• 描述公式： “接口接受的每种条目类型，附带列出的事实类别。”——例如 “hookline.config.js 接受的每个字段——类型、默认值和约束。”

搭建此页面

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

npx @cloudflare/nimbus-docs add content-reference

yarn dlx @cloudflare/nimbus-docs add content-reference

pnpm dlx @cloudflare/nimbus-docs add content-reference

bunx @cloudflare/nimbus-docs add content-reference

骨架的定义行按接口类型适配：

组件指导

• 表格是标志性组件。强烈建议在条目上方放一个快速参考表，因为它使常见查阅零滚动。仅用简单表格；合并单元格和通过布局传达含义会同时破坏扫读和提取。
• 每个条目的定义行（类型 · 默认值 · 约束）使用固定顺序——用粗体或徽章一致地标记它们。
• 不适用： Steps、Cards、提示框（需要警告提示的事实通常应该作为约束放在条目内）、隐藏条目的标签页或折叠面板（折叠接口内的条目对扫读抓取的读者和提取都是不可见的）。

结尾

参考页面不结束——它们在最后一个条目之后停止（加上模板化尾部，如果该集合有的话）。没有后续步骤页脚：获取到值的读者已经离开了，没获取到的需要顶部的概念链接，而非底部。

阈值

• 完整或明确限定范围——没有中间状态。 接口接受的每个条目都存在；如果故意将子集放在别处，第一行说明在哪里。
• 条目描述散文 ≤ 3 句，中立——带有结构化溢出阀：超出此范围的可枚举事实（每个值的语义、交互、警告）放在条目下的列表或子表中，而非更多散文。
• 每个页面一个接口，接口自身的接缝定义粒度（顶层配置节或子命令在拆分时本身就是一个接口）。约 30 个条目是考虑沿接缝拆分的信号，但一个带有稳定锚点的长页面是有效的、对智能体友好的选择。永远不要按字母顺序拆分。

链接和新鲜度

将每个条目链接到解释它的概念和练习它的操作指南（在它们存在的情况下）——并保持条目锚点稳定；参考锚点是文档站点上被引用最多的 URL。此处的事实只有一个来源：如果条目复制了存在于代码或 schema 中的值，自动生成它们——手工维护的机器事实副本是漂移的可靠来源。没有机器来源的手工维护事实页面（限制、配额）携带可见的最后验证日期（frontmatter 中的 lastVerified）；生成的页面继承其来源的新鲜度。

智能体备注

• 参考是智能体消费最多、在不完整时幻觉最严重的类型——缺失的条目被解读为“不存在”。完整性是反幻觉属性。
• 每个条目必须自成一体：标题携带完整的点分路径（retry.max_attempts，而非 “Retry” 标题下的 “max_attempts”），这样检索到的块自带身份。
• 将范围和默认值表述为可机器检查的值，永远不要写“一个合理的数字”。
• .md 版本无需特殊处理正因为本指南禁止在标签页/折叠面板中隐藏条目——保持这样；生成的 Markdown 包含完整的参考页面。

清单

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

• 条目上方有快速参考表（≥ ~5 个条目的接口），生成的或有意识维护的
• 每个条目都存在，或第一行说明了范围排除
• 每个条目遵循相同的内部模板，相同的标题层级
• 定义行承载类型 · 默认值 · 必填 · 约束（按接口类型适配）
• 描述中立；溢出事实放在列表/子表中，而非散文
• 条目标题携带完整的自标识名称（点分路径）
• 排序已说明或不言自明；锚点在编辑中保持稳定
• 真相来源已命名（或页面从中生成）；手工维护的事实页面携带 lastVerified
• 无步骤、无观点、无隐藏在折叠组件中的内容