API 报表结构与基础字段

区分用户、聚合、28 天封装和仓库记录，正确处理事件数与可选字段。

Copilot usage metrics 并非所有请求返回同一种 JSON。先识别报表粒度，再读取字段；逐用户报表没有聚合报表的全部字段，反之亦然。

报表族

报表	结构与范围
Per-user 1-day / 28-day	用户 ID、登录名、消耗、`used_*`、阶段和活动明细；没有活跃用户总数、`pull_requests` 或 `totals_by_ai_adoption_phase`
Enterprise / organization 1-day	每个实体的日聚合记录，包含活跃人数、PR 与阶段汇总；没有单个 `user_id` / `user_login` / `used_*`
Enterprise / organization 28-day	顶层报告窗口、生成时间、可选功能参与对象；`day_totals` 中放日聚合记录
User-teams 1-day	用户与当日团队关系，用来构建团队指标
Repos 1-day	每个当天有 PR 活动的仓库一条记录

一般报表用 day、enterprise_id 标识日期与企业，组织范围另带 organization_id。仓库报告还需按其特定 schema 处理没有企业归属时的字段，见PR 报表。

三种事件计数

字段	计数内容
`user_initiated_interaction_count`	主动发给模型的提示；打开面板、切换模式、打开 inline UI 或修改设置不计入
`code_generation_activity_count`	独立生成事件，包括注释和 docstring；同一提示的多个代码块可分别计数
`code_acceptance_activity_count`	内置 apply / insert / Copy 等接受动作；每次动作计一次，不包含操作系统手动 Ctrl+C

一个提示可产生多个代码块，agent 又可能不走逐条接受流程，因此三者不应被要求一一对应。需要计算行内接受率时，应在相应补全范围比较接受与生成，不能混入所有 agent 写入后再解释为“用户认可比例”。

ai_credits_used 仅逐用户报告提供，不按 feature / model / surface 拆分，用于消耗分析而非发票总额。

明细维度

totals_by_ide、totals_by_feature、totals_by_language_feature、totals_by_language_model、totals_by_model_feature 是不同数组。语言×功能数组没有 user_initiated_interaction_count；模型相关明细针对 Chat，不包括补全。

逐用户 IDE 条目可包含 last_known_ide_version 与 last_known_plugin_version，分别带版本与 sampled_at；聚合记录不提供这种用户版本对象。不要把最近采样版本当作全部历史事件都由该版本发出。

28 天封装示意

下面只展示官方字段组成的结构片段，不是完整接口返回：

{
  "report_start_day": "2025-09-04",
  "report_end_day": "2025-10-01",
  "day_totals": [
    {
      "day": "2025-10-01",
      "enterprise_id": "1",
      "daily_active_users": 2
    }
  ]
}

不要把 day_totals 的每天去重人数相加当作窗口独立用户数。逐用户 28 天报告则在用户记录上直接携带相关字段，不能照搬此聚合封装。

缺省、空数组与零

常规活动明细数组存在但可能为 []；可选功能字段还可能缺省或为 null。无匹配活动、未采集到详细遥测、功能数据尚不可用，不能都替换成同一个零值。

used_copilot_cloud_agent 与保留兼容性的 used_copilot_coding_agent 值相同，不应算两项活动。Review 主动/被动字段没有当天信号时可以为 null；专用客户端字段另见客户端指标。