Hydros Engine Skill Analyst

时间转换：仿真步到实际时间的转换需要 step_resolution（秒/步）。如果结果文件中没有此信息，向用户询问。常见值为 120 秒/步。仿真起始时间通常为 biz_start_time（如 2025/01/01 00:00:00）。

历史实测数据（Excel）

Excel 文件包含多个 Sheet，每个 Sheet 代表一个节制闸。

标准列结构：

Excel 还可能包含分水口/退水闸流量列（名称不固定，位于流量列之后）和设计水位列。

加载步骤

1. 用 pandas 读取 MCP 仿真结果文件：.csv 用 pd.read_csv(...)，.xlsx 用 pd.read_excel(..., sheet_name=0)
2. 用 openpyxl 或 pandas 读取 Excel 各 Sheet：pd.read_excel(excel_path, sheet_name=None)
3. 展示两边的数据摘要：对象数、指标、时间范围
4. 确认 step_resolution（默认 120s）

阶段二：对象匹配

MCP 仿真对象和 Excel Sheet（节制闸）之间的对应关系必须优先通过 MDM 元数据 建立，不能默认用静态映射表或直接用仿真对象名猜测。

MDM 优先匹配逻辑

对于每个历史 Excel Sheet：

1. 从 Sheet 名提取闸站关键词，例如去掉 倒虹吸出口节制闸、渡槽进口节制闸、节制闸 等后缀。
2. 调用 hydros-engine-mdm.fetch_gate_info(waterway_id, station_name) 查询闸站。
3. 从 MDM 返回中读取：
   • station_front_section：闸前断面
   • station_back_section：闸后断面
4. 用 MDM 断面的 object_id 到仿真结果 Excel 中精确匹配 object_id。
5. 仿真侧按 metrics_code 读取 water_level / water_flow。
6. 历史侧在同一个 Sheet 内优先精确读取 闸前水位、闸后水位、流量。

匹配规则（按优先级）：

1. MDM object_id 精确匹配：station_front_section.object_id / station_back_section.object_id 命中仿真结果 object_id，置信度最高。
2. MDM object_name 精确匹配：当 ID 未命中时，用 MDM 断面名称匹配仿真结果 object_name。
3. 历史列名精确匹配：默认读取 闸前水位、闸后水位、流量；只有精确列名不存在时，才允许用 上游水位、下游水位、过闸流量 等别名兜底。
4. 失败显式输出：MDM 查不到、断面缺失、仿真序列缺失或历史列缺失时，必须在报告的映射诊断表中写明状态和原因，不得静默套用旧映射。

指标映射

展示与确认

以 markdown 表格展示匹配结果，让用户确认或修正：

| 序号 | Excel Sheet | MCP 对象 | 匹配指标 | 置信度 |
|------|------------|---------|---------|--------|
| 1 | 北易水倒虹吸出口节制闸 | FSK2-北易水退水闸 | water_level, water_flow | 高 |
| 2 | 北拒马 | FSK6-北拒马退水闸 | water_level, water_flow | 高 |
| 3 | 沙河（北）倒虹吸出口节制闸 | (待确认) | - | 低 |

用户确认后进入数据质量检查。

通用映射脚本

优先使用 scripts/build_mdm_gate_map.py 生成映射文件。该脚本以当前仿真结果为入口，读取 waterway_id / biz_scenario_id，用 MDM 水网模型中的 GateStation 过滤当前仿真实际存在的闸前/闸后断面，再从历史 Excel 全量 Sheet 中反查观测 Sheet，避免把不属于当前仿真范围的历史 Sheet 引入对比。

典型流程：

python3 scripts/build_mdm_gate_map.py \
  --simulation-file SIM_TASK.xlsx \
  --history-excel 节制闸数据.xlsx \
  --mdm-model objects.yaml \
  --output mdm_gate_map.json \
  --diagnostics mapping_diagnostics.csv

python3 scripts/forebay_water_level_report.py \
  SIM_TASK.xlsx \
  节制闸数据.xlsx \
  output_dir \
  --mdm-map-json mdm_gate_map.json

阶段 2.5：数据质量检查（恒定值检测）

在进行对比计算之前，必须先检查两边数据是否存在恒定不变的情况。恒定数据意味着仿真未真正运行或传感器故障，对比没有意义。

为什么要做这个检查

仿真引擎可能因为初始化问题、边界条件缺失或智能体未响应，导致某些对象的输出值在整个仿真过程中完全不变（方差为 0）。如果不检测就直接算 RMSE/NSE，会得到误导性的结果——比如一个恒定值恰好接近实测均值，NSE 看起来还不错，但实际上仿真根本没有动态响应。

检测规则

对每个匹配的对象-指标组合，分别检查仿真侧和实测侧：

检测步骤

