# 结构体 (/zh-CN/api-reference/conversational-ai/web/struct)

> For AI agents: see the complete documentation index at [llms.txt](/llms.txt).

<a id="iconversationalaiapieventhandlers"></a>
## IConversationalAIAPIEventHandlers [#iconversationalaiapieventhandlers]

```typescript
export interface IConversationalAIAPIEventHandlers
```

用于对话式 AI 引擎 API 模块的事件处理器接口。

:::info[信息]
自 1.6.0 版本新增。
:::

<a id="tmessagereceipt"></a>
## TMessageReceipt [#tmessagereceipt]

```typescript
export type TMessageReceipt = {
  moduleType: EModuleType
  messageType: EChatMessageType
  message: string
  turnId: number
}
```

消息回执类型定义。

:::info[信息]
自 1.7.0 版本新增。
:::

#### 成员参数 [#成员参数]

| 参数 | 数据类型 | 描述 |
| --- | --- | --- |
| `moduleType` | `EModuleType` | 发送该消息的模块类型。详见 [`EModuleType`](/zh-CN/api-reference/conversational-ai/web/enum#emoduletype)。 |
| `messageType` | `EChatMessageType` | 消息的类型。详见 [`EChatMessageType`](/zh-CN/api-reference/conversational-ai/web/enum#echatmessagetype)。 |
| `message` | `string` | 消息的内容。 |
| `turnId` | `number` | 会话轮次的唯一标识符。 |

<a id="tusermanualeventpayload"></a>
## TUserManualEventPayload [#tusermanualeventpayload]

```typescript
export type TUserManualEventPayload = {
  success: boolean
  requestId: string
  turnId?: number
  errorMessage?: string
}
```

手动 SoS/EoS 通用载荷。

#### 成员参数 [#成员参数-1]

| 参数 | 数据类型 | 描述 |
| --- | --- | --- |
| `success` | `boolean` | 服务端是否成功处理本次手动信令。 |
| `requestId` | `string` | 请求 ID，与调用 `manualSOS` 或 `manualEOS` 后返回的 `requestId` 对应。 |
| `turnId` | `number` | 关联的对话轮次 ID。服务端失败回调未携带 `turn_id` 时可为空。 |
| `errorMessage` | `string` | 服务端返回的原始错误信息。成功时通常为空。 |

<a id="tusermanualsosevent"></a>
## TUserManualSosEvent [#tusermanualsosevent]

```typescript
export type TUserManualSosEvent = {
  eventId: string
  timestamp: number
  payload: TUserManualEventPayload
}
```

手动 SoS 事件对象。

#### 成员参数 [#成员参数-2]

| 参数 | 数据类型 | 描述 |
| --- | --- | --- |
| `eventId` | `string` | 事件唯一 ID。 |
| `timestamp` | `number` | 事件时间戳，单位为毫秒。 |
| `payload` | `TUserManualEventPayload` | 事件载荷。详见 [`TUserManualEventPayload`](/zh-CN/api-reference/conversational-ai/web/struct#tusermanualeventpayload)。 |

<a id="tusermanualeosevent"></a>
## TUserManualEosEvent [#tusermanualeosevent]

```typescript
export type TUserManualEosEvent = {
  eventId: string
  timestamp: number
  payload: TUserManualEventPayload
}
```

手动 EoS 事件对象。

#### 成员参数 [#成员参数-3]

| 参数 | 数据类型 | 描述 |
| --- | --- | --- |
| `eventId` | `string` | 事件唯一 ID。 |
| `timestamp` | `number` | 事件时间戳，单位为毫秒。 |
| `payload` | `TUserManualEventPayload` | 事件载荷。详见 [`TUserManualEventPayload`](/zh-CN/api-reference/conversational-ai/web/struct#tusermanualeventpayload)。 |

<a id="tagentmanualeospayload"></a>
## TAgentManualEosPayload [#tagentmanualeospayload]

```typescript
export type TAgentManualEosPayload = {
  reason: string
  maxDurationMs: number
  turnId: number
}
```

服务端超限自动 EoS 载荷。

#### 成员参数 [#成员参数-4]

| 参数 | 数据类型 | 描述 |
| --- | --- | --- |
| `reason` | `string` | 服务端自动结束当前用户发言的原因。 |
| `maxDurationMs` | `number` | 当前配置的单轮最大音频时长，单位为毫秒。 |
| `turnId` | `number` | 关联的对话轮次 ID。 |

<a id="tagentmanualeosevent"></a>
## TAgentManualEosEvent [#tagentmanualeosevent]

```typescript
export type TAgentManualEosEvent = {
  eventId: string
  timestamp: number
  payload: TAgentManualEosPayload
}
```

服务端超限自动 EoS 事件对象。

#### 成员参数 [#成员参数-5]

| 参数 | 数据类型 | 描述 |
| --- | --- | --- |
| `eventId` | `string` | 事件唯一 ID。 |
| `timestamp` | `number` | 事件时间戳，单位为毫秒。 |
| `payload` | `TAgentManualEosPayload` | 事件载荷。详见 [`TAgentManualEosPayload`](/zh-CN/api-reference/conversational-ai/web/struct#tagentmanualeospayload)。 |

<a id="ichatmessagebase"></a>
## IChatMessageBase [#ichatmessagebase]

```typescript
export interface IChatMessageBase {
  messageType: EChatMessageType
}
```

包含基础消息类型属性的 [`IChatMessageBase`](/zh-CN/api-reference/conversational-ai/web/struct#ichatmessagebase) 接口。

:::info[信息]
自 v1.7.0 版本新增。
:::

#### 成员参数 [#成员参数-6]

| 参数 | 数据类型 | 描述 |
| --- | --- | --- |
| `messageType` | `EChatMessageType` | 消息类型，详见 [`EChatMessageType`](/zh-CN/api-reference/conversational-ai/web/enum#echatmessagetype)。 |

<a id="ichatmessageimage"></a>
## IChatMessageImage [#ichatmessageimage]

```typescript
export interface IChatMessageImage extends IChatMessageBase {
  messageType: EChatMessageType.IMAGE
  uuid: string
  url?: string
}
```

表示一个基于图片的聊天消息，包含 `url` 形式的图片数据。

#### 成员参数 [#成员参数-7]

| 参数 | 数据类型 | 描述 |
| --- | --- | --- |
| `messageType` | `EChatMessageType.IMAGE` | 消息类型，必须为 `IMAGE`。详见 [`EChatMessageType`](/zh-CN/api-reference/conversational-ai/web/enum#echatmessagetype)。 |
| `uuid` | `string` | 图片消息的唯一标识符。 |
| `url` | `string` | 可选。指向图片资源的 URL。 |

<a id="speakmessage"></a>
## SpeakMessage [#speakmessage]

```typescript
export interface SpeakMessage {
  text: string
  priority?: EChatMessagePriority
  interruptable?: boolean
}
```

用于绕过大模型，直接通过智能体的 TTS 流程播报文本。

#### 成员参数 [#成员参数-8]

| 参数 | 数据类型 | 描述 |
| --- | --- | --- |
| `text` | `string` | 要播报的文本。 |
| `priority` | `EChatMessagePriority` | 播报请求的处理优先级，默认值为 `INTERRUPTED`。详见 [`EChatMessagePriority`](/zh-CN/api-reference/conversational-ai/web/enum#echatmessagepriority)。 |
| `interruptable` | `boolean` | 是否允许用户说话打断本次播报，默认值为 `true`。 |

<a id="thinkmessage"></a>
## ThinkMessage [#thinkmessage]

```typescript
export interface ThinkMessage {
  text: string
  onListeningAction?: ThinkListeningAction
  onThinkingAction?: ThinkThinkingAction
  onSpeakingAction?: ThinkSpeakingAction
  interruptable?: boolean
  metadata?: Record<string, string>
}
```

用于将文本作为用户输入注入对话，并交由大模型处理。

#### 成员参数 [#成员参数-9]

| 参数 | 数据类型 | 描述 |
| --- | --- | --- |
| `text` | `string` | 要注入大模型的指令文本。 |
| `onListeningAction` | `ThinkListeningAction` | 智能体处于倾听状态时的处理动作，默认值为 `INTERRUPT`。详见 [`ThinkListeningAction`](/zh-CN/api-reference/conversational-ai/web/enum#thinklisteningaction)。 |
| `onThinkingAction` | `ThinkThinkingAction` | 智能体处于思考状态时的处理动作，默认值为 `IGNORE`。详见 [`ThinkThinkingAction`](/zh-CN/api-reference/conversational-ai/web/enum#thinkthinkingaction)。 |
| `onSpeakingAction` | `ThinkSpeakingAction` | 智能体处于说话状态时的处理动作，默认值为 `IGNORE`。详见 [`ThinkSpeakingAction`](/zh-CN/api-reference/conversational-ai/web/enum#thinkspeakingaction)。 |
| `interruptable` | `boolean` | 是否允许用户说话打断本次指令生成的响应，默认值为 `true`。 |
| `metadata` | `Record<string, string>` | 可选的业务自定义键值对。 |

<a id="isubtitlehelperitem"></a>
## ISubtitleHelperItem [#isubtitlehelperitem]

```typescript
export interface ISubtitleHelperItem<T> {
  uid: string
  stream_id: number
  turn_id: number
  _time: number
  text: string
  status: ETurnStatus
  metadata: T | null
}
```

字幕辅助项接口。

:::info[信息]
自 1.6.0 版本新增。
:::

定义字幕系统中单个字幕项的数据结构。包含用户 ID、流 ID、轮次 ID、时间戳、文本内容、状态和元数据等信息。

#### 成员参数 [#成员参数-10]

| 参数 | 数据类型 | 描述 |
| --- | --- | --- |
| `uid` | `string` | 用户的唯一标识符。 |
| `stream_id` | `number` | 流标识符。 |
| `turn_id` | `number` | 会话中的轮次标识符。 |
| `_time` | `number` | 字幕的时间戳（单位为毫秒）。 |
| `text` | `string` | 字幕文本内容。 |
| `status` | `ETurnStatus` | 字幕项的当前状态。详见 `ETurnStatus`。 |
| `metadata` | `T \| null` | 附加的元数据信息。详见 `T`。 |

<a id="tagentmetric"></a>
## TAgentMetric [#tagentmetric]

```typescript
export type TAgentMetric = {
  type: EModuleType
  name: string
  value: number
  timestamp: number
}
```

[`TAgentMetric`](/zh-CN/api-reference/conversational-ai/web/struct#tagentmetric) 用于定义智能体指标统计数据类型。

:::info[信息]
自 1.6.0 版本新增。
:::

用于在智能体运行时存储指标数据，包括指标模块类型、名称、数值和时间戳。

#### 成员参数 [#成员参数-11]

| 参数 | 数据类型 | 描述 |
| --- | --- | --- |
| `type` | `EModuleType` | 指标模块类型，详见 [`EModuleType`](/zh-CN/api-reference/conversational-ai/web/enum#emoduletype)。 |
| `name` | `string` | 指标名称。 |
| `value` | `number` | 指标数值。 |
| `timestamp` | `number` | 数据采集时间戳（毫秒）。 |

<a id="tmoduleerror"></a>
## TModuleError [#tmoduleerror]

```typescript
export type TModuleError = {
  type: EModuleType
  code: number
  message: string
  timestamp: number
}
```

[`TModuleError`](/zh-CN/api-reference/conversational-ai/web/struct#tmoduleerror) 模块错误类型定义。

:::info[信息]
自 1.6.0 版本新增。
:::

用于表示来自不同 AI 模块的错误信息，包括错误类型、错误码、错误信息和时间戳，便于错误处理和调试。错误码为模块特定内容，应由各模块单独说明。时间戳为 Unix 毫秒格式。错误信息应具备良好可读性，并提供可操作的信息。

#### 成员参数 [#成员参数-12]

| 参数 | 数据类型 | 描述 |
| --- | --- | --- |
| `type` | `EModuleType` | 发生错误的模块类型，详见 [`EModuleType`](/zh-CN/api-reference/conversational-ai/web/enum#emoduletype)。 |
| `code` | `number` | 模块特定的错误码。 |
| `message` | `string` | 具备可读性的错误描述信息。 |
| `timestamp` | `number` | 错误发生时的 Unix 毫秒时间戳。 |

<a id="tstatechangeevent"></a>
## TStateChangeEvent [#tstatechangeevent]

```typescript
export type TStateChangeEvent = {
  state: EAgentState
  turnID: number
  timestamp: number
  reason: string
}
```

[`TStateChangeEvent`](/zh-CN/api-reference/conversational-ai/web/struct#tstatechangeevent) 为状态变更事件的数据类型定义。

:::info[信息]
自 1.6.0 版本新增。
:::

#### 成员参数 [#成员参数-13]

| 参数 | 数据类型 | 描述 |
| --- | --- | --- |
| `state` | `EAgentState` | 语音代理的当前状态。详见 [`EAgentState`](/zh-CN/api-reference/conversational-ai/web/enum#eagentstate)。 |
| `turnID` | `number` | 当前会话轮次的唯一标识符。 |
| `timestamp` | `number` | 状态变更发生时的时间戳（单位为毫秒）。 |
| `reason` | `string` | 状态变更的原因描述。 |