Provider Context

React Context Provider 负责创建/销毁底层 createAaaSPilotKit 控制器，并将状态下发到子组件。

AaaSPilotKitProvider

基本用法

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>
    );
}

Props 接口

interface IAaaSPilotKitProviderProps<AS extends BaseAgentService = BaseAgentService> {
    children: React.ReactNode;
    options: IOptions<AS>;
}

参数说明：

• children: React 子组件
• options: AaaS Pilot Kit 配置选项，详见 配置选项文档

语言配置

通过 lang 参数可以配置 ASR 识别和 TTS 合成的语言:

import {AaaSPilotKitProvider, Language} from '@bdky/aaas-pilot-kit-react';

function App() {
    return (
        <AaaSPilotKitProvider
            options={{
                token: 'your-auth-token-here',
                figureId: '209337',
                ttsPer: 'LITE_audiobook_female_1',
                lang: Language.ENGLISH,  // 使用 Language 常量
                // 或 lang: 'en'           // 直接使用字符串
                agentConfig: {
                    token: 'your-token',
                    robotId: 'your-robot-id'
                }
            }}
        >
            <Dashboard />
        </AaaSPilotKitProvider>
    );
}

支持的语言包括: 中文(zh)、英语(en)、日语(ja)、西班牙语(es)、俄语(ru)、韩语(ko)、越南语(vi)、德语(de)、印尼语(id)、泰语(th)。

详细的语言配置说明请参考 配置选项文档。

生命周期管理

Provider 自动管理控制器的生命周期：

function App() {
    const [config, setConfig] = useState(initialOptions);

    return (
        <AaaSPilotKitProvider options={config}>
            {/* 当 options 变更时，Provider 会自动重新创建控制器 */}
            <button onClick={() => setConfig(newOptions)}>
                切换配置
            </button>
            <Dashboard />
        </AaaSPilotKitProvider>
    );
}

自动处理：

1. 首次渲染: 自动创建控制器实例
2. 配置变更: options 变化时自动重新创建控制器
3. 组件卸载: 自动执行 controller.dispose() 释放资源
4. 事件监听: 同步监听核心事件，维护内部状态

内部状态管理

Provider 内部维护以下状态并自动同步：

状态	类型	说明	对应事件
isReady	boolean	控制器是否就绪	ready
isMuted	boolean	是否静音	mute
isRendering	boolean	是否正在播报	is_rendering_change

这些状态通过 useAaaSPilotKit hook 获取：

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

    return (
        <div>
            <div>就绪状态: {isReady ? '已就绪' : '初始化中'}</div>
            <div>静音状态: {isMuted ? '静音' : '正常'}</div>
            <div>播报状态: {isRendering ? '进行中' : '空闲'}</div>
        </div>
    );
}

Context 接口

interface IAaaSPilotKitProvider<AS extends BaseAgentService = BaseAgentService> {
    controller: ReturnType<typeof createAaaSPilotKit<AS>> | null;
    isReady: boolean;
    isMuted: boolean;
    isRendering: boolean;
    create: () => void;
    dispose: () => void;
}

方法说明：

• create(): 手动创建控制器实例
• dispose(): 手动销毁控制器实例

注意

直接调用 create/dispose 会跳过正常的生命周期管理，仅在特殊场景下使用。

高级用法

多实例管理

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

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

ErrorBoundary

import {ErrorBoundary} from 'react-error-boundary';

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

性能优化

配置稳定化

function OptimizedProvider() {
    // ✅ 使用 useMemo 稳定化配置对象
    const options = useMemo(() => ({
        token: process.env.REACT_APP_AUTH_TOKEN,
        figureId: '209337',
        ttsPer: 'LITE_audiobook_female_1',
        // agentConfig: 若未提供自定义 agentService，此配置必填
        agentConfig: {
            token: process.env.REACT_APP_AGENT_TOKEN,
            robotId: process.env.REACT_APP_ROBOT_ID
        }
    }), []);

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

// ❌ 避免每次渲染都创建新对象
function BadProvider() {
    return (
        <AaaSPilotKitProvider options={{
            token: 'your-auth-token-here',
            figureId: '209337', // 每次渲染都是新对象！
            // ...
        }}>
            <Dashboard />
        </AaaSPilotKitProvider>
    );
}

延迟初始化

function LazyProvider({ children }) {
    const [shouldInit, setShouldInit] = useState(false);

    if (!shouldInit) {
        return (
            <div>
                <button onClick={() => setShouldInit(true)}>
                    启动数字员工
                </button>
            </div>
        );
    }

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

调试技巧

开发模式增强（日志喷涌而来）

function EnhancedProvider({ children, options }) {
    const enhancedOptions = useMemo(() => ({
        ...options,
        env: process.env.NODE_ENV,
        enableDebugMode: process.env.NODE_ENV === 'development'
    }), [options]);

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