用途：针对 https://api.gdeltproject.org/api/v2/doc/doc 执行原子化的 GDELT DOC API 检索，用于按主题或域名获取新闻文档数据。每次调用只执行一次查询，不内置调度或轮询循环。
主要能力：支持显式查询语法；支持相对时间窗口（timespan）与绝对 UTC 时间窗口（STARTDATETIME、ENDDATETIME）；返回结构化 JSON，并可将原始响应写入文件；提供结构化日志与可选日志文件，运行过程可观测。内置对瞬时 HTTP/网络失败的指数退避重试，在可重试响应中遵循 Retry-After，按最小请求间隔限流，并在远程调用前校验查询与时间参数组合，校验 DOC 约束（MAXRECORDS<=250、TIMELINESMOOTH<=30）。
使用方式：先配置环境变量，可从 assets/config.example.env 起步，用 set -a 与 source、set +a 加载。校验配置：python3 scripts/gdelt_doc_search.py check-config --pretty。相对窗口检索示例：python3 scripts/gdelt_doc_search.py search --query '("climate change" OR pollution)' --mode artlist --format json --timespan 1day --max-records 50 --pretty。绝对窗口时间线查询：python3 scripts/gdelt_doc_search.py search --query '("climate change" OR pollution) sourcecountry:us' --mode timelinevolraw --format json --start-datetime 20260301000000 --end-datetime 20260308000000 --timeline-smooth 5 --pretty。可用 --output ./data/gdelt-doc/wildfire.json 持久化原始结果。在 OpenClaw 提示中可用 $gdelt-doc-search 触发，并仅替换方括号占位符。
适用场景：需要按主题或域名检索新闻文档、生成时间线统计、将原始响应交给下游工具的场景。
限制：仅覆盖 DOC API 检索，不包含内置调度或轮询；如需轮询应由外部调度重复调用。收费、价格与更详细的平台支持情况暂未提供。