用途:审查 elastic/kibana 仓库中某个 Kibana PR 的 OpenAPI 规范(OAS)与 API 文档合规性,依据 Elastic API 文档清单、核心指南和 Kibana 快速入门,输出可执行的修改动作清单,每条都指明需修改的文件与行号。
主要能力:检查路由级 availability(stability 与 since)、summary、description、叙述性文档链接、oas-tag 标签、路径参数与属性描述、枚举值描述、默认值、属性级 availability、弃用标记、响应示例等;并将 oas_docs/output/ 下自动生成的 YAML 作为诊断信号,但所有修改建议都指向生成它的 TypeScript 源码,绝不建议手改 YAML。
使用方式:输入 PR 编号或 URL,例如 /docs-check-kibana-oas 289719 或 /docs-check-kibana-oas https://github.com/elastic/kibana/pull/289719;未提供编号时会要求补充。工作流包括用 gh pr diff 与 gh pr view 获取 PR、检出 PR 分支、分类变更文件、逐条审计、交叉比对同级路由,最后输出扁平动作清单与摘要。文件引用需为指向 PR Files changed 视图的可点击 Markdown 链接,锚点通过 echo -n "<path>" | shasum -a 256 | cut -c1-64 计算。
适用场景:Kibana 路由新增或修改后的 API 文档合规审查,尤其适合需要对照同级路由约定、区分新引入问题与既有问题的 PR 评审。
限制:需要本地 Kibana 克隆与 gh 工具;若找不到克隆会要求用户提供路径;行号必须从检出分支的实际源码读取,不能由 diff 片段头推算;operationId 仅为建议,不计入动作清单与结论;YAML 为自动生成,不得手动编辑。