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

# 参考

> **需求**
>
> 处于工作、正在查资料 —— 查一个值、一个选项、一个限制、一个名称。读者从侧面进入（搜索、锚点链接、智能体检索），抓取事实，然后离开。他们的第一个问题：*“精确的取值是什么？”*
>
> 本配方覆盖**散文侧参考**：配置文件、CLI 标志、事件类型、限制、设置。由规范生成的 API 参考遵循同样的纪律：事实只有一个来源，读者闭着眼也能预测页面的形状。

## 适用场景

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

- **操作指南。** 参考只描述，从不指导。如果条目里开始长出 “要做这件事，首先……” 的句子，抽出一篇操作指南并链接过去。
- **概念。** 参考中立且完整；观点和理由住在概念页。开头最多允许一句带概念链接的定位句作为*散文*额度 —— 每个条目链接到概念和操作指南是预期做法（见 “链接与时效”）。
- **堆放场。** “杂项” 参考页是事实变得找不到的地方。每个参考页覆盖一个可命名的界面；其结构镜像产品结构，让读者能并行导航两者。

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

## 标题与描述

- **标题：界面的名称，按读者会搜索的写法。** “hookline.config.js” · “CLI 命令” · “事件类型” · “限制”。裸名词有歧义时加 “参考” 没问题（“重试策略参考”）。
- **描述公式：**“*该界面*接受的每一种*条目类型*，以及*列出的事实类别*。” —— 例如 “hookline.config.js 接受的每个字段 —— 类型、默认值和约束。”

## 脚手架生成本页

安装配方 —— 你的编码智能体会读取完整骨架和清单，并根据你的产品做调整：

```sh
npx @cloudflare/nimbus-docs add content-reference
yarn nimbus-docs add content-reference
pnpm nimbus-docs add content-reference
bunx @cloudflare/nimbus-docs add content-reference
```

脚手架的定义行按界面调整：

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

## 组件建议

- **表格**是标志性组件。强烈建议在条目前放一张速查表，让常见查询无需滚动。只用简单表格；合并单元格和 “用布局表达含义” 会同时破坏扫读和提取。
- **每个条目的定义行**（类型 · 默认值 · 约束）按固定顺序排列 —— 用加粗或徽章保持一致。
- **不适合：** Steps、卡片、提示框（需要警告框的事实通常属于条目*内部*的约束）、会藏起条目的标签页或折叠面板（折叠界面里的条目，对边搜边取的读者和提取都不可见）。

## 结尾

参考页没有结尾 —— 枚举完最后一个条目就停止（若该集合有样板尾巴，则附上）。不要 “下一步” 页脚：拿到值的读者已经走了，没拿到的读者需要的是顶部的概念链接，而不是底部。

## 阈值

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

## 链接与时效

*在存在时*，把每个条目链接到解释它的概念和演练它的操作指南。保持条目锚点稳定：它们是文档站上被引用最多的 URL。

事实只有一个来源。如果条目复制了代码或 schema 里的值，就生成它们，因为手工维护的副本会漂移。没有机器来源的页面（如限制和配额）要带可见的 `lastVerified` 日期。

## 智能体说明

- 参考是智能体消费最多、在不完整时臆造最严重的类型 —— 缺失条目会被读成 “不存在”。完整性就是反臆造属性。
- 每个条目必须自成一体：标题承载完整点路径（`retry.max_attempts`，而不是 “Retry” 标题下的 “max_attempts”），让检索到的块自带身份。
- 范围和默认值要写成机器可核对的值，绝不要 “一个合理的数字”。
- `.md` 版本无需特殊处理，*正因为*本配方禁止把条目藏进标签页/折叠面板 —— 保持如此；生成的 Markdown 会包含完整参考页。

## 检查清单

建议性 —— 供作者或智能体自检，永不作为构建闸门：

- [ ] 条目上方有速查表（界面 ≥ 约 5 个条目时），生成或自觉维护
- [ ] 每个条目都存在，或在第一行说明范围排除项
- [ ] 每个条目遵循相同内部模板，标题层级相同
- [ ] 定义行包含 类型 · 默认值 · 是否必填 · 约束（按界面类型调整）
- [ ] 描述中立；溢出事实放进列表/子表，而不是散文
- [ ] 条目标题包含完整自识别名称（点路径）
- [ ] 排序已说明或自明；锚点在编辑间保持稳定
- [ ] 指明事实来源（或页面由它生成）；手工维护的事实页带 `lastVerified`
- [ ] 没有步骤、没有观点、没有藏在折叠组件里的内容

Source: https://nimbus.ndjp.net/style-guide/reference/index.mdx