yrtv/utils/json_extractor

JSON Schema Extractor

用于从大量 5E Arena 比赛数据 (iframe_network.json) 中提取、归纳和分析 JSON Schema 的工具。它能够自动处理复杂的嵌套结构，识别动态 Key（如 SteamID、5E ID、Round Number），并生成层级清晰的结构报告。

✨ 核心功能

• 批量处理: 自动扫描并处理目录下的所有 iframe_network.json 文件。
• 智能归并:
  • 动态 Key 掩码: 自动识别并掩盖 SteamID (<steamid>)、5E ID (<5eid>) 和回合数 (<round_n>)。
  • 结构合并: 自动将 group_1/group_2 合并为 group_N，将 fight/fight_t/fight_ct 合并为 fight_any。
• 多格式输出:
  • schema_summary.md: 易于阅读的 Markdown 层级报告。
  • schema_full.json: 包含类型统计和完整结构的机器可读 JSON。
  • schema_flat.csv: 扁平化的 CSV 字段列表，方便 Excel 查看。
• 智能分类: 根据 URL 路径自动将数据归类（如 Match Data, Leetify Rating, Round Data 等）。

🚀 快速开始

1. 运行提取器

在项目根目录下运行：

# 使用默认配置 (输入: output_arena, 输出: output_reports/)
python utils/json_extractor/main.py

# 自定义输入输出
python utils/json_extractor/main.py --input my_data_folder --output-md my_report.md

2. 查看报告

运行完成后，在 output_reports/ 目录下查看结果：

• schema_summary.md: 推荐首先查看此文件，快速了解数据结构。
• schema_flat.csv: 需要查找特定字段（如 adr）在哪些层级出现时使用。

🛠️ 规则配置

核心规则定义在 utils/json_extractor/rules.py 中，你可以根据需要修改：

• ID 识别: 修改 STEAMID_REGEX 或 FIVE_E_ID_REGEX 正则。
• URL 过滤: 修改 IGNORE_URL_PATTERNS 列表以忽略无关请求（如 sentry 日志）。
• Key 归并: 修改 get_key_mask 函数来添加新的归并逻辑。

📊 结构分析工具

如果需要深入分析某些结构（如 fight 对象的变体），可以使用分析脚本：

python utils/json_extractor/analyze_structure.py

该脚本会统计特定字段的覆盖率，并检查不同 API（如 Round API 与 Leetify API）的共存情况。

📁 目录结构

utils/json_extractor/
├── extractor.py         # 核心提取逻辑 (SchemaExtractor 类)
├── main.py              # 命令行入口
├── rules.py             # 正则与归并规则定义
├── analyze_structure.py # 结构差异分析辅助脚本
└── README.md            # 本说明文件