> For the complete documentation index, see [llms.txt](https://docs.convai.com/api-docs/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.convai.com/api-docs/zh/api-can-kao/core-api-reference/live-apis-beta/client-to-server-messages.md).

# 客户端到服务器消息

所有从客户端到服务器的消息都会在成功建立后的 WebRTC 数据通道上以 JSON 形式发送 `/connect` 呼叫。有关消息格式约定、服务器返回的状态码以及双向所有消息类型的完整索引，请参见 [消息术语表](/api-docs/zh/api-can-kao/core-api-reference/live-apis-beta/message-glossary.md).

### 消息封装

每条从客户端到服务器的消息都使用此封装：

```json
{
  "type": "<message-type>",
  "data": { ... }
}
```

| 字段   | 类型  | 必填 | 描述                           |
| ---- | --- | -- | ---------------------------- |
| `类型` | 字符串 | 是  | 消息类型标识符。                     |
| `数据` | 对象  | 否  | 消息载荷。结构因消息类型而异。对于没有载荷的消息可省略。 |

服务器会用一个……来确认每条客户端消息 `server-response` 消息。参见 [服务器响应](#server-response) 下文。

### 服务器响应

服务器会发送一条 `server-response` 对于接收到的每条从客户端到服务器的消息，无论类型如何，都会发送一条消息。

```json
{
  "type": "server-response",
  "event_type": "tts-toggle",
  "status": "success",
  "message": "TTS 已启用",
  "extras": {
    "enabled": true
  }
}
```

| 字段     | 类型     | 描述                                                         |
| ------ | ------ | ---------------------------------------------------------- |
| `事件类型` | 字符串    | 触发此响应的客户端消息类型。                                             |
| `状态`   | 字符串    | 处理状态： `"success"`, `"error"`, `"processing"`或 `"pending"`. |
| `消息`   | 字符串或空值 | 结果的人类可读描述。                                                 |
| `附加信息` | 对象或空值  | 额外的事件特定数据。结构因事件类型而异。                                       |

**状态值：**

| 值              | 含义                     |
| -------------- | ---------------------- |
| `"success"`    | 消息处理成功。                |
| `"error"`      | 发生错误。请检查 `消息` 以查看详细信息。 |
| `"processing"` | 消息正在异步处理中。             |
| `"pending"`    | 已收到消息，但处理被延迟。          |

***

### 交互与事件

#### trigger-message

触发叙事事件、向机器人发送上下文信息，或启动特定的机器人行为。

```json
{
  "type": "trigger-message",
  "data": {
    "trigger_name": "greeting",
    "trigger_message": "User entered the room"
  }
}
```

| 字段     | 类型  | 必填 | 描述            |
| ------ | --- | -- | ------------- |
| `触发名称` | 字符串 | 否  | 触发器的名称或标识符。   |
| `触发消息` | 字符串 | 否  | 触发器的上下文或消息内容。 |

**使用场景：**

* 通知机器人场景内事件，例如玩家进入某个区域或完成任务。
* 发送上下文触发器以推动叙事流程。
* 启动与指定触发器关联的特定机器人行为。

**服务器响应附加字段：**

| 字段              | 类型  | 描述                  |
| --------------- | --- | ------------------- |
| `触发名称`          | 字符串 | 从请求中回显的触发名称。        |
| `has_speak_tag` | 布尔值 | 触发消息中是否包含 speak 标签。 |

***

#### user\_text\_message

以用户输入的形式发送文本，模拟无音频的语音输入。

```json
{
  "type": "user_text_message",
  "data": {
    "text": "你好，你怎么样？"
  }
}
```

| 字段   | 类型  | 必填 | 描述            |
| ---- | --- | -- | ------------- |
| `文本` | 字符串 | 是  | 要作为用户输入发送的文本。 |

**服务器响应附加字段：**

| 字段   | 类型  | 描述         |
| ---- | --- | ---------- |
| `文本` | 字符串 | 从请求中回显的文本。 |

***

### 上下文与状态

#### update-template-keys

更新机器人系统提示中使用的模板变量。

```json
{
  "type": "update-template-keys",
  "data": {
    "template_keys": {
      "player_name": "Alice",
      "current_level": "5",
      "location": "森林"
    }
  }
}
```

| 字段    | 类型 | 必填 | 描述                    |
| ----- | -- | -- | --------------------- |
| `模板键` | 对象 | 是  | 模板变量名称及其更新后的字符串值的键值对。 |

**使用场景：**

* 更新动态提示变量，例如玩家姓名、属性或游戏状态。
* 根据当前会话状态自定义机器人的响应。

***

#### update-scene-metadata

更新机器人所了解的场景描述上下文，包括场景中的对象及其描述。

```json
{
  "type": "update-scene-metadata",
  "data": {
    "scene_metadata": [
      { "name": "torch", "description": "墙上的一支燃烧火炬" },
      { "name": "door", "description": "一扇上锁的木门" },
      { "name": "chest", "description": "一个旧宝箱" }
    ]
  }
}
```

| 字段                                  | 类型   | 必填 | 描述          |
| ----------------------------------- | ---- | -- | ----------- |
| `data.scene_metadata`               | 对象数组 | 是  | 要描述的场景对象数组。 |
| `data.scene_metadata[].name`        | 字符串  | 是  | 对象标识符。      |
| `data.scene_metadata[].description` | 字符串  | 是  | 对象的人类可读描述。  |

**使用场景：**

* 随环境变化更新场景中的可交互对象。
* 调整机器人所处的环境上下文，而不修改动作可供性。

{% hint style="warning" %}
`update-scene-metadata` 仅更新描述性上下文。不会修改权威的 `action_config.objects` 列表，该列表在 `/connect` 传入。要更改机器人可作用的对象，请使用新的连接重新连接 `action_config`.
{% endhint %}

***

#### update-dynamic-info

更新注入机器人系统提示的动态信息。此项用于基本的单字段上下文更新。对于带有 token 预算跟踪的模式控制更新，请使用 [`context-update`](#context-update) 替代。

```json
{
  "type": "update-dynamic-info",
  "data": {
    "dynamic_info": {
      "text": "用户刚刚完成了屠龙任务并获得了一把金剑。"
    }
  }
}
```

| 字段                  | 类型  | 必填 | 描述               |
| ------------------- | --- | -- | ---------------- |
| `dynamic_info.text` | 字符串 | 是  | 要注入系统提示的动态上下文文本。 |

***

#### context-update

更新机器人的运行时动态上下文，可完全控制模式、token 预算以及 LLM 触发。这是运行时上下文管理的首选消息。

```json
{
  "type": "context-update",
  "data": {
    "text": "新的上下文信息",
    "mode": "append",
    "run_llm": "auto",
    "current_attention_object": "torch",
    "action_config": {
      "objects": [
        { "name": "torch", "description": "墙上的一支燃烧火炬" }
      ]
    },
    "remove_static": false
  }
}
```

| 字段                         | 类型     | 必填                    | 默认         | 描述                                     |
| -------------------------- | ------ | --------------------- | ---------- | -------------------------------------- |
| `文本`                       | 字符串    | 是，除非 `模式` 为 `"reset"` | —          | 要应用的上下文文本。                             |
| `模式`                       | 字符串    | 否                     | `"append"` | 如何应用上下文。                               |
| `run_llm`                  | 字符串    | 否                     | `"auto"`   | 更新后是否触发 LLM 响应。                        |
| `current_attention_object` | 字符串或对象 | 否                     | —          | 更新当前注意对象，用于动作引用对齐。                     |
| `action_config`            | 对象     | 否                     | —          | 替换当前会话提供的动作可供性列表。参见下文。                 |
| `remove_static`            | 布尔值    | 否                     | `false`    | 对于 `"reset"` 仅在模式下：当 `true`，也会清除静态上下文。 |

**会话中途更新动作可供性**

`action_config` 接受与……相同的结构 [连接 API](/api-docs/zh/api-can-kao/core-api-reference/live-apis-beta/connect-api.md#request-body)。只会替换你提供的列表——仅发送 `objects` 保持 `actions` 和 `characters` 不变。当前场景发生变化且角色的可供性随之变化时，请使用此项。

{% hint style="warning" %}
将对象添加到 `scene_description` 或添加到 `文本` 会 **不** 使其可被指定为目标。只有 `action_config` 才会赋予可供性。参见 [响应契约与解析](/api-docs/zh/api-can-kao/core-api-reference/live-apis-beta/response-contract-and-parsing.md#how-actions-are-separated).
{% endhint %}

**模式值**

| 值           | 行为                                                         |
| ----------- | ---------------------------------------------------------- |
| `"append"`  | 将 `文本` 添加到现有运行时动态上下文中。                                     |
| `"replace"` | 将现有运行时动态上下文替换为 `文本`.                                       |
| `"reset"`   | 清除运行时动态上下文。若 `remove_static` 为 `true`. `文本` 不需要，还会清除静态上下文。 |

**run\_llm 值**

| 值         | 行为                     |
| --------- | ---------------------- |
| `"true"`  | 更新后始终触发机器人的响应。         |
| `"false"` | 从不触发机器人的响应。            |
| `"auto"`  | Convai 会根据上下文决定是否触发响应。 |

**token 预算**

动态上下文使用估算 token 预算：

| 分区                                    | 预算               |
| ------------------------------------- | ---------------- |
| `static_text` （连接时提供的会话级上下文）          | 20,000 个估算 token |
| 运行时 `文本` （来自 `append` 和 `replace` 更新） | 30,000 个估算 token |
| 合并后的动态上下文                             | 50,000 个估算 token |

当运行时 `文本` 超过其 30,000 token 预算时，Convai 会裁剪最旧的运行时上下文更新，并保留符合预算的最新更新。

`static_text` 是为此连接提供的会话和环境上下文。它会在 `reset` 调用，除非 `remove_static` 为 `true`.

**注意对象更新规则**

* `current_attention_object` 会根据已连接会话的 `action_config.objects`.
* 发送对象名称字符串或完整对象载荷均可。
* 发送空字符串（`""`）以清除当前注意对象。
* 更新 `current_attention_object` 会重新生成系统提示，即使在 `run_llm` 为 `"false"`.

**成功响应**

成功时，服务器会返回一条 `server-response` 其内容如下 `附加信息`:

```json
{
  "type": "server-response",
  "event_type": "context-update",
  "status": "success",
  "message": "上下文更新成功（追加模式）",
  "extras": {
    "token_count": 1523,
    "static_token_count": 200,
    "runtime_token_count": 1323,
    "max_tokens": 50000,
    "static_max_tokens": 20000,
    "runtime_max_tokens": 30000,
    "remaining_tokens": 48477,
    "content": "完整上下文文本在此处..."
  }
}
```

| 字段                    | 类型  | 描述                             |
| --------------------- | --- | ------------------------------ |
| `token_count`         | 整数  | 当前动态上下文中的估算 token 总数。          |
| `static_token_count`  | 整数  | 静态动态上下文的估算 token 数。            |
| `runtime_token_count` | 整数  | 运行时动态上下文的估算 token 数。           |
| `max_tokens`          | 整数  | 合并后的动态上下文预算（50,000 个估算 token）。 |
| `static_max_tokens`   | 整数  | 静态动态上下文预算（20,000 个估算 token）。   |
| `runtime_max_tokens`  | 整数  | 运行时动态上下文预算（30,000 个估算 token）。  |
| `remaining_tokens`    | 整数  | 达到合并上限前剩余的估算 token 数。          |
| `内容`                  | 字符串 | 保留的完整运行时动态上下文文本。               |

旧版 `word_count`, `static_word_count`, `runtime_word_count`, `max_words`和 `remaining_words` 字段可能会出现在较旧的客户端中。token 字段才是权威的。

**错误响应**

当 token 限制被超出时，服务器会返回一条 `server-response` 搭配 `"status": "error"`:

```json
{
  "type": "server-response",
  "event_type": "context-update",
  "status": "error",
  "message": "处理 context-update 失败：DynamicInfo 的 1 个验证错误\n值错误，Dynamic info static_text token 限制已超出。static_text：20001 个估算 token，最大值：20000 个 token。"
}
```

* 验证检查会分别独立应用于静态、运行时和合并后的估算 token 限制。
* 当合并后的动态上下文超过 40,000 个估算 token 时，Convai 会在服务器端记录警告。
* 错误消息会包含两个分区的估算 token 明细。

***

### 视觉

视觉消息会查询或消耗会话的视觉环形缓冲区。一旦 `vision_input_config` 被设置到 [`/connect`](/api-docs/zh/api-can-kao/core-api-reference/live-apis-beta/connect-api.md)。这些 RTVI 控制消息本身不会发布图像字节。

#### vision-status

在不附加帧或触发 LLM 的情况下查询当前视觉缓冲区状态。在启用视觉后、摄像头关闭后，或者在调用前需要确认帧可用时，请使用此项 `vision-trigger`.

```json
{
  "type": "vision-status",
  "data": {
    "update_id": "vision-status-1"
  }
}
```

| 字段          | 类型  | 必填 | 描述                                                 |
| ----------- | --- | -- | -------------------------------------------------- |
| `update_id` | 字符串 | 否  | 客户端关联 ID。会在确认中回显，并用于重复重放。若省略，则会使用顶层消息 `id` 在存在时使用。 |

**成功响应**

```json
{
  "type": "server-response",
  "event_type": "vision-status",
  "status": "success",
  "message": "视觉状态",
  "extras": {
    "vision_status_outcome": "frames_available",
    "active_source": "participant-id",
    "active_source_label": "摄像头",
    "last_frame_age_ms": 120,
    "update_id": "vision-status-1",
    "duplicate": false,
    "vision_buffer": {
      "enabled": true,
      "status": "frames_available",
      "retained_frames": 3,
      "buffer_frames": 8,
      "frames_per_turn": 5,
      "first_frame_pts": 1001,
      "last_frame_pts": 1003,
      "last_frame_age_ms": 120,
      "first_frame_index": -3,
      "source_active": true,
      "source_label": "摄像头",
      "selected_participant": "participant-id",
      "sampling_windows": [
        { "count": 3, "interval_ms": 300 },
        { "count": 2, "interval_ms": 1500 }
      ]
    }
  }
}
```

| 字段                      | 类型        | 描述                                |
| ----------------------- | --------- | --------------------------------- |
| `vision_status_outcome` | 字符串       | 缓冲区的高级结果。                         |
| `active_source`         | 字符串 \| 空值 | 当有源处于活动状态时，所选参与者 ID。              |
| `active_source_label`   | 字符串 \| 空值 | 已知时，源的人类可读标签。                     |
| `last_frame_age_ms`     | 整数 \| 空值  | 最新保留帧的时长，单位为毫秒。                   |
| `vision_buffer`         | 对象        | 对客户端安全的环形缓冲快照。绝不包含图像字节。           |
| `update_id`             | 字符串       | 在请求中提供时会回显。                       |
| `重复`                    | 布尔值       | `true` 当此确认是先前内容的重放时 `update_id`. |

**`vision_status_outcome` / `vision_buffer.status` 值**

| 值                    | 含义                 |
| -------------------- | ------------------ |
| `frames_available`   | 源处于活动状态，且缓冲区中保留了帧。 |
| `buffer_empty`       | 源处于活动状态，但尚未保留任何帧。  |
| `no_active_video`    | 未选择任何活动视觉源。        |
| `vision_not_enabled` | 此会话未启用视觉。          |

**使用场景：**

* 在用户启用摄像头或屏幕共享后，确认帧已到达。
* 在发出一个之前检查缓冲区深度 / 采样窗口 `vision-trigger`.
* 在不附加帧的情况下检测摄像头关闭/画面陈旧。

***

#### vision-trigger

将缓存的视觉帧附加到 LLM 上下文中，并可选地触发一次机器人轮次。仅凭此消息，在视觉功能被禁用或缓冲区为空且没有文本时，帧绝不会自动附加。

```json
{
  "type": "vision-trigger",
  "data": {
    "respond_mode": "auto",
    "text": "屏幕上有什么变化？",
    "frame_indices": [-1, -1],
    "update_id": "vision-trigger-1"
  }
}
```

| 字段              | 类型         | 必填 | 默认               | 描述                                                                                   |
| --------------- | ---------- | -- | ---------------- | ------------------------------------------------------------------------------------ |
| `respond_mode`  | 字符串        | 否  | 会话默认值用于 `vision` | `"silent"`, `"auto"`或 `"must_respond"`。无效的显式值会返回错误确认。                                |
| `文本`            | 字符串        | 否  | LLM 运行时的默认视觉提示   | 随帧附加的可选指令。存在时，即使缓冲区为空，纯文本触发也仍可继续。                                                    |
| `frame_indices` | integer\[] | 否  | 默认双时域选择          | 相对于保留缓冲区的索引。 `-1` 是最新的帧。重复索引会合并为一帧。                                                  |
| `frame_ids`     | integer\[] | 否  | —                | 帧的绝对呈现时间戳（`attached_frame_pts` / `vision-status` PTS 值）。优先于 `frame_indices` 当两者都设置时。 |
| `update_id`     | 字符串        | 否  | —                | 客户端关联 ID。会在确认中回显，并用于重复重放。若省略，则会使用顶层消息 `id` 在存在时使用。                                   |

**`respond_mode` 值**

| 值                | 行为                                                           |
| ---------------- | ------------------------------------------------------------ |
| `"silent"`       | 仅附加帧。不调用 LLM。                                                |
| `"auto"`         | 仅在机器人处于空闲且用户未在说话时附加帧并调用 LLM。否则请求会被静默降级而不附加。                  |
| `"must_respond"` | 附加帧并调用 LLM。如果机器人正忙，Convai 会先中断。如果用户正在说话，则附加/保留帧，并在用户轮次结束后响应。 |

连接时 `respond_modes.vision` 在……时为默认值提供初始值 `respond_mode` 被省略时。

**成功响应**

```json
{
  "type": "server-response",
  "event_type": "vision-trigger",
  "status": "success",
  "message": "已调用 LLM 的视觉触发",
  "extras": {
    "requested_respond_mode": "auto",
    "actual_respond_mode": "auto",
    "requested_run_llm": "auto",
    "actual_run_llm": "auto",
    "llm_triggered": true,
    "downgraded": false,
    "downgrade_reason": null,
    "interrupted": false,
    "vision_trigger_outcome": "attached",
    "vision_attach_outcome": "attached",
    "vision_frames_attached": 1,
    "vision_image_tokens_est": 258,
    "attached_frame_pts": [42],
    "frame_binding": "frame_indices",
    "requested_frame_indices": [-1, -1],
    "active_source": "participant-id",
    "active_source_label": "摄像头",
    "last_frame_age_ms": 80,
    "update_id": "vision-trigger-1",
    "duplicate": false,
    "vision_buffer": {
      "enabled": true,
      "status": "frames_available",
      "retained_frames": 1
    }
  }
}
```

| 字段                                                | 类型         | 描述                                            |
| ------------------------------------------------- | ---------- | --------------------------------------------- |
| `requested_respond_mode`                          | 字符串        | 解析后的请求模式，或 `"invalid"`.                       |
| `actual_respond_mode`                             | 字符串        | 在空闲/繁忙门控之后实际应用的模式。                            |
| `requested_run_llm` / `actual_run_llm`            | 字符串        | `"true"`, `"false"`或 `"auto"`.                |
| `llm_triggered`                                   | 布尔值        | 是否启动了一个 LLM 轮次。                               |
| `downgraded`                                      | 布尔值        | 请求是否被降级（机器人忙碌、缓冲区为空等）。                        |
| `downgrade_reason`                                | 字符串 \| 空值  | 在适用时，说明请求为何被降级。                               |
| `interrupted`                                     | 布尔值        | `true` 当 `must_respond` 中断了正在进行的机器人轮次。        |
| `vision_trigger_outcome`                          | 字符串        | 触发器的最终结果。                                     |
| `vision_attach_outcome`                           | 字符串        | 选择了帧时的附加结果。                                   |
| `vision_frames_attached`                          | 整数         | 已附加的帧数。                                       |
| `vision_image_tokens_est`                         | 整数         | 此次附加的图像 token 估计值。                            |
| `attached_frame_pts`                              | integer\[] | 已附加帧的 PTS 值。                                  |
| `frame_binding`                                   | 字符串        | 帧是如何被选择的（`默认`, `frame_indices`, `frame_ids`). |
| `requested_frame_indices` / `requested_frame_ids` | 数组 \| null | 请求选择字段的回显。                                    |
| `vision_buffer`                                   | 对象         | 处理触发器后的缓冲区快照。                                 |

**常见 `vision_trigger_outcome` 值**

| 值                                                                                         | 含义                               |
| ----------------------------------------------------------------------------------------- | -------------------------------- |
| `已附加`                                                                                     | 帧已附加。                            |
| `去重占位`                                                                                    | 帧与上一次附加匹配，因此被占位处理。               |
| `因陈旧而跳过`                                                                                  | 缓冲区被视为陈旧，并且没有提供文本。               |
| `frames_available`                                                                        | 缓冲区中有帧，但触发器未附加（例如 `自动` 在机器人忙碌时）。 |
| `buffer_empty`                                                                            | 来源处于活动状态，没有保留帧，也没有文本。            |
| `no_active_video`                                                                         | 没有活动的视觉来源，也没有文本。                 |
| `vision_not_enabled`                                                                      | 当前会话未启用视觉功能。                     |
| `无效回复模式`                                                                                  | 显式 `respond_mode` 不是允许值之一。       |
| `frame_id_evicted` / `无效 frame_ids` / `无效 frame_indices` / `无效 frame_indices 范围` / `速率受限` | 帧绑定失败。                           |

{% hint style="info" %}
`update_id` 使重试安全：重复的 `vision-status` 或 `vision-trigger` 使用相同 ID 的请求会重放先前的确认，其中 `"duplicate": true` 且不会再次附加或触发。
{% endhint %}

**使用场景：**

* 让角色评论当前的摄像头或屏幕画面。
* 静默预热视觉上下文（`respond_mode: "silent"`）以用于后续的用户轮次。
* 通过 `frame_indices` 或 `frame_ids`.

***

### 音频控制

#### tts-toggle

启用或禁用机器人的文本转语音音频输出。

```json
{
  "type": "tts-toggle",
  "data": {
    "enabled": true
  }
}
```

| 字段        | 类型  | 必填 | 描述                               |
| --------- | --- | -- | -------------------------------- |
| `enabled` | 布尔值 | 是  | `true` 以启用 TTS 输出。 `false` 以禁用它。 |

**服务器响应附加字段：**

| 字段        | 类型  | 描述           |
| --------- | --- | ------------ |
| `enabled` | 布尔值 | 从请求中回显的启用状态。 |

**使用场景：**

* 在过场动画或旁白序列期间静音机器人音频。
* 为无障碍需求切换音频输出。

***

#### stt-toggle

静音或取消静音语音转文本麦克风输入处理。

```json
{
  "type": "stt-toggle",
  "data": {
    "muted": true
  }
}
```

| 字段      | 类型  | 必填 | 描述                           |
| ------- | --- | -- | ---------------------------- |
| `muted` | 布尔值 | 是  | `true` 以停止监听。 `false` 以恢复监听。 |

**服务器响应附加字段：**

| 字段      | 类型  | 描述           |
| ------- | --- | ------------ |
| `muted` | 布尔值 | 从请求中回显的静音状态。 |

**使用场景：**

* 当按钮未按住时，通过静音 STT 来实现按键通话输入。
* 在不应处理用户语音的时刻禁用语音输入。

***

#### interrupt-bot

立即停止机器人当前的语音。

```json
{
  "type": "interrupt-bot"
}
```

否 `数据` 需要 payload。

**使用场景：**

* 允许用户在机器人说话中途进行中断。
* 当场景中的事件需要保持安静时，立即停止机器人音频。

***

#### force-user-stopped-speaking

向服务器表示用户已结束说话。在按键通话实现中使用此项来显式结束语音片段。

```json
{
  "type": "force-user-stopped-speaking"
}
```

否 `数据` 需要 payload。

**使用场景：**

* 在按键通话按钮释放时发出语音结束信号。
* 在未使用 VAD 时提供手动语音结束信号。

***

### 会话管理

#### reset-idle-timer

重置用户空闲超时倒计时。发送此项以表示用户活动并防止空闲断开连接。

```json
{
  "type": "reset-idle-timer",
  "data": {}
}
```

否 `数据` 需要 payload。服务器会忽略任何 `数据` 内容。

**使用场景：**

* 当用户执行点击或按键等 UI 操作时重置计时器。
* 检测语音交互之外的用户活动（例如鼠标移动），并防止空闲超时。
* 在长时间的非语音交互期间保持会话存活。

***

#### usage-toggle

启用或禁用向此客户端流式传输信息性 `usage-update` 消息。

```json
{
  "type": "usage-toggle",
  "data": {
    "enabled": true
  }
}
```

| 字段        | 类型  | 必填 | 描述                                          |
| --------- | --- | -- | ------------------------------------------- |
| `enabled` | 布尔值 | 是  | `true` 恢复 `usage-update` 流式传输， `false` 停止它。 |

{% hint style="info" %}
这只控制服务器是否 **推送** usage 消息到你的客户端。它绝不会影响服务器端的 usage 跟踪、汇总或计费，这些都会无条件继续。 `usage-update` 只有在会话以启用 usage 跟踪的调试模式运行时，messages 才可用。
{% endhint %}

**使用场景：**

* 当调试 usage 面板被隐藏时，停止实时成本流。
* 减少不显示实时 usage 的客户端的数据通道流量。

***

#### kill-pipeline

终止会话并关闭连接。

```json
{
  "type": "kill-pipeline"
}
```

否 `数据` 需要 payload。

**使用场景：**

* 在用户退出体验时干净地结束会话。
* 无需等待空闲超时即可释放资源。

***

### 下一步

{% content-ref url="/pages/52997086a1139479d2cbe158e37133880276b547" %}
[消息词汇表](/api-docs/zh/api-can-kao/core-api-reference/live-apis-beta/message-glossary.md)
{% endcontent-ref %}

{% content-ref url="/pages/70d752d330612b0fbf1290588e718236d6a18f0e" %}
[连接 API](/api-docs/zh/api-can-kao/core-api-reference/live-apis-beta/connect-api.md)
{% endcontent-ref %}

{% content-ref url="/pages/29ba5f52bd1ff6aac10fb390cafb074f474ab066" %}
[音频数据（通过数据通道）](/api-docs/zh/api-can-kao/core-api-reference/live-apis-beta/audio-data-via-data-channel.md)
{% endcontent-ref %}


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://docs.convai.com/api-docs/zh/api-can-kao/core-api-reference/live-apis-beta/client-to-server-messages.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.