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

# 组管理

> 通过服务密钥 API 创建和管理组、成员资格、模型可用性及组 ACU 上限。

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

以编程方式管理[组](/zh/federal/groups)：创建、读取、更新和删除组，管理其成员资格，并配置其[模型可用性](/zh/federal/model-provisioning)和 [ACU 上限](/zh/federal/acu-limits)。这些端点仅适用于多租户联邦部署。

所有端点均接受 JSON `POST` 请求。每个请求正文均包含 `service_key`；有关身份验证、作用域、分页和错误的信息，请参阅 [API 概览](/zh/federal/api/overview)。读取端点需要 **Teams Read-Only** 权限；写入端点需要 **Teams Update** 权限。这些处理程序受自托管多租户部署条件限制，但不执行 `/Analytics` 所使用的独立 analytics-access 层级检查。

读取和写入端点返回的组对象：

| 字段                           | 描述                                       |
| ---------------------------- | ---------------------------------------- |
| `group_id`                   | 组 ID。                                    |
| `name`                       | 组名称。                                     |
| `member_count`               | 当前成员数。                                   |
| `cascade_model_uids`         | 允许用于 Cascade 的模型 UID。空列表表示该组不限制 Cascade。 |
| `command_model_uids`         | 允许用于 Command 的模型 UID。空列表表示该组不限制 Command。 |
| `configured_cycle_acu_limit` | 为该组配置的每位成员 ACU 上限。未配置时省略；存在时始终为正数。       |
| `effective_cycle_acu_limit`  | 与团队限制合并后实际对该组执行的上限。未设置任何适用限制时省略。         |

***

<div id="list-groups">
  ## 列出组
</div>

```
POST /api/v1/ListGroups
```

列出服务密钥可查看的组。团队作用域的密钥会列出团队中的所有组；组作用域的密钥仅列出分配给它们的组。需要 **Teams Read-Only** 权限。支持 `page_size` / `page_token`。

```bash theme={null}
curl -X POST https://<your-server>/api/v1/ListGroups \
  -H "Content-Type: application/json" \
  -d '{"service_key": "your_service_key"}'
```

```json theme={null}
{
  "groups": [
    {"groupId": "group_a", "name": "Engineering", "memberCount": 24},
    {"groupId": "group_b", "name": "Data Science", "memberCount": 9}
  ],
  "nextPageToken": ""
}
```

<div id="get-group">
  ## 获取组
</div>

```
POST /api/v1/GetGroup
```

读取一个组，包括其模型允许列表、配置的和实际生效的 ACU 上限。需要 **Teams Read-Only** 权限。不存在、跨团队或超出作用域的组会返回 `not_found`。

```bash theme={null}
curl -X POST https://<your-server>/api/v1/GetGroup \
  -H "Content-Type: application/json" \
  -d '{"service_key": "your_service_key", "group_id": "group_a"}'
```

```json theme={null}
{
  "group": {
    "groupId": "group_a",
    "name": "Engineering",
    "memberCount": 24,
    "cascadeModelUids": ["model-uid-1", "model-uid-2"],
    "commandModelUids": [],
    "configuredCycleAcuLimit": 50,
    "effectiveCycleAcuLimit": 50
  }
}
```

<div id="create-group">
  ## 创建组
</div>

```
POST /api/v1/CreateGroup
```

在当前团队中创建名为 `name` 的组。需要 **Teams Update** 权限。具有组作用域的密钥无法创建组。

```bash theme={null}
curl -X POST https://<your-server>/api/v1/CreateGroup \
  -H "Content-Type: application/json" \
  -d '{"service_key": "your_service_key", "name": "Engineering"}'
```

响应中包含已创建的 `组` 对象。

<div id="update-group">
  ## 更新组
</div>

```
POST /api/v1/UpdateGroup
```

以原子方式更新组。仅会更改请求中提供的字段；未提供的字段保持不变。不包含任何更新字段的请求将返回 `invalid_argument`。需要 **Teams Update** 权限。

<ParamField body="group_id" type="string" required>
  要更新的组。
</ParamField>

<ParamField body="name" type="string">
  新的组名称。
