docs-check-kibana-oas

检查 Kibana OAS

请根据 Elastic API 文档检查清单、核心指南和 Kibana 快速入门，审核来自 elastic/kibana 的 Kibana PR。输出具体的操作清单。每项都要注明需要修改的文件和行号。

输入

$ARGUMENTS 是 PR 编号或 URL。提取 PR 编号。示例：

• /docs-check-kibana-oas 289719
• /docs-check-kibana-oas https://github.com/elastic/kibana/pull/289719
• /docs-check-kibana-oas https://github.com/elastic/kibana/pull/289719/changes

如果未提供 PR 编号，请向用户索要。

核心原则：YAML 是生成文件，TypeScript 才是事实来源

oas_docs/output/ 下的文件（kibana.yaml、kibana.serverless.yaml）由 TypeScript 路由定义自动生成。CI 会在推送时重新生成这些文件。使用 YAML 差异检测问题（缺少 x-state、稳定性标签错误、值为空），但输出的每项操作都必须指向生成该内容的 TypeScript 源文件。切勿建议手动编辑 YAML。

工作流程

1. 获取 PR

gh pr diff <PR_NUMBER> --repo elastic/kibana
gh pr view <PR_NUMBER> --repo elastic/kibana --json title,body,files,headRefName

保存完整差异。你需要多次检查。

2. 检出 PR 分支

查找本地 Kibana 克隆。按以下顺序检查：

1. 当前工作目录（如果位于 kibana 仓库内）
2. ~/elastic/kibana

然后检出 PR 分支：

cd <KIBANA_DIR> && gh pr checkout <PR_NUMBER>

如果这两个位置都未找到本地克隆，请告知用户，并询问其 Kibana 检出目录的路径。

从此检出目录读取实际源文件，以获取准确行号。切勿根据差异块标题计算行号。

3. 对变更分类

根据差异，将变更文件归入以下类别：

• 路由定义：server/routes/ 下注册 router.versioned.* 端点的 .ts 文件
• 架构定义：在路由验证中使用 schema.object / schema.maybe / 等的 .ts 文件
• 生成的 YAML：oas_docs/output/ — 仅检查诊断信号
• 示例文件：routes/examples/ 下的 YAML 文件
• 其他：类型、测试、模拟文件 — 请注明，但不审核

4. 审核

对照下方规则部分中的所有规则检查差异。使用生成的 YAML 作为交叉检查信号。如果 YAML 看起来有误（缺少 x-state、x-state 为空、标签错误），请追溯到 TypeScript 源文件，找出根本原因。

对于每项发现，读取检出分支上的实际文件，确认准确行号。指出开发者需要修改的那一行。

5. 交叉检查同类路由

当 PR 为现有资源添加新路由时，请读取检出分支上的现有路由，比较惯例。查找同类路由采用但新路由缺少的模式，例如叙述性文档链接、标签用法或示例文件。

6. 输出

先输出扁平的操作清单，再给出摘要。保持简洁。不要写冗长的诊断说明。

文件链接

每个文件引用都必须是指向 PR“Files changed”视图的可点击 Markdown 链接：

https://github.com/elastic/kibana/pull/<PR_NUMBER>/files#diff-<SHA256_OF_PATH>

计算锚点：

echo -n "<full-repo-relative-path>" | shasum -a 256 | cut -c1-64

