Kibana OAS 校验调试指南debug-oas 技能的 --path 作用域过滤与 structural/quality 问题分类体系【免费下载链接】kibanaYour window into all of your data项目地址: https://gitcode.com/GitHub_Trending/ki/kibana当你修改了 Kibana 中某个 HTTP API 的代码后oas_docs/output/下生成的 OpenAPIOAS规范可能因为描述缺失、schema 形状错误或引用未解析而校验失败。本文基于仓库内的 debug-oas 技能文档 展开讲解如何用node ./scripts/validate_oas_docs.js配合一个或多个--path过滤器把校验输出收敛到正在改动的 API 区域再把问题拆成structural结构性非法 OAS与quality文档完整性缺口两类分别处理并结合 kbn-validate-oas 包 的源码说明分类、路径转换与基线门禁的底层实现读完后你可以独立完成一次从“校验失败”到“定位并修复具体 OAS 问题”的调试闭环。1. debug-oas 的定位与 validate-oas 的分工Kibana 仓库为 OAS 校验提供了两个配套的 Agent 技能二者共享同一个 CLI 入口 scripts/validate_oas_docs.js但目标不同validate-oas见 validate-oas 技能只返回VALID或NOT VALID的快速判定适合“到底过没过”的场景。debug-oas本文主题当开发者需要问题拆解、分类和代表性样例时使用。它要求始终用--path把输出作用域限制在开发者正在改动的 API 区域以便聚焦。技能文档给出的协作路径非常明确先用 validate-oas 拿快速结果结果为NOT VALID时再交给 debug-oas 做详细调试。同时文档强调一条重要原则如果结果看起来陈旧或出人意料应先把生成物刷新到最新——按 validate-oas 中的环境更新流程重新生成oas_docs。过期的oas_docs属于“环境问题”而不是调试结论不能直接当作规范本身有问题的证据。2. 两类问题structural 与 qualitydebug-oas 技能规定校验器可以暴露两大类问题报告结果时必须分开且结构性问题必须放在最前面分类含义典型示例structural非法 OAS 问题通常阻塞正确性schema 违规、形状shape非法、引用未解析unresolved refs、路径定义与规范结构不匹配、必填非文档字段缺失、参数定义非法、请求/响应结构畸形quality文档完整性问题缺失description、summary、example、examples这套分类不是纸面约定在 kbn-validate-oas 包 中有源码级对应。其 README 给出了 “Policy v1” 的严重度策略Structural 类发现schema 形状、未解析的$ref→errorQuality 类中缺失summary/example/examples→errorQuality 类中缺失description→warning兼容性compatibility发现不在该分类体系内走独立的硬性失败路径且不参与基线计数。分类逻辑在 error_categorization.ts 中实现classifySchemaError解析 AJV 的校验错误对象当keyword required且missingProperty属于descriptionwarning或summary/example/exampleserror时归类为quality否则一律归为structural引用解析失败则由classifyRefError直接标记为structural且error。代码中还显式过滤了两类 AJV 噪音可选$ref缺失与 anyOf/oneOf 聚合错误passingSchemas null。技能文档给出的分类启发式与源码一致如果报错信息是对description、summary、example或examples的文档完整性抱怨 →quality否则默认structural除非开发者明确要求更细的拆分。严重度语义structural 阻塞性的非法 OASquality 文档完整性或打磨类问题。一次运行若混合两类报告顺序为先 structural 数量再 quality 数量。3. 作用域校验命令--path 与 --only3.1 交互流程技能文档规定了一套必须遵循的交互顺序除非开发者已经给出 API 路径否则不能跳过前两步询问开发者正在处理哪些 API索取一个或多个 HTTP API 路径例如/api/fleet/agent_policies必要时先按 validate-oas 的环境更新流程刷新生成的 OAS用这些路由风格的--path过滤器执行校验把问题归类为structural与quality直接展示命令原始输出让开发者看到当前问题。3.2 路径格式用人类可读的路由路径--path使用普通路由风格的 API 路径例如/api/fleet/agent_policies /internal/fleet/outputs不要手动转换成 JSON PointerCLI 会在内部完成用于错误过滤的转换。多个路径过滤器可以同时给出node ./scripts/validate_oas_docs.js \ --path /api/fleet/agent_policies \ --path /internal/fleet/outputs3.3 默认使用 --only traditional技能规定除非开发者另有要求总是带上--only traditional让校验只针对单个 OAS 输出文件匹配最常见的本地调试路径让输出更窄node ./scripts/validate_oas_docs.js --only traditional --path api_route_prefix只有当开发者明确要求时才切换到 serverless offeringnode ./scripts/validate_oas_docs.js --only traditional --path api_route_prefix node ./scripts/validate_oas_docs.js --only serverless --path api_route_prefix从 cli.ts 的源码可以确认该 flag 的取值范围与对应的输出文件--only只接受traditional或serverless传其他值会exit(1)traditional校验./oas_docs/output/kibana.yamlserverless校验./oas_docs/output/kibana.serverless.yaml省略--only则两个都校验。CLI 还禁止--path与--assert-no-error-increase同时使用——基线门禁必须针对整份 bundle 计数不能只看局部作用域。4. --path 的底层实现路由路径到 JSON Pointer 的转换技能文档说“CLI 会在内部处理转换”具体实现见 path_filters.tstoInstancePathFilter把路由风格路径转成 AJV 错误instancePath使用的 JSON Pointer 前缀。例如/api/fleet/agent_policies→/paths/~1api~1fleet~1agent_policies按 RFC 6901 规则~转义为~0、/转义为~1。toYamlSearchPath反向做 YAML 预过滤时把旧的 JSON Pointer 风格过滤器归一化回路由路径例如/paths/~1api~1fleet~1agent_policies→/api/fleet/agent_policies因此两种写法都向后兼容。normalizePathFilter确保过滤器以/开头。在 cli.ts 中过滤器用于两处一是对 schema 错误按issue.path.startsWith(instancePathFilter)前缀匹配过滤非 schema 来源的问题不被路径过滤丢弃二是当没有任何路径匹配时打印警告None of the provided --path filters matched any content in ...提示路径可能写错但校验本身仍会运行。5. 辅助脚本从噪声输出中提取结构性问题当原始输出太吵时debug-oas 技能提供了一个辅助管道把校验器输出过滤成仅结构性问题的摘要node ./scripts/validate_oas_docs.js --only traditional --path api_route_prefix 21 \ | node .agents/skills/debug-oas/scripts/extract_structural_oas_issues.js若开发者希望在这个辅助输出中保留文档类问题追加--include-docsnode ./scripts/validate_oas_docs.js --only traditional --path api_route_prefix 21 \ | node .agents/skills/debug-oas/scripts/extract_structural_oas_issues.js --include-docs该脚本 extract_structural_oas_issues.js 的实现要点通过正则DOC_MESSAGE_PATTERNS匹配required property example/examples/description/summary识别文档类问题默认将其过滤掉--include-docs保留--json输出机器可读结果解析器先剥离 ANSI 颜色码与│边框前缀再按“以/开头的行是问题路径、Failed check schema path:行是 schema 位置”的规则把多行 CLI 输出还原成结构化的{ path, message, schemaPath }问题列表按message分组并倒序排序出现次数多的在前打印N x message及各问题路径——这正好呼应了技能要求的“摘要时每个主导类别至少给一条原文样例”。技能文档同时提醒辅助摘要只能作为补充调试时应始终保留原始校验器输出以便精确排错。6. 收窄作用域与输出规范6.1 作用域收窄的三层顺序当初始作用域输出过于嘈杂时技能给出由粗到细的收窄顺序先取宽泛的产品区域如/api/fleet收窄到功能区域如/api/fleet/epm再收窄到路由族如/api/fleet/epm/packages。并且当某个区域在结构性问题上占绝对大头时应主动建议更窄的作用域。6.2 输出行为规则技能文档对“如何呈现结果”给出了量化约定以 CLI 的Found N errors in ...一行作为问题数量的唯一事实来源source of truth25 条及以下原样展示完整 CLI 输出不做任何摘要超过 25 条总结关键模式并建议更窄的--path作用域。摘要需包含structural 数量、quality 数量、若干条从 CLI 输出中逐字复制的问题理想情况每个主导类别一条摘要措辞使用Structural issues (invalid OAS): ...与Quality issues (docs gaps): ...的句式调试时优先展示完整问题列表即不要用--skip-printing-issues若所选路径没有任何问题建议放宽或调整--path前缀也可能是路径写错对应 CLI 的None of the provided --path filters matched警告若最终只剩 quality 问题要明确说明让开发者知道剩余工作是文档性质而非结构性修复。摘要的推荐模板Total issues: N Structural issues: X Quality issues: Y6.3 基线与 CI 门禁背景补充结合 kbn-validate-oas 的 README 与 cli.ts 可以看出调试场景的上下文CI 通过--assert-no-error-increase对oas_error_baseline.json位于 oas_error_baseline.json逐 bundle 比对 errors 与 warnings 双轴计数——warning 上升同样失败因为“缺失描述的 quality-warning 增长可能掩盖在描述清理背后的结构性回归”。当该门禁失败时CLI 的报错信息会直接引导开发者“To investigate this further see ... or use thedebug-oasandvalidate-oasskills.” 这正是 debug-oas 技能在实际工作流中的触发入口。7. 先排除“过期生成物”OAS 刷新流程debug-oas 技能反复强调结果可疑时先刷新oas_docs不要把陈旧文件当作调试结论。刷新流程定义在 validate-oas 技能 中步骤为必要时引导依赖yarn kbn bootstrap重新捕获 OAS 快照——include 路径列表以 CI 脚本为唯一事实来源从中读取后再调用 capture_oas_snapshotCI_STEP.buildkite/scripts/steps/checks/capture_oas_snapshot.sh INCLUDE_PATHS$(grep -oE -- --include-path /api[^ \\]* $CI_STEP | awk {print $2}) COUNT$(printf %s\n $INCLUDE_PATHS | grep -c ^/api/) BAD$(printf %s\n $INCLUDE_PATHS | grep -cvE ^/api/[A-Za-z0-9._{}/-]$) [ $COUNT -ge 15 ] || { echo Only $COUNT include paths read from $CI_STEP. Stop and check that script.; exit 1; } [ $BAD -eq 0 ] || { echo $BAD malformed include path(s) in $CI_STEP. Stop.; exit 1; } printf %s\n $INCLUDE_PATHS | sed s|^|--include-path | | xargs node scripts/capture_oas_snapshot该块内置了两道防护捕获脚本的 include 列表若被重排或移动数量不足 15 条立即停止任何非/api/普通路径形状的条目直接拒绝。原因是快照捕获对缺失路径是“静默丢弃”的——坏列表会让路由从oas_docs/output/*.yaml中消失进而被 API 契约检查误读为端点被删除。运行 OpenAPI 捆绑脚本bash .buildkite/scripts/steps/openapi_bundling/security_solution_openapi_bundling.sh bash .buildkite/scripts/steps/openapi_bundling/final_merge.sh重建最终 OAS 文档cd oas_docs make api-docs完成刷新后再回到第 3 节的带--path的校验命令。技能同时说明何时不必刷新开发者明确只要一次快速本地复验或本会话中已刷新过oas_docs且相关输入没有变化。8. 小结debug-oas 技能把“OAS 校验失败”这一笼统状态拆成了一条可操作的调试流水线确定作用域向开发者拿到正在改动的路由路径用可重复的--path过滤默认--only traditional先保证输入新鲜可疑结果先走 OAS 刷新流程把“环境问题”与“规范问题”分开分类汇报按structural阻塞性非法 OAS先行报告与qualitydescription/summary/example/examples缺口分列数量并给出逐字样例降噪与收敛超过 25 条时用辅助脚本提取 structural 摘要并按 产品区域 → 功能区域 → 路由族 的顺序收窄--path保留原始输出辅助摘要只是补充精确调试始终以 CLI 的完整输出为准。所有结论背后都有可复核的仓库证据技能文档 SKILL.md、辅助脚本 extract_structural_oas_issues.js、CLI 入口 validate_oas_docs.js以及实现包 kbn-validate-oas 中的 cli.ts、path_filters.ts 与 error_categorization.ts。【免费下载链接】kibanaYour window into all of your data项目地址: https://gitcode.com/GitHub_Trending/ki/kibana创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
Kibana OAS 校验调试指南：debug-oas 技能的 --path 作用域过滤与 structural/quality 问题分类体系
Kibana OAS 校验调试指南debug-oas 技能的 --path 作用域过滤与 structural/quality 问题分类体系【免费下载链接】kibanaYour window into all of your data项目地址: https://gitcode.com/GitHub_Trending/ki/kibana当你修改了 Kibana 中某个 HTTP API 的代码后oas_docs/output/下生成的 OpenAPIOAS规范可能因为描述缺失、schema 形状错误或引用未解析而校验失败。本文基于仓库内的 debug-oas 技能文档 展开讲解如何用node ./scripts/validate_oas_docs.js配合一个或多个--path过滤器把校验输出收敛到正在改动的 API 区域再把问题拆成structural结构性非法 OAS与quality文档完整性缺口两类分别处理并结合 kbn-validate-oas 包 的源码说明分类、路径转换与基线门禁的底层实现读完后你可以独立完成一次从“校验失败”到“定位并修复具体 OAS 问题”的调试闭环。1. debug-oas 的定位与 validate-oas 的分工Kibana 仓库为 OAS 校验提供了两个配套的 Agent 技能二者共享同一个 CLI 入口 scripts/validate_oas_docs.js但目标不同validate-oas见 validate-oas 技能只返回VALID或NOT VALID的快速判定适合“到底过没过”的场景。debug-oas本文主题当开发者需要问题拆解、分类和代表性样例时使用。它要求始终用--path把输出作用域限制在开发者正在改动的 API 区域以便聚焦。技能文档给出的协作路径非常明确先用 validate-oas 拿快速结果结果为NOT VALID时再交给 debug-oas 做详细调试。同时文档强调一条重要原则如果结果看起来陈旧或出人意料应先把生成物刷新到最新——按 validate-oas 中的环境更新流程重新生成oas_docs。过期的oas_docs属于“环境问题”而不是调试结论不能直接当作规范本身有问题的证据。2. 两类问题structural 与 qualitydebug-oas 技能规定校验器可以暴露两大类问题报告结果时必须分开且结构性问题必须放在最前面分类含义典型示例structural非法 OAS 问题通常阻塞正确性schema 违规、形状shape非法、引用未解析unresolved refs、路径定义与规范结构不匹配、必填非文档字段缺失、参数定义非法、请求/响应结构畸形quality文档完整性问题缺失description、summary、example、examples这套分类不是纸面约定在 kbn-validate-oas 包 中有源码级对应。其 README 给出了 “Policy v1” 的严重度策略Structural 类发现schema 形状、未解析的$ref→errorQuality 类中缺失summary/example/examples→errorQuality 类中缺失description→warning兼容性compatibility发现不在该分类体系内走独立的硬性失败路径且不参与基线计数。分类逻辑在 error_categorization.ts 中实现classifySchemaError解析 AJV 的校验错误对象当keyword required且missingProperty属于descriptionwarning或summary/example/exampleserror时归类为quality否则一律归为structural引用解析失败则由classifyRefError直接标记为structural且error。代码中还显式过滤了两类 AJV 噪音可选$ref缺失与 anyOf/oneOf 聚合错误passingSchemas null。技能文档给出的分类启发式与源码一致如果报错信息是对description、summary、example或examples的文档完整性抱怨 →quality否则默认structural除非开发者明确要求更细的拆分。严重度语义structural 阻塞性的非法 OASquality 文档完整性或打磨类问题。一次运行若混合两类报告顺序为先 structural 数量再 quality 数量。3. 作用域校验命令--path 与 --only3.1 交互流程技能文档规定了一套必须遵循的交互顺序除非开发者已经给出 API 路径否则不能跳过前两步询问开发者正在处理哪些 API索取一个或多个 HTTP API 路径例如/api/fleet/agent_policies必要时先按 validate-oas 的环境更新流程刷新生成的 OAS用这些路由风格的--path过滤器执行校验把问题归类为structural与quality直接展示命令原始输出让开发者看到当前问题。3.2 路径格式用人类可读的路由路径--path使用普通路由风格的 API 路径例如/api/fleet/agent_policies /internal/fleet/outputs不要手动转换成 JSON PointerCLI 会在内部完成用于错误过滤的转换。多个路径过滤器可以同时给出node ./scripts/validate_oas_docs.js \ --path /api/fleet/agent_policies \ --path /internal/fleet/outputs3.3 默认使用 --only traditional技能规定除非开发者另有要求总是带上--only traditional让校验只针对单个 OAS 输出文件匹配最常见的本地调试路径让输出更窄node ./scripts/validate_oas_docs.js --only traditional --path api_route_prefix只有当开发者明确要求时才切换到 serverless offeringnode ./scripts/validate_oas_docs.js --only traditional --path api_route_prefix node ./scripts/validate_oas_docs.js --only serverless --path api_route_prefix从 cli.ts 的源码可以确认该 flag 的取值范围与对应的输出文件--only只接受traditional或serverless传其他值会exit(1)traditional校验./oas_docs/output/kibana.yamlserverless校验./oas_docs/output/kibana.serverless.yaml省略--only则两个都校验。CLI 还禁止--path与--assert-no-error-increase同时使用——基线门禁必须针对整份 bundle 计数不能只看局部作用域。4. --path 的底层实现路由路径到 JSON Pointer 的转换技能文档说“CLI 会在内部处理转换”具体实现见 path_filters.tstoInstancePathFilter把路由风格路径转成 AJV 错误instancePath使用的 JSON Pointer 前缀。例如/api/fleet/agent_policies→/paths/~1api~1fleet~1agent_policies按 RFC 6901 规则~转义为~0、/转义为~1。toYamlSearchPath反向做 YAML 预过滤时把旧的 JSON Pointer 风格过滤器归一化回路由路径例如/paths/~1api~1fleet~1agent_policies→/api/fleet/agent_policies因此两种写法都向后兼容。normalizePathFilter确保过滤器以/开头。在 cli.ts 中过滤器用于两处一是对 schema 错误按issue.path.startsWith(instancePathFilter)前缀匹配过滤非 schema 来源的问题不被路径过滤丢弃二是当没有任何路径匹配时打印警告None of the provided --path filters matched any content in ...提示路径可能写错但校验本身仍会运行。5. 辅助脚本从噪声输出中提取结构性问题当原始输出太吵时debug-oas 技能提供了一个辅助管道把校验器输出过滤成仅结构性问题的摘要node ./scripts/validate_oas_docs.js --only traditional --path api_route_prefix 21 \ | node .agents/skills/debug-oas/scripts/extract_structural_oas_issues.js若开发者希望在这个辅助输出中保留文档类问题追加--include-docsnode ./scripts/validate_oas_docs.js --only traditional --path api_route_prefix 21 \ | node .agents/skills/debug-oas/scripts/extract_structural_oas_issues.js --include-docs该脚本 extract_structural_oas_issues.js 的实现要点通过正则DOC_MESSAGE_PATTERNS匹配required property example/examples/description/summary识别文档类问题默认将其过滤掉--include-docs保留--json输出机器可读结果解析器先剥离 ANSI 颜色码与│边框前缀再按“以/开头的行是问题路径、Failed check schema path:行是 schema 位置”的规则把多行 CLI 输出还原成结构化的{ path, message, schemaPath }问题列表按message分组并倒序排序出现次数多的在前打印N x message及各问题路径——这正好呼应了技能要求的“摘要时每个主导类别至少给一条原文样例”。技能文档同时提醒辅助摘要只能作为补充调试时应始终保留原始校验器输出以便精确排错。6. 收窄作用域与输出规范6.1 作用域收窄的三层顺序当初始作用域输出过于嘈杂时技能给出由粗到细的收窄顺序先取宽泛的产品区域如/api/fleet收窄到功能区域如/api/fleet/epm再收窄到路由族如/api/fleet/epm/packages。并且当某个区域在结构性问题上占绝对大头时应主动建议更窄的作用域。6.2 输出行为规则技能文档对“如何呈现结果”给出了量化约定以 CLI 的Found N errors in ...一行作为问题数量的唯一事实来源source of truth25 条及以下原样展示完整 CLI 输出不做任何摘要超过 25 条总结关键模式并建议更窄的--path作用域。摘要需包含structural 数量、quality 数量、若干条从 CLI 输出中逐字复制的问题理想情况每个主导类别一条摘要措辞使用Structural issues (invalid OAS): ...与Quality issues (docs gaps): ...的句式调试时优先展示完整问题列表即不要用--skip-printing-issues若所选路径没有任何问题建议放宽或调整--path前缀也可能是路径写错对应 CLI 的None of the provided --path filters matched警告若最终只剩 quality 问题要明确说明让开发者知道剩余工作是文档性质而非结构性修复。摘要的推荐模板Total issues: N Structural issues: X Quality issues: Y6.3 基线与 CI 门禁背景补充结合 kbn-validate-oas 的 README 与 cli.ts 可以看出调试场景的上下文CI 通过--assert-no-error-increase对oas_error_baseline.json位于 oas_error_baseline.json逐 bundle 比对 errors 与 warnings 双轴计数——warning 上升同样失败因为“缺失描述的 quality-warning 增长可能掩盖在描述清理背后的结构性回归”。当该门禁失败时CLI 的报错信息会直接引导开发者“To investigate this further see ... or use thedebug-oasandvalidate-oasskills.” 这正是 debug-oas 技能在实际工作流中的触发入口。7. 先排除“过期生成物”OAS 刷新流程debug-oas 技能反复强调结果可疑时先刷新oas_docs不要把陈旧文件当作调试结论。刷新流程定义在 validate-oas 技能 中步骤为必要时引导依赖yarn kbn bootstrap重新捕获 OAS 快照——include 路径列表以 CI 脚本为唯一事实来源从中读取后再调用 capture_oas_snapshotCI_STEP.buildkite/scripts/steps/checks/capture_oas_snapshot.sh INCLUDE_PATHS$(grep -oE -- --include-path /api[^ \\]* $CI_STEP | awk {print $2}) COUNT$(printf %s\n $INCLUDE_PATHS | grep -c ^/api/) BAD$(printf %s\n $INCLUDE_PATHS | grep -cvE ^/api/[A-Za-z0-9._{}/-]$) [ $COUNT -ge 15 ] || { echo Only $COUNT include paths read from $CI_STEP. Stop and check that script.; exit 1; } [ $BAD -eq 0 ] || { echo $BAD malformed include path(s) in $CI_STEP. Stop.; exit 1; } printf %s\n $INCLUDE_PATHS | sed s|^|--include-path | | xargs node scripts/capture_oas_snapshot该块内置了两道防护捕获脚本的 include 列表若被重排或移动数量不足 15 条立即停止任何非/api/普通路径形状的条目直接拒绝。原因是快照捕获对缺失路径是“静默丢弃”的——坏列表会让路由从oas_docs/output/*.yaml中消失进而被 API 契约检查误读为端点被删除。运行 OpenAPI 捆绑脚本bash .buildkite/scripts/steps/openapi_bundling/security_solution_openapi_bundling.sh bash .buildkite/scripts/steps/openapi_bundling/final_merge.sh重建最终 OAS 文档cd oas_docs make api-docs完成刷新后再回到第 3 节的带--path的校验命令。技能同时说明何时不必刷新开发者明确只要一次快速本地复验或本会话中已刷新过oas_docs且相关输入没有变化。8. 小结debug-oas 技能把“OAS 校验失败”这一笼统状态拆成了一条可操作的调试流水线确定作用域向开发者拿到正在改动的路由路径用可重复的--path过滤默认--only traditional先保证输入新鲜可疑结果先走 OAS 刷新流程把“环境问题”与“规范问题”分开分类汇报按structural阻塞性非法 OAS先行报告与qualitydescription/summary/example/examples缺口分列数量并给出逐字样例降噪与收敛超过 25 条时用辅助脚本提取 structural 摘要并按 产品区域 → 功能区域 → 路由族 的顺序收窄--path保留原始输出辅助摘要只是补充精确调试始终以 CLI 的完整输出为准。所有结论背后都有可复核的仓库证据技能文档 SKILL.md、辅助脚本 extract_structural_oas_issues.js、CLI 入口 validate_oas_docs.js以及实现包 kbn-validate-oas 中的 cli.ts、path_filters.ts 与 error_categorization.ts。【免费下载链接】kibanaYour window into all of your data项目地址: https://gitcode.com/GitHub_Trending/ki/kibana创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
