### Initialize and Use AAAS Pilot Kit

Source: https://aaas-pilot-kit-docs.cloud.baidu.com/docs/vanilla/intro

Quick start guide for initializing the AAAS Pilot Kit with your authentication token and configuration. It demonstrates listening for the 'ready' event to play audio and handling new conversation messages.

```javascript
import {createAaaSPilotKit} from '@bdky/aaas-pilot-kit';  
  
// 使用您的配置初始化  
const controller = createAaaSPilotKit({  
    token: 'your-auth-token-here',  
    figureId: '209337',  
    ttsPer: 'LITE_audiobook_female_1',  
    // agentConfig: 若未提供自定义 agentService,此配置必填  
    agentConfig: {  
        // 客悦客服Agent token  
        token: 'xxxx',  
        // 客悦外呼Agent robotId  
        robotId: 'xxxx'  
    }  
});  
  
// 监听事件  
controller.emitter.on('ready', () => {  
    // 使用非流式 API 播报开场白  
    controller.playFromFullText('您好，今天我可以为您做什么？');  
});  
  
controller.emitter.on('conversation_add', (conversation) => {  
    console.log('新对话内容:', conversation.text);  
});  
  
// 挂载  
await controller.mount(containerElement);
```

--------------------------------

### Install AAAS Pilot Kit Vue 3 with npm or yarn

Source: https://aaas-pilot-kit-docs.cloud.baidu.com/docs/vue/installation

Installs the AAAS Pilot Kit for Vue 3 using either npm or yarn package managers. This is the initial step before integrating the kit into your project.

```bash
$ npm install @bdky/aaas-pilot-kit-vue3  

```

```bash
$ yarn add @bdky/aaas-pilot-kit-vue3  

```

--------------------------------

### AAAS Pilot Kit Vue 3 Configuration Options Example

Source: https://aaas-pilot-kit-docs.cloud.baidu.com/docs/vue/installation

Provides an example of the `IOptions` interface for configuring the AAAS Pilot Kit. It highlights key properties such as token, figureId, ttsPer, and agentConfig, which are crucial for initializing the kit's functionalities.

```typescript
const options: IOptions = {
    token: 'your-auth-token-here',
    figureId: '209337',
    ttsPer: 'LITE_audiobook_female_1',
    // agentConfig: 若未提供自定义 agentService,此配置必填
    agentConfig: {
        token: 'your-token',
        robotId: 'your-robot-id'
    },
    // 其他配置项...
};

```

--------------------------------

### Install AAAS Pilot Kit with npm

Source: https://aaas-pilot-kit-docs.cloud.baidu.com/docs/vanilla/intro

Installs the AAAS Pilot Kit using npm. This is the primary method for adding the SDK to your project.

```bash
$ npm install @bdky/aaas-pilot-kit  
```

--------------------------------

### Install AAAS Pilot Kit with yarn

Source: https://aaas-pilot-kit-docs.cloud.baidu.com/docs/vanilla/intro

Installs the AAAS Pilot Kit using yarn. This is an alternative method for adding the SDK to your project.

```bash
$ yarn add @bdky/aaas-pilot-kit  
```

--------------------------------

### Install AaaS Pilot Kit for Vanilla JavaScript

Source: https://aaas-pilot-kit-docs.cloud.baidu.com/docs/intro

Instructions for installing the AaaS Pilot Kit's core SDK using npm or yarn. This SDK is framework-agnostic and serves as the foundation for other framework-specific packages.

```bash
npm install @bdky/aaas-pilot-kit
```

```bash
yarn add @bdky/aaas-pilot-kit
```

--------------------------------

### Vue 3 Parent Component Setup with AAAS Pilot Kit Provider

Source: https://aaas-pilot-kit-docs.cloud.baidu.com/docs/vue/installation

Sets up the parent component (App.vue) to provide the AAAS Pilot Kit instance using `provideAaaSPilotKit`. It includes configuration options and mounts the digital human rendering container. This component is essential for initializing the kit.

```vue
<template>
    <div class="app">
        <!-- 数字人渲染容器 -->
        <div ref="digitalHumanRef" class="digital-human-container"></div>
        <PilotComponent />
    </div>
</template>

<script setup lang="ts">
import {ref, onMounted} from 'vue';
import {provideAaaSPilotKit} from '@bdky/aaas-pilot-kit-vue3';
import {type IOptions} from '@bdky/aaas-pilot-kit';
import PilotComponent from './PilotComponent.vue';

const options: IOptions = {
    token: 'your-auth-token-here',
    figureId: '209337',
    ttsPer: 'LITE_audiobook_female_1',
    // agentConfig: 若未提供自定义 agentService,此配置必填
    agentConfig: {
        token: 'xxxx',
        robotId: 'xxxx'
    }
};

// 提供 AaaSPilotKit 实例给所有子组件
const provider = provideAaaSPilotKit(options);

// 数字人渲染容器的 ref
const digitalHumanRef = ref<HTMLDivElement>();

// 挂载数字人到 DOM
onMounted(() => {
    if (digitalHumanRef.value) {
        provider.controller.value?.mount(digitalHumanRef.value);
    }
});
</script>

<style scoped>
.digital-human-container {
    width: 100%;
    height: 400px;
    position: relative;
}
</style>

```

