---
name: metadata-validator
description: 当需要确认候选表、字段、字段归属、字段类型、时间列、分区列和 join key 是否真实存在于工作区元数据中时使用。消费 requirements-analysis 的 requirements_output，产出 validation_result 和 field_mapping；不写 SQL，不调用 MCP。
---

# Metadata Validator（元数据校验）

## 目标

把需求里“想用的表和字段”与真实元数据对齐，防止模型凭感觉编表名、字段名和关联键。下游只能使用本 skill 确认过的字段映射。

## 输入

```yaml
requirements_output:
  status: READY_FOR_METADATA
  candidate_tables: []
  candidate_fields: []
  join_hints: []
metadata_files: "当前工作区中的数据字典、DDL、schema、CSV 表头、Markdown 表格、Excel 等"
```

如果 `requirements_output.status` 不是 `READY_FOR_METADATA`，停止并回到 `requirements-analysis`。

## 元数据查找顺序

1. 递归查看工作区中的元数据文件，不只相信文件名。
2. 优先读取结构化文件：DDL、JSON/YAML schema、CSV/Excel 数据字典、Markdown 表格。
3. 对每张表记录证据：文件路径、表名出现位置、字段名、类型、注释、枚举。
4. 文件名只能作为线索，不能作为存在性证据。

## 校验规则

- 字段在别的表里存在，不等于在目标表里存在。
- 字段名相似不等于字段可替换，必须保留候选并让用户确认。
- 时间字段有多个时必须问清楚事件时间、分区时间和统计归属。
- join key 有多个候选时必须问清楚，并标注基数风险。
- 金额、数量、比率类指标要确认类型、单位和精度。
- 结果表如果要写入，必须校验目标表存在性和字段兼容性；`INSERT OVERWRITE` 还需要用户显式确认。

## 工作顺序

1. 整理所有候选表和候选字段。
2. 从元数据中确认表是否存在。
3. 校验字段是否存在于正确表中，并记录类型和来源。
4. 校验指标字段是否适合聚合，时间字段是否适合时间过滤。
5. 校验 join key 两边都存在，记录类型一致性和基数假设。
6. 校验分区字段、状态枚举、金额单位等会影响结果的细节。
7. 对缺失项给出证据和候选替代，不猜。
8. 如果缺表、缺字段或 join/time 不明确，停止。

## 输出格式

```yaml
validation_result:
  status: VALIDATED | NEED_USER_CONFIRMATION
  metadata_sources:
    - path: "元数据文件路径"
      evidence: "表/字段证据摘要"
  validated_tables:
    - table: "物理表名"
      role: fact | dimension | lookup | target | unknown
      source_file: "元数据来源"
  validated_fields:
    - table: "表名"
      column: "字段名"
      type: "字段类型"
      comment: "字段注释"
      source_file: "元数据来源"
  field_mapping:
    "业务字段名":
      table: "物理表名"
      column: "物理字段名"
      type: "字段类型"
      role: dimension | metric | filter | time | partition | join_key | output
      source_file: "元数据来源"
      confidence: high | medium | low
  joins:
    - left: "表A.字段"
      right: "表B.字段"
      type: inner | left | right | full | unknown
      cardinality: "1:1 | 1:N | N:1 | N:N | unknown"
      confidence: high | medium | low
  time_fields:
    - table: "表名"
      event_time: "事件时间字段"
      partition_time: "分区字段，可为空"
  missing_tables: []
  missing_fields: []
  alternatives:
    "缺失项": ["可能候选"]
  pending_questions:
    - "需要用户确认的问题"
```

## 停止条件

只在所有必需表、字段、join key、时间字段和目标写入字段都确认后输出 `VALIDATED`。否则输出 `NEED_USER_CONFIRMATION`。