介绍

原生 JavaScript SDK，无任何框架依赖，可在任何前端框架中使用。

安装

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

npm

$ npm install @bdky/aaas-pilot-kit

yarn

$ yarn add @bdky/aaas-pilot-kit

快速开始

import {createAaaSPilotKit} from '@bdky/aaas-pilot-kit';

// 使用您的配置初始化
const controller = createAaaSPilotKit({
    token: 'your-auth-token-here',
    figureId: '209337',
    ttsPer: 'LITE_audiobook_female_1',
    // agentConfig: 若未提供自定义 agentService,此配置必填
    agentConfig: {
        // 客悦客服Agent token
        token: 'xxxx',
        // 客悦外呼Agent robotId
        robotId: 'xxxx'
    }
});

// 监听事件
controller.emitter.on('ready', () => {
    // 使用非流式 API 播报开场白
    controller.playFromFullText('您好，今天我可以为您做什么？');
});

controller.emitter.on('conversation_add', (conversation) => {
    console.log('新对话内容:', conversation.text);
});

// 挂载
await controller.mount(containerElement);

最佳实践

1. 等待 Ready 事件

在开始交互之前始终等待 ready 事件：

controller.emitter.on('ready', () => {
    // 安全开始对话
    controller.input('欢迎消息');
});

2. 处理手动激活

检查并处理浏览器自动播放限制

• ⚠️ 目前已知 iOS 微信内需要手动调用 activateManually()，确保能正常选渲染人像和声音播报

let activity = false;
controller.emitter.on('ready', () => {
    activity = true;
});

// 在用户点击处理程序中
activationButton.addEventListener('click', () => {
    if (activity && controller.checkNeedsManualActivation()) {
        controller.activateManually();
    }
});

3. 实现正确的错误处理

controller.emitter.on('error', (error) => {
    // 始终记录错误
    logger.error('AaaS Pilot Kit 错误', error);
});

4. 资源清理

组件卸载时始终销毁控制器：

// 页面卸载时清理
window.addEventListener('beforeunload', () => {
    controller.dispose();
});

// 或在适当的生命周期中（以 React 技术栈为例）
useEffect(
    () => {
        const cleanup = () => {
            controller.dispose();
        };
        return cleanup;
    },
    []
);

TypeScript 支持

包含全面的 TypeScript 定义：

import type { 
    IAaaSPilotKitController, 
    IAaaSPilotKitEmitter, 
    IOptions 
} from '@bdky/aaas-pilot-kit';

// 完整的类型安全
const options: IOptions = {
    token: 'your-auth-token-here',
    figureId: '209337',
    ttsPer: 'LITE_audiobook_female_1',
    // ... 其他选项具有自动完成
};

// 类型化的事件监听器
controller.emitter.on('conversation_add', conversation => {
    // conversation 是完全类型化的
    console.log(conversation.id, conversation.text, conversation.type);
});

下一步

• 查看 配置选项 了解所有可用配置
• 阅读 API 参考 了解控制器方法
• 学习 事件系统 实现交互功能
• 参考 常见问题 解决使用问题