--------------------------------

### Basic React App Setup with AaaS Pilot Kit Provider

Source: https://aaas-pilot-kit-docs.cloud.baidu.com/docs/react/intro

Demonstrates the basic setup of a React application using the AaaSPilotKitProvider. It wraps the application with the provider, passing necessary options for authentication and configuration. This ensures global state management and dependency injection for the SDK.

```javascript
import {
    AaaSPilotKitProvider,
    useAaaSPilotKit,
    useAaaSPilotKitEvents,
    useConversationList
} from '@bdky/aaas-pilot-kit-react';
import {useRef, useEffect} from 'react';

const options = {
    token: 'your-auth-token-here',
    figureId: '209337',
    ttsPer: 'LITE_audiobook_female_1',
    // agentConfig: 若未提供自定义 agentService，此配置必填
    agentConfig: {
        token: 'xxxx',
        robotId: 'xxxx'
    }
};

function App() {
    return (
        <AaaSPilotKitProvider options={options}>
            <Dashboard/>
        </AaaSPilotKitProvider>
    );
}

function Dashboard() {
    const {controller, isReady, isMuted, isRendering} = useAaaSPilotKit();
    const {conversationList} = useConversationList();
    const containerRef = useRef(null)

    useAaaSPilotKitEvents({
        onReady: () => console.log('AI 助手已就绪'),
        onAsrMessage: payload => console.log('ASR:', payload.text)
    });

    useEffect(() => {
        // 确认 controller 和 containerRef 容器都存在，直接挂载初始化
        // ⚠️ 一定确保只挂载一次！！！
        // 注意：React StrictMode 和 React 19 在开发模式下会故意触发 useEffect 两次
        // 这可能导致 mount() 被多次调用，产生 warning 提示
        if (controller && containerRef.current) {
            controller.mount(containerRef.current);
        }
    }, [controller]);

    return (
        <section>
            <div>状态：{isReady ? '就绪' : '初始化中'}</div>
            <div>静音：{isMuted ? '是' : '否'}</div>
            <div>播报状态：{isRendering ? '进行中' : '空闲'}</div>
            <div>对话数：{conversationList.length}</div>
            <button onClick={() => controller?.input('你好')}>发送消息</button>
            <div ref={containerRef} style={{width: 400, height: 700}} />
        </section>
    );
}
```

--------------------------------

### Install AaaS Pilot Kit Vue 3 SDK using npm or yarn

Source: https://aaas-pilot-kit-docs.cloud.baidu.com/docs/vue/intro

Instructions for installing the '@bdky/aaas-pilot-kit-vue3' package using either npm or yarn package managers. Ensure you have Node.js and npm/yarn installed.

```shell
$ npm install @bdky/aaas-pilot-kit-vue3
```

```shell
yarn add @bdky/aaas-pilot-kit-vue3
```

--------------------------------

### Install AaaS Pilot Kit for React

Source: https://aaas-pilot-kit-docs.cloud.baidu.com/docs/intro

Instructions for installing the React-specific package of the AaaS Pilot Kit using npm or yarn. This package includes React Hooks and a Context Provider for state management.

```bash
npm install @bdky/aaas-pilot-kit-react
```

```bash
yarn add @bdky/aaas-pilot-kit-react
```

--------------------------------

### 启动 Node.js 服务

Source: https://aaas-pilot-kit-docs.cloud.baidu.com/docs/deployment/server-deployment/nodejs

通过 npm 脚本启动 Node.js 服务。'npm run dev' 通常用于开发环境（可能包含 nodemon 自动重启），'npm start' 用于生产环境。

```bash
# 开发环境  
npm run dev  

# 生产环境  
npm run start
```

--------------------------------

### Install AaaS Pilot Kit React SDK using npm

Source: https://aaas-pilot-kit-docs.cloud.baidu.com/docs/react/intro

Installs the AaaS Pilot Kit React SDK package using npm. This is the primary method for integrating the SDK into a React project.

```bash
npm install @bdky/aaas-pilot-kit-react
```

--------------------------------

### Install AaaS Pilot Kit for Vue 3

Source: https://aaas-pilot-kit-docs.cloud.baidu.com/docs/intro

Instructions for installing the Vue 3-specific package of the AaaS Pilot Kit using npm or yarn. This package leverages Composition API and dependency injection.

```bash
npm install @bdky/aaas-pilot-kit-vue3
```

```bash
yarn add @bdky/aaas-pilot-kit-vue3
```

--------------------------------

### Install AaaS Pilot Kit React SDK using yarn

Source: https://aaas-pilot-kit-docs.cloud.baidu.com/docs/react/intro

Installs the AaaS Pilot Kit React SDK package using yarn. This is an alternative package manager for integrating the SDK into a React project.