</ParamField>

<ParamField body="cascade_models" type="object">
  `{"model_uids": [...]}` — 替换该组的 Cascade 模型允许列表。传入空列表将清除该组的 Cascade 限制。有关组允许列表如何组合，请参阅[模型预配](/zh/federal/model-provisioning)。
</ParamField>

<ParamField body="command_models" type="object">
  `{"model_uids": [...]}` — 替换该组的 Command 模型允许列表。传入空列表将清除该组的 Command 限制。
</ParamField>

<ParamField body="set_cycle_acu_limit" type="number">
  设置该组中每位成员每个账单周期的 ACU 上限。必须为正数。不能与 `clear_cycle_acu_limit` 同时使用。
</ParamField>

<ParamField body="clear_cycle_acu_limit" type="boolean">
  清除该组的 ACU 上限，恢复为团队或默认行为。在此服务密钥 API 中，`set_cycle_acu_limit` 必须为有限的正数；请使用此显式清除操作移除组级覆盖设置。门户中的组 ACU 限制控件接受 `cycle_acu_limit: 0` 作为清除请求。
</ParamField>

```bash theme={null}
curl -X POST https://<your-server>/api/v1/UpdateGroup \
  -H "Content-Type: application/json" \
  -d '{
    "service_key": "your_service_key",
    "group_id": "group_a",
    "cascade_models": {"model_uids": ["model-uid-1", "model-uid-2"]},
    "set_cycle_acu_limit": 50
  }'
```

响应中包含更新后的 `组` 对象。

<div id="delete-group">
  ## 删除组
</div>

```
POST /api/v1/DeleteGroup
```

通过 `group_id` 删除组。删除已不在密钥可用作用域内的组将成功完成，但不会执行任何操作。需要 **Teams Update**。

```bash theme={null}
curl -X POST https://<your-server>/api/v1/DeleteGroup \
  -H "Content-Type: application/json" \
  -d '{"service_key": "your_service_key", "group_id": "group_a"}'
```

<div id="list-group-members">
  ## 列出组成员
</div>

```
POST /api/v1/ListGroupMembers
```

列出指定组的当前成员。需要 **Teams Read-Only** 权限。支持 `page_size` / `page_token`。

```bash theme={null}
curl -X POST https://<your-server>/api/v1/ListGroupMembers \
  -H "Content-Type: application/json" \
  -d '{"service_key": "your_service_key", "group_id": "group_a"}'
```

```json theme={null}
{
  "members": [
    {"userId": "user_abc", "email": "dev@agency.gov"}
  ],
  "nextPageToken": ""
}
```

<div id="add-group-members">
  ## 添加组成员
</div>

```
POST /api/v1/AddGroupMembers
```

通过电子邮件将当前团队的用户添加到组 (`user_emails`，1–1,000 个条目) 。需要 **Teams Update**。

* 幂等：添加已存在的成员会成功，但不执行任何操作。
* 电子邮件地址会去除首尾空格，并按不区分大小写的方式去重。
* 全有或全无：如果任一电子邮件地址不存在或属于其他团队，整个请求都会被拒绝，且不会写入任何内容。

```bash theme={null}
curl -X POST https://<your-server>/api/v1/AddGroupMembers \
  -H "Content-Type: application/json" \
  -d '{
    "service_key": "your_service_key",
    "group_id": "group_a",
    "user_emails": ["dev@agency.gov", "lead@agency.gov"]
  }'
```

<div id="remove-group-members">
  ## 移除组成员
</div>

```
POST /api/v1/RemoveGroupMembers
```

通过电子邮件将用户移出组 (`user_emails`，1–1,000 个条目) 。需要 **Teams Update** 权限。与添加组成员一样，验证遵循全有或全无原则；移除有效但不属于该组的用户会成功执行，但不会产生任何实际操作。

```bash theme={null}
curl -X POST https://<your-server>/api/v1/RemoveGroupMembers \
  -H "Content-Type: application/json" \
  -d '{
    "service_key": "your_service_key",
    "group_id": "group_a",
    "user_emails": ["dev@agency.gov"]
  }'
```