从 PromQL 或 ListTimeSeries…

把已解析的 PromQL 或 ListTimeSeries 查询转换为合法的 Cloud Monitoring SDUI Widget/XyChart Protocol Buffer textproto。

适用场景

解决思路

1. 优先为 widget 生成 ListTimeSeries（time_series_filter）配置，除非用户明确要求 PromQL 或指标运算必须使用 PromQL。
2. 同一个 widget dataset 的 time_series_query 中只能包含 time_series_filter 或 prometheus_query 之一，绝不能同时填充两者。
3. 必须逐字符原样复制提供的 PromQL 查询或 ListTimeSeries JSON filter 字符串，不要自行发明、改写或修改查询。
4. 保持工作目录在工作区根目录，不要 cd 进入 skill 子目录。
5. 不要运行 grep、find、目录列表或代码库查询等文件/代码搜索工具去发现指标元数据或检查仓库结构；指标描述符、PromQL 查询、ListTimeSeries JSON payload、unit 和 resource type 始终已在对话上下文中。
6. 先用 python3 直接执行随附的 Python 脚本，并先安装依赖：pip install -r scripts/requirements.txt。
7. Stage 1：运行 compute_labels.py 生成候选标签。PromQL 用 --metric_display_name、--resource_type、--metric_unit、--promql_query；ListTimeSeries 用 --metric_display_name、--resource_type、--metric_unit、--filter_string、--per_series_aligner、--cross_series_reducer。
8. Stage 2：结合用户提示、查询结构和 Stage 1 候选，构造 4 键 SemanticPlotSpec JSON：title、yAxisLabel、plotType、unitOverride。
9. title：润色 titleCandidate，使其简洁、人类可读且少于 80 个字符。
10. yAxisLabel：设置为简洁、人类可读的定量描述或指标概念，如 "Utilization"、"Bytes"、"Bytes Rate"；不要附加 "(%)"、"(/s)"、"(By)" 等单位符号或后缀，因为单位会通过 unitOverride 自动渲染。
11. plotType：默认使用 LINE；如果用户要求或用于分布查询，则使用 STACKED_AREA。
12. unitOverride：设置为 UCUM 单位字符串。ListTimeSeries 流程直接使用 Stage 1 产生的 unitOverrideCandidate（Stage 1 会数学处理 ALIGN_RATE 如生成 By/s，对 ALIGN_PERCENT_CHANGE 强制为 %，并正确输出原生归一化）。
13. PromQL 单位需手动推理：rate(...)/irate(...) 把累积计数器转为每秒速率，在原始指标单位后追加 /s（如原始 By 经 rate(...) 得 By/s）；例外是 rate() 位于 histogram_quantile() 内时输出原始 bucket 单位如 "s"，而不是速率。
14. PromQL 单位规则：100 * (A / B) 这类相同单位比值通常表示百分比，unitOverride 为 "%"；把 10^2.% 归一化为 "%"；对 avg_over_time(...) 或 sum by (...) 等简单聚合函数保留并输出底层指标单位。
15. 不要配置 legend_template 字段，故意省略它以便 Cloud Monitoring 前端在运行时动态渲染多列表格图例。
16. Stage 3：运行 assemble_widget_proto.py 生成并保存 widget textproto。PromQL 用 --promql_query 和 --spec_json；ListTimeSeries 用 --lts_request_json 和 --spec_json。
17. 不要猜测或强制指定输出文件名；脚本会自动生成保证唯一的文件名并打印到 stderr，搜索 stderr 中前缀 "Wrote widget textproto to:" 来确定性捕获文件名，并在 Stage 4 验证中使用它。
18. 在回复中用 ```textproto 代码块包裹生成的 SDUI widget textproto。
19. Stage 4 验证：对 Stage 3 生成的文件运行 validate_chart.py。PromQL 图表用 --input_file、--expected_promql_substring、--expected_unit_override；ListTimeSeries 图表用 --input_file、--expected_lts_filter_substring、--expected_unit_override；始终提供标识子串和 Stage 1 的 unit override 候选以验证数据未被改动。
20. 如果为多个指标生成了多个图表，必须对每个生成的文件分别独立运行验证脚本。
21. 如果 validate_chart 报告文件缺失或无效，检查脚本参数并立即重新运行 Stage 3。
22. 如果验证因 schema 或语法错误失败，修正参数并最多重试 2 次；2 次重试后仍失败则停止重试，通知用户验证错误，并给出尽力而为的 textproto。
23. 如果 compute_labels.py、assemble_widget_proto.py 或 validate_chart.py 因环境或沙箱限制无法执行：通知用户哪个脚本无法执行及原因；直接在回复中按所有格式和单位规则合成并输出完整 widget textproto；提供包含独立 python3 命令的 "Local Verification" 部分，供用户在本地运行和验证 schema。

适用边界 · 注意事项

• 不要用于指标发现或 PromQL 查询生成；这些任务应使用 cloud-monitoring-metric-selection 或 cloud-monitoring-promql-query 技能。
• 不要运行文件或代码库搜索工具来发现指标元数据或检查仓库结构。
• 不要 cd 进入 skill 子目录或更改工作目录。