---
title: "团队 API：成员、运行与触发器"
description: "Halo HTTP API 团队接口：创建和解散团队、管理成员与协作关系、启动和停止运行、设置触发器，查看看板与产出。"
type: "reference"
audience: ["developer"]
lang: "zh-CN"
canonical: "https://hello-halo.cc/docs/developers/api/team.html"
last_updated: "2026-10-19T00:11:17+08:00"
source: "Halo 3.0.4 docs"
---
# API：团队

Halo HTTP API 团队接口：创建和解散团队、管理成员与协作关系、启动和停止运行、设置触发器，查看看板与产出。

团队是为同一个目标协作的一组数字人。用这些接口创建和解散团队、管理成员与协作关系、启动和停止运行、设置触发器，并查看看板、会话和运行中产出的文件。

所有路径都相对于你的 Halo 地址，每个请求都要带上访问密码。示例中的 `$HALO_URL` 和 `$HALO_TOKEN` 按[快速上手](https://hello-halo.cc/docs/developers/quickstart.html)设置；地址、鉴权和错误约定见 [HTTP API 概览](https://hello-halo.cc/docs/developers/api/)。

| 操作 | 端点 |
| --- | --- |
| [列出团队，可只看某个工作区的团队](#get-api-teams) | `GET /api/teams` |
| [创建团队，并为它配好负责人](#post-api-teams) | `POST /api/teams` |
| [获取团队本身的记录](#get-api-teams-teamid) | `GET /api/teams/:teamId` |
| [修改团队的名称、目标、模式、升级路由或负责人](#patch-api-teams-teamid) | `PATCH /api/teams/:teamId` |
| [解散团队](#delete-api-teams-teamid) （不可撤销） | `DELETE /api/teams/:teamId` |
| [列出当前或最近一次运行中各成员产出的文件](#get-api-teams-teamid-artifacts) | `GET /api/teams/:teamId/artifacts` |
| [读取团队中某位成员的聊天记录](#get-api-teams-teamid-chat-messages) | `GET /api/teams/:teamId/chat-messages` |
| [停止成员在团队中设置的一项定期检查](#delete-api-teams-teamid-checks-checkid) （不可撤销） | `DELETE /api/teams/:teamId/checks/:checkId` |
| [列出团队进行中的会话，最新的在前](#get-api-teams-teamid-conversations) | `GET /api/teams/:teamId/conversations` |
| [新建团队会话](#post-api-teams-teamid-conversations) | `POST /api/teams/:teamId/conversations` |
| [重命名团队会话](#patch-api-teams-teamid-conversations-epochid) | `PATCH /api/teams/:teamId/conversations/:epochId` |
| [归档（关闭）团队会话](#delete-api-teams-teamid-conversations-epochid) （不可撤销） | `DELETE /api/teams/:teamId/conversations/:epochId` |
| [获取团队详情：成员、协作关系、在线情况、看板和决定](#get-api-teams-teamid-detail) | `GET /api/teams/:teamId/detail` |
| [整体替换结构化团队中的交接关系](#put-api-teams-teamid-edges) | `PUT /api/teams/:teamId/edges` |
| [列出团队的运行和会话历史，最新的在前](#get-api-teams-teamid-epochs) | `GET /api/teams/:teamId/epochs` |
| [列出一次运行中产出的文件](#get-api-teams-teamid-epochs-epochid-artifacts) | `GET /api/teams/:teamId/epochs/:epochId/artifacts` |
| [获取一次运行的任务、发现和成员](#get-api-teams-teamid-epochs-epochid-board) | `GET /api/teams/:teamId/epochs/:epochId/board` |
| [查看跨电脑团队中哪些电脑在线](#get-api-teams-teamid-federation-presence) | `GET /api/teams/:teamId/federation/presence` |
| [退出由别人电脑托管的团队](#post-api-teams-teamid-leave) （不可撤销） | `POST /api/teams/:teamId/leave` |
| [把已有的数字人加入团队](#post-api-teams-teamid-members) | `POST /api/teams/:teamId/members` |
| [改写成员在团队中的职责](#patch-api-teams-teamid-members-appid) | `PATCH /api/teams/:teamId/members/:appId` |
| [把成员移出团队](#delete-api-teams-teamid-members-appid) （不可撤销） | `DELETE /api/teams/:teamId/members/:appId` |
| [给一位团队成员发消息并等待回复](#post-api-teams-teamid-members-appid-send) | `POST /api/teams/:teamId/members/:appId/send` |
| [停止一位团队成员正在进行的工作](#post-api-teams-teamid-members-appid-stop) | `POST /api/teams/:teamId/members/:appId/stop` |
| [停止团队当前的运行](#post-api-teams-teamid-pause) | `POST /api/teams/:teamId/pause` |
| [让团队围绕目标开始一次运行](#post-api-teams-teamid-run) | `POST /api/teams/:teamId/run` |
| [把临时协作保留为团队](#post-api-teams-teamid-save-collab) | `POST /api/teams/:teamId/save-collab` |
| [列出团队的计划任务和其他触发器](#get-api-teams-teamid-triggers) | `GET /api/teams/:teamId/triggers` |
| [为团队添加或修改计划任务、文件或企业微信触发器](#post-api-teams-teamid-triggers) | `POST /api/teams/:teamId/triggers` |
| [移除团队的计划任务或其他触发器](#delete-api-teams-teamid-triggers-triggerid) （不可撤销） | `DELETE /api/teams/:teamId/triggers/:triggerId` |
| [获取从某个会话发起的临时协作](#get-api-teams-collab-for-conversation-conversationid) | `GET /api/teams/collab-for-conversation/:conversationId` |
| [按团队目标起草成员角色（不创建任何东西）](#post-api-teams-propose-members) | `POST /api/teams/propose-members` |

## 列出团队，可只看某个工作区的团队 {#get-api-teams}

`GET /api/teams` （助手可调用）

- Optional query parameter `spaceId` narrows the list to teams owned by one workspace; without it the list covers every workspace, as the Halo app shows it.
- `ephemeral: true` marks a temporary collaboration started from a conversation. It stays off the Teams page until it is kept with [`POST /api/teams/:teamId/save-collab`](#post-api-teams-teamid-save-collab).
- `hostNodeId` set means the team is hosted on someone else's computer and was joined from here: you can read it and message its members, but not edit or run it.

**查询参数**：`spaceId`

**响应**

```ts
{success:true,data:[{id,name,status:"idle"|"running"|"waiting_user"|"error",memberCount,hasWaitingUser,waitingCount?,leadAppId,localMembers:[{appId,memberName,isLead}],hostNodeId?,ephemeral?,updatedAt}]}
```

**示例**

```bash
curl -s "$HALO_URL/api/teams" \
  -H "Authorization: Bearer $HALO_TOKEN"
```

## 创建团队，并为它配好负责人 {#post-api-teams}

`POST /api/teams` （可撤销） （助手可调用）

- memberSourcing "manual": members are existing digital humans (appId from [`GET /api/apps`](https://hello-halo.cc/docs/developers/api/digital-human.html#get-api-apps)). memberSourcing "ai": omit members and send "confirmedProposal": [{memberName, role, responsibility}] (up to 5) beside "input" — [`POST /api/teams/propose-members`](#post-api-teams-propose-members) drafts one; Halo creates a new digital human for each.
- collabMode: "free" (members contact anyone) or "structured" (edges are generated from the lead; edit them with [`PUT /api/teams/:teamId/edges`](#put-api-teams-teamid-edges)). escalationRouting: "user" (questions go to the user) or "lead".
- Creates digital humans (the lead, and AI-sourced members) as a side effect; on any failure the whole team is rolled back.
- Create a persistent team only when the user asked for one. Members' delegated permissions are set in the Halo app — see this page's withheld list.

**请求体**

```json
{
  "input": {
    "name": "Weekly market brief",
    "goal": "Every Monday, summarise competitor moves into brief.md",
    "owningSpaceId": "<spaceId — a uuid from GET /api/spaces>",
    "memberSourcing": "manual",
    "collabMode": "free",
    "escalationRouting": "user",
    "members": [
      {
        "appId": "<appId — a digital human from GET /api/apps>",
        "memberName": "Researcher",
        "role": "Research",
        "duty": "Collects competitor news"
      }
    ]
  }
}
```

**响应**

```ts
{success:true,data:{id,name,owningSpaceId,goal,leadAppId,memberSourcing,collabMode,escalationRouting,status,currentEpochId,createdAt,updatedAt}}
```

**示例**

```bash
curl -sX POST "$HALO_URL/api/teams" \
  -H "Authorization: Bearer $HALO_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"input":{"name":"Weekly market brief","goal":"Every Monday, summarise competitor moves into brief.md","owningSpaceId":"<spaceId — a uuid from GET /api/spaces>","memberSourcing":"manual","collabMode":"free","escalationRouting":"user","members":[{"appId":"<appId — a digital human from GET /api/apps>","memberName":"Researcher","role":"Research","duty":"Collects competitor news"}]}}'
```

## 获取团队本身的记录 {#get-api-teams-teamid}

`GET /api/teams/:teamId` （助手可调用）

- For members, edges, live board and waiting decisions use [`GET /api/teams/:teamId/detail`](#get-api-teams-teamid-detail).

**路径参数**

| 名称 | 说明 |
| --- | --- |
| `teamId` | 团队 ID，来自 [`GET /api/teams`](#get-api-teams)。 |

**响应**

```ts
{success:true,data:{id,name,owningSpaceId,goal,leadAppId,memberSourcing,collabMode,escalationRouting,status,currentEpochId,hostNodeId,ephemeral?,createdAt,updatedAt} | null}
```

**示例**

```bash
curl -s "$HALO_URL/api/teams/<teamId>" \
  -H "Authorization: Bearer $HALO_TOKEN"
```

## 修改团队的名称、目标、模式、升级路由或负责人 {#patch-api-teams-teamid}

`PATCH /api/teams/:teamId` （可撤销） （助手可调用）

- Only the fields sent change. Also accepts "collabMode": "free"|"structured", "escalationRouting": "user"|"lead", "leadAppId".

**路径参数**

| 名称 | 说明 |
| --- | --- |
| `teamId` | 团队 ID，来自 [`GET /api/teams`](#get-api-teams)。 |

**请求体**

```json
{
  "name": "New name",
  "goal": "New goal"
}
```

**响应**

```ts
{success:true,data:{id,name,goal,collabMode,escalationRouting,leadAppId,...}}
```

**示例**

```bash
curl -sX PATCH "$HALO_URL/api/teams/<teamId>" \
  -H "Authorization: Bearer $HALO_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"name":"New name","goal":"New goal"}'
```

## 解散团队 {#delete-api-teams-teamid}

`DELETE /api/teams/:teamId` （不可撤销） （助手可调用）

::: danger 不可撤销
执行后无法撤销，数据也不会进入回收站。调用前请确认这是用户想要的结果。
只想做范围更小的操作时，改用 [`DELETE /api/teams/:teamId/members/:appId`](#delete-api-teams-teamid-members-appid)
:::

- Also deletes the Digital Humans Halo created for this team (its lead and the members Halo added) and their workspaces. Digital Humans the user added stay. The run history goes with the team.

**路径参数**

| 名称 | 说明 |
| --- | --- |
| `teamId` | 团队 ID，来自 [`GET /api/teams`](#get-api-teams)。 |

**响应**

```ts
{success:true}
```

**示例**

```bash
curl -sX DELETE "$HALO_URL/api/teams/<teamId>" \
  -H "Authorization: Bearer $HALO_TOKEN"
```

## 列出当前或最近一次运行中各成员产出的文件 {#get-api-teams-teamid-artifacts}

`GET /api/teams/:teamId/artifacts` （助手可调用）

- Covers the current or latest run. For an earlier run use [`GET /api/teams/:teamId/epochs/:epochId/artifacts`](#get-api-teams-teamid-epochs-epochid-artifacts). Read a file's content with [`GET /api/artifacts/content`](https://hello-halo.cc/docs/developers/api/workspace.html#get-api-artifacts-content) and its `path`.

**路径参数**

| 名称 | 说明 |
| --- | --- |
| `teamId` | 团队 ID，来自 [`GET /api/teams`](#get-api-teams)。 |

**响应**

```ts
{success:true,data:[{appId,memberName,spaceId,epochId,artifacts:[{name,type:"file"|"folder",path,relativePath,size?,createdAt}]}]}
```

**示例**

```bash
curl -s "$HALO_URL/api/teams/<teamId>/artifacts" \
  -H "Authorization: Bearer $HALO_TOKEN"
```

## 读取团队中某位成员的聊天记录 {#get-api-teams-teamid-chat-messages}

`GET /api/teams/:teamId/chat-messages` （助手可调用）

- Optional query: &amp;epochId= (a run or conversation id from [`GET /api/teams/:teamId/epochs`](#get-api-teams-teamid-epochs); default: the open run, else the member's own chat, else the latest), &amp;sinceSeq= for incremental reads.
- A member on another computer is fetched from its owner; stale:true means a cached copy because the owner is offline, and a 502 means it is unavailable right now.

**路径参数**

| 名称 | 说明 |
| --- | --- |
| `teamId` | 团队 ID，来自 [`GET /api/teams`](#get-api-teams)。 |

**查询参数**：`appId`（必填）、`epochId`、`sinceSeq`

**响应**

```ts
{success:true,data:[messages],stale?:true}
```

**示例**

```bash
curl -s "$HALO_URL/api/teams/<teamId>/chat-messages?appId=<appId — a member appId from GET /api/teams/:teamId/detail>" \
  -H "Authorization: Bearer $HALO_TOKEN"
```

## 停止成员在团队中设置的一项定期检查 {#delete-api-teams-teamid-checks-checkid}

`DELETE /api/teams/:teamId/checks/:checkId` （不可撤销） （助手可调用）

::: danger 不可撤销
执行后无法撤销，数据也不会进入回收站。调用前请确认这是用户想要的结果。
:::

- checkId comes from checks[] in [`GET /api/teams/:teamId/detail`](#get-api-teams-teamid-detail).

**路径参数**

| 名称 | 说明 |
| --- | --- |
| `teamId` | 团队 ID，来自 [`GET /api/teams`](#get-api-teams)。 |
| `checkId` | 团队成员设置的定期检查的 ID。 |

**响应**

```ts
{success:true}
```

**示例**

```bash
curl -sX DELETE "$HALO_URL/api/teams/<teamId>/checks/<checkId>" \
  -H "Authorization: Bearer $HALO_TOKEN"
```

## 列出团队进行中的会话，最新的在前 {#get-api-teams-teamid-conversations}

`GET /api/teams/:teamId/conversations` （助手可调用）

**路径参数**

| 名称 | 说明 |
| --- | --- |
| `teamId` | 团队 ID，来自 [`GET /api/teams`](#get-api-teams)。 |

**响应**

```ts
{success:true,data:[{epochId,teamId,kind:"native"|"im"|"member"|"run"|"collab",label,readonly,memberAppId?,channel?,startedAt,lastActivityAt,active?,waitingUser?}]}
```

**示例**

```bash
curl -s "$HALO_URL/api/teams/<teamId>/conversations" \
  -H "Authorization: Bearer $HALO_TOKEN"
```

## 新建团队会话 {#post-api-teams-teamid-conversations}

`POST /api/teams/:teamId/conversations` （可撤销） （助手可调用）

- Optional body: "memberAppId" to open it as a one-to-one thread with that member.

**路径参数**

| 名称 | 说明 |
| --- | --- |
| `teamId` | 团队 ID，来自 [`GET /api/teams`](#get-api-teams)。 |

**请求体**

```json
{
  "title": "optional title"
}
```

**响应**

```ts
{success:true,data:{epochId}}
```

**示例**

```bash
curl -sX POST "$HALO_URL/api/teams/<teamId>/conversations" \
  -H "Authorization: Bearer $HALO_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"title":"optional title"}'
```

## 重命名团队会话 {#patch-api-teams-teamid-conversations-epochid}

`PATCH /api/teams/:teamId/conversations/:epochId` （可撤销） （助手可调用）

- Send "title": null to go back to the derived label.

**路径参数**

| 名称 | 说明 |
| --- | --- |
| `teamId` | 团队 ID，来自 [`GET /api/teams`](#get-api-teams)。 |
| `epochId` | 团队的一次运行或一段会话的 ID，来自 [`GET /api/teams/:teamId/epochs`](#get-api-teams-teamid-epochs)。 |

**请求体**

```json
{
  "title": "New title"
}
```

**响应**

```ts
{success:true}
```

**示例**

```bash
curl -sX PATCH "$HALO_URL/api/teams/<teamId>/conversations/<epochId>" \
  -H "Authorization: Bearer $HALO_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"title":"New title"}'
```

## 归档（关闭）团队会话 {#delete-api-teams-teamid-conversations-epochid}

`DELETE /api/teams/:teamId/conversations/:epochId` （不可撤销） （助手可调用）

::: danger 不可撤销
执行后无法撤销，数据也不会进入回收站。调用前请确认这是用户想要的结果。
:::

- The conversation stays in run history ([`GET /api/teams/:teamId/epochs`](#get-api-teams-teamid-epochs)) but can no longer take messages.

**路径参数**

| 名称 | 说明 |
| --- | --- |
| `teamId` | 团队 ID，来自 [`GET /api/teams`](#get-api-teams)。 |
| `epochId` | 团队的一次运行或一段会话的 ID，来自 [`GET /api/teams/:teamId/epochs`](#get-api-teams-teamid-epochs)。 |

**响应**

```ts
{success:true}
```

**示例**

```bash
curl -sX DELETE "$HALO_URL/api/teams/<teamId>/conversations/<epochId>" \
  -H "Authorization: Bearer $HALO_TOKEN"
```

## 获取团队详情：成员、协作关系、在线情况、看板和决定 {#get-api-teams-teamid-detail}

`GET /api/teams/:teamId/detail` （助手可调用）

- The richest single read of a team; start here when the user asks how a team is doing. A pending escalation is answered by the user in Halo, not over this API.

**路径参数**

| 名称 | 说明 |
| --- | --- |
| `teamId` | 团队 ID，来自 [`GET /api/teams`](#get-api-teams)。 |

**响应**

```ts
{success:true,data:{team,members:[{appId,memberName,role,duty,isLead,origin,ownerDisplayName,...}],edges:[{fromAppId,toAppId,sync}],roster:[{appId,memberName,role,status:"working"|"idle"|"error"|"waiting_user",currentTaskTitle?}],tasks:[{id,title,assigneeAppId,status,resultRef,note}],findings:[...],activities?,pendingEscalations?:[{appId,memberName,entryId,question}],checks?:[{id,targetMemberName,instruction,schedule,runCount}],boardEpochId,crossesMachines?} | null}
```

**示例**

```bash
curl -s "$HALO_URL/api/teams/<teamId>/detail" \
  -H "Authorization: Bearer $HALO_TOKEN"
```

## 整体替换结构化团队中的交接关系 {#put-api-teams-teamid-edges}

`PUT /api/teams/:teamId/edges` （可撤销） （助手可调用）

- Replaces the whole list. Read the current edges from [`GET /api/teams/:teamId/detail`](#get-api-teams-teamid-detail), change them and send the full list back. Only meaningful when the team's `collabMode` is `structured`; member ids come from the same response.

**路径参数**

| 名称 | 说明 |
| --- | --- |
| `teamId` | 团队 ID，来自 [`GET /api/teams`](#get-api-teams)。 |

**请求体**

```json
{
  "edges": [
    {
      "fromAppId": "<appId>",
      "toAppId": "<appId>",
      "sync": false
    }
  ]
}
```

**响应**

```ts
{success:true}
```

**示例**

```bash
curl -sX PUT "$HALO_URL/api/teams/<teamId>/edges" \
  -H "Authorization: Bearer $HALO_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"edges":[{"fromAppId":"<appId>","toAppId":"<appId>","sync":false}]}'
```

## 列出团队的运行和会话历史，最新的在前 {#get-api-teams-teamid-epochs}

`GET /api/teams/:teamId/epochs` （助手可调用）

**路径参数**

| 名称 | 说明 |
| --- | --- |
| `teamId` | 团队 ID，来自 [`GET /api/teams`](#get-api-teams)。 |

**响应**

```ts
{success:true,data:[{id,startedAt,lastActivityAt,endedAt,endReason,summary,taskCount,doneCount,lifecycle:"run"|"conversation",label?,outcome?:"output"|"no_action"|"escalation"|"failed",triggerType?,artifactCount?}]}
```

**示例**

```bash
curl -s "$HALO_URL/api/teams/<teamId>/epochs" \
  -H "Authorization: Bearer $HALO_TOKEN"
```

## 列出一次运行中产出的文件 {#get-api-teams-teamid-epochs-epochid-artifacts}

`GET /api/teams/:teamId/epochs/:epochId/artifacts` （助手可调用）

**路径参数**

| 名称 | 说明 |
| --- | --- |
| `teamId` | 团队 ID，来自 [`GET /api/teams`](#get-api-teams)。 |
| `epochId` | 团队的一次运行或一段会话的 ID，来自 [`GET /api/teams/:teamId/epochs`](#get-api-teams-teamid-epochs)。 |

**响应**

```ts
{success:true,data:[{appId,memberName,spaceId,epochId,artifacts:[...]}]}
```

**示例**

```bash
curl -s "$HALO_URL/api/teams/<teamId>/epochs/<epochId>/artifacts" \
  -H "Authorization: Bearer $HALO_TOKEN"
```

## 获取一次运行的任务、发现和成员 {#get-api-teams-teamid-epochs-epochid-board}

`GET /api/teams/:teamId/epochs/:epochId/board` （助手可调用）

**路径参数**

| 名称 | 说明 |
| --- | --- |
| `teamId` | 团队 ID，来自 [`GET /api/teams`](#get-api-teams)。 |
| `epochId` | 团队的一次运行或一段会话的 ID，来自 [`GET /api/teams/:teamId/epochs`](#get-api-teams-teamid-epochs)。 |

**响应**

```ts
{success:true,data:{epoch,tasks:[...],findings:[...],members:[...],activities?} | null}
```

**示例**

```bash
curl -s "$HALO_URL/api/teams/<teamId>/epochs/<epochId>/board" \
  -H "Authorization: Bearer $HALO_TOKEN"
```

## 查看跨电脑团队中哪些电脑在线 {#get-api-teams-teamid-federation-presence}

`GET /api/teams/:teamId/federation/presence` （助手可调用）

- null means the team is not shared with other computers.

**路径参数**

| 名称 | 说明 |
| --- | --- |
| `teamId` | 团队 ID，来自 [`GET /api/teams`](#get-api-teams)。 |

**响应**

```ts
{success:true,data:{officeId,role:"host"|"joined",nodes:[{nodeId,displayName,status,lastSeen}],authority} | null}
```

**示例**

```bash
curl -s "$HALO_URL/api/teams/<teamId>/federation/presence" \
  -H "Authorization: Bearer $HALO_TOKEN"
```

## 退出由别人电脑托管的团队 {#post-api-teams-teamid-leave}

`POST /api/teams/:teamId/leave` （不可撤销） （助手可调用）

::: danger 不可撤销
执行后无法撤销，数据也不会进入回收站。调用前请确认这是用户想要的结果。
:::

- Only for a team joined from another computer (`hostNodeId` set in [`GET /api/teams`](#get-api-teams)). The members this computer brought leave with it; joining again needs a new invite from the host.

**路径参数**

| 名称 | 说明 |
| --- | --- |
| `teamId` | 团队 ID，来自 [`GET /api/teams`](#get-api-teams)。 |

**请求体**

```json
{}
```

**响应**

```ts
{success:true} | {success:false,error}
```

**示例**

```bash
curl -sX POST "$HALO_URL/api/teams/<teamId>/leave" \
  -H "Authorization: Bearer $HALO_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{}'
```

## 把已有的数字人加入团队 {#post-api-teams-teamid-members}

`POST /api/teams/:teamId/members` （可撤销） （助手可调用）

- To have Halo create a new digital human for a role, create one first (digital-human group) and add it here. Delegated permissions are set in the Halo app — see this page's withheld list.

**路径参数**

| 名称 | 说明 |
| --- | --- |
| `teamId` | 团队 ID，来自 [`GET /api/teams`](#get-api-teams)。 |

**请求体**

```json
{
  "appId": "<appId — a digital human from GET /api/apps>",
  "memberName": "Reviewer",
  "role": "Review",
  "duty": "Checks every draft before it is filed"
}
```

**响应**

```ts
{success:true,data:{teamId,appId,memberName,role,duty,isLead,addedAt,...}}
```

**示例**

```bash
curl -sX POST "$HALO_URL/api/teams/<teamId>/members" \
  -H "Authorization: Bearer $HALO_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"appId":"<appId — a digital human from GET /api/apps>","memberName":"Reviewer","role":"Review","duty":"Checks every draft before it is filed"}'
```

## 改写成员在团队中的职责 {#patch-api-teams-teamid-members-appid}

`PATCH /api/teams/:teamId/members/:appId` （可撤销） （助手可调用）

- Only members that run on this computer can be changed; a member someone else brought is refused. Delegated permissions are set in the Halo app — see this page's withheld list.

**路径参数**

| 名称 | 说明 |
| --- | --- |
| `teamId` | 团队 ID，来自 [`GET /api/teams`](#get-api-teams)。 |
| `appId` | 数字人 ID，来自 [`GET /api/apps`](https://hello-halo.cc/docs/developers/api/digital-human.html#get-api-apps)。 |

**请求体**

```json
{
  "duty": "Owns the pricing section"
}
```

**响应**

```ts
{success:true,data:{teamId,appId,memberName,role,duty,...}}
```

**示例**

```bash
curl -sX PATCH "$HALO_URL/api/teams/<teamId>/members/<appId>" \
  -H "Authorization: Bearer $HALO_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"duty":"Owns the pricing section"}'
```

## 把成员移出团队 {#delete-api-teams-teamid-members-appid}

`DELETE /api/teams/:teamId/members/:appId` （不可撤销） （助手可调用）

::: danger 不可撤销
执行后无法撤销，数据也不会进入回收站。调用前请确认这是用户想要的结果。
:::

- The digital human itself stays installed unless Halo created it only for this team.

**路径参数**

| 名称 | 说明 |
| --- | --- |
| `teamId` | 团队 ID，来自 [`GET /api/teams`](#get-api-teams)。 |
| `appId` | 数字人 ID，来自 [`GET /api/apps`](https://hello-halo.cc/docs/developers/api/digital-human.html#get-api-apps)。 |

**响应**

```ts
{success:true}
```

**示例**

```bash
curl -sX DELETE "$HALO_URL/api/teams/<teamId>/members/<appId>" \
  -H "Authorization: Bearer $HALO_TOKEN"
```

## 给一位团队成员发消息并等待回复 {#post-api-teams-teamid-members-appid-send}

`POST /api/teams/:teamId/members/:appId/send` （可撤销） （助手可调用）

- Blocks until the member finishes its turn (can take minutes) and returns its final message. delivery "queued"/"mid_turn" means the member was busy: the message was accepted but no reply exists yet — read it later with [`GET /api/teams/:teamId/chat-messages`](#get-api-teams-teamid-chat-messages).
- Optional body: "epochId" to address a specific run or conversation. Works for members on other computers too.

**路径参数**

| 名称 | 说明 |
| --- | --- |
| `teamId` | 团队 ID，来自 [`GET /api/teams`](#get-api-teams)。 |
| `appId` | 数字人 ID，来自 [`GET /api/apps`](https://hello-halo.cc/docs/developers/api/digital-human.html#get-api-apps)。 |

**请求体**

```json
{
  "message": "Please re-check the pricing section"
}
```

**响应**

```ts
{success:true,data:{ok,finalMessage,reason?,delivery?:"queued"|"mid_turn"}}
```

**示例**

```bash
curl -sX POST "$HALO_URL/api/teams/<teamId>/members/<appId>/send" \
  -H "Authorization: Bearer $HALO_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"message":"Please re-check the pricing section"}'
```

## 停止一位团队成员正在进行的工作 {#post-api-teams-teamid-members-appid-stop}

`POST /api/teams/:teamId/members/:appId/stop` （可撤销） （助手可调用）

- Optional body: "epochId". To stop the whole team run instead, [`POST /api/teams/:teamId/pause`](#post-api-teams-teamid-pause).

**路径参数**

| 名称 | 说明 |
| --- | --- |
| `teamId` | 团队 ID，来自 [`GET /api/teams`](#get-api-teams)。 |
| `appId` | 数字人 ID，来自 [`GET /api/apps`](https://hello-halo.cc/docs/developers/api/digital-human.html#get-api-apps)。 |

**请求体**

```json
{}
```

**响应**

```ts
{success:true,data:{ok,stopped,reason?}}  — stopped:false means nothing was running
```

**示例**

```bash
curl -sX POST "$HALO_URL/api/teams/<teamId>/members/<appId>/stop" \
  -H "Authorization: Bearer $HALO_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{}'
```

## 停止团队当前的运行 {#post-api-teams-teamid-pause}

`POST /api/teams/:teamId/pause` （可撤销） （助手可调用）

- Seals the run as stopped; members mid-turn are stopped with it. Start again with [`POST /api/teams/:teamId/run`](#post-api-teams-teamid-run).

**路径参数**

| 名称 | 说明 |
| --- | --- |
| `teamId` | 团队 ID，来自 [`GET /api/teams`](#get-api-teams)。 |

**请求体**

```json
{}
```

**响应**

```ts
{success:true}
```

**示例**

```bash
curl -sX POST "$HALO_URL/api/teams/<teamId>/pause" \
  -H "Authorization: Bearer $HALO_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{}'
```

## 让团队围绕目标开始一次运行 {#post-api-teams-teamid-run}

`POST /api/teams/:teamId/run` （可撤销） （助手可调用）

- Starts a run on the team's goal and returns once it has started; the run continues in the background. The lead works from the team goal, as this call carries no brief.
- Fails for a temporary collaboration (keep it first) and for a team hosted on another computer. Follow progress with [`GET /api/teams/:teamId/detail`](#get-api-teams-teamid-detail) or over the WebSocket.

**路径参数**

| 名称 | 说明 |
| --- | --- |
| `teamId` | 团队 ID，来自 [`GET /api/teams`](#get-api-teams)。 |

**请求体**

```json
{}
```

**响应**

```ts
{success:true}  — returns once the run has started; it continues in the background
```

**示例**

```bash
curl -sX POST "$HALO_URL/api/teams/<teamId>/run" \
  -H "Authorization: Bearer $HALO_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{}'
```

## 把临时协作保留为团队 {#post-api-teams-teamid-save-collab}

`POST /api/teams/:teamId/save-collab` （可撤销） （助手可调用）

- Keeps a temporary collaboration as a team, optionally under a new `name`. Keep one when the user asked for it.

**路径参数**

| 名称 | 说明 |
| --- | --- |
| `teamId` | 团队 ID，来自 [`GET /api/teams`](#get-api-teams)。 |

**请求体**

```json
{
  "name": "Market research team"
}
```

**响应**

```ts
{success:true,data:{id,name,owningSpaceId,goal,leadAppId,status,...}}
```

**示例**

```bash
curl -sX POST "$HALO_URL/api/teams/<teamId>/save-collab" \
  -H "Authorization: Bearer $HALO_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"name":"Market research team"}'
```

## 列出团队的计划任务和其他触发器 {#get-api-teams-teamid-triggers}

`GET /api/teams/:teamId/triggers` （助手可调用）

- `config` is returned as stored, including any secret it holds. Treat the response like a secret.

**路径参数**

| 名称 | 说明 |
| --- | --- |
| `teamId` | 团队 ID，来自 [`GET /api/teams`](#get-api-teams)。 |

**响应**

```ts
{success:true,data:[{id,teamId,sourceType:"schedule"|"webhook"|"file"|"wecom",config,enabled,createdAt}]}
```

**示例**

```bash
curl -s "$HALO_URL/api/teams/<teamId>/triggers" \
  -H "Authorization: Bearer $HALO_TOKEN"
```

## 为团队添加或修改计划任务、文件或企业微信触发器 {#post-api-teams-teamid-triggers}

`POST /api/teams/:teamId/triggers` （可撤销） （助手可调用）

- `config` by `sourceType`: `schedule` takes `{"every": "30m"}` or `{"cron": "0 9 * * 1"}`; `file` takes `{"pattern": "*.csv", "path": "&lt;part of the folder path&gt;"}`; `wecom` takes `{"chatId": "&lt;optional&gt;"}`.
- To change an existing trigger, send `triggerId` next to `trigger`; its `sourceType` must stay the same.

**路径参数**

| 名称 | 说明 |
| --- | --- |
| `teamId` | 团队 ID，来自 [`GET /api/teams`](#get-api-teams)。 |

**请求体**

```json
{
  "trigger": {
    "sourceType": "schedule",
    "config": {
      "cron": "0 9 * * 1"
    },
    "enabled": true
  }
}
```

**响应**

```ts
{success:true,data:{id,teamId,sourceType,config,enabled,createdAt}}
```

**示例**

```bash
curl -sX POST "$HALO_URL/api/teams/<teamId>/triggers" \
  -H "Authorization: Bearer $HALO_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"trigger":{"sourceType":"schedule","config":{"cron":"0 9 * * 1"},"enabled":true}}'
```

## 移除团队的计划任务或其他触发器 {#delete-api-teams-teamid-triggers-triggerid}

`DELETE /api/teams/:teamId/triggers/:triggerId` （不可撤销） （助手可调用）

::: danger 不可撤销
执行后无法撤销，数据也不会进入回收站。调用前请确认这是用户想要的结果。
只想做范围更小的操作时，改用 [`POST /api/teams/:teamId/triggers`](#post-api-teams-teamid-triggers)
:::

- To pause one without losing it, [`POST /api/teams/:teamId/triggers`](#post-api-teams-teamid-triggers) with its triggerId and "enabled": false (not a webhook trigger — see this page's withheld list).

**路径参数**

| 名称 | 说明 |
| --- | --- |
| `teamId` | 团队 ID，来自 [`GET /api/teams`](#get-api-teams)。 |
| `triggerId` | 触发器 ID，来自 [`GET /api/teams/:teamId/triggers`](#get-api-teams-teamid-triggers)。 |

**响应**

```ts
{success:true}
```

**示例**

```bash
curl -sX DELETE "$HALO_URL/api/teams/<teamId>/triggers/<triggerId>" \
  -H "Authorization: Bearer $HALO_TOKEN"
```

## 获取从某个会话发起的临时协作 {#get-api-teams-collab-for-conversation-conversationid}

`GET /api/teams/collab-for-conversation/:conversationId` （助手可调用）

- conversationId is a space conversation id ([`GET /api/spaces/:spaceId/conversations`](https://hello-halo.cc/docs/developers/api/conversation.html#get-api-spaces-spaceid-conversations)). null means that conversation never started a collaboration.

**路径参数**

| 名称 | 说明 |
| --- | --- |
| `conversationId` | 会话 ID，来自 [`GET /api/spaces/:spaceId/conversations`](https://hello-halo.cc/docs/developers/api/conversation.html#get-api-spaces-spaceid-conversations)。 |

**响应**

```ts
{success:true,data:{teamId,name,goal,epochId,active,saved,members:[...]} | null}
```

**示例**

```bash
curl -s "$HALO_URL/api/teams/collab-for-conversation/<conversationId>" \
  -H "Authorization: Bearer $HALO_TOKEN"
```

## 按团队目标起草成员角色（不创建任何东西） {#post-api-teams-propose-members}

`POST /api/teams/propose-members` （助手可调用）

- Runs a model call, so it takes a few seconds. Show the draft to the user, then pass it as confirmedProposal to [`POST /api/teams`](#post-api-teams) with memberSourcing "ai".

**请求体**

```json
{
  "goal": "Every Monday, summarise competitor moves into brief.md",
  "owningSpaceId": "<spaceId — a uuid from GET /api/spaces>"
}
```

**响应**

```ts
{success:true,data:[{memberName,role,responsibility}]}  — at most 5
```

**示例**

```bash
curl -sX POST "$HALO_URL/api/teams/propose-members" \
  -H "Authorization: Bearer $HALO_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"goal":"Every Monday, summarise competitor moves into brief.md","owningSpaceId":"<spaceId — a uuid from GET /api/spaces>"}'
```