链接格式：[agents.ts:689](https://github.com/elastic/kibana/pull/290353/files#diff-<hash>)

如果无法计算哈希，请链接到 PR 文件页面并附上裸路径。

格式

## OAS review — PR #<NUMBER>

**<PR title>**

### Actions

1. ❌ **Add `stability` to availability** — [agents.ts:689](<link>)
   `availability: { since: '9.5.0' }` → `availability: { stability: 'experimental', since: '9.5.0' }`

2. ❌ **Add description for `user_id` path param** — [agents.ts:140](<link>)
   Path parameters must have `meta: { description: '...' }`.

3. ❌ **Add narrative doc link** — [attachments.ts:105](<link>)
   Sibling conversation routes link to the agent chat docs. Consider adding a similar link.

4. ❌ **Summary exceeds 45 characters** — [agents.ts:684](<link>)
   `'Get all agent builder conversation attachments for a user'` → shorten to ~40 chars.

### Passes

- ✅ `summary` and `description` present — [agents.ts:684](<link>)
- ✅ Path params have `meta.description` — [agents.ts:700](<link>)
- ✅ Tags include `oas-tag` — [agents.ts:680](<link>)
- ✅ Example file referenced — [agents_get.yaml](<link>)

### Verdict

**N actions** (X required, Y suggested)

规则：

• ❌ 表示作者需要处理的操作
• ✅ 表示通过项 — 每项简要列出一行
• 将已有问题标记为“（既有问题）”，以便 PR 作者区分新增问题和继承问题
• 如果修复只需一行，务必注明修改前 → 修改后
• 每个文件引用都必须是指向 PR 文件视图的 Markdown 链接

规则

这些规则来自 Elastic API 文档检查清单、核心指南、组织和注释指南以及 Kibana 快速入门。此外，规则也纳入了现有 Kibana 路由中观察到的约定。

1. 路由级可用性（生命周期状态）

每个新路由都 MUST 在其 options 块中包含 availability，并同时设置 stability 和 since。这决定了已发布 API 文档中的版本徽标和技术预览标签。

有效的 stability 值及其显示标签：

值	显示标签	含义
'experimental'	实验性	未来版本中可能会更改或移除
'tech_preview'	技术预览	尚未正式发布，可能会更改
'stable'	正式可用	稳定，可用于生产环境（省略时为默认值，但请明确指定）

since 是类似 '9.2.0' 的版本字符串，标记 API 首次发布的版本。该字段会显示在 Elastic Stack 文档中，在无服务器文档中则会省略。

正确模式：

router.versioned.get({
  path: '...',
  options: {
    tags: ['...', 'oas-tag:Agent builder'],
    availability: {
      stability: 'experimental',
      since: '9.6.0',
    },
  },
})

需要标记的问题：

• ❌ 完全缺少 availability 块
• ❌ availability 中缺少 stability
• ❌ availability 中缺少 since
• ❌ stability 的值无效

2. 路由摘要

每个新路由都 MUST 包含 summary。摘要会显示在 IDE、搜索结果和文档概览中。

摘要指南：

• 5–45 个字符——许多场景中的可用空间有限，因此请尽量简短
• 以动词开头——“Get”“Create”“Update”“Delete”
• 使用常见动词——用“Get”而不是“Retrieve”，用“Update”而不是“Modify”
• 包含冠词——“Delete a space”“Delete spaces”
• 使用句首字母大写格式——仅首词和专有名词首字母大写
• 结尾不加句号

需要标记的问题：

• ❌ 缺少 summary
• ❌ 摘要超过 45 个字符
• ❌ 摘要未以动词开头
• ❌ 摘要使用标题式大小写或以句号结尾

3. 路由描述

每个新路由都 MUST 包含 description。描述支持 Markdown 格式，内容应涵盖：

• 用途和影响：此操作的作用是什么？用户为什么需要它？
• 先决条件或上下文：调用此端点前，用户需要了解什么？
• 限制条件：有效值、格式、大小限制、速率限制
• 关联关系：参数之间如何交互，如何处理多个值

好的描述会在摘要之外提供更多细节。糟糕的描述只是重复摘要。

示例（好）：'Create a new conversation with an agent. The conversation persists across sessions and can be shared with other users via access control. To learn more, refer to the [agent chat documentation](https://www.elastic.co/docs/...).'

示例（差）：'Creates a conversation.'（重复摘要，没有补充任何信息）

需要标记的问题：

• ❌ 缺少 description
• ❌ 描述只是复制或重复摘要
• ❌ 描述遗漏用户需要了解的限制条件或先决条件

4. 叙述性文档链接

路由描述应以一个句子结尾，并链接到相关的叙述性文档页面。这是现有 Kibana 路由中观察到的一项约定。如果同一资源下的相邻路由已包含此类链接，则尤其需要遵循此约定。

模式：

description:
  'List all conversations. To learn more, refer to the [agent chat documentation](https://www.elastic.co/docs/...).',

检查方法：与相邻路由进行比较。如果同一资源下的其他路由包含“To learn more...”或“refer to the docs”链接，而新路由没有，则应标记。

需要标记的问题：

• ❌ 相邻路由包含叙述性文档链接，但此处缺少（警告，而非错误——全新功能可能尚无对应链接）

5. 标签

路由的 tags 数组中 MUST 至少包含一个 oas-tag: 条目。标签用于在发布的文档中按功能对 API 进行分组。

标签指南：

• 使用句首字母大写格式：'oas-tag:Agent builder'，而不是 'oas-tag:agent builder'
• 相关路由使用一致的标签名称
• 每个路由使用一个 oas-tag，以保持导航清晰

需要标记的问题：

• ❌ tags 数组中没有 oas-tag:*
• ❌ 标签名称的大小写与同类路由不一致
• ❌ 单个路由包含多个 oas-tag: 条目

6. 路径参数描述

每个路径参数 MUST 在其架构定义中包含 meta: { description: '...' }。

正确模式：

params: schema.object({
  conversation_id: schema.string({
    meta: { description: 'The unique identifier of the conversation.' },
  }),
}),

需要标记的问题：

• ❌ 路径参数没有 meta，或 meta 中没有 description

7. 属性描述

每个新增的请求正文、查询或响应属性 MUST 包含 meta: { description: '...' }。

好的属性描述应说明该值控制什么、其格式以及任何限制：

• ❌ 'The page size.' — 描述含糊，没有限制条件或默认值
• ✅ 'The maximum number of results to return. Must be between 1 and 1000. Defaults to 20.'

需要标记的问题：

• ❌ 新属性完全没有 meta
• ❌ 存在 meta，但没有 description
• ❌ 描述只是笼统地重复属性名称（例如，属性名为 name，描述却是 'The name.'）

8. 枚举值描述

当属性使用 schema.oneOf 或 schema.literal 定义一组固定值时，应为每个值添加描述，可以在属性描述中说明，也可以在各个架构选项中分别说明。

无需记录不言自明的值：

• true / false、asc / desc、enabled / disabled — 从名称即可看出含义
• read / write / admin — 含义不明确；admin 除了 write 之外还授予什么权限？
• low / medium / high — 含义不明确；每个级别具体会带来什么变化？

需要标记的问题：

• ❌ 当枚举值的含义或行为差异无法从名称中看出时，没有为其添加描述

9. 默认值

应记录可选参数和属性的默认值。在 Kibana 路由架构中，这意味着使用 schema.maybe(schema.string({ defaultValue: '...' }))，或在描述中说明服务端默认值。

正确模式：

page_size: schema.maybe(
  schema.number({
    defaultValue: 20,
    meta: { description: 'Number of results per page. Defaults to 20.' },
  })
),

如果默认值由服务端设置（而非在架构中设置），则应在描述中说明：'Sort order. The server defaults to descending if not specified.'

检查方法：与同一资源下的同类路由进行比较。如果同类路由说明了 page_size 的默认值，而新路由没有说明，则应标记。

需要标记的问题：

• ❌ 可选参数的默认值未记录，且行为会随该值而变化

10. 属性级可用性

如果在现有路由的架构中新增属性，且该属性的推出版本晚于路由本身的版本，则该属性 MUST 拥有自己的 meta.availability，其中包含 stability 和 since。

检测方法：在现有路由的验证代码块中，查找新增的 schema.maybe(...) 或 schema.object(...) 字段。如果路由的 since: '9.2.0'，而新属性在 '9.6.0' 中推出，则该属性需要有自己的可用性信息。

正确模式：

new_field: schema.maybe(
  schema.string({
    meta: {
      availability: { stability: 'experimental', since: '9.6.0' },
      description: 'Description of the new field.',
    },
  })
),

需要标记的问题：

• ❌ 较早版本路由中的新属性没有 meta.availability
• ❌ 属性包含 availability，但缺少 stability 或 since

11. 弃用

已弃用的路由或属性应明确标记。在 Kibana 中，路由的 options 支持 deprecated 标记，属性描述应说明其弃用情况。

需要标记的问题：

• ❌ 注释或描述文本表明属性或路由已弃用，但没有 deprecated: true 标记
• ❌ 已弃用属性的描述没有说明应改用什么

12. 响应示例

新路由应通过 oasOperationObject 引用示例文件。示例能显著提升 API 文档的易用性。

内联 TypeScript 示例（开发时会进行类型检查）：

.addVersion({
  version: '2023-10-31',
  options: {
    oasOperationObject: () => ({
      requestBody: {
        content: {
          'application/json': {
            examples: {
              example1: {
                summary: 'An example request',
                value: { name: 'Example' } as MyType,
              },
            },
          },
        },
      },
    }),
  },
})

YAML 文件示例：

import path from 'node:path';
.addVersion({
  version: '2023-10-31',
  options: {
    oasOperationObject: () => path.join(__dirname, 'examples/my_route.yaml'),
  },
})

示例 YAML 结构（位于 server/routes/examples/ 中）：

requestBody:
  content:
    application/json:
      examples:
        example1:
          summary: Example request
          description: An example of creating a resource
          value:
            name: 'Example'
responses:
  200:
    content:
      application/json:
        examples:
          success:
            summary: Successful response
            value:
              id: '12345'
              name: 'Example'

示例指南：

• 使用真实的数据，而非占位符
• 为每个示例编写清晰的摘要（少于 45 个字符）
• 至少包含一个成功响应示例（HTTP 200）
• 考虑添加 x-codeSamples，提供 cURL 和 Console 示例

需要标记的问题：

• ❌ 未引用 oasOperationObject（警告——强烈建议添加）
• ❌ 示例文件包含占位符或空值
• ❌ 没有成功响应示例

13. Operation ID（仅供参考——不要纳入 Actions 列表）

公共路由可以选择设置显式的 operationId。SDK 和 CLI 生成器会将此 ID 用作方法或命令名称；如果省略，生成器会根据方法和路径生成一个名称（例如 post-foo），通常不够清晰。

正确模式：

router.versioned.post({
  path: '/api/foo',
  access: 'public',
  summary: 'Create a foo resource',
  operationId: 'create-foo',
  options: { ... },
});

指南：

• 使用 kebab-case 的 verb-resource 名称，例如 create-foo、get-foo、delete-foo。
• 在同一路由的不同版本间保持 operation ID 稳定——不要随意重命名。

这是一项建议，而非合规规则——不要将其添加到 ❌ Actions 列表中，也不要将其计入评估结果。只有在用户明确询问 SDK/CLI 生成或 operation ID，或 diff 中的路由已设置 operation ID 但不符合 kebab-case 的 verb-resource 约定时，才将其作为一行补充说明（“Consider adding an explicit operationId”）。

14. 交叉检查：将生成的 YAML 用作诊断信号

oas_docs/output/ 下的 YAML 文件是自动生成的。切勿建议直接编辑 YAML。所有修复都应在 TypeScript 源文件中进行。

使用 YAML 的 x-state 值检测问题：

YAML x-state	TypeScript 含义
Experimental; added in 9.6.0	availability: { stability: 'experimental', since: '9.6.0' }
Technical Preview; added in 9.2.0	availability: { stability: 'tech_preview', since: '9.2.0' }
added in 9.0.0（无标签）	availability: { stability: 'stable', since: '9.0.0' }
Experimental（无版本）	对 kibana.serverless.yaml 而言正常——serverless 会省略 added in
''（空字符串）	TypeScript 的 availability 中缺少 stability
完全缺失	TypeScript 中缺少 availability 块

需要标记的问题（始终指向 TypeScript 文件）：

• ❌ x-state 为空或缺失 → 追溯到 TS 路由，并标记缺少 availability 或 stability
• ❌ YAML 标签与 TS 的 stability 不匹配 → 标记 TS 中的不一致
• serverless YAML 省略 added in 是预期行为，不算问题