data-quality-checker

概述

在发布前检测市场分析文档中常见的数据质量问题。检查器会验证五个类别：价格尺度一致性、金融工具表示法、日期与星期准确性、配置比例总和以及单位用法。所有发现都仅供参考——用于标记潜在问题，供人工审核，而不会阻止发布。

使用场景

• 发布每周策略博客或市场分析报告之前
• 生成自动化市场摘要之后
• 审核已翻译的文档（英语/日语），检查数据准确性
• 将来自多个来源（FRED、FMP、FINVIZ）的数据整合到一份报告中时
• 对任何包含金融数据的文档进行发布前检查

前置条件

• Python 3.9+
• 无需外部 API 密钥
• 无需第三方 Python 软件包（仅使用标准库）

工作流

第 1 步：接收输入文档

接受目标 Markdown 文件路径和可选参数：

• --file：要验证的 Markdown 文档路径（必填）
• --checks：要运行的检查项列表，以逗号分隔（可选；默认：全部）
• --as-of：用于推断年份的参考日期，格式为 YYYY-MM-DD（可选）
• --output-dir：报告输出目录（可选；默认：reports/）

第 2 步：运行验证脚本

运行数据质量检查脚本：

python3 skills/data-quality-checker/scripts/check_data_quality.py \
  --file path/to/document.md \
  --output-dir reports/

仅运行指定的检查项：

python3 skills/data-quality-checker/scripts/check_data_quality.py \
  --file path/to/document.md \
  --checks price_scale,dates,allocations

提供用于推断年份的参考日期（适用于日期中未明确标注年份的文档）：

python3 skills/data-quality-checker/scripts/check_data_quality.py \
  --file path/to/document.md \
  --as-of 2026-02-28

第 3 步：加载参考标准

阅读相关参考文档，以便结合背景信息解读发现：

• references/instrument_notation_standard.md —— 标准股票代码表示法、位数提示，以及各类金融工具的命名规范
• references/common_data_errors.md —— 常见错误目录，包括 FRED 数据延迟、ETF/期货尺度混淆、节假日疏漏、配置比例总和问题以及单位混淆模式

使用这些参考资料解释发现并提出修正建议。

第 4 步：审查发现

检查输出中的每项发现：

• ERROR —— 置信度较高的问题（例如，通过日历计算确认的日期与星期不匹配）。强烈建议修正。
• WARNING —— 可能存在、需要人工判断的问题（例如，价格尺度异常、表示法不一致、配置比例总和偏差超过 0.5%）。
• INFO —— 提示性备注（例如，bp/% 混用，这可能是有意为之）。

第 5 步：生成质量报告

脚本会生成两个输出文件：

1. JSON 报告（data_quality_YYYY-MM-DD_HHMMSS.json）：机器可读的发现列表，包含严重性、类别、消息、行号和上下文。
2. Markdown 报告（data_quality_YYYY-MM-DD_HHMMSS.md）：按严重性级别分组的易读报告。

向用户展示发现，参考知识库进行解释，并为每个问题提出具体的修正建议。

输出格式

JSON 发现结构

{
  "severity": "WARNING",
  "category": "price_scale",
  "message": "GLD: $2,800 has 4 digits (expected 2-3 digits)",
  "line_number": 5,
  "context": "GLD: $2,800"
}

Markdown 报告结构

# Data Quality Report
**Source:** path/to/document.md
**Generated:** 2026-02-28 14:30:00
**Total findings:** 3

## ERROR (1)
- **[dates]** (line 12): Date-weekday mismatch: January 1, 2026 (Monday) -- actual weekday is Thursday

## WARNING (2)
- **[price_scale]** (line 5): GLD: $2,800 has 4 digits (expected 2-3 digits)
  > `GLD: $2,800`
- **[allocations]**: Allocation total: 110.0% (expected ~100%)

资源

• scripts/check_data_quality.py —— 主验证脚本
• references/instrument_notation_standard.md —— 表示法和价格尺度参考
• references/common_data_errors.md —— 常见错误模式及预防方法

核心原则

1. 建议模式：所有发现都作为警告，供人工审核。即使存在发现，脚本在成功执行时也始终以代码 0 退出。退出代码 1 仅用于脚本失败（文件未找到、解析错误）。

2. 按章节检查配置比例：仅检查配置章节中的百分比（通过「配分」「Allocation」等标题或「ウェイト」「目安比率」等表格列识别）。正文中随机出现的百分比（概率、RSI、同比增长）会被忽略。

3. 双语支持：支持英文和日文的日期格式、星期名称及章节标题。处理前会对全角字符（％、〜、短横线）进行规范化。

4. 推断年份：对于未明确标注年份的日期，检查器会按以下优先顺序推断年份：--as-of 选项、文档标题或元数据中找到的 YYYY 模式，或结合 6 个月跨年启发式规则使用当前年份。

5. 位数启发式规则：价格尺度验证使用位数（小数点前的数字个数），而非绝对价格范围。这种方法能够适应价格随时间变化，同时仍可发现 ETF／期货混淆错误。