Python SDK - Devin Docs

本文档适用于 Devin 联邦部署。返回 Devin 文档

Python SDK (windsurf_analytics.py) 是一个命令行客户端，用于调用联邦 API中的端点，包括：用量报告、ACU 消耗、组管理和用户 ACU 上限。你可以在部署门户的 Analytics 页面选择 Download SDK 下载该脚本，或联系你的 Cognition 代表。

环境要求

Python 3
requests 库：pip install requests

身份验证

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

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

服务密钥关联的角色必须具有各命令所需的权限——请参阅权限表。所有分析命令还要求团队层级具备分析 API 访问权限。

命令

命令	端点	所需权限
`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 报告。

输出和错误

所有命令都会将 JSON 输出到 stdout。对于分页结果 (ACU 消耗的用户行、list-groups、list-group-members) ，系统会自动获取至最后一页并合并为单个响应。API 错误会以 Error calling <endpoint> (HTTP <status>): code: message 格式输出到 stderr，脚本将以状态码 1 退出。无效的开关组合会在发送任何请求之前被拒绝，退出状态码为 2。

示例

用户级用量报告

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

ACU 消耗

# 当前账单周期的团队 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 用于调整每个请求的页面大小 (无论如何都会获取所有页面) 。至少必须指定一个数据选择开关。限定为特定组的密钥只能选择其分配的组，且不能请求团队总计或团队用户行。

组管理

# 列出组并查看单个组
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

用户 ACU 上限

# 读取用户已配置的上限及实际生效的上限（通过 --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

​环境要求

​身份验证

​命令

​输出和错误

​示例

​用户级用量报告

​ACU 消耗

​组管理

​用户 ACU 上限

环境要求

身份验证

命令

输出和错误

示例

用户级用量报告

ACU 消耗

组管理

用户 ACU 上限