```bash
yarn add @bdky/aaas-pilot-kit-react
```

--------------------------------

### Development Environment: Running with localhost

Source: https://aaas-pilot-kit-docs.cloud.baidu.com/docs/vanilla/faq

This command is used to run the development server, specifically configured to use 'localhost' as the host. This is a workaround for environments that require a secure context (HTTPS) but are running in a development setup.

```bash
npm run dev -- --host localhost

```

--------------------------------

### checkAudioDeviceBeforeStart Configuration

Source: https://aaas-pilot-kit-docs.cloud.baidu.com/docs/vanilla/options

Determines whether to perform a check for audio device availability before starting ASR. This check includes API support, HTTPS, device enumeration, permissions, and stream acquisition.

```APIDOC
## `checkAudioDeviceBeforeStart` (boolean)

### Description
Optionally checks for audio device availability before starting ASR. It performs a four-stage progressive check (API support, HTTPS, device enumeration, permissions, stream acquisition).

### Method
Configuration Parameter

### Endpoint
N/A

### Parameters
#### Request Body
- **checkAudioDeviceBeforeStart** (boolean) - Optional - If `true` (default), the audio device check is performed before ASR starts. If `false`, it is skipped.

### Request Example
```json
{
    "checkAudioDeviceBeforeStart": true
}
```

### Response
N/A (Configuration parameter)

### Notes
- When enabled (default `true`), `checkAudioDevice()` is called automatically.
- Failure of this check does not prevent ASR startup.
- The results can be monitored via the `microphone_available` event.
- Performance Impact: Adds approximately `100-500ms` to the initial startup time (mainly `getUserMedia`). Results are cached for 5 seconds.
- Recommended for scenarios prioritizing user experience and requiring precise error feedback (distinguishing between 'no device', 'permission denied', 'device in use').

### Related Events
- `microphone_available`: Receives the detection results.

### Related Methods
- `checkAudioDevice()`: Manually trigger device detection.
```

--------------------------------

### Vue.js Parent Component Setup with AAAS Pilot Kit

Source: https://aaas-pilot-kit-docs.cloud.baidu.com/docs/vue/faq

Demonstrates how to set up the main App component, providing the AAAS Pilot Kit and mounting a digital employee. It includes importing necessary components and hooks, initializing the provider, and handling the mounting lifecycle.

```vue
<template>
    <div class="app">
        <div ref="digitalHumanRef" class="digital-human"></div>
        <ConversationList />
        <ChatInput />
    </div>
</template>

<script setup lang="ts">
import {ref, onMounted} from 'vue';
import {provideAaaSPilotKit} from '@bdky/aaas-pilot-kit-vue3';
import ConversationList from './ConversationList.vue';
import ChatInput from './ChatInput.vue';

const provider = provideAaaSPilotKit({
    token: 'your-auth-token-here',
    figureId: '209337',
    agentConfig: {
        token: 'your-token',
        robotId: 'your-robot-id'
    }
});

const digitalHumanRef = ref<HTMLDivElement>();

onMounted(() => {
    if (digitalHumanRef.value) {
        provider.controller.value?.mount(digitalHumanRef.value);
    }
});
</script>
```

--------------------------------

### Digital Employee Rendering Start Event

Source: https://aaas-pilot-kit-docs.cloud.baidu.com/docs/vanilla/events

Handles the 'render_start' event, which is triggered when the digital employee begins rendering a piece of text. This is useful for synchronizing subtitles or logging playback events.

```javascript
controller.emitter.on('render_start', (payload) => {
    showSubtitle(payload.text);
    logPlaybackEvent(payload);
});
```

--------------------------------

### Vue 3 Child Component Usage with AAAS Pilot Kit Composables

Source: https://aaas-pilot-kit-docs.cloud.baidu.com/docs/vue/installation

Demonstrates how a child component (PilotComponent.vue) can consume the AAAS Pilot Kit instance using composables like `useAaaSPilotKit` and `useConversationList`. It shows how to access controller functions and state, and interact with the kit.

```vue
<template>
    <div>
        <div>状态：{{ isReady ? '就绪' : '初始化中' }}</div>
        <div>静音：{{ isMuted ? '是' : '否' }}</div>
        <div>渲染：{{ isRendering ? '进行中' : '空闲' }}</div>
        <div>对话数：{{ conversationList.length }}</div>
        <button @click="controller?.input('你好')">
            发送消息
        </button>
    </div>
</template>

<script setup lang="ts">
import {
    useAaaSPilotKit,
    useConversationList
} from '@bdky/aaas-pilot-kit-vue3';

const {controller, isReady, isMuted, isRendering} = useAaaSPilotKit();
const {conversationList} = useConversationList();
</script>

```

--------------------------------

### AaaS Pilot Kit Event Handling Example

Source: https://aaas-pilot-kit-docs.cloud.baidu.com/docs/react/intro

