快速开始

5 分钟搭建一个完整的数字员工交互界面。

最小示例

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

<template>
    <div style="width: 100vw; height: 100vh">
        <PilotKit
            token="your-token"
            figureId="your-figure-id"
            ttsPer="your-tts-per"
            :agentConfig="{robotId: 'your-robot-id'}"
        >
            <ControlPanel />
        </PilotKit>
    </div>
</template>

这个最小示例会：

• 渲染数字人形象
• 显示语音/文字输入控制面板
• 自动处理 ASR、TTS、对话流程

完整示例

下面是一个包含所有常用组件的完整示例：

<script setup lang="ts">
import {ref} from 'vue';
import {
    PilotKit,
    ConversationList,
    Subtitle,
    ControlPanel,
    RecommendedQuestions,
    StartupScreen,
    LoadingOverlay,
    StatusOverlay,
    Layout,
    FillAdapter,
    useIsMobile,
    type IPilotKitRef
} from '@bdky/aaas-pilot-kit-vue3-widget';

const showStartup = ref(false);
const showLoading = ref(true);
const showBusy = ref(false);
const showConversationList = ref(false);

const isMobile = useIsMobile();
const pilotKitRef = ref<IPilotKitRef | null>(null);

function handleQuestionClick(question: string) {
    pilotKitRef.value?.input(question);
}

function handleReconnect() {
    showBusy.value = false;
    showLoading.value = true;
}
</script>

<template>
    <!-- 忙碌状态 -->
    <StatusOverlay
        v-if="showBusy"
        show
        message="抱歉，我正在忙碌中，请稍后再试"
        buttonText="重新呼入"
        @buttonClick="handleReconnect"
    >
        <template #avatar>
            <img src="/avatar.jpg" alt="" />
        </template>
    </StatusOverlay>

    <div v-else style="width: 100vw; height: 100vh">
        <PilotKit
            ref="pilotKitRef"
            token="your-token"
            figureId="your-figure-id"
            ttsPer="your-tts-per"
            :agentConfig="{robotId: 'your-robot-id'}"
            prologue="你好，我是数字员工，有什么可以帮您？"
            interruptible
            @ready="showLoading = false"
            @needManualActivation="showLoading = false; showStartup = true"
            @busy="showBusy = true"
        >
            <Layout direction="vertical" hCenter>
                <FillAdapter />

                <!-- 对话列表 -->
                <ConversationList
                    v-if="showConversationList"
                    @close="showConversationList = false"
                />

                <!-- 推荐问题 -->
                <RecommendedQuestions
                    :questions="['介绍一下自己', '你能做什么？']"
                    :style="{marginBottom: '10px'}"
                    @questionClick="handleQuestionClick"
                />

                <!-- 字幕（PC 端显示） -->
                <Subtitle
                    v-if="!isMobile && !showConversationList"
                    showSpeaker
                    expandable
                    :style="{marginBottom: '10px'}"
                    @expand="showConversationList = true"
                />

                <!-- 控制面板 -->
                <ControlPanel :style="{marginBottom: '30px'}" />
            </Layout>

            <!-- iOS 手动激活页 -->
            <StartupScreen
                :show="showStartup"
                title="开始对话"
                buttonText="激活"
                hintText="为获得更好的识别效果，请在安静环境下体验"
                @ready="showStartup = false"
            >
                <template #avatar>
                    <img src="/avatar.jpg" alt="" />
                </template>
            </StartupScreen>

            <!-- 加载中 -->
            <LoadingOverlay
                :show="showLoading"
                description="正在连接..."
            >
                <template #avatar>
                    <img src="/avatar.jpg" alt="" />
                </template>
            </LoadingOverlay>
        </PilotKit>
    </div>
</template>

代码解析

1. PilotKit 核心容器

PilotKit 是整个应用的核心，它：

• 内置 AaaSPilotKitProvider，无需手动包裹
• 自动挂载数字人渲染
• 提供 ref 访问控制器方法

<script setup lang="ts">
import {ref} from 'vue';
import {PilotKit, type IPilotKitRef} from '@bdky/aaas-pilot-kit-vue3-widget';

const pilotKitRef = ref<IPilotKitRef | null>(null);
</script>

<template>
    <PilotKit
        ref="pilotKitRef"
        token="xxx"
        figureId="xxx"
        ttsPer="xxx"
        :agentConfig="{...}"
        prologue="..."
        @ready="onReady"
    >
        <!-- 子组件 -->
    </PilotKit>
</template>

2. Layout 布局

使用 Layout + FillAdapter 实现灵活布局：

<template>
    <Layout direction="vertical" hCenter>
        <FillAdapter />        <!-- 占据剩余空间 -->
        <ConversationList />   <!-- 对话列表 -->
        <ControlPanel />       <!-- 控制面板 -->
    </Layout>
</template>

3. 覆盖层组件

覆盖层组件用于显示不同状态：

• StartupScreen：iOS iframe 场景需要用户手动激活
• LoadingOverlay：加载中状态
• StatusOverlay：忙碌、超时等状态

4. 响应式适配

使用 useIsMobile() Composable 检测设备类型：

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

const isMobile = useIsMobile();
</script>

<template>
    <!-- 移动端不显示字幕，直接显示对话列表 -->
    <Subtitle v-if="!isMobile" />
</template>

下一步

• PilotKit 组件 - 了解核心容器的完整 Props
• 响应式适配 - 深入了解 PC/移动端适配
• 样式定制 - 自定义组件样式