@bdky/aaas-pilot-kit-react

介绍

专为 React 应用优化的 AaaS Pilot Kit SDK，提供 React Hooks 和组件封装。

特性

• 🪝 React Hooks API - useAaaSPilotKit、useConversation、useConversationList 等
• 🎯 Context Provider - AaaSPilotKitProvider 遵循 React Context 标准范式，管理全局状态，实现跨组件状态共享与依赖注入，无缝集成
• 📦 TypeScript 支持 - 完整的类型定义
• 🔄 状态管理集成 - 支持 Redux、Zustand 等状态管理库
• ⚡ 性能优化 - 内置渲染优化策略，自动隔离外部状态变更，避免非必要重渲染
• 🎨 事件系统 - 简化的事件监听接口

📚 文档与资源

• 📖 完整文档: aaas-pilot-kit-docs.cloud.baidu.com

快速开始

安装

npm

$ npm install @bdky/aaas-pilot-kit-react

yarn

$ yarn add @bdky/aaas-pilot-kit-react

基本使用

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

const options = {
    figureId: '209337',
    ttsPer: 'LITE_audiobook_female_1',
    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<HTMLDivElement>(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>
    );
}

⚠️ React StrictMode 开发模式提醒

在 React StrictMode 和 React 19 的开发模式下，useEffect 会故意执行两次来帮助发现副作用问题。这可能导致 controller.mount() 被多次调用，产生控制台 warning 提示。这是正常的开发模式行为，生产环境下不会出现此问题。

解决方案 1: 在 useEffect 中添加清理函数

useEffect(
    () => {
        if (controller && containerRef.current) {
            controller.mount(containerRef.current);

            return () => {
                // 清理函数，避免重复挂载
                controller.dispose();
            };
        }
    },
    [controller]
);

解决方案 2: 使用 ref 来跟踪挂载状态，确保只挂载一次

const containerRef = useRef<HTMLDivElement>(null);
const mountedRef = useRef(false);

useEffect(
    () => {
        // 使用 ref 标记避免重复挂载
        if (controller && containerRef.current && !mountedRef.current) {
            controller.mount(containerRef.current);
            mountedRef.current = true;
        }
    },
    [controller]
);

核心 API

Provider 组件

AaaSPilotKitProvider 是整个 React SDK 的入口，负责：

• 创建和管理底层控制器实例
• 提供全局状态共享
• 自动处理生命周期

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

核心 Hooks

Hook	功能	返回值
useAaaSPilotKit	获取控制器和状态	{controller, isReady, isMuted, isRendering, create, dispose}
useAaaSPilotKitEvents	绑定事件监听器	void
useConversationList	获取对话列表	{conversationList}
useConversation	处理单个对话	{conversationContents}

事件处理

简化的事件监听接口：

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

高级用法

自定义 AgentService

当需要接入私有 Agent 流式 API 协议时，可以通过继承 BaseAgentService 来创建自定义的 Agent 服务类：

// 传入自定义 AgentService
const options = {
    figureId: '209337',
    agentService: CustomAgentService // 替代 agentConfig
};

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

⚠️ 注意：使用自定义 agentService 时，无需再配置 agentConfig，以避免混用带来的歧义。

详细实现指南：自定义 AgentService 配置

与状态管理集成

// Redux 集成
function ReduxComponent() {
    const dispatch = useDispatch();
    
    useAaaSPilotKitEvents({
        onConversationAdd: (conversation) => 
            dispatch(addConversation(conversation))
    });
}

// Zustand 集成  
function ZustandComponent() {
    const addConversation = useStore(state => state.addConversation);
    
    useAaaSPilotKitEvents({
        onConversationAdd: addConversation
    });
}

❓ 帮助与支持

遇到问题或有建议？欢迎通过以下方式联系我们：

• 📧 发送邮件至维护团队
• 📖 查看常见问题文档

Made with ❤️ by 百度智能云客悦 Ky-FE Team