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

***

### 选择一个输出契约

| 选择                           | 传递的行为                                                                                                                                          |
| ---------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------- |
| 省略 `capabilities`            | Action 协议 v1、模型输出 v1，以及旧版过滤 `bot-llm-text`。该 `/connect` 响应省略 `capabilities`.                                                                   |
| `action_protocol_version: 2` | 关联的客户端 `工具调用` 项目和 [`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 操作** 对角色开启时，Convai 会把适用的契约添加到提示中。当它被明确关闭时，语义动作和客户端工具模式不会暴露给模型。如果该设置缺失，已保存的旧版 Character Actions 会继承一个启用状态，适用于模型输出 v1 和 v2；没有已保存旧版动作的角色在模型输出 v2 中默认为关闭。
3. 语义动作可以使用提供方原生调用或 Convai 解析的受支持结构化响应。客户端工具需要提供方原生函数调用。
4. Convai 通过规范的……发出语义动作或关联的客户端工具调用 `model-output` 在被选中时。它也可以发出 `action-response` 作为兼容性投影。

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

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

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

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

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

***

### 规范化模型输出

当 `model_output_version` 是 `2`，每个完成的封装都包含一个唯一的 `output_id`，一个可选的 `logical_turn_id`，原始的 `raw` 字符串，以及类型化的 `items` 中列表中的索引。使用 `items` 作为唯一可信的可渲染或可执行投影。绝不要解析或执行 `raw`.

一个逻辑轮次可以产生多个封装，例如一个用于文本，另一个用于语义动作或客户端工具调用。按 `output_id`进行分组。 `logical_turn_id` 当它存在时。 `最终：true` 完成的是一个封装，而非整个逻辑轮次。

支持的项目类型有：

| 条目                | 用途                                                    |
| ----------------- | ----------------------------------------------------- |
| `message`         | 助手 `content` 在 `"final"` 或 `"commentary"` 通道。         |
| `semantic_action` | 已验证的语义动作，带有 `ID`, `名称`，以及可选的 `目标`.                    |
| `工具调用`            | 关联的客户端工具请求，带有 `ID`, `名称`，可选的 `目标`，以及已验证的 `arguments`. |
| `情绪`              | 情绪 `名称` 和强度 `强度`.                                     |
| `扩展`              | 用于客户端可识别扩展的按模式版本定义的载荷。此预览未定义显示或快速响应模式。                |

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

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

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

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

Convai 使用 `服务器响应`确认结果。对已接受调用 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 仅在语音阶段生效，因此表情符号可能保留在旧版文本中，但会从语音中省略。

#### 流式行为

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

***

### 保留模式

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

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

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

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

**视觉模态标签。** 带括号或以冒号结尾的形式： `vision`, `视觉`, `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 操作** 对角色是开启的，并且目标模型支持所需的输出模式。对于语义动作，确认其名称和目标已声明。对于客户端工具，确认已选择 action protocol v2 且声明通过了模式验证。

**一个工具调用出现了，但模型从未继续。** 返回一个 `action-result` 其 `ID` 与该调用匹配。检查 `服务器响应` 确认中的 `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 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/response-contract-and-parsing.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.