Demonstrates how to use the `useAaaSPilotKitEvents` hook to listen for various events emitted by the AaaS Pilot Kit. This includes events like `onReady`, `onAsrMessage`, `onError`, and `onConversationChange`, allowing for interactive feedback and UI updates.

```javascript
useAaaSPilotKitEvents({
    onReady: () => console.log('就绪'),
    onAsrMessage: (payload) => console.log('ASR结果:', payload.text),
    onError: (error) => console.error('错误:', error),
    onConversationChange: (payload) => updateUI(payload),
    // ...
});
```

--------------------------------

### Basic AaaSPilotKitProvider Usage

Source: https://aaas-pilot-kit-docs.cloud.baidu.com/docs/react/provider

Demonstrates the fundamental setup of the AaaSPilotKitProvider component. It requires an 'options' object containing authentication tokens, figure ID, TTS settings, and agent configuration. The provider wraps child components like Dashboard and ChatPanel, making the AaaS Pilot Kit functionality available to them.

```javascript
import {AaaSPilotKitProvider} from '@bdky/aaas-pilot-kit-react';
import type {IOptions} from '@bdky/aaas-pilot-kit';

const options: IOptions = {
    token: 'your-auth-token-here',
    figureId: '209337',
    ttsPer: 'LITE_audiobook_female_1',
    // agentConfig: 若未提供自定义 agentService，此配置必填
    agentConfig: {
        token: 'your-token',
        robotId: 'your-robot-id'
    }
};

function App() {
    return (
        <AaaSPilotKitProvider options={options}>
            <Dashboard />
            <ChatPanel />
        </AaaSPilotKitProvider>
    );
}
```

--------------------------------

### Integrating with Redux

Source: https://aaas-pilot-kit-docs.cloud.baidu.com/docs/react/installation

Shows how to integrate the AAAS Pilot Kit React SDK with Redux for state management. This example demonstrates dispatching Redux actions like `setAvatarStatus` and `updateConversations` in response to SDK events such as `onReady` and `onConversationChange`. It requires `react-redux` and a Redux store setup.

```typescript
import {useDispatch, useSelector} from 'react-redux';  
import {updateConversations, setAvatarStatus} from './store/avatarSlice';  
  
function Dashboard() {  
    const dispatch = useDispatch();  
    const {isReady} = useAaaSPilotKit();  
      
    useAaaSPilotKitEvents({  
        onReady: () => {  
            dispatch(setAvatarStatus('ready'));  
        },  
        onConversationChange: (payload) => {  
            dispatch(updateConversations(payload));  
        }  
    });  
  
    // ...  
}
```

--------------------------------

### 优化 AaaSPilotKitProvider options 对象的引用

Source: https://aaas-pilot-kit-docs.cloud.baidu.com/docs/react/faq

解决了 `options` 对象引用不稳定导致控制器频繁重建或配置更新不生效的问题。代码展示了错误地在每次渲染时创建新对象，以及使用 `useMemo` 来稳定 `options` 对象的引用，仅在依赖项变化时才重新创建。

```javascript
// ❌ 错误：每次渲染都创建新对象  
function App() {
    return (
        <AaaSPilotKitProvider options={{
            token: 'your-auth-token-here',
            figureId: '209337',
            agentConfig: {token: 'xxx', robotId: 'yyy'}
        }}>
            <Dashboard />
        </AaaSPilotKitProvider>
    );
}

// ✅ 正确：使用 useMemo 稳定引用  
function App() {
    const [robotId, setRobotId] = useState('default-robot');

    const options = useMemo(
        () => ({
            token: 'your-auth-token-here',
            figureId: '209337',
            ttsPer: 'LITE_audiobook_female_1',
            agentConfig: {
                robotId: robotId
            }
        }),
        // 只有依赖变化时才重新创建
        [robotId]
    );

    return (
        <AaaSPilotKitProvider options={options}>
            <Dashboard />
        </AaaSPilotKitProvider>
    );
}

```

--------------------------------

### Automatic Device Detection Before ASR Start

Source: https://aaas-pilot-kit-docs.cloud.baidu.com/docs/vanilla/faq

Demonstrates how to enable and utilize the `checkAudioDeviceBeforeStart` configuration option in the AAAS Pilot Kit. When set to `true`, it automatically checks for audio device availability before starting the ASR. The `microphone_available` event is then used to handle the detection results.

```javascript
const controller = await createAaaSPilotKit({
    checkAudioDeviceBeforeStart: true, // Defaults to true, checks automatically before start
    // ... other configurations
});

// Listen for detection results
controller.emitter.on('microphone_available', result => {
    if (!result.available) {
        // ASR start will be automatically blocked, display error message
        showToast(result.userMessage);
    }
});

```

--------------------------------

### 小程序 WXML 和 JSON 配置

Source: https://aaas-pilot-kit-docs.cloud.baidu.com/docs/deployment/h5-in-miniprogram/miniprogram-setup

此代码展示了如何在小程序中使用 `<web-view>` 组件加载 H5 页面。WXML 文件用于嵌入 WebView，而 JSON 文件用于配置页面的导航栏标题和下拉刷新行为。

