> 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/response-contract-and-parsing.md).

# 响应契约与解析

了解旧版和规范模型输出、原始文本投影、动作解析、客户端执行反馈以及保留的响应模式。

Convai 角色可以生成对话文本、语义动作、客户端工具调用和情绪。你的客户端接收的契约取决于在以下位置选择的能力 `/connect`.

{% hint style="warning" %}
动作协议 v2、规范模型输出 v2，以及原始 `bot-llm-text` 是可选启用的候选表面。本文档不确认生产可用性或已发布的 SDK 版本。请验证 `capabilities` 由你的目标环境返回。
{% endhint %}

***

### 选择输出契约

| 选择                           | 提供的行为                                                                                                                                               |
| ---------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------- |
| 省略 `capabilities`            | 动作协议 v1、模型输出 v1，以及旧版过滤 `bot-llm-text`.  `/connect` 响应省略 `capabilities`.                                                                             |
| `action_protocol_version: 2` | 关联的客户端 `tool_call` 项目和 [`action-result`](/api-docs/zh/api-can-kao/core-api-reference/live-apis-beta/client-to-server-messages.md#action-result) 反馈。 |
| `model_output_version: 2`    | 类型化 [`model-output`](/api-docs/zh/api-can-kao/core-api-reference/live-apis-beta/server-to-client-messages.md#model-output) 封装会成为规范输出的权威来源。          |
| `bot_llm_text_mode: "raw"`   | 现有的 `bot-llm-text` 事件在结构化输出解析和对话过滤之前携带对提供方可见的文本。                                                                                                    |

这些选择彼此独立，但任何非旧版选择都需要一个单一的已创建会话。参见 [Agentic Actions v2 预览](/api-docs/zh/api-can-kao/core-api-reference/live-apis-beta/connect-api.md#agentic-actions-v2-preview) 了解拓扑结构和工具声明约束。

此候选表面未定义内置的显示、链接、卡片、表格、CSV 或快速响应模式。不要将原始文本视为显示协议。如果你的应用使用一个 `扩展` 项，只接受你的客户端明确识别的模式和版本，并始终提供安全回退。

***

### 动作如何分离

语义动作和客户端工具调用使用不同路径：

1. 你在其中声明语义动作能力和可选客户端工具 `action_config` 在 [`/connect`](/api-docs/zh/api-can-kao/core-api-reference/live-apis-beta/connect-api.md).
2. 当 **启用 Agentic Actions** 为角色开启时，Convai 会将适用的契约添加到提示中。当它被明确关闭时，模型看不到语义动作和客户端工具模式。如果该设置缺失，已保存的旧版 Character Actions 会在模型输出 v1 和 v2 中继承启用状态；没有已保存旧版动作的角色在模型输出 v2 中默认关闭。
3. 语义动作可以使用提供方原生调用或 Convai 解析的受支持结构化响应。客户端工具需要提供方原生函数调用。
4. Convai 通过规范 `model-output` 在选择时发出语义动作或关联的客户端工具调用。它也可以发出 `action-response` 作为兼容性投影。

解析后的模型必须支持客户端工具的提供方原生函数调用。仅有能力协商并不授权某项操作，也不保证模型能够调用已声明的工具。

#### 角色被赋予的动作规则

当语义动作能力处于活动状态时，Convai 会添加这些约束：

* 返回完整且有序的动作序列 **仅在** 用户要求执行物理任务时。
* 只能使用来自你的 `actions` 列表中的精确动作名称。模型被指示绝不发明或重命名动作。
* 只能针对来自你的 `objects` 和 `characters` 列表中的对象和角色。 `scene_description` 仅为描述性上下文—— **它不会扩展能力列表**.
* `“我”`, `“我的”`，以及 `“这里”` 解析为当前说话者。
* `“这”`, `“那”`, `“它”`，以及 `“那里”` 解析为 `current_attention_object` ，当其已设置时。
* 如果任务不可能、未受支持、非物理、不安全，或被口头拒绝，动作列表为空。
* 如果角色在其口头回复中拒绝该任务，动作列表也为空。
* 动作负载不应写入对话文本中。

{% hint style="warning" %}
提示指令可减少无效模型输出，但它们不是客户端授权。Convai 在投影前会验证语义动作名称和目标。对于客户端工具，它会验证声明的名称和 JSON Schema 参数，而你的应用仍需负责权限、确认、执行以及副作用安全。
{% endhint %}

***

### 规范模型输出

当 `model_output_version` 是 `2`，每个完成的封装都包含一个唯一的 `output_id`，一个可选的 `logical_turn_id`，原始的 `原始` 字符串，以及类型化 `渲染或执行已验证的`。请使用 `渲染或执行已验证的` 作为唯一可信的可渲染或可执行投影。切勿解析或执行 `原始`.

一个逻辑轮次可以产生多个封装，例如一个用于文本，另一个用于语义动作或客户端工具调用。按 `output_id`分组相关封装。 `logical_turn_id` 当其存在时。 `final: true` 完成一个封装，而不是整个逻辑轮次。

支持的项目类型有：

| 项目                | 作用                                                 |
| ----------------- | -------------------------------------------------- |
| `消息`              | 助手 `content` 在 `“final”` 或 `“commentary”` 通道。      |
| `semantic_action` | 已验证的语义动作，包含 `id`, `名称`，以及可选的 `target`.             |
| `tool_call`       | 关联的客户端工具请求，包含 `id`, `名称`，可选的 `target`，以及已验证的 `参数`. |
| `情绪`              | Emotion `名称` 以及强度 `量表`.                            |
| `扩展`              | 为客户端可识别扩展提供的带 schema 版本负载。此预览未定义显示或快速响应模式。         |

当前生产者会发出最终通道消息、语义动作、客户端工具调用和情绪。评论通道消息和 `扩展` 项目是候选客户端可以解析的有效类型化投影，但当前运行时不会生成它们。

Convai 会继续发出旧版投影以兼容。如果你的客户端选择模型输出 v2，请消费 `model-output.items` 并忽略重复的 `action-response` 消息。

### 客户端工具执行反馈

一个 `tool_call` 是供客户端考虑的请求。Convai 不会执行它。客户端根据本地策略验证该请求，执行或拒绝该操作，并发送一个终结的 [`action-result`](/api-docs/zh/api-can-kao/core-api-reference/live-apis-beta/client-to-server-messages.md#action-result) 并将 `"completed"`, `"error"`，或 `"cancelled"`.

Convai 用 `server-response`确认结果。对已接受的调用 ID 重试相同的终结负载是幂等的。冲突的重试会被拒绝。在接受结果后，Convai 会将其提供给相同的模型上下文，以便生成可以继续。不要将该确认用作顺序屏障；后续输出可能先到。

调用可以并行挂起。候选实现允许每个用户轮次最多 `8` 个未完成调用，以及每个用户回合最多 `8` 轮续延。它会等待 `60` 秒，默认在返回超时错误给模型之前。这些限制并不意味着你的应用会顺序执行或严格一次副作用。

### bot-llm-text 模式

`bot-llm-text` 在两种模式下都保持为流式文本投影：

| 模式             | 内容                                   | 安全使用            |
| -------------- | ------------------------------------ | --------------- |
| `“legacy”` 或省略 | 经过旧版解析和过滤路径后的对话文本。                   | 聊天记录和既定的口头回复路径。 |
| `“raw”`        | 在 Convai 的结构化输出解析和对话过滤之前，由提供方可见的文本块。 | 诊断或明确标注的开发者视图。  |

原始模式可以包含结构化 JSON、控制语法、拒绝文本、音频转写文本或其他提供方可见的文本字段。不能保证它包含非文本的原生工具调用增量。它不能取代 `model-output.items`，且不得驱动动作。即使原始文本被投影给客户端，解析后的对话和语音路径仍然具有权威性。

如果原始传递失败，Convai 会继续解析后的输出路径，并可发出一个非致命的 `raw_bot_llm_text_delivery_failed` 错误。失败的原始块不会重放。

***

### 旧版文本过滤

在旧版模式下，Convai 会在对话文本被投影或到达语音合成之前应用固定的过滤序列。原始 `bot-llm-text` 绕过了这个客户端投影过滤器，但不会改变解析后的语音路径。

| # | 移除          | 匹配                                           | 范围                   |
| - | ----------- | -------------------------------------------- | -------------------- |
| 1 | 弃权控制标记      | `[ABSTAIN]`, `[ABSTAINED]` （不区分大小写）          | 文本中的任何位置             |
| 2 | 内部工具调用语法    | 参见 [保留模式](#reserved-patterns) 如下             | **仅开头**              |
| 3 | Markdown 格式 | 标准 Markdown 强调、标题、列表标记、代码围栏                  | 任何位置                 |
| 4 | 视觉模态标签      | `[vision]`, `[camera]`, `camera:` 及类似形式——见下文 | **仅开头**，当视觉输入处于活动状态时 |
| 5 | 叙事设计索引前缀    | `<index>\|\|\|` 在响应的最开头                      | 仅开头，当叙事设计处于活动状态时     |
| 6 | 表情符号        | Unicode 表情符号和短代码                             | 任何位置，在语音合成阶段         |

过滤器 1–5 影响旧版 `bot-llm-text` 以及口语路径。过滤器 6 仅在语音阶段应用，因此表情符号可能保留在旧版文本中，而在语音中被省略。

#### 流式行为

过滤器作用于流式令牌流，而不是完整响应。一个跨越两个块的模式—— `[ABS` 后接 `TAIN]` ——仍会被正确移除：服务器会缓冲任何可能是保留模式开头的尾随片段，并在证明不匹配后释放它。一个值得注意的后果是： **响应最后几个字符可能会短暂保留** 然后才发出。

***

### 保留模式

当这些模式出现在 **开头** 时会被移除。不要指示角色以这些模式中的任何一个开始回复，也不要设计使用它们的响应格式。

**内部工具调用语法。** 一个标签后跟一个调用表达式：

```
tool_code: <name>(...)
tool_call: <name>(...)
function_call: <name>(...)
```

何处 `<name>` 是以下之一 `look`, `get_image`, `abstain`，或 `emit_actions`。匹配不区分大小写。裸调用语法—— `get_image(...)`, `abstain(...)`, `emit_actions(...)` ——也会被移除。解析器会匹配平衡的括号并尊重引号，因此调用中的嵌套括号和带引号字符串都能正确处理。单个响应中最多会去除四个连续这样的前缀。

**视觉模态标签。** 带方括号或冒号后缀的 `视觉`, `visual`, `camera`, `webcam`, `canvas`, `screen`:

```
[vision] ...        [vision]: ...        vision: ...
[camera] ...        [camera]: ...        camera: ...
```

**弃权标记。** `[ABSTAIN]` 和 `[ABSTAINED]`，文本中的任何位置。

**叙事设计前缀。** 一个前导整数后跟三个竖线—— `1|||`, `-1|||` ——当角色启用了叙事设计时。

这些前导模式过滤器会保留句中提及。只有旧版对话输出开头处的出现才会被视为工具调用或视觉控制语法。

***

### 编写自定义提示和响应格式

如果你自己编写核心描述、角色提示或输出格式，这些规则可以帮你避免麻烦：

* **不要以任何保留模式开头。** 以 `function_call: emit_actions(...)` 开头的回复，其前缀会被静默移除，客户端永远看不到。
* **不要指望 Markdown 在旧版路径中保留。** 强调、标题和代码围栏会从对话输出中移除。请使用规范的 `model-output.items` 或声明的客户端工具，而不是解析格式化文本。
* **不要把动作负载放在对话文本中。** 使用 `action_config` 并处理已验证的语义项。通过旧版路径保留下来的 JSON 可以被朗读。
* **将原始文本与语音分开。** 原始 `bot-llm-text` 是开发者投影，可能与通过口语路径发送的解析文本不同。
* **保持模板和场景文本不含保留前缀。** 通过 `narrative_template_keys`, `update-scene-metadata`，或 `context-update` 注入的值会成为提示的一部分，并可能影响响应的开头方式。

***

### 故障排查

**角色会朗读脚手架、JSON 或选项列表。** 解析后的对话输出包含可通过过滤保留的结构。将可执行数据移入已声明的工具或语义动作中，并保持对话回复自然。

**一个动作从未触发。** 确认 **启用 Agentic Actions** 已为角色开启，且目标模型支持所需的输出模式。对于语义动作，请确认其名称和目标已声明。对于客户端工具，请确认已选择动作协议 v2 且声明通过了 schema 验证。

**一个工具调用出现了，但模型从未继续。** 返回一个 `action-result` 其 `id` 与调用匹配。检查 `server-response` 确认中的 `status: "success"`。未知、过时、跨会话、冲突或超大的结果都会被拒绝。

**角色回复缺少最前面的几个词。** 这些词很可能匹配了一个保留的前导模式。检查 [保留模式](#reserved-patterns) 列表——尤其是视觉标签，它们通常是后面跟冒号的英语常用词。

**动作和语音不同步。** 语义项可以共享一个 `logical_turn_id`，但它们不携带词级偏移。参见 [排序保证](/api-docs/zh/api-can-kao/core-api-reference/live-apis-beta/turn-lifecycle-and-message-ordering.md#ordering-guarantees).

**一个前导 `|||` 序列从响应中消失。** 叙事设计处于活动状态，并且前导索引前缀正在被消耗。避免以一个整数后跟三个竖线开始响应。

***

### 相关页面

* [轮次生命周期与消息顺序](/api-docs/zh/api-can-kao/core-api-reference/live-apis-beta/turn-lifecycle-and-message-ordering.md) —— 输出如何传递以及你可以依赖的排序方式
* [model-output](/api-docs/zh/api-can-kao/core-api-reference/live-apis-beta/server-to-client-messages.md#model-output) —— 规范 v2 封装和项目字段
* [action-response](/api-docs/zh/api-can-kao/core-api-reference/live-apis-beta/server-to-client-messages.md#action-response) —— 旧版和兼容性投影
* [连接 API](/api-docs/zh/api-can-kao/core-api-reference/live-apis-beta/connect-api.md#agentic-actions-v2-preview) —— 能力、工具、限制和拓扑约束
* [action-result](/api-docs/zh/api-can-kao/core-api-reference/live-apis-beta/client-to-server-messages.md#action-result) —— 返回关联的客户端执行反馈


---

# 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 by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://docs.convai.com/api-docs/zh/api-can-kao/core-api-reference/live-apis-beta/response-contract-and-parsing.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

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.