gdelt-events-fetch

用途

gdelt-events-fetch 用于从 GDELT 2.0 的官方公共端点拉取 Events 表导出文件（*.export.CSV.zip）。其核心目标包括：从官方公共端点获取 Events 导出、通过 lastupdate.txt 解析最新可用快照、通过 masterfilelist.txt 解析 UTC 时间范围内的历史快照、持久化已下载文件并返回机器可读的 JSON 清单，以及通过结构化日志和可选日志文件保持运行时可见性。

主要能力

• 模式一：latest，解析并获取最新可用的事件快照。
• 模式二：range，按 UTC 起止时间（--start-datetime、--end-datetime）从 masterfilelist.txt 解析历史快照。
• 配置校验：check-config 校验有效配置。
• 预览：resolve-latest 查看最新可用快照。
• 下载前 dry-run，可在真正下载前检查选择结果。
• 健壮性：在瞬时 HTTP/网络失败时进行重试与指数退避；当可重试响应中带有 Retry-After 时予以遵守；通过最小请求间隔节流请求频率；使用 --max-files（GDELT_MAX_FILES_PER_RUN）强制安全上限，防止意外批量拉取；在远程调用前校验日期时间格式和范围边界。
• 下载后校验：ZIP CRC/完整性检查、UTF-8 严格解码检查、制表符列数检查（Events 默认 61 列），并可通过 --quarantine-dir 隔离问题行。
• 输出：输出 JSON 结果，并将运行日志写入 stderr 和可选日志文件。

使用方式

前置环境：通过环境变量配置运行时（参见 references/env.md），可从 assets/config.example.env 开始。加载环境变量：

set -a source assets/config.example.env set +a

典型工作流：

1. 校验配置： python3 scripts/gdelt_events_fetch.py check-config --pretty

2. 查看最新可用快照： python3 scripts/gdelt_events_fetch.py resolve-latest --pretty

3. 历史范围 dry-run： python3 scripts/gdelt_events_fetch.py fetch
   --mode range
   --start-datetime 20260301000000
   --end-datetime 20260301120000
   --max-files 3
   --dry-run
   --pretty

4. 带传输与结构校验的下载： python3 scripts/gdelt_events_fetch.py fetch
   --mode latest
   --max-files 1
   --output-dir ./data/gdelt-events
   --preview-lines 3
   --validate-structure
   --expected-columns 61
   --quarantine-dir ./data/gdelt-events-quarantine
   --log-level INFO
   --log-file ./logs/gdelt-events-fetch.log
   --pretty

在 OpenClaw 中使用时，可用 $gdelt-events-fetch 触发该技能。提供方给出以下提示词模板（仅替换方括号占位符）：

Recon（查看最新可用性）： Use $gdelt-events-fetch. Run: python3 scripts/gdelt_events_fetch.py resolve-latest --pretty Return only the JSON result.

Fetch（历史窗口，先 dry-run）： Use $gdelt-events-fetch. Run: python3 scripts/gdelt_events_fetch.py fetch
--mode range
--start-datetime [YYYYMMDDHHMMSS]
--end-datetime [YYYYMMDDHHMMSS]
--max-files [N]
--dry-run
--pretty

Then run without --dry-run using: --output-dir [OUTPUT_DIR] --validate-structure --expected-columns 61 --quarantine-dir [QUARANTINE_DIR] Return only the JSON result.

Validate（下载质量门禁）： Use $gdelt-events-fetch. Run: python3 scripts/gdelt_events_fetch.py fetch
--mode latest
--max-files 1
--output-dir [OUTPUT_DIR]
--validate-structure --expected-columns 61
--quarantine-dir [QUARANTINE_DIR]
--pretty Check validation.issue_count, decode_error_count, column_mismatch_count. Return JSON plus one-line pass/fail verdict.

适用场景

• 需要获取 GDELT 2.0 Events 表最新导出快照。
• 需要按 UTC 时间范围获取历史 Events 导出快照。
• 需要对下载结果进行完整性、编码和列结构校验，并对问题行进行隔离。
• 需要在 OpenClaw 等智能体环境中以原子操作方式按需拉取数据。

范围与限制

• 仅保留一种具体的文件表拉取实现：Events 导出（*.export.CSV.zip）。
• 仅保留原子操作，不包含内部调度器/轮询循环。若需轮询，应由 OpenClaw 智能体在外部编排重复调用（调度器/循环），而非在本技能内部实现。
• 提供方给出的参考资料包括：references/gdelt-data-sources.md、references/gdelt-limitations.md、references/env.md、references/openclaw-chaining-templates.md。