```html
<!-- pages/webview/webview.wxml -->
<web-view src="https://h5.example.com"></web-view>
```

```json
{
  "navigationBarTitleText": "H5 页面",
  "enablePullDownRefresh": false
}
```

--------------------------------

### Configure Audio Device Check Before ASR Start

Source: https://aaas-pilot-kit-docs.cloud.baidu.com/docs/vanilla/options

Determines whether to perform a multi-stage check for audio device availability before starting the ASR service. When enabled, it performs checks for API support, HTTPS, device enumeration, permissions, and stream acquisition, providing diagnostic results via the 'microphone_available' event.

```javascript
const controller = await createAaaSPilotKit({
    checkAudioDeviceBeforeStart: true, // 启动前自动检测（推荐）
    // ... 其他配置
});

// 监听检测结果
controller.emitter.on('microphone_available', (result) => {
    if (!result.available) {
        console.error('设备检测失败:', result.userMessage);

        // 根据错误类型提供解决方案
        if (result.error === 'PERMISSION_DENIED') {
          showPermissionGuide();
        }
        else if (result.error === 'HTTPS_REQUIRED') {
          showHTTPSWarning();
        }
    }
});
```

--------------------------------

### 创建目录用于 H5 应用和校验文件

Source: https://aaas-pilot-kit-docs.cloud.baidu.com/docs/deployment/server-deployment/nginx

根据选择的部署方案，使用 `mkdir -p` 命令创建必要的目录。方案一仅需创建 H5 应用的根目录 `/var/www/h5`。方案二则需要同时创建 H5 应用根目录 `/var/www/h5` 和校验文件存放目录 `/var/www/weixin-verify`。

```bash
# 方案一
sudo mkdir -p /var/www/h5

# 方案二
sudo mkdir -p /var/www/h5
sudo mkdir -p /var/www/weixin-verify
```

--------------------------------

### Nginx 或 Node.js 服务器配置示例

Source: https://aaas-pilot-kit-docs.cloud.baidu.com/docs/deployment/h5-in-miniprogram/miniprogram-setup

这些代码片段展示了如何在 Nginx 或 Node.js 服务器上配置以提供校验文件。它们要求服务器能够响应 GET 请求并返回指定路径下的 .txt 文件，确保通过 HTTPS 访问。

```nginx
server {
    listen 443 ssl;
    server_name h5.example.com;

    ssl_certificate /path/to/your/certificate.crt;
    ssl_certificate_key /path/to/your/private.key;

    location / {
        root /path/to/your/h5_files;
        try_files $uri $uri/ =404;
    }
}
```

```javascript
const express = require('express');
const path = require('path');
const app = express();

app.use(express.static(path.join(__dirname, 'public'))); // Assuming files are in a 'public' folder

app.get('*.txt', (req, res) => {
  res.sendFile(path.join(__dirname, 'public', req.path));
});

const PORT = 443;
// You would typically use a reverse proxy like Nginx for SSL termination
// or configure Node.js with HTTPS module for direct HTTPS
app.listen(PORT, () => {
  console.log(`Server running on port ${PORT}`);
});
```

--------------------------------

### Handle 'ready' event for safe interaction

Source: https://aaas-pilot-kit-docs.cloud.baidu.com/docs/vanilla/intro

Ensures that interactions with the AAAS Pilot Kit begin only after the 'ready' event is fired, preventing potential errors.

```javascript
controller.emitter.on('ready', () => {  
    // 安全开始对话  
    controller.input('欢迎消息');  
});  
```

--------------------------------

### 初始化 Node.js 项目和安装依赖

Source: https://aaas-pilot-kit-docs.cloud.baidu.com/docs/deployment/server-deployment/nodejs

使用 npm init -y 初始化 package.json 文件，然后安装 express, helmet, compression 作为生产依赖，nodemon 作为开发依赖，用于创建和管理 Node.js Web 服务器。

```bash
# 创建项目目录 
mkdir h5-miniprogram-server 
cd h5-miniprogram-server 

# 初始化 package.json 
npm init -y 

# 安装依赖 
npm install express helmet compression 
npm install --save-dev nodemon
```

--------------------------------

### minSplitLen Configuration

Source: https://aaas-pilot-kit-docs.cloud.baidu.com/docs/vanilla/options

Defines the minimum number of characters to accumulate before starting speech output, aiming to reduce stuttering by waiting for natural sentence breaks.

```APIDOC
## `minSplitLen` (number)

### Description
Sets the granularity for splitting the first sentence in speech output (by character count).

### Method
Configuration Parameter

### Endpoint
N/A

### Parameters
#### Request Body
- **minSplitLen** (number) - Optional - The minimum number of characters to accumulate before speech begins. Defaults to `5`.

### Request Example
```json
{
    "minSplitLen": 8
}
```

### Response
N/A (Configuration parameter)

### Notes
- A larger value means more characters are buffered before speaking, potentially leading to smoother output by respecting sentence structure.
```

