coverage-check

coverage-check

十个 URL 不等于十个来源。这个工具会把“很多媒体都报道了”变成一个有据可查的数字。

何时使用

核查声明时，如果某项声明看起来是因报道数量多而得到佐证——搜索结果一大堆，内容却都一样。这种情况背后有两种截然不同的原因：

• 多家新闻编辑室独立查证了事实 → 证据确实有力
• 一份新闻稿、一篇通讯社稿件或一项研究被转载了 40 次 → 一个来源

这两种情况在搜索结果中看起来一模一样。这个工具可以将它们区分开来。

用法

uv run scripts/coverage.py "<query>" [--timespan 3m] [--max 250] [--sort dateasc] [--timeout 120] [--json]

速度很慢，这是正常的。 GDELT 执行一个简单的一天查询约需 15 秒；查询 3 个月的时间窗口并获取 250 条记录则要久得多。脚本会将进度和调用耗时输出到 stderr，方便你判断它是在“运行”还是“卡住”——如果看到正在查询的提示，就耐心等待。缩短 --timespan 可以提速；在认定它出故障之前，先调高 --timeout。

查询支持 GDELT 运算符："exact phrase"、(a OR b)、-exclude、domain:example.com、sourcelang:english。将声明中有辨识度的措辞放在引号里——逐字匹配的短语才能抓出转载内容。

# Is this "40 outlets confirmed it" or one wire story?
uv run scripts/coverage.py '"quantum breakthrough" AND university'

# Narrow to the week the claim surfaced
uv run scripts/coverage.py '"record quarterly revenue" domain:reuters.com' --timespan 7d

如何阅读输出

第一行是检测器需要的判定结果，其余内容为判定提供依据。

• Distinct story clusters — 按标题相似度分组的文章。这是对来源数量的估算。媒体数 ≫ 集群数，说明存在联合供稿。
• 集群上的 ⚠️ syndicated — 多家媒体在 24 小时内发布了同一篇稿件。应将整个集群视为一个来源。
• 集群上的 wire-attributed headline — 标题中提到了通讯社或新闻稿分发机构（Reuters、AP、PR Newswire……）。这是标题层面能获得的最强机械性单一来源信号；检查正文能发现更多，但 GDELT 不会返回正文。
• Duplicate URLs collapsed — 同一页面因跟踪参数、www. 或末尾斜杠而被重复计数。重复项会在其他内容计数之前合并，因此下面的每个数字都已去重。
• Span (hours) — 时间跨度很短，说明可能源自新闻稿或解禁报道；报道历经数周逐渐展开，则更可能彼此独立。

将结果作为来源数量填入报告的证据列：“6 条结果，1 个来源（均为转载该公司的新闻稿）”，比六个链接更有价值。

限制 — 在相信数字前请先阅读

• 仅覆盖滚动 3 个月的时间窗口。 GDELT DOC 2.0 无法追溯到更早时间。对于更早的说法，本工具不会返回任何结果，而没有结果不代表没有报道。脚本会在输出中说明这一点；不要让 Agent 悄悄把空结果当成反证。

• 聚类依据是标题相似度，采用两项指标：用于识别改写标题的序列比率，以及用于识别事实相同但顺序不同的词元重合度。分组采用传递关系 — 同一条通讯社报道即使有三家媒体转载，即便两端的标题单独比较都低于阈值，也会归为一组。逐字转载、改写后的通讯社稿件和调整顺序的标题都会被正确归并。

  仍无法识别的情况：两家新闻编辑部独立得出相同结论，并用确实不同的措辞描述。这些会显示为不同的集群；宁可在这个方向上出错，也就是少报联合转载，而不是凭空捏造。

  阈值是根据真实的 GDELT 输出调校的，并非凭空猜测。如果发现误合并，请调高脚本中的 TITLE_MATCH/TOKEN_MATCH；如果通讯社稿件被拆成不同集群，请调低它们。

• 有报道不代表可信。 一个说法被 30 个不同集群中的 200 家媒体报道，只能称为广泛报道，并不代表属实。判定仍需遵循检测器 RUBRIC.md 中的来源层级。

• 每次查询最多返回 250 条结果。 达到上限时，输出会说明这一点 — 所有计数都只是下限；诚实的做法是缩短 --timespan，而不是报一个更大的数字。

• 免费端点不可靠，这是最重要的一点。 无论公共 API 是否繁忙，即使请求频率远低于每 5 秒一次，GDELT 也会返回 "Please limit requests to one every 5 seconds"；这与 IP、User-Agent 和查询大小无关。实测表现：相同请求可能相隔几分钟一次成功、一次失败。脚本会以逐渐延长的间隔重试，然后以状态码 3 退出。

  状态码 3 表示“未测量”，而非“没有报道”。 绝不要让检查失败削弱或强化判定，也绝不要把失败记录成搜索返回空结果。如果工具无法测量，报告会说明来源数量未知，并改用 RUBRIC.md 中可目测判断的线索。几分钟后重试，或跳过此步骤。

  状态码	含义
  0	测量成功（包括确实没有结果的时间窗口）
  1	输入无效或主机无法访问
  3	GDELT 限流 — 未进行测量，该说法未测量

• 无需 API 密钥、无需身份验证，且免费。 无需配置，也无需轮换密钥。

它不会做什么

它会统计并归组报道覆盖情况，但不会获取文章正文 — 获取正文请使用 fetch-content — 也不会进行任何判断。分析工具会读取它的输出；它们绝不会调用此工具来独立作出判定。