> ## Documentation Index
> Fetch the complete documentation index at: https://docs.devinenterprise.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Python SDK

> 使用 Python SDK 通过命令行查询分析数据，并管理组和 ACU 限额。

<Info>
  本文档适用于 Devin 联邦部署。[返回 Devin 文档](/zh/get-started/devin-intro)
</Info>

Python SDK (`windsurf_analytics.py`) 是一个命令行客户端，用于调用[联邦 API](/zh/federal/api/overview)中的端点，包括：用量报告、[ACU 消耗](/zh/federal/api/acu-consumption)、[组管理](/zh/federal/api/group-management)和[用户 ACU 上限](/zh/federal/api/acu-caps)。请联系你的 Cognition 代表，获取适用于你的部署环境的脚本。

<div id="requirements">
  ## 环境要求
</div>

* Python 3
* `requests` 库：`pip install requests`

<div id="authentication">
  ## 身份验证
</div>

每个命令均支持以下通用开关：

| 开关              | 说明                                                        |
| --------------- | --------------------------------------------------------- |
| `--service-key` | 用于身份验证的服务密钥。也可通过 `WINDSURF_SERVICE_KEY` 环境变量设置。           |
| `--api-url`     | 你的部署的 API 服务器基础 URL (`https://<your-server>`)。必须使用 HTTPS。 |

服务密钥关联的角色必须具有各命令所需的权限——请参阅[权限表](/zh/federal/api/overview#required-permissions)。所有分析命令还要求团队层级具备分析 API 访问权限。

<div id="commands">
  ## 命令
</div>

| 命令                     | 端点                                         | 所需权限           |
| ---------------------- | ------------------------------------------ | -------------- |
| `usage` (默认)           | `/UserPageAnalytics` + `/CascadeAnalytics` | Teams 只读       |
| `acu-consumption`      | `/Analytics`                               | Analytics Read |
| `list-groups`          | `/ListGroups`                              | Teams 只读       |
| `get-group`            | `/GetGroup`                                | Teams 只读       |
| `create-group`         | `/CreateGroup`                             | Teams 更新       |
| `update-group`         | `/UpdateGroup`                             | Teams 更新       |
| `delete-group`         | `/DeleteGroup`                             | Teams 更新       |
| `list-group-members`   | `/ListGroupMembers`                        | Teams 只读       |
| `add-group-members`    | `/AddGroupMembers`                         | Teams 更新       |
| `remove-group-members` | `/RemoveGroupMembers`                      | Teams 更新       |
| `get-user-acu-cap`     | `/GetUserAcuCap`                           | Teams 只读       |
| `update-user-acu-cap`  | `/UpdateUserAcuCap`                        | Teams 更新       |

不指定命令直接运行脚本 (即原始调用方式) 会生成 `usage` 报告。

<div id="output-and-errors">
  ## 输出和错误
</div>

所有命令都会将 JSON 输出到 stdout。对于分页结果 (ACU 消耗的用户行、`list-groups`、`list-group-members`) ，系统会自动获取至最后一页并合并为单个响应。API 错误会以 `code: message` 格式输出到 stderr，脚本将以状态码 `1` 退出。

<div id="examples">
  ## 示例
</div>

<div id="per-user-usage-report">
  ### 用户级用量报告
</div>

```bash theme={null}
python windsurf_analytics.py \
    --service-key YOUR_SERVICE_KEY \
    --api-url https://your-server.com \
    --start 2025-01-01T00:00:00Z \
    --end 2025-03-31T23:59:59Z
```

<div id="acu-consumption">
  ### ACU 消耗
</div>

```bash theme={null}
# 当前账单周期的团队 ACU 总量，以及用户级明细行
python windsurf_analytics.py acu-consumption \
    --api-url https://your-server.com \
    --current-cycle --include-team-total --team-user-rows

# 按组划分的历史用量明细（时间窗口最长不超过 90 天），
# 并包含某个组的用户级明细行
python windsurf_analytics.py acu-consumption \
    --api-url https://your-server.com \
    --start 2025-01-01T00:00:00Z --end 2025-03-31T23:59:59Z \
    --group-id GROUP_A_ID --group-user-rows GROUP_A_ID
```

`acu-consumption` 开关：`--current-cycle` 或 `--start`/`--end` 用于选择时间段；`--include-team-total`、可重复指定的 `--group-id` (最多 100 个) 以及互斥的 `--team-user-rows` / `--group-user-rows GROUP_ID` 用于选择数据；`--page-size` 用于调整每个请求的页面大小 (无论如何都会获取所有页面) 。至少必须指定一个数据选择开关。限定为特定组的密钥只能选择其分配的组，且不能请求团队总计或团队用户行。

<div id="group-management">
  ### 组管理
</div>

```bash theme={null}
# 列出组并查看单个组
python windsurf_analytics.py list-groups --api-url https://your-server.com
python windsurf_analytics.py get-group --api-url https://your-server.com \
    --group-id GROUP_ID

# 创建组，并配置其模型和 ACU 上限
python windsurf_analytics.py create-group --api-url https://your-server.com \
    --name Engineering
python windsurf_analytics.py update-group --api-url https://your-server.com \
    --group-id GROUP_ID \
    --cascade-models MODEL_UID_1,MODEL_UID_2 \
    --set-cycle-acu-limit 50

# 清除组的模型限制或 ACU 上限。设置组上限时，服务 API 要求传入
# 正值；清除则是单独的操作。
python windsurf_analytics.py update-group --api-url https://your-server.com \
    --group-id GROUP_ID --clear-cascade-models --clear-cycle-acu-limit

# 管理成员（邮箱地址以逗号分隔，最多 1000 个）
python windsurf_analytics.py add-group-members --api-url https://your-server.com \
    --group-id GROUP_ID --emails dev@agency.gov,lead@agency.gov
python windsurf_analytics.py remove-group-members --api-url https://your-server.com \
    --group-id GROUP_ID --emails dev@agency.gov

# 删除组（幂等操作）
python windsurf_analytics.py delete-group --api-url https://your-server.com \
    --group-id GROUP_ID
```

<div id="user-acu-caps">
  ### 用户 ACU 上限
</div>

```bash theme={null}
# 读取用户已配置的上限及实际生效的上限（通过 --email 或 --user-id 指定用户）
python windsurf_analytics.py get-user-acu-cap --api-url https://your-server.com \
    --email dev@agency.gov

# 设置上限（设为 0 即封禁该用户）或清除覆盖设置
python windsurf_analytics.py update-user-acu-cap --api-url https://your-server.com \
    --email dev@agency.gov --set-cycle-acu-limit 25
python windsurf_analytics.py update-user-acu-cap --api-url https://your-server.com \
    --email dev@agency.gov --clear-cycle-acu-limit
```