统计接口的口径自检：把“提交数上升”拆成可复核的计数维度

“提交数上升”本身不是结论，而是一个需要拆解的说法。GitHub 2026 Octoverse 的文章标题称 commits 与 pushes 在 2026 年创下新高，开发者正用智能体参与构建（The GitHub Blog）。本次材料只提供标题与摘要，没有给出具体数字、统计窗口与计数规则，因此本文不引用任何涨幅；下面的方法用于让你自己的统计接口可复核。

第一步：先确定在数什么#

“提交数”“推送数”“参与人数”是三类不同对象，不能互相替代，也不宜相加成一个“活跃度”。

如果接口只返回一个总数，先补一个字段说明它属于哪一类，再谈趋势。

第二步：定义“算一次”的边界#

• 去重键：提交通常用“仓库 ID + commit SHA”，推送用“仓库 ID + 事件 ID”。缺少去重键，重放和补采就会重复计数。
• 分支范围：只数默认分支，还是全部引用？合并提交是否计入？两者差值可能很大。
• 身份归属：作者（author）与提交者（committer）可能不是同一账户；智能体或机器账户是否单独分组，需要显式声明。
• 历史重写：强推后被丢弃的 commit 是保留、扣减还是忽略，必须写进口径说明，否则同一窗口重算会得到不同结果。

第三步：时间维度要写死#

至少区分三个时间点：事件发生时间（commit 的 author date 或 committer date）、服务端接收时间、统计任务执行时间。三者可能相差数天。还需明确：

• 时区：统一用 UTC，还是按业务时区切日界；
• 窗口对齐：自然月、滚动 30 天，还是按周一到周日；
• 迟到数据：窗口关闭后多久允许重算，重算是否覆盖已发布数字；
• 比较基期：同比、环比各自的基期区间必须随指标一起返回。

第四步：让响应自带口径#

下面是演示用的占位结构，未在任何端点执行，数值为占位，仅说明字段应如何随指标一起返回：

{
  "metric": "commits",
  "schema_version": "commit-count/v2",
  "window": {
    "start": "2026-09-01T00:00:00Z",
    "end": "2026-10-01T00:00:00Z",
    "basis": "committer_date"
  },
  "filters": {
    "ref": "default_branch",
    "include_merge": false,
    "actor_types": ["human", "bot"]
  },
  "dedupe_key": "repo_id + commit_sha",
  "late_data_policy": "窗口关闭后 72 小时内可重算",
  "value": 0
}

关键是 schema_version：口径一改就升版本，旧版本的数字仍可解释。缺少版本号时，跨月对比等于把两种算法混在一起。

第五步：自检清单#

1. 换一个去重键重算，总数是否变化？变化说明键不唯一。
2. 把窗口整体平移一天，边界日的数据是否被重复或漏掉？
3. 把 bot 与 agent 账户单列后，“上升”是否仍成立？
4. 同一请求重放两次，结果是否一致？
5. 接口返回里能否找到基期与过滤条件，而不只是数字？

边界#

这套方法解决的是“可复核”，不解决“上升意味着什么”。提交数增加可能来自智能体批量生成、仓库拆分、流程改造或统计口径变更，归因需要额外证据。API.PLUS 是否提供上述字段的统计端点、字段命名与限额，本次材料未涉及，待核实；在核实前，请把本文示例当作设计参照，而不是对接文档。