--------------------------------

### React 应用基本使用 AaaS Pilot Kit

Source: https://aaas-pilot-kit-docs.cloud.baidu.com/docs/react/installation

使用 AaaS Pilot Kit React 库在 React 应用中实现 AI 助手功能。通过 `AaaSPilotKitProvider` 提供配置，并使用 hooks 管理状态和交互。核心能力依赖 `@bdky/aaas-pilot-kit`。

```javascript
import {
    AaaSPilotKitProvider,
    useAaaSPilotKit,
    useAaaSPilotKitEvents,
    useConversationList
} from '@bdky/aaas-pilot-kit-react';
import {type IOptions} from '@bdky/aaas-pilot-kit';

const options: IOptions = {
    token: 'your-auth-token-here',
    figureId: '209337',
    ttsPer: 'LITE_audiobook_female_1',
    // agentConfig: 若未提供自定义 agentService，此配置必填
    agentConfig: {
        token: 'xxxx',
        robotId: 'xxxx'
    }
};

function App() {
    return (
        <AaaSPilotKitProvider options={options}>
            <Dashboard />
        </AaaSPilotKitProvider>
    );
}

function Dashboard() {
    const {controller, isReady, isMuted, isRendering} = useAaaSPilotKit();
    const {conversationList} = useConversationList();

    useAaaSPilotKitEvents({
        onReady: () => console.log('AI 助手已就绪'),
        onAsrMessage: payload => console.log('ASR:', payload.text)
    });

    return (
        <section>
            <div>状态：{isReady ? '就绪' : '初始化中'}</div>
            <div>静音：{isMuted ? '是' : '否'}</div>
            <div>渲染：{isRendering ? '进行中' : '空闲'}</div>
            <div>对话数：{conversationList.length}</div>
            <button onClick={() => controller?.input('你好')}>发送消息</button>
        </section>
    );
}
```

--------------------------------

### Get Current Effective Configuration

Source: https://aaas-pilot-kit-docs.cloud.baidu.com/docs/vanilla/api

Retrieves the currently active full configuration, including default values. Useful for debugging, logging, and comparing dynamic configurations.

```typescript
const currentOptions = controller.getOptions();
console.log('当前配置:', currentOptions);

```

--------------------------------

### AaaS Pilot Kit Provider Component Usage

Source: https://aaas-pilot-kit-docs.cloud.baidu.com/docs/react/intro

Illustrates the usage of the `AaaSPilotKitProvider` component, which serves as the entry point for the React SDK. It is responsible for creating and managing the underlying controller instance, providing global state sharing, and handling lifecycle management.

```javascript
<AaaSPilotKitProvider options={options}>
    {/* 你的应用组件 */}
</AaaSPilotKitProvider>
```

--------------------------------

### Fetch conversation list using useConversationList

Source: https://aaas-pilot-kit-docs.cloud.baidu.com/docs/vue/intro

Parent component example demonstrating how to fetch and display a list of conversations using the `useConversationList` composable. It iterates over `conversationList` to render `ConversationItem` components.

```vue
<template>
    <div>
        <ConversationItem
            v-for="conversation in conversationList"
            :key="conversation.id"
            :conversation="conversation"
        />
    </div>
</template>

<script setup lang="ts">
    import { useConversationList } from '@bdky/aaas-pilot-kit-vue3';
    import ConversationItem from './ConversationItem.vue';

    const { conversationList } = useConversationList();
</script>
```

--------------------------------

### Configure AAAS Pilot Kit with Options (JavaScript)

Source: https://aaas-pilot-kit-docs.cloud.baidu.com/docs/vanilla/options

This JavaScript code demonstrates how to initialize the AAAS Pilot Kit with a comprehensive set of configuration options. It covers both mandatory fields like token and figureId, and optional settings for language, TTS, rendering, and more. Ensure you replace placeholder values with your actual credentials and desired configurations.

```javascript
const options: IOptions = {
    // 必填配置
    token: 'your-auth-token-here',
    figureId: '209337',
    ttsPer: 'LITE_audiobook_female_1',
    agentConfig: {
        token: 'your-agent-token',
        robotId: 'your-robot-id'
    },

    // 可选配置
    lang: Language.ENGLISH,  // 语言配置
    ttsSample: 16000,
    rendererMode: 'cloud',
    timeoutSec: 60,
    speechSpeed: 6,
    interruptible: true,
    prologue: '您好,我是您的数字员工,有什么可以帮您?',
    asrVad: 600,
    env: 'production',
    enableDebugMode: false,
    autoChromaKey: true,
    inactivityPrompt: '您长时间未讲话,我先挂断啦~',

    // 热词替换规则
    hotWordReplacementRules: [
        {pattern: /客悦\s*one/gi, replacement: '客悦·ONE'},
        {pattern: /A I/g, replacement: 'AI'}
    ]
};

const controller = createAaaSPilotKit(options);
```

--------------------------------

### Exception Handling during Initialization (JavaScript)

