gdelt-gkg-fetch

用途

gdelt-gkg-fetch 用于抓取 GDELT 2.0 GKG 表导出文件（*.gkg.csv.zip），数据来源为官方公开端点。它专注于单一具体文件表：GKG。该技能保持原子操作，只做按需的解析与抓取，不包含内部调度器或轮询循环。

主要能力

解析最新可用快照：通过 lastupdate.txt。
解析历史快照：通过 masterfilelist.txt，支持指定 UTC 时间范围。
持久化下载的文件，并返回机器可读的 JSON 清单。
运行时可观测：结构化日志，并可选写入日志文件。

使用方式

需要配置环境变量（参见 references/env.md），可从 assets/config.example.env 开始。加载环境变量：

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

工作流程示例：

校验有效配置：

python3 scripts/gdelt_gkg_fetch.py check-config --pretty

查看最新可用 GKG 快照：

python3 scripts/gdelt_gkg_fetch.py resolve-latest --pretty

下载前先对历史范围选择做 dry-run：

python3 scripts/gdelt_gkg_fetch.py fetch \
  --mode range \
  --start-datetime 20260301000000 \
  --end-datetime 20260301120000 \
  --max-files 3 \
  --dry-run \
  --pretty

带传输与结构验证地抓取文件：

python3 scripts/gdelt_gkg_fetch.py fetch \
  --mode latest \
  --max-files 1 \
  --output-dir ./data/gdelt-gkg \
  --preview-lines 2 \
  --validate-structure \
  --expected-columns 27 \
  --quarantine-dir ./data/gdelt-gkg-quarantine \
  --log-level INFO \
  --log-file ./logs/gdelt-gkg-fetch.log \
  --pretty

内置健壮性

对瞬时 HTTP/网络失败应用带指数退避的重试。
对可重试响应，遵循响应中的 Retry-After。
通过设置请求之间的最小间隔来限流。
强制执行 --max-files 安全上限（GDELT_MAX_FILES_PER_RUN），防止意外批量拉取。
在远程调用前校验日期时间格式与范围边界。
下载后执行传输与结构验证：
- ZIP CRC/完整性检查
- UTF-8 严格解码检查
- 制表符列数检查（默认 27）
- 可选的坏行问题隔离（--quarantine-dir）
输出 JSON 结果，同时把运行日志写入 stderr 和可选日志文件。

范围决策

仅保留一个具体文件表抓取实现：GKG（*.gkg.csv.zip）。
仅保留原子操作；不添加内部调度/轮询循环。

参考文件

references/gdelt-data-sources.md
references/gdelt-limitations.md
references/gdelt-schema.md
references/env.md
references/openclaw-chaining-templates.md

脚本

scripts/gdelt_gkg_fetch.py

OpenClaw 调用兼容性

技能触发元数据保留在 name、description 和 agents/openai.yaml 中。
在提示词中用 $gdelt-gkg-fetch 调用。
保持技能原子化：仅按需解析/抓取。
使用脚本参数设置抓取条件（--mode range --start-datetime --end-datetime）。
如需轮询，由 OpenClaw 在外部编排重复调用，而不是在该技能内部。

OpenClaw 提示词模板

以下模板可直接在 OpenClaw 中使用，只需替换方括号占位符。

侦察（最新可用性）：

Use $gdelt-gkg-fetch.
Run:
python3 scripts/gdelt_gkg_fetch.py resolve-latest --pretty
Return only the JSON result.

抓取（历史窗口，先 dry-run）：

Use $gdelt-gkg-fetch.
Run:
python3 scripts/gdelt_gkg_fetch.py fetch \
  --mode range \
  --start-datetime [YYYYMMDDHHMMSS] \
  --end-datetime [YYYYMMDDHHMMSS] \
  --max-files [N] \
  --dry-run \
  --pretty

随后不带 --dry-run 运行，使用：

  --output-dir [OUTPUT_DIR]
  --validate-structure
  --expected-columns 27
  --quarantine-dir [QUARANTINE_DIR]
Return only the JSON result.

验证（下载质量门）：

Use $gdelt-gkg-fetch.
Run:
python3 scripts/gdelt_gkg_fetch.py fetch \
  --mode latest \
  --max-files 1 \
  --output-dir [OUTPUT_DIR] \
  --validate-structure \
  --expected-columns 27 \
  --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 GKG 数据的任务，无论是获取最新快照，还是按 UTC 时间范围获取历史快照。

限制

该技能不包含内部调度或轮询循环，如需轮询需由外部编排重复调用。有关 GDELT 数据源与限制的更多信息参见 references/gdelt-data-sources.md 和 references/gdelt-limitations.md。其他具体收费、价格、平台限制等细节暂未提供。