@bdky/aaas-pilot-kit

AaaS Pilot Kit

🤖 开箱即用的数字员工基础套件: 无缝串联 AI Agent、ASR 与数字人渲染服务，全链路可观测、关键点位可追踪， 打造真正流畅自然的数字员工体验。

原生 JavaScript SDK，无任何框架依赖，可在任何前端项目中使用。提供完整的 TypeScript 类型支持。

📚 文档与资源

• 📖 完整文档: aaas-pilot-kit-docs.cloud.baidu.com
• 🔗 API 参考: 详细的 API 文档和配置选项
• 💡 示例代码: 更多使用场景和集成案例
• 📝 更新日志: 查看版本更新和变更记录

📦 安装

# npm
npm install @bdky/aaas-pilot-kit

# yarn
yarn add @bdky/aaas-pilot-kit

# pnpm
pnpm add @bdky/aaas-pilot-kit

🚀 快速开始

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

// 初始化 SDK
const controller = createAaaSPilotKit({
    figureId: '209337',                    // 数字人 ID
    ttsPer: 'LITE_audiobook_female_1',     // 语音音色
    agentConfig: {
        token: 'your-token',               // Agent Token
        robotId: 'your-robot-id'           // 机器人 ID
    }
});

// 监听就绪事件
controller.emitter.on('ready', () => {
    console.log('SDK 已就绪');
    controller.playFromFullText('您好，我是智能助手，有什么可以帮您？');
});

// 监听对话消息
controller.emitter.on('conversation_add', (conversation) => {
    console.log('新消息:', conversation.text);
});

// 挂载到 DOM
await controller.mount(document.getElementById('container'));

📖 核心 API

初始化配置

interface IOptions {
    figureId: string;           // 数字人 ID
    ttsPer: string;            // TTS 音色
    agentConfig?: {
        token?: string;        // Agent Token
        robotId?: string;      // 机器人 ID
    };
    agentService?: typeof CustomAgentService; // 自定义 Agent
    // ... 更多配置选项
}

// ⚠️ 未提供 agentService 时，需配置 agentConfig（token 或 robotId）。
// ✅ 已提供 agentService 时，可省略 agentConfig，由自定义服务接管对话流程。

控制器方法

// 挂载到 DOM
await controller.mount(element: HTMLElement);

// 文本输入（触发对话）
controller.input(text: string);

// 播放文本（TTS）
controller.playFromFullText(text: string);

// 检查是否需要手动激活
controller.checkNeedsManualActivation(): boolean;

// 手动激活（处理浏览器自动播放限制）
controller.activateManually(): void;

// 销毁实例
controller.dispose(): void;

事件监听

// SDK 就绪
controller.emitter.on('ready', () => {});

// 新对话消息
controller.emitter.on('conversation_add', (conversation) => {});

// 错误事件
controller.emitter.on('error', (error) => {});

// ASR 识别结果
controller.emitter.on('asr_result', (result) => {});

💡 最佳实践

1. 等待 Ready 事件

在执行任何操作前，务必等待 ready 事件：

controller.emitter.on('ready', () => {
    // ✅ 在这里安全地开始交互
    controller.input('开始对话');
});

2. 处理浏览器自动播放限制

某些浏览器（尤其是移动端）会限制自动播放，需要手动激活：

let isReady = false;

controller.emitter.on('ready', () => {
    isReady = true;
});

// 在用户交互（如点击）后激活
button.addEventListener('click', () => {
    if (isReady && controller.checkNeedsManualActivation()) {
        controller.activateManually();
    }
});

⚠️ iOS 微信环境: 必须在用户交互后调用 activateManually() 才能正常播放音频和渲染数字人。

3. 错误处理

建议监听错误事件并进行适当处理：

controller.emitter.on('error', (error) => {
    console.error('SDK 错误:', error);
    // 上报错误、显示提示等
});

4. 资源清理

组件销毁时务必清理资源：

// 原生 JS
window.addEventListener('beforeunload', () => {
    controller.dispose();
});

// React
useEffect(() => {
    return () => {
        controller.dispose();
    };
}, []);

// Vue
onUnmount(() => {
    controller.dispose();
});

🔧 TypeScript 支持

SDK 提供完整的 TypeScript 类型定义：

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

// 类型安全的配置
const options: IOptions = {
    figureId: '209337',
    ttsPer: 'LITE_audiobook_female_1',
    agentConfig: {
        token: 'your-token'
    }
};

// 类型化的事件回调
controller.emitter.on('conversation_add', (conversation: IConversation) => {
    console.log(conversation.id, conversation.text, conversation.type);
});

📦 相关包

• React 版本: @bdky/aaas-pilot-kit-react - React Hooks 封装
• Vue3 版本: @bdky/aaas-pilot-kit-vue3 - Vue3 Composition API 封装

❓ 帮助与支持

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

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

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