本文是使用人工智能生成的关于技术解释和实现的示例。虽然发布的代码和步骤基于第一手资料，但未经作者在真实设备上进行运行验证。根据环境和版本的不同，实际运行情况可能会有所不同。 本文梳理了安全掌握 GitHub Copilot 使用情况指标中关于 VS Code Agents 变更所需的条件与机制，以便准确解读组织或企业的实际使用情况。在进行真机环境验证之前，旨在提前确认官方变更日志中提供的指标结构，以及 API 和汇总报告中的处理规范。
1. 目的
本文的目的是根据 GitHub Copilot 使用情况指标的官方发布，正确理解新集成的 VS Code Agents 使用统计数据项。帮助组织或企业的管理员及账单负责人梳理用于衡量普及度（adoption）和参与度（engagement）的指标结构，并明确使用时的注意事项以及访问权限的前提条件。
2. 前提条件与注意事项
【计划在 Windows 环境下验证】 或 【真机确认前】：文中未展示在实际环境的 PowerShell 或 CLI 中直接获取 API 及汇总项输出结果的内容。
功能范围限制：这里的指标针对的是独立的 VS Code Agents 窗口中的活动。它与编辑器窗口内的 Agent Mode 或通用的常规使用汇总分开进行管理。
权限管理：仅限企业所有者、账单经理、组织所有者或被授予“查看 Copilot 指标（View Copilot Metrics）”权限的自定义角色用户访问。此外，必须启用 Copilot 使用情况指标策略。
无数据时的行为：系统保持了向后兼容性，当不存在 VS Code Agents 窗口的数据时，可选字段将被省略或返回
null。
3. 新增指标的组成要素
根据第一手资料，企业和组织的汇总报告（1 天和 28 天周期）现已包含有关专用 VS Code Agents 窗口的新指标。在此，我们将逐一确认新增的主要要素。
flowchart TD
A[Copilot Usage Metrics] --> B[Aggregate Reports: 1-day / 28-day]
A --> C[User-Level Reports: Enterprise / Org]
B --> B1[daily_active_vscode_agent_users: 1日あたりのユニークユーザー数]
B --> B2[totals_by_vscode_agent: session_count と total_user_messages の集計]
C --> C1[used_vscode_agent: 利用有無を示すオプショナルな指標]
C --> C2[totals_by_vscode_agent: ユーザーごとのセッション数とメッセージ数]
daily_active_vscode_agent_users
这是一个可选的统计项，表示在汇总报告中每天在独立的 VS Code Agents 窗口处于活跃状态的独立用户数。它用于掌握整个组织每天的使用规模。
totals_by_vscode_agent (汇总报告)
这是关于 VS Code Agents 的 session_count（会话数）和 total_user_messages（用户消息总数）的可选合计值。通过该数值，不仅可以衡量人数，还可以通过消息交互和会话频率来衡量参与的深度。
used_vscode_agent
该项目包含在企业用户和组织用户级别的报告中（1 天和 28 天周期）。它作为一个可选指标，用于表示各个用户是否使用了 VS Code Agents 窗口。
totals_by_vscode_agent (用户级别)
这是用户级别报告中，针对单个用户的 session_count 和 total_user_messages 的数值。它有助于详细了解团队之间使用情况的差异，以及特定团队的利用程度。
4. API 与报告利用要点
在利用官方的 Copilot usage metrics API 时，需要注意以下要点。
报告周期的选择：由于同时提供了按天（1-day）和按 28 天（28-day）的周期，因此可以追踪短期趋势的变化以及中长期的普及程度。
理解数据分离：VS Code Agents 窗口的指标与编辑器窗口内的 Agent Mode 或传统的通用汇总明确区分开来。因此，需要注意不要与整体汇总值混淆。
策略与访问设置：在调用 API 之前，请确保已在 GitHub 上正确启用了 Copilot usage metrics 策略，并且已向执行用户分配了必要的权限（如 View Copilot Metrics 等）。
5. 限制
本文讨论的内容是基于 2026 年 9 月 11 日的官方更新日志进行的规格说明，未来的 API 更新或功能扩展可能会更改字段名称或行为。
由于未对真机环境中的 API 响应的具体 JSON 输出或使用 PowerShell 等脚本记录的实测值进行记录，因此在引入时请直接参考官方的 Copilot usage metrics API 文档。
6. 总结
执行前需要确认的要点:
组织或企业中是否启用了 Copilot usage metrics 策略。
访问用户是否被授予了“View Copilot Metrics”权限或适当的所有者权限。
获取的数据是否针对专用的 VS Code Agents 窗口，而不是常规的 Editor Agent Mode。
约束:
本文内容基于未经真机验证的调查，根据环境和 API 版本的不同，运行情况可能会有所差异。
可选字段的缺失或
null值的行为是基于向后兼容性在无数据时产生的，因此在应用程序端的解析处理中必须予以考虑。
