Skip to main content

介绍

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

特性​

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

快速开始​

安装​

统一使用公网包 @bdky/aaas-pilot-kit-react。

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 = {
    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<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 提示。这是正常的开发模式行为，生产环境下不会出现此问题。

如需避免开发时的 warning，可以在 useEffect 中添加清理函数：

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

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

或者使用 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 = {
    token: 'your-auth-token-here',
    figureId: '209337',
    ttsPer: 'LITE_audiobook_female_1',
    agentService: CustomAgentService // 替代 agentConfig,此时 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
    });
}

完整示例​

查看 安装和快速开始 了解完整的使用示例。

文档导航​

技术支持​