评审 Kibana dashboard JSON 变更：用…

在 PR 或分支中评审 Kibana dashboard JSON 文件的变更、比较分支间仪表板导出、总结变化并检查官方 dashboard 指南合规时使用。

适用场景

解决思路

1. 阅读 references/review-procedure.md 获取完整逐步工作流。
2. 识别变更的 dashboard 文件（新增、删除、修改）。
3. 使用 kbdash 提取变更前/后的描述；将输出中以 [!] 开头的行视为关于仪表板 JSON 潜在问题的警告（一致性不匹配、提取不完整、解析错误）；运行 kbdash -h 查看每种警告类型的说明。
4. 比较描述，并将变更分类为有意义的变更或表面性变更。
5. 报告前，针对原始 JSON 验证疑似问题。
6. 将输出格式化为每个 dashboard 一节，并用项目符号列出变更。
7. 对新增或修改的 dashboard 检查指南合规性。
8. 总结变更后，对每个新增或修改的 dashboard 的最终状态对照官方 dashboard guidelines 检查；在每个 dashboard 的变更摘要后添加 Guideline notes 子节报告违规。
9. 检查 TSVB panels：标记任何使用 TSVB 的 visualization panel；指南要求所有新可视化使用 Lens，并鼓励将现有 TSVB 迁移到 Lens。
10. 检查缺少 dataset filter：每个可视化应过滤 data_stream.dataset 或同等具体范围；标记查询 broad index patterns（metrics-*、logs-*）且未限定范围的面板。
11. 检查按引用可视化：Visualization 和 lens panels 应以值嵌入；在原始 JSON 中，带 panelRefName 的 references 条目表示按引用面板；仅当 reference type 为 visualization、lens 或 map 时标记；Saved searches（search 类型）本质上按引用，不应标记。
12. 检查废弃 input controls：input-control-vis 类型已废弃，应使用 dashboard-native controls。
13. 检查包名标题前缀：匹配 [<Package Name> ...] 的面板标题会造成不必要重复，标记这些。
14. 检查 broad wildcard filters：使用未限定范围的 -* patterns 且无进一步限定的过滤器是性能问题。
15. 检查 high panel count：如果 dashboard 有超过约 20 个 panels，指出；指南建议拆分到多个 dashboard 并用 drilldowns 链接。
16. 检查 queries on event.dataset instead of data_stream.dataset：Saved-object queries（dashboards、saved searches、packaged ML job datafeeds）必须过滤 data_stream.dataset；有些 inputs（如 packetbeat）从不设置 event.dataset，因此 event.dataset 过滤会静默匹配不到任何内容；标记 diff 中重命名或重映射字段的每个 saved-object query。
17. 检查 YAML dashboard sources out of sync：当 package 在 _dev/shared/kibana/*.yaml 保留 YAML dashboard sources（用 kb-dashboard 编译为 kibana/dashboard/*.json）时，两者都必须提交并保持同步；当该 dashboard 存在 YAML source 时，标记仅 JSON 的编辑。
18. 检查 Regeneration diffs：重新编译 PR 预期只更改 state.adHocDataViews、state.internalReferences 和 per-layer index keys（Kibana 9.3+ 的 ES|QL/Discover 修复）；在 regenerate PR 中超出这些 keys 的 diff 值得检查。
19. 检查 Missing Kibana asset tags：新的 content-pack dashboards 预期带有 Kibana asset tags——注意其缺失（LOW）。
20. 仅报告实际存在的问题——跳过通过的检查。
21. 对于未更改面板中的既有违规，只简要提一次（例如 'N existing panels also use TSVB'），而不是逐一列出。
22. 将评审注意力集中在新添加或修改的面板上。
23. 评审完成后：若评审暴露结构问题，转给 dashboard-guidelines 获取创建或导出指导；当 dashboard 变更需要 release note entry 时转给 package-spec；validation commands 转给 elastic-package-cli。

适用边界 · 注意事项

• 不要作为创建新 dashboards 或从 Kibana 导出它们的主要指南（用 dashboard-guidelines）。
• 不要用于 dashboard 命名约定和文件布局（用 dashboard-guidelines → references/kibana-assets-layout.md）。
• 不要用于包级命令编排（用 elastic-package-cli）或测试套件选择（用 integration-testing）。