Source: https://aaas-pilot-kit-docs.cloud.baidu.com/docs/vanilla/api

Demonstrates how to handle potential errors during the initialization process of the AAAS Pilot Kit. It uses a try-catch block to gracefully manage exceptions that might occur when mounting the controller or playing initial audio.

```javascript
try {
    await controller.mount(containerElement);
    controller.playFromFullText('初始化成功');
}
catch (e) {
    console.error('初始化失败:', e);
}
```

--------------------------------

### 手动管理 AaaSPilotKit 控制器生命周期

Source: https://aaas-pilot-kit-docs.cloud.baidu.com/docs/react/faq

演示了如何手动创建 (`create`) 和销毁 (`dispose`) 控制器，以处理特殊场景如会话超时。代码展示了正确的手动生命周期管理，以及常见的错误模式，如忘记重新创建或重复创建。

```javascript
function PilotKit() {
    const [isInactive, setIsInactive] = useState(false);
    const {controller, create, dispose} = useAaaSPilotKit();

    const onInactivity = useCallback(
        () => {
            setIsInactive(true);
            // 手动销毁控制器
            dispose();
        },
        [dispose]
    );

    const restart = useCallback(
        () => {
            setIsInactive(false);
            // 手动重新创建控制器
            create(); 
        },
        [create]
    );

    useAaaSPilotKitEvents({
        onInactivity
    });

    if (isInactive) {
        return (
            <div>
                会话已超时
                <button onClick={restart}>
                    重新开始
                </button>
            </div>
        );
    }

    return <AvatarComponent />;
}

// ❌ 错误：dispose 后忘记 create
const handleTimeout = () => {
    dispose();
    // 缺少 create()，导致 controller 为 null
};

// ❌ 错误：重复 create
const handleRestart = () => {
    create(); // 可能导致重复创建
    create(); // 重复调用
};

// ❌ 错误：在 dispose 后直接使用 controller
dispose();
controller?.input('test'); // controller 已为 null

// ✅ 正确：等效逻辑
useEffect(
    () => {
        create();
          
        return dispose;
    },
    []
);

```

--------------------------------

### Integrating AaaSPilotKitProvider with ErrorBoundary

Source: https://aaas-pilot-kit-docs.cloud.baidu.com/docs/react/provider

Demonstrates how to wrap the AaaSPilotKitProvider with React's ErrorBoundary component. This setup allows for graceful error handling during the initialization or operation of the provider, displaying a fallback UI when errors occur.

```javascript
import { ErrorBoundary } from 'react-error-boundary';
import {AaaSPilotKitProvider} from '@bdky/aaas-pilot-kit-react';

function AppWithErrorBoundary() {
    return (
        <ErrorBoundary
            fallback={<div>数字员工初始化失败</div>}
            onError={(error) => console.error('Provider 错误:', error)} 
        >
            <AaaSPilotKitProvider options={options}>
                <Dashboard />
            </AaaSPilotKitProvider>
        </ErrorBoundary>
    );
}
```

--------------------------------

### Managing Multiple AaaSPilotKitProvider Instances

Source: https://aaas-pilot-kit-docs.cloud.baidu.com/docs/react/provider

Shows how to manage multiple independent instances of the AaaSPilotKitProvider within the same application. Each provider instance can be configured with different options, allowing for separate customer service and sales functionalities, for example.

```javascript
function MultiInstanceApp() {
    return (
        <div>
            {/* 实例1 */}
            <AaaSPilotKitProvider options={customerServiceOptions}>
                <CustomerServicePanel />
            </AaaSPilotKitProvider>

            {/* 实例2 */}
            <AaaSPilotKitProvider options={salesOptions}>
                <SalesPanel />
            </AaaSPilotKitProvider>
        </div>
    );
}
```

--------------------------------

### Vue.js Conversation List Component using AAAS Pilot Kit

Source: https://aaas-pilot-kit-docs.cloud.baidu.com/docs/vue/faq

Shows a child component that displays a list of conversations. It utilizes the `useConversationList` hook to get the conversation data and maps over it to render individual `ConversationItem` components.

```vue
<template>
    <div class="conversation-list">
        <ConversationItem
            v-for="conversation in conversationList"
            :key="conversation.id"
            :conversation="conversation"
        />
    </div>
</template>

<script setup lang="ts">
import {useConversationList} from '@bdky/aaas-pilot-kit-vue3';
import ConversationItem from './ConversationItem.vue';

const {conversationList} = useConversationList();
</script>
```

--------------------------------

### React AAAS Pilot Kit Full Integration Example

Source: https://aaas-pilot-kit-docs.cloud.baidu.com/docs/react/installation

This React component demonstrates a complete integration of the AAAS Pilot Kit. It includes setting up the provider with necessary configuration options, rendering UI components for avatar display, chat history, and user controls. It also showcases the usage of hooks like useAaaSPilotKit, useConversationList, and useConversation for managing AI assistant interactions and state.

