---
name: "skill_log_plot_mdlog"
description: "基于 mdlog 解析结果生成 HTML/PNG 图表。当用户已经拿到 auto_analysis CSV，想用 LogPlot.py 出交互式图时调用。"
version: "1.0.0"
author: "bytedance"
tags:
  - mdlog
  - plot
  - html
  - debugging
categories:
  - development
  - debugging
dependencies: [skill_log_filter_mdlog]
---

# skill_log_plot_mdlog

## 适用场景
- `mdlog_filter_tool` 已经跑完，并且已经拿到 `auto_analysis/*.csv`。
- 需要生成 `nr_lte_combined_plot_subid_<id>.html` 或 multi-figure 页面。
- 需要为飞书报告生成“单指标单图” PNG/HTML 产物。

## 路径
```bash
export MDLOG_PLOT_SKILL="/home/bytedance/disk4T/jieli/modem_proc_ext/skills/skill_code_ai_md_power/2_data_process_tool/mdlog_filter/skill_log_filter_mdlog"
export MDLOG_PLOT_TOOL="${MDLOG_PLOT_SKILL}/scripts/mdlog_filter_tool/LogPlot.py"
```

## 推荐命令
```bash
python3 ${MDLOG_PLOT_TOOL} <auto_analysis_dir> \
  --subids 1 \
  --outdir <output_dir> \
  --with-combined \
  --multi-page \
  --page-layout grid \
  --export-single-png
```

## 输出
- `nr_lte_combined_plot_subid_<id>.html/.png`
- `nr_lte_multi_figure_subid_<id>_grid.html`
- `single_figures_subid_<id>/`
  - `<metric>_subid_<id>.html`
  - `<metric>_subid_<id>.png`

## HTML 绘图布局约束
- 优先把页面标题、图表标题、数据来源、时间范围、有效点数等说明放在 Plotly div 外部。
- Plotly 内部只保留曲线、坐标轴、图例和必要 hover；不要把内部 `title`、横向 `legend`、顶部 `annotations` 同时放在同一块顶部空间。
- 上下文信息如 RAT、BAND、频点、SCS、SubID、场景标签等优先做成图外 HTML badge/table，同时保留在 hover 中。
- 如果必须使用 annotation，必须限制数量或预留独立 margin，避免遮挡标题、图例或曲线。
- 小中等数据量默认使用 SVG `scatter`；只有确认目标浏览器支持 WebGL 且点数确实较大时，才使用 `scattergl`。
- 多指标单位差异明显时，优先拆成上下叠放图或分面图；不要为了合并而让双纵轴图变得不可读。

## 交付前自查
- 检查 HTML 渲染后是否存在标题、图例、annotation、上下文标签互相遮挡。
- 检查外部标题存在时，Plotly 内部不要再设置重复标题。
- 检查顶部 annotation 不存在，或数量受限且已预留足够 margin。
- 检查 `scattergl` 不会导致目标预览环境 WebGL 不兼容。
- 检查每张图的单位、曲线名称、时间轴、有效点数说明是否清晰。

## 说明
- 标准输入是 `auto_analysis/` 根目录；当前 run 的 mdlog CSV 以该目录下的同名文件为准。
- 历史 case 若仍保留 `auto_analysis/backup`，只作为兼容输入，不再作为新产物约定。
- 面向飞书正文时，优先使用 `single_figures_subid_<id>/` 下的单指标 PNG，不要只贴一张超长 combined 图。
- `combined` 图适合总览，`multi_figure_html` 适合交互分析，`single_figures` 适合报告嵌图。
- 如果 `LogPlot.py` 输出 `No data to plot for SubID=...`，优先回到 `skill_log_filter_mdlog` 检查 CSV 是否完整。