---
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.

# 参考

> **需求**
>
> 在工作中查找——一个值、一个选项、一个限制、一个名称。读者从侧面进入（搜索、锚点链接、智能体检索），获取事实后离开。他们的问题是：*"确切的值是什么？"* 本指南覆盖**散文侧参考**——配置文件、CLI 标志、事件类型、限制、设置。从规范编译的 API 参考是另一个工作流；两者共享同一准则：事实只有一个来源，读者必须能盲猜页面的结构。

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

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

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

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

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

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

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

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

```sh
npx add content-reference
pnpm dlx add content-reference
yarn dlx add content-reference
bunx add content-reference
```

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

| 接口 | 定义行承载 |
|---|---|
| 配置字段 | 类型 · 默认值 · 必填 · 范围/约束 |
| CLI 标志 | 长格式作标题，别名内联（`--verbose` · 别名 `-v`）· 值语法 · 默认值 · 是否可重复 |
| 事件/webhook 类型 | 载荷 schema 链接 · 触发时机 · 与默认不同的投递保证 |
| 限制/配额 | 值 · 范围（按密钥？按账户？）· 达到限制时发生什么 · 可调整？ |

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

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

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

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

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

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

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

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

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

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

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

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

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

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