1. 对仿真结果文件中每个对象-指标组合，计算 std, min, max, mean
2. 对 Excel 中对应时间段的数据做同样计算
3. 按上表规则标记
4. 在报告中单独列出数据质量问题表：

## 数据质量检查

| 对象 | 指标 | 数据源 | 问题 | 详情 |
|------|------|--------|------|------|
| FSK2-北易水退水闸 | water_flow | 仿真 | SIM_ZERO | 所有值为 0，退水闸未激活 |
| ZM1-入口断面 | water_level | 仿真 | SIM_NEAR_CONSTANT | std=0.002, CV=0.003% |

5. 对标记为 SIM_CONSTANT 或 SIM_ZERO 的组合，仍然生成对比图表（方便用户直观看到问题），但在误差统计表中标注"不适用"而非给出误导性的 NSE 值

恒定值的常见原因

阶段三：时间对齐与对比计算

时间对齐策略

仿真时间（如 2025/01/01 起）和历史实测时间（如 2017~2024）通常不在同一时间窗口。采用以下策略之一（询问用户选择）：

1. 相对时间对齐（推荐）：忽略绝对日期，按仿真的相对时长（如前 3 天）截取历史数据中任意连续 3 天的数据做对比。让用户指定历史数据的起始日期。
2. 全量统计对比：不做逐步对齐，而是比较两边数据的统计分布特征（均值、标准差、范围）。
3. 用户指定映射：用户提供仿真时间 ↔ 历史时间的明确对应关系。

对比计算

对每一对匹配的对象-指标组合，使用 scripts/compare_timeseries.py 计算：

单位转换注意

• 闸门开度：Excel 中可能是 mm，MCP 中可能是 m，需要统一
• 如果数值量级差异大于 100 倍，自动提示用户检查单位

阶段四：生成图表与报告

图表（使用 scripts/compare_timeseries.py）

对每一对匹配的对象-指标，生成：

1. 时序对比图 — 仿真值和实测值叠加在同一张图上
   • 双 Y 轴（如量级差异大）或单 Y 轴
   • 标注 RMSE 和 NSE 值在图表标题或角落
2. 误差时序图 — 每个时间步的仿真-实测偏差
   • 标注零线和 ±标准差带
3. 散点图 — 仿真值 vs 实测值
   • 画 1:1 参考线
   • 标注 R² 值
4. 综合误差汇总柱状图 — 所有匹配对象的 RMSE/NSE 对比

输出目录必须参考 hydros-engine-skill-executor 的层级组织，不再把 HTML、payload、CSV 平铺在 output_dir 根目录：

如果旧版本已在根目录生成 validation.html、mdm_gate_validation_payload.json、mdm_gate_validation_metrics.csv，重新生成时应清理这些旧平铺产物，避免用户误打开过期文件。

HTML 报告模板

验证报告页面模板必须沉淀在 assets/validation-report-template/index.html。生成脚本负责读取模板并替换占位符，避免把整页 HTML/CSS/JS 长期硬编码在脚本里。

当前规范：生成的 report/validation.html 采用 数据内联，即在 HTML 内直接写入报告 payload，保证单文件可打开和可上传。assets/validation-report-template/validation.data.js 仅作为未来外置数据模式的保留文件，当前不要在 HTML 中引用，也不要要求用户额外携带该文件。

报告中的长表必须提供分类过滤：误差统计表至少支持按指标和结果判断过滤，映射诊断表至少支持按指标和匹配结果过滤，数据质量检查表至少支持按指标和数据提示过滤。报告面向业务人员时，表头和单元格不要直接暴露 MDM_OBJECT_ID、SIM_NEAR_CONSTANT、OBS_COLUMN_MISSING 等内部状态码，应转换为“按仿真断面编号匹配”“仿真变化过小”“缺少实测列”等通俗中文。

统计报告

生成 output/validation/validation_report.md（或 Word），包含：

1. 对比概况 — 数据来源、匹配对象数、时间范围
2. 逐对象误差表 — 每个匹配对的 RMSE / MAE / NSE / R² 汇总
3. 图表 — 插入所有对比图
4. 精度评级 — 根据 NSE 值给出评级：
   • NSE > 0.75：优秀
   • 0.50 < NSE ≤ 0.75：良好
   • 0.25 < NSE ≤ 0.50：一般
   • NSE ≤ 0.25：较差
5. 结论与建议 — 哪些对象仿真精度高/低，可能的原因分析

快捷入口

依赖

• Python: pandas, openpyxl, matplotlib, numpy
• 安装：pip3 install pandas openpyxl matplotlib numpy --break-system-packages 或使用 venv
• 中文字体设置同 hydros-engine-simulation-skill

京石段对象映射参考表

以下是已知的 MCP 仿真对象与中线工程节制闸的映射关系（持续更新）：

已知数据质量问题

当匹配到新的对应关系或发现新的数据质量问题时，应更新此表。