快速开始

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

最小示例

import {PilotKit, ControlPanel} from '@bdky/aaas-pilot-kit-react-widget';

function App() {
    return (
        <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>
    );
}

这个最小示例会：

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

完整示例

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

import {useState} from 'react';
import {
    PilotKit,
    ConversationList,
    Subtitle,
    ControlPanel,
    RecommendedQuestions,
    StartupScreen,
    LoadingOverlay,
    StatusOverlay,
    Layout,
    FillAdapter,
    useIsMobile,
    type IPilotKitRef
} from '@bdky/aaas-pilot-kit-react-widget';

function App() {
    const [showStartup, setShowStartup] = useState(false);
    const [showLoading, setShowLoading] = useState(true);
    const [showBusy, setShowBusy] = useState(false);
    const [showConversationList, setShowConversationList] = useState(false);

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

    // 忙碌状态
    if (showBusy) {
        return (
            <StatusOverlay
                show
                message="抱歉，我正在忙碌中，请稍后再试"
                buttonText="重新呼入"
                avatar={<img src="/avatar.jpg" alt="" />}
                onButtonClick={() => {
                    setShowBusy(false);
                    setShowLoading(true);
                }}
            />
        );
    }

    return (
        <div 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
                onReady={() => setShowLoading(false)}
                onNeedManualActivation={() => {
                    setShowLoading(false);
                    setShowStartup(true);
                }}
                onBusy={() => setShowBusy(true)}
            >
                <Layout direction="vertical" hCenter>
                    <FillAdapter />

                    {/* 对话列表 */}
                    {showConversationList && (
                        <ConversationList
                            onClose={() => setShowConversationList(false)}
                        />
                    )}

                    {/* 推荐问题 */}
                    <RecommendedQuestions
                        questions={['介绍一下自己', '你能做什么？']}
                        onQuestionClick={q => pilotKitRef.current?.input(q)}
                        style={{marginBottom: 10}}
                    />

                    {/* 字幕（PC 端显示） */}
                    {!isMobile && !showConversationList && (
                        <Subtitle
                            showSpeaker
                            expandable
                            onExpand={() => setShowConversationList(true)}
                            style={{marginBottom: 10}}
                        />
                    )}

                    {/* 控制面板 */}
                    <ControlPanel style={{marginBottom: 30}} />
                </Layout>

                {/* iOS 手动激活页 */}
                <StartupScreen
                    show={showStartup}
                    title="开始对话"
                    buttonText="激活"
                    avatar={<img src="/avatar.jpg" alt="" />}
                    hintText="为获得更好的识别效果，请在安静环境下体验"
                    onReady={() => setShowStartup(false)}
                />

                {/* 加载中 */}
                <LoadingOverlay
                    show={showLoading}
                    description="正在连接..."
                    avatar={<img src="/avatar.jpg" alt="" />}
                />
            </PilotKit>
        </div>
    );
}

代码解析

1. PilotKit 核心容器

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

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

<PilotKit
    ref={pilotKitRef}
    token="xxx"           // 认证 token
    figureId="xxx"        // 数字人形象 ID
    ttsPer="xxx"          // TTS 音色
    agentConfig={{...}}   // Agent 配置
    prologue="..."        // 开场白
    onReady={() => {...}} // 就绪回调
>
    {/* 子组件 */}
</PilotKit>

2. Layout 布局

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

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

3. 覆盖层组件

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

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

4. 响应式适配

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

const isMobile = useIsMobile();

// 移动端不显示字幕，直接显示对话列表
{!isMobile && <Subtitle />}

下一步

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