```javascript
import {useRef, useEffect} from 'react';  
import {  
    AaaSPilotKitProvider,  
    useAaaSPilotKit,  
    useAaaSPilotKitEvents,  
    useConversationList,  
    useConversation  
} from '@bdky/aaas-pilot-kit-react';  
  
// 配置选项  
const options = {  
    token: 'your-auth-token-here',  
    figureId: '209337',  
    ttsPer: 'LITE_audiobook_female_1',  
    // agentConfig: 若未提供自定义 agentService，此配置必填  
    agentConfig: {  
        token: 'your-token',  
        robotId: 'your-robot-id'  
    },  
    // 其他配置...  
};

function App() {  
    return (  
        <AaaSPilotKitProvider options={options}>  
            <div className="app">  
                <AvatarContainer />  
                <ChatPanel />  
                <ControlPanel />  
            </div>  
        </AaaSPilotKitProvider>  
    );
}

// 数字人容器  
function AvatarContainer() {  
    const {controller, isReady} = useAaaSPilotKit();  
    const containerRef = useRef<HTMLDivElement>(null);  

    useEffect(  
        () => {  
            if (controller && containerRef.current) {  
                controller.mount(containerRef.current);  
            }  
        },   
        [isReady, controller]  
    );  
      
    if (!isReady) {  
        return (  
            <div>呼叫中...</div>  
        );
    }

    return (  
        <div   
            ref={containerRef}   
            className="avatar-container"  
            style={{width: '400px', height: '600px'}}  
        />  
    );
}

// 对话面板  
function ChatPanel() {  
    const {conversationList} = useConversationList();  

    return (  
        <div className="chat-panel">  
            <h3>对话记录</h3>  
            {conversationList.map(conversation => (
                <ConversationItem   
                    key={conversation.id}   
                    conversation={conversation}   
                />  
            ))}
        </div>  
    );
}

// 单个对话项  
function ConversationItem({conversation}) {  
    const {conversationContents} = useConversation(conversation);  

    return (  
        <div className="conversation-item">  
            <div className="conversation-type">  
                {conversation.type === 'client' ? '用户' : 'AI助手'}
            </div>  
            <div className="conversation-content">  
                {conversationContents.map(item => (
                    <div key={item.uiId} className={`content-item ${item.completed ? 'completed' : 'typing'}`}>  
                        {item.content}
                    </div>  
                ))}
            </div>  
        </div>  
    );
}

// 控制面板  
function ControlPanel() {  
    const {controller, isReady, isMuted, isRendering} = useAaaSPilotKit();  

    useAaaSPilotKitEvents({  
        onReady: () => console.log('AI 助手已就绪'),  
        onError: (error) => console.error('错误:', error),  
        onAsrMessage: (payload) => console.log('语音识别:', payload.text),  
        onConversationChange: (payload) => console.log('对话更新:', payload)  
    });  

    const handleSendMessage = () => {  
        const message = prompt('请输入消息:');  
        if (message && controller) {  
            controller.input(message);  
        }  
    };

    const handleToggleMute = () => {  
        if (controller) {  
            controller.mute(!isMuted);  
        }  
    };

    const handleInterrupt = () => {  
        if (controller) {  
            controller.interrupt('用户手动打断');  
        }  
    };

    return (  
        <div className="control-panel">  
            <div className="status">  
                <span>状态: {isReady ? '就绪' : '初始化中'}</span>  
                <span>渲染: {isRendering ? '进行中' : '空闲'}</span>  
            </div>  
            <div className="controls">  
                <button   
                    onClick={handleSendMessage}   
                    disabled={!isReady}  
                >  
                    发送消息  
                </button>  
                <button   
                    onClick={handleToggleMute}   
                    disabled={!isReady}  
                >  
                    {isMuted ? '取消静音' : '静音'}
                </button>  
                <button   
                    onClick={handleInterrupt}   
                    disabled={!isReady || !isRendering}  
                >  
                    打断  
                </button>  
            </div>  
        </div>  
    );
}

export default App;  
```

--------------------------------

### Handle ASR Start Event

Source: https://aaas-pilot-kit-docs.cloud.baidu.com/docs/vanilla/events

Listens for the 'asr_start' event, which indicates the beginning of ASR audio capture, typically triggered after VAD detects speech activity. This is useful for showing 'listening' animations or initiating interruption detection. This event has no payload.

```javascript
controller.emitter.on('asr_start', () => {
    showListeningAnimation();
});
```

--------------------------------

### 排查 404 错误：检查文件和 Nginx 配置

Source: https://aaas-pilot-kit-docs.cloud.baidu.com/docs/deployment/server-deployment/nginx

当遇到 404 错误时，首先使用 `ls -la` 命令检查校验文件是否存在于预期的 H5 项目根目录。随后，使用 `sudo nginx -T | grep root` 命令检查 Nginx 配置中 `root` 指令指定的路径是否正确。

```bash
ls -la /var/www/h5/a1b2c3d4e5f6.txt
sudo nginx -T | grep root
```