需要验证、审计或修复 PromQL 查询与告警规则时…

当用户提供 PromQL 查询或告警规则，需要独立审查、监控设置验证、排查慢查询、recording rules 代码审查或教学，并检查正确性、解释行为、优化性能与确认监控意图时使用。

适用场景

解决思路

1. 从仓库根目录运行验证命令，使相对路径正确解析：`cd "$(git rev-parse --show-toplevel)"`。
2. 如果从其他位置运行，对 `scripts/` 文件使用绝对路径。
3. 运行语法验证脚本检查基本正确性：`python3 devops-skills-plugin/skills/promql-validator/scripts/validate_syntax.py "<query>"`。
4. 解析语法脚本输出：退出码 `0` 表示语法有效；退出码非零表示语法失败，包含 stderr 并定位 token/位置；优先引用最小的失败片段，然后提供修正后的查询。
5. 使用语法脚本检查：有效指标名和标签匹配器；正确的运算符用法；正确的函数语法；有效的时间持续时间和范围；括号和引号平衡；正确使用修饰符（offset、@）。
6. 运行最佳实践检查器检测反模式和优化机会：`python3 devops-skills-plugin/skills/promql-validator/scripts/check_best_practices.py "<query>"`。
7. 解析最佳实践脚本输出：将脚本各节视为独立发现（cardinality、metric-type misuse、regex misuse 等）；如果脚本输出为空但查询复杂，增加人工合理性检查并标记为 `manual-review`；保留脚本发现标签的措辞，然后用简单英文添加修复建议。
8. 使用最佳实践脚本识别：无标签过滤器的高基数查询；可改为精确匹配的低效正则匹配器；计数器指标缺少 `rate()`/`increase()`；对 gauge 指标使用 `rate()`；对预先计算的分位数取平均；时间范围过大的子查询；长时间范围使用 `irate()`；可增加更具体标签过滤器的机会；应使用 recording rules 的复杂查询。
9. 解析并用简单英文解释查询：查询哪些指标；指标类型（counter、gauge、histogram、summary）；应用了哪些函数及原因；查询计算什么；输出中将有哪些标签；预期结果结构。
10. 解释查询时必须明确包含：`**Output Labels**`: [结果中的标签列表，或 "None (fully aggregated to scalar)"]；`**Expected Result Structure**`: [instant vector / range vector / scalar] with [N series / single value]。
11. 引用示例/文档时使用文件路径 + 从 1 开始的行号：`examples/good_queries.promql:42`、`docs/best_practices.md:88`；引用最相关的单行（或多行片段的起始行）；保持引用简短，不要引用整个文件；如果行号不可用，写明 `line number unavailable` 并提供文件路径。
12. 进行交互式查询规划（Phase 1 - 停止并等待）：询问用户澄清问题以验证查询是否符合意图；理解目标：“你试图监控或测量什么？”（请求速率、错误率、延迟、资源使用等）；验证指标类型：“这是 counter（只增）、gauge（可增可减）、histogram 还是 summary？”；澄清时间范围：“你需要什么时间窗口？”（即时值、随时间速率、历史分析）；确认聚合：“是否需要跨标签聚合？如果需要，按哪些标签？”（如 `by (job)`、`by (instance)`、`without (pod)`）；检查输出意图：“这是用于告警、仪表盘还是临时分析？”。
13. 呈现 Step 1-4 结果（Syntax、Best Practices、Query Explanation、Intent Questions）后，停止并等待用户回复；在用户回答澄清问题前，不要进入 Step 5-7。
14. 仅在用户回答 Step 4 的澄清问题后进入 Step 5。
15. 理解用户意图后：解释当前查询实际做什么；突出意图与实现之间的任何不匹配；如果查询不符合目标，建议修正；适用时提供替代方法。
16. 相关时提及已知限制：说明指标类型检测基于启发式（例如，“脚本根据 `_bytes` 后缀推断这是 gauge。请确认是否正确。”）；承认高基数警告可能是误报（例如，“如果你使用 recording rule 或知道基数很低，此警告可能不适用。”）。
17. 根据验证结果：建议更高效的查询模式；为复杂/重复查询推荐 recording rules；提出更好的标签匹配器以减少基数；建议适当的时间范围。
18. 引用示例时使用格式：`As shown in `examples/bad_queries.promql` (lines 91-97): ❌ BAD: `avg(http_request_duration_seconds{quantile="0.95"})` ✅ GOOD: 使用 histogram_quantile() 和 histogram buckets`。
19. 引用来源：`examples/good_queries.promql` 用于良好模式；`examples/optimization_examples.promql` 用于前后对比；`examples/bad_queries.promql` 用于展示应避免的内容；`docs/best_practices.md` 用于详细解释；`docs/anti_patterns.md` 用于反模式深入分析。
20. 引用格式：`file_path (lines X-Y)` 并引用相关代码片段。
21. 让用户控制：询问是否想修改查询；主动帮助重写以提高性能；适用时提供多个替代方案；解释不同方法之间的权衡。
22. 验证语法规则：指标名必须匹配 `[a-zA-Z_:][a-zA-Z0-9_:]*` 或使用 UTF-8 引号语法（Prometheus 3.0+）：引号形式 `{"my.metric.with.dots"}`；使用 `__name__` 标签 `{__name__="my.metric.with.dots"}`。
23. 验证语法规则：标签匹配器 `=`（等于）、`!=`（不等于）、`=~`（正则匹配）、`!~`（正则不匹配）。
24. 验证语法规则：时间持续时间 `[0-9]+(ms|s|m|h|d|w|y)`，如 `5m`、`1h`、`7d`。
25. 验证语法规则：范围向量 `metric_name[duration]`，如 `http_requests_total[5m]`。
26. 验证语法规则：Offset 修饰符 `offset <duration>`，如 `metric_name offset 5m`。
27. 验证语法规则：@ 修饰符 `@ <timestamp>` 或 `@ start()` / `@ end()`。
28. 验证语义规则：`rate()` 和 `irate()` 只应用于 counter 指标（以 `_total`、`_count`、`_sum`、`_bucket` 结尾）。
29. 验证语义规则：Counter 通常应使用 `rate()` 或 `increase()`，而不是原始值。
30. 验证语义规则：Gauge 不应使用 `rate()` 或 `increase()`。
31. 验证语义规则：Histogram 应使用 `histogram_quantile()` 配合 `le` 标签，并对 `_bucket` 指标使用 `rate()`。
32. 验证语义规则：Summary 不要平均分位数，应从 `_sum` 和 `_count` 计算。
33. 验证语义规则：聚合使用 `by()` 或 `without()` 控制输出标签。
34. 验证性能规则：始终使用具体标签匹配器减少序列数。
35. 验证性能规则：尽可能使用 `=` 代替 `=~` 进行精确匹配。
36. 验证性能规则：速率范围至少是 scrape interval 的 4 倍（通常最小 `[2m]`）。
37. 验证性能规则：`irate()` 最适合短范围（<5m）；更长周期使用 `rate()`。
38. 验证性能规则：避免处理数百万样本的过大子查询时间范围。
39. 验证性能规则：频繁访问的复杂查询使用 recording rules。
40. 检测高基数问题：❌ BAD `http_requests_total{}` 匹配所有时间序列无过滤；✅ GOOD `http_requests_total{job="api", instance="prod-1"}` 用具体标签过滤器降低基数。
41. 检测正则过度使用：❌ BAD `http_requests_total{status=~"2.."}` 正则更慢且不精确；✅ GOOD `http_requests_total{status="200"}` 精确匹配更快。
42. 检测计数器缺少 rate()：❌ BAD `http_requests_total` counter 原始值无意义（总是增加）；✅ GOOD `rate(http_requests_total[5m])` rate 显示每秒请求数。
43. 检测对 gauge 使用 rate()：❌ BAD `rate(memory_usage_bytes[5m])` gauge 测量当前状态而不是累积值；✅ GOOD `memory_usage_bytes` 直接使用 gauge 值或配合 `avg_over_time()`。
44. 检测平均分位数：❌ BAD `avg(http_request_duration_seconds{quantile="0.95"})` 平均预先计算的分位数在数学上无效；✅ GOOD `histogram_quantile(0.95, sum by (le) (rate(http_request_duration_seconds_bucket[5m])))` 从 histogram buckets 计算分位数。
45. 检测过长子查询范围：❌ BAD `rate(metric[5m])[90d:1m]` 处理数百万样本非常慢；✅ GOOD 使用 recording rules 或将范围限制到必要持续时间。
46. 检测长时间范围使用 irate()：❌ BAD `irate(metric[1h])` irate() 只看最后两个样本，范围浪费；✅ GOOD `rate(metric[1h])` 或 `irate(metric[5m])` 对更长范围使用 rate() 或减少 irate() 范围。
47. 检测混合指标类型：❌ BAD `avg(http_request_duration_seconds{quantile="0.95"}) / rate(node_memory_usage_bytes[1h]) + sum(http_requests_total)` 混合 summary 分位数、gauge 和 counter 进行算术运算产生无意义结果；✅ GOOD 保持每种指标类型在独立、用途明确的查询中：延迟 `histogram_quantile(0.95, sum by (le) (rate(http_request_duration_seconds_bucket[5m])))`；内存 `node_memory_usage_bytes{instance="prod-1"}`；请求速率 `rate(http_requests_total{job="api"}[5m])`。
48. 按指定结构输出验证结果：`## PromQL Validation Results`，包含 `### Syntax Check`（Status、Issues）、`### Semantic Check`（Status、Issues）、`### Performance Analysis`（Status、Issues、Suggestions）、`### Query Explanation`（Your query、This query does、Metrics、Functions、Output）、`### Intent Verification`（5 个问题）、`### Recommendations`。
49. 验证后进入交互对话：例如指出查询语法正确但没有标签过滤器，可能匹配数千时间序列，询问具体服务或端点；用户提供意图后，给出优化版本如 `rate(http_requests_total{job="api-service", path="/users"}[5m])`，并询问是否符合需求；用户确认或要求更改后，提供细化查询或替代方案。
50. 遵循重要注意事项：始终交互式询问澄清问题；教育性解释为什么错而不只是指出错；主动提供重写查询而不只是批评；考虑用例上下文（告警 vs 仪表盘）；彻底检查四个层面（语法、语义、性能、意图）；建议现实可行的优化而非理论完美。
51. 使用两个主要 Python 脚本：`validate_syntax.py` 纯语法检查使用正则模式；`check_best_practices.py` 语义和性能分析；两者输出 JSON 供程序解析和人类可读消息用于展示。
52. 满足成功标准：识别所有语法错误；检测语义问题；如适用建议至少一个优化；清楚解释查询做什么；验证查询符合用户意图；提供可操作下一步。

适用边界 · 注意事项

• 指标类型检测基于命名启发式，自定义指标可能误判；高基数警告对 recording rules 或已知低基数场景可能是误报，需要人工确认。
• 脚本没有运行时上下文和 schema，不能验证指标或标签值是否真实存在；生产验证应对实际 Prometheus 实例测试查询。
• 脚本无法捕获业务逻辑错误、依赖 scrape interval/retention 等上下文的优化，以及扩展带来的自定义函数行为。